Introduction
Purpose
This guide provides steps to integrate Apple Pay into your payment flow using the Nuvei Simply Connect platform.
After the successful completion of this integration, the Apple Pay button should appear in the Payment Methods Gallery of your website or application, when using an Apple Pay compatible device.
Prerequisites and Notes
This guide assumes you have completed all account setup prerequisites, and are ready to integrate Apple Pay into your payment flow.
You are responsible for the button implementation, according to the Apple Pay UI guidelines.
1. Authentication
Follow the instructions in these steps:
- Initiate a Session
This authenticates and sets up an order in the Nuvei system, by sending an/openOrder
request, and returns asessionToken
. - Create an HTML Placeholder
This instantiates the Web SDK with thesessionToken
received from the server call to/openOrder
.
2. Collect the Card Details
The Apple Pay button is used to collect your customer’s card details.
Display the Apple Pay button in the payment methods gallery on the Nuvei Simply Connect page, as follows:
Send a checkout()
request with its mandatory checkout() Input Parameters as shown in the example, and include these additional parameters:
- Any additional optional parameters that you require.
- If you would like Nuvei to collect the user’s details directly from ApplePay, then you can set the
collectUserDetails
parameter as ‘true‘ in theapmConfig
block. Default value is set as ‘false‘. When you set this parameter to true, Nuvei sends ApplePay (in the token request) both shipping and billing objects to be returned, map them to the relative classes, and send it in theclientPayment
request. - (Optional) If you want to customize the button style (the color), the button type (the text), or the location of the Apple Pay button, then include the
apmConfig
block, as shown in the example below:- To customize the Apple Pay button color, include the
buttonStyle
parameter:- Possible values: black (default), white, white-outline
- For examples, see the Button Styles section.
- To customize the text on the Apple Pay button, include the
buttonType
parameter:- Possible values: buy (default), plain, book, checkout, order, pay, subscribe, inStore, addMoney, X, contribute, donate, reload, rent, setUp, support, tip, topUp
- For examples, see the Button Types section.
- To customize the Apple Pay button location, include the
buttonLocation
parameter:- Possible values: onTop (default), gallery
- To customize the Apple Pay button color, include the
Example checkout()
Request for Apple Pay
checkout({ logLevel: 0, payButton: "amountButton", showResponseMessage: true, sessionToken: document.getElementById('session').value, env: 'test', merchantSiteId: document.getElementById('merchantSiteID').value, merchantId: document.getElementById('merchantID').value, country: 'US', locale: 'en', apmConfig: { applePay: { collectUserDetails: 'true', // false (default), true buttonStyle: 'black', // black (default), white, white-outline buttonType: 'checkout' // buy (default), plain, // book, checkout, order, pay, subscribe, inStore, // addMoney, continue, contribute, donate, reload, // rent, setUp, support, tip, topUp buttonLocation:’onTop’// onTop (default), gallery } }, currency: 'USD', amount: 135, renderTo: '.container_for_checkout', onResult: onResult, autoOpenPM: true, alwaysCollectCvv: false, fullName: 'CL-BRW1', email: 'ranv@nuvei.com' })
3. Payment
The Apple Pay button is displayed in the payment methods gallery on the Nuvei Simply Connect page.
- The customer triggers the Apple Pay payment flow by pressing the Apple Pay button.
- Apple Pay displays the cards in the customer’s Wallet, or asks the customer to “Add new credit/debit card” details.
- After the customer selects one of their Apple Pay payment methods, Apple Pay returns the encrypted token for Nuvei to process the transaction.
- Nuvei processes the transaction and handles the rest of the payment flow automatically.
- When the transaction is complete, the system displays the relevant “Approved” / “Declined” transaction message.
3D Flow Process
To manage the 3D Flow process, you need to add a new parameter in theapmConfig
object 3Dflow with the value “enable” that is a default value.
When this parameter is sent in the initialization object, the flow proceeds as follows:
- Simply Connect initiates the payment process with
3Dflow
: enable in theapmConfig
block.{ "apmConfig":{ "applePay":{ "3Dflow":"enable" } } }
- The user selects “Apple Pay” from the gallery and presses the Pay button.
- Simply Connect sends an
initPaymentWithCardTokenization
request to check if the card supports 3D. - If the response includes
paymentOption.card.threeD.v2supported
: “true”, indicating that the card supports 3D, Simply Connect processes the payment in the 3DS-v2 Payment flow. It collects the fingerprinting and continues by sending aclientPayment()
request with complete 3D block information. - If
paymentOption.card.threeD.v2supported
: “false”, indicating that the card does not support 3D, no 3D processing takes place. - The cryptogram is stored and can be used for finalizing the payment if required.
- Once the process is completed, the merchant receives a response and a DMN with the status of the transaction.
Appendix – JSFiddle Example
Editing JSFiddle Examples
You can use the JSFiddle demonstration environment to view, run and customize the code examples below.
To edit sample code in JSFiddle, press “Edit in JSFiddle” in the top right corner.
This redirects you to a page where you run and test the code.
Feel free to change your code, including the HTML and CSS.
Simply Connect JSFiddle
You can use the JSFiddle demonstration environment to view the Apple Pay Simply Connect example below.
If you are using an Apple device, then you can also run and customize the Apple Pay Simply Connect example.