Overview
This topic describes how to accept payments from your customers via APMs using Nuvei Web SDK methods.
1. Initiate a Session
The server-side /openOrder
API request does the following:
- Authenticates your Nuvei merchant credentials.
- Sets up the authenticated order in the Nuvei system, and returns a
sessionToken
, which is needed later for the Web SDKcreatePayment()
method.
Send a server-side /openOrder
API request with its mandatory parameters.
Example /openOrder
Request
{ "merchantId":"<your merchantId goes here>", "merchantSiteId":"<your merchantSiteId goes here>", "clientUniqueId":"<unique transaction ID in merchant system>", "clientRequestId":"<unique request ID in merchant system>", "currency":"USD", "amount":"200", "timeStamp":"<YYYYMMDDHHmmss>", "checksum":"<calculated checksum>" }
<?php $safecharge = new \SafeCharge\Api\RestClient([ 'environment' => \SafeCharge\Api\Environment::INT, 'merchantId' => '<your merchantId>', 'merchantSiteId' => '<your merchantSiteId>', 'merchantSecretKey' => '<your merchantSecretKey>', ]); $openOrderRequest = $SafeCharge->getPaymentService()->openOrder([ 'clientUniqueId' => '<unique transaction ID in merchant system>', 'clientRequestId' => '<unique request ID in merchant system>', 'currency' => 'USD', 'amount' => '200', ]); ?>
public static void main(String[] args) { // for initialization String merchantId = "<your merchantId>"; String merchantSiteId = "<your merchantSiteId>"; String merchantKey = "<your merchantKey>"; safecharge.initialize(merchantId, merchantSiteId, merchantKey, APIConstants.Environment.INTEGRATION_HOST.getUrl(), Constants.HashAlgorithm.SHA256); //for openOrder String clientUniqueId = "<unique transaction ID in merchant system>"; String clientRequestId = "<unique request ID in merchant system>"; String currency = "USD"; String amount = "200"; Safecharge safecharge = new Safecharge(); SafechargeResponse response = safecharge.openOrder(userTokenId, clientRequestId, clientUniqueId, null, null, null, null, currency, amount, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null); }
var safecharge = new Safecharge( "<your merchantKey>", "<your merchantId>", "<your merchantSiteId>", "<your server host value>", HashAlgorithmType.SHA256 ); var response = safecharge.OpenOrder( "USD", "200", clientUniqueId: "<unique transaction ID in merchant system>", clientRequestId: "<unique request ID in merchant system>", );
const safecharge = require('safecharge'); safecharge.initiate(<merchantId>, <merchantSiteId>, <merchantSecretKey>, <env>); safecharge.paymentService.openOrder({ 'clientUniqueId' : '<unique transaction ID in merchant system>', 'clientRequestId' : '<unique request ID in merchant system>', 'currency' : 'USD', 'amount' : '200' }, function (err, result) { console.log(err, result) });
Example /openOrder
Response
{ "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b", "orderId": "39272", "merchantId": "427583496191624621", "merchantSiteId": "142033", "clientUniqueId": "12345", "clientRequestId": "1484759782197", "internalRequestId": "866", "status": "SUCCESS", "errCode": "0", "reason": "", "version": "1.0" }
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: 'int', // Nuvei API environment - 'int' (integration) or 'prod' (production - default if omitted) merchantId : '<your merchantId>', //as assigned by Nuvei merchantSiteId : '<your merchantSiteId>' //as assigned by Nuvei });
3. Get APM Details (optional)
The getAPMs()
method retrieves a list of APMs supported by your Nuvei merchant account, which can be filtered by country, currency, language, and type (deposit or withdrawal).
You can display these APMs to the customer to select a payment method. After the customer chooses one, you can send the selected paymentMethod
in a createPayment()
request.
The following getAPMs()
example retrieves a list of APMs for a customer from the UK (GB) who uses GBP currency.
Example getApms()
Request
sfc.getApms({ "currencyCode": "GBP", "countryCode": "GB", "languageCode": "en" }, function(res) { console.log(res) })
The example response returns two payment methods:
- A card:
"paymentMethod": "cc_card"
- A PayPal APM:
"paymentMethod": "apmgw_expresscheckout"
You can display the APM display name and logo returned, to allow a customer to select a payment method.
(After they choose one, in the next step you can send the selected fields.name
in a createPayment()
request.
Example getApms()
Response
{ "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": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "version": "1.0", "clientRequestId": "20200301153018" }
4. Create an APM Payment
When processing a redirect-based APM payment, the Web SDK opens a new tab or an IFrame for the APM provider to collect payment details from the customer.
The createPayment()
example below shows an APM payment using the paymentMethod
parameter to specify the "apmgw_expresscheckout"
PayPal APM.
Example createPayment()
Request
sfc.createPayment({ "sessionToken": "<sessiontoken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "clientUniqueId": "695701003", "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'); });
5. Redirect to the APM
Use the redirectUrl
(from the response to the createPayment()
request above) to redirect your customer to the APM’s URL.
6. Verifying the Response
See the Web SDK Response Verification topic.