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 is completed, a standing instruction is activated so it can be reused for subsequent payments.

In this scenario, the standing instruction is created for recurring SEPA Direct Debit payments.

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.

For SEPA Direct Debit, the standing instruction becomes active after the mandate is confirmed.

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",
  [...]
  "method": {
    "type": "sepa_direct_debit",
    "remittance_info": "TITANAUTO - Invoice 202511-0133"
  },
  "standing_instruction": {
    "id": "sti_4tbftjwzxja1h71nzas1g0g1xm"
  }
}

5. Handle payment response​

A successful payment creation returns a payment id and its current 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 estimated capture time depends on the payment method. For example, while card payments usually complete in seconds, SEPA Direct Debit payments can take up to 3 business 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"
  }
}