Overview

The subMethod class is used in different request methods to access the following advanced APM features:

• General APM Recurring Billing
  Specific APM providers offer a redirect “initial payment” and then direct server-to-server payments for subsequent recurring/re-bill payments, thereby eliminating the need for the customer to be involved.
• Special APM Recurring Billing
  Specific APM providers offer a direct server-to-server payment option for subsequent recurring/re-bill payments, thereby eliminating the need for the customer to be involved.
• Customer Registration via APM
  Specific APM providers offer a service to supply you with the customer details needed to register a new customer in your system, based on the customer details collected by the APM provider.

You can invoke these APM features from the Nuvei platforms as described below.

General APM Recurring Billing

Specific APM providers (listed in the table below) offer a redirect APM workflow for the initial payment and then direct server-to-server payments for subsequent recurring/re-bill payments, thereby eliminating the need for the customer to be involved.
The General APM Recurring Billing flow is available on the Cashier and REST API product platforms.

The specific APM providers supporting this feature are listed in the table below. The table also includes links to test data from some APM providers.

For REST API

This topic describes the General APM Recurring Billing Flow for specific APMs for REST API:

1. Send the initial redirect recurring payment, by sending a /payment request with its mandatory parameters, and include:
   • paymentOption.alternativePaymentMethod.paymentMethod: “<name of APM>“
   • paymentOption.subMethod.subMethod: “RECURRING“
   • Set the amount according to the relevant “Initial Amount” value for that APM, as shown in the table below:
     
     

     APMs using subMethod for Recurring Payments – with Initial Amounts

     Initial Amount	APMs
     0	Sepa, Dana, KaKaoPay, Gcash, Truemoney, Touch ’n Go, AlipayHK

     In the table above, press a “linked” APM name to see that APM’s test data (if available).

   Example Initial /payment Request

   {
     "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": "IDR",
     "amount": "0",
     "paymentOption": {
       "alternativePaymentMethod": {
         "paymentMethod": "apmgw_Dana"
       },
       "subMethod": {
         "subMethod": "RECURRING"
       }
     },
     "billingAddress": {
       "country": "ID",
       "email": "[email protected]"
     },
     "userDetails": {
       "firstName": "John",
       "lastName": "Smith",
       "email": "[email protected]",
       "phone": "6175551414"
     },
     "deviceDetails": {
       "ipAddress": "<customer's IP address>"
     },
     "timeStamp": "<YYYYMMDDHHmmss>",
     "checksum": "<calculated checksum>"
   }

2. The response returns a redirectURL.
   (The system also creates a UPO record, which is populated in the next step, and returns userPaymentOptionId.)

   Example Initial /payment Response

   {
     "reason": "",
     "orderId": "37588561",
     "transactionStatus": "REDIRECT",
     "clientRequestId": "F71YY27W1",
     "internalRequestId": 20648621,
     "version": "1.0",
     "merchantSiteId": "126006",
     "merchantId": "2502136204546424962",
     "clientUniqueId": "695701003",
     "errCode": 0,
     "paymentOption": {
       "redirectUrl": "https://europaytest.nuvei.com/AlipayOSP/Preapproval/PreapprovalLanding.aspx?ID=41061&Hash=180F9D617D642B48D0644F84C30F3364",
       "userPaymentOptionId": "8196851",
       "card": {}
     },
     "sessionToken": "171ec215-45ec-4da8-93f7-e759e481fb34",
     "userTokenId": "DNRSO145UVT6",
     "status": "SUCCESS"
   }

3. Redirect the customer to the redirectURL, for them to enter their APM account details
4. Upon completion, the system updates the UPO record with the captured customer details and the data collected from the request.
5. The system performs an internal process to link the customer’s APM account to the APM recurring system.
   • After a short period of time, a preApprovalID is generated and stored in the UPO record.
   • The preApprovalID indicates that customer’s APM account details are correct and can be used in subsequent payment requests, with no need to collect them again.
     If you are planning to send a subsequent recurring request immediately, then you should use the /getUserUPOs request to check if the preApprovalId has been created and stored in the UPO record.

6. From this point onwards, you can send subsequent recurring requests, using direct server-to-server /payment requests to the APM.
   Send a /payment request with its mandatory parameters and include:
   • paymentOption.userPaymentOptionId: “<ID of a previously stored payment option>“
   • paymentOption.subMethod.subMethod: “RECURRING“

   Example Subsequent /payment Request

   {
     "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": "IDR",
     "amount": "1000",
     "paymentOption": {
       "userPaymentOptionId": "<ID of a previously stored payment option>",
       "subMethod": {
         "subMethod": "RECURRING"
       }
     },
     "billingAddress": {
       "country": "ID",
       "email": "[email protected]"
     },
     "userDetails": {
       "firstName": "John",
       "lastName": "Smith",
       "email": "[email protected]",
       "phone": "6175551414"
     },
     "deviceDetails": {
       "ipAddress": "<customer's IP address>"
     },
     "timeStamp": "<YYYYMMDDHHmmss>",
     "checksum": "<calculated checksum>"
   }

Special APM Recurring Billing

The following specific APM providers (listed in the table below) support direct server-to-server recurring payment requests:

APM Providers Offering a Recurring Billing Service

APM	Parameter
PayPal – Billing Agreement	subMethod: "ReferenceTransaction"
Post Finance – Alias Registration	subMethod: "AliasRegistration"
Skrill – Skrill1Tap	subMethod: "Skrill1Tap"

Follow the steps to integrate this APM workflow into your site using the relevant Nuvei product platform/s, as described below:

• For REST API
• For Web SDK
• For Simply Connect

For REST API

For both the initial and subsequent /payment requests, include the relevant paymentOption.subMethod.subMethod parameter, listed in the APM Providers Offering a “Recurring Billing” Service table above.

Example /payment Request

{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "amount":"200",
  "currency":"USD",
  "userTokenId":"<unique customer identifier in merchant system>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "paymentOption":{
    "alternativePaymentMethod":{
      "paymentMethod":"apmgw_MoneyBookers",
      "account_id":"<Skrill account>"
    },
    "subMethod":{
      "subMethod":"skrill1Tap"
    }
  },
  "billingAddress":{
    "country":"US",
    "email":"[email protected]"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

For Web SDK

Send the initial payment as a regular redirect-based createPayment() request and include the relevant paymentOption.subMethod.subMethod parameter, listed in the APM Providers Offering a “Recurring Billing” Service table above.

This performs the initial payment and also registers the recurring billing agreement with the APM.

For an example, see the APM Recurring Billing topic.

For Simply Connect

Send the initial payment as a checkout() request, and include savePM: “true” to display a Save my details for future use checkbox for each payment method in the Payment Methods list.

When a customer chooses a payment method from the Payment Methods list and selects Save my details for future use, then the payment method details are stored.
If the payment method is an APM that supports the direct server-to-server payment option for subsequent recurring/re-bill payments, then the transaction is marked as the initial transaction in a Recurring Billing arrangement for that customer and payment method.

For an example, see the Perform a checkout() Payment topic.

Customer Registration via APM

The following APM providers offer a service to supply you with the customer details needed to register a new customer in your system, based on the customer details collected by the APM provider:

APM Providers Offering a “Customer Registration via APM” Service

APM	Parameter
PayPal	subMethod: "QuickRegistration"
Trustly	subMethod: "PayNPlay"

Follow the steps to integrate this APM workflow into your site using the relevant Nuvei product platform/s, as described below:

• For REST API
• For Web SDK
• For Simply Connect

For REST API

Send a /payment request and include the relevant paymentOption.subMethod.subMethod parameter, listed in the APM Providers for Customer Registration table above.
For an example, see the Initiate an APM Payment topic.

For Web SDK

Send a createPayment() request as a regular redirect-based request and include the relevant paymentOption.subMethod.subMethod parameter, listed in the APM Providers for Customer Registration table above.

This performs the payment with the APM and also returns all the customer details needed for you to register the new customer in your system.

For an example, see the Customer Registration via APM topic.

For Simply Connect

Send a checkout() payment request and include this parameter:

subMethod: [“PayNPlay”,”QuickRegistration”] //customer registration APM providers

For an example, see the Perform a checkout() Payment topic.