Skip to content
CatholicPayDevelopers

Idempotency

Every request that creates something or moves money takes an Idempotency-Key header, and it is required: such a request without one is refused with 400 VALIDATION_ERROR. The API reference lists the header on each endpoint that takes it. Requests that are safe to repeat as they are (closing an account number, updating or deleting a customer, the sandbox simulations) do not take one.

Idempotency-Key: 5f0c8a2e-6f4b-4d1a-9a59-2f1f7b0f8d31
  • Use a new key, 1 to 100 characters, for each new operation. A UUID is best.
  • The same key with the same request returns the first response, without doing anything again. So when a request times out or the connection drops, retry it with the same key: it cannot pay twice.
  • The same key with a different request is refused: 409 IDEMPOTENCY_KEY_REUSED.
  • While the first request is still running, a retry gets 409 IDEMPOTENCY_KEY_IN_USE: wait a moment and retry.

References

Section titled “References”

Many objects also take your own reference: reference on account numbers, checkouts, mandates and withdrawals, transaction_ref on wallet charges and payment requests. A reference is unique in your organisation: creating with a used reference returns the existing object (200), or 409 REFERENCE_USED if the details differ. Use your own invoice or order number, so you can always find the payment again with verify.