• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
  • Payment Overview
    • Introduction
    • Choosing an Integration Method
  • Accept Payment
    • Payment Page
      • Quick Start
      • Input Parameters
      • Output Parameters
    • Web SDK
      • Quick Start
      • Nuvei Fields
        • Styling
      • Additional Functions
      • APM Payments
      • Tokenization-Only Flow
      • Scenarios
      • Using ReactJS
        • Full Samples
        • Sandbox Examples
      • FAQs
    • Checkout
      • Quick Start
        • UI Customization
        • Payment Customization
        • Advanced Controls
        • Checkout Examples
      • Server-to-Server
      • Payment Scenarios
      • Mobile SDKs (Beta Release)
        • Android Mobile SDK (Beta Release)
        • iOS Mobile SDK (Beta Release)
      • Flow Diagrams
      • Plugins
        • Magento
          • Rebilling with Magento
        • WooCommerce
          • Rebilling with WooCommerce
        • PrestaShop
          • PrestaShop with Web SDK
          • PrestaShop with Checkout
        • OpenCart
        • Shopify (via AsiaBill)
        • Mirakl
        • Salesforce
        • SAP
        • WIX
      • Marketplaces
    • Features
      • Authentication
      • Financial Operations
        • Refund
        • Void
        • Auth and Settle
        • Partial Approval
        • Currency Conversion (DCC and MCP)
        • Payout
      • Card Operations
        • Card-on-File
        • PCI and Tokenization
        • Zero-Authorization
        • Merchant-Initiated Transactions (MIT)
        • Blocking Cards
      • Subscription (Rebilling)
      • 3D-Secure
        • 3D-Secure Explained
        • 3DS Implementations
          • 3DS MPI-Only Web SDK
          • 3DS MPI-Only REST
          • 3DS External MPI
          • 3DS Responses
        • 3DS Functions
          • 3D-Secure Fingerprinting
          • 3D-Secure Authentication Challenge
      • Webhooks (DMNs)
        • Payment Transaction Requests
        • Control Panel Events API
    • Guides
      • Testing Cards, APIs and APMs
        • Testing Cards
        • Testing APIs with Postman
        • Testing APMs
      • Response Handling
      • Alternative Payment Guides (APMs)
      • Airline Ticket Guides
        • Airline Addendum
        • External Authorization Addendum
      • Payment Facilitators (PayFac)
      • Cashier
        • Cashier Events Guide
        • Cashier Features
      • Withdrawal Guide
      • Risk Guide
        • Nuvei Services
        • Transaction Types
        • Credits and Payouts
        • Fraud to Sale Programs
        • Compliance Programs
        • Chargebacks
      • eKYC Guide
      • Server SDKs
        • Java SDK
        • .NET SDK
        • PHP SDK
        • Node.JS SDK
      • Fast Track Onboarding Developer Guide
      • Currency Conversion Guides
        • Multiple Currency Pricing (MCP)
        • Dynamic Currency Conversion (DCC)
          • DCC in Cashier or Payment Page
          • DCC in REST API Workflows
          • DCC in Web SDK Workflows
      • Website Compliance Guides
    • Additional Links
      • FAQs
      • API Reference
      • Release Notes
      • Country and Currency Codes

    APM Payments

    On this page:
    • Overview
    • 1. Initiate a Session
    • 2. Initialize the Web SDK
    • 3. Get APM Details (optional)
    • 4. Create an APM Payment
    • 5. Redirect to the APM
    • 6. Verifying the Response

    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.

    2022 Nuvei. All rights reserved.