Developers

Overview

Nuvei supports several payment flows to accommodate a range of merchant payment models.

For example, some merchants require a one-time payment to charge their customers, while others have subscriptions based on recurring payment. In addition, many merchants handle 3D-Secure differently.
This section summarizes the main merchant payment flows:

• Manage 3D-Secure
• Always 3D
• Non-3D
• 3D-Only (MPI only)
• Liability Shift Payment (External MPI)
• MIT/Recurring
• Alternative Payment Methods (APMs)

• If you need a workflow not mentioned in this section, please contact our Support Team for assistance.

Manage 3D-Secure (recommended for cards)

Merchant Requirement

I would like Nuvei to control my 3D management (to process 3D-secure).

I would like Nuvei to manage all aspects of the 3D-Secure workflow, and avoid the implementation complexities (e.g. when to process with 3D-Secure and which 3D-Secure version to use, how processing differs between the two 3D-Secure versions, when and how to perform 3D-Secure fingerprinting, when and how to perform challenge, etc.

Nuvei Solutions

• Using the Checkout Page (seamless integration).
• Using the Web SDK:
  • Using the createPayment() method.
  • See the Web SDK Quick Start.
• Using API:
  • When a 3D challenge is required, after presenting the challenge to the customer, send a liability-shifted payment and include the relatedTransactionId field containing the initial 3D-Secure payment_id.
  • When a 3D challenge is not required, then send a 3D-Secure /payment request and include the threeD JSON block containing the 3D data.
  For details, see 3D-Secure Explained and the 3D-Secure How-To Guide.

Always 3D

Merchant Requirement

I would like to perform 3D transactions only. If a payment request fails the 3D-Secure authentication, then abort the payment and don’t continue processing any transaction.

Some merchants wish to perform 3D-Secure transactions only.

Nuvei Solution

This is a sub-case of the Manage 3D-Secure scenario (described above), which does not continue processing the transaction if the 3D authentication fails.
(In the standard the Manage 3D-Secure scenario, if 3D authentication fails (e.g. if the cardholder or issuer is not registered for 3D-Secure), then the system will continue to process the payment as a non-3D transaction.)

• This option will become obsolete in the near future, when 3D-Secure becomes mandatory for all card schemes.

Non-3D

Merchant Requirement

I would like to make a simple non-3D-Secure transaction.

This is relevant to merchants who operate in parts of the world that do not support 3D-Secure.

Nuvei Solutions

• Using the Checkout Page (seamless integration)
• Using the Web SDK:
  • Using the createPayment() method.
  • See the Web SDK Quick Start
    
    Before using Web SDK for non-3D payments, you must contact Nuvei and have them configure your account for the non-3D payment flow.

• Using API:
  • Send 3D-Secure /payment requests without the threeD JSON block.

3D-Only (MPI only)

Merchant Requirement

I would like to run authorizer/authenticate 3D.

I would like to use Nuvei’s 3D-Secure authorization and authentication services only, and then continue to process the transaction with another payment provider.

Nuvei Solutions

• Checkout Page – Not applicable
• Using the Web SDK:
  • Using the authenticate3d() method.
  • See the 3D-Secure-Only Transaction (MPI) (in the 3D-Secure How-To Guide).
• Using API:
  • Perform a 3D Auth with /authorize3d, then verify it with /verify3d API calls.
  • See the Server-to-Server Integration – adapted for MPI-Only.
  • Work with a full sample workflow that demonstrates the 3D-Secure Authorization and Authentication for processing with other payment providers. That scenario is in the Nuvei Postman collection. To access it, import the JSON file in the link into Postman and follow additional instructions in Testing APIs with Postman.

Liability Shift Payment (External MPI)

Merchant Requirement

I want to run a liability-shifted transaction using 3D authentication I have made with my MPI provider.
Some merchants prefer to receive the 3D-Secure service from a different party (e.g. having one 3D-Secure provider and multiple payment providers).

• Potentially, you can use Nuvei as the “third-party” 3D-Secure provider, as described in the previous 3D-Only section. In this case, you should not use the externalMpi JSON block, but instead use the relatedTransactionId received from the /verify3d request you have performed with the 3D-Only procedure.

Nuvei Solutions

• Checkout Page – Not applicable
• Web SDK – Not applicable
• Using API:
  • /payment: With externalMpi JSON block that specifies the authentication output received from the third-party 3D provider.
  • See the External MPI (Third-Party 3D-Secure) section under the 3D-Secure Guide.
  • Work with a full workflow using the Liability-shifted Transaction using 3D Authentication sample. This scenario is in the Nuvei Postman collection. To access it, import the JSON file in the link into Postman and follow additional instructions in Testing APIs with Postman.

Merchant Initiation Transaction (MIT) / Recurring

Merchant Requirement

I would like to manage a recurring plan on my system.

Nuvei Solutions

Nuvei provides the necessary service for a merchant to run a self-managed recurring system. For example, the ability to tokenize, to run an MIT, to perform an “Add Card” to a customer account without performing a transaction, etc.
All these actions have certain rules that need to be followed and dictated by the card schemes and Nuvei can do this on your behalf.
In doing so you are also taking advantage of Nuvei User Payment Option management(UPO), which allows you to add cards and other payment methods and manage them on your behalf.

Steps

Step 1: Initiating a Recurring Session

• Using the Checkout Page (seamless integration).
• Using the Web SDK:
  • Using the createPayment() method. Prior to calling the createPayment(), you need to set the recurring flags on the server-side /openOrder API call:
    • isRebilling”: “0” to mark it to as initializing a recurring session.
• Using API:
  • /payment with recurring flags.
    • isRebilling”: “0” to mark it to as initializing a recurring session.
  • Work with a full workflow using the Recurring (with 3D-Secure) sample. The scenario is in the Nuvei Postman collection. To access it, import the JSON file in the link into Postman and follow additional instructions in Testing APIs with Postman.

Step 2: Initiating a Recurring Session

• Checkout Page – Not applicable
• Web SDK – Not applicable
• Using API:
  • /payment: With the relatedTransactionId of the initiating payment request in Step 1.
    Also provide the userPaymentOptionId retrieved from the initiating payment request, which represents the customer payment option for charging.
  • /payment: With any of the above scenarios and with rebilling fields, not using UserTokenId
  • Web SDK: createPayment(), rebilling fields are set via /openOrder.
  • Work with a full workflow using the Recurring (with 3D-Secure) sample. The scenario is in the Nuvei Postman collection. To access the collection, import the JSON file in the link into Postman and follow additional instructions in Testing APIs with Postman.

Step 3:

• Using the /payment method with the relatedTransactionId, not using UPO.
• Web SDK: Not supported by Web SDK, only Server-to-Server.

Alternative Payment Methods (APMs)

Merchant Requirement

I would like to process APMs with Nuvei.

Nuvei Solutions

• Using the Checkout Page (seamless integration).
• Using the Web SDK:
  • See Web SDK APMs.
  • Using the createPayment() method, providing the alternativePaymentMethod JSON block with the relevant payment method details. You can also use the getAPMs() method to retrieve the relevant APMs for the customer.
  • The function will automatically redirect the customer for the completion of the payment.
• Using API:
  • Using the /payment method and specifying the alternativePaymentMethod JSON block.
  • Using the /getMerchantPaymentMethods method.