ProductsDeveloperSupport
Guides

Recurring Payments

Suggest Edits

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

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
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": "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
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": "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 3 months ago

API Products

Point of Sale

Developer

Resources

Contact Cookies Privacy Notice Legal

Copyright© 2024 Fiserv. All rights reserved.

First Data Europe Limited, is a subsidiary of Fiserv, Inc. and is trading as Fiserv. First Data Europe Limited, is a private limited company incorporated in England (Company Number 02012925) with a registered address at Janus House, Endeavour Drive, Basildon, Essex, SS14 3WF. First Data Europe Limited is authorised and regulated by the UK Financial Conduct Authority (FCA Register No. 582703; CCA No. 739230). All trademarks, service marks, and trade names referenced in this material are the property of their respective owners.

v1.11

Want a quick overview?