Prevent Duplicate Requests

Payabli’s idempotencyKey header parameter lets you give your POST requests a unique identifier so you can safely retry a request that timed out without worrying about creating duplicate objects or transactions. Using them is optional, but is a best practice to avoid creating duplicate transactions.

The idempotency key is something that you must generate and include as a header parameter in POST requests. Payabli recommends using a UUID for your tokens.

​

Considerations

When using idempotency keys, keep these considerations in mind.

• Payabli retains the idempotency key for 1 minute. After 1 minute, you can reuse the key if needed.
• If a transaction is declined because of a bad payment method, you can’t correct the payment information and retry the transaction with the same idempotency key value, it fails with a 409 Conflict error.

​

Usage example

When using an idempotency key, your request header looks something like this:

curl --request POST \
     --url https://api.payabli.com/api/MoneyIn/getpaid \
     --header "accept: application/json" \
     --header "content-type: application/*+json" \
     --header "idempotencyKey: dc125696-0c78-11ee-be56-0242ac120002" \
     --header "requestToken: <API TOKEN>"

​

409 Conflict

If you send an idempotencyKey more than once before it expires, you get a 409 Conflict response:

HTTP Response: 409 Conflict
Duplicated idempotencyKey: 12345

If you get this error when running a payment transaction, you can query a list of transactions to pull in any information about a transaction that was approved but timed out.

​

Best practices for avoiding duplicate transactions

Payabli recommends using webhooks to help avoid duplicate transactions. All of the Money In webhooks are helpful, but the ApprovedTransaction notification is particularly useful.

One of the main reasons you might double-charge a card is if you tried to process the payment and received a timeout error response. In that case, you don’t know if the original transaction was received, processed, or approved, and the standard course of action is to resubmit the transaction request.

If you have webhooks configured, you will get a copy of the approval or decline response. You can use the response sent via webhook instead of the standard response you should have received but didn’t because the request timed out.