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.

• APM Workflows
• APM Integrations

For information about payment DMNs for APM transactions, see DMNs for APM Transactions.

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
  • APM “Redirect” Payment
  • General APM Recurring Billing
• APM “Direct” Workflows
  • APM “Direct” Payments
  • Special APM Recurring Billing
• Customer Registration via APM
• APM Refunds

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 class containing the relevant APM Input Fields.

Summary of the APM “Redirect” Workflow Steps

1. Collecting the transaction details:
   The customer initiates a deposit on the merchant’s payment page by entering an amount.
2. Collecting the APM provider APM account details:
   The customer selects an APM provider and enters their APM account details (if required).
3. Sending the payment request:
   These details are used to send a payment request.
4. Redirection:
   A successful response returns a redirectUrl which is used to redirect the customer to the APM provider’s page.
5. 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.
   For some APMs, Nuvei passes the credentials directly to the APM provider instead of displaying a pop-up window.

   Some APM providers allow customers to change the original transaction amount that was entered on the merchant’s Deposit/Payment page. In such cases, be sure to only use the final amount returned in the DMN.
   Do not use the original transaction amount that you passed in the request, as well as the amount returned in the HTTPS response.

6. 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.
     
     If the transaction is rejected, then Nuvei Payment Page / Cashier can display a message suggesting that the customer attempted to pay using another payment method.

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
• Special APM Recurring Billing

APM “Direct” Payments

The customer completes the workflow steps on the merchant’s page.

Payment requests include the alternativePaymentMethod class 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

Merchants can perform APM refunds in the same way as card refunds, by sending a /refundTransaction request. For details, see Refund in Financial Operations.

APM Integrations

APM providers are easily accessed by including an alternativePaymentMethod class 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:

• Filtering APMs in the Payment Methods Gallary topic.
• Visual Promotion for a Selected APM topic.

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: paymentOption.alternativePaymentMethod – For a new customer, the alternativePaymentMethod class allows you to specify the APM selected by the customer for use in this transaction. See APM Input Fields and APIs for details. paymentOption.userPaymentOptionId – For a returning customer, you can provide the identifier representing the customer's previously stored (by Nuvei) payment method.
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.