Push provisioning

Push provisioning allows cardholders to add their Card to a Digital Wallet at the tap of a button instead of having to manually type in the Card details.

Apple Pay

In-app push provisioning

Prerequisites

Enabling push provisioning to Apple Pay wallets in your iOS application requires an Apple Pay Entitlement to be issued by Apple for your application. Please reach out to support@increase.com and we will guide you through the process and any other setup needed.

Push provisioning flow

• Add an AddPassToWalletButton to a view. Please refer to Apple’s documentation on guidelines for proper presentation of the button.

• When the button is tapped, present a PKAddPaymentPassViewController to the user, configured for the card:

let requestConfiguration = PKAddPaymentPassRequestConfiguration.init(
  encryptionScheme: PKEncryptionScheme.ECC_V2,
)!

requestConfiguration.paymentNetwork = .visa
requestConfiguration.cardholderName = "Ian Crease"
requestConfiguration.primaryAccountSuffix = "1288"
requestConfiguration.localizedDescription = "Crease Card"

let controller = PKAddPaymentPassViewController(
  requestConfiguration: requestConfiguration,
  delegate: delegate,
)

• Implement the PKAddPaymentPassViewControllerDelegate protocol. In the generateRequestWithCertificateChain method, pass the certificates, nonce, and nonce signature to your backend as Base64-encoded data.

• On your backend, send the certificates, nonce, and nonce signature to POST /cards/:card_id/push_provision with the apple_pay_in_app channel, and return Increase’s response to your application:

curl -X "POST" \
  --url "${INCREASE_URL}/cards/card_oubs0hwk5rn6knuecxg2/push_provision" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "channel": "apple_pay_in_app",
    "cardholder_name": "Ian Crease",
    "apple_pay_in_app": {
      "certificates": [
        {
          "certificate": "..."
        },
        {
          "certificate": "..."
        }
      ],
      "nonce": "...",
      "nonce_signature": "..."
    }
  }'

{
  "channel": "apple_pay_in_app",
  "apple_pay_in_app": {
    "activation_data": "...",
    "encrypted_pass_data": "...",
    "encryption_version": "EV_ECC_v2",
    "ephemeral_public_key": "..."
  }
}

• Back in your application, Base64-decode the values in Increase’s response to construct a PKAddPaymentPassRequest:

let addPaymentPassRequest = PKAddPaymentPassRequest()
addPaymentPassRequest.activationData = Data(base64Encoded: backendResponse.apple_pay_in_app.activation_data)
addPaymentPassRequest.ephemeralPublicKey = Data(base64Encoded: backendResponse.apple_pay_in_app.ephemeral_public_key)
addPaymentPassRequest.encryptedPassData = Data(base64Encoded: backendResponse.apple_pay_in_app.encrypted_pass_data)
return addPaymentPassRequest

• Wait for the didFinishAdding delegate method to be called to determine the outcome of the push provisioning flow. As the flow progresses, a Digital Wallet Token will be created and receive updates.

Google Pay

Increase supports Google’s Unified Push Provisioning flow, which works the same way on the web and in Android applications.

Push provisioning flow

Increase returns two opaque payment cards. Pass them to Google’s SDK without modifying them:

• token_service_provider_opaque_payment_card adds the Card to Google Wallet on the cardholder’s phone or wearable.
• google_opaque_payment_card saves the Card to the cardholder’s Google account.

Google Pay web push provisioning

• Load Google’s web push provisioning library and add an Add to Google Wallet button to your page, following Google’s brand guidelines.

• When the button is clicked, call openAppWindow. In onSessionCreated, send the session details to your backend and pass the response to pushPaymentCredentials:

window.googlepay.openAppWindow({
  integratorId: YOUR_INTEGRATOR_ID,
  clientSessionId: YOUR_CLIENT_SESSION_ID,
  tokenSetting: 1,
  cardSetting: 1,
  onSessionCreated: async (session) => {
    const response = await sendSessionToBackend({
      server_session_identifier: session.serverSessionId,
      public_device_identifier: session.publicDeviceId,
      public_wallet_identifier: session.publicWalletId,
    });
    const {
      token_service_provider_opaque_payment_card,
      google_opaque_payment_card,
    } = response.google_pay_web;

    const paymentCredentials = {
      displayName: 'Crease Card',
      lastDigits: '1288',
      userAddress: {
        name: 'Ian Crease',
        addressLines: ['33 Liberty Street'],
        localityName: 'New York',
        administrativeAreaName: 'NY',
        postalCodeNumber: '10045',
        countryCode: 'US',
        phone: '+12125550100',
      },
    };
    if (session.tokenSetting === 1) {
      paymentCredentials.tokenCredentials = {
        cardNetwork: 'CARD_NETWORK_VISA',
        tokenServiceProvider: 'TOKEN_PROVIDER_VISA',
        opaquePaymentCard: token_service_provider_opaque_payment_card,
      };
    }
    if (session.cardSetting === 1) {
      paymentCredentials.cardCredentials = {
        googleOpaquePaymentCard: google_opaque_payment_card,
      };
    }

    window.googlepay.pushPaymentCredentials(paymentCredentials);
  },
  onSuccess: () => {
    // Show "Added to Google Wallet" to the cardholder
  },
  onFailure: () => {},
  onCancel: () => {},
});

• On your backend, call POST /cards/:card_id/push_provision with the google_pay_web channel:

curl -X "POST" \
  --url "${INCREASE_URL}/cards/card_oubs0hwk5rn6knuecxg2/push_provision" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "channel": "google_pay_web",
    "cardholder_name": "Ian Crease",
    "google_pay_web": {
      "server_session_identifier": "...",
      "public_device_identifier": "...",
      "public_wallet_identifier": "..."
    }
  }'

{
  "channel": "google_pay_web",
  "google_pay_web": {
    "token_service_provider_opaque_payment_card": "...",
    "google_opaque_payment_card": "..."
  }
}

Google only provides publicDeviceId and publicWalletId when the Card can be added to one of the cardholder’s devices. Without them, Increase only returns the google_opaque_payment_card.

Google can also override the token and card settings you asked for, so only include tokenCredentials and cardCredentials when the session’s tokenSetting and cardSetting are 1. Set displayName, lastDigits, and userAddress to the Card’s name, last four digits, and billing address.

Google Pay in-app push provisioning

• Add an Add to Google Wallet button to your Android application, following Google’s brand guidelines.

• When the button is tapped, Google’s SDK provides a GeneratePaymentCredentialsRequest. Send its stableHardwareId, walletId, and serverSessionId to your backend.

• On your backend, call POST /cards/:card_id/push_provision with the google_pay_in_app channel:

curl -X "POST" \
  --url "${INCREASE_URL}/cards/card_oubs0hwk5rn6knuecxg2/push_provision" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "channel": "google_pay_in_app",
    "cardholder_name": "Ian Crease",
    "google_pay_in_app": {
      "stable_hardware_identifier": "...",
      "wallet_identifier": "...",
      "server_session_identifier": "..."
    }
  }'

{
  "channel": "google_pay_in_app",
  "google_pay_in_app": {
    "token_service_provider_opaque_payment_card": "...",
    "google_opaque_payment_card": "..."
  }
}

• Return the opaque payment cards to Google’s SDK as the payment credentials for the GeneratePaymentCredentialsRequest.

server_session_identifier is optional. Without it, Increase only returns the token_service_provider_opaque_payment_card, which adds the Card to the device but doesn’t save it to the cardholder’s Google account.