Idempotency

Implementing Idempotent Requests

When initiating a Create Payment request, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of sending a second payment. It's unnecessary to use them with GET and DELETE operations, as these are inherently idempotent, and including an idempotency key will have no impact.

Implementing Idempotent Requests

To leverage idempotency, include X-Idempotency-Key in your request headers for a Create Payment request. Walapay's backend system stores the response of a successful request linked to a unique idempotency key. Any further attempts using the same idempotency key will yield the identical response.

Example Response if Key Has Already Been Used:

{
  "message": "Idempotency key already exists; below are the details of the payment that was already created.",
  "id": "cm0ecdme600049z7f943qflni",
  "status": "PENDING",
  "comment": null,
  "paymentRail": "INSTAPAY",
  "purposeCode": null,
  "sourceAmount": 5,
  "paymentMethod": "BANK",
  "sourceOfFunds": null,
  "destinationAmount": 279.935562200525,
  "sourceCurrencyCode": "USD",
  "destinationCurrencyCode": "PHP",
  "paymentAccountId": "cm0ecdm87000927fian7vnyp"
}

Key Behavior of Idempotency Keys

Idempotency keys are automatically removed from Walapay's system once a payment has successfully been completed (i.e., the account holder has the money in their account). Should a key be reused post-deletion, a new request will be initiated.

The responsibility of generating a unique idempotency key falls to the client. These should be UUIDs.

⚠️

Requests that return errors can be retried using the same idempotency key as no payments are ever created when an error occurs.

See the Payments section in API Core Concepts for examples.