Idempotency

Creating a charge is not an idempotent operation by nature: two calls with the same body create two distinct resources. So that you can retry without duplicating and reconcile your operations against those of TapiPay, the API follows the header-based idempotency pattern (the same approach as Stripe).

How it works

Send the Idempotency-Key header in your creation requests. It is optional, and your body stays clean: control information is not mixed with the resource data.

curl --request POST \
  --url 'https://tapipay-facade.homo.tapila.cloud/v2/debts' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-authorization-token: YOUR_TAPI_TOKEN' \
  --header 'Idempotency-Key: INV-2026-001' \
  --header 'Content-Type: application/json' \
  --data '{ "externalClientId": "CLI-00042", "amount": 1500.00, "dueDate": "2026-07-01" }'

The response always includes the externalRequestId field, whether or not you sent the key:

If you sent Idempotency-Key: externalRequestId is exactly the value you sent.
If you did not send it: the backend generates an externalRequestId (a UUID) and returns it to you, so that you can use it in future queries and reconciliation.

In both cases the debtId is debt_ + externalRequestId.

{
  "data": {
    "debtId": "debt_INV-2026-001",
    "externalRequestId": "INV-2026-001",
    "status": "PENDING"
  },
  "requestId": "req_a1b2c3d4"
}

{
  "data": {
    "debtId": "debt_9f1c2e7a-4b21-4d8e-9c3a-1f7b2e9d4c5a",
    "externalRequestId": "9f1c2e7a-4b21-4d8e-9c3a-1f7b2e9d4c5a",
    "status": "PENDING"
  },
  "requestId": "req_a1b2c3d4"
}

Permanent deduplication

The externalRequestId is a permanent unique key within your organization: there is a uniqueness constraint with no expiration (no TTL or time window).

Retrying with an already-used Idempotency-Key does not return the original resource: it returns a 409 RESOURCE_CONFLICT error. The resource is not duplicated and you receive an explicit signal that the key was already taken.

409 RESOURCE_CONFLICT

{
  "error": {
    "code": "RESOURCE_CONFLICT",
    "message": "externalRequestId already exists"
  },
  "requestId": "req_3f8a1c9e2b"
}

This is why the key must be unique per operation intent: use a distinct key for each charge you want to create, and reuse the same one only when you are retrying exactly the same operation after a timeout or a network error.

Dual function: idempotency and reconciliation

The externalRequestId serves two roles at once:

Protects against duplicates when you retry a request that failed or expired.

Reconciliation

It is the external key of the debt. You can filter and list by it: GET /debts?externalRequestId=....

Where each key applies

Each creation resource has its own external key.

Resource	External key	Where it is sent
Debt (`POST /v2/debts`, single debt)	`externalRequestId`	`Idempotency-Key` header (optional)
Debt (`POST /v2/debts`, batch mode)	`externalRequestId`	Body, in each item of `debts` (required). The header does not apply.
Subscription	`externalSubscriptionId`	Request body (required). It does not use the header.
Payment link	`externalPaymentLinkId`	Request body or `Idempotency-Key` header (optional)

Subscriptions

The key of a subscription is externalSubscriptionId, which goes in the body and is unique per organization. Repeating it returns 409 RESOURCE_CONFLICT. POST /subscriptions does not use the Idempotency-Key header. The debts generated by the subscription use externalRequestId = <externalSubscriptionId>-cycle-<n>, with n starting at 0, so you can find the first cycle’s debt with GET /debts?externalRequestId=SUB-2026-007-cycle-0. See Subscriptions.

Payment links

The key of a payment link is externalPaymentLinkId:

If you send it in the body, that value is used and the Idempotency-Key header is ignored.
If you do not send it but you send the Idempotency-Key header, the header value is used as externalPaymentLinkId.
If you send neither, the link has no external key: externalPaymentLinkId is null and each request creates a new link.

Repeating an externalPaymentLinkId returns 409 RESOURCE_CONFLICT and no debt is created. See Payment links.

Idempotency applies per organization. The same key in two distinct organizations does not interfere with each other.

Get started

What's new

Concepts

Resources

Payment portal

Webhooks

Idempotency

How it works

Permanent deduplication

Dual function: idempotency and reconciliation

Idempotency

Reconciliation

Where each key applies

Subscriptions

Payment links

​How it works

​Permanent deduplication

​Dual function: idempotency and reconciliation

Idempotency

Reconciliation

​Where each key applies

​Subscriptions

​Payment links

How it works

Permanent deduplication

Dual function: idempotency and reconciliation

Where each key applies

Subscriptions

Payment links