Skip to main content

Idempotency

Introduction​

Idempotency is a concept that means performing an action multiple times has the same effect as performing it once. In other words, no matter how many times the operation is repeated, the outcome remains unchanged after the first execution.

It is crucial for building reliable and robust systems, especially in distributed environments where requests might be retried automatically due to timeouts or failures.

Moyasar provides a simple solution that you can adapt to ensure your payment creation requests are idempotent. Therefore, in the case of network issues, you can safely retry creating payments without the risk of duplicate charges to your customers.

Common Scenario - No Idempotency​

In the case where idempotency is not supported, suppose you are sending the following payment creation request:

{
"amount": 100,
"callback_url": "http://payments.local",
"description": "card",
"source": {
"type": "creditcard",
"number": "4111111111111111",
"name": "John Doe",
"cvc": "113",
"month": "3",
"year": "2035"
}
}

You should receive either:

  • a 201 response to indicate that the payment has been processed (either initiated, failed, or paid)
  • a 4xx response to indicate a client-side error.
  • a 5xx response to indicate that something somewhere went wrong.

The first two responses convey what happened to the payment request. You can decide what to do next.

However, the third one doesn't exactly tell what happened. There are multiple scenarios associated with the payment:

  • Processed: The amount has been deducted from the customer. If you retry again, the customer will be double charged.
  • Not Processed: The amount has not been deducted from the customer. If you retry again, the customer will not "feel" the service disturbance.

Overall, you will never know the conclusion in a timely manner to decide what to do next.

Common Scenario - With Idempotency​

Moyasar supports payment creation idempotency by allowing you to provide a given_id key with a value of a uuid (v4 is recommended) in the payment creation request. You will need to generate it from your side.

Request

{
"given_id": "a1168bd1-47a4-4b97-8a50-dd5caaccacf2",
"amount": 100,
"callback_url": "http://payments.local",
"description": "card",
"source": {
"type": "creditcard",
"number": "4111111111111111",
"name": "John Doe",
"cvc": "113",
"month": "3",
"year": "2035"
}
}

Response

{
"id": "a1168bd1-47a4-4b97-8a50-dd5caaccacf2",
"status": "initiated",
"amount": 100,
...
"source": {
...
}
}

The ID of the created payment will be the same one you have provided in the given_id.

This simple yet powerful feature enables you to safely retry creating the payment for multiple times if you get a 5xx response.

  • If the payment is already processed by the first request, you will get the same successful response you should have gotten before.
  • If the payment wasn't processed yet, it will be processed as if it has been received for the first time.

Therefore, your customers are shielded from any potential networks issues - No duplicate charges with multiple retries.

info

If you ever send the same given_id value for different payments, you will receive a 400 response with the error type used_given_id.

When To Retry Payment Creation​

You should retry creating the payment in the following cases:

  • When you receive a 5xx response when creating a new payment.
  • When you have a network error.
  • When you get a timeout error (open, read, or write).

Payout Idempotency​

Payout creation supports the same given_id key. Use it to safely retry sending money without paying the same beneficiary twice.

Endpoint: POST /v1/payouts

Authentication: Secret key

POST /v1/payouts
{
"given_id": "b5a1c3e2-7f4d-4c1a-9e8b-2d6f0a9c4e11",
"source_id": "ceb461ea-3f35-4027-b20a-beb89f5ee574",
"amount": 100,
"purpose": "personal",
"destination": {
"type": "wallet",
"mobile": "0555555555"
}
}

The ID of the created payout will be the given_id you provided.

  • If you retry with the same given_id, the same payout account, and the same amount, currency, and destination (type, mobile, and iban), you get the existing payout back. No new payout is created or sent.
  • If you send a given_id that was already used for a payout with different details, you receive a 400 response with the error type used_given_id.
tip

Generate one given_id for each payout you intend to send, for example one per order, and store it before sending the request. Reuse it for every retry of that payout. A new given_id means a new payout.

Bulk Payouts​

POST /v1/payouts/bulk accepts a given_id on each payout in the payouts array. Each given_id must be unique within the request.

  • If every payout in a retried request has a given_id that matches an existing payout, you get the existing payouts back. Nothing new is created.
  • If only some of the given_id values were used before, or one of them was used with different details, the whole request is rejected with a 400 response and the error type used_given_id. No payouts are created.

When To Retry Payout Creation​

You should retry creating the payout, with the same given_id, in the following cases:

  • When you receive a 5xx response when creating a new payout.
  • When you have a network error.
  • When you get a timeout error (open, read, or write).

A payout that was created successfully but is still initiated is being processed. Don't create a new payout for it; wait for it to reach a final status.