Overview

The eWallet Tokens feature allows partners to:

• Enable customers to add credit and debit cards to their digital wallets (i.e. Google Pay or Apple Pay) directly from the card issuer’s (i.e. Visa or Mastercard) application
• Create push provisioning data
• Retrieve push provision configuration options for a specific account
• Retrieve eWallet tokens for a specific account

📘

Partners must be configured to use eWallet Token APIs. Contact your Green Dot representative to request configuration.

Digital Wallets

Digital wallets, such as Apple Pay and Google Pay, store digitized versions of payment instruments (cards) which provides customers with a secure and convenient way to store and use their payment instruments without carrying physical cards. The eWallet Tokens APIs allow Partners to offer digital wallet technology to their customers.

📘

Certain prerequisites are required for iOS / Android integrations.

Tokenization

When using digital wallet technology, a customer’s card data, such as the PAN, CVV, and expiration date, is protected using card tokenization. Once a payment instrument is added to a digital wallet, the sensitive data is replaced with a token that serves as a reference to the payment instrument whenever it is used. For example, if a customer uses a payment instrument in their Google Pay digital wallet to purchase groceries, Google Pay will only provide the token at checkout without exposing any of the card data. Green Dot supports network tokenization where the card network (i.e., Visa, Mastercard, Discover, QUICPay) generates the tokens.

iOS / Apple Pay Prerequisites

You will need to submit a request to enable your developer Team ID for the appropriate Apple Pay In-App Provisioning entitlements. Enterprise Team IDs are not supported.

Provide the following information via e-mail to [email protected].

• App Name
• TeamID (e.g. 1ABCD2FGHI)
• AdminID (e.g. 123456789)

Once the entitlements have been granted, you’ll need to include the distribution entitlement into a provisioning profile and ensure you are leveraging the same profile to develop the app within Xcode. Please follow these steps:

1. Head to the Apple Developer Website and proceed to login
2. Select Certificates, Identifiers & Profiles
3. Select “Distribution” underneath the “Provisioning Profiles” heading on the sidebar
4. On the right, select the distribution iOS provisioning profile that you'll use to deploy your App to the App Store
5. Click “edit" and, from the ensuing entitlements dropdown, select “ApplePay In-App Provisioning Distribution” to add the entitlement to the profile. See Figure 3 for details.

Once you’ve generated a profile which has been assigned the entitlement for In-App Provisioning, within Xcode, head to the Preferences > Accounts > (Your Account) > View Details pane where you can then find and download the profile you generated.

Lastly, in build settings, you can then adjust the Provisioning Profile to the newly generated profile. See following screenshots for details.

As a final step add the entitlement manually to the .entitlement plist file of your Xcode project, by setting to true the following key: com.apple.developer.payment-pass-provisioning. Below an example of a simple .entitlement plist containing the In-App Provisioning entitlement key.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/
PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
       <key>com.apple.developer.payment-pass-provisioning</key>
       <true/>
       <key>com.apple.developer.pass-type-identifiers</key>
       <array>
               <string>$(TeamIdentifierPrefix)*</string>
       </array>
</dict>
</plist>

Android / Google Pay Prerequisites

1. Whitelist your app

Google grants access to the Push Provisioning API only to participating financial institutions. Therefore, issuer apps need to be whitelisted before they can call the API.

Please use our App whitelist request form to request to have your app package name and SHA-256 certificate checksum whitelisted.

$ keytool -printcert -jarfile my-push-provisioning-app.apk | grep SHA256
SHA256: 36:38:63:59:6E:...:00:82:16:4E:FF

In addition to whitelisting your production app, we can also whitelist other package names for your pre-release apps (e.g. an alpha or beta build). However, we require that you reserve the namespace in the Google Play Store for any whitelisted package names. You can reserve the namespace without releasing an app by uploading the app but not finalizing the publication process (Do not click on 'Publish').

Once we have whitelisted your package name, force the update using either of the following techniques:

• Enter ##CHECKIN## or ##243546## into the Android phone app. If successful, the digits should disappear and the update will happen silently.
• Navigate to Android Settings > System > System update > Check for update.

2. Extract the SDK into a Maven Repo

The public version of the Google Play services SDK is available through maven.google.com. To access the this API, you must add our private SDK supplement to the public build.

Our supplement is composed of a series of Java libraries (AAR files) and artifacts (POM, XML, SHA1) structured as a Maven repository. When building your app, you must ensure Gradle resolves the public SDK with our supplement to avoid compilation errors.

To integrate the Push Provisioning libraries, you need to perform a few basic tasks to prepare your Android Studio project:

1. Unzip the SDK
2. Edit your project Gradle file
3. Edit your module Gradle file

Unzip the SDK

Unzip the SDK supplement you downloaded from releases page. Make sure the path to the SDK supplement aligns with the path you configure in your Gradle configuration.

Edit your project Gradle file

Add rules to your root-level build.gradle file, to include a dependency checker plugin for Google-specific artifacts from the Google Maven repository:

buildscript {
    // ...
    dependencies {
        // ...
        classpath 'com.google.android.gms:strict-version-matcher-plugin:1.0.1'
    }
}
 
allprojects {
    // ...
    repositories {
        // ...
        google() // Google's public Maven repository
        maven { url "file:/path/to/your/repo/m2repository/" }  // Local path to the push provisioning SDK
    }
}

Edit your module Gradle file

In your module Gradle file (usually the app/build.gradle), add the apply plugin line at the bottom of the file to enable the Gradle plugin:

apply plugin: 'com.android.application'
 
android {
  // ...
}
 
dependencies {
  // ...
  implementation 'com.google.android.gms:play-services-tapandpay:16.0.0'
  // Getting a "Could not find" error? Make sure you have added the Google
  // maven repository and our supplement to your root build.gradle
}
 
// ADD THIS AT THE BOTTOM, you may have the "google-services" plugin below it as well.
apply plugin: 'com.google.android.gms.strict-version-matcher-plugin'

📘

The API can only be used after whitelisted.

eWallet Token API Endpoints

Now that you have prerequisites completed for either Apple Pay or Google Pay, you can utilize our eWallet Token APIs below for push provisioning.

Creates Push Provisioning Data for App-Initiated Digital Wallet Operations

Push provisioning allows customers to add credit and debit cards to their digital wallets (i.e. Google Pay or Apple Pay) directly from the card issuer’s (i.e. Visa or Mastercard) application. This endpoint can be used to create the data needed to add payment instruments to a digital wallet within the card issuer’s application.

API Call Structure

POST /programs/{programCode}/accounts/{accountIdentifier}/paymentInstruments/{paymentInstrumentIdentifier}/CreatepushProvisionData

POST /programs/{programCode}/accounts/{accountIdentifier}/paymentInstruments/{paymentInstrumentIdentifier}/pushProvisionData

API Call Structure Parameters

Sample Requests

Sample Request Body – Apple Pay
{
   "walletProvider":"apple",
   "deviceData":{
      "nonce":"fa5fa8f08186b3e52dd46a51cc22a638ab6badf69281aefce377ae7f7ca37c3d",
      "nonceSignature":"ea83a9a6862149815a563d06f2b8dffb49ad00d9cfcb0ef683652f3ee0f16698", 
      "publicCertData":"30820413308203b8a003020102020812f0fd2adc53b95d300a06082a8648ce3d0403023081813
      13b303906035504030c3254657374204170706c6520576f726c647769646520446576656c6f706572732052656c6
      174696f6e73204341202d204543433120301e060355040b0c1743657274696669636174696f6e2041757
      4686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301
      e170d3137303532303034313535375a170d3139303631393034313535375a306d3136303406035504030
      c2d6563632d63727970746f2d73657276696365732d656e6369706865726d656e745f5543362d496e4d6
      56d6f72793111300f060355040b0c084170706c6550617931133011060355040a0c0a4170706c6520496e
      632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004
      2e3e5ccf6b9ab04be7a22f3faccfde73c87e87155394a34815408a896ca18a374dac669af3bf6220fc863767f
      4af47507c5bc221fc4a19874daf39b4074e3eb8a382022b30820227304f06082b060105050701010443304
      1303f06082b060105050730018633687474703a2f2f6f6373702d7561742e636f72702e6170706c652e636
      f6d2f6f63737030342d74657374777764726361656363301d0603551d0e04160414ad2ea3cb7e34c2edee
      43684e27111fcc493339d0300c0603551d130101ff04023000301f0603551d23041830168014d6d6d55ae5
      fffdc27c34c343debd68765c36a9be3082011d0603551d2004820114308201103082010c06092a864886f7
      636405013081fe3081c306082b060105050702023081b60c81b352656c69616e6365206f6e20746869732
      0636572746966696361746520627920616e7920706172747920617373756d657320616363657074616e
      6365206f6620746865207468656e206170706c696361626c65207374616e64617264207465726d732061
      6e6420636f6e646974696f6e73206f66207573652c20636572746966696361746520706f6c69637920616e
      642063657274696669636174696f6e2070726163746963652073746174656d656e74732e303606082b06
      010505070201162a687474703a2f2f7777772e6170706c652e636f6d2f636572746966696361746561757
      4686f726974792f30410603551d1f043a30383036a034a0328630687474703a2f2f63726c2d7561742e636
      f72702e6170706c652e636f6d2f6170706c657777647263616563632e63726c300e0603551d0f0101ff040
      403020328301206092a864886f7636406270101ff04020500300a06082a8648ce3d040302034900304602
      21008cbd4ab6614c58fd1a93584e05aac3d3afdcc6ca2942ba7214dc54a86ed7a9ee022100ded5771dc1d2
      9ec34c2a971ddd3920fb1918b7480c6d4d4f13a4d8e8ff37b186"
   }
}

Sample Request Body – Google Pay
{
   "walletProvider":"google",
   "deviceData":{
      "clientDeviceId":"TdUHPKS07-Emnen8vpBtvCApt",
      "clientWalletId":"oIm5zV9g0UObFJRuz92qZWhw"
   }
}

Request Parameters

Sample Response

Sample Response – Apple
{
   "activationData":"FOqhkP1N4hvGoZ0DcUi/z6zQf6vOu0o/Zxdv7Ae6qb8=",
   "encryptedPaymentData":{
      "version":"EC_v3",
      "ephemeralPublicKey":"ZZMsgjYmi0KDdxyFo12SfA==",
      "publicKeyHash":"+OQASwQ/N06FeGjPAQ0X9w==",
      "data":"jGQ8uoUK/0GVtTCsZNaE9Q=="
   },
   "displayName":"Super Product",
   "paymentNetworkOperator":"Visa",
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Sample Response – Google
{
   "billingAddress":{
      "addressLine1":"3465 E Foothill Blvd",
      "addressLine2":"SUITE 100",
      "city":"Pasadena",
      "state":"CA",
      "zipCode":"91107",
      "countryCode":"USA",
      "type":"Home",
      "isDefault":true,
      "isVerified":false,
      "isReturned":false,
      "lastUpdatedDateTime":"12/02/2019 01:34:13"
   },
   "phoneNumber":{
      "number":"5555551234",
      "type":"mobile",
      "isDefault":true,
      "isVerified":true,
      "lastUpdatedDateTime":"12/02/2019 01:34:13"
   },
   "last4Pan":"1111",
   "paymentNetworkOperator":"Visa",
   "displayName":"Super Product",
   "opc":"eyJraWQiOiJXOUdTOVFFWFJHVktWVE9MWFIxTzExa2VBSXdIVGF1aUtxdFBQWWxqM1A2bGdYLXVFIiwid
    HlwIjoiSk9TRSIsImNoYW5uZWxTZWN1cml0eUNvbnRleHQiOiJTSEFSRURfU0VDUkVUIiwiZW5jIjoiQTI1NkdD
    TSIsInRhZyI6IktCUWNRU2ZQUUpHYWtjRjdkMHh1VkEiLCJpYXQiOjE1NzUzMjE0NzIsImFsZyI6IkEyNTZHQ01
    LVyIsIml2IjoiaV92blNMREZmaWthRGZwcyJ9.yF28yFIhoU-mreWRBbLA4HxHsjQg4kGfMARc5xCuDY0.9T-ZMi96DU-
    yC9rP.48wfLg9F_bV8oiKnrxHfX8jRIKft2Xz2rLMDp9r6aHy25PI45X7VK54cTKtp-OG8wI1YCSlagoD2b3wZDGDITBdppvqo1GHRi_Hn7B4IUEENYRs0CleQq8ZltUL8zgfaGBP9iCOJD7Fk3ZPsxKtv
    SZ5hkFgPAdkzjXH1EjHkib7o-zRkkX9NlpOJIctYQIpmubdUI95UKAN8WchXEV7kQXwsOukWxWo0rpoNSAmQwsGYBcfgEySQ7Fdg-
    1mhI6fkkiOxqcKlTnszOYD9hQ77QwKmK6jYG6HpLwMia7nFmPMC4eG_P6qf6qTSmv6EtG57DjdW_AjEVKR
    b3ZhH7PBjvl_5vdtxy448LxO_aHLqSK9b_Avkv5Q3faKRH5jzhe9l8t2D2YjYv-lf8zXED-
    y1sSO5AqL4ScTwujs6QrVaYjwiC2c1MlTVxxUyMJIN7mE8pZYQOMt8U9H2juKYmG749qGgxzte0pEMoAK0D
    TahifNMyzMQFzVl4vQz97cUxf04I71jMacjvNFs4DNk3GBls0eBixj8q5bytiTX371MBxsUATwdK7FuE85TcXzKJ
    qzLOkXo108m-TAsXyI6muMDCAfm_3D17fwnePlMsNeEAg.HOhMDW0PdmesJtzCtk3Bjg",
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Response Parameters

Response Codes

Get List of Push Provision Config Options

This endpoint allows Partners to retrieve a list of options that can be used to add payment instruments to a digital wallet for a specific account.

API Call Structure

GET /programs/{programCode}/accounts/{accountIdentifier}/pushProvisionConfig

Request Parameters

Sample Response Body

{
   "provisionConfigs":[
      {
         "walletProvider":"apple",
         "tokenServiceProviderEncryptionVersion":"EV_ECC_v2",
         "paymentNetworkOperator":"Visa"
      },
      {
         "walletProvider":"google",
         "tokenServiceProviderEncryptionVersion":"opc",
         "paymentNetworkOperator":"Visa"
      }
   ],
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Response Parameters

Response Codes

Get List of Payment Instrument Tokens

This endpoint allows the retrieval of all eWallet tokens previously provisioned into a digital wallet for a specific account based on the accountIdentifier provided in the request.

API Call Structure

GET /programs/{programCode}/accounts/{accountIdentifier}/tokens

API Call Structure Parameters

Sample Response Body

{
   "tokens":[
      {
         "paymentIdentifier":"358d4590-c705-4897-8b8f-6a41b0ddcb3b",
         "deviceId":"string",
         "last4Pan":"6800",
         "DPANID":"DNITHE301908474895150373",
         "FPANID":"V-3019084710557757067789",
         "PAR":"V0010013019084710556681691761",
         "last4DPAN":"0858",
         "wallet":"Apple Pay",
         "walletType":"digitalWallet",
         "status":"active"
      },
      {
         "paymentIdentifier":"358d4590-c705-4897-8b8f-6a41b0ddcb3b",
         "last4Pan":"6800",
         "DPANID":"DNITHE301908476980456666",
         "FPANID":"V-3019084710556356039764",
         "PAR":"V0010013019084710556109830817",
         "last4DPAN":"2256",
         "wallet":"Google Pay",
         "walletType":"digitalWallet",
         "status":"active"
      },
      {
         "paymentIdentifier":"358d4590-c705-4897-8b8f-6a41b0ddcb3b",
         "last4Pan":"6800",
         "DPANID":"DNITHE301908477007877450",
         "FPANID":"V-3019084710554673407693",
         "PAR":"V0010013019084710555813032289",
         "last4DPAN":"6401",
         "wallet":"Samsung Pay",
         "walletType":"digitalWallet",
         "status":"active"
      }
   ],
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Response Parameters

Response Codes