Quickstart: Recurring
This guide assumes a basic understanding of PPRO's core API objects, common API functionality and recurring payments.
Payment agreements simplify the management of recurring payments by streamlining the setup process and reducing operational complexity. Certain payment methods require a payment agreement to support recurring transactions.
The flow generally consists of three simple steps:
- Create the payment agreement with the necessary information for consumer authentication.
- Authenticate the payment agreement and/or an initial charge.
- Create subsequent recurring payments.
1. Create a payment agreement
You can also include the initialPaymentCharge
object in this agreement creation call to immediately initiate the first payment without making a separate call. If you include this object, you'll need to specify:
- The exact
amount.value
andamount.currency
of the first payment.
Request
POST /v1/payment-agreements
{
"paymentMethod": "PAYMENT_METHOD",
"consumer": {
"name": "John Smith",
"country": "US"
},
"description": "Monthly Subscription",
"startDate": "2025-03-26T00:00:000Z",
"endDate": "2026-03-25T00:00:000Z",
"frequency": {
"type": "MONTHLY",
"interval": 1
},
"amount": {
"value": 1000,
"currency": "USD"
},
"amountType": "EXACT",
"authenticationSettings": [
{
"type": "REDIRECT",
"settings": {
"returnUrl": "https://www.webshop.com/order-results-page"
}
}
]
}
{
"paymentMethod": "PAYMENT_METHOD",
"consumer": {
"name": "John Smith",
"country": "US"
},
"description": "Monthly Subscription",
"startDate": "2025-03-26T00:00:000Z",
"endDate": "2026-03-25T00:00:000Z",
"frequency": {
"type": "MONTHLY",
"interval": 1
},
"amount": {
"value": 1000,
"currency": "USD"
},
"amountType": "EXACT",
"authenticationSettings": [
{
"type": "REDIRECT",
"settings": {
"returnUrl": "https://www.webshop.com/order-results-page"
}
}
],
"initialPaymentCharge": {
"amount": {
"value": 1000,
"currency": "USD"
}
}
}
Response
{
"id": "agr_7ojvgTjYX3K4px0nVg9Ha",
"status": "AUTHENTICATION_PENDING",
"description": "Monthly Subscription",
"paymentMethod": "PAYMENT_METHOD",
"frequency": {
"type": "MONTHLY",
"interval": 1
},
"startDate": "2025-03-26T00:00:00.000Z",
"endDate": "2026-03-25T00:00:00.000Z",
"amount": {
"value": 1000,
"currency": "USD"
},
"instrumentId": "instr_1SqRaKkRdGRsOZhyeNXzk",
"amountType": "EXACT",
"consumer": {
"name": "John Smith",
"country": "US"
},
"authenticationMethods": [
{
"details": {
"requestUrl": "https://redirection-target.ppro.com",
"requestMethod": "GET"
},
"type": "REDIRECT"
}
],
"history": [
{
"id": "ahist_lmwBQn9SXJbMtDJrZSmwI",
"status": "AUTHENTICATION_PENDING",
"createdAt": "2025-04-28T12:33:53.041Z"
}
],
"createdAt": "2025-04-28T12:33:53.041Z",
"updatedAt": "2025-04-28T12:33:53.041Z"
}
{
"id": "agr_BNwOGWPuOqPhtOHagGJmr",
"status": "AUTHENTICATION_PENDING",
"description": "Monthly Subscription",
"paymentMethod": "PAYMENT_METHOD",
"frequency": {
"type": "MONTHLY",
"interval": 1
},
"startDate": "2025-03-26T00:00:00.000Z",
"endDate": "2026-03-25T00:00:00.000Z",
"amount": {
"value": 1000,
"currency": "USD"
},
"instrumentId": "instr_elaSc3HlNj5UgjrAXzVW0",
"amountType": "EXACT",
"consumer": {
"name": "John Smith",
"country": "US"
},
"authenticationMethods": [
{
"details": {
"requestUrl": "https://redirection-target.ppro.com",
"requestMethod": "GET"
},
"type": "REDIRECT"
}
],
"history": [
{
"id": "ahist_4wiMQPW73VndvXLEueZil",
"status": "AUTHENTICATION_PENDING",
"createdAt": "2025-04-28T12:59:43.713Z"
}
],
"initialPaymentChargeId": "charge_gR0bxFxiHF6SWmUaym8Sh",
"createdAt": "2025-04-28T12:59:43.713Z",
"updatedAt": "2025-04-28T12:59:43.713Z"
}
The agreement status is AUTHENTICATION_PENDING
and requires authenticating by the consumer before it is ready to accept charges.
2. Pick the desired authentication method
REDIRECT
- Redirect your consumer to the returned
$.authenticationMethods[?(@.type == "REDIRECT")].details.requestUrl
.
For example, with the value ofhttps://redirection-target.ppro.com/
using the returned$.authenticationMethods[?(@.type == "REDIRECT")].details.requestMethod
HTTP method. - The consumer will finalize the agreement and/or the payment process on the redirected page.
3. Handle the result
REDIRECT
- Once the consumer has confirmed the agreement and/or payment, they are redirected to the
returnUrl
provided in the payment agreement creation request. - After the consumer is redirected back to your site, check the agreement and/or payment status and use the
Status
that you received to display the outcome to the consumer.
GET /v1/payment-agreements/{agreement-id}
GET /v1/payment-charges/{paymentChargeId} - Webhooks are also sent to inform you of the agreement and/or payment outcome. If the shopper closes the browser and doesn't return to your website, you can rely on webhooks to receive the result.
- Store the Payment Agreement ID for subsequent payments.
4. Create a recurring payment
To initiate a subsequent recurring payment, send a request against an active agreement /v1/payment-agreements/{agreement-id}/payment-charges.
Request
POST /v1/payment-agreements/{agreementId}/payment-charges
{
"amount": {
"value": 1000,
"currency": "USD"
},
"initiator": "MERCHANT"
}
Response
{
"id": "charge_tUgsdN6qmNiwIIe7cIok5",
"paymentMethod": "PAYMENT_METHOD",
"currency": "USD",
"country": "US",
"instrumentId": "instr_elaSc3HlNj5UgjrAXzVW0",
"status": "CAPTURED",
"consumer": {
"name": "John Smith",
"country": "US"
},
"authorizations": [
{
"id": "authz_0KSy64HI5jNO4Y1KS4PA7",
"amount": 1000,
"status": "AUTHORIZED",
"schemeAuthorizationReference": "MC1234567890ABCDE",
"createdAt": "2025-04-28T13:17:22.418Z",
"updatedAt": "2025-04-28T13:17:22.418Z"
}
],
"captures": [
{
"id": "capture_8FDZ0odFkQsLhNtY6A7TW",
"amount": 1000,
"status": "CAPTURED",
"createdAt": "2025-04-28T13:17:22.418Z",
"updatedAt": "2025-04-28T13:17:22.418Z"
}
],
"refunds": [],
"voids": [],
"createdAt": "2025-04-28T13:17:22.305Z",
"updatedAt": "2025-04-28T13:17:22.418Z"
}
5. Retrieve all recurring payments against under an agreement
Request
GET /v1/payment-charges?agreementId={agreementId}
Response
{
"data": [
{
"id": "charge_gR0bxFxiHF6SWmUaym8Sh",
"paymentMethod": "PAYMENT_METHOD",
"paymentMedium": "ECOMMERCE",
"scheduleType": "RECURRING",
"instrumentId": "instr_elaSc3HlNj5UgjrAXzVW0",
"currency": "USD",
"country": "US",
"status": "CAPTURED",
"consumer": {
"name": "John Smith",
"country": "US"
},
"authenticationMethods": [
{
"details": {
"requestUrl": "https://redirection-target.ppro.com",
"requestMethod": "GET"
},
"type": "REDIRECT"
}
],
"authorizations": [
{
"id": "authz_xaGb4Wa0SsrwRAzvtiCrn",
"amount": 1000,
"status": "AUTHENTICATION_PENDING",
"createdAt": "2025-04-28T12:59:43.668Z",
"updatedAt": "2025-04-28T12:59:43.668Z"
},
{
"id": "authz_ccJpek3gzJYVtbjPgZHlU",
"amount": 1000,
"status": "AUTHORIZED",
"createdAt": "2025-04-28T13:17:15.214Z",
"updatedAt": "2025-04-28T13:17:15.214Z"
}
],
"captures": [
{
"id": "capture_iiHPli7lkalrbMKzPA0mq",
"amount": 1000,
"status": "CAPTURED",
"createdAt": "2025-04-28T13:17:15.214Z",
"updatedAt": "2025-04-28T13:17:15.214Z"
}
],
"refunds": [],
"voids": [],
"createdAt": "2025-04-28T12:59:43.518Z",
"updatedAt": "2025-04-28T13:17:15.214Z"
},
{
"id": "charge_tUgsdN6qmNiwIIe7cIok5",
"paymentMethod": "PAYMENT_METHOD",
"paymentMedium": "ECOMMERCE",
"scheduleType": "RECURRING",
"instrumentId": "instr_elaSc3HlNj5UgjrAXzVW0",
"currency": "USD",
"country": "US",
"status": "CAPTURED",
"consumer": {
"name": "John Smith",
"country": "US"
},
"authorizations": [
{
"id": "authz_0KSy64HI5jNO4Y1KS4PA7",
"amount": 1000,
"status": "AUTHORIZED",
"createdAt": "2025-05-28T13:17:22.418Z",
"updatedAt": "2025-05-28T13:17:22.418Z"
}
],
"captures": [
{
"id": "capture_8FDZ0odFkQsLhNtY6A7TW",
"amount": 1000,
"status": "CAPTURED",
"createdAt": "2025-05-28T13:17:22.418Z",
"updatedAt": "2025-05-28T13:17:22.418Z"
}
],
"refunds": [],
"voids": [],
"createdAt": "2025-05-28T13:17:22.305Z",
"updatedAt": "2025-05-28T13:17:22.418Z"
},
{
"id": "charge_K0kX3IiH74fT9P48FL2Nb",
"paymentMethod": "PAYMENT_METHOD",
"paymentMedium": "ECOMMERCE",
"scheduleType": "RECURRING",
"instrumentId": "instr_elaSc3HlNj5UgjrAXzVW0",
"currency": "USD",
"country": "US",
"status": "CAPTURED",
"consumer": {
"name": "John Smith",
"country": "US"
},
"authorizations": [
{
"id": "authz_RbQgBUHo7YE0iG2RwUKk9",
"amount": 599,
"status": "AUTHORIZED",
"createdAt": "2025-06-28T13:20:29.207Z",
"updatedAt": "2025-06-28T13:20:29.207Z"
}
],
"captures": [
{
"id": "capture_gjnkGISVah7SwSYpzh4As",
"amount": 599,
"status": "CAPTURED",
"createdAt": "2025-06-28T13:20:29.207Z",
"updatedAt": "2025-06-28T13:20:29.207Z"
}
],
"refunds": [],
"voids": [],
"createdAt": "2025-06-28T13:20:29.116Z",
"updatedAt": "2025-06-28T13:20:29.207Z"
},
{
"id": "charge_2zWzf3HU4ANaJPEbToKqH",
"paymentMethod": "PAYMENT_METHOD",
"paymentMedium": "ECOMMERCE",
"scheduleType": "RECURRING",
"instrumentId": "instr_elaSc3HlNj5UgjrAXzVW0",
"currency": "USD",
"country": "US",
"status": "CAPTURED",
"consumer": {
"name": "John Smith",
"country": "US"
},
"authorizations": [
{
"id": "authz_eAtEQivx109SqHRzddU16",
"amount": 2899,
"status": "AUTHORIZED",
"createdAt": "2025-07-28T13:20:35.911Z",
"updatedAt": "2025-07-28T13:20:35.911Z"
}
],
"captures": [
{
"id": "capture_0VpHCisRhhp2zsjOzFHEA",
"amount": 2899,
"status": "CAPTURED",
"createdAt": "2025-07-28T13:20:35.911Z",
"updatedAt": "2025-07-28T13:20:35.911Z"
}
],
"refunds": [],
"voids": [],
"createdAt": "2025-07-28T13:20:35.837Z",
"updatedAt": "2025-07-28T13:20:35.911Z"
}
],
"_links": {
"payment_charge1": {
"href": "/v1/payment-charges/charge_gR0bxFxiHF6SWmUaym8Sh"
},
"payment_charge2": {
"href": "/v1/payment-charges/charge_tUgsdN6qmNiwIIe7cIok5"
},
"payment_charge3": {
"href": "/v1/payment-charges/charge_K0kX3IiH74fT9P48FL2Nb"
},
"payment_charge4": {
"href": "/v1/payment-charges/charge_2zWzf3HU4ANaJPEbToKqH"
}
}
}
6. Revoke a payment agreement
Request
POST /v1/payment-agreements/{agreementId}/revocations
Response
{
"status": "REVOKED"
}
Not using payment agreements?
It's possible to process recurring card payments without using payment agreements. Instead, the saved payment instrument Id can be used to initiate recurring payments.
Request
Include the instrumentId
in the payment charge request to initiate a recurring payment.
{
"paymentMethod": "CARD",
"initiator": "MERCHANT",
"scheduleType": "UNSCHEDULED",
"initialSchemeAuthorizationReference": "MC1234567890ABCDE",
"instrumentId": "instr_KMkZAlNzIhaXD1il7DD72",
"amount": {
"value": 1000,
"currency": "BRL"
},
"consumer": {
"name": "John Smith",
"country": "BR"
}
}
Updated 15 days ago