1. Generate a sessionToken

Press here for details.

2. APM Payment Form

Retrieve a list of supported APMs and banks by sending a /getMerchantPaymentMethods API request with its mandatory parameters including:

• currencyCode for a supported currency
• countryCode for a supported country

Example /getMerchantPaymentMethods Request

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "currencyCode":"AED",
  "countryCode":"AE",
  "type":"DEPOSIT",
  "languageCode":"en",
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

The response provides information about each APM supported by the merchant’s Nuvei account in the specified countryCode, including a fields array.

fields Array Structure in Response

"fields"[
  "name" (String, 45),
  "type" (String, 45),
  "validationMessage" 
    ["language" (String, 2), "message" (String, 400)],
  "caption" 
    ["language" (String, 2), "message" (String, 400)],
  "listValues" [
    "code" (String, 255),
    "caption" (String),
    "mandatoryFields" 
      [(String, 45)]
  ]
]

Response Output Parameters

Example Information for Lean in Response

{
  "paymentMethod": "apmgw_Lean",
  "paymentMethodDisplayName": [
    {
      "language": "en",
      "message": "Instant Bank Transfer"
    }
  ],
  "isDirect": "false",
  "countries": [
    "AE"
  ],
  "currencies": [
    "AED"
  ],
  "logoURL": "https://secure.safecharge.com/ppp/resources/img/svg/solid-white/open_banking.svg",
  "fields": [
    {
      "name": "BankCode",
      "type": "text",
      "caption": [
        {
          "language": "en",
          "message": "Bank"
        }
      ],
      "listValues": [
        {
          "code": "MASHREQ_NEO_UAE",
          "caption": "Mashreq Neo Bank",
          "mandatoryFields": []
        },
        {
          "code": "ADIB_UAE",
          "caption": "Abu Dhabi Islamic Bank",
          "mandatoryFields": []
        },
        {
          "code": "ENBD_UAE",
          "caption": "Emirates NBD",
          "mandatoryFields": []
        }
      ]
    }
  ],
  "openInExternalBrowser": "false"
}

Present the user a payment form containing the list of these APMs. For each APM, use the paymentMethodDisplayName.message for the relevant language and the logoURL.

After the user selects Instant Bank Transfer, present a list of the banks using their listValues.caption values, and a Register button. After the user selects a bank, if there are any mandatoryFields for that bank, collect the mandatory information from the user.

3. Register the User

When the user presses Register, send a zero-amount /payment registration request with its mandatory parameters including:

• userTokenId
• currency for a supported currency
• amount: “0“
• paymentOption.alternativePaymentMethod class containing:
  • paymentMethod: “apmgw_Lean“
  • BankCode – code for the bank selected
• billingAddress block containing: email, country

Example /payment Request – Registration

{
    "sessionToken": "<sessionToken from /getSessionToken>",
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "userTokenId": "<unique customer identifier in merchant system>",
    "paymentOption": {
        "alternativePaymentMethod": {
            "paymentMethod": "apmgw_Lean",
            "BankCode": "MASHREQ_NEO_UAE"
        }
    },
    "currency": "AED",
    "amount": "0",
    "billingAddress": {
        "email": "[email protected]",
        "country": "AE"
    },
    "urlDetails":{
        "successUrl": "<URL to which the customer is directed when registration succeeds>",
        "failureUrl": "<URL to which the customer is directed when registration fails>",
        "pendingUrl": "<URL to which the customer is directed when registration is pending>"
    },
    "timeStamp": "<YYYYMMDDHHmmss>",
    "checksum": "<calculated checksum>"
}

A successful /payment registration request generates a response that includes:

• redirectUrl – Redirect the user to this URL to connect a bank account.
• userPaymentOptionId – Use in the subsequent /payment request and in other future transactions.

Example /payment Response – Registration

{
  "internalRequestId": 43961551,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "5634436935940029474",
  "merchantSiteId": "242181",
  "version": "1.0",
  "sessionToken": "110c619c-496d-46da-aa9e-0353d595848f",
  "orderId": "43706751",
  "userTokenId": "Mirel244",
  "paymentOption": {
    "redirectUrl": "https://apmtest.gate2shop.com/ppp/resources/cdn/v1/bank-details-30606.html?customerId=5ecb495f-fb19-4088-b037-c6f23e729f16&appToken=02289950-27ff-4b4e-99e9-34024b1e23f6&accessToken=eyJraWQiOiI5NTk4MmMyYi1iOGMxLTQ2YTItOWVhNi1iOTFlZjRiZGQxYzMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIwMjI4OTk1MC0yN2ZmLTRiNGUtOTllOS0zNDAyNGIxZTIzZjYiLCJhdWQiOiIwMjI4OTk1MC0yN2ZmLTRiNGUtOTllOS0zNDAyNGIxZTIzZjYiLCJuYmYiOjE3Mjk2OTUxOTEsInNjb3BlIjpbImN1c3RvbWVyLnJlYWQiLCJiZW5lZmljaWFyeS53cml0ZSIsInBheW1lbnQud3JpdGUiLCJwYXltZW50LnJlYWQiLCJkZXN0aW5hdGlvbi5yZWFkIiwiY29ubmVjdC53cml0ZSIsImNvbm5lY3QucmVhZCIsImFwcGxpY2F0aW9uLnJlYWQiLCJiYW5rLnJlYWQiLCJrZXkucmVhZCJdLCJpc3MiOiJodHRwczovL2F1dGguc2FuZGJveC5sZWFudGVjaC5tZSIsImN1c3RvbWVycyI6W3siaWQiOiI1ZWNiNDk1Zi1mYjE5LTQwODgtYjAzNy1jNmYyM2U3MjlmMTYifV0sImV4cCI6MTcyOTY5ODc5MSwiaWF0IjoxNzI5Njk1MTkxLCJqdGkiOiIxNTMxM2U1MS0xNmIwLTQ4ZTYtYjhiMi00ZTEwYzllOGY4YWMiLCJhcHBsaWNhdGlvbnMiOlt7ImlkIjoiMDIyODk5NTAtMjdmZi00YjRlLTk5ZTktMzQwMjRiMWUyM2Y2In1dfQ.YdVWsvxYZCcsYe7cQvMPfjmvyDbXCJClFRVyLXVU6TDihoqty6ELVRvEARmCmvvhGhHfSCdlu0bxlk_q37Phq5oQQoXHj0TO1zbA4pVbMSWy5E8C1CMm1353hKZY4VkL0vWC9c9utXKO0KhpywMCYh759d_sIC2eVL_36uUEkcGHZuOPWBvfmr_z55YgQrc_-miij3Sa15BkbA42fSnZ_ocH-P9Ykk1pSA7t-mlG0Ncc-xKngNUQ6NJlNXWDqm2IipRXYRr1IgxeXPX7QsV0-QX2MlPj8gcPcT1I0-3UyDi2HDvmoJhAava58ZIR_JEnyt3eGBi5-WOzI1rahPsM1Q&bankIdentifier=LEANMB2_SAU&returnUrl=https%3A%2f%2fk8s-tlv-cl0-qa1.gw-4u.com%2fapm%2flean%2fv1%2fconsumerReturn%2f50623ED0D37CA9080A8B42BB8738EA56&mode=connect",
    "userPaymentOptionId": "2153484251",
    "card": {}
  },
  "transactionStatus": "REDIRECT"
}

After the APM provider processes the /payment registration request, Nuvei sends a Direct Merchant Notification (DMN) to urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.

Example /payment DMN – Registration

...'ppp_status=PENDING&Status=UPDATE&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43706751&userid=Mirel244&merchant_unique_id=&customData=&productId=&first_name=&last_name=&email=john.smith%40email.com&currency=AED&pmDisplayName=AE140497772174758429187&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=United+Arab+Emirates&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Lean-DMCC-Direct&expMonth=&expYear=&Token=&tokenId=&AuthCode=LEANMB2_SAU&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=242181&merchant_status=&action=&requestVersion=&message=UPDATE&merchantLocale=&unknownParameters=&payment_method=apmgw_Lean&ID=&merchant_id=5634436935940029474&responseTimeStamp=2024-09-09.12%3A21%3A47&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Mirel244&userPaymentOptionId=2153401501&TransactionID=2610000000000059040&externalTransactionId=ee62f4d8-31a6-4700-a229-a2dda7255ded_LEANMB2_SAU&APMReferenceID=3754B4A56A80293813FC8A49222C4B48&orderTransactionId=24970601&totalAmount=0.00&dynamicDescriptor=static+test&item_name_1=NA&item_number_1=&item_amount_1=0.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&externalToken_blockedCard=&externalToken_cardAcquirerId=&externalToken_cardAcquirerName=&externalToken_cardBin=&externalToken_cardBrandId=&externalToken_cardBrandName=&externalToken_cardExpiration=&externalToken_cardLength=&externalToken_cardMask=&externalToken_cardName=&externalToken_cardTypeId=&externalToken_cardTypeName=&externalToken_clubName=&externalToken_creditCompanyId=&externalToken_creditCompanyName=&externalToken_extendedCardType=&externalToken_Indication=&externalToken_tokenValue=&externalToken_tokenProvider=&ECIRaw=&cryptogram=&maskedNetworkTokenNumber=&upoRegistrationDate=20240909&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=%5B%5D&sessionId=6b49e9b97ed9939377bfce8ac6d9&responsechecksum=a27c5c933a19f30453b7cc2b751945b9&advanceResponseChecksum=71f34029c292df100a928c9e8782f7bb',

4. Send a Payment Request

Some banks require a 24-hour waiting period during which the user payment option (UPO) is not yet active, and the user cannot make payments with it.

After the UPO becomes active and the user selects it to make a payment, send a second /payment request with its mandatory parameters including:

• userTokenId
• currency
• amount
• paymentOption.alternativePaymentMethod class containing:
  • userPaymentOptionId: userPaymentOptionId from the response to the registration request
  • paymentMethod: “apmgw_Lean“
• billingAddress block containing: email, country

Example /payment Request – Payment

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "paymentOption": {
    "userPaymentOptionId": "<userPaymentOptionId from registration request>",
    "alternativePaymentMethod": {
      "paymentMethod": "apmgw_Lean"
    }
  },
  "currency": "AED",
  "amount": "40",
  "billingAddress": {
    "email": "[email protected]",
    "country": "AE"
  },
  "urlDetails":{
    "successUrl": "<URL to which the customer is directed when the payment request succeeds>",
    "failureUrl": "<URL to which the customer is directed when the payment request fails>",
    "pendingUrl": "<URL to which the customer is directed when the payment request is pending>"
 },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

A successful /payment payment request generates a response that includes a redirectUrl.

Example /payment Response – Payment

{
  "internalRequestId": 44033351,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "5634436935940029474",
  "merchantSiteId": "242181",
  "version": "1.0",
  "sessionToken": "e92586d3-f36b-425a-b651-4c4679eb1d6a",
  "orderId": "43717971",
  "userTokenId": "Mirel246",
  "paymentOption": {
    "redirectUrl": "https://apmtest.gate2shop.com/ppp/resources/cdn/v1/bank-details-30606.html?paymentIntentId=f974a691-7957-431b-bf77-3e306fc28b68&appToken=02289950-27ff-4b4e-99e9-34024b1e23f6&accessToken=eyJraWQiOiI2ZTI2MzcxYy04NDEyLTRjZWQtOTRjNi05NDhkZWIyY2I5ODYiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIwMjI4OTk1MC0yN2ZmLTRiNGUtOTllOS0zNDAyNGIxZTIzZjYiLCJhdWQiOiIwMjI4OTk1MC0yN2ZmLTRiNGUtOTllOS0zNDAyNGIxZTIzZjYiLCJuYmYiOjE3MjYwNDQzOTMsInNjb3BlIjpbImN1c3RvbWVyLnJlYWQiLCJiZW5lZmljaWFyeS53cml0ZSIsInBheW1lbnQud3JpdGUiLCJwYXltZW50LnJlYWQiLCJkZXN0aW5hdGlvbi5yZWFkIiwiY29ubmVjdC53cml0ZSIsImNvbm5lY3QucmVhZCIsImFwcGxpY2F0aW9uLnJlYWQiLCJiYW5rLnJlYWQiLCJrZXkucmVhZCJdLCJpc3MiOiJodHRwczovL2F1dGguc2FuZGJveC5sZWFudGVjaC5tZSIsImN1c3RvbWVycyI6W3siaWQiOiJhNDA1MGRmNy01MjY0LTQyNmMtOTcxZC1mMTE0ZmM3ZDY4MGUifV0sImV4cCI6MTcyNjA0Nzk5MywiaWF0IjoxNzI2MDQ0MzkzLCJqdGkiOiIzOTAyMzFkOS1iNzViLTRlYmItOGM5YS1iMjIwMzkzZDVmNTEiLCJhcHBsaWNhdGlvbnMiOlt7ImlkIjoiMDIyODk5NTAtMjdmZi00YjRlLTk5ZTktMzQwMjRiMWUyM2Y2In1dfQ.YdjIJxeiz4JvXq1wmcI6r6NwDhFBF3I7MkEYHJtYGu1BhRiFAvP28dsJQ7MU6RtQig6zDsJPHjkedQqMkpA4lKwrlkWDOAc8TKSJiDk0f7CNiQsujueQaImJmHfm1_h0J9i10-i7wjpP4de9gclKKUS6K7ycu6K9-eY1SZLEiA0GuMe0oEkCnq9tHcbDmr-xtFJKSk7GyGtI5TMkWllvvg-AaAbQ7E85BIyEm7g9Eshqq555FdrOafh9YsxwB5HHYPxVqrbqAYBMQeV7hclLF1JUb0EYjKQrYl8jZaA_5_OesKEyIyy6STdFwfWyCxk9z3a2N7t-VsnmOpNOkoNdrg&accountId=c3705696-911e-4b43-a28e-255b3800c436&returnUrl=https%3A%2F%2Fk8s-tlv-cl0-qa1.gw-4u.com%2Fapm%2Flean%2Fv1%2FconsumerReturn%2F04F5B4773991B01ECF4C973A92D25A6E&mode=pay",
    "userPaymentOptionId": "2153401581",
    "card": {}
  },
  "transactionStatus": "REDIRECT"
}

Redirect the user to redirectUrl to complete the payment.

1. Initiate a Session

Send a zero-amount /openOrder server-side API request with its mandatory parameters including:

• userTokenId
• currency for a supported currency
• amount: “0“

Example Zero-Amount /openOrder Request

{  
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "userTokenId": "<unique customer identifier in merchant system>",
    "clientUniqueId": "<unique transaction ID in merchant system>",
    "clientRequestId": "<unique request ID in merchant system>",
    "currency": "AED",
    "amount": "0",
    "urlDetails":{
      "successUrl": "<URL to which the customer is directed when registration succeeds>",
      "failureUrl": "<URL to which the customer is directed when registration fails>",
      "pendingUrl": "<URL to which the customer is directed when registration is pending>"
     },
    "timeStamp": "<YYYYMMDDHHmmss>",
    "checksum": "<calculated checksum>"
}

The response includes a sessionToken.

Example /openOrder Response

{
  "sessionToken": "25419355-444e-46fa-9b46-5a8e5a6e001e",
  "orderId": "43711571",
  "merchantId": "5634436935940029474",
  "merchantSiteId": "242181",
  "clientUniqueId": "12345",
  "clientRequestId": "1484759782197",
  "internalRequestId": 43996241,
  "status": "SUCCESS",
  "userTokenId": "Mirel255",
  "errCode": 0,
  "reason": "",
  "version": "1.0"
}

2. Initialize the Web SDK

Use the sessionToken from the /openOrder registration response to instantiate the Nuvei Web SDK.

3. Get APM Details

Retrieve a list of supported APMs and banks by sending a getAPMs() Web SDK request including:

• currencyCode for a supported currency
• countryCode for a supported country

Example getApms() Request

sfc.getApms({
  "countryCode": "AE",
  "currencyCode": "AED", 
  "languageCode": "en"
  }, 

function (res) {
  console.log(res)
})

The response provides information about each APM supported by the merchant’s Nuvei account in the specified countryCode, including a fields array.

fields Array Structure in Response

"fields"[
  "name" (String, 45),
  "type" (String, 45),
  "validationMessage" 
    ["language" (String, 2), "message" (String, 400)],
  "caption" 
    ["language" (String, 2), "message" (String, 400)],
  "listValues" [
    "code" (String, 255),
    "caption" (String),
    "mandatoryFields" 
      [(String, 45)]
  ]
]

Response Output Parameters

Example Information for Lean in Response

{
  "paymentMethod": "apmgw_Lean",
  "paymentMethodDisplayName": [
    {
      "language": "en",
      "message": "Instant Bank Transfer"
    }
  ],
  "isDirect": "false",
  "countries": [
    "AE"
  ],
  "currencies": [
    "AED"
  ],
  "logoURL": "https://secure.safecharge.com/ppp/resources/img/svg/solid-white/open_banking.svg",
  "fields": [
    {
      "name": "BankCode",
      "type": "text",
      "caption": [
        {
          "language": "en",
          "message": "Bank"
        }
      ],
      "listValues": [
        {
          "code": "MASHREQ_NEO_UAE",
          "caption": "Mashreq Neo Bank",
          "mandatoryFields": []
        },
        {
          "code": "ADIB_UAE",
          "caption": "Abu Dhabi Islamic Bank",
          "mandatoryFields": []
        },
        {
          "code": "ENBD_UAE",
          "caption": "Emirates NBD",
          "mandatoryFields": []
        }
      ]
    }
  ],
  "openInExternalBrowser": "false"
}

Present the user a payment form containing the list of these APMs. For each APM, use the paymentMethodDisplayName.message for the relevant language and the logoURL.

After the user selects Instant Bank Transfer, present a list of the banks using their listValues.caption values, and a Register button. After the user selects a bank, if there are any mandatoryFields for that bank, collect the mandatory information from the user.

4. Register the User

When the user presses Register, send a createPayment() Web SDK request with its mandatory parameters including:

• userTokenId
• paymentOption.alternativePaymentMethod block containing:
  • paymentMethod: “apmgw_Lean“
  • BankCode – code for the bank selected
• billingAddress block containing: email, country

Example createPayment() Request – Registration

sfc.createPayment({
  sessionToken: "<sessionToken from /openOrder>",
  userTokenId: "<unique customer identifier in merchant system>",
  paymentOption: {
    alternativePaymentMethod: {
      paymentMethod: "apmgw_Lean",
      BankCode: "MASHREQ_NEO_UAE"
    }
  },
  billingAddress: {
    email: "[email protected]",
    country: "AE"
  },
}, function(res) {
  console.log(res);
});

The user is automatically redirected to the APM provider to set up an account.

5. Verify the Response

Because Nuvei sends the createPayment() response to the client side, it is vulnerable to manipulation by the end user. The merchant needs to verify the response on the server side. Press here for details.

For example, after the provider processes the createPayment() registration request, Nuvei sends a Direct Merchant Notification (DMN) to urlDetails.notificationUrl, which Nuvei recommends including in the createPayment() request. The DMN includes the userPaymentOptionId to use in a subsequent createPayment() request and in other future transactions.

Example createPayment() DMN – Registration

...'ppp_status=PENDING&Status=UPDATE&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43706751&userid=Mirel244&merchant_unique_id=&customData=&productId=&first_name=&last_name=&email=john.smith%40email.com&currency=AED&pmDisplayName=AE140497772174758429187&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=United+Arab+Emirates&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Lean-DMCC-Direct&expMonth=&expYear=&Token=&tokenId=&AuthCode=LEANMB2_SAU&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=242181&merchant_status=&action=&requestVersion=&message=UPDATE&merchantLocale=&unknownParameters=&payment_method=apmgw_Lean&ID=&merchant_id=5634436935940029474&responseTimeStamp=2024-09-09.12%3A21%3A47&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Mirel244&userPaymentOptionId=2153401501&TransactionID=2610000000000059040&externalTransactionId=ee62f4d8-31a6-4700-a229-a2dda7255ded_LEANMB2_SAU&APMReferenceID=3754B4A56A80293813FC8A49222C4B48&orderTransactionId=24970601&totalAmount=0.00&dynamicDescriptor=static+test&item_name_1=NA&item_number_1=&item_amount_1=0.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&externalToken_blockedCard=&externalToken_cardAcquirerId=&externalToken_cardAcquirerName=&externalToken_cardBin=&externalToken_cardBrandId=&externalToken_cardBrandName=&externalToken_cardExpiration=&externalToken_cardLength=&externalToken_cardMask=&externalToken_cardName=&externalToken_cardTypeId=&externalToken_cardTypeName=&externalToken_clubName=&externalToken_creditCompanyId=&externalToken_creditCompanyName=&externalToken_extendedCardType=&externalToken_Indication=&externalToken_tokenValue=&externalToken_tokenProvider=&ECIRaw=&cryptogram=&maskedNetworkTokenNumber=&upoRegistrationDate=20240909&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=%5B%5D&sessionId=6b49e9b97ed9939377bfce8ac6d9&responsechecksum=a27c5c933a19f30453b7cc2b751945b9&advanceResponseChecksum=71f34029c292df100a928c9e8782f7bb',

Some banks require a 24-hour waiting period during which the user payment option (UPO) is not yet active, and the user cannot make payments with it.

5. Initiate a New Session

After the UPO becomes active and the user selects it to make a payment, send an /openOrder API request with its mandatory parameters including:

• userTokenId
• currency for a supported currency
• amount

Example /openOrder Request

{
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "currency": "AED",
  "amount": "40",
  "urlDetails":{
    "successUrl": "<URL to which the customer is directed when payment succeeds>",
    "failureUrl": "<URL to which the customer is directed when payment fails>",
    "pendingUrl": "<URL to which the customer is directed when payment is pending>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

The response includes a sessionToken.

Example /openOrder Response

{
  "sessionToken": "b9b918c5-3c1e-41b1-8e40-35f534270eb6",
  "orderId": "43718431",
  "merchantId": "5634436935940029474",
  "merchantSiteId": "242181"
  "internalRequestId": 44034981,
  "status": "SUCCESS",
  "userTokenId": "Mirel246",
  "errCode": 0,
  "version": "1.0"
}

6. Initialize the Web SDK

Use the sessionToken in the /openOrder response to instantiate the Nuvei Web SDK.

7. Create an APM Payment

Send a second createPayment() Web SDK request with its mandatory parameters including:

• userTokenId
• paymentOption.userPaymentOptionId – userPaymentOptionId from the createPayment() registration DMN
• paymentOption.alternativePaymentMethod block containing:
  • paymentMethod: “apmgw_Lean“
• billingAddress block containing: email, country

Example createPayment() Request – Payment

sfc.createPayment({
  sessionToken: "<sessionToken from /openOrder>",
  userTokenId: "<unique customer identifier in merchant system>",
  paymentOption: {
    userPaymentOptionId: "<UPO ID from registration DMN>",
    alternativePaymentMethod: {
      paymentMethod: "apmgw_Lean"
    }
  },
  billingAddress: {
    email: "[email protected]",
    country: "AE"
  },
}, function(res) {
  console.log(res);
});

The user is automatically redirected to the APM provider to complete the payment.

5. Verify the Response

Press here for details.

1. Initiate a Session

Send a zero-amount /openOrder server-side API request with its mandatory parameters including:

• userTokenId
• currency for a supported currency
• amount: “0“

Example Zero-Amount /openOrder Request

{  
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "userTokenId": "<unique customer identifier in merchant system>",
    "clientUniqueId": "<unique transaction ID in merchant system>",
    "currency": "AED",
    "amount": "0",
    "urlDetails":{
      "successUrl": "<URL to which the customer is directed when registration succeeds>",
      "failureUrl": "<URL to which the customer is directed when registration fails>",
      "pendingUrl": "<URL to which the customer is directed when registration is pending>"
    },
    "timeStamp": "<YYYYMMDDHHmmss>",
    "checksum": "<calculated checksum>"
}

The response includes a sessionToken.

Example /openOrder Response

{
  "sessionToken": "8d0408ca-84bb-4d48-900a-e8745853c417",
  "orderId": "43713271",
  "merchantId": "5634436935940029474",
  "merchantSiteId": "242181",
  "clientUniqueId": "sdf234wdsf",
  "clientRequestId": "1484759782197",
  "internalRequestId": 43996241,
  "status": "SUCCESS",
  "userTokenId": "Mirel258",
  "errCode": 0,
  "reason": "",
  "version": "1.0"
}

2. Create an HTML Placeholder

Press here for details.

3. Register the User

When the user presses Register, send a zero-amount checkout() Web SDK request with its mandatory parameters including:

• country for a supported country
• currency for a supported currency
• amount: “0“
• billingAddress block containing: email, country

Example checkout() Request – Registration

document.getElementById('checkout').innerHTML = "";
checkout({
  sessionToken: document.getElementById('session').value,
  env: 'int', // Nuvei API environment – 'int' (integration) or 'prod' (production – default if omitted)
  merchantSiteId: '<your merchantSiteId>',
  merchantId: '<your merchantId>',
  country: 'AE',
  currency: 'AED',
  amount: 0,
  billingAddress: {
    email: "[email protected]",
    country: "AE"
  },
  renderTo: '#checkout',
  onResult: function(result) {
    console.log("Result", result);
  }
});

The user is automatically redirected to the APM provider to set up an account.

4. Verify the Response

Because Nuvei sends the checkout() response to the client side, it is vulnerable to manipulation by the end user. The merchant needs to verify the response on the server side. Press here for details.

For example, after the provider processes the checkout() registration request, Nuvei sends a Direct Merchant Notification (DMN) to urlDetails.notificationUrl, which Nuvei recommends including in the checkout() request. The DMN includes the userPaymentOptionId to use in a subsequent checkout() request and in other future transactions.

Example checkout() DMN – Registration

...'ppp_status=PENDING&Status=UPDATE&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43706751&userid=Mirel244&merchant_unique_id=&customData=&productId=&first_name=&last_name=&email=john.smith%40email.com&currency=AED&pmDisplayName=AE140497772174758429187&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=United+Arab+Emirates&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Lean-DMCC-Direct&expMonth=&expYear=&Token=&tokenId=&AuthCode=LEANMB2_SAU&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=242181&merchant_status=&action=&requestVersion=&message=UPDATE&merchantLocale=&unknownParameters=&payment_method=apmgw_Lean&ID=&merchant_id=5634436935940029474&responseTimeStamp=2024-09-09.12%3A21%3A47&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Mirel244&userPaymentOptionId=2153401501&TransactionID=2610000000000059040&externalTransactionId=ee62f4d8-31a6-4700-a229-a2dda7255ded_LEANMB2_SAU&APMReferenceID=3754B4A56A80293813FC8A49222C4B48&orderTransactionId=24970601&totalAmount=0.00&dynamicDescriptor=static+test&item_name_1=NA&item_number_1=&item_amount_1=0.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&externalToken_blockedCard=&externalToken_cardAcquirerId=&externalToken_cardAcquirerName=&externalToken_cardBin=&externalToken_cardBrandId=&externalToken_cardBrandName=&externalToken_cardExpiration=&externalToken_cardLength=&externalToken_cardMask=&externalToken_cardName=&externalToken_cardTypeId=&externalToken_cardTypeName=&externalToken_clubName=&externalToken_creditCompanyId=&externalToken_creditCompanyName=&externalToken_extendedCardType=&externalToken_Indication=&externalToken_tokenValue=&externalToken_tokenProvider=&ECIRaw=&cryptogram=&maskedNetworkTokenNumber=&upoRegistrationDate=20240909&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=%5B%5D&sessionId=6b49e9b97ed9939377bfce8ac6d9&responsechecksum=a27c5c933a19f30453b7cc2b751945b9&advanceResponseChecksum=71f34029c292df100a928c9e8782f7bb',

Some banks require a 24-hour waiting period during which the registered payment method is not yet active, and the user cannot make payments with it.

5. Initiate a New Session

After the UPO becomes active, send an /openOrder API request with its mandatory parameters including:

• userTokenId
• currency for a supported currency
• amount
• paymentOption.userPaymentOptionId – userPaymentOptionId from the checkout() registration DMN

Example /openOrder Request – Payment

{
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "currency": "AED",
  "amount": "40",
  "paymentOption": {
    "userPaymentOptionId": "<UPO ID from registration DMN>"
  },
  "urlDetails":{
    "successUrl": "<URL to which the customer is directed when payment succeeds>",
    "failureUrl": "<URL to which the customer is directed when payment fails>",
    "pendingUrl": "<URL to which the customer is directed when payment is pending>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

The response includes a sessionToken.

Example /openOrder Response – Payment

{
  "sessionToken": "71f54e19-2064-46f5-964e-a496802e47dc",
  "orderId": "43718921",
  "merchantId": "5634436935940029474",
  "merchantSiteId": "242181",
  "clientUniqueId": "sdf234wdsf",
  "internalRequestId": 44036391,
  "status": "SUCCESS",
  "userTokenId": "Mirel246",
  "errCode": 0,
  "reason": "",
  "version": "1.0"
}

6. Create an HTML Placeholder

Press here for details.

7. Perform a checkout() Payment

Send a second checkout() Web SDK request with its mandatory parameters including:

• country for a supported country
• currency for a supported currency
• amount
• billingAddress block containing: email, country

For information about other checkout() input parameters that allow the merchant to customize the UI/UX/payment processing, see Customizing UI/UX/Processing.

Example Simple checkout() Request

document.getElementById('checkout').innerHTML = "";
checkout({
  sessionToken: document.getElementById('session').value,
  env: 'int', // Nuvei API environment – 'int' (integration) or 'prod' (production – default if omitted)
  merchantSiteId: '<your merchantSiteId>',
  merchantId: '<your merchantId>',
  country: 'AE',
  currency: 'AED',
  amount: 40,
  billingAddress: {
    email: "[email protected]",
    country: "AE"
  },
  renderTo: '#checkout',
  onResult: function(result) {
    console.log("Result", result);
  }
});

On the checkout page, the registered payment method appears under SELECT YOUR PAYMENT METHOD. Certain banks require a 24-hour waiting period during which the payment method appears, but is disabled.

8. Verify the Response

Press here for details.