Creating a Provisioning Request

This guide describes part of the procedure for push-provisioning a tokenized card to a mobile wallet, using the Create Provisioning Request endpoint. Prior to performing this procedure, you must work with Galileo, the mobile wallet providers, and your card network to set up your program to use mobile wallets, as described in the Setup for Mobile Wallets guide.

Prior to calling Create Provisioning Request

Before initiating the push-provisioning process, the card to provision must already exist in the Galileo system. If the card does not exist, call one of these endpoints to create the account.

  • Create Account — Use when the customer does not have an account on the Galileo system, or a customer wants to have a secondary account to another customer's primary account. See the Creating an Account guide for details.
  • Add Account — Use when the customer already has an account on the Galileo system and wants to add a secondary card. See the Adding an Account guide for details.

A provisioning request is successful only when the following fields in the customer record are populated. (For existing accounts call Get Account Overview to review the information):

  • First name
  • Last name
  • Address 1
  • Address 2 (if available)
  • City
  • State
  • Zip or postal code
  • Country code
  • Email
  • Mobile phone number

Use Update Account to populate or modify the fields as necessary.

When a customer requests a tokenized card for a mobile wallet through your mobile app or web site, you send a request to the wallet provider to get keys, certificates, and other data to include in the Create Provisioning Request call that you send to Galileo. (Consult the documentation from the mobile wallet provider for instructions.)

With the data in Galileo's response, you send a tokenization request to the mobile wallet provider through its SDK. As shown in Push-provisioning workflow in the Setup for Mobile Wallets guide, the wallet provider, the card network, and Galileo perform the final steps to complete the provisioning.

Result of calling Create Provisioning Request

When Create Provisioning Request has run successfully, you obtain encrypted information to send to the mobile wallet provider.

Parameters

Which parameters to populate depends on the wallet provider and the information that the provider sent to you.

Parameters for Apple Pay

Use these parameters for a provisioning request to Apple Pay. See the Create Provisioning Request reference for details and this recipe for an example:

ParameterUsage
accountNoUse the CAD (card_id) of the card to provision
walletProvider1
cert1The leaf certificate provided by Apple Pay that is signed using cert2. See Certificate formatting.
cert2The subordinate certificate provided by Apple Pay that is signed using the Apple Pay’s Certificate Authority. See Certificate formatting.
nonce8-character value provided by Apple Pay.
nonceSignatureValue provided by Apple Pay.

Parameters for Google Pay

Use these parameters for a provisioning request to Google Pay. See the Create Provisioning Request reference for details and either of these two recipes for an example:

ParameterUsage
accountNoUse the CAD (card_id) of the card to provision
walletProvider2
clientWalletAccountIDVisa only. Provided by Google Pay.
clientDeviceIDVisa only. Provided by Google Pay.

Parameters for Samsung Pay

Use these parameters for a provisioning request to Samsung Pay. See the Create Provisioning Request reference for details and either of these two recipes for an example:

ParameterUsage
accountNoUse the CAD (card_id) of the card to provision
walletProvider3
cert1This parameter is no longer required for Samsung Pay implementations. If you have a legacy setup that requires this field, set the SFISP parameter.
cert2This parameter is no longer required for Samsung Pay implementations. If you have a legacy setup that requires this field, set the SFISP parameter.
clientWalletAccountIDVisa only. Provided by Samsung Pay.
clientDeviceIDVisa only. Provided by Samsung Pay.

Create Provisioning Request workflow

Consult this explanation for the Create Provisioning Request workflow. The actual sequence of events in the Galileo system may vary.

  1. You populate Create Provisioning Request with data from the wallet provider and send it to Galileo.
  2. Galileo verifies that walletProvider is valid, and if it is not, returns status: 548-10.
  3. Galileo verifies that you have the wallet provider set up properly, and if you do not, returns status: 548-09.
  4. Galileo verifies that the card belongs to a card network that Galileo supports for mobile wallets, and if it does not, returns status: 548-06.
  5. For Apple Pay, Galileo validates the certificates. If validation fails, Galileo returns status: 548-01.
  6. Galileo verifies that the product is eligible for tokenization, and if it is not, returns status: 548-02.
  7. Galileo verifies that the card status permits tokenization, as specified in TOKCS (default: N). If the card is in the wrong status, Galileo returns status: 548-03.
  8. For Visa, Galileo verifies that all additional parameters are valid, and if they are not, returns status: 548-11.
  9. Galileo generates and encrypts the payload for the response.
    • If Apple Pay encryption fails, Galileo returns status: 548-07.
    • If Galileo was unable to get provisioning data from its databases, Galileo returns status: 548-08.
  10. Galileo sends the response.

Certificate formatting

The values for cert1 and cert2 must be the hexlified (case-insensitive) binary data of the certificate.

Example using a PEM-encoded certificate

A certificate in PEM format should follow the typical standards for PEM: the tags -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- should be present and the Base64-encoded value should have lines of length 64.

Start with the original certificate with its standard PEM formatting:

-----BEGIN CERTIFICATE-----
MIICizCCAjGgAwIBAgIJAKsEmM1ALepFMAoGCCqGSM49BAMCMGUxCzAJBgNVBAYT
AlVTMQ0wCwYDVQQIEwRVdGFoMRcwFQYDVQQHEw5TYWx0IExha2UgQ2l0eTEbMBkG
A1UEChMSR2FsaWxlbyBQcm9jZXNzaW5nMREwDwYDVQQDEwhqaGVuc2xleTAgFw0x
...
-----END CERTIFICATE-----

Perform the hexlify operation on the entire certificate to get the hex string:

2d2d2d2d2d424547494e2043455254494649434154452d2d2d2d2d0a4d494943697a4343416a4767417749424167494a414b73456d4d31...

Example using DER-encoded certificate

A certificate with DER encoding may look like the example below, or it may be a string of special characters:

0��0�1�
______________________________________________________________________________
 � ��@-�E0
______________________________________________________________________________
*�H�=
______________________________________________________________________________
______________________________________________________________________________
0e1

0      	0
______________________________________________________________________________
U 
______________________________________________________________________________
US1
______________________________________________________________________________
U 
______________________________________________________________________________
Utah10 
______________________________________________________________________________
U 
______________________________________________________________________________
Salt Lake 

Perform the hexlify operation on the entire certificate to get the hex string:
3082028b30820231a003020102020900ab0498cd402dea45300a06082a8648ce3d0403023065310b3009060355040613025553310d300b0...

Event messages

The Create Provisioning Request endpoint does not directly trigger any events. For event messages that are triggered by other aspects of the wallet-provisioning process, see Events API messages in the Setup for Mobile Wallets guide.

Sample endpoint responses

The responses to this endpoint vary according to the wallet provider. Consult the Create Provisioning Request endpoint description as well as these recipes for examples:

The wallet-specific fields that are returned in addition to the response are in the provisioning_request_data object.

Apple Pay

FieldDescriptionExample
encryptedPassDataAn encrypted JSON file containing the sensitive information needed to add a card to a wallet.F92C1D45EFF127F92C1D4...2C1D45EFF127==
ephemeralPublicKeyA generated key that is combined with a private key.0499a6f42e83ea4f150a78780ffb562c9c....
activationDataThe request's activation data. This must be Base64-encoded.8BF291C91F3ED4EF92C1D45EFF127C1F9ABC12348D

PPALE is a product parameter that is set for older programs. When PPALE is set to Y, the three fields in this table could be either Base64-encoded or hex-encoded. When PPALE is not set to Y, then each of the three fields will always be Base64-encoded.

Google Pay

FieldDescriptionExample
opaquePaymentCardA Base64-encoded or Base64url-encoded opaque string.c2FtcGxlIHRleHQK

Samsung Pay

FieldDescriptionExample
payloadA Base64-encoded or Base64url-encoded opaque string.c2FtcGxlIHRleHQK

Next steps

With the data from the provisioning_request_data object, create a provisioning request that you send to the wallet provider via its SDK.

Status codes

Consult the Create Provisioning Request endpoint for status codes and next steps.