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 and include:

• 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 and include:

• 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 Registration Request

{
    "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 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 Registration Response

{
  "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 registration request, Nuvei sends a Direct Merchant Notification (DMN) to urlDetails.notificationUrl, which Nuvei recommends including in the registration request.

Example Registration DMN

...'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

{
  "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 request generates a response that includes a redirectUrl.

Example Payment Response

{
  "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 and include:

• 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"
}

After the zero-amount request is processed, Nuvei sends a Direct Merchant Notification (DMN) to urlDetails.notificationUrl, which Nuvei recommends including in the request.

Example Zero-Amount /openOrder DMN

...'ppp_status=PENDING&Status=UPDATE&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43711571&userid=Mirel255&merchant_unique_id=&customData=&productId=&first_name=John&last_name=Smith&email=john.smith%40email.com&currency=AED&pmDisplayName=AE320294235618240538913&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=123+test+str&address2=&country=United+Arab+Emirates&state=&city=Dubai&zip=12345&phone1=971553056671&phone2=&phone3=&client_ip=128.127.116.34&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-10.08%3A33%3A10&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Mirel255&userPaymentOptionId=2153403321&TransactionID=2610000000000059287&externalTransactionId=ca386b32-8dd0-41e4-a80b-9f530d310d88_LEANMB2_SAU&APMReferenceID=104656CA4701E3368EB46A0AC1791225&orderTransactionId=24973901&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=20240910&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=%5B%5D&sessionId=b1027b479013aa42f6edc2002d4a&responsechecksum=bd86d151b2f514b3e56a27140c830988&advanceResponseChecksum=c3170dd8e2728a5816d2db23f997481e',

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 and include:

• 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 and include:

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

Example Registration Request

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

Press here for details.

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

Example Registration DMN

...'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 and include:

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

Example Payment Request

sfc.createPayment({
  sessionToken: "<sessionToken from /openOrder>",
  userTokenId: "<unique customer identifier in merchant system>",
  paymentOption: {
    userPaymentOptionId: "<UPO ID from the response to the registration request>",
    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 and include:

• 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"
}

After the zero-amount /openOrder request is processed, Nuvei sends a Direct Merchant Notification (DMN) to urlDetails.notificationUrl, which Nuvei recommends including in the request.

Example Zero-Amount /openOrder DMN

...'ppp_status=PENDING&Status=UPDATE&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43713271&userid=Mirel258&merchant_unique_id=sdf234wdsf&customData=&productId=&first_name=John&last_name=Smith&email=john.smith%40email.com&currency=AED&pmDisplayName=AE320294235618240538913&clientUniqueId=sdf234wdsf&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=123+test&address2=&country=United-Arab-Emirates&state=&city=Dubai&zip=12345&phone1=971553056671&phone2=&phone3=&client_ip=128.127.116.34&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Lean-DMCC-Direct&expMonth=&expYear=&Token=&tokenId=&AuthCode=LEANMB2_SAU&AvsCode=&Cvv2Reply=&shippingCountry=UAE&shippingState=&shippingCity=iasi&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-10.11%3A21%3A51&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Mirel258&userPaymentOptionId=2153403751&TransactionID=2610000000000059344&externalTransactionId=5658223e-550d-4d2a-b444-8493ca826c20_LEANMB2_SAU&APMReferenceID=C5F9EF1C2B97E01625364F3BD7EEE69F&orderTransactionId=24974621&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=20240910&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=%5B%5D&sessionId=baa2175add4cf2f140cdb851356d&responsechecksum=af3dd6f69d58730438dd03e0b533abf6&advanceResponseChecksum=4e33578216027d767a6dc2848e44cc68',

2. Create an HTML Placeholder

Press here for details.

3. Register the User

Send a zero-amount checkout() Web SDK request with its mandatory parameters and include:

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

Example Registration 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: 0,
  email: '[email protected]',
  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

Press here for details.

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

Example Registration DMN

...'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 registration response

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",
  "paymentOption": {
    "userPaymentOptionId": "<UPO ID from the response to the registration request>"
  },
  "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": "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 and include:

• 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,
  email: '[email protected]',
  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.

Example checkout() Response

{
  "amount": "40",
  "bin": "",
  "cancelled": false,
  "ccCardNumber": "",
  "ccExpMonth": "",
  "ccExpYear": "",
  "clientUniqueId": "sdf234wdsf",
  "currency": "AED",
  "errCode": 0,
  "errorDescription": "",
  "internalRequestId": 44036481,
  "last4Digits": "",
  "merchantSiteId": "242181",
  "paymentOption": {
    "alternativePaymentMethod": "{ ... }",
    "card": "{ ... }",
    "userPaymentOptionId": "2153401591"
  },
  "result": "APPROVED",
  "sessionToken": "71f54e19-2064-46f5-964e-a496802e47dc",
  "status": "SUCCESS",
  "transactionId": "2610000000000059735",
  "transactionType": "Sale",
  "userPaymentOptionId": "2153401591",
  "version": "1.0"
}

8. Verify the Response

Press here for details.