- METHOD TYPEBank Transfer
- PAYMENTS
- PAYOUTS
- REFUNDS
- RECURRING
Introduction
Lean is an Open Banking-enabled provider that facilitates instant bank-to-bank transfers across financial institutions throughout the MENA region. It is regulated in the UAE by the Abu Dhabi Global Market (ADGM) Financial Services Regulatory Authority and is licensed under the SAMA Regulatory Sandbox by the Saudi Central Bank.
Supported Countries
- United Arab Emirates
Supported Currencies
- AED
Payment (Deposit) Flow
Press tab to open…
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 currencycountryCode
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
Parameter | Description | Examples |
---|---|---|
paymentMethod | paymentMethod value for APM. | apmgw_Lean |
paymentMethod.displayName | Array of text labels for the paymentMethod to use on the payment form. | - |
paymentMethod.displayName .language | Language code. | en |
paymentMethod.displayName .message | Text label. | Instant Bank Transfer |
paymentMethod.countries | Country codes the APM supports. | AE |
paymentMethod.currencies | Currency codes the APM supports. | AED |
paymentMethod.logoURL | URL for the paymentMethod logo to use on the payment form. | https://secure.safecharge.com /ppp/resources/img/svg/solid -white/open_banking.svg |
fields | Array of /payment or createPayment() input parameters for the APM. | - |
fields.name | Name of input parameter for /payment or createPayment() requests. | lean_bank |
fields.listValues | Array of valid values for field.name for a dropdown list the merchant presents to the user. | - |
fields.listValues .code | The value of the input parameter for /payment or createPayment() requests. | MASHREQ_NEO_UAE ADIB_UAE ENBD_UAE |
fields.listValues .caption | Text the merchant presents to the user in a dropdown list. | Mashreq Neo Bank Abu Dhabi Islamic Bank Emirates NBD |
fields.listValues .mandatoryFields | Array of fields required for /payment or createPayment() requests. | - |
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 currencyamount
: “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¤cy=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 requestpaymentMethod
: “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 currencyamount
: “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 currencycountryCode
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
Parameter | Description | Examples |
---|---|---|
paymentMethod | paymentMethod value for APM. | apmgw_Lean |
paymentMethod.displayName | Array of text labels for the paymentMethod to use on the payment form. | - |
paymentMethod.displayName .language | Language code. | en |
paymentMethod.displayName .message | Text label. | Instant Bank Transfer |
paymentMethod.countries | Country codes the APM supports. | AE |
paymentMethod.currencies | Currency codes the APM supports. | AED |
paymentMethod.logoURL | URL for the paymentMethod logo to use on the payment form. | https://secure.safecharge.com /ppp/resources/img/svg/solid -white/open_banking.svg |
fields | Array of /payment or createPayment() input parameters for the APM. | - |
fields.name | Name of input parameter for /payment or createPayment() requests. | lean_bank |
fields.listValues | Array of valid values for field.name for a dropdown list the merchant presents to the user. | - |
fields.listValues .code | The value of the input parameter for /payment or createPayment() requests. | MASHREQ_NEO_UAE ADIB_UAE ENBD_UAE |
fields.listValues .caption | Text the merchant presents to the user in a dropdown list. | Mashreq Neo Bank Abu Dhabi Islamic Bank Emirates NBD |
fields.listValues .mandatoryFields | Array of fields required for /payment or createPayment() requests. | - |
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¤cy=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 currencyamount
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 thecreatePayment()
registration DMNpaymentOption.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 currencyamount
: “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 countrycurrency
for a supported currencyamount
: “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¤cy=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 currencyamount
paymentOption.userPaymentOptionId
–userPaymentOptionId
from thecheckout()
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 countrycurrency
for a supported currencyamount
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.
- REST API
-
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 currencycountryCode
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 afields
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
Parameter Description Examples paymentMethod paymentMethod
value for APM.apmgw_Lean paymentMethod.displayName Array of text labels for the paymentMethod
to use on the payment form.- paymentMethod.displayName
.languageLanguage code. en paymentMethod.displayName
.messageText label. Instant Bank Transfer paymentMethod.countries Country codes the APM supports. AE paymentMethod.currencies Currency codes the APM supports. AED paymentMethod.logoURL URL for the paymentMethod
logo to use on the payment form.https://secure.safecharge.com
/ppp/resources/img/svg/solid
-white/open_banking.svgfields Array of /payment
orcreatePayment()
input parameters for the APM.- fields.name Name of input parameter for /payment
orcreatePayment()
requests.lean_bank fields.listValues Array of valid values for field.name
for a dropdown list the merchant presents to the user.- fields.listValues
.codeThe value of the input parameter for /payment
orcreatePayment()
requests.MASHREQ_NEO_UAE
ADIB_UAE
ENBD_UAEfields.listValues
.captionText the merchant presents to the user in a dropdown list. Mashreq Neo Bank
Abu Dhabi Islamic Bank
Emirates NBDfields.listValues
.mandatoryFieldsArray of fields required for /payment
orcreatePayment()
requests.- 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 thelogoURL
.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 anymandatoryFields
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 currencyamount
: “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) tourlDetails.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¤cy=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 requestpaymentMethod
: “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 aredirectUrl
.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. - Web SDK
-
1. Initiate a Session
Send a zero-amount
/openOrder
server-side API request with its mandatory parameters including:userTokenId
currency
for a supported currencyamount
: “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 currencycountryCode
for a supported country
Example
getApms()
Requestsfc.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 afields
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
Parameter Description Examples paymentMethod paymentMethod
value for APM.apmgw_Lean paymentMethod.displayName Array of text labels for the paymentMethod
to use on the payment form.- paymentMethod.displayName
.languageLanguage code. en paymentMethod.displayName
.messageText label. Instant Bank Transfer paymentMethod.countries Country codes the APM supports. AE paymentMethod.currencies Currency codes the APM supports. AED paymentMethod.logoURL URL for the paymentMethod
logo to use on the payment form.https://secure.safecharge.com
/ppp/resources/img/svg/solid
-white/open_banking.svgfields Array of /payment
orcreatePayment()
input parameters for the APM.- fields.name Name of input parameter for /payment
orcreatePayment()
requests.lean_bank fields.listValues Array of valid values for field.name
for a dropdown list the merchant presents to the user.- fields.listValues
.codeThe value of the input parameter for /payment
orcreatePayment()
requests.MASHREQ_NEO_UAE
ADIB_UAE
ENBD_UAEfields.listValues
.captionText the merchant presents to the user in a dropdown list. Mashreq Neo Bank
Abu Dhabi Islamic Bank
Emirates NBDfields.listValues
.mandatoryFieldsArray of fields required for /payment
orcreatePayment()
requests.- 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 thelogoURL
.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 anymandatoryFields
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 – Registrationsfc.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) tourlDetails.notificationUrl
, which Nuvei recommends including in thecreatePayment()
request. The DMN includes theuserPaymentOptionId
to use in a subsequentcreatePayment()
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¤cy=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 currencyamount
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 thecreatePayment()
registration DMNpaymentOption.alternativePaymentMethod
block containing:paymentMethod
: “apmgw_Lean“
billingAddress
block containing:email
,country
Example
createPayment()
Request – Paymentsfc.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.
- Simply Connect
-
1. Initiate a Session
Send a zero-amount
/openOrder
server-side API request with its mandatory parameters including:userTokenId
currency
for a supported currencyamount
: “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 countrycurrency
for a supported currencyamount
: “0“billingAddress
block containing:email
,country
Example
checkout()
Request – Registrationdocument.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) tourlDetails.notificationUrl
, which Nuvei recommends including in thecheckout()
request. The DMN includes theuserPaymentOptionId
to use in a subsequentcheckout()
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¤cy=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 currencyamount
paymentOption.userPaymentOptionId
–userPaymentOptionId
from thecheckout()
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()
PaymentSend a second
checkout()
Web SDK request with its mandatory parameters including:country
for a supported countrycurrency
for a supported currencyamount
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()
Requestdocument.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.
After the APM provider processes the payment request, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the request to urlDetails.notificationUrl
, which Nuvei recommends including in the request.
Example Payment DMN with Status
=APPROVED
...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43717971&userid=Mirel246&merchant_unique_id=&customData=&productId=&first_name=&last_name=&email=John.Smith%40email.com¤cy=AED&pmDisplayName=AE290289390310935900867&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=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_Lean&ID=&merchant_id=5634436935940029474&responseTimeStamp=2024-09-11.08%3A47%3A23&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Mirel246&userPaymentOptionId=2153401581&TransactionID=2610000000000059624&externalTransactionId=f974a691-7957-431b-bf77-3e306fc28b68&APMReferenceID=04F5B4773991B01ECF4C973A92D25A6E&orderTransactionId=24980371&totalAmount=40.00&dynamicDescriptor=static+test&item_name_1=NA&item_number_1=&item_amount_1=40.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%7B%22name%22%3A%22Payload%22%2C%22value%22%3A%22%7B%5Cn++%5C%22id%5C%22%3A+%5C%222564f6e6-1362-42fd-b183-bae19244d217%5C%22%2C%5Cn++%5C%22bank_identifier%5C%22%3A+%5C%22LEANMB2_SAU%5C%22%2C%5Cn++%5C%22name%5C%22%3A+%5C%22Nuvei%5C%22%2C%5Cn++%5C%22iban%5C%22%3A+%5C%22AE3402600000000007286010000%5C%22%2C%5Cn++%5C%22display_name%5C%22%3A+%5C%22Nuvei%5C%22%2C%5Cn++%5C%22account_number%5C%22%3A+%5C%2200000007286010000%5C%22%2C%5Cn++%5C%22swift_code%5C%22%3A+%5C%22EBILAEAD%5C%22%2C%5Cn++%5C%22status%5C%22%3A+%5C%22CONFIRMED%5C%22%2C%5Cn++%5C%22address%5C%22%3A+%5C%22INDEX+TOW+999+DUBAI+UNITED+ARAB+EMIRATES%5C%22%2C%5Cn++%5C%22country%5C%22%3A+%5C%22SAU%5C%22%2C%5Cn++%5C%22city%5C%22%3A+%5C%22Riyadh%5C%22%2C%5Cn++%5C%22default%5C%22%3A+true%2C%5Cn++%5C%22owner_type%5C%22%3A+%5C%22APPLICATION%5C%22%5Cn%7D%22%7D%5D&sessionId=0433e1c5e40471ea03df0c8b1d57&responsechecksum=082e2fa7f78b292a32c3643bab9bc4f5&advanceResponseChecksum=84efb5d6c70c0985ea8eecd8c34c32c3',
Example Payment DMN with Status
=PENDING
...'ppp_status=PENDING&Status=PENDING&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43718091&userid=Mirel246&merchant_unique_id=&customData=&productId=&first_name=&last_name=&email=John.Smith%40email.com¤cy=AED&pmDisplayName=AE290289390310935900867&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=&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=PENDING&merchantLocale=&unknownParameters=&payment_method=apmgw_Lean&ID=&merchant_id=5634436935940029474&responseTimeStamp=2024-09-11.09%3A02%3A07&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Mirel246&userPaymentOptionId=2153401581&TransactionID=2610000000000059635&externalTransactionId=86497daa-3889-4ccc-aeb9-e164b9b23448&APMReferenceID=DDFEE2115DE958BC0974530A49DC067E&orderTransactionId=24980451&totalAmount=40.00&dynamicDescriptor=static+test&item_name_1=NA&item_number_1=&item_amount_1=40.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=&sessionId=05157d1258166517090bc080a916&responsechecksum=bb0ca53994011900b0cf8b7b5c706dd9&advanceResponseChecksum=164ed361780a457eb4621baa40d90106',
Example Payment DMN with Status
=DECLINE
...'ppp_status=FAIL&Status=DECLINED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43718241&userid=Mirel246&merchant_unique_id=&customData=&productId=&first_name=&last_name=&email=John.Smith%40email.com¤cy=AED&pmDisplayName=AE290289390310935900867&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=DECLINED&merchantLocale=&unknownParameters=&payment_method=apmgw_Lean&ID=&merchant_id=5634436935940029474&responseTimeStamp=2024-09-11.09%3A20%3A49&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Mirel246&userPaymentOptionId=2153401581&TransactionID=2610000000000059645&externalTransactionId=f277059a-f51d-4cd6-9fc9-dbcdf3c10abb&APMReferenceID=384715E09D2A66ABE84BC51884962DAE&orderTransactionId=24980531&totalAmount=40.00&dynamicDescriptor=static+test&item_name_1=NA&item_number_1=&item_amount_1=40.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%7B%22name%22%3A%22Payload%22%2C%22value%22%3A%22%7B%5Cn++%5C%22id%5C%22%3A+%5C%222564f6e6-1362-42fd-b183-bae19244d217%5C%22%2C%5Cn++%5C%22bank_identifier%5C%22%3A+%5C%22LEANMB2_SAU%5C%22%2C%5Cn++%5C%22name%5C%22%3A+%5C%22Nuvei%5C%22%2C%5Cn++%5C%22iban%5C%22%3A+%5C%22AE3402600000000007286010000%5C%22%2C%5Cn++%5C%22display_name%5C%22%3A+%5C%22Nuvei%5C%22%2C%5Cn++%5C%22account_number%5C%22%3A+%5C%2200000007286010000%5C%22%2C%5Cn++%5C%22swift_code%5C%22%3A+%5C%22EBILAEAD%5C%22%2C%5Cn++%5C%22status%5C%22%3A+%5C%22CONFIRMED%5C%22%2C%5Cn++%5C%22address%5C%22%3A+%5C%22INDEX+TOW+999+DUBAI+UNITED+ARAB+EMIRATES%5C%22%2C%5Cn++%5C%22country%5C%22%3A+%5C%22SAU%5C%22%2C%5Cn++%5C%22city%5C%22%3A+%5C%22Riyadh%5C%22%2C%5Cn++%5C%22default%5C%22%3A+true%2C%5Cn++%5C%22owner_type%5C%22%3A+%5C%22APPLICATION%5C%22%5Cn%7D%22%7D%5D&sessionId=0621dba2f9b62cd4b6de8ab0943b&responsechecksum=22e4a3c1d2d677081d510e221eb003f2&advanceResponseChecksum=4f3fa0d5810e58f39899ba7039889ced',
User Experience
User Registration
- The user selects the Instant Bank Transfer payment method in a supported country.
- The user selects a bank and presses Register.
- The user is redirected to the APM provider and sets up an account.
- The user provides credentials for the selected bank and logs in.
- A confirmation message appears.
Payment (Deposit)
- The user selects the Instant Bank Transfer payment method in a supported country.
- The user selects an existing payment method.
- The user is redirected to the APM provider to review and confirm the payment details.
- A confirmation message appears.
Testing
Test credentials and testing scenarios can be provided by Nuvei if necessary. You can contact Nuvei support for assistance.