Skip to content

Refunding with the API

You can refund transactions processed with Finix programmatically using the Finix API instead of a user interface. The API supports refunds for both online and in-person payments.

Refunding online Payments

To refund a Transfer via API, create a reversal Transfer. Pass the id query parameter set to the original Transfer you want to refund.

Include an amount equal to or less than the payment to refund. Enter a value less than the payment amount for a partial refund.

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": 1000
  }'

A successful request returns a 201 Created status code, with the response body containing:

  • parent_transfer representing the Transfer that was reversed.
  • state - Initially set to PENDING to indicate that the refund is still processing.
    • Changes to SUCCEEDED when the refund is processed.
  • type set to REVERSAL.
Transfer - Reversal
{
  "id": "TRhop5SzZD5AbRGz6HC6qB5w",
  "created_at": "2026-09-25T20:36:25.76Z",
  "updated_at": "2026-09-25T20:36:25.79Z",
  "3d_secure_session": null,
  "additional_buyer_charges": null,
  "additional_healthcare_data": null,
  "additional_lodging_data": null,
  "additional_motor_vehicle_rental_data": null,
  "additional_purchase_data": null,
  "address_verification": null,
  "amount": 1000,
  "amount_requested": 1000,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "created_via": "UNKNOWN",
  "currency": "USD",
  "destination": "PI6iQcTtJNCS8GZAVKYi5Ueb",
  "expires_at": "2026-11-09T20:36:25.76Z", 
  "externally_funded": "UNKNOWN",
  "failure_code": null,
  "failure_message": null,
  "fee": 0,
  "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj",
  "idempotency_id": null,
  "ip_address_details": null,
  "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm",
  "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H",
  "messages": [],
  "network_details": null,
  "operation_key": "CARD_NOT_PRESENT_REFUND",
  "parent_transfer": "TRqvNLUdn3aPmdwLMSKs3Gxz", 
  "parent_transfer_trace_id": null,
  "processed_at": 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": {},
  "third_party_details": null,
  "tip_amount": null,
  "trace_id": "9fc0c015-0d97-49f1-93a6-b845d4e50c01",
  "type": "REVERSAL", 
  "_links": {
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "self": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRhop5SzZD5AbRGz6HC6qB5w"
    },
    "parent": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRqvNLUdn3aPmdwLMSKs3Gxz"
    },
    "destination": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6iQcTtJNCS8GZAVKYi5Ueb"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H"
    },
    "payment_instruments": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRhop5SzZD5AbRGz6HC6qB5w/payment_instruments"
    },
    "fee_profile": {
      "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj"
    }
  }
}

The state will be SUCCEEDED when the refund finishes processing. Buyers will see the refund credited within 5-10 business days, depending on their bank. Refunds can't be canceled once processed.

Held Refunds

When refund holds are enabled, refunds stay in state: PENDING until the merchant's settlement balance covers them, and the response includes an expires_at date. A refund that cannot be covered in time fails with failure_code: REFUND_EXPIRED. For more information, see Pending refunds.

Refunding Card-Present Payments

Which refund method to use for card-present payments depends on how much time has passed since the original transaction. For debit transactions, the determining factor is whether the batch is still open; for credit transactions, whether it's within 45 days.

  • Referenced Refunds — Reverse the original Transfer directly using its ID. No card swipe required in most cases.
  • Unreferenced Refunds — Create a new Transfer unlinked from the original. The cardholder must swipe their card to authorize the refund. Only available for physically swiped transactions.

Referenced Refunds

Use a referenced refund when:

  • The payment type was credit and the transaction is within 45 days (regardless of batch status).
  • The payment type was debit and the transaction is in the current open batch.

To perform the refund, reverse the original Transfer:

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 '{
    "device": "DVhCtTEMVHnDPFMh2KQLrFSi",
    "refund_amount": 150
  }'

A successful request returns a 201 Created status code, with the response body containing:

  • state - Initially set to PENDING to indicate that the refund is still processing.
    • Changes to SUCCEEDED when the refund is processed.
  • type is set to REVERSAL.
  • Under _links.parent, you can find the original Transfer that was reversed.
Reversed Card-Present Transfer Referencing Parent
{
  "id": "TR7PYuTpCU3AtLSgvSobjmGg",
  "created_at": "2026-09-28T20:31:08.64Z",
  "updated_at": "2026-09-28T20:31:08.69Z",
  "3d_secure_session": null,
  "additional_buyer_charges": null,
  "additional_healthcare_data": null,
  "additional_lodging_data": null,
  "additional_motor_vehicle_rental_data": null,
  "additional_purchase_data": null,
  "address_verification": null,
  "amount": 150,
  "amount_requested": 150,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "created_via": "UNKNOWN",
  "currency": "USD",
  "destination": "PI2zjrcxkiPYEokwQPq2G58z",
  "device": "DVhCtTEMVHnDPFMh2KQLrFSi",
  "expires_at": "2026-11-12T20:31:08.64Z",
  "externally_funded": "UNKNOWN",
  "failure_code": null,
  "failure_message": null,
  "fee": 0,
  "fee_profile": "FPmtT4MYmiAs1qjLjneQmk4d",
  "idempotency_id": null,
  "ip_address_details": null,
  "merchant": "MUmFY9PWbqJPGtQEN7RXdFAb",
  "merchant_identity": "IDvEVPqD9rnfLCAGnLJphyGT",
  "messages": [],
  "network_details": null,
  "operation_key": "CARD_PRESENT_REFUND",
  "parent_transfer": "TRhBbRpGifWm9U8fCaKVVAZo",
  "parent_transfer_trace_id": null,
  "processed_at": 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": {},
  "third_party_details": null,
  "tip_amount": null,
  "trace_id": "253a57c6-a449-427c-9732-33655040b819",
  "type": "REVERSAL", 
  "_links": {
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "self": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TR7PYuTpCU3AtLSgvSobjmGg"
    },
    "parent": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRhBbRpGifWm9U8fCaKVVAZo"
    },
    "destination": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI2zjrcxkiPYEokwQPq2G58z"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDvEVPqD9rnfLCAGnLJphyGT"
    },
    "payment_instruments": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TR7PYuTpCU3AtLSgvSobjmGg/payment_instruments"
    },
    "fee_profile": {
      "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d"
    }
  }
}

Unreferenced Refunds

Use an unreferenced refund when:

  • The payment type is debit and the transaction is no longer in the batch.
  • The payment type is credit and the transaction is no longer in the batch and older than 45 days.

To perform the unreferenced refund, create a Transfer with operation_key: CARD_PRESENT_UNREFERENCED_REFUND. The cardholder must swipe their card to authorize the refund.

Card-not-present transactions (e.g., eCommerce) do not support unreferenced refunds.

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": 150,
    "currency": "USD",
    "device": "DVcazsRGCXuRgxYAqwkbvvci",
    "operation_key": "CARD_PRESENT_UNREFERENCED_REFUND"
  }'

A successful request returns a 201 Created status code, with the response body containing:

  • operation_key is set to CARD_PRESENT_UNREFERENCED_REFUND.
  • state - Initially set to PENDING to indicate that the refund is still processing.
    • Changes to SUCCEEDED when the refund is processed.
  • type is set to CREDIT or DEBIT based on the original transfer type, rather than REVERSAL.

Unlike referenced refunds, there is no _links.parent property — a new Transfer was created instead of reversing an existing one.

Card Present Transfer without Parent Reference
{
  "id": "TRo5JpCqMY26ufvRdTJ8715j",
  "created_at": "2025-11-19T20:31:16.48Z",
  "updated_at": "2025-11-19T20:31:16.48Z",
  "additional_buyer_charges": null,
  "additional_healthcare_data": null,
  "additional_purchase_data": null,
  "address_verification": null,
  "amount": 150,
  "amount_requested": 150,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "card_present_details": {
    "emv_data": {
      "application_identifier": "A0000000041010",
      "application_label": "Mastercard Debit",
      "application_preferred_name": null,
      "application_transaction_counter": "01D2",
      "cryptogram": "ARQC 579B6893AADF6245",
      "issuer_code_table_index": null,
      "network_emv_response": null,
      "pin_verified": false,
      "tags": null
    },
    "masked_account_number": "523499******4130",
    "name": null,
    "brand": "UNKNOWN",
    "entry_mode": "CONTACTLESS",
    "payment_type": "CREDIT",
    "approval_code": "674313",
    "digital_signature_file_id": null
  },
  "currency": "USD",
  "destination": "PInqirmUHFh1FmPNa8reirAb",
  "device": "DVoDo7F6yYCnX2d6Fj9hvsd",
  "externally_funded": "UNKNOWN",
  "failure_code": null,
  "failure_message": null,
  "fee": 0,
  "fee_profile": "FPmtT4MYmiAs1qjLjneQmk4d",
  "idempotency_id": null,
  "ip_address_details": null,
  "merchant": "MUsMvN47nRtdgUkE23SRHDC6",
  "merchant_identity": "IDgu8uaRpVnfSEcRcZFXqpjK",
  "messages": [],
  "network_details": null,
  "operation_key": "CARD_PRESENT_UNREFERENCED_REFUND", 
  "parent_transfer": null,
  "parent_transfer_trace_id": null,
  "raw": null,
  "ready_to_settle_at": "2025-11-20T20:32:38.76Z",
  "receipt_last_printed_at": null,
  "security_code_verification": null,
  "source": null,
  "split_transfers": [],
  "state": "SUCCEEDED", 
  "statement_descriptor": "FLX*FINIX FLOWERS",
  "subtype": "API",
  "supplemental_fee": null,
  "tags": {},
  "third_party_details": null,
  "tip_amount": null,
  "trace_id": "23f1fdf9-2783-4bbe-8de2-afd7a7502aad",
  "type": "CREDIT", 
  "_links": {
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "self": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRo5JpCqMY26ufvRdTJ8715j"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDgu8uaRpVnfSEcRcZFXqpjK"
    },
    "device": {
      "href": "https://finix.sandbox-payments-api.com/devices/DVoDo7F6yYCnX2d6Fj9hvsd"
    },
    "payment_instruments": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRo5JpCqMY26ufvRdTJ8715j/payment_instruments"
    },
    "reversals": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRo5JpCqMY26ufvRdTJ8715j/reversals"
    },
    "fees": {
      "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRo5JpCqMY26ufvRdTJ8715j"
    },
    "disputes": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TRo5JpCqMY26ufvRdTJ8715j/disputes"
    },
    "destination": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PInqirmUHFh1FmPNa8reirAb"
    },
    "fee_profile": {
      "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d"
    }
  }
}