- METHOD TYPEReal-Time Bank Transfer
- PAYMENTS
- PAYOUTS
- REFUNDS
- RECURRING
Introduction
The SPEI® APM consists of:
- SPEI, authorized by Banco de México®, which enables users to make electronic fund transfers between bank accounts. SPEI supports regular payments (deposits).
- STPmex, which offers technological products and services aimed at satisfying the needs of its clients in making electronic transfers. STPmex supports a multiple deposit flow and supports payouts (withdrawals).
Prerequisites and Notes
- When a deposit request is submitted with a new user (
user_token_id), a unique CLABE (Standardized Bank Code) number is generated for this specific user. The CLABE number remains the same for all future deposits with the same user. All future deposits are connected to the first request. This means that for every user, we have one request in our system but there can be many transactions associated with this user. - The Direct Merchant Notification (DMN) sent does NOT include other custom parameters, such as
userIdandcustomData. - Since the user completes the deposit offline (via his bank account), the user can submit another deposit to the same CLABE number (generated on the first deposit) without having to go to the merchant’s payment page.
Supported Countries
- Mexico
Supported Currencies
- MXN
Regular Payment (Deposit) Flow
Press tab to open…
Follow these steps to perform a payment using Nuvei REST API integration:
1. Generate a sessionToken
Press here for details.
2. Send a /payment Request
Perform the payment by sending a /payment request with its mandatory parameters including:
userTokenIdamount– must be greater than 0 (zero)currencypaymentOption.alternativePaymentMethodclass containing:paymentMethod: “apmgw_Spei“
deviceDetailsclass containing:ipAddressbillingAddressclass containing:firstName,lastName,country,emailuserDetailsclass containing:firstName,lastName,country,email
Example /payment Request
{
"sessionToken":"<sessionToken from /getSessionToken>",
"merchantId": "<your merchantId>",
"merchantSiteId": "<your merchantSiteId>",
"clientRequestId": "<unique request ID in merchant system>",
"amount": "1000",
"currency": "MXN",
"userTokenId": "<unique customer identifier in merchant system>",
"clientUniqueId": "<unique transaction ID in merchant system>",
"paymentOption":{
"alternativePaymentMethod":{
"paymentMethod":"apmgw_Spei"
}
},
"deviceDetails":{
"ipAddress":"<customer's IP address>"
},
"billingAddress": {
"firstName": "John",
"lastName": "Smith",
"country": "MX",
"email":"[email protected]"
},
"userDetails": {
"firstName": "John",
"lastName": "Smith",
"country": "MX",
"email":"[email protected]"
},
"timeStamp":"<YYYYMMDDHHmmss>",
"checksum":"<calculated checksum>"
}
After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided in urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.
Follow these steps to perform a payment using Nuvei Web SDK integration.
1. Initiate a Session
Before you can submit payment using the client-side Nuvei Web SDK, you need to send the /openOrder API call with the following mandatory parameter:
amount– must be greater than 0 (zero)
2. Initialize the Web SDK
Instantiate the Web SDK with the sessionToken received from the server call to /openOrder.
3. Create an APM Payment
Send a createPayment() request with its mandatory parameters including:
paymentOption.alternativePaymentMethodclass containing:paymentMethod: “apmgw_Spei“
deviceDetailsclass containing:ipAddressbillingAddressclass containing:firstName,lastName,country,emailuserDetailsclass containing:firstName,lastName,country,email
Example createPayment() Request
sfc.createPayment({
sessionToken: "<sessiontoken>",
merchantId: "<your merchantId>",
merchantSiteId: "<your merchantSiteId>",
clientUniqueId: "<your clientUniqueId>",
paymentOption: {
alternativePaymentMethod: {
paymentMethod: "apmgw_Spei"
}
},
deviceDetails:{
ipAddress:"<customer's IP address>"
},
billingAddress: {
firstName: "John",
lastName: "Smith",
country: "US",
email: "[email protected]"
},
userDetails: {
firstName: "John",
lastName: "Smith",
country: "US",
email: "[email protected]"
},
}, function(res) {
console.log(res);
if (res.cancelled === true) {
example.querySelector('.token').innerText = 'cancelled';
} else {
example.querySelector('.token').innerText = res.transactionStatus + ' – Reference: ' + res.transactionId;
}
example.classList.add('submitted');
});
After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided in urlDetails.notificationUrl, which Nuvei recommends including in the /openOrder request.
Example Payment Page Request
After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to notify_url, which Nuvei recommends including in the request.
- REST API
-
Follow these steps to perform a payment using Nuvei REST API integration:
1. Generate a
sessionTokenPress here for details.
2. Send a
/paymentRequestPerform the payment by sending a
/paymentrequest with its mandatory parameters including:userTokenIdamount– must be greater than 0 (zero)currencypaymentOption.alternativePaymentMethodclass containing:paymentMethod: “apmgw_Spei“
deviceDetailsclass containing:ipAddressbillingAddressclass containing:firstName,lastName,country,emailuserDetailsclass containing:firstName,lastName,country,email
Example
/paymentRequest{ "sessionToken":"<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "clientRequestId": "<unique request ID in merchant system>", "amount": "1000", "currency": "MXN", "userTokenId": "<unique customer identifier in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "paymentOption":{ "alternativePaymentMethod":{ "paymentMethod":"apmgw_Spei" } }, "deviceDetails":{ "ipAddress":"<customer's IP address>" }, "billingAddress": { "firstName": "John", "lastName": "Smith", "country": "MX", "email":"[email protected]" }, "userDetails": { "firstName": "John", "lastName": "Smith", "country": "MX", "email":"[email protected]" }, "timeStamp":"<YYYYMMDDHHmmss>", "checksum":"<calculated checksum>" }After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided in
urlDetails.notificationUrl, which Nuvei recommends including in the/paymentrequest. - Web SDK
-
Follow these steps to perform a payment using Nuvei Web SDK integration.
1. Initiate a Session
Before you can submit payment using the client-side Nuvei Web SDK, you need to send the /openOrder API call with the following mandatory parameter:
amount– must be greater than 0 (zero)
2. Initialize the Web SDK
Instantiate the Web SDK with the
sessionTokenreceived from the server call to/openOrder.3. Create an APM Payment
Send a createPayment() request with its mandatory parameters including:
paymentOption.alternativePaymentMethodclass containing:paymentMethod: “apmgw_Spei“
deviceDetailsclass containing:ipAddressbillingAddressclass containing:firstName,lastName,country,emailuserDetailsclass containing:firstName,lastName,country,email
Example
createPayment()Requestsfc.createPayment({ sessionToken: "<sessiontoken>", merchantId: "<your merchantId>", merchantSiteId: "<your merchantSiteId>", clientUniqueId: "<your clientUniqueId>", paymentOption: { alternativePaymentMethod: { paymentMethod: "apmgw_Spei" } }, deviceDetails:{ ipAddress:"<customer's IP address>" }, billingAddress: { firstName: "John", lastName: "Smith", country: "US", email: "[email protected]" }, userDetails: { firstName: "John", lastName: "Smith", country: "US", email: "[email protected]" }, }, function(res) { console.log(res); if (res.cancelled === true) { example.querySelector('.token').innerText = 'cancelled'; } else { example.querySelector('.token').innerText = res.transactionStatus + ' – Reference: ' + res.transactionId; } example.classList.add('submitted'); });After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided in
urlDetails.notificationUrl, which Nuvei recommends including in the/openOrderrequest. - Payment Page
-
Example Payment Page Request
After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to
notify_url, which Nuvei recommends including in the request.
Multi-Deposit Flow
Press tab to open…
Using Nuvei REST API integration, follow these steps:
1. Generate a sessionToken
Press here for details.
2. Send a /payment Request
Send a /payment request with its mandatory parameters including:
userTokenIdamount: “0” (zero)currencypaymentOption.alternativePaymentMethodclass containing:paymentMethod: “apmgw_STPmex“
deviceDetailsclass containing:ipAddressbillingAddressclass containing:firstName,lastName,country,emailuserDetailsclass containing:firstName,lastName,country,email
Example /payment Request
{
"sessionToken":"<sessionToken from /getSessionToken>",
"merchantId": "<your merchantId>",
"merchantSiteId": "<your merchantSiteId>",
"clientRequestId": "<unique request ID in merchant system>",
"amount": "0",
"currency": "MXN",
"userTokenId": "<unique customer identifier in merchant system>",
"clientUniqueId": "<unique transaction ID in merchant system>",
"paymentOption":{
"alternativePaymentMethod":{
"paymentMethod":"apmgw_STPmex"
}
},
"deviceDetails":{
"ipAddress":"<customer's IP address>"
},
"billingAddress": {
"firstName": "John",
"lastName": "Smith",
"country": "MX",
"email":"[email protected]"
},
"userDetails": {
"firstName": "John",
"lastName": "Smith",
"country": "MX",
"email":"[email protected]"
},
"timeStamp":"<YYYYMMDDHHmmss>",
"checksum":"<calculated checksum>"
}
After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided in urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.
Using Nuvei Web SDK integration, follow these steps.
1. Initiate a Session
Before you can submit payment using the client-side Nuvei Web SDK, you need to send the /openOrder API call with the following mandatory parameter:
amount: “0” (zero)
2. Initialize the Web SDK
Instantiate the Web SDK with the sessionToken received from the server call to /openOrder.
3. Create an APM Payment
Send a createPayment() request with its mandatory parameters including:
paymentOption.alternativePaymentMethodclass containing:paymentMethod: “apmgw_STPmex“
deviceDetailsclass containing:ipAddressbillingAddressclass containing:firstName,lastName,country,emailuserDetailsclass containing:firstName,lastName,country,email
Example createPayment() Request
sfc.createPayment({
sessionToken: "<sessiontoken>",
merchantId: "<your merchantId>",
merchantSiteId: "<your merchantSiteId>",
clientUniqueId: "<your clientUniqueId>",
paymentOption: {
alternativePaymentMethod: {
paymentMethod: "apmgw_STPmex"
}
},
deviceDetails:{
ipAddress:"<customer's IP address>"
},
billingAddress: {
firstName: "John",
lastName: "Smith",
country: "US",
email: "[email protected]"
},
userDetails: {
firstName: "John",
lastName: "Smith",
country: "US",
email: "[email protected]"
},
}, function(res) {
console.log(res);
if (res.cancelled === true) {
example.querySelector('.token').innerText = 'cancelled';
} else {
example.querySelector('.token').innerText = res.transactionStatus + ' – Reference: ' + res.transactionId;
}
example.classList.add('submitted');
});
After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided in urlDetails.notificationUrl, which Nuvei recommends including in the /openOrder request.
Example Payment Page Request
After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to notify_url, which Nuvei recommends including in the request.
- REST API
-
Using Nuvei REST API integration, follow these steps:
1. Generate a
sessionTokenPress here for details.
2. Send a
/paymentRequestSend a
/paymentrequest with its mandatory parameters including:userTokenIdamount: “0” (zero)currencypaymentOption.alternativePaymentMethodclass containing:paymentMethod: “apmgw_STPmex“
deviceDetailsclass containing:ipAddressbillingAddressclass containing:firstName,lastName,country,emailuserDetailsclass containing:firstName,lastName,country,email
Example
/paymentRequest{ "sessionToken":"<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "clientRequestId": "<unique request ID in merchant system>", "amount": "0", "currency": "MXN", "userTokenId": "<unique customer identifier in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "paymentOption":{ "alternativePaymentMethod":{ "paymentMethod":"apmgw_STPmex" } }, "deviceDetails":{ "ipAddress":"<customer's IP address>" }, "billingAddress": { "firstName": "John", "lastName": "Smith", "country": "MX", "email":"[email protected]" }, "userDetails": { "firstName": "John", "lastName": "Smith", "country": "MX", "email":"[email protected]" }, "timeStamp":"<YYYYMMDDHHmmss>", "checksum":"<calculated checksum>" }After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided in
urlDetails.notificationUrl, which Nuvei recommends including in the/paymentrequest. - Web SDK
-
Using Nuvei Web SDK integration, follow these steps.
1. Initiate a Session
Before you can submit payment using the client-side Nuvei Web SDK, you need to send the /openOrder API call with the following mandatory parameter:
amount: “0” (zero)
2. Initialize the Web SDK
Instantiate the Web SDK with the
sessionTokenreceived from the server call to/openOrder.3. Create an APM Payment
Send a createPayment() request with its mandatory parameters including:
paymentOption.alternativePaymentMethodclass containing:paymentMethod: “apmgw_STPmex“
deviceDetailsclass containing:ipAddressbillingAddressclass containing:firstName,lastName,country,emailuserDetailsclass containing:firstName,lastName,country,email
Example
createPayment()Requestsfc.createPayment({ sessionToken: "<sessiontoken>", merchantId: "<your merchantId>", merchantSiteId: "<your merchantSiteId>", clientUniqueId: "<your clientUniqueId>", paymentOption: { alternativePaymentMethod: { paymentMethod: "apmgw_STPmex" } }, deviceDetails:{ ipAddress:"<customer's IP address>" }, billingAddress: { firstName: "John", lastName: "Smith", country: "US", email: "[email protected]" }, userDetails: { firstName: "John", lastName: "Smith", country: "US", email: "[email protected]" }, }, function(res) { console.log(res); if (res.cancelled === true) { example.querySelector('.token').innerText = 'cancelled'; } else { example.querySelector('.token').innerText = res.transactionStatus + ' – Reference: ' + res.transactionId; } example.classList.add('submitted'); });After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided in
urlDetails.notificationUrl, which Nuvei recommends including in the/openOrderrequest. - Payment Page
-
Example Payment Page Request
After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to
notify_url, which Nuvei recommends including in the request.
Payout (Withdrawal) Flow
REST API
The following two methods can be used to process a /payout request with STPmex:
- By collecting the customer’s bank account details using the
/accountCapturemethod. - By creating a UPO, which represents the customer’s bank account details, with the
/addUPOAPMmethod.
Press tab to open…
- Generate a
sessionToken. Press here for details. - Send an
/accountCapturerequest that includes the following mandatory fields as shown in the example request below:userTokenId– Unique customer identifier in merchant system.paymentMethod: “apmgw_STPmex“currencyCode: MXNcountryCode: MX
Example
/accountCaptureRequest{ "sessionToken": "<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "<unique customer identifier in merchant system>", "paymentMethod": "apmgw_STPmex", "currencyCode": "MXN", "countryCode": "MX", }The request returns a
redirectUrl.Example
/accountCaptureResponse{ "redirectUrl":"https://ppp-test.safecharge.com/ppp/acs/get.do?cccid=111&country=MX&language=en&amount=100¤cy=MXN&ReturnURL=https%3a%2f%2ftest.safecharge.com%2fAPMNotificationGateway%2fSTPmex%2fSTPmexRedirectWithdrawResponse.ashx&APMTransactionID=404EE9CD3BBDDD2622BECE95DA936FF1&AccountInfo5=+", "userTokenId":"1810test", "sessionToken":"89c762b7-06c6-45f4-8517-0e335350d0e3", "internalRequestId":603948068, "status":"SUCCESS", "errCode":0, "reason":"", "merchantId":"221195993304907999", "merchantSiteId":"232618", "version":"1.0" }
- Use
redirectUrlto redirect the customer to the APM’s account details capture interface for them to enter their account details. - Once the information is captured, Nuvei stores the data in a
userPaymentOptionId(UPO) identifier, and sends a with the newly createduserPaymentOptionIdtourlDetails.notificationUrl, which Nuvei recommends including in the/accountCapturerequest. - Send a
/payoutrequest and include theuserPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.
1. Register a userTokenId
A userTokenId is a field in the Nuvei system containing the user’s identifier in the merchant system.
If you do not have a userTokenId registered in the Nuvei system for this user, then register one by sending a /createUser request, including email, countryCode, firstName, and lastName.
Example /createUser Request
{
"merchantId":"<your merchantId>",
"merchantSiteId":"<your merchantSiteId>",
"clientRequestId":"<unique request ID in merchant system>",
"userTokenId":"<unique user identifier in merchant system>",
"email":"[email protected]",
"countryCode":"<2-letter ISO country code>",
"firstName":"John",
"lastName":"Smith",
"timeStamp":"<YYYYMMDDHHmmss>",
"checksum":"<calculated checksum>"
}
Example /createUser Response
{
"userId":78403498,
"internalRequestId":552360538,
"status":"SUCCESS",
"errCode":0,
"reason":"",
"merchantId":"2439523627382132721",
"merchantSiteId":"224428",
"version":"1.0",
"clientRequestId":"20221108130736"
}
The request registers the userTokenId (userId) in the Nuvei system, which is needed to generate a userPaymentOptionId in the next step.
2. Create the UPO
Create a UPO by sending an /addUPOAPM request and include:
userTokenId– The unique user identifier in your system.paymentMethodName: “apmgw_STPmex“apmDataclass containing:beneficiaryBank– Press here to see list of supportedbeneficiaryBankcodes.beneficiaryNamebeneficiaryNumberbeneficiaryType
billingAddressclass containing:countryandemail
Example /addUPOAPM Request
{
"merchantId":"<your merchantId>",
"merchantSiteId":"<your merchantSiteId>",
"clientRequestId":"<unique request ID in merchant system>",
"userTokenId":"<unique customer identifier in merchant system>",
"paymentMethodName":"apmgw_STPmex",
"apmData": {
"beneficiaryBank": "<supported beneficiary bank code>",
"beneficiaryName": "John Smith",
"beneficiaryNumber": "<CLABE number>",
"beneficiaryType": "40"
},
"billingAddress":{
"country":"MX",
"email":"[email protected]"
},
"timeStamp":"<YYYYMMDDHHmmss>",
"checksum":"<calculated checksum>"
}
The request returns an encrypted userPaymentOptionId representing the user’s APM account details.
Example /addUPOAPM Response
{
"userPaymentOptionId":83458468,
"internalRequestId":553078068,
"status":"SUCCESS",
"errCode":0,
"reason":"",
"merchantId":"2439523627382132721",
"merchantSiteId":"224428",
"version":"1.0",
"clientRequestId":"20221109154215"
}
3. Send a /payout Request
Send a /payout request and include the userPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.
-
/accountCapture -
- Generate a
sessionToken. Press here for details. - Send an
/accountCapturerequest that includes the following mandatory fields as shown in the example request below:userTokenId– Unique customer identifier in merchant system.paymentMethod: “apmgw_STPmex“currencyCode: MXNcountryCode: MX
Example
/accountCaptureRequest{ "sessionToken": "<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "<unique customer identifier in merchant system>", "paymentMethod": "apmgw_STPmex", "currencyCode": "MXN", "countryCode": "MX", }The request returns a
redirectUrl.Example
/accountCaptureResponse{ "redirectUrl":"https://ppp-test.safecharge.com/ppp/acs/get.do?cccid=111&country=MX&language=en&amount=100¤cy=MXN&ReturnURL=https%3a%2f%2ftest.safecharge.com%2fAPMNotificationGateway%2fSTPmex%2fSTPmexRedirectWithdrawResponse.ashx&APMTransactionID=404EE9CD3BBDDD2622BECE95DA936FF1&AccountInfo5=+", "userTokenId":"1810test", "sessionToken":"89c762b7-06c6-45f4-8517-0e335350d0e3", "internalRequestId":603948068, "status":"SUCCESS", "errCode":0, "reason":"", "merchantId":"221195993304907999", "merchantSiteId":"232618", "version":"1.0" }
- Use
redirectUrlto redirect the customer to the APM’s account details capture interface for them to enter their account details. - Once the information is captured, Nuvei stores the data in a
userPaymentOptionId(UPO) identifier, and sends a with the newly createduserPaymentOptionIdtourlDetails.notificationUrl, which Nuvei recommends including in the/accountCapturerequest. - Send a
/payoutrequest and include theuserPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.
- Generate a
-
/addUPOAPM -
1. Register a
userTokenIdA
userTokenIdis a field in the Nuvei system containing the user’s identifier in the merchant system.If you do not have a
userTokenIdregistered in the Nuvei system for this user, then register one by sending a/createUserrequest, includingemail,countryCode,firstName, andlastName.Example
/createUserRequest{ "merchantId":"<your merchantId>", "merchantSiteId":"<your merchantSiteId>", "clientRequestId":"<unique request ID in merchant system>", "userTokenId":"<unique user identifier in merchant system>", "email":"[email protected]", "countryCode":"<2-letter ISO country code>", "firstName":"John", "lastName":"Smith", "timeStamp":"<YYYYMMDDHHmmss>", "checksum":"<calculated checksum>" }Example
/createUserResponse{ "userId":78403498, "internalRequestId":552360538, "status":"SUCCESS", "errCode":0, "reason":"", "merchantId":"2439523627382132721", "merchantSiteId":"224428", "version":"1.0", "clientRequestId":"20221108130736" }The request registers the
userTokenId(userId) in the Nuvei system, which is needed to generate auserPaymentOptionIdin the next step.2. Create the UPO
Create a UPO by sending an
/addUPOAPMrequest and include:userTokenId– The unique user identifier in your system.paymentMethodName: “apmgw_STPmex“apmDataclass containing:beneficiaryBank– Press here to see list of supportedbeneficiaryBankcodes.beneficiaryNamebeneficiaryNumberbeneficiaryType
billingAddressclass containing:countryandemail
Example
/addUPOAPMRequest{ "merchantId":"<your merchantId>", "merchantSiteId":"<your merchantSiteId>", "clientRequestId":"<unique request ID in merchant system>", "userTokenId":"<unique customer identifier in merchant system>", "paymentMethodName":"apmgw_STPmex", "apmData": { "beneficiaryBank": "<supported beneficiary bank code>", "beneficiaryName": "John Smith", "beneficiaryNumber": "<CLABE number>", "beneficiaryType": "40" }, "billingAddress":{ "country":"MX", "email":"[email protected]" }, "timeStamp":"<YYYYMMDDHHmmss>", "checksum":"<calculated checksum>" }The request returns an encrypted
userPaymentOptionIdrepresenting the user’s APM account details.Example
/addUPOAPMResponse{ "userPaymentOptionId":83458468, "internalRequestId":553078068, "status":"SUCCESS", "errCode":0, "reason":"", "merchantId":"2439523627382132721", "merchantSiteId":"224428", "version":"1.0", "clientRequestId":"20221109154215" }3. Send a
/payoutRequestSend a
/payoutrequest and include theuserPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.
After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided in urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.
Web SDK
When performing a Withdrawal with SPEI, the following two methods can be used to process a Withdrawal request: accountCapture() or addApmUpo().
For information about the Withdrawal flow for WebSDK, see Withdrawal.
Press tab to open…
The following flow describes how to capture a user’s account details before processing a payout request using Nuvei Web SDK integration.
1. Initiate a Session
Before you can submit payment using the client-side Nuvei Web SDK, you need to send the /openOrder API call.
2. Initialize the Web SDK
Instantiate the Web SDK with the sessionToken received from the server call to /openOrder.
3. Send an accountCapture() request
a. Send an accountCapture() request that includes the following mandatory fields (as shown in the example request below):
userTokenId– Unique customer identifier in merchant system.paymentMethod: “apmgw_STPmex“currencyCodecountryCode
Example accountCapture() Request
sfc.accountCapture({
sessionToken: "<sessiontoken>",
merchantId: "<your merchantId>",
merchantSiteId: "<your merchantSiteId>",
paymentMethod: "apmgw_STPmex",
userTokenId: "<unique customer identifier in merchant system>",
currencyCode: "MXN",
countryCode: "MX",
languageCode: "en",
urlDetails:{
successUrl:"<URL the customer is directed to after a successful transaction>",
pendingUrl:"<URL the customer is directed to when the transaction response is pending>",
failureUrl:"<URL the customer is directed to after an unsuccessful transaction>",
notificationUrl:"<URL to which DMNs are sent>"
},
sourceApplication: "WebSDK"
}, function(accountRes) {
console.log(accountRes);
})
The request returns a redirectUrl.
Example accountCapture() Response
{
"redirectUrl": "<redirect URL to enter account details>",
"userTokenId": "bankCaptureUser4",
"sessionToken": "e44a932a-e9fc-4482-a570-cf07175408e0",
"internalRequestId": 23238261,
"status": "SUCCESS",
"errCode": 0,
"reason": "",
"merchantId": "8256777005602846935",
"merchantSiteId": "112106",
"version": "1.0"
}
b. Use the redirectUrl to redirect the customer to the APM’s account details interface, to enter their account details.
c. Once the information is captured, Nuvei stores the data in a UPO record, and sends a DMN with the newly created userPaymentOptionId to urlDetails.notificationUrl, which Nuvei recommends including in the /accountCapture request.
4. Send a /payout Request
Send a /payout request and include the userPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.
1. Register a userTokenId
A userTokenId is a field in the Nuvei system containing the user’s identifier in the merchant system.
If you do not have a userTokenId registered in the Nuvei system for this user, then register one by sending a /createUser request, including email, countryCode, firstName, and lastName.
Example /createUser Request
{
"merchantId":"<your merchantId>",
"merchantSiteId":"<your merchantSiteId>",
"clientRequestId":"<unique request ID in merchant system>",
"userTokenId":"<unique user identifier in merchant system>",
"email":"[email protected]",
"countryCode":"<2-letter ISO country code>",
"firstName":"John",
"lastName":"Smith",
"timeStamp":"<YYYYMMDDHHmmss>",
"checksum":"<calculated checksum>"
}
Example /createUser Response
{
"userId":78403498,
"internalRequestId":552360538,
"status":"SUCCESS",
"errCode":0,
"reason":"",
"merchantId":"2439523627382132721",
"merchantSiteId":"224428",
"version":"1.0",
"clientRequestId":"20221108130736"
}
The request registers the userTokenId (userId) in the Nuvei system, which is needed to generate a userPaymentOptionId in the next step.
2. Create the UPO
Create a UPO by sending an addApmUpo() request and include:
userTokenId– The unique user identifier in your system.paymentMethodName: “apmgw_STPmex“apmDataclass containing:beneficiaryBank– Press here to see list of supportedbeneficiaryBankcodes.beneficiaryNamebeneficiaryNumberbeneficiaryType
billingAddressclass containing:countryandemail
Example addApmUpo() Request
function addApmUpo() {
sfc.addApmUpo({
"paymentMethodName": "apmgw_STPmex",
"apmData": {
"beneficiaryBank": "<supported beneficiary bank code>",
"beneficiaryName": "John Smith",
"beneficiaryNumber": "<CLABE number>",
"beneficiaryType": "40"
},
billingAddress: { // optional
email: '[email protected]',
country: 'MX'
} },
function(result) {
console.log(result);
})
The request returns an encrypted userPaymentOptionId representing the user’s APM account details.
Example addApmUpo() Response
{
"result": "ADDED",
"errCode": 0,
"errorDescription": "",
"userPaymentOptionId": "14958143",
"cancelled": false
}
3. Send a /payout Request
Send a /payout request and include the userPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.
-
accountCapture() -
The following flow describes how to capture a user’s account details before processing a payout request using Nuvei Web SDK integration.
1. Initiate a Session
Before you can submit payment using the client-side Nuvei Web SDK, you need to send the /openOrder API call.
2. Initialize the Web SDK
Instantiate the Web SDK with the
sessionTokenreceived from the server call to/openOrder.3. Send an
accountCapture()requesta. Send an
accountCapture()request that includes the following mandatory fields (as shown in the example request below):userTokenId– Unique customer identifier in merchant system.paymentMethod: “apmgw_STPmex“currencyCodecountryCode
Example
accountCapture()Requestsfc.accountCapture({ sessionToken: "<sessiontoken>", merchantId: "<your merchantId>", merchantSiteId: "<your merchantSiteId>", paymentMethod: "apmgw_STPmex", userTokenId: "<unique customer identifier in merchant system>", currencyCode: "MXN", countryCode: "MX", languageCode: "en", urlDetails:{ successUrl:"<URL the customer is directed to after a successful transaction>", pendingUrl:"<URL the customer is directed to when the transaction response is pending>", failureUrl:"<URL the customer is directed to after an unsuccessful transaction>", notificationUrl:"<URL to which DMNs are sent>" }, sourceApplication: "WebSDK" }, function(accountRes) { console.log(accountRes); })The request returns a
redirectUrl.Example
accountCapture()Response{ "redirectUrl": "<redirect URL to enter account details>", "userTokenId": "bankCaptureUser4", "sessionToken": "e44a932a-e9fc-4482-a570-cf07175408e0", "internalRequestId": 23238261, "status": "SUCCESS", "errCode": 0, "reason": "", "merchantId": "8256777005602846935", "merchantSiteId": "112106", "version": "1.0" }b. Use the
redirectUrlto redirect the customer to the APM’s account details interface, to enter their account details.c. Once the information is captured, Nuvei stores the data in a UPO record, and sends a DMN with the newly created
userPaymentOptionIdtourlDetails.notificationUrl, which Nuvei recommends including in the/accountCapturerequest.4. Send a
/payoutRequestSend a
/payoutrequest and include theuserPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example. -
addApmUpo() -
1. Register a
userTokenIdA
userTokenIdis a field in the Nuvei system containing the user’s identifier in the merchant system.If you do not have a
userTokenIdregistered in the Nuvei system for this user, then register one by sending a/createUserrequest, includingemail,countryCode,firstName, andlastName.Example
/createUserRequest{ "merchantId":"<your merchantId>", "merchantSiteId":"<your merchantSiteId>", "clientRequestId":"<unique request ID in merchant system>", "userTokenId":"<unique user identifier in merchant system>", "email":"[email protected]", "countryCode":"<2-letter ISO country code>", "firstName":"John", "lastName":"Smith", "timeStamp":"<YYYYMMDDHHmmss>", "checksum":"<calculated checksum>" }Example
/createUserResponse{ "userId":78403498, "internalRequestId":552360538, "status":"SUCCESS", "errCode":0, "reason":"", "merchantId":"2439523627382132721", "merchantSiteId":"224428", "version":"1.0", "clientRequestId":"20221108130736" }The request registers the
userTokenId(userId) in the Nuvei system, which is needed to generate auserPaymentOptionIdin the next step.2. Create the UPO
Create a UPO by sending an
addApmUpo()request and include:userTokenId– The unique user identifier in your system.paymentMethodName: “apmgw_STPmex“apmDataclass containing:beneficiaryBank– Press here to see list of supportedbeneficiaryBankcodes.beneficiaryNamebeneficiaryNumberbeneficiaryType
billingAddressclass containing:countryandemail
Example
addApmUpo()Requestfunction addApmUpo() { sfc.addApmUpo({ "paymentMethodName": "apmgw_STPmex", "apmData": { "beneficiaryBank": "<supported beneficiary bank code>", "beneficiaryName": "John Smith", "beneficiaryNumber": "<CLABE number>", "beneficiaryType": "40" }, billingAddress: { // optional email: '[email protected]', country: 'MX' } }, function(result) { console.log(result); })The request returns an encrypted
userPaymentOptionIdrepresenting the user’s APM account details.Example
addApmUpo()Response{ "result": "ADDED", "errCode": 0, "errorDescription": "", "userPaymentOptionId": "14958143", "cancelled": false }3. Send a
/payoutRequestSend a
/payoutrequest and include theuserPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.
After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided in urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.
User Experience
Regular Payment
- The user is redirected to a page with the generated CLABE number to which you need to transfer the funds.

- The user selects a bank and is redirected to the bank’s login page.
- The user logs in and makes the transfer.
For the transfer to succeed, the user must transfer the correct amount and use the unique reference number. The same CLABE number is used for all future deposits for the user, while the reference number is unique per transaction. - After the deposit is completed, the bank sends a notification. For example,

Multi-Deposit
- The user is redirected to a page with either one or two generated CLABEs to which you need to transfer the funds.
One CLABE

Two CLABEs

- The user selects a bank and is redirected to the bank’s login page.
- The user logs in and makes the transfer.
For the transfer to succeed, the user must transfer the correct amount and use the unique reference number. The same CLABE number is used for all future deposits for the user, while the reference number is unique per transaction. - After the deposit is completed, the bank sends a notification. For example,

Payout
- The user is redirected to an account capture page.
- In Account type, the user selects either CLABE or DebitCard, and then either:
- Enters their CLABE number.

- Enters their debit card number and selects their bank.

- Enters their CLABE number.
- Once the user submits the form, a withdrawal request is created.
Testing
Full flow testing is not possible in an integration environment.
Appendices
Check Order
The Check Order feature is activated on request, and allows the merchant to query STPMEX for approved deposits and retrieve additional information on these deposits such as rfcCep, urlCEP, and account holder name.
There is a service that runs in the background and picks up approved STPMEX deposits for merchants that have this setting enabled, and then performs a check order call to STP.
Example DMN
...'ppp_status=OK&Status=UPDATE&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=31706810216&userid=&merchant_unique_id=&customData=&productId=&first_name=Cristo+rey&last_name=Rodr%C3%ADguez&email=Kris2425leah%40hotmail.com¤cy=MXN&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=Mexico&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=STPmex+MX-PI&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=222779&merchant_status=&action=&requestVersion=&message=UPDATE&merchantLocale=&unknownParameters=&payment_method=apmgw_STPmex&ID=&merchant_id=1659611123406912420&responseTimeStamp=2022-09-19.21%3A03%3A55&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=9e28218a-9509-4fc9-ba7c-ad7caa3ce5aa&userPaymentOptionId=1665864976&TransactionID=2130000000991852528&ExternalaccountID=646052258100011027&externalAccountDescription=account_id%3A646052258100011027&externalTransactionId=3843CP01202209191901635060&APMReferenceID=AF375F0461B5E5A1ACB364A15358A003&orderTransactionId=26437565446&totalAmount=97.00&dynamicDescriptor=WINPOT&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20220913&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=%7B%22estado%22%3A0%2C%22mensaje%22%3A%22Datos+consultados+correctamente%22%2C%22respuesta%22%3A%7B%22idEF%22%3A309094374%2C%22claveRastreo%22%3A%223843CP01202209191901635060%22%2C%22conceptoPago%22%3A%22cristo+rey%22%2C%22cuentaBeneficiario%22%3A%22646052258100011027%22%2C%22cuentaOrdenante%22%3A%22072905011247815235%22%2C%22empresa%22%3A%22SAFECHARGE%22%2C%22estado%22%3A%22CCO%22%2C%22fechaOperacion%22%3A20220919%2C%22institucionContraparte%22%3A40072%2C%22institucionOperante%22%3A90646%2C%22medioEntrega%22%3A1%2C%22monto%22%3A97.00%2C%22nombreBeneficiario%22%3A%22NO+INGRESADO%22%2C%22nombreOrdenante%22%3A%22CRISTO+REY+RODRIGUEZ+JACOME%22%2C%22nombreCep%22%3Anull%2C%22rfcCep%22%3A%22SDI170928EX7%22%2C%22sello%22%3Anull%2C%22rfcCurpBeneficiario%22%3A%22No+capturado%22%2C%22referenciaNumerica%22%3A220919%2C%22rfcCurpOrdenante%22%3A%22ROJC901124DI0%22%2C%22tipoCuentaBeneficiario%22%3A40%2C%22tipoCuentaOrdenante%22%3A40%2C%22tipoPago%22%3A1%2C%22tsCaptura%22%3A1663618837274%2C%22tsLiquidacion%22%3A1663618837274%2C%22causaDevolucion%22%3Anull%2C%22urlCEP%22%3A%22https%3A%2F%2Fwww.banxico.org.mx%2Fcep%2Fgo%3Fi%3D90646%26s%3D20210302%26d%3Dq19uQPRq3sdgt6MLsir4qa56mu6GylpgypPNN85PvrHR%252BFKXInTbXIXndDh5fgMC0X3T%252FRkZSqOX3dal1ABXvY7YuAQoZIZxqnO%252Fq9ng6d0%253D%22%7D%7D&responsechecksum=ce577b633adcebaa575af42185c1aceda59871cea2f783d174e58b237d972aff&advanceResponseChecksum=826d2fbf7ba9dadcaa46abc5541cc41c18e2d4ad49d1dc9fa7aa4a0d7c5c76cc',
Bank Codes
If the customer uses a debit card for payout, include the apmData class in the /payout as shown below:
{
"apmData":{
"beneficiaryBank":"40044",
"beneficiaryName":"John Doe",
"beneficiaryNumber":"4111111111111111",
"beneficiaryType":"3"
}
}
The supported codes for beneficiaryBank are presented in the table below.
| Bank | Code |
|---|---|
| BANXICO | 2001 |
| BANCOMEXT | 37006 |
| BANOBRAS | 37009 |
| BANJERCITO | 37019 |
| NAFIN | 37135 |
| BaBien | 37166 |
| HIPOTECARIA FED | 37168 |
| BANAMEX | 40002 |
| BBVA MEXICO | 40012 |
| SANTANDER | 40014 |
| HSBC | 40021 |
| BAJIO | 40030 |
| INBURSA | 40036 |
| MIFEL | 40042 |
| SCOTIABANK | 40044 |
| BANREGIO | 40058 |
| INVEX | 40059 |
| BANSI | 40060 |
| AFIRME | 40062 |
| BANORTE | 40072 |
| BANK OF AMERICA | 40106 |
| MUFG | 40108 |
| JP MORGAN | 40110 |
| BMONEX | 40112 |
| VE POR MAS | 40113 |
| AZTECA | 40127 |
| AUTOFIN | 40128 |
| BARCLAYS | 40129 |
| COMPARTAMOS | 40130 |
| MULTIVA BANCO | 40132 |
| ACTINVER | 40133 |
| INTERCAM BANCO | 40136 |
| BANCOPPEL | 40137 |
| UALA | 40138 |
| CONSUBANCO | 40140 |
| VOLKSWAGEN | 40141 |
| CIBANCO | 40143 |
| BBASE | 40145 |
| BANKAOOL | 40147 |
| PAGATODO. | 40148 |
| INMOBILIARIO | 40150 |
| DONDE. | 40151 |
| BANCREA | 40152 |
| BANCO COVALTO | 40154 |
| ICBC | 40155 |
| SABADELL | 40156 |
| SHINHAN | 40157 |
| MIZUHO BANK | 40158 |
| BANK OF CHINA | 40159 |
| BANCO S3 | 40160 |
| MONEXCB | 90600 |
| GBM | 90601 |
| MASARI | 90602 |
| VALUE | 90605 |
| VECTOR | 90608 |
| FINAMEX | 90616 |
| VALMEX | 90617 |
| PROFUTURO | 90620 |
| CB INTERCAM | 90630 |
| CI BOLSA | 90631 |
| FINCOMUN | 90634 |
| NU MEXICO | 90638 |
| REFORMA | 90642 |
| STP | 90646 |
| CREDICAPITAL | 90652 |
| KUSPIT | 90653 |
| UNAGRA | 90656 |
| ASP INTEGRA OPC | 90659 |
| ALTERNATIVOS | 90661 |
| LIBERTAD | 90670 |
| CAJA POP MEXICA | 90677 |
| CRISTOBAL COLON | 90680 |
| CAJA TELEFONIST | 90683 |
| TRANSFER | 90684 |
| FONDO (FIRA) | 90685 |
| INVERCAP | 90686 |
| FOMPED | 90689 |
| TESORED | 90703 |
| ARCUS | 90706 |
| NVIO | 90710 |
| Mercado Pago W | 90722 |
| CUENCA | 90723 |
| INDEVAL | 90902 |
| CoDi Valida | 90903 |
| SANTANDER2* | 90814 |
| BANAMEX2 | 91802 |
| BBVA BANCOMER2* | 91812 |
| SANTANDER2* | 91814 |
| HSBC2* | 91821 |
| BANORTE2* | 91872 |
| AZTECA2* | 91927 |
| SPIN BY OXXO | 90728 |
| FONDEADORA | 90699 |
| ALBO | 90721 |
| HEY BANCO | 40167 |