# Idempotent Request

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.


```json 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.


```shell 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"
    }
  }'
```


```json 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.


```shell 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"
  }'
```


```json 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.


```shell 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"
    }
  }'
```


```json 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.


```shell 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"
    }
  }'
```


```json 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"
    }
  }
}
```