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:
- 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
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>" }
- The response returns a
redirectURL
.
(The system also creates a UPO record, which is populated in the next step, and returnsuserPaymentOptionId
.)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" }
- Redirect the customer to the
redirectURL
, for them to enter their APM account details - Upon completion, the system updates the UPO record with the captured customer details and the data collected from the request.
- 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.
- After a short period of time, a
- 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 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 the savePM: true
parameter 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 the “Save my details for future use” checkbox, 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
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.