Documentation

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:

  1. Create the payment agreement with the necessary information for consumer authentication.
  2. Authenticate the payment agreement and/or an initial charge.
  3. 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 and amount.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 of https://redirection-target.ppro.com/ using the returned $.authenticationMethods[?(@.type == "REDIRECT")].details.requestMethod HTTP method.


3. Handle the result

REDIRECT

  1. After the consumer completes the authentication, they are redirected to the returnUrl specified in the payment charge creation request.
  2. Upon redirect back to your site, retrieve the latest agreement status by performing a GET /v1/payment-agreements/{agreementId}. Use the returned status field to determine and display the final payment outcome to the consumer.
  3. Additionally, webhooks are triggered to notify you of the payment result. This ensures you receive the outcome even if the consumer closes their browser or fails to return to your website.

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 9 months ago

Did this page help you?