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 Facade 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.dev.tapila.cloud/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 and returns it to you, so that you can use it in future queries and reconciliation.

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

{
  "data": {
    "debtId": "debt_9aL3kP2m",
    "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. Only debts use the header; subscriptions and payment links carry their key in the body.

Resource	External key	Where it is sent
Debt	`externalRequestId`	`Idempotency-Key` header (optional)
Subscription	`externalSubscriptionId`	Request body
Payment link	`externalPaymentLinkId`	Request body (optional)

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

Get started

Concepts

Resources

Payment portal

Webhooks

Idempotency

How it works

Permanent deduplication

Dual function: idempotency and reconciliation

Idempotency

Reconciliation

Where each key applies

​How it works

​Permanent deduplication

​Dual function: idempotency and reconciliation

Idempotency

Reconciliation

​Where each key applies

How it works

Permanent deduplication

Dual function: idempotency and reconciliation

Where each key applies