Overview
This guide provides steps to send payments and recurring payments to Apple Pay using Nuvei Web SDK.
Prerequisites and Notes
Before you begin, perform the steps in the Initiate a Session topic.
Test Your Integration
After completing the relevant integration steps, test your Apple Pay integration in the Apple Pay Sandbox environment using the test credit and debit cards provided.
See the Apple Pay Integration Testing topic.
Payments
You can process payments using the Web SDK createPayment() method, which manages end-to-end card payment processing.
Call the Web SDK createPayment() request with its mandatory parameters. Include the data received on your server, in the paymentOption.card.externalToken
block with these parameters:
externalTokenProvider
: “ApplePay“mobileToken
: “<the encrypted data generated by Apple from the device by a function defined insc_api_applepay.min.js
>“
Example createPayment()
Request – Decryption by Nuvei
sfc.createPayment({ sessionToken: "<sessiontoken from openOrder>", merchantId: "<your merchantId>", merchantSiteId: "<your merchantSiteId>", clientUniqueId: "<unique transaction ID in merchant system>", // optional paymentOption: { card: { externalToken: { externalTokenProvider: "ApplePay", mobileToken: "<encrypted token received from Apple Pay>" } }, billingAddress: { email: "[email protected]", country: "US" } } )
Example createPayment()
Response
{ "result": "APPROVED", "errCode": 0, "errorDescription": "", "userPaymentOptionId": "14958143", "ccCardNumber": "5****5761", "bin": "511142", "last4Digits": "5761", "ccExpMonth": "09", "ccExpYear": "21", "transactionId": "1110000000004146935", "threeDReason": "", "threeDReasonId": "", "challengeCancelReasonId": "", "challengeCancelReason": "", "isLiabilityOnIssuer": "1", "challengePreferenceReason": "", "cancelled": false }
Control 3D Flow
The merchant can control 3D flow via Web SDK by adding applePay3Dflow
to the paymentOption
block in createApplePayPayment()
. When sending applePay3Dflow
=disable (default), Web SDK processes the card transaction as a non-3D Apple Pay transaction; when sending applePay3Dflow
=enable, the transaction is processed with 3D-Secure verification.
Example createApplePayPayment()
request with applePay3Dflow
sfc.createApplePayPayment({ sessionToken: "<sessiontoken>", // received from openOrder API merchantId: "<your merchantId>", // as assigned by Nuvei merchantSiteId: "<your merchantSiteId>", // as assigned by Nuvei clientUniqueId: "<unique transaction ID in merchant system>", // optional countryCode: 'GB', currencyCode: 'GBP', applePay3Dflow: "disable", // disable (default), enable collectUserDetails: false, billingAddress: { firstName: 'John', lastName: 'Smith', country: 'US', email: '[email protected]' }, userDetails: { firstName: 'John', lastName: 'Smith', country: 'US', email: '[email protected]' } shippingAddress: { firstName: 'John', lastName: 'Smith', address: '22 Main Street', city: 'Boston', zip: '02460', state: 'MA', country: 'US' }, total: { label: 'Your Company', amount: '19.99' } function(res) { console.log(res) } });
Recurring Payments
You can use Apple Pay for recurring payments, which involves two types of payments.
The first payment is initiated by the customer using Apple Pay.
Subsequent payments are initiated by the merchant.
Follow these steps to integrate Apple Pay recurring payments into your payment flow:
Initial Recurring Payment
The first recurring payment request is initiated by the customer.
1. Initiate a Session
When sending the /openOrder
request described in the Initiate a Session topic, include the following parameters:
userTokenId
: “<unique customer identifier in merchant system>“isRebilling
: “0“
Example /openOrder
Request for Recurring Payments
{ "merchantId": "<your merchantId goes here>", "merchantSiteId": "<your merchantSiteId goes here>", "clientUniqueId": "<unique transaction ID in merchant system>", "clientRequestId": "<unique request ID in merchant system>", "userTokenId": "<unique customer identifier in your system>", "isRebilling": "0", "currency": "USD", "amount": "200", "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
2. Send the Initial Payment
Perform the steps in the Payments topic above.
(How it works: Behind the scenes, the createPayment()
request knows that this is an “initial recurring payment” via the sessionToken
.)
Subsequent Payments
Subsequent recurring payments are initiated by you (with the customer’s consent) from the backend using REST API (not from the frontend via Web SDK).
Perform the steps in the REST API Subsequent Recurring Payments topic, and also include: userTokenId
: “<unique customer identifier in merchant system>“.