Adding Digital Wallet Data to the Customer Vault

This guide will help you add customers who want to pay using Apple Pay or Google Pay to the Customer Vault. Their payment data is stored securely on the NMI platform, so you can make future payments without a second customer interaction.

1. Prepare To Accept Apple Pay

Make sure you’re already configured to accept Apple Pay and/or Google Pay. For Apple Pay, be sure that the appropriate domains and verification files are set up in the Merchant Portal under Settings > Apple Pay.

2. Collect Digital Wallet Data

Your shopping cart now needs to collect the Apple Pay/Google Pay data.

If your cart gathers Apple Pay or Google Pay data directly, it should have an appropriate integration to receive the encrypted wallet data during the checkout process.

If you use Collect.js, you can choose to surface a ready-made “Pay with Apple Pay” or “Pay with Google Pay” button. When the customer interaction completes, it will post data to your server including a payment_token linked to the encrypted wallet data. See the Digital Wallet Setup guide for more details and example code.

3. Submit Wallet Data To The Vault

Your server can now submit a request to the Gateway to board the vault data. The exact data you send will vary based on the way you've collected the wallet data. In all situations, you should sendcustomer_vault set to add_customer, and optionally a customer_vault_id if you don't want an automatically generated ID.

Sending Collect.js Data

The payment_token pulls the wallet data in automatically.

curl --request POST \
     --url https://secure.nmi.com/api/transact.php \
     --header 'accept: application/x-www-form-urlencoded' \
     --header 'content-type: application/x-www-form-urlencoded'
     
     --data customer_vault=add_customer \
     --data customer_vault_id=123456 \
     --data payment_token=00000000-000000-000000-000000000000\ 
     --data stored_credential_indicator=stored \
     --data initiated_by=customer \

     
     --data first_name=John \
     --data last_name=Doe \
     --data 'address1=123 Main Street' \
     --data 'address2=Apt E' \
     --data city=Wichita \
     --data state=KS \
     --data zip=12345 \
     --data country=US \
     --data phone=8005551212 \
     --data [email protected] \
     
     --data security_key=XXXXXXXXXXXXXXXXXXXXXXXXXXX

Sending Encrypted Wallet Data

(for Google Pay, use googlepay_payment_data instead)

curl --request POST \
     --url https://secure.nmi.com/api/transact.php \
     --header 'accept: application/x-www-form-urlencoded' \
     --header 'content-type: application/x-www-form-urlencoded'
     
     --data customer_vault=add_customer \
     --data customer_vault_id=123456 \
     --data applepay_payment_data=EEvIz56vkjN….zb5MD45fh7687SGfTd=
     --data stored_credential_indicator=stored \
     --data initiated_by=customer \
     
     --data first_name=John \
     --data last_name=Doe \
     --data 'address1=123 Main Street' \
     --data 'address2=Apt E' \
     --data city=Wichita \
     --data state=KS \
     --data zip=12345 \
     --data country=US \
     --data phone=8005551212 \
     --data [email protected] \
     
     --data security_key=XXXXXXXXXXXXXXXXXXXXXXXXXXX

Sending Decrypted Wallet Data

(For Google Pay, send decrypted_googlepay_data instead)

curl --request POST \
     --url https://secure.nmi.com/api/transact.php \
     --header 'accept: application/x-www-form-urlencoded' \
     --header 'content-type: application/x-www-form-urlencoded'
     
     --data customer_vault=add_customer \
     --data customer_vault_id=123456 \
     --data ccnumber=4111111111111111 \
     --data ccexp=1234 \
     --data cavv=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA= \
     --data decrypted_applepay_data=1 \
     --data stored_credential_indicator=stored \
     --data initiated_by=customer \

     
     --data first_name=John \
     --data last_name=Doe \
     --data 'address1=123 Main Street' \
     --data 'address2=Apt E' \
     --data city=Wichita \
     --data state=KS \
     --data zip=12345 \
     --data country=US \
     --data phone=8005551212 \
     --data [email protected] \
     
     --data security_key=XXXXXXXXXXXXXXXXXXXXXXXXXXX

4. Real Time Transaction

When the wallet data is vaulted, we perform a transaction in real time. For Google Pay, this defaults to $0 authorization. For Apple Pay, the transaction is based on the amount baked into the Apple Pay wallet data. (If you use Collect.js to build a subscription request, it defaults to $0). This transaction ensures that we consume the perishable "cryptogram" part of the wallet data before it expires, so the next transaction-- which might not take place for months-- will complete smoothly. Performing a transaction in real time also allows us to block the registration immediately if the payment data is bad, rather than waiting for the first actual payment to fail.

You can also choose to perform an "up-front" sale or authorization, instead of a $0 transaction, while registering the adding the data to the vault. Specify the desired type and amount values on the add_customer request. When you use Apple Pay, the Apple Pay payment sheet must show the customer the intended up-front amount. Collect.js lets you specify data-field-apple-pay-vault-up-front-price to set the value there, and then the request summary says that the customer will be billed when their balance is exhausted.

5. Using the Vaulted Payment Information

Save the transactionid and customer_vault_id values you get back when you vault the payment data. You can perform any additional “follow-up” transactions once the data is successfully vaulted. In subsequent transactions, you should specify appropriate data to link the transactions back to the initial card storage event:

Send the customer_vault_id instead of passing raw card information.
Set appropriate stored_credential_indicator and initiated_by values. Typically stored_credential_indicatorshould be used, since we're using account info we already stored, but the initiated_by could be customer (for situations where a customer is directly triggering an order) or merchant (for subscriptions and top-ups)
Use the saved transactionid as initial_transaction_id to make sure the transaction history is connected correctly.

Here's an example of a merchant-initiated transaction.

curl --request POST \
     --url https://secure.nmi.com/api/transact.php \
     --header 'accept: application/x-www-form-urlencoded' \
     --header 'content-type: application/x-www-form-urlencoded'
     
     --data type=sale \
     --data amount=300.00 \
     --data customer_vault_id=123456 \
     --data stored_credential_indicator=used \
     --data initiated_by=merchant \
     --data initial_transaction_id=123456789023 \
        
     --data security_key=XXXXXXXXXXXXXXXXXXXXXXXXXXX