> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/customers-and-saved-methods/recurring-payments.md).

# Recurring Payments Guide

Build recurring billing on top of customers, tokenization, and regular payment creation.

## Overview

The public API does not document a dedicated subscriptions scheduler. Instead, recurring billing is assembled from these primitives:

* Customers: `POST /v1/customers`
* Tokenization sessions: `POST /v1/sessions` with `"type": "tokenization"`
* Saved instrument management: `GET` and `DELETE /v1/customers/{customerId}/payment-instruments`
* Charges against saved instruments: `POST /v1/payments`

The public contract also does not document a "set default payment instrument" endpoint. If you need a preferred card, choose it in your own application logic.

Use this guide for charging saved instruments on your own billing schedule. For the reusable-card collection flow itself, use [Tokenization Guide](/rest-api/customers-and-saved-methods/tokenization-guide.md).

## Recommended Recurring Flow

### 1. Create the customer

```http
POST /v1/customers
Authorization: Basic {credentials}
Content-Type: application/json

{
  "referenceId": "subscriber-1001",
  "email": "subscriber@example.com",
  "firstName": "Test",
  "lastName": "Subscriber"
}
```

### 2. Collect a reusable payment instrument

Create a tokenization session and associate it with the customer.

```http
POST /v1/sessions
Authorization: Basic {credentials}
Content-Type: application/json

{
  "merchantId": 12345,
  "referenceId": "subscription-setup-1001",
  "type": "tokenization",
  "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "settings": {
    "tokenization": {
      "type": "store",
      "allowedCardTypes": ["credit", "debit"],
      "features": ["create", "list", "select", "delete"]
    },
    "callbacks": {
      "tokenizationCallbackUrl": "https://merchant.example.com/callbacks/tokenization"
    }
  }
}
```

After the hosted flow completes, read the customer's instruments and persist the token reference in your subscription system.

### 3. Charge the saved instrument

```http
POST /v1/payments
Authorization: Basic {credentials}
Content-Type: application/json

{
  "merchantId": 12345,
  "referenceId": "subscription-charge-2026-03",
  "invoiceNumber": "SUB-2026-03-1001",
  "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "amount": {
    "total": 10000,
    "currency": "UYU"
  },
  "paymentMethod": {
    "source": "token",
    "paymentInstrument": {
      "token": "9b7f1c2e-4a3d-4e8b-9c1f-2d3e4f5a6b7c"
    }
  },
  "capture": {
    "method": "automatic"
  },
  "metadata": {
    "subscriptionId": "sub-1001",
    "billingCycle": "2026-03"
  }
}
```

## Alternative: Save the Card During the First Charge

If the first order should charge the card and store it for future renewals, create the payment with `paymentMethod.card.tokenizationSettings` and a `customerId`. After the payment succeeds, read the customer's instruments to get the reusable token.

## Failure Handling

Recurring billing logic lives in your system, so plan for asynchronous failures and retries.

* Use unique `referenceId` and `invoiceNumber` values for every billing attempt
* Store the payment `id` and final `status` from each cycle
* Retry according to your own billing rules, not by reusing the same payment record
* If a token stops working, send the customer back through a tokenization session to replace it

## Updating the Payment Method

The supported public replacement flow is:

1. Create a new tokenization session for the customer
2. Read the new token from `GET /v1/customers/{customerId}/payment-instruments`
3. Update your subscription record to use the new token
4. Optionally delete the old token with `DELETE /v1/customers/{customerId}/payment-instruments/{tokenId}`

## Best Practices

* Store the Plexo `customerId` and instrument token alongside your subscription record
* Keep recurring retries idempotent in your own scheduler
* Prefer hosted tokenization over collecting card data on your server
* Use `metadata` to store subscription identifiers for reconciliation
* Re-query the customer instruments list before assuming a token is still active

## Related Resources

* [Tokenization Guide](/rest-api/customers-and-saved-methods/tokenization-guide.md)
* [Customer Management](/rest-api/customers-and-saved-methods/customer-management.md)
* [Payment Processing](/rest-api/payments/payment-processing.md)