- METHOD TYPEACH
- PAYMENTS
- PAYOUTS
- REFUNDS
- RECURRING
Introduction
ACH (Automated Clearing House) is a US-based financial network used for electronic payments and money transfers. ACH payments, also known as “direct payments”, are a way to transfer money from one bank account to another without using paper checks, credit card networks, wire transfers, or cash.
Nuvei supports a growing number of ACH APM integrations, which are available via our payment technology platforms.
This guide describes how to integrate the following ACH APMs into your payment flows:
- The “Bank Transfer (ACH)” APM
- The “Secure Bank Transfer” APM
Supported Countries
- United States
Supported Currencies
- USD
APM Overview
Bank Transfer (ACH) APM
APM Name | Nuvei APM | Integration Methods | ||
REST API | Web SDK | Checkout SDK | ||
ACH | apmgw_ACH | ✓ | ✓ | ✓ |
APM Flow: | This APM uses a "Direct" workflow. | |||
Notes: |
|
Secure Bank Transfer APM
Nuvei’s Secure Bank Transfer ACH solution allows e-commerce merchants in the US to accept ACH payments. Third-party verification tools (like Plaid) are utilized by Nuvei, to validate transactions in real-time, validate consumers, as well as generate consumer risk assessments.
APM Name | Nuvei APM | Integration Methods | ||
REST API | Web SDK | Checkout SDK | ||
Secure Bank Transfer | apmgw_Secure_Bank_Transfer | ✓ | ✓ | ✓ |
APM Flow: | This APM uses a "Redirect" workflow.
|
Prerequisites and Notes
- This document assumes that you have completed all the account setup prerequisites, and are ready to integrate the APMs into your payment flow.
- ACH only supports US-based IPs. IP addresses outside the US do not work.
- Transactions are conducted in US Dollars.
- Test credentials and testing scenarios should be obtained from Nuvei.
- You can contact Nuvei Support for any type of assistance.
Platform-Specific Notes
Press tab to open…
- In addition to payment request responses, the system sends Direct Merchant Notifications (DMNs) containing the transaction processing results to a specified
notificationUrl
provided by you. This ensures that you receive transaction results that may not always be immediately available. You should include theurlDetails.notificationUrl
in each/payment
and/payout
request.
- Some parameters can be collected in both the
/openOrder
request and thecreatePayment()
request. - When processing a
createPayment()
request, if there are multiple input values for the same parameter, then the system chooses a single parameter value depending on two factors:- The method used to collect the parameter value.
- The JSON class the parameter belongs to.
- In addition to payment request responses, the system sends Direct Merchant Notifications (DMNs) containing the transaction processing results to a specified
notificationUrl
provided by you. This ensures that you receive transaction results that may not always be immediately available. You should include theurlDetails.notificationUrl
in each/openOrder
request.
-
- The
billingAddress
class collected in thecreatePayment()
request. - The
userDetails
class collected in thecreatePayment()
request.
- The
- Make sure that the ACH payment methods described in this guide are included in your Nuvei account.
- When initiating your payment page using the Simply Connect method, set the country to “US” and the currency to “USD” to present these ACH payment methods in the payment method gallery. No further integration steps are required.
- In addition to payment request responses, the system sends Direct Merchant Notifications (DMNs) containing the transaction processing results to a specified
notificationUrl
provided by you. This ensures that you receive transaction results that may not always be immediately available. You should includenotify_url
in each request.
- REST API
-
- In addition to payment request responses, the system sends Direct Merchant Notifications (DMNs) containing the transaction processing results to a specified
notificationUrl
provided by you. This ensures that you receive transaction results that may not always be immediately available. You should include theurlDetails.notificationUrl
in each/payment
and/payout
request.
- In addition to payment request responses, the system sends Direct Merchant Notifications (DMNs) containing the transaction processing results to a specified
- Web SDK
-
- Some parameters can be collected in both the
/openOrder
request and thecreatePayment()
request. - When processing a
createPayment()
request, if there are multiple input values for the same parameter, then the system chooses a single parameter value depending on two factors:- The method used to collect the parameter value.
- The JSON class the parameter belongs to.
- In addition to payment request responses, the system sends Direct Merchant Notifications (DMNs) containing the transaction processing results to a specified
notificationUrl
provided by you. This ensures that you receive transaction results that may not always be immediately available. You should include theurlDetails.notificationUrl
in each/openOrder
request.
-
- The
billingAddress
class collected in thecreatePayment()
request. - The
userDetails
class collected in thecreatePayment()
request.
- The
- Some parameters can be collected in both the
- Simply Connect
-
- Make sure that the ACH payment methods described in this guide are included in your Nuvei account.
- When initiating your payment page using the Simply Connect method, set the country to “US” and the currency to “USD” to present these ACH payment methods in the payment method gallery. No further integration steps are required.
- In addition to payment request responses, the system sends Direct Merchant Notifications (DMNs) containing the transaction processing results to a specified
notificationUrl
provided by you. This ensures that you receive transaction results that may not always be immediately available. You should includenotify_url
in each request.
Bank Transfer (ACH)
You can use the Bank Transfer (ACH) APM integration to perform payments (deposits), payouts (withdrawals), refunds, and voids.
Nuvei stores your customer’s bank account details in an encrypted UPO (User Payment Option) record in the Nuvei system. A UPO represents a customer bank account or another payment method, for use in future transactions with no need for the customer to enter their payment details again.
Contact Nuvei Support for implementation support.
Payments
The payment flow begins on your payment page when a customer selects the Bank Transfer (ACH) payment method.
- For a new customer, or for payment method details that were not previously captured, follow the steps in the Payment (without UPO).
- For a “returning customer”, offer them the option to select one of their previously captured payment methods. Follow the steps in the Payment (with UPO).
Payouts
Refunds
- See the Refund topic.
Voids
- See the Void topic.
Prerequisites and Notes
- A
userPaymentOptionId
(UPO) represents the customer’s bank account in the Nuvei system. It can be used in future payment transactions to represent the customer’s bank account details. - A
preApprovalId
is stored in the UPO record. This is used by the system to automatically approve certain payment transactions when this payment method is used in the future.
ApreApprovalId
indicates that:- The specified customer payment method is authenticated, and there is no need to perform the authentication process again.
- If this is an initial recurring payment, then the customer allows you to create subsequent recurring payments on their behalf, without their presence, according to some rebilling agreement.
Payment (without UPO)
Follow the relevant steps for each environment:
Press tab to open…
- The payment flow begins on your payment page when the customer enters a payment
amount
and selects the Bank Transfer (ACH) payment method. - Prompt the customer to enter:
AccountNumber
– The customer bank account from which to pay.RoutingNumber
– The Bank Routing Number for that bank account.SECCode
– The ACH Standard Entry Class (SEC) code. Required for B2B transactions.firstName
lastName
- Generate a
sessionToken
by sending a/getSessionToken
request. - Send a
/payment
request with its mandatory parameters including:userTokenId
– Unique customer identifier in merchant system.amount
paymentOption.alternativePaymentMethod
class containing:paymentMethod
: “apmgw_ACH“AccountNumber
RoutingNumber
SECCode
deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,phone
,address
,city
,zip
,state
userDetails
class containing:firstName
,lastName
,phone
,address
,city
,zip
,state
,identification
urlDetails.notificationUrl
-
Example
/payment
Request (without UPO){ "sessionToken": "<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "<unique customer identifier in merchant system>", "clientRequestId": "<unique request ID in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "currency": "USD", "amount": "100", "paymentOption": { "alternativePaymentMethod": { "paymentMethod": "apmgw_ACH", "AccountNumber": "111111111", "RoutingNumber": "999999992", "SECCode": "CCD" } }, "deviceDetails": { "ipAddress": "<customer's IP address>" }, "billingAddress": { "firstName": "John", "lastName": "Smith", "phone": "6175551414", "address": "22 Main Street", "city": "Boston", "zip": "02460", "state": "MA", "country": "US" }, "userDetails": { "firstName": "John", "lastName": "Smith", "phone": "6175551414", "address": "22 Main Street", "city": "Boston", "zip": "02460", "state": "MA", "country": "US", "identification": "123456789" }, "urlDetails": { "notificationUrl": "<URL to which DMNs are sent>" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
- The payment flow begins on your payment page when the customer enters a payment
amount
. - Initiate a Session
Send theamount
and auserTokenId
(unique customer identifier in merchant system) in an/openOrder
request, which authenticates and sets up an order in the Nuvei system, and returns asessionToken
. - Initialize the Web SDK
This instantiates the Web SDK with thesessionToken
received from the server call to/openOrder
. - Allow the customer to select the Bank Transfer (ACH) APM as the payment method.
- Prompt the customer to enter:
AccountNumber
– The customer bank account from which to pay.RoutingNumber
– The routing number for that account.firstName
lastName
- Send a createPayment() request with its mandatory parameters including:
sessionToken
paymentOption.alternativePaymentMethod
class containing:paymentMethod
: “apmgw_ACH“AccountNumber
RoutingNumber
deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,phone
,address
,city
,zip
,state
userDetails
class containing:firstName
,lastName
,phone
,address
,city
,zip
,state
,identification
Example createPayment()
Request (without UPO)
sfc.createPayment({ sessionToken: "<sessiontoken>", paymentOption: { alternativePaymentMethod: { paymentMethod: "apmgw_ACH", AccountNumber: document.getElementById("AccountNumber").value, RoutingNumber: document.getElementById("RoutingNumber").value } }, deviceDetails: { ipAddress: "<customer's IP address>" }, billingAddress: { firstName: "John", lastName: "Smith", phone: "6175551414", address: "22 Main Street", city: "Boston", zip: "02460", state: "MA", country: "US" }, userDetails: { firstName: "John", lastName: "Smith", phone: "6175551414", address: "22 Main Street", city: "Boston", zip: "02460", state: "MA", country: "US" identification: "123456789" } }, function(res) { console.log(res); })
- The Bank Transfer (ACH) flow begins when the customer selects the Bank Transfer (ACH) payment method from the payment method gallery.
- The customer enters the Account Number, Routing Number, and Amount, and presses the Deposit/Process button.
- REST API
-
- The payment flow begins on your payment page when the customer enters a payment
amount
and selects the Bank Transfer (ACH) payment method. - Prompt the customer to enter:
AccountNumber
– The customer bank account from which to pay.RoutingNumber
– The Bank Routing Number for that bank account.SECCode
– The ACH Standard Entry Class (SEC) code. Required for B2B transactions.firstName
lastName
- Generate a
sessionToken
by sending a/getSessionToken
request. - Send a
/payment
request with its mandatory parameters including:userTokenId
– Unique customer identifier in merchant system.amount
paymentOption.alternativePaymentMethod
class containing:paymentMethod
: “apmgw_ACH“AccountNumber
RoutingNumber
SECCode
deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,phone
,address
,city
,zip
,state
userDetails
class containing:firstName
,lastName
,phone
,address
,city
,zip
,state
,identification
urlDetails.notificationUrl
-
Example
/payment
Request (without UPO){ "sessionToken": "<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "<unique customer identifier in merchant system>", "clientRequestId": "<unique request ID in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "currency": "USD", "amount": "100", "paymentOption": { "alternativePaymentMethod": { "paymentMethod": "apmgw_ACH", "AccountNumber": "111111111", "RoutingNumber": "999999992", "SECCode": "CCD" } }, "deviceDetails": { "ipAddress": "<customer's IP address>" }, "billingAddress": { "firstName": "John", "lastName": "Smith", "phone": "6175551414", "address": "22 Main Street", "city": "Boston", "zip": "02460", "state": "MA", "country": "US" }, "userDetails": { "firstName": "John", "lastName": "Smith", "phone": "6175551414", "address": "22 Main Street", "city": "Boston", "zip": "02460", "state": "MA", "country": "US", "identification": "123456789" }, "urlDetails": { "notificationUrl": "<URL to which DMNs are sent>" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
- The payment flow begins on your payment page when the customer enters a payment
- Web SDK
-
- The payment flow begins on your payment page when the customer enters a payment
amount
. - Initiate a Session
Send theamount
and auserTokenId
(unique customer identifier in merchant system) in an/openOrder
request, which authenticates and sets up an order in the Nuvei system, and returns asessionToken
. - Initialize the Web SDK
This instantiates the Web SDK with thesessionToken
received from the server call to/openOrder
. - Allow the customer to select the Bank Transfer (ACH) APM as the payment method.
- Prompt the customer to enter:
AccountNumber
– The customer bank account from which to pay.RoutingNumber
– The routing number for that account.firstName
lastName
- Send a createPayment() request with its mandatory parameters including:
sessionToken
paymentOption.alternativePaymentMethod
class containing:paymentMethod
: “apmgw_ACH“AccountNumber
RoutingNumber
deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,phone
,address
,city
,zip
,state
userDetails
class containing:firstName
,lastName
,phone
,address
,city
,zip
,state
,identification
Example
createPayment()
Request (without UPO)sfc.createPayment({ sessionToken: "<sessiontoken>", paymentOption: { alternativePaymentMethod: { paymentMethod: "apmgw_ACH", AccountNumber: document.getElementById("AccountNumber").value, RoutingNumber: document.getElementById("RoutingNumber").value } }, deviceDetails: { ipAddress: "<customer's IP address>" }, billingAddress: { firstName: "John", lastName: "Smith", phone: "6175551414", address: "22 Main Street", city: "Boston", zip: "02460", state: "MA", country: "US" }, userDetails: { firstName: "John", lastName: "Smith", phone: "6175551414", address: "22 Main Street", city: "Boston", zip: "02460", state: "MA", country: "US" identification: "123456789" } }, function(res) { console.log(res); })
- The payment flow begins on your payment page when the customer enters a payment
- Simply Connect
-
- The Bank Transfer (ACH) flow begins when the customer selects the Bank Transfer (ACH) payment method from the payment method gallery.
- The customer enters the Account Number, Routing Number, and Amount, and presses the Deposit/Process button.
Handling the Response
As the transaction progresses in the flow from PENDING to UPDATE to APPROVED, you receive responses and DMNs:
transactionStatus
=PENDING:
The request returns:- A response that includes
transactionStatus
: PENDING and a"userPaymentOptionId"
.
Example of Some Parameters Returned
{ ... ... "transactionId":"36682151", "paymentOption": { "userPaymentOptionId": "8100521", "card": {} }, "transactionStatus": "PENDING", ... ... }
- A DMN containing
status
=PENDING.
See Example DMN with status=PENDING.
- A response that includes
transactionStatus
=UPDATE:- After a short time period, a
preApprovalId
is generated and stored in the UPO record. - You receive a DMN containing
status
=UPDATE.
See Example DMN with status=UPDATE.
- After a short time period, a
transactionStatus
=APPROVED:
The request is processed and returns a transaction notification with the final status within 2–5 days.- If the transfer is successful, then the following is returned:
- A response with
status
=APPROVED. - A DMN containing
status
=APPROVED.
See Example DMN with status=APPROVED.
- A response with
- If the transfer is not successful, then the following is returned:
- A response with
status
=DECLINED. - A DMN containing
status
=DECLINED.
- A response with
- If the transfer is successful, then the following is returned:
Payment (with UPO)
Follow the relevant steps for each environment:
Press tab to open…
- The payment flow begins on your payment page when a “returning customer” enters a payment
amount
and selects the Bank Transfer (ACH) payment method. - Call a /getUserUPOs request to retrieve a list of the customer’s UPOs.
(If no appropriate UPOs are returned, then skip the rest of these steps, and perform the steps in the Payment (without UPO) flow instead.) - Offer the “returning customer” the option to select one of their previously captured payment methods (stored in a UPO record, representing the customer’s bank account), instead of collecting their bank account details again.
- If the customer selects one of their previously captured payment methods (UPOs), then continue with the next step.
- If not, then skip the rest of these steps, and perform the steps in the Payment (without UPO) flow instead.
- Generate a
sessionToken
by sending a/getSessionToken
request. - Send a
/payment
request with its mandatory parameters including:userTokenId
– Unique customer identifier in merchant system.amount
paymentOption.userPaymentOptionId
: “<ID of a previously stored payment option>“deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,country
urlDetails.notificationUrl
Example of /payment
Request (with UPO)
{ "sessionToken": "<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "<unique customer identifier in merchant system>", "clientRequestId": "<unique request ID in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "currency": "USD", "amount": "100", "paymentOption": { "userPaymentOptionId": "8100521" }, "deviceDetails": { "ipAddress": "<customer's IP address>" }, "billingAddress": { "firstName": "John", "lastName": "Smith", "country": "US" }, "urlDetails": { "notificationUrl": "<URL to which DMNs are sent>" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
- The payment flow begins on your payment page when a “returning customer” enters a payment
amount
. - Initiate a Session
Send theamount
and auserTokenId
(unique customer identifier in merchant system) in an/openOrder
request, which authenticates and sets up an order in the Nuvei system, and returns asessionToken
. - Initialize the Web SDK
This instantiates the Web SDK with thesessionToken
received from the server call to/openOrder
. - Allow the customer to select the Bank Transfer (ACH) APM as the payment method.
- Call a /getUserUPOs request to retrieve a list of the customer’s UPOs.
(If no appropriate UPOs are returned, then skip the rest of these steps, and perform the steps in the Payment (without UPO) flow instead.) - Offer the “returning customer” the option to select one of their previously captured payment methods (stored in a UPO record, representing the customer’s bank account), instead of collecting their bank account details again.
- If the customer selects one of their previously captured payment methods (UPOs), then continue with the next step.
- If not, then skip the rest of these steps, and perform the steps in the Payment (without UPO) flow instead.
- Send a createPayment() request with its mandatory parameters including:
userTokenId
– Unique customer identifier in merchant system.amount
paymentOption.userPaymentOptionId
: “<ID of a previously stored payment option>“deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,country
urlDetails.notificationUrl
Example createPayment()
Request (With UPO)
sfc.createPayment({ sessionToken: "<sessiontoken>", paymentOption: { userPaymentOptionId: "8100521" }, deviceDetails: { ipAddress: "<customer's IP address>" }, billingAddress: { firstName: "John", lastName: "Smith", country: "US" }, urlDetails: { notificationUrl: "<URL to which DMNs are sent>" }, }, function(res) { console.log(res); });
- The Bank Transfer (ACH) flow begins when the customer selects the Bank Transfer (ACH) payment method from the payment method gallery.
- The customer selects one of their previously captured payment methods (UPOs), enters an amount, and presses the Deposit/Process button.
- REST API
-
- The payment flow begins on your payment page when a “returning customer” enters a payment
amount
and selects the Bank Transfer (ACH) payment method. - Call a /getUserUPOs request to retrieve a list of the customer’s UPOs.
(If no appropriate UPOs are returned, then skip the rest of these steps, and perform the steps in the Payment (without UPO) flow instead.) - Offer the “returning customer” the option to select one of their previously captured payment methods (stored in a UPO record, representing the customer’s bank account), instead of collecting their bank account details again.
- If the customer selects one of their previously captured payment methods (UPOs), then continue with the next step.
- If not, then skip the rest of these steps, and perform the steps in the Payment (without UPO) flow instead.
- Generate a
sessionToken
by sending a/getSessionToken
request. - Send a
/payment
request with its mandatory parameters including:userTokenId
– Unique customer identifier in merchant system.amount
paymentOption.userPaymentOptionId
: “<ID of a previously stored payment option>“deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,country
urlDetails.notificationUrl
Example of
/payment
Request (with UPO){ "sessionToken": "<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "<unique customer identifier in merchant system>", "clientRequestId": "<unique request ID in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "currency": "USD", "amount": "100", "paymentOption": { "userPaymentOptionId": "8100521" }, "deviceDetails": { "ipAddress": "<customer's IP address>" }, "billingAddress": { "firstName": "John", "lastName": "Smith", "country": "US" }, "urlDetails": { "notificationUrl": "<URL to which DMNs are sent>" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
- The payment flow begins on your payment page when a “returning customer” enters a payment
- Web SDK
-
- The payment flow begins on your payment page when a “returning customer” enters a payment
amount
. - Initiate a Session
Send theamount
and auserTokenId
(unique customer identifier in merchant system) in an/openOrder
request, which authenticates and sets up an order in the Nuvei system, and returns asessionToken
. - Initialize the Web SDK
This instantiates the Web SDK with thesessionToken
received from the server call to/openOrder
. - Allow the customer to select the Bank Transfer (ACH) APM as the payment method.
- Call a /getUserUPOs request to retrieve a list of the customer’s UPOs.
(If no appropriate UPOs are returned, then skip the rest of these steps, and perform the steps in the Payment (without UPO) flow instead.) - Offer the “returning customer” the option to select one of their previously captured payment methods (stored in a UPO record, representing the customer’s bank account), instead of collecting their bank account details again.
- If the customer selects one of their previously captured payment methods (UPOs), then continue with the next step.
- If not, then skip the rest of these steps, and perform the steps in the Payment (without UPO) flow instead.
- Send a createPayment() request with its mandatory parameters including:
userTokenId
– Unique customer identifier in merchant system.amount
paymentOption.userPaymentOptionId
: “<ID of a previously stored payment option>“deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,country
urlDetails.notificationUrl
Example
createPayment()
Request (With UPO)sfc.createPayment({ sessionToken: "<sessiontoken>", paymentOption: { userPaymentOptionId: "8100521" }, deviceDetails: { ipAddress: "<customer's IP address>" }, billingAddress: { firstName: "John", lastName: "Smith", country: "US" }, urlDetails: { notificationUrl: "<URL to which DMNs are sent>" }, }, function(res) { console.log(res); });
- The payment flow begins on your payment page when a “returning customer” enters a payment
- Simply Connect
-
- The Bank Transfer (ACH) flow begins when the customer selects the Bank Transfer (ACH) payment method from the payment method gallery.
- The customer selects one of their previously captured payment methods (UPOs), enters an amount, and presses the Deposit/Process button.
Handling the Response
You receive a DMN as the transactionStatus
progresses from PENDING to UPDATE to APPROVED:
(The next steps are identical to the steps in Payment (without UPO) above.)
Payout
A payout is performed using the REST API /payout
request.
Prerequisites
A /payout
request is performed using a UPO (representing the customer bank account).
UPOs can be generated in the following ways:
- A UPO is automatically created upon successful completion of a
/payment
request, as described in the payment topics. - Alternatively, you can generate a UPO as described in the Generating UPOs topic.
Sending a /payout
Request
Call the /payout
request with its mandatory parameters including:
userTokenId
– Unique customer identifier in merchant system.userPaymentOption
class containing:userPaymentOptionId
deviceDetails
class containing:ipAddress
urlDetails.notificationUrl
- The following parameters may be required if they are not already stored in the UPO:
userDetails
class containing:firstName
,lastName
,email
If they are not present, please use the /updateUser method to add them.
Example /payout
Request
{ "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "<unique customer identifier in merchant system>", "clientRequestId": "<unique request ID in merchant system>", "currency": "USD", "amount": "100", "userPaymentOption": { "userPaymentOptionId": "<UPO received from previous deposit>" }, "deviceDetails": { "ipAddress": "<customer's IP address>" }, "urlDetails": { "notificationUrl": "<URL to which DMNs are sent>" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
The request is processed and returns a transaction notification with the final status.
- If the transaction is successful, then the following is returned:
- A response with
status
=APPROVED. - A DMN containing
status=
APPROVED.
- A response with
- If the transaction is not successful, then the following is returned:
- A response with
status
=DECLINED. - A DMN containing
status
=DECLINED.
- A response with
Example /payout
Response
{ "reason": "", "transactionStatus": "APPROVED", "clientRequestId": "W1Q3SBGE4", "internalRequestId": 17817071, "version": "1.0", "transactionId": "2110000000004333013", "merchantSiteId": "126006", "merchantId": "2502136204546424962", "additionalTransactionBankId": "1802509592" "clientUniqueId": "695701003", "errCode": 0, "userPaymentOptionId": "8054521", "paymentMethodErrorCode": 0, "userTokenId": "CEBQK9OVSLJA", "externalTransactionId": "2110000000068709", "status": "SUCCESS" }
Refund
See the Refund topic.
Voids
See the topic.
Secure Bank Transfer
You can use the Secure Bank Transfer APM integration to perform payments (deposits), payouts (withdrawals), and refunds.
Contact Nuvei Support for implementation support.
Payments
The payment flow begins on your payment page when a customer selects the Secure Bank Transfer payment method.
- For a new customer, follow the steps in the Payment (without UPO) flow.
- For a “returning customer”, offer them the option to select one of their previously captured payment methods. Follow the steps in the Payment (with UPO) flow.
Payouts
- Payout (same flow as for Bank Transfer (ACH))
Refunds
- See the Refund topic.
Prerequisites and Notes
- A
userPaymentOptionId
represents the customer’s bank account in the Nuvei system. It can be used in future payment transactions to represent the customer’s bank account details. - A
preApprovalId
is stored in the UPO record. This is used by the system to automatically approve certain payment transactions when this payment method is used in the future.
ApreApprovalId
indicates that:- The specified customer payment method is authenticated, and there is no need to perform the authentication process again.
- If this is an initial recurring payment, then the customer allows you to create subsequent recurring payments on their behalf, without their presence, according to some rebilling agreement.
- You have the option to enable the Privacy Policy acceptance (optional) feature, by contacting Nuvei to configure this feature in your merchant account.
This feature forces customers who are using the Secure Bank Transfer APM for the first time to agree to the “Privacy Notice”, before allowing them to continue to the next step. If you choose to use this feature, then:- You should display a link for the customer to view the Nuvei Privacy Notice (https://nuvei.com/privacy-notice/).
- Provide a checkbox for the customer to accept the “Privacy Notice”, before being allowed to continue to the next step.
For example, “I agree to the Privacy Policy”.
- You have the option to enable the “Automatic Transaction Approval” (optional) feature, however, you are responsible for all losses from “returned transactions” and other risks.
To enable this, contact Nuvei to configure this feature in your merchant account.
Payment (without UPO)
Follow the relevant steps for each environment:
Press tab to open…
- The payment flow begins on your payment page when the customer enters an
amount
they wish to transfer, and selects the Secure Bank Transfer payment method. - This is an optional step, if you enabled the “Privacy Notice” acceptance option (see the prerequisite above):
- Display a “Privacy Notice” link for the customer to press to view the Nuvei Privacy Notice (https://nuvei.com/privacy-notice/).
- Display the “I agree to the Privacy Policy” checkbox, which the customer must select before allowing them to continue to the next step.
- Prompt the customer to enter their user details:
firstName
,lastName
,email
,phone
,address
,city
,zip
,state
,identification
. - Generate a
sessionToken
by sending a/getSessionToken
request. - Send a
/payment
request with its mandatory parameters including:userTokenId
– Unique customer identifier in merchant system.amount
paymentOption.alternativePaymentMethod
: “apmgw_Secure_Bank_Transfer“deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,email
,phone
,address
,city
,zip
,state
userDetails
class containing:firstName
,lastName
,email
,phone
,address
,city
,zip
,state
,identification
urlDetails.notificationUrl
Example
/payment
Request (without UPO){ "sessionToken": "<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "<unique customer identifier in merchant system>", "clientRequestId": "<unique request ID in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "currency": "USD", "amount": "100", "paymentOption": { "alternativePaymentMethod": { "paymentMethod": "apmgw_Secure_Bank_Transfer" } }, "billingAddress": { "firstName": "John", "lastName": "Smith", "email": "[email protected]", "phone": "6175551414", "address": "22 Main Street", "city": "Boston", "zip": "02460", "state": "MA", "country": "US" }, "userDetails": { "firstName": "John", "lastName": "Smith", "email": "[email protected]", "phone": "6175551414", "address": "22 Main Street", "city": "Boston", "zip": "02460", "state": "MA", "country": "US", "identification": "123456789" }, "deviceDetails": { "ipAddress": "<customer's IP address>" }, "urlDetails": { "notificationUrl": "<URL to which DMNs are sent>" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
- A successful request returns a
paymentOption.redirectUrl
(to a Secure Bank Transfer URL).
Example of a Successful Response with a
paymentOption.redirectUrl
{ "reason": "", "orderId": "36298881", "transactionStatus": "REDIRECT", "clientRequestId": "GF1XTXTBM", "internalRequestId": 17817111, "version": "1.0", "merchantSiteId": "126006", "merchantId": "2502136204546424962", "clientUniqueId": "695701003", "errCode": 0, "paymentOption": { "redirectUrl": "https://cdn-int.safecharge.com/safecharge_resources/v1/get_to_post/index.html?eyJhbGciOiJSUzI1NiJ9.eyJkZXRhaWxzIjoiNzRDQkZEODMyOUI1RDMwMjNDM0YwNUJERThGRkFEMDRGQUNEMURCQUZFMEYxM0QwMzhFQkU5RjRCMzhFMTY2RTY5NEI0QzhDMDg2RjYzMDM2RTdCMkIyREVBRjRENTIyNkM2RDg1RUE5NkI2QjIzNjEzMUVBREI0NDBGRjU0QzE0RThGM0ZCODg2QzUwQzcyMTYxMURBMkNBQzg1NzI2NjRCOEE4ODE0MThEMkJCMjBFNTAzRDE4MTRBMkJBM0M1NjM3RDBCNkFFRDU5MUVFQzk2NEQwMUE2OEFFRUQyMDBBMUJBRUQ4RUIxNDBGNEEwQkQ2OTE3MzYxMEM4Rjg1MTAwMjMxREEzQkRDNUZGMkNGOUNGRURCQkZFMTQ2REEwMDdCQUY4QUUzN0Q1Q0JEQTYzOTQyNDhGMkFEQzhFMzMyODU4NzQ5MzUyNTI2NDFFREREM0Q4ODEwQTE3RkVCNTlBMjY4ODBCMkI2NjYzRkVENjk3RjRBMDhERTFBNzVDRDdBMzk2MzBGRjJBREU1Mjk0N0FERjFFQUVFMDA4Nzg4Q0REN0RCNjM5M0QwRTNEOTFBQkVERTY3MDFBMUQ0RkU3M0M3RTQwNUQ5RjlCNzZDMUYxRjQ5QzIxMjU4RERENDVDQUFDNTNERDg4MEVBNTk2Mzk1QzBDRDQ4NUY0OTQ4M0VERURGNDJFRkQzMUJBNkIwMUYwMTFGMTVGNzAyMUI2OTRBOUQ1NTU0OEEyQ0FDNUQ3MzVBNTgyMkJCMEFDOUFCQjhBQzc1Q0UxNzc1NjI0QzY1QUQ1MDU4NTVCRDI5RjFCMjJCMDlCREExM0I1QkFFQ0ZEMTA1MUI2NTQ4QTUxQkJDNDlEOTlCQUI4MUZERjAwNzAyQTBDQ0IyQTk3MDVENzE2MkZFRUQ5RjEzN0ZGN0FGMDUwNUIyMUIwOTY2RDA2NTFFQkRDRDA1MkY0RTE4MDY5ODlCOEFBQjJDMTIxNkIzNzJDREQ5RDQ0RDQ2N0EwOEUwQjI4MkUzOTkwNjAwOTcyQ0NDNEYwQjZEMDdERDg1ODk2MDYzM0UwNkExQ0VGRTY0OEExNzBDOTA3RjA3Qzg4NDA4NDI0MzQzRjNGQjM1MDZFN0EzRkEwNkQ0MDY5M0QyQkE3MzBGQTdCNzc3NDFFQUU2NDg2NEI2NjE3MDdGMzY0MDNCMTQyOTJDMTM1NzI5NDUwQ0YxRDk3NTcxQUE5NzJDQzg1MTVGQSIsIm1lcmNoYW50X2lkIjoiU2ZDaGFyZ2UiLCJpdiI6Ijk5RTM0MEMyNzg0MkNBOTlCQkIxQzUyNzVFQUFFNURBIiwidXJsIjoiaHR0cHM6Ly9zdGFnaW5nLnZlcmlmaWVkYWNoLmNvbS9jb25zdW1lci9BY3F1aXJlSW5mb0dhdGV3YXkuZG8ifQ.EF3K5UsPQYdua_YcRd9Yefl-KemNwEMq5-EXV7QWAZUbCQglncAaAHzzlW-sxq2XcVZcZ2qbxLkQqjzkB3tItTGUDmqysL-opqOdaaz54EKeHKC5hzQIp77DucIGYQhPxfOB_eAxTOPLvZ85c3woJ37m8BH8kuJPSoAjYrZ12geEQJQx4R2VxNT3QsxxryEWZvU1yKc8mjCl011nWz6cp4LZpHIMwUwvdCMJWUeJtAxC-Q6Ec4NqP93AFki9Ln0OOvenbOEBn3UpK_BncxKu7RFOzM8w4kSf0eopKC44awlROwZaO0k0htJAUikA_W-fgeLISuMpHmWMZz6X3Ju2Bg", "userPaymentOptionId": "8061731", "card": {} }, "sessionToken": "6fa38ea2-6f1a-4620-85ae-7deaf0d5f8f1", "userTokenId": "2J6QZH3UF9E2", "status": "SUCCESS" }
- Redirect the customer to their bank’s site, so they can capture the bank account details of the account they want to pay from.
- The payment flow begins on your payment page when the customer enters a payment
amount
. - Initiate a Session
Send theamount
and auserTokenId
(unique customer identifier in merchant system) in an/openOrder
request, which authenticates and sets up an order in the Nuvei system, and returns asessionToken
. - Initialize the Web SDK
This instantiates the Web SDK with thesessionToken
received from the server call to/openOrder
. - This is an optional step, if you enabled the “Privacy Notice” acceptance option (see the prerequisite above):
- Display a “Privacy Notice” link for the customer to press to view the Nuvei Privacy Notice (https://nuvei.com/privacy-notice/).
- Display the “I agree to the Privacy Policy” checkbox, which the customer must select before allowing them to continue to the next step.
- Allow the customer to select the Secure Bank Transfer APM as the payment method.
- Prompt the customer to enter their user details:
firstName
,lastName
,email
,phone
,address
,city
,zip
,state
,identification
. - Send a createPayment() request with its mandatory parameters including:
userTokenId
– Unique customer identifier in merchant system.amount
paymentOption.alternativePaymentMethod
: “apmgw_Secure_Bank_Transfer“deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,email
,phone
,address
,city
,zip
,state
userDetails
class containing:firstName
,lastName
,email
,phone
,address
,city
,zip
,state
,identification
urlDetails.notificationUrl
Example
createPayment()
Request (without UPO)sfc.createPayment({ sessionToken: "<sessiontoken>", paymentOption: { alternativePaymentMethod: { paymentMethod: "apmgw_Secure_Bank_Transfer" } }, deviceDetails: { ipAddress: "<customer's IP address>" }, billingAddress: { firstName: "John", lastName: "Smith", email: "[email protected]", phone: "6175551414", address: "22 Main Street", city: "Boston", zip: "02460", state: "MA", country: "US" }, userDetails: { firstName: "John", lastName: "Smith", email: "[email protected]", phone: "6175551414", address: "22 Main Street", city: "Boston", zip: "02460", state: "MA", country: "US", identification: "123456789" }, urlDetails: { notificationUrl: "<URL to which DMNs are sent>" }, }, function(res) { console.log(res); });
- A successful request returns a
paymentOption.redirectUrl
(to a Secure Bank Transfer URL).
Example of a Successful Response with a
paymentOption.redirectUrl
{ "reason": "", "orderId": "36298881", "transactionStatus": "REDIRECT", "clientRequestId": "GF1XTXTBM", "internalRequestId": 17817111, "version": "1.0", "merchantSiteId": "126006", "merchantId": "2502136204546424962", "clientUniqueId": "695701003", "errCode": 0, "paymentOption": { "redirectUrl": "https://cdn-int.safecharge.com/safecharge_resources/v1/get_to_post/index.html?eyJhbGciOiJSUzI1NiJ9.eyJkZXRhaWxzIjoiNzRDQkZEODMyOUI1RDMwMjNDM0YwNUJERThGRkFEMDRGQUNEMURCQUZFMEYxM0QwMzhFQkU5RjRCMzhFMTY2RTY5NEI0QzhDMDg2RjYzMDM2RTdCMkIyREVBRjRENTIyNkM2RDg1RUE5NkI2QjIzNjEzMUVBREI0NDBGRjU0QzE0RThGM0ZCODg2QzUwQzcyMTYxMURBMkNBQzg1NzI2NjRCOEE4ODE0MThEMkJCMjBFNTAzRDE4MTRBMkJBM0M1NjM3RDBCNkFFRDU5MUVFQzk2NEQwMUE2OEFFRUQyMDBBMUJBRUQ4RUIxNDBGNEEwQkQ2OTE3MzYxMEM4Rjg1MTAwMjMxREEzQkRDNUZGMkNGOUNGRURCQkZFMTQ2REEwMDdCQUY4QUUzN0Q1Q0JEQTYzOTQyNDhGMkFEQzhFMzMyODU4NzQ5MzUyNTI2NDFFREREM0Q4ODEwQTE3RkVCNTlBMjY4ODBCMkI2NjYzRkVENjk3RjRBMDhERTFBNzVDRDdBMzk2MzBGRjJBREU1Mjk0N0FERjFFQUVFMDA4Nzg4Q0REN0RCNjM5M0QwRTNEOTFBQkVERTY3MDFBMUQ0RkU3M0M3RTQwNUQ5RjlCNzZDMUYxRjQ5QzIxMjU4RERENDVDQUFDNTNERDg4MEVBNTk2Mzk1QzBDRDQ4NUY0OTQ4M0VERURGNDJFRkQzMUJBNkIwMUYwMTFGMTVGNzAyMUI2OTRBOUQ1NTU0OEEyQ0FDNUQ3MzVBNTgyMkJCMEFDOUFCQjhBQzc1Q0UxNzc1NjI0QzY1QUQ1MDU4NTVCRDI5RjFCMjJCMDlCREExM0I1QkFFQ0ZEMTA1MUI2NTQ4QTUxQkJDNDlEOTlCQUI4MUZERjAwNzAyQTBDQ0IyQTk3MDVENzE2MkZFRUQ5RjEzN0ZGN0FGMDUwNUIyMUIwOTY2RDA2NTFFQkRDRDA1MkY0RTE4MDY5ODlCOEFBQjJDMTIxNkIzNzJDREQ5RDQ0RDQ2N0EwOEUwQjI4MkUzOTkwNjAwOTcyQ0NDNEYwQjZEMDdERDg1ODk2MDYzM0UwNkExQ0VGRTY0OEExNzBDOTA3RjA3Qzg4NDA4NDI0MzQzRjNGQjM1MDZFN0EzRkEwNkQ0MDY5M0QyQkE3MzBGQTdCNzc3NDFFQUU2NDg2NEI2NjE3MDdGMzY0MDNCMTQyOTJDMTM1NzI5NDUwQ0YxRDk3NTcxQUE5NzJDQzg1MTVGQSIsIm1lcmNoYW50X2lkIjoiU2ZDaGFyZ2UiLCJpdiI6Ijk5RTM0MEMyNzg0MkNBOTlCQkIxQzUyNzVFQUFFNURBIiwidXJsIjoiaHR0cHM6Ly9zdGFnaW5nLnZlcmlmaWVkYWNoLmNvbS9jb25zdW1lci9BY3F1aXJlSW5mb0dhdGV3YXkuZG8ifQ.EF3K5UsPQYdua_YcRd9Yefl-KemNwEMq5-EXV7QWAZUbCQglncAaAHzzlW-sxq2XcVZcZ2qbxLkQqjzkB3tItTGUDmqysL-opqOdaaz54EKeHKC5hzQIp77DucIGYQhPxfOB_eAxTOPLvZ85c3woJ37m8BH8kuJPSoAjYrZ12geEQJQx4R2VxNT3QsxxryEWZvU1yKc8mjCl011nWz6cp4LZpHIMwUwvdCMJWUeJtAxC-Q6Ec4NqP93AFki9Ln0OOvenbOEBn3UpK_BncxKu7RFOzM8w4kSf0eopKC44awlROwZaO0k0htJAUikA_W-fgeLISuMpHmWMZz6X3Ju2Bg", "userPaymentOptionId": "8061731", "card": {} }, "sessionToken": "6fa38ea2-6f1a-4620-85ae-7deaf0d5f8f1", "userTokenId": "2J6QZH3UF9E2", "status": "SUCCESS" }
- Redirect the customer to their bank’s site, so they can capture the bank account details of the account they want to pay from.
- The Secure Bank Transfer flow begins when the customer selects the Secure Bank Transfer payment method from the payment method gallery.
- This is an optional step, if you enabled the “Privacy Notice” acceptance option (see the prerequisite above):
- Display a “Privacy Notice” link for the customer to press to view the Nuvei Privacy Notice (https://nuvei.com/privacy-notice/).
- Display the “I agree to the Privacy Policy” checkbox, which the customer must select before allowing them to continue to the next step.
- The customer enters the Amount and other required details, and presses the Deposit/Process button.
- The customer is redirected to their bank’s site, so they can capture the bank account details of the account they want to pay from.
- REST API
-
- The payment flow begins on your payment page when the customer enters an
amount
they wish to transfer, and selects the Secure Bank Transfer payment method. - This is an optional step, if you enabled the “Privacy Notice” acceptance option (see the prerequisite above):
- Display a “Privacy Notice” link for the customer to press to view the Nuvei Privacy Notice (https://nuvei.com/privacy-notice/).
- Display the “I agree to the Privacy Policy” checkbox, which the customer must select before allowing them to continue to the next step.
- Prompt the customer to enter their user details:
firstName
,lastName
,email
,phone
,address
,city
,zip
,state
,identification
. - Generate a
sessionToken
by sending a/getSessionToken
request. - Send a
/payment
request with its mandatory parameters including:userTokenId
– Unique customer identifier in merchant system.amount
paymentOption.alternativePaymentMethod
: “apmgw_Secure_Bank_Transfer“deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,email
,phone
,address
,city
,zip
,state
userDetails
class containing:firstName
,lastName
,email
,phone
,address
,city
,zip
,state
,identification
urlDetails.notificationUrl
Example
/payment
Request (without UPO){ "sessionToken": "<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "<unique customer identifier in merchant system>", "clientRequestId": "<unique request ID in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "currency": "USD", "amount": "100", "paymentOption": { "alternativePaymentMethod": { "paymentMethod": "apmgw_Secure_Bank_Transfer" } }, "billingAddress": { "firstName": "John", "lastName": "Smith", "email": "[email protected]", "phone": "6175551414", "address": "22 Main Street", "city": "Boston", "zip": "02460", "state": "MA", "country": "US" }, "userDetails": { "firstName": "John", "lastName": "Smith", "email": "[email protected]", "phone": "6175551414", "address": "22 Main Street", "city": "Boston", "zip": "02460", "state": "MA", "country": "US", "identification": "123456789" }, "deviceDetails": { "ipAddress": "<customer's IP address>" }, "urlDetails": { "notificationUrl": "<URL to which DMNs are sent>" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
- A successful request returns a
paymentOption.redirectUrl
(to a Secure Bank Transfer URL).
Example of a Successful Response with a
paymentOption.redirectUrl
{ "reason": "", "orderId": "36298881", "transactionStatus": "REDIRECT", "clientRequestId": "GF1XTXTBM", "internalRequestId": 17817111, "version": "1.0", "merchantSiteId": "126006", "merchantId": "2502136204546424962", "clientUniqueId": "695701003", "errCode": 0, "paymentOption": { "redirectUrl": "https://cdn-int.safecharge.com/safecharge_resources/v1/get_to_post/index.html?eyJhbGciOiJSUzI1NiJ9.eyJkZXRhaWxzIjoiNzRDQkZEODMyOUI1RDMwMjNDM0YwNUJERThGRkFEMDRGQUNEMURCQUZFMEYxM0QwMzhFQkU5RjRCMzhFMTY2RTY5NEI0QzhDMDg2RjYzMDM2RTdCMkIyREVBRjRENTIyNkM2RDg1RUE5NkI2QjIzNjEzMUVBREI0NDBGRjU0QzE0RThGM0ZCODg2QzUwQzcyMTYxMURBMkNBQzg1NzI2NjRCOEE4ODE0MThEMkJCMjBFNTAzRDE4MTRBMkJBM0M1NjM3RDBCNkFFRDU5MUVFQzk2NEQwMUE2OEFFRUQyMDBBMUJBRUQ4RUIxNDBGNEEwQkQ2OTE3MzYxMEM4Rjg1MTAwMjMxREEzQkRDNUZGMkNGOUNGRURCQkZFMTQ2REEwMDdCQUY4QUUzN0Q1Q0JEQTYzOTQyNDhGMkFEQzhFMzMyODU4NzQ5MzUyNTI2NDFFREREM0Q4ODEwQTE3RkVCNTlBMjY4ODBCMkI2NjYzRkVENjk3RjRBMDhERTFBNzVDRDdBMzk2MzBGRjJBREU1Mjk0N0FERjFFQUVFMDA4Nzg4Q0REN0RCNjM5M0QwRTNEOTFBQkVERTY3MDFBMUQ0RkU3M0M3RTQwNUQ5RjlCNzZDMUYxRjQ5QzIxMjU4RERENDVDQUFDNTNERDg4MEVBNTk2Mzk1QzBDRDQ4NUY0OTQ4M0VERURGNDJFRkQzMUJBNkIwMUYwMTFGMTVGNzAyMUI2OTRBOUQ1NTU0OEEyQ0FDNUQ3MzVBNTgyMkJCMEFDOUFCQjhBQzc1Q0UxNzc1NjI0QzY1QUQ1MDU4NTVCRDI5RjFCMjJCMDlCREExM0I1QkFFQ0ZEMTA1MUI2NTQ4QTUxQkJDNDlEOTlCQUI4MUZERjAwNzAyQTBDQ0IyQTk3MDVENzE2MkZFRUQ5RjEzN0ZGN0FGMDUwNUIyMUIwOTY2RDA2NTFFQkRDRDA1MkY0RTE4MDY5ODlCOEFBQjJDMTIxNkIzNzJDREQ5RDQ0RDQ2N0EwOEUwQjI4MkUzOTkwNjAwOTcyQ0NDNEYwQjZEMDdERDg1ODk2MDYzM0UwNkExQ0VGRTY0OEExNzBDOTA3RjA3Qzg4NDA4NDI0MzQzRjNGQjM1MDZFN0EzRkEwNkQ0MDY5M0QyQkE3MzBGQTdCNzc3NDFFQUU2NDg2NEI2NjE3MDdGMzY0MDNCMTQyOTJDMTM1NzI5NDUwQ0YxRDk3NTcxQUE5NzJDQzg1MTVGQSIsIm1lcmNoYW50X2lkIjoiU2ZDaGFyZ2UiLCJpdiI6Ijk5RTM0MEMyNzg0MkNBOTlCQkIxQzUyNzVFQUFFNURBIiwidXJsIjoiaHR0cHM6Ly9zdGFnaW5nLnZlcmlmaWVkYWNoLmNvbS9jb25zdW1lci9BY3F1aXJlSW5mb0dhdGV3YXkuZG8ifQ.EF3K5UsPQYdua_YcRd9Yefl-KemNwEMq5-EXV7QWAZUbCQglncAaAHzzlW-sxq2XcVZcZ2qbxLkQqjzkB3tItTGUDmqysL-opqOdaaz54EKeHKC5hzQIp77DucIGYQhPxfOB_eAxTOPLvZ85c3woJ37m8BH8kuJPSoAjYrZ12geEQJQx4R2VxNT3QsxxryEWZvU1yKc8mjCl011nWz6cp4LZpHIMwUwvdCMJWUeJtAxC-Q6Ec4NqP93AFki9Ln0OOvenbOEBn3UpK_BncxKu7RFOzM8w4kSf0eopKC44awlROwZaO0k0htJAUikA_W-fgeLISuMpHmWMZz6X3Ju2Bg", "userPaymentOptionId": "8061731", "card": {} }, "sessionToken": "6fa38ea2-6f1a-4620-85ae-7deaf0d5f8f1", "userTokenId": "2J6QZH3UF9E2", "status": "SUCCESS" }
- Redirect the customer to their bank’s site, so they can capture the bank account details of the account they want to pay from.
- The payment flow begins on your payment page when the customer enters an
- Web SDK
-
- The payment flow begins on your payment page when the customer enters a payment
amount
. - Initiate a Session
Send theamount
and auserTokenId
(unique customer identifier in merchant system) in an/openOrder
request, which authenticates and sets up an order in the Nuvei system, and returns asessionToken
. - Initialize the Web SDK
This instantiates the Web SDK with thesessionToken
received from the server call to/openOrder
. - This is an optional step, if you enabled the “Privacy Notice” acceptance option (see the prerequisite above):
- Display a “Privacy Notice” link for the customer to press to view the Nuvei Privacy Notice (https://nuvei.com/privacy-notice/).
- Display the “I agree to the Privacy Policy” checkbox, which the customer must select before allowing them to continue to the next step.
- Allow the customer to select the Secure Bank Transfer APM as the payment method.
- Prompt the customer to enter their user details:
firstName
,lastName
,email
,phone
,address
,city
,zip
,state
,identification
. - Send a createPayment() request with its mandatory parameters including:
userTokenId
– Unique customer identifier in merchant system.amount
paymentOption.alternativePaymentMethod
: “apmgw_Secure_Bank_Transfer“deviceDetails
class containing:ipAddress
billingAddress
class containing:firstName
,lastName
,email
,phone
,address
,city
,zip
,state
userDetails
class containing:firstName
,lastName
,email
,phone
,address
,city
,zip
,state
,identification
urlDetails.notificationUrl
Example
createPayment()
Request (without UPO)sfc.createPayment({ sessionToken: "<sessiontoken>", paymentOption: { alternativePaymentMethod: { paymentMethod: "apmgw_Secure_Bank_Transfer" } }, deviceDetails: { ipAddress: "<customer's IP address>" }, billingAddress: { firstName: "John", lastName: "Smith", email: "[email protected]", phone: "6175551414", address: "22 Main Street", city: "Boston", zip: "02460", state: "MA", country: "US" }, userDetails: { firstName: "John", lastName: "Smith", email: "[email protected]", phone: "6175551414", address: "22 Main Street", city: "Boston", zip: "02460", state: "MA", country: "US", identification: "123456789" }, urlDetails: { notificationUrl: "<URL to which DMNs are sent>" }, }, function(res) { console.log(res); });
- A successful request returns a
paymentOption.redirectUrl
(to a Secure Bank Transfer URL).
Example of a Successful Response with a
paymentOption.redirectUrl
{ "reason": "", "orderId": "36298881", "transactionStatus": "REDIRECT", "clientRequestId": "GF1XTXTBM", "internalRequestId": 17817111, "version": "1.0", "merchantSiteId": "126006", "merchantId": "2502136204546424962", "clientUniqueId": "695701003", "errCode": 0, "paymentOption": { "redirectUrl": "https://cdn-int.safecharge.com/safecharge_resources/v1/get_to_post/index.html?eyJhbGciOiJSUzI1NiJ9.eyJkZXRhaWxzIjoiNzRDQkZEODMyOUI1RDMwMjNDM0YwNUJERThGRkFEMDRGQUNEMURCQUZFMEYxM0QwMzhFQkU5RjRCMzhFMTY2RTY5NEI0QzhDMDg2RjYzMDM2RTdCMkIyREVBRjRENTIyNkM2RDg1RUE5NkI2QjIzNjEzMUVBREI0NDBGRjU0QzE0RThGM0ZCODg2QzUwQzcyMTYxMURBMkNBQzg1NzI2NjRCOEE4ODE0MThEMkJCMjBFNTAzRDE4MTRBMkJBM0M1NjM3RDBCNkFFRDU5MUVFQzk2NEQwMUE2OEFFRUQyMDBBMUJBRUQ4RUIxNDBGNEEwQkQ2OTE3MzYxMEM4Rjg1MTAwMjMxREEzQkRDNUZGMkNGOUNGRURCQkZFMTQ2REEwMDdCQUY4QUUzN0Q1Q0JEQTYzOTQyNDhGMkFEQzhFMzMyODU4NzQ5MzUyNTI2NDFFREREM0Q4ODEwQTE3RkVCNTlBMjY4ODBCMkI2NjYzRkVENjk3RjRBMDhERTFBNzVDRDdBMzk2MzBGRjJBREU1Mjk0N0FERjFFQUVFMDA4Nzg4Q0REN0RCNjM5M0QwRTNEOTFBQkVERTY3MDFBMUQ0RkU3M0M3RTQwNUQ5RjlCNzZDMUYxRjQ5QzIxMjU4RERENDVDQUFDNTNERDg4MEVBNTk2Mzk1QzBDRDQ4NUY0OTQ4M0VERURGNDJFRkQzMUJBNkIwMUYwMTFGMTVGNzAyMUI2OTRBOUQ1NTU0OEEyQ0FDNUQ3MzVBNTgyMkJCMEFDOUFCQjhBQzc1Q0UxNzc1NjI0QzY1QUQ1MDU4NTVCRDI5RjFCMjJCMDlCREExM0I1QkFFQ0ZEMTA1MUI2NTQ4QTUxQkJDNDlEOTlCQUI4MUZERjAwNzAyQTBDQ0IyQTk3MDVENzE2MkZFRUQ5RjEzN0ZGN0FGMDUwNUIyMUIwOTY2RDA2NTFFQkRDRDA1MkY0RTE4MDY5ODlCOEFBQjJDMTIxNkIzNzJDREQ5RDQ0RDQ2N0EwOEUwQjI4MkUzOTkwNjAwOTcyQ0NDNEYwQjZEMDdERDg1ODk2MDYzM0UwNkExQ0VGRTY0OEExNzBDOTA3RjA3Qzg4NDA4NDI0MzQzRjNGQjM1MDZFN0EzRkEwNkQ0MDY5M0QyQkE3MzBGQTdCNzc3NDFFQUU2NDg2NEI2NjE3MDdGMzY0MDNCMTQyOTJDMTM1NzI5NDUwQ0YxRDk3NTcxQUE5NzJDQzg1MTVGQSIsIm1lcmNoYW50X2lkIjoiU2ZDaGFyZ2UiLCJpdiI6Ijk5RTM0MEMyNzg0MkNBOTlCQkIxQzUyNzVFQUFFNURBIiwidXJsIjoiaHR0cHM6Ly9zdGFnaW5nLnZlcmlmaWVkYWNoLmNvbS9jb25zdW1lci9BY3F1aXJlSW5mb0dhdGV3YXkuZG8ifQ.EF3K5UsPQYdua_YcRd9Yefl-KemNwEMq5-EXV7QWAZUbCQglncAaAHzzlW-sxq2XcVZcZ2qbxLkQqjzkB3tItTGUDmqysL-opqOdaaz54EKeHKC5hzQIp77DucIGYQhPxfOB_eAxTOPLvZ85c3woJ37m8BH8kuJPSoAjYrZ12geEQJQx4R2VxNT3QsxxryEWZvU1yKc8mjCl011nWz6cp4LZpHIMwUwvdCMJWUeJtAxC-Q6Ec4NqP93AFki9Ln0OOvenbOEBn3UpK_BncxKu7RFOzM8w4kSf0eopKC44awlROwZaO0k0htJAUikA_W-fgeLISuMpHmWMZz6X3Ju2Bg", "userPaymentOptionId": "8061731", "card": {} }, "sessionToken": "6fa38ea2-6f1a-4620-85ae-7deaf0d5f8f1", "userTokenId": "2J6QZH3UF9E2", "status": "SUCCESS" }
- Redirect the customer to their bank’s site, so they can capture the bank account details of the account they want to pay from.
- The payment flow begins on your payment page when the customer enters a payment
- Simply Connect
-
- The Secure Bank Transfer flow begins when the customer selects the Secure Bank Transfer payment method from the payment method gallery.
- This is an optional step, if you enabled the “Privacy Notice” acceptance option (see the prerequisite above):
- Display a “Privacy Notice” link for the customer to press to view the Nuvei Privacy Notice (https://nuvei.com/privacy-notice/).
- Display the “I agree to the Privacy Policy” checkbox, which the customer must select before allowing them to continue to the next step.
- The customer enters the Amount and other required details, and presses the Deposit/Process button.
- The customer is redirected to their bank’s site, so they can capture the bank account details of the account they want to pay from.
Handling the Response
The transaction begins to be processed and the system returns the following responses:
The transaction status progresses from PENDING to UPDATE, and then to APPROVED or DECLINED.
You receive the following responses and DMNs:
transactionStatus
=PENDING:
The request returns:- A response that includes
"transactionStatus"
: PENDING and a"userPaymentOptionId"
.
Example of Some Parameters Returned
{ ... ... "transactionId":"36682151", "paymentOption": { "userPaymentOptionId": "8100521", "card": {} }, "transactionStatus": "PENDING", ... ... }
- A DMN containing
status
=PENDING.
See Example DMN with status=PENDING.
- A response that includes
transactionStatus
=UPDATE:- After a short time period, a
preApprovalId
is generated and stored in the UPO record. - You receive a DMN containing
status
=UPDATE.
See Example DMN with status=UPDATE.
- After a short time period, a
- The request is processed and returns a transaction notification with the final status within 2–5 days.
transactionStatus
=APPROVED:
If the transfer is successful, then the following is returned:- A response with
status
=APPROVED. - A DMN containing
status
=APPROVED.
See Example DMN with status=APPROVED.
- A response with
status=DECLINED
:
If the transfer is not successful, then the following is returned:- A response with
status
=DECLINED. - A DMN containing
status
=DECLINED.
- A response with
Payment (with UPO)
Follow the relevant steps for each environment:
Press tab to open…
- The payment flow begins on your payment page when a “returning customer” enters an
amount
they wish to transfer, and selects the Secure Bank Transfer payment method. - Generate a
sessionToken
by sending a/getSessionToken
request. - Call a /getUserUPOs request to retrieve a list of the customer’s UPOs.
(If no appropriate UPOs are returned, then skip the rest of these steps, and perform the steps in the Payment (without UPO) flow instead.) - Offer the “returning customer” the option to select one of their previously captured payment methods (stored in a UPO record, representing the customer’s bank account), instead of collecting their bank account details again.
- If the customer selects one of their previously captured payment methods (UPOs), then continue with the next step.
- If the customer does not select one of their existing UPOs, then skip the rest of these steps and perform the steps in the Payment (without UPO) flow instead.
- Send a
/payment
request with its mandatory parameters including:userTokenId
– Unique customer identifier in merchant system.amount
userPaymentOptionId
: “<ID of a previously stored payment option>“deviceDetails
class containing:ipAddress
paymentOption.alternativePaymentMethod
: “apmgw_Secure_Bank_Transfer“billingAddress
class containing:firstName
,lastName
,email
,phone
,address
,city
,zip
,state
,country
userDetails
class containing:firstName
,lastName
,email
,phone
,address
,city
,zip
,state
,country
,identification
urlDetails.notificationUrl
Example of /payment
Request (with UPO)
{ "sessionToken": "<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "<unique customer identifier in merchant system>", "clientRequestId": "<unique request ID in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "currency": "USD", "amount": "100", "paymentOption": { "userPaymentOptionId": "8100521", "alternativePaymentMethod": { "paymentMethod": "apmgw_Secure_Bank_Transfer" } }, deviceDetails: { ipAddress: "<customer's IP address>" }, "billingAddress": { "firstName": "John", "lastName": "Smith", "email": "[email protected]", "phone": "6175551414", "address": "22 Main Street", "city": "Boston", "zip": "02460", "state": "MA", "country": "US" }, "userDetails": { "firstName": "John", "lastName": "Smith", "email": "[email protected]", "phone": "6175551414", "address": "22 Main Street", "city": "Boston", "zip": "02460", "state": "MA", "country": "US", "identification": "123456789" }, "urlDetails": { "notificationUrl": "<URL to which DMNs are sent>" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
- The payment flow begins on your payment page when a “returning customer” enters a payment
amount
. - Initiate a Session
Send theamount
and auserTokenId
(unique customer identifier in merchant system) in an/openOrder
request, which authenticates and sets up an order in the Nuvei system, and returns asessionToken
. - Initialize the Web SDK
This instantiates the Web SDK with thesessionToken
received from the server call to/openOrder
. - Allow the customer to select the Secure Bank Transfer APM as the payment method.
- Call a /getUserUPOs request to retrieve a list of the customer’s UPOs.
(If no appropriate UPOs are returned, then skip the rest of these steps, and perform the steps in the Payment (without UPO) flow instead.) - Offer the “returning customer” the option to select one of their previously captured payment methods (stored in a UPO record, representing the customer’s bank account), instead of collecting their bank account details again.
- If the customer selects one of their previously captured payment methods (UPOs), then continue with the next step.
- If not, then skip the rest of these steps, and perform the steps in the Payment (without UPO) flow instead.
- Send a createPayment() request with its mandatory parameters including:
userTokenId
– Unique customer identifier in merchant system.amount
userPaymentOptionId
: “<ID of a previously stored payment option>“paymentOption.alternativePaymentMethod
: “apmgw_Secure_Bank_Transfer“deviceDetails
class containing:ipAddress
billingAddress
block containing:firstName
,lastName
,email
,phone
,address
,city
,zip
,state
,country
userDetails
class containing:firstName
,lastName
,email
,phone
,address
,city
,zip
,state
,country
,identification
urlDetails.notificationUrl
Example createPayment()
Request (with UPO)
sfc.createPayment({ sessionToken: "<sessiontoken>", paymentOption: { userPaymentOptionId: "8100521", alternativePaymentMethod: { paymentMethod: "apmgw_Secure_Bank_Transfer" } }, deviceDetails: { ipAddress: "<customer's IP address>" }, billingAddress: { firstName: "John", lastName: "Smith", email: "[email protected]", phone: "6175551414", address: "22 Main Street", city: "Boston", zip: "02460", state: "MA", country: "US" }, userDetails: { firstName: "John", lastName: "Smith", email: "[email protected]", phone: "6175551414", address: "22 Main Street", city: "Boston", zip: "02460", state: "MA", country: "US", identification: "123456789" }, urlDetails: { notificationUrl: "<URL to which DMNs are sent>" }, }, function(res) { console.log(res); });
- The Secure Bank Transfer flow begins when the customer selects the Secure Bank Transfer payment method from the payment method gallery.
- The customer selects one of their previously captured payment methods (UPOs), enters an amount, and presses the Deposit/Process button.
- REST API
-
- The payment flow begins on your payment page when a “returning customer” enters an
amount
they wish to transfer, and selects the Secure Bank Transfer payment method. - Generate a
sessionToken
by sending a/getSessionToken
request. - Call a /getUserUPOs request to retrieve a list of the customer’s UPOs.
(If no appropriate UPOs are returned, then skip the rest of these steps, and perform the steps in the Payment (without UPO) flow instead.) - Offer the “returning customer” the option to select one of their previously captured payment methods (stored in a UPO record, representing the customer’s bank account), instead of collecting their bank account details again.
- If the customer selects one of their previously captured payment methods (UPOs), then continue with the next step.
- If the customer does not select one of their existing UPOs, then skip the rest of these steps and perform the steps in the Payment (without UPO) flow instead.
- Send a
/payment
request with its mandatory parameters including:userTokenId
– Unique customer identifier in merchant system.amount
userPaymentOptionId
: “<ID of a previously stored payment option>“deviceDetails
class containing:ipAddress
paymentOption.alternativePaymentMethod
: “apmgw_Secure_Bank_Transfer“billingAddress
class containing:firstName
,lastName
,email
,phone
,address
,city
,zip
,state
,country
userDetails
class containing:firstName
,lastName
,email
,phone
,address
,city
,zip
,state
,country
,identification
urlDetails.notificationUrl
Example of
/payment
Request (with UPO){ "sessionToken": "<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "<unique customer identifier in merchant system>", "clientRequestId": "<unique request ID in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "currency": "USD", "amount": "100", "paymentOption": { "userPaymentOptionId": "8100521", "alternativePaymentMethod": { "paymentMethod": "apmgw_Secure_Bank_Transfer" } }, deviceDetails: { ipAddress: "<customer's IP address>" }, "billingAddress": { "firstName": "John", "lastName": "Smith", "email": "[email protected]", "phone": "6175551414", "address": "22 Main Street", "city": "Boston", "zip": "02460", "state": "MA", "country": "US" }, "userDetails": { "firstName": "John", "lastName": "Smith", "email": "[email protected]", "phone": "6175551414", "address": "22 Main Street", "city": "Boston", "zip": "02460", "state": "MA", "country": "US", "identification": "123456789" }, "urlDetails": { "notificationUrl": "<URL to which DMNs are sent>" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
- The payment flow begins on your payment page when a “returning customer” enters an
- Web SDK
-
- The payment flow begins on your payment page when a “returning customer” enters a payment
amount
. - Initiate a Session
Send theamount
and auserTokenId
(unique customer identifier in merchant system) in an/openOrder
request, which authenticates and sets up an order in the Nuvei system, and returns asessionToken
. - Initialize the Web SDK
This instantiates the Web SDK with thesessionToken
received from the server call to/openOrder
. - Allow the customer to select the Secure Bank Transfer APM as the payment method.
- Call a /getUserUPOs request to retrieve a list of the customer’s UPOs.
(If no appropriate UPOs are returned, then skip the rest of these steps, and perform the steps in the Payment (without UPO) flow instead.) - Offer the “returning customer” the option to select one of their previously captured payment methods (stored in a UPO record, representing the customer’s bank account), instead of collecting their bank account details again.
- If the customer selects one of their previously captured payment methods (UPOs), then continue with the next step.
- If not, then skip the rest of these steps, and perform the steps in the Payment (without UPO) flow instead.
- Send a createPayment() request with its mandatory parameters including:
userTokenId
– Unique customer identifier in merchant system.amount
userPaymentOptionId
: “<ID of a previously stored payment option>“paymentOption.alternativePaymentMethod
: “apmgw_Secure_Bank_Transfer“deviceDetails
class containing:ipAddress
billingAddress
block containing:firstName
,lastName
,email
,phone
,address
,city
,zip
,state
,country
userDetails
class containing:firstName
,lastName
,email
,phone
,address
,city
,zip
,state
,country
,identification
urlDetails.notificationUrl
Example
createPayment()
Request (with UPO)sfc.createPayment({ sessionToken: "<sessiontoken>", paymentOption: { userPaymentOptionId: "8100521", alternativePaymentMethod: { paymentMethod: "apmgw_Secure_Bank_Transfer" } }, deviceDetails: { ipAddress: "<customer's IP address>" }, billingAddress: { firstName: "John", lastName: "Smith", email: "[email protected]", phone: "6175551414", address: "22 Main Street", city: "Boston", zip: "02460", state: "MA", country: "US" }, userDetails: { firstName: "John", lastName: "Smith", email: "[email protected]", phone: "6175551414", address: "22 Main Street", city: "Boston", zip: "02460", state: "MA", country: "US", identification: "123456789" }, urlDetails: { notificationUrl: "<URL to which DMNs are sent>" }, }, function(res) { console.log(res); });
- The payment flow begins on your payment page when a “returning customer” enters a payment
- Simply Connect
-
- The Secure Bank Transfer flow begins when the customer selects the Secure Bank Transfer payment method from the payment method gallery.
- The customer selects one of their previously captured payment methods (UPOs), enters an amount, and presses the Deposit/Process button.
The request is processed:
- Secure Bank Transfer processes the transaction and returns transaction notifications and status.
See the Handling the Response topic (same as for “Payment (without UPO)” (above). - Alternatively:
Payout
A payout is performed using the REST API /payout
request.
See the Payout topic above – same flow as for Bank Transfer (ACH).
Refund
See the Refund topic.
Testing
Declined Deposit and Declined Pre-approval
NSF – Amount 1.27
Declined – Amount 1.30
Account No: 3666394279
Routing No: 123456780
Successful Deposit and Successful Pre-approval
Success – Amount: 1.25
Account No: 111111111
Routing No: 123456780
Testing Trigger Amounts
Appendices
DMN Error Codes
When the APM declines or returns a transaction, the DMN includes one of the following error codes:
Code from APM | Description | SC Code |
---|---|---|
1001 | R01-Insufficient funds | 1150 |
1002 | R02-Account Closed | 1030 |
1003 | R03-No current account | 1259 |
1004 | R04-Invalid Account Number | 1017 |
1005 | R05-Decline. Customer cancellation | 10039 |
1006 | R06-Return by ODFI | 101260 |
1007 | R07-Rejected by customer | 1232 |
1008 | R08-Stop Payment Order | 1199 |
1009 | R09-Check is OK but cannot be converted | 1204 |
1010 | R10-Payment not authorized by user | 1218 |
1011 | R11-Decline. Customer cancellation | 10039 |
1012 | R12-Invalid bank | 1231 |
1013 | R13-Invalid Bank Code | 1018 |
1014 | R14-Consumer Cannot Pay | 1241 |
1015 | R15-Consumer Cannot Pay | 1241 |
1016 | R16-Account locked | 1223 |
1017 | R17-Format error | 1167 |
1018 | R18-Invalid effective date | 1033 |
1019 | R19-Invalid account specified | 1185 |
1020 | R20-Restricted card/bank account | 1233 |
1021 | R21-Invalid company identification | 101261 |
1022 | R22-Consumer info validation failed | 1272 |
1023 | R23-Check is OK but cannot be converted | 1204 |
1024 | R24-ACH: Duplicate Entry | 1027 |
1025 | R25-Format error | 1167 |
1026 | R26-Mandatory field is missing | 10000 |
1027 | R27-Invalid trace number | 101262 |
1028 | R28-Check digits mismatch | 1140 |
1029 | R29-Decline. Customer cancellation | 10039 |
1030 | R30-RDFI not participating in check truncation program | 101263 |
1031 | R31-Transaction cannot be completed | 1195 |
1032 | R32-Transaction cannot be completed | 1195 |
1033 | R33-Return error | 101264 |
1034 | R34-Transaction cannot be completed; violation of law | 1246 |
1035 | R35-Return error | 101264 |
1036 | R36-Return error | 101264 |
1037 | R37-Stop Payment Order | 1199 |
1038 | R38-Stop Payment Order | 1199 |
1039 | R39-Stop Payment Order | 1199 |
1040 | R40-Automated enrollment error | 101265 |
1041 | R41-Invalid transaction | 1162 |
1042 | R42-Check digits mismatch | 1140 |
1043 | R43-Invalid Account Number | 1017 |
1044 | R44-ACH: Invalid IdentificationNumber | 1019 |
1045 | R45-The payer’s name is incorrect. | 1256 |
1046 | R46-Invalid payee | 1134 |
1047 | R47-Automated enrollment error | 101265 |
1048 | R50-Transaction cannot be completed; violation of law | 1246 |
1049 | R51-Transaction cannot be completed | 1195 |
1050 | R52-Stop Payment Order | 1199 |
1051 | R53-ACH: Duplicate Entry | 1027 |
1052 | R61-Routing error | 1194 |
1053 | R62-ODFI error | 101266 |
1054 | R67-ODFI error | 101266 |
1055 | R68-ODFI error | 101266 |
1056 | R69-ODFI error | 101266 |
1057 | R70-ODFI error | 101266 |
1058 | R71-Contested error | 101267 |
1059 | R72-Contested error | 101267 |
1060 | R73-Contested error | 101267 |
1061 | R74-Contested error | 101267 |
1062 | R75-Return error | 101264 |
1063 | R76-Return error | 101264 |
1064 | R77-Contested error | 101267 |
1065 | R80-Cross-border error | 101268 |
1066 | R81-Cross-border error | 101268 |
1067 | R82-Cross-border error | 101268 |
1068 | R83-Cross-border error | 101268 |
1069 | R84-Cross-border error | 101268 |
1070 | R85-Return error | 101264 |
1071 | R99-Return error | 101264 |
1072 | M01-Return error | 101264 |
1073 | M02-Return error | 101264 |
Generating UPOs
Introduction
A userPaymentOptionId
represents a customer bank account in the Nuvei system. It is normally generated automatically upon successful completion of a /payment
request.
However, you can also generate a UPO without first sending a /payment
request first, as described below.
Prerequisites
The userTokenId
is a mandatory parameter when sending a /addUPOAPM
request.
If the customer’s userTokenId
is not yet registered in the Nuvei system, then you can register it by sending a /createUser
request with its mandatory parameters, including email
, countryCode
, firstName
, and lastName
.
Example /createUser
Request
{ "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "clientRequestId": "<unique request ID in merchant system>", "userTokenId": "<unique customer identifier in merchant system>", "firstName":"John", "lastName":"Smith", "email":"[email protected]", "countryCode":"2-letter ISO country code>", "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Generating a UPO
Send an /addUPOAPM
request with its mandatory parameters including:
userTokenId
– The unique customer identifier in your system.apmData
class containing:AccountNumber
– The customer’s bank account number.RoutingNumber
– The customer’s financial institution ABA number (9 digits including leading zeros).
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_ACH", "apmData":{ "AccountNumber":"111111111", "RoutingNumber":"999999992" }, "billingAddress":{ "firstName":"John", "lastName":"Smith", "email":"[email protected]", "phone":"6175551414", "address":"22 Main Street", "city":"Boston", "zip":"02460", "state":"MA", "country":"US" }, "timeStamp":"<YYYYMMDDHHmmss>", "checksum":"<calculated checksum>" }
{ "merchantId":"<your merchantId>", "merchantSiteId":"<your merchantSiteId>", "clientRequestId":"<unique request ID in merchant system>", "userTokenId":"<unique customer identifier in merchant system>", "paymentMethodName":"apmgw_Secure_Bank_Transfer", "apmData":{ "AccountNumber":"111111111", "RoutingNumber":"999999992" }, "billingAddress":{ "firstName":"John", "lastName":"Smith", "email":"[email protected]", "phone":"6175551414", "address":"22 Main Street", "city":"Boston", "zip":"02460", "state":"MA", "country":"US" }, "timeStamp":"<YYYYMMDDHHmmss>", "checksum":"<calculated checksum>" }
Example /addUPOAPM
Response
{ "reason":"", "merchantId":"2502136204546424962", "errCode":0, "clientRequestId":"HWMTWQ2RT", "userPaymentOptionId":8052151, "internalRequestId":17817221, "version":"1.0", "status":"SUCCESS", "merchantSiteId":"126006" }
Example Payment DMNs
Example DMN with status
=PENDING
...'ppp_status=PENDING&Status=PENDING&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=37833471&userid=UID&merchant_unique_id=MUID012311122&customData=QA+test+merchant&productId=PID&first_name=Alberta&last_name=Bobbeth+Charleson&email=test%40mymail.com¤cy=USD&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Sancho+el+fuerte&address2=15&country=United+States&state=NEW+YORK&city=Madrid&zip=07208&phone1=4804638290&phone2=&phone3=&client_ip=174.26.150.77&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Nuvei-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=0000&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=3111&merchant_status=&action=&requestVersion=&message=PENDING&merchantLocale=en_GB&unknownParameters=&payment_method=apmgw_Secure_Bank_Transfer&ID=&merchant_id=4972436454212160565&responseTimeStamp=2022-07-12.11%3A22%3A01&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Test1111111111111222222&user_token=auto&userPaymentOptionId=8288891&TransactionID=2110000000006605022&externalTransactionId=9715155&APMReferenceID=9195BF012FC0B7FFCD0B4DB98799ABAB&orderTransactionId=18916101&totalAmount=1.25&dynamicDescriptor=QA+Test+site&item_name_1=ItemName&item_number_1=&item_amount_1=1.25&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=&upoRegistrationDate=20220711&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=%7B%22StatusInfo%22%3A%22%7B+StatusCode%3A+%2C+info%3A+%7D%22%2C%22BankName%22%3A%22Chase%3A+Plaid+Checking%22%2C%22AccountNumber%22%3A%220000%22%2C%22AccountHolder%22%3A%22Alberta+Bobbeth+Charleson%22%2C%22TransactionAmountLimit%22%3A%2250000%22%2C%22DailyAmountLimit%22%3A%2250000%22%2C%22MonthlyAmountLimit%22%3A%22100000%22%2C%22BankKYC%22%3A%5B%7B%22names%22%3A%5B%22Alberta+Bobbeth+Charleson%22%5D%2C%22addresses%22%3A%5B%7B%22data%22%3A%7B%22city%22%3A%22Malakoff%22%2C%22country%22%3A%22US%22%2C%22postal_code%22%3A%2202460%22%2C%22region%22%3A%22MA%22%2C%22street%22%3A%2222+Main+Street%22%7D%2C%22primary%22%3Atrue%7D%2C%7B%22data%22%3A%7B%22city%22%3A%22San+Matias%22%2C%22country%22%3A%22US%22%2C%22postal_code%22%3A%2293405-2255%22%2C%22region%22%3A%22CA%22%2C%22street%22%3A%222493+Leisure+Lane%22%7D%2C%22primary%22%3Afalse%7D%5D%2C%22emails%22%3A%5B%7B%22data%22%3A%22accountholder0%40example.com%22%2C%22primary%22%3Atrue%7D%2C%7B%22data%22%3A%22accountholder1%40example.com%22%2C%22primary%22%3Afalse%7D%2C%7B%22data%22%3A%22extraordinarily.long.email.username.123456%40reallylonghostname.com%22%2C%22primary%22%3Afalse%7D%5D%2C%22phone_numbers%22%3A%5B%7B%22data%22%3A%226175551414%22%2C%22primary%22%3Afalse%7D%2C%7B%22data%22%3A%221112224444%22%2C%22primary%22%3Afalse%7D%2C%7B%22data%22%3A%221112225555%22%2C%22primary%22%3Afalse%7D%5D%7D%5D%2C%22Note%22%3A%22PrevPay%3A+nil+%2B0%7CScore%3A+100%2F100%22%7D&sessionId=21f7e875c612def9af98328ceb5f&responsechecksum=0296f25eb86c71bdf4dd7fe3e4060e1b&advanceResponseChecksum=5f47045e522221edfb1b084cf2caa5a3,
Example DMN with status
=UPDATE
...'ppp_status=OK&Status=UPDATE&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=37833471&userid=UID&merchant_unique_id=MUID012311122&customData=QA+test+merchant&productId=PID&first_name=Alberta&last_name=Bobbeth+Charleson&email=test%40mymail.com¤cy=USD&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Sancho+el+fuerte&address2=15&country=United+States&state=NEW+YORK&city=Madrid&zip=07208&phone1=4804638290&phone2=&phone3=&client_ip=174.26.150.77&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Nuvei-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=0000&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=3111&merchant_status=&action=&requestVersion=&message=UPDATE&merchantLocale=en_GB&unknownParameters=&payment_method=apmgw_Secure_Bank_Transfer&ID=&merchant_id=4972436454212160565&responseTimeStamp=2022-07-12.12%3A58%3A19&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Test1111111111111222222&user_token=auto&userPaymentOptionId=8288891&TransactionID=2110000000006605022&externalTransactionId=9715155&APMReferenceID=9195BF012FC0B7FFCD0B4DB98799ABAB&orderTransactionId=18916101&totalAmount=1.25&dynamicDescriptor=QA+Test+site&item_name_1=ItemName&item_number_1=&item_amount_1=1.25&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=&upoRegistrationDate=20220711&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=%7B%22StatusInfo%22%3A%22%7B+StatusCode%3A+%2C+info%3A+%7D%22%2C%22BankName%22%3A%22Chase%3A+Plaid+Checking%22%2C%22AccountNumber%22%3A%220000%22%2C%22AccountHolder%22%3A%22Alberta+Bobbeth+Charleson%22%2C%22AvailableBalance%22%3A%2210000%22%2C%22CurrentBalance%22%3A%2211000%22%2C%22TransactionAmountLimit%22%3A%2250000%22%2C%22DailyAmountLimit%22%3A%2250000%22%2C%22MonthlyAmountLimit%22%3A%22100000%22%2C%22BankKYC%22%3A%5B%7B%22names%22%3A%5B%22Alberta+Bobbeth+Charleson%22%5D%2C%22addresses%22%3A%5B%7B%22data%22%3A%7B%22city%22%3A%22Malakoff%22%2C%22country%22%3A%22US%22%2C%22postal_code%22%3A%2202460%22%2C%22region%22%3A%22MA%22%2C%22street%22%3A%2222+Main+Street%22%7D%2C%22primary%22%3Atrue%7D%2C%7B%22data%22%3A%7B%22city%22%3A%22San+Matias%22%2C%22country%22%3A%22US%22%2C%22postal_code%22%3A%2293405-2255%22%2C%22region%22%3A%22CA%22%2C%22street%22%3A%222493+Leisure+Lane%22%7D%2C%22primary%22%3Afalse%7D%5D%2C%22emails%22%3A%5B%7B%22data%22%3A%22accountholder0%40example.com%22%2C%22primary%22%3Atrue%2C%22type%22%3A%22primary%22%7D%2C%7B%22data%22%3A%22accountholder1%40example.com%22%2C%22primary%22%3Afalse%2C%22type%22%3A%22secondary%22%7D%2C%7B%22data%22%3A%22extraordinarily.long.email.username.123456%40reallylonghostname.com%22%2C%22primary%22%3Afalse%2C%22type%22%3A%22other%22%7D%5D%2C%22phone_numbers%22%3A%5B%7B%22data%22%3A%226175551414%22%2C%22primary%22%3Afalse%2C%22type%22%3A%22home%22%7D%2C%7B%22data%22%3A%221112224444%22%2C%22primary%22%3Afalse%2C%22type%22%3A%22work%22%7D%2C%7B%22data%22%3A%221112225555%22%2C%22primary%22%3Afalse%2C%22type%22%3A%22mobile%22%7D%5D%7D%5D%2C%22Note%22%3A%22PrevPay%3A+nil+%2B0%7CScore%3A+100%2F100%22%7D&representmentInformation=Account+Linked&sessionId=21f7e875c612def9af98328ceb5f&responsechecksum=40ce1091b7db73b2b9203452f86d4b19&advanceResponseChecksum=a6252e4a90a788b4641db423ad54409a',
Example DMN with status
=APPROVED
...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=37833471&userid=UID&merchant_unique_id=MUID012311122&customData=QA+test+merchant&productId=PID&first_name=Alberta&last_name=Bobbeth+Charleson&email=test%40mymail.com¤cy=USD&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Sancho+el+fuerte&address2=15&country=United+States&state=NEW+YORK&city=Madrid&zip=07208&phone1=4804638290&phone2=&phone3=&client_ip=174.26.150.77&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Nuvei-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=0000&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=3111&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=en_GB&unknownParameters=&payment_method=apmgw_Secure_Bank_Transfer&ID=&merchant_id=4972436454212160565&responseTimeStamp=2022-07-12.11%3A31%3A46&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Test1111111111111222222&user_token=auto&userPaymentOptionId=8288891&TransactionID=2110000000006605022&externalTransactionId=9715155&APMReferenceID=9195BF012FC0B7FFCD0B4DB98799ABAB&orderTransactionId=18916101&totalAmount=1.25&dynamicDescriptor=QA+Test+site&item_name_1=ItemName&item_number_1=&item_amount_1=1.25&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=&upoRegistrationDate=20220711&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=%7B%22StatusInfo%22%3A%22%7B+StatusCode%3A+%2C+info%3A+%2C+originalAmount%3A+1.2500%2C+ProcessedAmount%3A+1.25%7D%22%2C%22BankName%22%3A%22Chase%3A+Plaid+Checking%22%2C%22AccountNumber%22%3A%220000%22%2C%22AccountHolder%22%3A%22Alberta+Bobbeth+Charleson%22%2C%22AvailableBalance%22%3A%2210000%22%2C%22CurrentBalance%22%3A%2211000%22%2C%22TransactionAmountLimit%22%3A%2250000%22%2C%22DailyAmountLimit%22%3A%2250000%22%2C%22MonthlyAmountLimit%22%3A%22100000%22%2C%22BankKYC%22%3A%5B%7B%22names%22%3A%5B%22Alberta+Bobbeth+Charleson%22%5D%2C%22addresses%22%3A%5B%7B%22data%22%3A%7B%22city%22%3A%22Malakoff%22%2C%22country%22%3A%22US%22%2C%22postal_code%22%3A%2202460%22%2C%22region%22%3A%22MA%22%2C%22street%22%3A%2222+Main+Street%22%7D%2C%22primary%22%3Atrue%7D%2C%7B%22data%22%3A%7B%22city%22%3A%22San+Matias%22%2C%22country%22%3A%22US%22%2C%22postal_code%22%3A%2293405-2255%22%2C%22region%22%3A%22CA%22%2C%22street%22%3A%222493+Leisure+Lane%22%7D%2C%22primary%22%3Afalse%7D%5D%2C%22emails%22%3A%5B%7B%22data%22%3A%22accountholder0%40example.com%22%2C%22primary%22%3Atrue%7D%2C%7B%22data%22%3A%22accountholder1%40example.com%22%2C%22primary%22%3Afalse%7D%2C%7B%22data%22%3A%22extraordinarily.long.email.username.123456%40reallylonghostname.com%22%2C%22primary%22%3Afalse%7D%5D%2C%22phone_numbers%22%3A%5B%7B%22data%22%3A%226175551414%22%2C%22primary%22%3Afalse%7D%2C%7B%22data%22%3A%221112224444%22%2C%22primary%22%3Afalse%7D%2C%7B%22data%22%3A%221112225555%22%2C%22primary%22%3Afalse%7D%5D%7D%5D%2C%22Note%22%3A%22PrevPay%3A+nil+%2B0%7CScore%3A+100%2F100%22%7D&sessionId=21f7e875c612def9af98328ceb5f&responsechecksum=40ce1091b7db73b2b9203452f86d4b19&advanceResponseChecksum=789fc87b58bce800ac0890acaf491563',