ProductsDeveloperSupport

Recurring Payments

Suggest Edits

Introduction

In cases where a one-off payment is not sufficient, such as a recurring monthly subscription or a payment split across a number of months, our recurring payment features can be used.

Payment API

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.

1. 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 begin
  • numberOfPayments - the total number of payments that will be taken over the course of the subscription
  • frequency - how often the payments will be taken
Click for example request / response

See the example request and response for this here:

{
    "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": "123"
        }
    },
    "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"
}

2. 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.

Click for example 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
sequencerepresents the sequence, available values for recurring payments are:
'FIRST' - initial payment
'SUBSEQUENT' - subsequent payment
scheduledindicator, if the payment is part of scheduled or unscheduled transaction, for recurring payments must be always set to 'true'
initiatorrepresents transaction initiator, available values;
'CARDHOLDER' - to be used for Recurring FIRST
'MERCHANT' - to be used for Recurring SUBSEQUENT
referencedSchemeTransactionIdvalue 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": "24"
  		}
  	}
  },
  "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": "2024"
            },
            "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
sequencerepresents the sequence, available values for recurring payments are:
"FIRST" - initial payment
"SUBSEQUENT" - subsequent payment
scheduledindicator, if the payment is part of scheduled or unscheduled transaction, for recurring payments must be always set to true
initiatorrepresents transaction initiator, available values;
"CARDHOLDER" - to be used for Recurring FIRST
"MERCHANT" - to be used for Recurring SUBSEQUENT
referencedSchemeTransactionIdvalue 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": "24"
  		}
  	}
  },
  "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": "2024"
            },
            "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": "24"
  		}
  	}
  },
"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": "2024"
            },
            "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": "24"
  		}
  	}
  },
  "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": "2024"
            },
            "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"
    }
}

Hosted Payment Page Recurring Scheduler

Recurring payments can either be triggered by your system every time a payment is due using our APIs or you can make use of our scheduler that allows you to define the frequency and period (e.g. every three days, every second week, every month, once a year, etc.)

To use this feature, the following additional parameters will have to be submitted in the initial transaction request form:

Field NameAvailable ValuesDescription
recurringInstallmentCountnumeric; min 2 max 999Represents the number of installments to be made including the initial transaction submitted
recurringInstallmentPeriod• day
• week
• month
• year		Represents the periodicity of the recurring payment
recurringInstallmentFrequencynumeric: min 1 max 99Represents the time period between installments

📘

Please note, that the start date of the recurring payments is the current date automatically calculated by the system.

Updated about 2 months ago