Idempotent Request
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Finix recommends including an idempotency_id field on specific API resources to ensure that each request is processed only once. This is especially useful in scenarios where a checkout page hangs and users may retry the request.

You can generate a unique ID and include it in your request payload. If the same idempotency_id is submitted again, Finix will return the original response or raise an exception if the new request differs from the first.

Using idempotency_id protects against duplicate authorizations or transfers.

Implementing Idempotent Requests

Follow the steps below to generate, include, and process an idempotency_id in your API requests.

Step 1: Generate a Unique Identifier

You should generate a unique string to use as the idempotency_id. Finix recommends using a UUID (Universally Unique Identifier), a 128-bit value represented as a 36-character string that uniquely identifies information across systems. Each API request should include its own distinct idempotency_id.

Step 2: Include the ID in the Request Body

Pass the generated idempotency_id as part of your request payload.

Sample Request Payload

{
  "amount": 1000,
  "currency": "USD",
  "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm",
  "source": "PI6iQcTtJNCS8GZAVKYi5Ueb",
  "idempotency_id": "7f1b4c82-9e3a-4e5b-93b0-2ad1c6c47a11"
}

Step 3: Finix Processes the Request

The first time the idempotency_id is seen for the given endpoint, the request is processed and the result is stored. If the same idempotency_id is received again with an identical payload, Finix returns the original response.

Example Idempotent Requests

The following examples show how to use idempotency_id in Finix API requests and responses.

Sample IDs are for Demonstration

The idempotency_id values shown in these examples are for demonstration purposes. In your environment, each request must include a new, unique idempotency_id, as API calls with the example IDs will not be valid or testable.

Endpoints Supporting Idempotency

Endpoint	Description
`POST /transfers`	Create a new transfer.
`POST /authorizations`	Create a new authorization.
`POST /transfers/{id}/reversals`	Create a reversal for a specific transfer.

Online Sale

Include an idempotency_id when creating an online sale.

Example Transfer Request

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/transfers \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "amount": 1000000,
    "currency": "USD",
    "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm",
    "source": "PI6iQcTtJNCS8GZAVKYi5Ueb",
    "idempotency_id": "0e2e97c0-8b4c-4c52-90c5-c13a3c69f6e0",     <--- sample value
    "tags": {
      "test": "Sale"
    }
  }'

Example Transfer Response

{
  "id": "TRjiQJ5gRfuVtccFmtn2HYuT",
  "created_at": "2025-09-26T16:05:10.85Z",
  "updated_at": "2025-09-26T16:05:10.85Z",
  "additional_buyer_charges": null,
  "additional_healthcare_data": null,
  "additional_purchase_data": null,
  "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
  "amount": 1000000,
  "amount_requested": 1000000,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "currency": "USD",
  "destination": null,
  "externally_funded": "UNKNOWN",
  "failure_code": null,
  "failure_message": null,
  "fee": 0,
  "fee_profile": "FPmtT4MYmiAs1qjLjneQmk4d",
  "idempotency_id": "0e2e97c0-8b4c-4c52-90c5-c13a3c69f6e0",
  "merchant": "MUwfZPNW3r4EqLMzwgr6txw4",
  "merchant_identity": "IDhC29dXMAkbmr1aBpS91Hpx",
  "messages": [],
  "network_details": {
    "brand": "VISA",
    "authorization_code": "840735",
    "acquirer_reference_number": null
  },
  "operation_key": "CARD_NOT_PRESENT_SALE",
  "parent_transfer": null,
  "parent_transfer_trace_id": null,
  "raw": null,
  "ready_to_settle_at": "2025-09-27T16:05:11.42Z",
  "receipt_last_printed_at": null,
  "security_code_verification": "MATCHED",
  "source": "PI6iQcTtJNCS8GZAVKYi5Ueb",
  "split_transfers": [],
  "state": "SUCCEEDED",
  "statement_descriptor": "FLX*FINIX FLOWERS",
  "subtype": "API",
  "supplemental_fee": null,
  "tags": {
    "test": "Sale"
  },
  "tip_amount": null,
  "trace_id": "a6c5835b-d855-4961-8070-caeaa8e89cbb",
  "type": "DEBIT",
  "_links": {
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "self": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRjiQJ5gRfuVtccFmtn2HYuT"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDhC29dXMAkbmr1aBpS91Hpx"
    },
    "payment_instruments": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRjiQJ5gRfuVtccFmtn2HYuT/payment_instruments"
    },
    "reversals": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRjiQJ5gRfuVtccFmtn2HYuT/reversals"
    },
    "fees": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRjiQJ5gRfuVtccFmtn2HYuT/fees"
    },
    "disputes": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRjiQJ5gRfuVtccFmtn2HYuT/disputes"
    },
    "source": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6iQcTtJNCS8GZAVKYi5Ueb"
    },
    "fee_profile": {
      "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d"
    }
  }
}

In-Person Sale

Include an idempotency_id when creating an in-person sale.

Example Transfer Request

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/transfers \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "amount": 1500,
    "currency": "USD",
    "device": "DVhXqP9onzhA7sxheKXoBc3J",
    "idempotency_id": "7f1b4c82-9e3a-4e5b-93b0-2ad1c6c47a11",     <--- sample value
    "operation_key": "CARD_PRESENT_SALE"
  }'

Example Transfer Response

{
  "id": "TRuuwYpzXQsxNRY77CVvcJJp",
  "created_at": "2025-07-25T18:19:28.11Z",
  "updated_at": "2025-07-25T18:19:28.11Z",
  "additional_buyer_charges": null,
  "additional_healthcare_data": null,
  "additional_purchase_data": null,
  "address_verification": null,
  "amount": 1500,
  "amount_requested": 1500,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "card_present_details": {
    "emv_data": {
      "application_identifier": null,
      "application_label": null,
      "application_preferred_name": null,
      "application_transaction_counter": null,
      "cryptogram": null,
      "issuer_code_table_index": null,
      "network_emv_response": null,
      "pin_verified": false,
      "tags": null
    },
    "masked_account_number": null,
    "name": null,
    "brand": null,
    "entry_mode": "UNKNOWN",
    "payment_type": null,
    "approval_code": null,
    "digital_signature_file_id": null
  },
  "currency": "USD",
  "destination": null,
  "device": "DVhXqP9onzhA7sxheKXoBc3J",
  "externally_funded": "UNKNOWN",
  "failure_code": "DEVICE_UNREACHABLE",
  "failure_message": "The API request could not communicate with the device. Please try again.",
  "fee": 0,
  "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj",
  "idempotency_id": "7f1b4c82-9e3a-4e5b-93b0-2ad1c6c47a11",
  "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm",
  "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H",
  "messages": [
    "RAW MESSAGE"
  ],
  "operation_key": "CARD_PRESENT_SALE",
  "parent_transfer": null,
  "parent_transfer_trace_id": null,
  "raw": null,
  "ready_to_settle_at": null,
  "receipt_last_printed_at": null,
  "security_code_verification": null,
  "source": "PI9hTsZF8ms387bxNv5FmPyU",
  "split_transfers": [],
  "state": "FAILED",
  "statement_descriptor": "FLX*FINIX FLOWERS",
  "subtype": "API",
  "supplemental_fee": null,
  "tags": {},
  "tip_amount": null,
  "trace_id": "70bbc88e-83db-4efe-a4ab-eb54cd6da5fe",
  "type": "DEBIT",
  "_links": {
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "self": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRuuwYpzXQsxNRY77CVvcJJp"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/transfers/ID6UfSm1d4WPiWgLYmbyeo3H"
    },
    "device": {
      "href": "https://finix.sandbox-payments-api.com/devices/DVhXqP9onzhA7sxheKXoBc3J"
    },
    "payment_instruments": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRuuwYpzXQsxNRY77CVvcJJp/payment_instruments"
    },
    "reversals": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRuuwYpzXQsxNRY77CVvcJJp/reversals"
    },
    "fees": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRuuwYpzXQsxNRY77CVvcJJp/fees"
    },
    "disputes": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRuuwYpzXQsxNRY77CVvcJJp/disputes"
    },
    "fee_profile": {
      "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj"
    }
  }
}

Authorization

Include an idempotency_id when creating an authorization.

Example Authorization Request

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/authorizations \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "amount": 12000,
    "currency": "USD",
    "merchant": "MUsVtN9pH65nGw61H7Nv8Apo",
    "source": "PIkxmtueemLD6dN9ZoWGHT44",
    "idempotency_id": "d4a2f1e7-63b8-4c90-8b5e-7b91c2c3e215",     <--- sample value
    "tags": {
      "order_number": "21DFASJSAKAS"
    }
  }'

Example Authorization Response

{
  "id": "AUsJgTPyNKUKbkTk4mzq2aoM",
  "created_at": "2025-10-27T15:55:36.29Z",
  "updated_at": "2025-10-27T15:55:36.29Z",
  "3ds_redirect_url": null,
  "additional_buyer_charges": null,
  "additional_healthcare_data": null,
  "additional_purchase_data": null,
  "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
  "amount": 12000,
  "amount_requested": 12000,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "currency": "USD",
  "expires_at": "2025-11-03T15:55:36.29Z",
  "failure_code": null,
  "failure_message": null,
  "idempotency_id": "d4a2f1e7-63b8-4c90-8b5e-7b91c2c3e215",
  "ip_address_details": null,
  "is_void": false,
  "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm",
  "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H",
  "messages": [],
  "raw": null,
  "receipt_last_printed_at": null,
  "security_code_verification": "MATCHED",
  "source": "PIkxmtueemLD6dN9ZoWGHT44",
  "state": "SUCCEEDED",
  "supplemental_fee": null,
  "tags": {
    "order_number": "21DFASJSAKAS"
  },
  "trace_id": "0504c0cc-7665-4555-90c3-c460330acf2e",
  "transfer": null,
  "void_state": "UNATTEMPTED",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/authorizations/AUsJgTPyNKUKbkTk4mzq2aoM"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H"
    }
  }
}

Refund

Include an idempotency_id when creating a reversal transfer.

Example Refund Request

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/transfers/TRnErBfrHLgdAi3BqAkWLN27/reversals \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "refund_amount": 1000000,
    "idempotency_id": "3f9c8a41-b0e7-4e27-9f6c-0d2f3a9e52b8",     <--- sample value
    "tags": {
      "test": "Refund"
    }
  }'

Example Refund Response

{
  "id": "TRi87Kgx6NdZFXkQtLXQ9NMJ",
  "created_at": "2025-08-05T17:22:50.40Z",
  "updated_at": "2025-08-05T17:22:50.44Z",
  "additional_buyer_charges": null,
  "additional_healthcare_data": null,
  "additional_purchase_data": null,
  "address_verification": null,
  "amount": 1000000,
  "amount_requested": 1000000,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "currency": "USD",
  "destination": "PImXAVgkKVshKWWHUk4xXbve",
  "externally_funded": "UNKNOWN",
  "failure_code": null,
  "failure_message": null,
  "fee": 0,
  "fee_profile": "FPmtT4MYmiAs1qjLjneQmk4d",
  "idempotency_id": "3f9c8a41-b0e7-4e27-9f6c-0d2f3a9e52b8",
  "merchant": "MUcgYZswyRfqSSbvMsxuaHxZ",
  "merchant_identity": "IDgCoio3FfaMSKPNM35atXPU",
  "messages": [],
  "operation_key": "CARD_NOT_PRESENT_REFUND",
  "parent_transfer": "TRjAnCNNSxDCW8GDsxYobHHe",
  "parent_transfer_trace_id": null,
  "raw": null,
  "ready_to_settle_at": null,
  "receipt_last_printed_at": null,
  "security_code_verification": null,
  "source": null,
  "split_transfers": [],
  "state": "PENDING",
  "statement_descriptor": "FLX*FINIX FLOWERS",
  "subtype": "API",
  "supplemental_fee": null,
  "tags": {
    "test": "Refund"
  },
  "tip_amount": null,
  "trace_id": "d1cb23da-3368-473d-bf8e-68d8e093839b",
  "type": "REVERSAL",
  "_links": {
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "self": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRi87Kgx6NdZFXkQtLXQ9NMJ"
    },
    "parent": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRjAnCNNSxDCW8GDsxYobHHe"
    },
    "destination": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImXAVgkKVshKWWHUk4xXbve"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDgCoio3FfaMSKPNM35atXPU"
    },
    "payment_instruments": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRi87Kgx6NdZFXkQtLXQ9NMJ/payment_instruments"
    },
    "fee_profile": {
      "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d"
    }
  }
}

Idempotent RequestCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude