Digital wallets
Your cardholders can add cards to digital wallets such as Apple Pay and Google Pay using standard text entry or automated push provisioning.
Configuration
All cards issued through a Green Program have support for digital wallets enabled immediately.
If you have one of our Blue or Orange Programs, it must be configured to support digital wallets. During the configuration process Apto works with the issuing bank, the card networks, and the relevant app store to run checks and gain approval for cards to work with each kind of digital wallet.
The approval process includes administrative and operational checks. An example of an administrative check is confirming that the cardholder agreement shown in the app, and card design displayed in the wallet’s UI, adhere to standards. An example of an operation check is verifying that information is correctly transmitted between the digital wallet and the card networks.
Apto takes care of the entire process, but it takes some time to exchange paperwork and receive the necessary approvals. We recommend beginning this process as soon as possible during your implementation.
Text entry
If your card program is approved to use digital wallets, your cardholders can enter their card details into any mobile wallet. Green Programs have digital wallet support by default, so cardholders within these programs can enter their payment card details without additional configuration.
Feature summary
This table explains how each feature relates to the main card program types.
| Green Program | Blue or Orange Programs | |
|---|---|---|
| Digital wallets | Enabled immediately | Require configuration |
| Text entry | Allowed immediately | Allowed after configuration is complete |
Testing
Thorough testing ensures that cards can be added to a cardholder’s digital wallet, the Terms and Conditions are displayed correctly, and the necessary One-Time Passcode (OTP) SMS messages are delivered to the cardholder.
Out of the box, digital wallets use the default card design shown in the images above. To ensure that cardholders see your custom card art in their digital wallets, we highly recommend that you finalize digital wallet card art prior to program launch.
Because digital wallets involve many parties—such as a merchant, Mastercard/Visa, and Apple, Google, or Samsung—controlled testing must be performed in a production environment.
Apto completes rigorous testing, but we recommend that you also perform your own thorough testing prior to launch.
Webhook changes
When a cardholder adds a card to (or removes a card from) a digital wallet, Mastercard/Visa sends Apto a series of transactions. The transactions do the following:
- Exchange the token information
- Inform Apto an OTP verification is made
- Inform Apto a card was approved to be added to a digital wallet
In turn, we send you webhook transaction_update events.
These transactions do not come in the same order each time. You must account for the various orders in which the transactions may arrive. Additionally, not all three transactions are always performed.
Digital wallet provisioning webhooks contain "type": "NON_FINANCIAL". A common identifier is sent in the transaction_update webhook for all related digital wallet transactions.
Below are examples of the webhooks that are generated:
Card was approved to be added
{
"transaction": {
"livemode": true,
"id": "txn_abcdefg12345",
"authorizations": [
{
"authorization": {
"id": "auth_bcdefg23456",
"issuer_data": null,
"decline_code": null,
"decline_reason": null,
"external_authorization_id": "29",
"authorized": null,
"created_at": "2020-09-03T17:55:35Z"
}
}
],
"adjustments": [],
"cardholder_id": "crdhldr_cdefgh3456789",
"created_at": "2020-09-03T17:55:35Z",
"settlement_date": null,
"cardholder_email": "bob@email.com",
"cardholder_first_name": "Bob",
"cardholder_last_name": "Smith",
"card_id": "crd_defghij456789",
"description": "Mastercard St. Louis MOUSA",
"merchant_name": "Mastercard",
"merchant_locality": "St. Louis",
"merchant_region": "MO",
"merchant_country": "USA",
"mcc": "5969",
"mcc_icon": "cart",
"mcc_name": "Direct Marketing",
"merchant_identifier": "CARD ACCPT IDC",
"merchant_terminal_identifier": "MDTERM",
"state": "pending",
"context": "Balance inquiry (MASTERCARD)",
"card_present": false,
"ecommerce": false,
"international": false,
"emv": false,
"network": "MASTERCARD",
"shift_stand_in": false,
"dispute_id": null,
"dispute_at": null,
"dispute_won_at": null,
"dispute_lost_at": null,
"decline_reason": null,
"decline_code": null,
"funding_source_name": "USD Wallet",
"type": "NON_FINANCIAL",
"merchant": {
"found": false,
"latitude": null,
"longitude": null,
"name": null,
"formatted_address": null,
"street_number": null,
"street": null,
"locality": null,
"region": null,
"country": null,
"postal_code": null,
"external_id": null
},
"idempotency_key": null,
"local_amount": {
"currency": "USD",
"amount": 0
},
"hold_amount": {
"currency": "USD",
"amount": 0
},
"cashback_amount": {
"currency": "USD",
"amount": 0
},
"fee_amount": {
"currency": "USD",
"amount": 0
},
"billing_amount": {
"currency": "USD",
"amount": 0
},
"native_balance_amount": {
"currency": null,
"amount": null
},
"event": null
}
}
OTP verification
{
"transaction": {
"livemode": true,
"id": "txn_abcdefg12345",
"authorizations": [],
"adjustments": [],
"cardholder_id": "crdhldr_cdefgh3456789",
"created_at": "2020-09-03T17:55:58Z",
"settlement_date": null,
"cardholder_email": "bob@email.com",
"cardholder_first_name": "Bob",
"cardholder_last_name": "Smith",
"card_id": "crd_defghij456789",
"description": null,
"merchant_name": null,
"merchant_locality": null,
"merchant_region": null,
"merchant_country": null,
"mcc": "7299",
"mcc_icon": "card",
"mcc_name": "Miscellaneous General Services",
"merchant_identifier": "111111111111111",
"merchant_terminal_identifier": "11111111",
"state": "pending",
"context": "Uncategorized (MASTERCARD)",
"card_present": false,
"ecommerce": false,
"international": false,
"emv": false,
"network": "MASTERCARD",
"shift_stand_in": false,
"dispute_id": null,
"dispute_at": null,
"dispute_won_at": null,
"dispute_lost_at": null,
"decline_reason": null,
"decline_code": null,
"funding_source_name": "USD Wallet",
"type": "NON_FINANCIAL",
"merchant": {
"found": false,
"latitude": null,
"longitude": null,
"name": null,
"formatted_address": null,
"street_number": null,
"street": null,
"locality": null,
"region": null,
"country": null,
"postal_code": null,
"external_id": null
},
"idempotency_key": null,
"local_amount": {
"currency": "USD",
"amount": 0
},
"hold_amount": {
"currency": "USD",
"amount": 0
},
"cashback_amount": {
"currency": "USD",
"amount": 0
},
"fee_amount": {
"currency": "USD",
"amount": 0
},
"billing_amount": {
"currency": "USD",
"amount": 0
},
"native_balance_amount": {
"currency": null,
"amount": null
},
"event": null
}
}
Token exchange and removal (At this time, we do not offer the ability to distinguish between an add and a removal)
{
"transaction": {
"livemode": true,
"id": "txn_abcdefg12345",
"authorizations": [],
"adjustments": [],
"cardholder_id": "crdhldr_cdefgh3456789",
"created_at": "2020-09-03T17:56:02Z",
"settlement_date": null,
"cardholder_email": "bob@email.com",
"cardholder_first_name": "Bob",
"cardholder_last_name": "Smith",
"card_id": "crd_defghij456789",
"description": null,
"merchant_name": null,
"merchant_locality": null,
"merchant_region": null,
"merchant_country": null,
"mcc": null,
"mcc_icon": "right",
"mcc_name": "SENT",
"merchant_identifier": null,
"merchant_terminal_identifier": null,
"state": "pending",
"context": "MASTERCARD Token: 12344567890123 ()",
"card_present": false,
"ecommerce": false,
"international": false,
"emv": false,
"network": "MASTERCARD",
"shift_stand_in": false,
"dispute_id": null,
"dispute_at": null,
"dispute_won_at": null,
"dispute_lost_at": null,
"decline_reason": null,
"decline_code": null,
"funding_source_name": "USD Wallet",
"type": "NON_FINANCIAL",
"merchant": {
"found": false,
"latitude": null,
"longitude": null,
"name": null,
"formatted_address": null,
"street_number": null,
"street": null,
"locality": null,
"region": null,
"country": null,
"postal_code": null,
"external_id": null
},
"idempotency_key": null,
"local_amount": {
"currency": "USD",
"amount": 0
},
"hold_amount": {
"currency": "USD",
"amount": 0
},
"cashback_amount": {
"currency": "USD",
"amount": 0
},
"fee_amount": {
"currency": "USD",
"amount": 0
},
"billing_amount": {
"currency": "USD",
"amount": 0
},
"native_balance_amount": {
"currency": null,
"amount": null
},
"event": null
}
}
Digital wallet transactions appear the same as any other transaction performed with the card. At this time, Apto does not offer the ability to identify whether the transaction was performed using a digital wallet. This feature is currently in our roadmap.