Recurring Payments
Recurring Scheduler
It is possible to set up a subscription payment via our APIs using the /payment-schedules endpoint. While using this option, the Gateway creates a subscription based on the information obtained in the first request.
Creating the subscription
Firstly, to start a new subscription, you must perform a POST providing all the necessary details about the subscription such as:
startDate- the date the payments should beginnumberOfPayments- the total number of payments that will be taken over the course of the subscriptionfrequency- how often the payments will be taken
See the example request and response below:
{
"requestType": "PaymentMethodPaymentSchedulesRequest",
"startDate": "2023-01-01",
"numberOfPayments": 11,
"maximumFailures": 1,
"invoiceNumber": "INV1234",
"purchaseOrderNumber": "PO1042",
"transactionOrigin": "ECOM",
"dynamicMerchantName": "A really cool merchant",
"frequency": {
"every": 1,
"unit": "MONTH"
},
"paymentMethod": {
"paymentCard": {
"number": "1234123412341234",
"expiryDate": {
"month": "01",
"year": "28"
},
"securityCode": "XXX"
}
},
"transactionAmount": {
"total": "20.99",
"currency": "EUR"
}
}
{
"clientRequestId": "6e9e3521-ef4e-4598-94c5-83e3ce07ed03",
"apiTraceId": "YzQkrsQq0Q2umBxuy6d4cQAAAvU",
"requestStatus": "SUCCESS",
"orderId": "R-79ae2b06-78b2-4d8b-9640-c379a5b6420f",
"state": "Installed"
}
Managing the subscription
Once a payment schedule has been established, there are then 3 actions that can be taken on it:
- View the schedule to see how it is progressing
- Update the schedule, for example to adjust the amount to be paid
- Cancel the schedule, preventing all future payments
For example, if we want to view an existing subscription, we would use the orderId returned in the above response.
The same principles apply in using orderId to update or cancel an existing subscription.
// GET /payment-schedules/R-79ae2b06-78b2-4d8b-9640-c379a5b6420f
{
"clientRequestId": "85b51979-e291-42f7-a2a5-4fa712297926",
"apiTraceId": "YzQ7X5pRN-z9R2q7VM8EawAAAXg",
"orderId": "R-79ae2b06-78b2-4d8b-9640-c379a5b6420f",
"transactions": [],
"recurringPaymentDetails": {
"storeId": "72305408",
"purchaseOrderNumber": "PO1042",
"invoiceNumber": "INV1234",
"creationDate": "Wed Sep 28 14:19:25 CEST 2022",
"startDate": "Sun Jan 01 00:00:00 CET 2023",
"nextAttemptDate": "Sun Jan 01 00:00:00 CET 2023",
"creationDateFormatted": "2022-09-28",
"startDateFormatted": "2023-01-01",
"nextAttemptDateFormatted": "2023-01-01",
"transactionAmount": {
"total": 20.99,
"currency": "EUR",
"components": {
"subtotal": 20.99
}
},
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "10",
"year": "45"
},
"last4": "1002"
},
"paymentMethodType": "PAYMENT_CARD"
},
"frequency": {
"every": 1,
"unit": "MONTH"
},
"numberOfPayments": 10,
"runCount": 0,
"state": "Installed"
}
}
Please note, that Recurring Scheduler cannot be used in a combination with 3-D Secure authentication flow.
Recurring Payments (Merchant Managed)
For cases when you would prefer to manage the recurring schedule yourself you must indicate to the Gateway, if the recurring transaction represents the first or subsequent transaction.
Please use the following mandatory parameters to submit initial recurring payment:
| storedCredentials | Parameter description |
|---|---|
sequence | represents the sequence, available values for recurring payments are: 'FIRST' - initial payment 'SUBSEQUENT' - subsequent payment |
scheduled | indicator, if the payment is part of scheduled or unscheduled transaction, for recurring payments must be always set to 'true' |
initiator | represents transaction initiator, available values; 'CARDHOLDER' - to be used for Recurring FIRST 'MERCHANT' - to be used for Recurring SUBSEQUENT |
referencedSchemeTransactionId | value received in the response from "recurring FIRST" transaction in the response parameterschemeTransactionId |
The following JSON document represents an example of a Recurring FIRST transaction with minimal set of elements:
{
"requestType": "PaymentCardSaleTransaction",
"transactionAmount": {
"total": "12.00",
"currency": "EUR"
},
"paymentMethod": {
"paymentCard": {
"number": "414746******0083",
"securityCode": "XXX",
"expiryDate": {
"month": "12",
"year": "28"
}
}
},
"storedCredentials": {
"sequence": "FIRST",
"scheduled": true,
"initiator": "CARDHOLDER"
}
}
In the response from the Gateway you will receive schemeTransactionId what must be used as a reference in the subsequent recurring request.
Below JSON document represents an example of a response:
{
"clientRequestId": "b7d87061-c5e4-44a6-a4d0-f6a410c7d5ef",
"apiTraceId": "ZLE50eVaHdp5HHvQ-HnBjAAAA5w",
"ipgTransactionId": "84631563084",
"orderId": "R-a81bdb91-b27e-41d3-afc0-cf52ffd6aa89",
"transactionType": "SALE",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"brand": "VISA",
"type": "PAYMENT_CARD"
},
"transactionOrigin": "ECOM",
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "12",
"year": "2028"
},
"bin": "414746",
"last4": "0083",
"brand": "VISA"
},
"paymentMethodType": "PAYMENT_CARD",
"paymentMethodBrand": "VISA"
},
"country": "Singapore",
"terminalId": "80000860",
"merchantId": "000102072004393",
"transactionTime": 1689336274,
"approvedAmount": {
"total": 12.00,
"currency": "EUR",
"components": {
"subtotal": 12.00
}
},
"transactionAmount": {
"total": 12.00,
"currency": "EUR",
"components": {
"subtotal": 12.00
}
},
"transactionStatus": "APPROVED",
"approvalCode": "Y:912110:4631563084:YYYM:991940",
"schemeTransactionId": "234567891234560",
"processor": {
"referenceNumber": "319512991940",
"authorizationCode": "912110",
"responseCode": "00",
"responseMessage": "Function performed error-free",
"avsResponse": {
"streetMatch": "Y",
"postalCodeMatch": "Y"
},
"securityCodeResponse": "MATCHED"
}
}
In order to differentiate between initial and subsequent recurring payment, you need to change the values in storedCredentials parameters, so that the Gateway is able to flag the authorisation message accordingly.
The following parameters are mandatory for Recurring SUBSEQUENT transactions request:
| storedCredentials | Parameter description |
|---|---|
sequence | represents the sequence, available values for recurring payments are: "FIRST" - initial payment "SUBSEQUENT" - subsequent payment |
scheduled | indicator, if the payment is part of scheduled or unscheduled transaction, for recurring payments must be always set to true |
initiator | represents transaction initiator, available values; "CARDHOLDER" - to be used for Recurring FIRST "MERCHANT" - to be used for Recurring SUBSEQUENT |
referencedSchemeTransactionId | value received in the response from "recurring FIRST" transaction in the response parameterschemeTransactionId |
In the next step you submit a request as specified below:
{
"requestType": "PaymentCardSaleTransaction",
"transactionAmount": {
"total": "12.00",
"currency": "EUR"
},
"paymentMethod": {
"paymentCard": {
"number": "414746******0083",
"securityCode": "XXX",
"expiryDate": {
"month": "12",
"year": "28"
}
}
},
"storedCredentials": {
"sequence": "SUBSEQUENT",
"scheduled": true,
"initiator": "MERCHANT",
"referencedSchemeTransactionId": "234567891234560"
}
}
{
"clientRequestId": "21fd05d9-fbfd-49ea-8eed-c984ced93532",
"apiTraceId": "ZLE8XvUX_78lJa8mrtHpGQAAAGY",
"ipgTransactionId": "84631563684",
"orderId": "R-704d9763-36c3-468c-9237-4f663990d068",
"transactionType": "SALE",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"brand": "VISA",
"type": "PAYMENT_CARD"
},
"transactionOrigin": "ECOM",
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "12",
"year": "2028"
},
"bin": "414746",
"last4": "0083",
"brand": "VISA"
},
"paymentMethodType": "PAYMENT_CARD",
"paymentMethodBrand": "VISA"
},
"country": "Singapore",
"terminalId": "80000860",
"merchantId": "000102072004393",
"transactionTime": 1689336926,
"approvedAmount": {
"total": 12.00,
"currency": "EUR",
"components": {
"subtotal": 12.00
}
},
"transactionAmount": {
"total": 12.00,
"currency": "EUR",
"components": {
"subtotal": 12.00
}
},
"transactionStatus": "APPROVED",
"approvalCode": "Y:392681:4631563684:YYYM:991974",
"schemeTransactionId": "234567891234560",
"processor": {
"referenceNumber": "319512991974",
"authorizationCode": "392681",
"responseCode": "00",
"responseMessage": "Function performed error-free",
"avsResponse": {
"streetMatch": "Y",
"postalCodeMatch": "Y"
},
"securityCodeResponse": "MATCHED"
}
}
Recurring Payments with 3-D Secure
In case you are impacted with PSD2 mandate for Strong Customer Authentication (SCA) and you are managing recurring payments yourself, you need to authenticate the cardholder during initial recurring transaction. In such case you need to include additional parameters in the API request as per scheme requirements.
Please use challengeIndicator value = "04" (Challenge mandated), so that the cardholders are able to authenticate themselves while they are in session.
The following JSON document represents an example of a Recurring FIRST transaction including authentication request:
{
"requestType": "PaymentCardSaleTransaction",
"transactionAmount": {
"total": "22.00",
"currency": "EUR"
},
"paymentMethod": {
"paymentCard": {
"number": "4149011****0527",
"securityCode": "999",
"expiryDate": {
"month": "12",
"year": "28"
}
}
},
"storedCredentials": {
"sequence": "FIRST",
"scheduled": true,
"initiator": "CARDHOLDER"
},
"authenticationRequest": {
"authenticationType": "Secure3DAuthenticationRequest",
"termURL": "https://test.ipg-online.com/webshop/simulator/secure3d/return",
"methodNotificationURL": "https://test.ipg-online.com/ipgconfirmation/services/secure3ds",
"challengeIndicator": "04"
}
}
In the next step you must follow our 3-D Secure specification for processing the authentication, so that recurring payment may be completed.
After the authentication has been completed successfully and the cardholder has been fully authenticated, you will receive a response from the Gateway as on example below:
{
"clientRequestId": "5dda0dd1-1130-4ce0-8822-9f1161130399",
"apiTraceId": "ZLFKZ-DocBc3wPjA216CbwAAAtc",
"ipgTransactionId": "84631578706",
"orderId": "R-acacb8bd-de0c-4b05-a784-84c1c25ddb4c",
"transactionType": "SALE",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"brand": "VISA",
"type": "PAYMENT_CARD"
},
"transactionOrigin": "ECOM",
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "12",
"year": "2028"
},
"bin": "414901",
"last4": "0527",
"brand": "VISA"
},
"paymentMethodType": "PAYMENT_CARD",
"paymentMethodBrand": "VISA"
},
"country": "Germany",
"terminalId": "80000860",
"merchantId": "000102072004393",
"transactionTime": 1689340441,
"approvedAmount": {
"total": 22,
"currency": "EUR",
"components": {
"subtotal": 22
}
},
"transactionAmount": {
"total": 22,
"currency": "EUR",
"components": {
"subtotal": 22
}
},
"transactionStatus": "APPROVED",
"approvalCode": "Y:370063:4631578706:YYYM:992110",
"secure3dResponse": {
"responseCode3dSecure": "1"
},
"schemeTransactionId": "234567891234560",
"processor": {
"referenceNumber": "319513992110",
"authorizationCode": "370063",
"responseCode": "00",
"responseMessage": "Function performed error-free",
"avsResponse": {
"streetMatch": "Y",
"postalCodeMatch": "Y"
},
"securityCodeResponse": "MATCHED"
}
}
As in previous cases you will obtain schemeTransactionId what you must use in all subsequent recurring payments as described above.
The process how to continue and trigger Recurring SUBSEQUENT transaction is identical as in case of Recurring payment without 3DS:
{
"requestType": "PaymentCardSaleTransaction",
"transactionAmount": {
"total": "12.00",
"currency": "EUR"
},
"paymentMethod": {
"paymentCard": {
"number": "414746******0083",
"securityCode": "XXX",
"expiryDate": {
"month": "12",
"year": "28"
}
}
},
"storedCredentials": {
"sequence": "SUBSEQUENT",
"scheduled": true,
"initiator": "MERCHANT",
"referencedSchemeTransactionId": "234567891234560"
}
}
{
"clientRequestId": "21fd05d9-fbfd-49ea-8eed-c984ced93532",
"apiTraceId": "ZLE8XvUX_78lJa8mrtHpGQAAAGY",
"ipgTransactionId": "84631563684",
"orderId": "R-704d9763-36c3-468c-9237-4f663990d068",
"transactionType": "SALE",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"brand": "VISA",
"type": "PAYMENT_CARD"
},
"transactionOrigin": "ECOM",
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "12",
"year": "2028"
},
"bin": "414746",
"last4": "0083",
"brand": "VISA"
},
"paymentMethodType": "PAYMENT_CARD",
"paymentMethodBrand": "VISA"
},
"country": "Singapore",
"terminalId": "80000860",
"merchantId": "000102072004393",
"transactionTime": 1689336926,
"approvedAmount": {
"total": 12.00,
"currency": "EUR",
"components": {
"subtotal": 12.00
}
},
"transactionAmount": {
"total": 12.00,
"currency": "EUR",
"components": {
"subtotal": 12.00
}
},
"transactionStatus": "APPROVED",
"approvalCode": "Y:392681:4631563684:YYYM:991974",
"schemeTransactionId": "234567891234560",
"processor": {
"referenceNumber": "319512991974",
"authorizationCode": "392681",
"responseCode": "00",
"responseMessage": "Function performed error-free",
"avsResponse": {
"streetMatch": "Y",
"postalCodeMatch": "Y"
},
"securityCodeResponse": "MATCHED"
}
}
Updated 9 months ago
