Push Provisioning for Issuers

Overview

Push Provisioning allows an issuer’s app to add a card directly to a digital wallet (Apple Pay / Google Pay / Samsung Pay). Since this process involves the issuer's server-side handling of PCI data, they can leverage the VGS Push Provisioning Encryption Service to complete this integration while remaining completely out of scope. This implementation guide is specific to Apple and Google Pay for Mastercard cards.

Note: A significant portion of the issuer client-side integration involves working with Apple Passkit (Wallet API) and Google Push Provisioning API.

  • For Apple, client-side implementation resources can be sourced from the official [ Apple Passkit Documentation ](https://developer.apple.com/documentation/passkit) or guides provided by Apple.

  • For Google, they can be sourced from the [ Google Push Provisioning Documentation ](https://developer.apple.com/documentation/passkit) or guides provided by Google.

Apple Pay - Implementation Diagram

The following diagram illustrates how the integration will work between an issuer, VGS, Apple’s Server, and the Networks:

Push Provisioning for Apple

Apple Pay - Implementation Steps

Note: Before starting, the client-side must check the following:

  • Whether the selected mobile device is eligible for In-App Provisioning

  • Whether the selected mobile device has existing payment cards

1. User clicks “Add to Apple Wallet” button The user initiates the In-App Provisioning process by selecting the ‘Add to Apple Wallet’ button in the app. The client-side will need to do the following:

  • Present the ‘Add to Apple Wallet’ button

  • Initiate the In-App Provisioning View Controller

2. Client-side requests Provisioning Certificates from Apple The issuer’s client-side (Apple Wallet) requests Apple’s Public Certificates, which VGS will use to encrypt the payment data payload

3. Client-side requests Provisioning Certificates from Apple The issuer’s client-side (Apple Wallet) requests Apple’s Public Certificates, which VGS will use to encrypt the payment data payload

3. Apple Server returns requested data to the client-side Apple’s Public Certificates and nonce are provided to the Apple Wallet.

4. Mobile Device signs the nonce The Secure Element on the end user’s device will sign the nonce and return nonceSignature to Apple Wallet

5. The client-side sends data to VGS The client-side submits the required data to the VGS Reverse Proxy endpoint (whitelabeled as issuer’s API endpoint). See more on this process in the "VGS Data Encryption" and "VGS Setup Instructions" below

6. VGS passes the data through to the issuer’s Server VGS will accept the data above and pass it through unchanged to the issuer’s server-side.

7. Issuer’s Server Authenticates Request Once the data is received by issuer’s server, it will need to do the following: Authenticate the request from the client-side Swap out the issuer Card ID (or another card reference given to issuer’s Customer) with the VGS Alias representing the underlying PAN.

8. VGS encrypts the data VGS will accept the data above and generate the encryptedPassData, ephemeralPublicKey, and activationData.

9. Client submits encrypted data to Apple for further Verification Issuer's customer client-side passes the encryptedPassData, ephemeralPublicKey, and activationData to Apple’s Servers, where additional validation checks are performed.

10. Apple Servers pass encrypted data to the Networks Apple Servers pass the encryptedPassData and ephemeralPublicKey to the Networks.

11. Networks complete the verification process There are a series of additional events required to complete the verification (not reflected on the diagram):

  • Networks send T&C (Terms and Conditions) to the client-side to be accepted by the user

  • The user agrees to the T&Cs, and the client Side sends the activationData to the Networks

  • Networks validate the activationData with issuer’s customer directly

  • Networks send successful activation status to Apple Wallet

12. The client-side returns result to the end-user The end user sees that the card has been successfully activated.

Apple Pay - VGS Data Encryption

The issuer’s client-side will need to provide the following to Apple for them to complete the provisioning process (step #8 on the implementation diagram):

  • encryptedPassData

  • ephemeralPublicKey

  • activationData

Since generating these values involves handling sensitive PCI data, the issuer will use VGS to facilitate this process. Steps #4-8 on the implementation diagram are expanded on below:

  • The issuer's client-side will submit the payload to the VGS Reverse Proxy. This payload will contain:

    • Apple Pay certificates

    • nonce

    • nonceSignature

    • activationData

    • issuer’s Card ID (or another card reference object)

  • VGS Reverse Proxy will forward this data unchanged to the issuer's Server Side for authentication. This step is needed so that the VGS Reverse Proxy is able to encrypt the data on the response from the issuer.

  • issuer’s server-side will append VGS Alias to this payload on the response phase

  • VGS Reverse Proxy will accept this data and encrypt it.

  • VGS will forward this result back to the client-side for subsequent submission to Apple’s Servers.

Apple Provisioning with Mastercard

To test Apple in-App Provisioning with VGS for Mastercard, construct your cURL using the sample request below:

curl -v --location 'https://{VAULT_ID}.sandbox.verygoodproxy.com/{PATH}' \
--header 'Content-Type: application/json' \
--data '{
    "payload": {
        "expiration": "01/22",
        "name": "John Appleseed",
        "nonce": "XXXXX",
        "nonceSignature": "XXXXX",
        "primaryAccountNumber": "{YOUR_VGS_ALIAS}",
        "productType": "DEFAULT_MASTERCARD",
        "version": "3"
    },
    "activationData": {
  "tokenUniqueReferenceIncluded":"XXXXX",
  "signatureAlgorithm":"XXXXXXXX",
  "signature":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "expirationDateIncluded":"XXXX",
  "version":"3"

    },
    "signingCertificate": "S0tLSWc1lYUnBiMjV6SUVOQklDMGdSekl",
    "applePublicKey": "alkyV8KRlVPaZkSVElGSUNBVEUtLS0tLQ=="
}'

Contents of the request:

  1. Target URL – this URL represents your VGS Inbound Route, e.g. https://<VAULT_ID>.sandbox.verygoodproxy.com/<PATH>

  2. Payload – the payload structure above is specific to Mastercard:

    • Nonce – this data will be provided by Apple’s Server

    • nonceSignature – this data will be signed by the Secure Element of the mobile device

    • PrimaryAccountNumber – this field will need to contain your VGS Alias representing an underlying PAN data

  3. Activation Data – this part of the request is specific to Mastercard. The issuer will need to check the format and contents of this data with Mastercard directly.

  4. signingCertificate – will be provided by Apple’s Server

  5. applePublicKey – will be provided by Apple’s Server

Google Pay - Implementation Diagram

Push Provisioning for Google

Google Pay - Implementation Steps

1. User clicks “Add to G-Pay” button The user initiates the In-App Provisioning process by selecting the ‘Add to G-Pay’ button in the app.

2. Client-side calls the server to request OPC

  • The client-side calls the issuer's server through VGS Reverse Proxy to request an OPC (Opaque Payment Card). This data is required to perform validations with the Networks in order to complete the Push Provisioning process.

  • The Issuer will submit a request to the VGS Reverse Proxy URL, which will be then forwarded to the issuer's server-side. The Issuer will also need to include issuer’s Card Id in the request so it could be tied to the VGS Alias. At this stage, VGS will simply pass the data through.

3. Issuer returns response to the client-side through VGS

  • The issuer’s server-side will authenticate the client request

  • The issuer will append the VGS alias in response. This alias will be used by VGS to generate an OPC.

  • The data will go through the VGS Reverse Proxy on the response and VGS will perform the necessary encryption.

4. Client-side passes the data to Google The Client-side will pass the data to Google using Google Push Provisioning SDK. This will be accomplished by passing OPC, TSP, network, UserAddress as arguments within the PushTokenize method.

5. Google communicates with the Networks to complete provisioning Once Google receives the data, it will pass it on to the Networks to initiate the Network validations required.

6. Networks complete the verification process There are a series of additional events required to complete the verification (not reflected on the diagram):

  • Networks send T&C (Terms and Conditions) to the client-side to be accepted by the user

  • The user agrees to the T&Cs, and the client Side sends the activationData to the Networks

  • Networks send successful activation status to Google Wallet

7. The client-side returns result to the end-user The end user sees that the card has been successfully activated.

Google Pay - VGS Data Encryption

The issuer will need to generate an OPC (Opaque Payment Card) in order to provision a card with Google Pay. Similarly to Apple Pay, generating these values involves handling sensitive PCI data, so the issuer will use VGS to facilitate this process. Steps #2-3 on the implementation diagram are expanded on below:

  • The issuer's customer’s client-side will submit the payload to the VGS Reverse Proxy. This payload will contain:

  • protocolHeader

  • validationContext

  • paymentContext

  • The issuer’s Card ID (or another card reference object)

  • VGS Reverse Proxy will forward this data unchanged to the issuer's Server Side for authentication. This step is needed so that the VGS Reverse Proxy is able to encrypt the data on the response from the issuer.

  • The issuer’s server-side will append VGS Alias to this payload on the response phase

  • VGS Reverse Proxy will accept this data and encrypt it.

  • VGS will forward this result back to the client-side for subsequent submission to Google’s Servers

It's important to note that OPC generation involves the Issuer’s Private Key and Google certificates. The following data will may need to be passed to the VGS in addition to the payload above:

  • signingCertificate (Issuer’s private key which they can get from Mastercard)

  • googlePublicKey

  • googlePublicKeyFingerprint

Google Pay Provisioning with Mastercard

To test Google Pay in-App Provisioning with VGS for Mastercard, construct your cURL using the sample request below:

curl -v --location 'https://{VAULT_ID}.sandbox.verygoodproxy.com/{PATH}' \
  --header 'Content-Type: application/json' \
  --data '{
    "googleOpcJson": {
      "protocolHeader": {
        "version": 1
      },
      "validationContext": {
        "serverSessionId": "GoogleSession123"
      },
      "paymentCard": {
        "accountNumber": "{YOUR_VGS_ALIAS}",
        "expiryMonth": "12",
        "expiryYear": "29"
      }
    "signingCertificate": "S0tLSWc1lYUnBiMjV6SUVOQklDMGdSekl",
    "googlePublicKey": "alkyV8KRlVPaZkSVElGSUNBVEUtLS0tLQ==",
    "googlePublicKeyFingerprint": "EUtLS0tLQal=="
    }
  }'

VGS Setup Instructions

To complete each Push Provisioning integration with VGS, issuer will need to set up the following:

  1. Create an Inbound route in the VGS Dashboard and enable the “Push Provisioning” Add-on (or coordinate with the VGS Solutions Engineering team to set this up on issuer’s behalf).

  2. Set the issuer's upstream host to its target server-side endpoint.

  3. Provide the URL associated with the VGS inbound route (Vault URL) to the issuer’s customer’s client-side:

    • a. By default, this URL would look as shown below:

      • https://<VAULT_ID>.sandbox.verygoodproxy.com/<PATH>

    • b. Issuer can use CNAME to mask the VGS Inbound URL to a custom URL:

      • https://api.issuer-push-provisioning.com/<PATHINFO>

  4. In case of Google Pay, Issuer’s private certificate will need to be uploaded as a token to the VGS inbound route.

Once these steps are completed, VGS is ready to accept the data from issuer’s customer’s client-side

See relevant documentation and guides on setting up VGS:

PreviousIntegrating with Google Pay™️NextTechnology

Last updated