- 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
userId
andcustomData
. - 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:
userTokenId
amount
– must be greater than 0 (zero)currency
paymentOption.alternativePaymentMethod
class containing:paymentMethod
: “apmgw_SPEI“
deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,country
,email
userDetails
class 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.alternativePaymentMethod
class containing:paymentMethod
: “apmgw_SPEI“
deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,country
,email
userDetails
class 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
sessionToken
Press here for details.
2. Send a
/payment
RequestPerform the payment by sending a
/payment
request with its mandatory parameters including:userTokenId
amount
– must be greater than 0 (zero)currency
paymentOption.alternativePaymentMethod
class containing:paymentMethod
: “apmgw_SPEI“
deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,country
,email
userDetails
class 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. - 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
sessionToken
received from the server call to/openOrder
.3. Create an APM Payment
Send a createPayment() request with its mandatory parameters including:
paymentOption.alternativePaymentMethod
class containing:paymentMethod
: “apmgw_SPEI“
deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,country
,email
userDetails
class 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/openOrder
request. - 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:
userTokenId
amount
: “0” (zero)currency
paymentOption.alternativePaymentMethod
class containing:paymentMethod
: “apmgw_STPmex“
deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,country
,email
userDetails
class 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.alternativePaymentMethod
class containing:paymentMethod
: “apmgw_STPmex“
deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,country
,email
userDetails
class 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
sessionToken
Press here for details.
2. Send a
/payment
RequestSend a
/payment
request with its mandatory parameters including:userTokenId
amount
: “0” (zero)currency
paymentOption.alternativePaymentMethod
class containing:paymentMethod
: “apmgw_STPmex“
deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,country
,email
userDetails
class 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. - 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
sessionToken
received from the server call to/openOrder
.3. Create an APM Payment
Send a createPayment() request with its mandatory parameters including:
paymentOption.alternativePaymentMethod
class containing:paymentMethod
: “apmgw_STPmex“
deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,country
,email
userDetails
class 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/openOrder
request. - 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
/accountCapture
method. - By creating a UPO, which represents the customer’s bank account details, with the
/addUPOAPM
method.
Press tab to open…
- Generate a
sessionToken
. Press here for details. - 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“currencyCode
: MXNcountryCode
: MX
Example
/accountCapture
Request{ "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
/accountCapture
Response{ "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
redirectUrl
to 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 createduserPaymentOptionId
tourlDetails.notificationUrl
, which Nuvei recommends including in the/accountCapture
request. - Send a
/payout
request 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“apmData
class containing:beneficiaryBank
– Press here to see list of supportedbeneficiaryBank
codes.beneficiaryName
beneficiaryNumber
beneficiaryType
billingAddress
class containing:country
andemail
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
/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“currencyCode
: MXNcountryCode
: MX
Example
/accountCapture
Request{ "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
/accountCapture
Response{ "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
redirectUrl
to 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 createduserPaymentOptionId
tourlDetails.notificationUrl
, which Nuvei recommends including in the/accountCapture
request. - Send a
/payout
request and include theuserPaymentOptionId
, which contains the user’s previously stored APM account details. Press here for an example.
- Generate a
-
/addUPOAPM
-
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, includingemail
,countryCode
,firstName
, andlastName
.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 auserPaymentOptionId
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“apmData
class containing:beneficiaryBank
– Press here to see list of supportedbeneficiaryBank
codes.beneficiaryName
beneficiaryNumber
beneficiaryType
billingAddress
class containing:country
andemail
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
RequestSend a
/payout
request 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 /payout
with SPEI, the following two methods can be used to process a /payout
request:
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“currencyCode
countryCode
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“apmData
class containing:beneficiaryBank
– Press here to see list of supportedbeneficiaryBank
codes.beneficiaryName
beneficiaryNumber
beneficiaryType
billingAddress
class containing:country
andemail
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
sessionToken
received 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“currencyCode
countryCode
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
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
tourlDetails.notificationUrl
, which Nuvei recommends including in the/accountCapture
request.4. Send a
/payout
RequestSend a
/payout
request and include theuserPaymentOptionId
, which contains the user’s previously stored APM account details. Press here for an example. -
addApmUpo()
-
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, includingemail
,countryCode
,firstName
, andlastName
.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 auserPaymentOptionId
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“apmData
class containing:beneficiaryBank
– Press here to see list of supportedbeneficiaryBank
codes.beneficiaryName
beneficiaryNumber
beneficiaryType
billingAddress
class containing:country
andemail
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
userPaymentOptionId
representing the user’s APM account details.Example
addApmUpo()
Response{ "result": "ADDED", "errCode": 0, "errorDescription": "", "userPaymentOptionId": "14958143", "cancelled": false }
3. Send a
/payout
RequestSend a
/payout
request 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 |
ABC CAPITAL | 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 |
MULTIVA CBOLSA | 90613 |
FINAMEX | 90616 |
VALMEX | 90617 |
PROFUTURO | 90620 |
CB INTERCAM | 90630 |
CI BOLSA | 90631 |
FINCOMUN | 90634 |
NU MEXICO | 90638 |
REFORMA | 90642 |
STP | 90646 |
TACTIV CB | 90648 |
CREDICAPITAL | 90652 |
KUSPIT | 90653 |
UNAGRA | 90656 |
ASP INTEGRA OPC | 90659 |
ALTERNATIVOS | 90661 |
LIBERTAD | 90670 |
CAJA POP MEXICA | 90677 |
CRISTOBAL COLON | 90680 |
CAJA TELEFONIST | 90683 |
OPM | 90684 |
FONDO (FIRA) | 90685 |
INVERCAP | 90686 |
FOMPED | 90689 |
TESORED | 90703 |
ARCUS | 90706 |
NVIO | 90710 |
INDEVAL | 90902 |
CoDi Valida | 90903 |
SANTANDER2* | 90814 |
BANAMEX2 | 91802 |
BBVA BANCOMER2* | 91812 |
SANTANDER2* | 91814 |
HSBC2* | 91821 |
BANORTE2* | 91872 |
AZTECA2* | 91927 |