Skip to main content

Recurring

Overview​

Recurring and unscheduled payments require a prior agreement, the standing instruction, between the buyer and the seller or platform. This agreement allows the seller to initiate future payments without the buyer re-entering payment methods details each time.

The payment instrument is securely stored on file, and subsequent payments can be initiated by referencing the standing instruction created during the initial payment, where the buyer explicitly authorizes the platform and the seller to charge the additional payments.

  • Recurring payments: periodic charges at a fixed frequency (e.g., weekly, monthly) with either fixed or variable amounts (e.g., metered or usage-based subscriptions but still follow a regular schedule).
  • Unscheduled charges: variable or fixed amount payments with no fixed schedule or frequency (e.g., account top-ups or pay-per-use services without fixed frequency).
  • Customer-initiated payments using stored credentials: the buyer previously chose to save their payment method during checkout and later triggers a new payment using the stored credential.
  • Installment plans: a finite series of payments over a fixed term agreed upfront.
  • Delayed charges: follow-up payments for additional amounts related to the same service.
  • No show: charges applied when the buyer consented to be billed if they fail to show up for a reserved service.
  • Reauthorizations: used to extend or refresh a prior authorization.
warning

The indication of the standing instruction does not trigger an automatic collection of the subsequent payments.

If you are interested in scheduled automatic payments via subscriptions, reach out the support team via support@getpaid.io for further details.

Steps​

1. Create initial payment​

Indicate in the checkout the standing instruction to create. Usually, you would like to specify a single payment method to use for the series.

Once the payment completed, an standing instruction is created in the solution so it can be reused in the subsequent payments.

In this scenario, the standing instruction will be created for recurring payments and it is a SEPA Direct Debit subscription.

POST api.getpaid.io/v2/checkouts
{
  "payment_methods": {
    "type": "explicit",
    "available": [
      {
        "type": "sepa_direct_debit"
      }
    ]
  },
  [...]
  "standing_instruction": {
    "terms": {
      "type": "recurring"
    }
  }
}

2. Enter payment method details​

The buyer enters their payment method details to authorize the initial payment of the sequence choosing the best payment method among the available in the hosted checkout.

The checkout process follows the same steps as any other payment initiated by the buyer.

3. Checkout completed notification​

Once the checkout is completed, your platform server receives a checkout_completed webhook that includes the standing instruction information to be reused in the subsequent payments.

checkout_completed webhook
{
  "id": "evt_4jbfjc3dfybnw9f15en0rve844",
  "type": "checkout_completed",
  "version": "v2",
  "occurred_at": "2025-10-24T14:52:57.312Z",
  "data": {
    "id": "cko_44678r08jtm8zbt227tzhc4nw5",
    "reference": "ORD-202510-0232",
    "payment": {
      "id": "pay_4kf9v6xp00hzc99rdwr5m97wce",
      "standing_instruction": {
        "id": "sti_4tbftjwzxja1h71nzas1g0g1xm",
        "status": "active"
      }
    }
  }
}

4. Create subsequent payment​

For each subsequent payment, your first step is to create a payment via API by calling POST api.getpaid.io/v2/payments endpoint, setting the payment information and how funds, splits between the parties involved, and the original standing instruction to trigger a payment initiated by the seller that do not require buyer interaction.

POST api.getpaid.io/v2/payments
{
  "reference": "ORD-202511-0133",
  [...]
  "standing_instruction": {
    "id": "sti_4tbftjwzxja1h71nzas1g0g1xm"
  }
}

5. Handle payment response​

A successful payment creation returns a payment id and an in progress or final authorization or capture status.

201 Created - POST api.getpaid.io/v2/payments
{
  "id": "pay_4asvwjbgbypk6d9z3xp95ttrc8",
  [...]
}

6. Payment captured notification​

After the payment funds are secured, your platform server receives a payment_captured webhook that includes the standing instruction information to be reused in the subsequent payments.

The payment capture estimated arrival depends on the payment method selected, while in cards is usually seconds, for online banking methods could take days.

payment_captured webhook
{
  "id": "evt_4zbqpghwmh5sde072ay1h6t34p",
  "type": "payment_captured",
  "version": "v2",
  "occurred_at": "2025-11-24T16:12:49.321Z",
  "data": {
    "id": "pay_4asvwjbgbypk6d9z3xp95ttrc8",
    "reference": "ORD-202511-0133"
  }
}