Overview

This topic describes how to accept payments from your customers via APMs using Nuvei Web SDK methods.

1. Initiate a Session

Before you can submit payment using the client-side Nuvei Web SDK, you need to send the /openOrder API call.

Prerequisites and Notes for the /openOrder Request

• The server-side /openOrder API request does the following:
  • Authenticates your Nuvei merchant credentials.
    (You can log in to the Nuvei Control Panel using your username and password to find your credentials here.)
  • Sets up the authenticated order in the Nuvei system, and returns a sessionToken which is needed to send other requests in the session.
• Always send the /openOrder request from your backend server because the checksum parameter calculation includes your secret key, which should NOT be exposed on the client side.

Sending an /openOrder Request

On the server side, send an /openOrder request with its mandatory parameters, and include the following:

• checksum
  This is a SHA-256 encrypted string that you create, which is used for request authentication. You can calculate it by performing a SHA-256 encryption on a string of these concatenated fields, in the following order:
  merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, and your merchantSecretKey at the end.
• country and email
  If these are not provided here, then they must be included later in a createPayment() / authenticate3d() request.
• urlDetails.notificationUrl (recommended)
  The URL to which DMNs can be sent.
• preventOverride=”1” (optional)
  This prevents future requests from over-writing values contained in these classes: userDetails, billingAddress, or shippingAddress.
• sessionCardDeclineLimit (optional)
  This parameter controls the number of transaction declines that can be received during a single session. If this limit of declines is reached, the session expires immediately.

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.

Send a createPayment() request with its mandatory parameters, the payment method selected in the previous step, and the relevant input fields.

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: "[email protected]"
  }
}, 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 (returned in 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.