APM Payments

On this page:

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 SDK createPayment() method.

Send a server-side /openOrder API request with its mandatory parameters.

Input parameters:

  • checksum – This is a SHA-256 encrypted string that you create for request authentication. You can calculate it by performing a SHA-256 encryption on a string of the concatenation of these fields, in the following order:
    merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp and your secret key in the end.
  • country and email must be included later in the createPayment() request.
  • urlDetails.notificationUrl (optional) – The URL to which DMNs can be sent.
  • Press this /openOrder link for the full list of mandatory parameters.

Multiple input values for the same parameter:

  • Some parameters can be collected in both the /openOrder request and the createPayment() request.
  • When processing a createPayment() request, if there are multiple input values for the same parameter, then the system chooses a single parameter value depending on two factors:
    • The method used to collect the parameter value.
    • The JSON block the parameter belongs to.

    The following order of precedence is used to choose the single parameter value (from highest priority to lowest):
    1. The billingAddress block collected in the createPayment() request.
    2. The userDetails block collected in the createPayment() request.
  • Press this /openOrder link for the full list of 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"
}

The /openOrder request must be performed on your backend server because the checksum calculation includes your secret key. To prevent front-end user manipulation, never perform the /openOrder request on the frontend, because your secret key should NOT be exposed on the client-side.

You can simulate running the /openOrder request in our Postman test environment.
For your convenience, we have prepared sample Postman requests this Postman collection file.
Press the link to download the file, and then import the collection into your local Postman instance.
For steps to set up our Postman test environment locally and import Postman collections, see the Testing APIs with Postman topic.

POST is used for all Nuvei REST API methods that involve a transfer of data from client to server.

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.