This guide shows you how you can use the Web SDK to charge your customers with these APMs.
Nuvei offers two Web SDK methods to help you with processing APMs:
-
getAPMs() – This function returns the APMs supported with all their metadata needed for displaying them to the user and prepares them for processing, such as their display name, logo, etc. and most importantly the APM
name
field. You use this field to specify which APM you wish to charge when requesting a payment, as shown next.
Using getAPMs() is optional. You do not need it if you already know which APM you are going to charge and the input required for it.
-
createPayment() – Call this method to request a payment for the APMs, specified in the
name
field. Most of the APMs are “redirect” based, which means that the Web SDK opens a tab or an Iframe of the APM provider to collect the payment from the end user.
In addition, as with any Web SDK, you have to call the /getPaymentStatus
API to verify the response of the payment.
Step-by-Step Guide
Step 1: Authenticate and Open Session
Before you can start the APM payment session, you need to authenticate and create a sessionToken
using the openOrder() method.
Sample Request:
{ "merchantId":"427583496191624621", "merchantSiteId":"142033", "userTokenId":"487106", "clientUniqueId":"12345", "clientRequestId":"1484759782197", "currency":"USD", "amount":"10", "billingAddress":{ "firstName":"some first name", "lastName":"some last name", "address":"some street", "cell":"", "phone":"972502457558", "zip":"", "city":"some city", "country":"GB", "state":"", "email":"someemail@somedomain.com", "county":"" }, "dynamicDescriptor":{ "merchantName":"merchantName", "merchantPhone":"merchantPhone" }, "timeStamp":"20170118191751", "checksum":"6b53666fc048a825be63cbb820da467b" }
Sample Response:
{ "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b", "orderId": "39272", "merchantId": "427583496191624621", "merchantSiteId": "142033", "userTokenId": "487106", "clientUniqueId": "12345", "clientRequestId": "1484759782197", "internalRequestId": "866", "status": "SUCCESS", "errCode": "0", "reason": "", "version": "1.0" }
Step 2: Initialize the Web SDK
Instantiate the Web SDK with the sessionToken
received from the server call to /openOrder.
// Instantiate Nuvei API var sfc = SafeCharge({ env: 'test', // the environment you are running on, 'prod' for production merchantId : "", // your Merchant ID provided by Nuvei merchantSiteId : "", // your Merchant Site ID provided by Nuvei });
Step 3: Get APMs (optional)
In this example, we use the getAPMs() to query for all the relevant APMs for a user coming from the UK (GB) and using GBP for currency.
sfc.getApms({"currencyCode": "GBP", "countryCode":"GB", "languageCode":"en"}, function(res){console.log(res)})
The getAPMs() returns a JSON as a response. In the following example, the retrieved payment methods are cards (cc_card) and PayPal (apmgw_expresscheckout). You will need the PayPal API name (apmgw_expresscheckout) in the next step to call the createPayment() method.
{ "paymentMethods": [ { "paymentMethod": "cc_card", "paymentMethodDisplayName": [ { "language": "en", "message": "Credit Card" } ], "countries": [ "GB" ], "currencies": [ "GBP" ], "logoURL": "https://cdn-int.safecharge.com/ppp_resources/02251608/resources/img/svg/default_cc_card.svg", "fields": [ { "name": "ccCardNumber", "type": "text", "caption": [] }, { "name": "ccExpMonth", "type": "text", "caption": [] }, { "name": "ccExpYear", "type": "text", "caption": [] }, { "name": "ccNameOnCard", "type": "text", "caption": [] } ] }, { "paymentMethod": "apmgw_expresscheckout", "paymentMethodDisplayName": [ { "language": "en", "message": "PayPal" } ], "isDirect": "false", "countries": [ "GB" ], "currencies": [ "GBP" ], "logoURL": "https://cdn-int.safecharge.com/ppp_resources/02251608/resources/img/svg/paypal.svg", "fields": [] } ], "type": "DEPOSIT", "sessionToken": "50dd6b3a-ed65-4bae-bb76-184e4a4a00ba", "internalRequestId": 178003768, "status": "SUCCESS", "errCode": 0, "reason": "", "merchantId": "479748173730597238", "merchantSiteId": "180083", "version": "1.0", "clientRequestId": "20200301153018" }
Step 4: Create APM Payment
In this step, we will process a PayPal transaction by calling the createPayment() method.
sfc.createPayment({ "sessionToken" : "<sessiontoken>", //received from openOrder API "merchantId" : "1475082432483184221", //as assigned by Nuvei "merchantSiteId" : "184941", //as assigned by Nuvei "userTokenId" : "230811147", "clientUniqueId" : "695701003", // optional "paymentOption" : { "alternativePaymentMethod": { "paymentMethod": "apmgw_expresscheckout" }, "billingAddress": { "country":"GB" "email": "someone@somedomain.com", } }, function (res) { console.log(res) if (res.cancelled === true){ example.querySelector('.token').innerText = 'cancelled'; }else{ example.querySelector('.token').innerText = res.transactionStatus + ' - Reference: '+ res.transactionId; } example.classList.add('submitted'); })
Step 5: Verify the Payment Response
Call /getPaymentStatus, using the same sessionToken
value.
{ "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b" }
Sample Response:
For a full description of responses, refer to /getPaymentStatus.
{ "transactionStatus": "APPROVED", "gwExtendedErrorCode": 0, "gwErrorCode": 0, "reason": "", "authCode": "075449", "clientRequestId": "9WD9JCZW9", "internalRequestId": 13004281, "version": "1.0", "transactionId": "2110000000001496240", "merchantSiteId": "126006", "transactionType": "Sale", "clientUniqueId": "695701003", "errCode": 0, "paymentOption": { "userPaymentOptionId": "7072706" }, "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b", "userTokenId": "230811147", "status": "SUCCESS" }