Overview
For payouts (withdrawals), some APMs have rigorous validations for the input fields required to authenticate user account details. To streamline the user experience, Nuvei provides API and Web SDK methods for collecting and validating the input fields for these APMs.
These methods return a URL to redirect the user and capture their account details. Nuvei stores the captured details in a userPaymentOptionId
(UPO) identifier (see Payment Management), which merchants can then use to send the payout (withdrawal) request.
Capturing the Account Details
Press tab to open…
Follow these steps to perform a payout using Nuvei REST API integration:
- 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
– See the list of APMs that support account details capture.currencyCode
countryCode
Example
/accountCapture
Request{ "sessionToken":"<sessionToken from /getSessionToken>", "merchantId":"<your merchantId>", "merchantSiteId":"<your merchantSiteId>", "paymentMethod":"apmgw_<APM provider name>", "userTokenId":"<unique customer identifier in merchant system>", "currencyCode":"USD", "countryCode":"US", "amount":"200", "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>" }, }
The request returns a
redirectUrl
.Example
/accountCapture
Response{ "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b", "merchantId":"427583496191624621", "merchantSiteId":"142033", "redirectUrl":"<redirect URL to enter account details>" }
- Use the
redirectUrl
to redirect the customer to the APM’s account details capture interface. - After the information is captured, Nuvei stores the data in a UPO record, and sends a DMN to the merchant with a newly created
userPaymentOptionId
.
Example DMN
ppp_status=OK userid=139619531 currency=BRL country=BR merchant_site_id=142033 payment_method=apmgw_PayRetailers_Payouts merchant_id=427583496191624621 responseTimeStamp=2021-06-07.07:29:04 user_token_id=KUGOKLLCP52V userPaymentOptionId=8030921 type=ACCOUNT_CAPTURE responsechecksum=dc5d86f3b2248c108b1897bc859cb81c advanceResponseChecksum=00c8cb00622ce0dcae6ad443bea56598
- Send a
/payout
request and include theuserPaymentOptionId
, which contains the user’s previously stored APM account details. Press here for an example.
Follow these steps to perform a payout using Nuvei Web SDK integration:
1. Initiate a Session
Before submitting a payout request using the client-side Nuvei Web SDK, the merchant needs to send an /openOrder request.
2. Initialize the Web SDK
Instantiate the Web SDK with the sessionToken
received from the server request 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
– See the list of APMs that support account details capture.currencyCode
countryCode
Example accountCapture()
Request
sfc.accountCapture({ sessionToken: "<sessiontoken>", merchantId: "<your merchantId>", merchantSiteId: "<your merchantSiteId>", paymentMethod: "apmgw_<APM provider name>", userTokenId: "<unique customer identifier in merchant system>", currencyCode: "USD", countryCode: "US", 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 response includes 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 capture interface.
c. After the information is captured, Nuvei stores the data in a UPO record, and sends a DMN back to the merchant with the newly created userPaymentOptionId
.
Example DMN
ppp_status=OK
userid=139619531
currency=BRL
country=BR
merchant_site_id=142033
payment_method=apmgw_PayRetailers_Payouts
merchant_id=427583496191624621
responseTimeStamp=2021-06-07.07:29:04
user_token_id=KUGOKLLCP52V
userPaymentOptionId=8030921
type=ACCOUNT_CAPTURE
responsechecksum=dc5d86f3b2248c108b1897bc859cb81c
advanceResponseChecksum=00c8cb00622ce0dcae6ad443bea56598
4. Send a submitWdRequest()
request
Send a submitWdRequest()
request and include the upoId
(the userPaymentOptionId
in the DMN), which contains the user’s previously stored APM account details.
- REST API
-
Follow these steps to perform a payout using Nuvei REST API integration:
- 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
– See the list of APMs that support account details capture.currencyCode
countryCode
Example
/accountCapture
Request{ "sessionToken":"<sessionToken from /getSessionToken>", "merchantId":"<your merchantId>", "merchantSiteId":"<your merchantSiteId>", "paymentMethod":"apmgw_<APM provider name>", "userTokenId":"<unique customer identifier in merchant system>", "currencyCode":"USD", "countryCode":"US", "amount":"200", "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>" }, }
The request returns a
redirectUrl
.Example
/accountCapture
Response{ "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b", "merchantId":"427583496191624621", "merchantSiteId":"142033", "redirectUrl":"<redirect URL to enter account details>" }
- Use the
redirectUrl
to redirect the customer to the APM’s account details capture interface. - After the information is captured, Nuvei stores the data in a UPO record, and sends a DMN to the merchant with a newly created
userPaymentOptionId
.
Example DMN
ppp_status=OK userid=139619531 currency=BRL country=BR merchant_site_id=142033 payment_method=apmgw_PayRetailers_Payouts merchant_id=427583496191624621 responseTimeStamp=2021-06-07.07:29:04 user_token_id=KUGOKLLCP52V userPaymentOptionId=8030921 type=ACCOUNT_CAPTURE responsechecksum=dc5d86f3b2248c108b1897bc859cb81c advanceResponseChecksum=00c8cb00622ce0dcae6ad443bea56598
- Send a
/payout
request and include theuserPaymentOptionId
, which contains the user’s previously stored APM account details. Press here for an example.
- Generate a
- Web SDK
-
Follow these steps to perform a payout using Nuvei Web SDK integration:
1. Initiate a Session
Before submitting a payout request using the client-side Nuvei Web SDK, the merchant needs to send an /openOrder request.
2. Initialize the Web SDK
Instantiate the Web SDK with the
sessionToken
received from the server request 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
– See the list of APMs that support account details capture.currencyCode
countryCode
Example
accountCapture()
Requestsfc.accountCapture({ sessionToken: "<sessiontoken>", merchantId: "<your merchantId>", merchantSiteId: "<your merchantSiteId>", paymentMethod: "apmgw_<APM provider name>", userTokenId: "<unique customer identifier in merchant system>", currencyCode: "USD", countryCode: "US", 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 response includes 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 capture interface.c. After the information is captured, Nuvei stores the data in a UPO record, and sends a DMN back to the merchant with the newly created
userPaymentOptionId
.
Example DMN
ppp_status=OK userid=139619531 currency=BRL country=BR merchant_site_id=142033 payment_method=apmgw_PayRetailers_Payouts merchant_id=427583496191624621 responseTimeStamp=2021-06-07.07:29:04 user_token_id=KUGOKLLCP52V userPaymentOptionId=8030921 type=ACCOUNT_CAPTURE responsechecksum=dc5d86f3b2248c108b1897bc859cb81c advanceResponseChecksum=00c8cb00622ce0dcae6ad443bea56598
4. Send a
submitWdRequest()
requestSend a
submitWdRequest()
request and include theupoId
(theuserPaymentOptionId
in the DMN), which contains the user’s previously stored APM account details.
Appendix
APMs Supporting Account Details Capture
APM | paymentMethod Parameter |
---|---|
Astropay Bank Payouts | apmgw_AstropayBankPayouts |
Bank Payouts | apmgw_Local_Payouts |
Bank Transfer Malaysia | apmgw_Bank_Transfer_Malaysia |
DragonPay | apmgw_DragonPay |
EFT Payments | apmgw_Instant_Bank_Transfer |
ElementPay Payouts | apmgw_Elementpay_Payouts |
India Payouts | apmgw_India_Payouts |
Instant Bank Payments | apmgw_Instant_Bank_Payments_SE apmgw_Instant_Bank_Payments_DK apmgw_Instant_Bank_Payments_EE apmgw_Instant_Bank_Payments_FI |
Interac eCashout | apmgw_Interac_eTransfer |
International Payouts | apmgw_Bank_Payouts |
LATAM Payouts | apmgw_LATAM_Payouts |
Local Bank Payouts | apmgw_BankPayouts |
Local Currency Payouts | apmgw_Local_Currency_Payouts |
Local Payments Indonesia | apmgw_Local_Payments_Indonesia |
Local Payments Vietnam | apmgw_Local_Payments_Vietnam |
Nuvei Instant Bank Transfer (IBT) | apmgw_eCheckSelect |
Payretailers Bank Payouts | apmgw_PayRetailers_Payouts |
STPMex | apmgw_STPmex |
SugarPay | apmgw_SugarPay |
Trustly | apmgw_Trustly_DI |
Verified Faster Payments | apmgw_Verified_Faster_Payments |
Verified SEPA Payouts | apmgw_Verified_SEPA_Payouts |