Overview
Nuvei APM integrations give you easy access to hundreds of APM providers and handle all fund settlements and flows.
This topic describes the APM workflows and APM integrations supported by Nuvei.
Hundreds of APM Providers
So you want to access hundreds of APM providers, but integrating directly with these APM providers is not a trivial exercise!
Nuvei invests an enormous amount of resources to provide you with easy-to-use streamlined integrations with these APM providers.
Instead of a merchant needing to establish individual contracts with all potential APM providers, Nuvei has done that work for you:
- We maintain agreements with hundreds of APM providers all around the world.
- Our integrations dramatically simplify and fast-track your APM integration process.
- We provide integrations with many of the largest APM providers that support a range of countries and currencies.
APM Workflows
APM providers compete directly with traditional card issuers, offering their customers payment (deposit) and payout (withdrawal) services, using a range of workflows as well as some other quite unique settlement processes.
Nuvei supports the following APM workflows for accepting APM payments from your customers, as well as other special APM-related workflows:
APM “Redirect” Workflows
The customer is “redirected” from the merchant’s page to the APM provider’s site to enter their APM account credentials and accept their payment, enter other payment details, or receive payment instructions, etc.
Nuvei provides the following APM “Redirect” workflows:
- APM “Redirect” Payment
- General APM Recurring Billing (For specific APM providers)
APM “Redirect” Payment
This is the most popular workflow. Payment requests include the alternativePaymentMethod
block containing the relevant APM Input Fields.
Summary of the APM “Redirect” Workflow Steps
- Collecting the transaction details:
The customer initiates a deposit on the merchant’s payment page by entering an amount. - Collecting the APM provider APM account details:
The customer selects an APM provider and enters their APM account details (if required). - Sending the payment request:
These details are used to send a payment request. - Redirection:
A successful response returns aredirectUrl
which is used to redirect the customer to the APM provider’s page. - Authentication:
The customer provides their account credentials on their APM’s authentication page to complete the payment.
The APM’s authentication page is displayed to the customer as a pop-up window where they can enter their APM account details. - Handling the transaction response:
The APM authenticates the request.
Depending on the result, the customer is redirected to the relevant Success/Pending/Error/Decline page on the merchant’s site:- Success page: When the transaction is processed and approved immediately.
- Pending page: When there is a delay between deposit submission and the processing of the transaction.
- Error/Decline page: When the transaction is rejected.
General Recurring Billing
Specific APM providers offer “redirect” initial payments followed by direct server-to-server payments for subsequent recurring/re-billing payments.
For implementation in the relevant Nuvei product platform/s, see the steps in the General APM Recurring Billing topic.
APM “Direct” Workflows
Nuvei supports APM “Direct” payment workflows and other advanced workflows to support APM features offered by specific APM providers:
APM “Direct” Payments
The customer completes the workflow steps on the merchant’s page.
Payment requests include the alternativePaymentMethod
block containing the relevant APM Input Fields.
Special Recurring Billing
Specific APM providers offer a direct server-to-server payment option for subsequent recurring/re-bill payments.
For implementation in the relevant Nuvei product platform/s, see the steps in the Special APM Recurring Billing topic.
Customer Registration via APM
Specific APM providers offer a service to provide you with the necessary customer details to register a new customer in your system, based on the customer details collected by the APM provider.
For implementation in the relevant Nuvei product platform/s, see the steps in the Customer Registration via APM topic.
APM Refunds
Refunds can be perform in the same way as for card transactions, by sending a /refundTransaction
request.
For details, see the Refund topic.
APM Integrations
APM providers are easily accessed by including an alternativePaymentMethod
block containing the relevant APM Input Fields in the relevant Nuvei payment (or payout) request.
All Nuvei Solution Platforms support APM transactions.
See the relevant APM integration steps described below:
- APM Payment Page / Cashier Integration
- APM Web SDK Integration
- APM Simply Connect Integration
- APM REST API Integration
Follow the integration steps described below for the relevant Nuvei payment platform/s.
APM Payment Page / Cashier
For integration details, see the Nuvei Payment Page – Quick Start topic.
Also, see the other APM-related topics:
APM Web SDK
For integration details, see the APM Payments with Web SDK topic.
APM Simply Connect
For integration details, see the Perform a checkout() Payment topic.
APM REST API
This topic describes how to accept payments from your customers via APMs using Nuvei REST API methods.
Follow these APM REST API integration steps:
1. Get sessionToken
Each API session begins with a /getSessionToken
call to receive a sessionToken
for use in the subsequent API calls.
Example /getSessionToken
Request
{ "merchantSiteId":"<your merchantSiteId>", "merchantId":"<your merchantId>", "clientRequestId":"<unique request ID in merchant system>", "timeStamp":"<YYYYMMDDHHmmss>", "checksum":"<calculated checksum>" }
Example /getSessionToken
Response
{ "sessionToken":"f7763a23-9847-49c6-8ea5-96597aff6f78", "internalRequestId":272443598, "status":"SUCCESS", "errCode":0, "reason":"", "merchantId":"479748173730597238", "merchantSiteId":"204388", "version":"1.0", "clientRequestId":"20210428200753" }
2. APM Payment Form
Present a payment form containing the list of APMs for your customers to choose from. Use either of these approaches:
- Hard-Coded Approach – If you offer a simple set of pre-defined APMs (only a few APMs and for a few countries), then you can simply hard-code their input parameters into your payment form.
- Holistic/Real-Time/Dynamic Approach – If you wish to offer a dynamic list of APMs in many countries, then use the /getMerchantPaymentMethods API method to retrieve the relevant APMs for the customer.
3. Initiate an APM Payment
Send a /payment method call to initiate the APM payment.
Parameter | Description |
---|---|
Credential parameters | merchantId , merchantSiteId , clientRequestId , timeStamp , checksum . |
paymentOption | The paymentOption class contains details of the payment method selected by the customer for the transaction. There are two options:
|
amount | Payment amount . |
currency | The transaction currency . |
Example /payment
Request
{ "sessionToken":"<sessionToken from /getSessionToken>", "merchantId":"<your merchantId>", "merchantSiteId":"<your merchantSiteId>", "clientRequestId":"<unique request ID in merchant system>", "currency":"USD", "amount":"200", "userTokenId":"230811147", "paymentOption":{ "alternativePaymentMethod":{ "paymentMethod":"apmgw_MoneyBookers", "account_id":"SkrillTestUser3" } }, "billingAddress":{ "country":"US", "email":"[email protected]" }, "deviceDetails":{ "ipAddress":"<customer's IP address>" }, "timeStamp":"<YYYYMMDDHHmmss>", "checksum":"<calculated checksum>" }The response parameters returned can vary depending on the APM.
See the /payment method documentation for a description of all the possible output parameters.
Example /payment
Response
{ "orderId":"284832898", "userTokenId":"230811147", "paymentOption":{ "redirectUrl":"https://pay.skrill.com?sid=566c3869b901337398818e17f78a5525", "userPaymentOptionId":"53857808", "card":{ } }, "transactionStatus":"REDIRECT", "sessionToken":"f7763a23-9847-49c6-8ea5-96597aff6f78", "internalRequestId":272443728, "status":"SUCCESS", "errCode":0, "reason":"", "merchantId":"479748173730597238", "merchantSiteId":"204388", "version":"1.0", "clientRequestId":"20210428200916" }
Parameter | Details |
---|---|
transactionStatus | The status of the transaction. For Direct APM only. Possible values: APPROVED, DECLINED, ERROR, REDIRECT |
redirectUrl | The APM’s URL to redirect to. For Redirect APM only. |
reason | The error reason, in the event of an error. |
transactionId | The unique transaction ID assigned by Nuvei. This ID is needed for future related requests, such as a refund. |
userPaymentOptionId | An ID assigned for the processed user’s card for future transaction to be performed by the same user. Refer to Card-on-File for further details. |
4. Redirect to the APM
Use the redirectUrl
(returned in the response to the initial /payment
request above) to redirect your customer to the APM’s URL.
5. DMN Response for APM
After processing transactions through an APM, Nuvei returns a Direct Merchant Notification (DMN) that includes the result of the transaction in status
and in payment_method
, which identifies the payment method that the customer selected.
There are three possible values of status
:
- APPROVED: The transaction was processed and approved by the APM processor.
- DECLINED: The transaction was processed by the APM processor and declined.
- PENDING: The transaction is being processed by the APM processor.
Transactions are processed synchronously and asynchronously depending on the APM. When an APM processes the transaction asynchronously, the length of time that passes before the transaction is processed can be several seconds to several days.
After the final result (APPROVED or DECLINED) is received from the APM processor, Nuvei sends the merchant an additional DMN with the same transaction data as the previous DMN, containing the final transaction status
.
Example /payment
DMN with status
=PENDING
...'ppp_status=PENDING&PPP_TransactionId=257354778&userid=&merchant_unique_id=5CXS9TWCNFJP&customData=&productId=&first_name=Test&last_name=Test&email=test%40test.com¤cy=EUR&clientUniqueId=5CXS9TWCNFJP&Status=PENDING&customField1=merchantName&customField2=merchantName&customField3=merchantName&customField4=merchantName&customField5=&customField6=&customField7=&customField8=&customField9=merchantName&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=billing_address1&address2=&country=Germany&state=&city=billing_city&zip=9999&phone1=123456&phone2=&phone3=&client_ip=192.168.5.1&nameOnCard=&cardNumber=&bin=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&ExErrCode=0&ErrCode=0&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=197846&merchant_status=&action=&requestVersion=&message=PENDING&merchantLocale=&unknownParameters=&payment_method=apmgw_expresscheckout&Id=&merchant_id=4960497427404081578&responseTimeStamp=2020-03-21.15:42:48&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=ralphv5%40safecharge.com&cardCompany=&eci=&user_token_id=testPaypal&userPaymentOptionId=47865938&TransactionId=1110000000004579353&ExternalaccountId=3ZPD52JF4XY4S&externalAccountDescription=account_id:3ZPD52JF4XY4S%7Cemail:ralphv5%40safecharge.com&externalTransactionId=40T14511AV6745111&APMReferenceID=B586E22F7608F7416E201A9EBC58AF69&orderTransactionId=1044765948&totalAmount=20.00&dynamicDescriptor=%3F&Reason=&ReasonCode=0&item_name_1=NA&item_number_1=&item_amount_1=20.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20200321&type=DEPOSIT&clientRequestId=20200321174049&relatedTransactionId=&apmPayerInfo=Address:Confirmed%3BPayer:verified%3BCountry:GB%3BFirstName:Ralph%3BLastName:Van+Coevorden&responsechecksum=0606f157a5075d1d4dc11db7279deb9afd2b933575845bd71e5db99747db30d3&advanceResponseChecksum=1b85115ce2647e02461a4ad93d5a04873cb049470ec1e82b6d66d205ef9e4cfe',
Example /payment
DMN with status
=APPROVED
...'ppp_status=OK&PPP_TransactionId=257354778&userid=&merchant_unique_id=5CXS9TWCNFJP&customData=&productId=&first_name=Test&last_name=Test&email=test%40test.com¤cy=EUR&clientUniqueId=5CXS9TWCNFJP&Status=APPROVED&customField1=merchantName&customField2=merchantName&customField3=merchantName&customField4=merchantName&customField5=&customField6=&customField7=&customField8=&customField9=merchantName&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=billing_address1&address2=&country=Germany&state=&city=billing_city&zip=9999&phone1=123456&phone2=&phone3=&client_ip=192.168.5.1&nameOnCard=&cardNumber=&bin=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&ExErrCode=0&ErrCode=0&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=197846&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_expresscheckout&Id=&merchant_id=4960497427404081578&responseTimeStamp=2020-03-21.15:42:49&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=ralphv5%40safecharge.com&cardCompany=&eci=&user_token_id=testPaypal&userPaymentOptionId=47865938&TransactionId=1110000000004579353&ExternalaccountId=3ZPD52JF4XY4S&externalAccountDescription=account_id:3ZPD52JF4XY4S%7Cemail:ralphv5%40safecharge.com&externalTransactionId=40T14511AV6745111&APMReferenceID=B586E22F7608F7416E201A9EBC58AF69&orderTransactionId=1044765948&totalAmount=20.00&dynamicDescriptor=%3F&Reason=&ReasonCode=0&item_name_1=NA&item_number_1=&item_amount_1=20.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20200321&type=DEPOSIT&clientRequestId=20200321174049&relatedTransactionId=&apmPayerInfo=Address:Confirmed%3BPayer:verified%3BCountry:GB%3BFirstName:Ralph%3BLastName:Van+Coevorden&responsechecksum=7721cf5aea6773ac011df0f2224481041ecfff2ebc08bd265ec5b10c3f5ea4d5&advanceResponseChecksum=2164dc8cd5d93a4529dd6894f20563639ac22b953b06cdd0c5c4f1fb4e2cd3d3',