Sign in
Transfers

Refund or Reverse a Transfer

Reverse a transfer with a type of DEBIT. This reversal creates a new Transfer resource with a type of REVERSAL.

Related Guides: Refunding Payments

post/transfers/{transfer_id}/reversals

Headers

Finix-Versionstring
Example:2022-02-01

Specify the API version of your request. For more details, see Versioning.

Content-Typestring
Example:application/json

The data type being sent in the request body must be application/json.

Request body

OR
OR

Response

The Transfer was successfully reversed.

idstring

The ID of the resource.

created_atstring date-time

Timestamp of when the object was created.

updated_atstring date-time

Timestamp of when the object was last updated.

address_verification'POSTAL_CODE_AND_STREET_MATCH' | 'STREET_MATCH' | 'POSTAL_CODE_MATCH' | 'NO_ADDRESS' | 'NO_MATCH' | 'NOT_SUPPORTED' | 'UNKNOWN' nullable

Details the results of the address verification checks.

amountinteger

The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).

amount_requestedinteger

The amount that was requested to get debited from the source when the transaction was created, in cents (e.g., 100 = $1.00).

applicationstring

ID of the Application associated with the resource.

currency'CAD' | 'USD'

ISO 4217 3-letter currency code.

created_via'CARD_PRESENT_SEMI_INTEGRATED_API' | 'CARD_PRESENT_STANDALONE' | 'CARD_PRESENT_STANDALONE_MANUAL_ENTRY' | 'CARD_PRESENT_IOS_APP' | 'CARD_PRESENT_IOS_APP_MANUAL_ENTRY' | 'CARD_PRESENT_IOS_D135_SDK' | 'CARD_PRESENT_ANDROID_APP' | 'CARD_PRESENT_ANDROID_APP_MANUAL_ENTRY' | 'CARD_PRESENT_ANDROID_D135_SDK' | 'CHECKOUT_FORM' | 'CYBERSOURCE' | 'PAYMENT_LINK' | 'PAYOUT_LINK' | 'PLUGIN_CHECKOUT_CHAMP' | 'PLUGIN_FYNTEK' | 'PLUGIN_GAMBLE_ID' | 'PLUGIN_GAMMA_SWEEP' | 'PLUGIN_HYPERSWITCH' | 'PLUGIN_PAYSIGHT' | 'PLUGIN_STICKYIO' | 'PLUGIN_TAGADA' | 'PLUGIN_WOO_COMMERCE' | 'SUBSCRIPTION' | 'UNKNOWN' | 'VIRTUAL_TERMINAL'

Gives more information about the product flow that was used to create the resource. Finix retains the right to add additional enums for this field without it being a breaking change.

destinationstring nullable

ID of the Payment Instrument where funds will be sent.

devicestring

The ID of the Device resource the Transfer was created under.

externally_fundedstring

Details if the Transfer will be settled externally by card processors.

failure_codestring nullable

The code of the failure so the decline can be handled programmatically. For more info on how to handle the failure, see Failure Codes.

failure_messagestring nullable

A human-readable description of why the transaction was declined. This will also include a suggestion on how to complete the payment.

feeinteger

The minimum amount of the Transfer you'd like to collect as your fee in cents. Defaults to zero (must be less than or equal to the amount).

  • If the fees applied by the 'Fee Profile' are higher than the value passed in 'fee', 'fee' will not be applied and have no effect.
  • If the fees applied by the 'Fee Profile' are lower than the value passed in 'fee', an additional fee is be applied, in addition to the fees generated by the Fee Profile.
    • The additional fee is equal to the difference between the value passed in 'fee' and the fees generated by the Fee Profile.
fee_profilestring

The ID of the Fee Profile that will be used for calculating fees for this transfer.

funds_flow_type'GENERAL_PAYOUT' | 'ME_TO_ME' | 'GOVERNMENT' nullable

The type of disbursement to perform. Defaults to GENERAL_PAYOUT.

idempotency_idstring nullable

Pass any randomly generated or internal ID to idempotently identify Transfers, Authorizations, or refund requests.

ip_address_detailsobject nullable

Always returns null.

merchantstring

The ID of the Merchant resource the Transfer was created under.

merchant_identitystring

The ID of Identity resource used by the Merchant the Transfer was created under.

messagesstring[] nullable

A list of messages that provides additional details.

operation_key'CARD_NOT_PRESENT_CAPTURE' | 'CARD_NOT_PRESENT_REFUND' | 'CARD_NOT_PRESENT_SALE' | 'CARD_NOT_PRESENT_UNREFERENCED_REFUND' | 'CARD_PRESENT_AUTHORIZATION' | 'CARD_PRESENT_DEBIT' | 'CARD_PRESENT_SALE' | 'CARD_PRESENT_UNREFERENCED_REFUND' | 'INSTANT_APPLICATION_FUNDING_PULL_FROM_ACH' | 'INSTANT_APPLICATION_FUNDING_PULL_FROM_CARD' | 'INSTANT_APPLICATION_FUNDING_PULL_FROM_FED_NOW' | 'INSTANT_APPLICATION_FUNDING_PULL_FROM_SAME_DAY_ACH' | 'INSTANT_APPLICATION_FUNDING_PUSH_TO_ACH' | 'INSTANT_APPLICATION_FUNDING_PUSH_TO_CARD' | 'INSTANT_APPLICATION_FUNDING_PUSH_TO_FED_NOW' | 'INSTANT_APPLICATION_FUNDING_PUSH_TO_SAME_DAY_ACH' | 'INSTANT_MERCHANT_FUNDING_PULL_FROM_ACH' | 'INSTANT_MERCHANT_FUNDING_PULL_FROM_FED_NOW' | 'INSTANT_MERCHANT_FUNDING_PULL_FROM_SAME_DAY_ACH' | 'INSTANT_MERCHANT_FUNDING_PUSH_TO_ACH' | 'INSTANT_MERCHANT_FUNDING_PUSH_TO_CARD' | 'INSTANT_MERCHANT_FUNDING_PUSH_TO_FED_NOW' | 'INSTANT_MERCHANT_FUNDING_PUSH_TO_SAME_DAY_ACH' | 'MERCHANT_CREDIT_ADJUSTMENT' | 'MERCHANT_DEBIT_ADJUSTMENT' | 'PULL_FROM_CARD' | 'PUSH_TO_CARD' | 'SALE' | 'STANDARD_APPLICATION_FUNDING_PULL_FROM_ACH' | 'STANDARD_APPLICATION_FUNDING_PULL_FROM_CARD' | 'STANDARD_APPLICATION_FUNDING_PULL_FROM_SAME_DAY_ACH' | 'STANDARD_APPLICATION_FUNDING_PUSH_TO_ACH' | 'STANDARD_APPLICATION_FUNDING_PUSH_TO_CARD' | 'STANDARD_APPLICATION_FUNDING_PUSH_TO_SAME_DAY_ACH' | 'STANDARD_MERCHANT_FUNDING_PULL_FROM_ACH' | 'STANDARD_MERCHANT_FUNDING_PULL_FROM_CARD' | 'STANDARD_MERCHANT_FUNDING_PULL_FROM_SAME_DAY_ACH' | 'STANDARD_MERCHANT_FUNDING_PUSH_TO_ACH' | 'STANDARD_MERCHANT_FUNDING_PUSH_TO_CARD' | 'STANDARD_MERCHANT_FUNDING_PUSH_TO_SAME_DAY_ACH' | 'UNREFERENCED_REFUND' nullable

Details the operation that's performed in the transaction.

parent_transferstring nullable

ID of the original parent Transfer. Only present when type is REVERSAL.

parent_transfer_trace_idstring nullable

The trace_id of the original parent Transfer. Only present when type is REVERSAL.

pull_transfer_idstring nullable

The ID of the corresponding pull Transfer linked in a ME_TO_ME transaction.

ready_to_settle_atstring date-time nullable

The timestamp indicating when the Transfer is ready to be settled.

receipt_last_printed_atstring date-time nullable

Timestamp when the receipt was last printed.

security_code_verification'MATCHED' | 'UNKNOWN' | 'UNMATCHED' nullable

Details the results of the Card Verification Code check.

sourcestring nullable

The ID of the Payment Instrument that will be debited and performing the Transfer.

split_transfersstring[]

Array containing the resource IDs of the Split Transfers generated from the Transfer.

For standard split transactions, this contains IDs of Split Transfers created from the parent Transfer.

For dispute adjustment transfers on split transactions:

  • When a MERCHANT_DEBIT or MERCHANT_CREDIT adjustment Transfer is created for a Dispute on a split transaction, this array contains the IDs of Split Transfers created for each participant.
  • The Split Transfers are created proportionally based on each merchant's share of the original sale.

For more information, see Split Transactions - Disputes.

state'CANCELED' | 'PENDING' | 'FAILED' | 'SUCCEEDED' | 'UNKNOWN' | 'RETURNED'

The status of the Transfer.

statement_descriptorstring nullable

The description of the Merchant that appears on the buyer's bank or card statement.

subtype'API' | 'DISPUTE' | 'MERCHANT_CREDIT' | 'MERCHANT_CREDIT_ADJUSTMENT' | 'MERCHANT_DEBIT' | 'MERCHANT_DEBIT_ADJUSTMENT' | 'PLATFORM_CREDIT' | 'PLATFORM_CREDIT_ADJUSTMENT' | 'PLATFORM_DEBIT' | 'PLATFORM_DEBIT_ADJUSTMENT' | 'SETTLEMENT_MERCHANT' | 'SETTLEMENT_NOOP' | 'SETTLEMENT_PARTNER' | 'SETTLEMENT_PLATFORM' | 'SPLIT_PAYOUT' | 'SPLIT_PAYOUT_ADJUSTMENT' | 'SYSTEM'

Additional information describing the payment_type.

For dispute adjustment transfers (type: DISPUTE):

  • MERCHANT_DEBIT: Funds are pulled from the merchant(s) when a chargeback occurs. For split transactions, this creates Split Transfers with type: DISPUTE_MERCHANT_DEBIT.
  • MERCHANT_CREDIT: Funds are returned to the merchant(s) when a Dispute is ruled in their favor. For split transactions, this creates Split Transfers with type: DISPUTE_MERCHANT_CREDIT.
supplemental_feestring nullable

Amount in cents for which an additional fee will be created in addition to any fees created from the assigned fee profile.

tagsTags nullable

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)
tip_amountinteger nullable

The tip amount included in the total amount.

trace_idstring nullable

Trace ID of the Transfer. The processor sends back the trace_id so you can track the Transfer end-to-end.

type'DEBIT' | 'CREDIT' | 'REVERSAL' | 'ADJUSTMENT' | 'DISPUTE' | 'RESERVE' | 'SETTLEMENT' | 'UNKNOWN'

Type of Transfer.

Example response

{
  "additional_purchase_data": {
    "item_data": [
      {
        "sales_tax_rate": 0.25
      }
    ]
  },
  "amount": 5000,
  "amount_requested": 100,
  "merchant": "MUxxxxxxxxxxxxxxxxxxxxxxx",
  "merchant_identity": "IDxxxxxxxxxxxxxxxxxxxxxxxx",
  "network_details": {
    "brand": "VISA"
  }
}

Changes

Changed in 4 of the 9 revisions of this API.179

  • 0cf4cdf273615See the full diff
    • ▲

      the response property card_present_details/emv_data/application_identifier became nullable for the status 201

      response-property-became-nullable

    • ▲

      the response property card_present_details/emv_data/application_label became nullable for the status 201

      response-property-became-nullable

    • ▲

      the response property card_present_details/emv_data/application_transaction_counter became nullable for the status 201

      response-property-became-nullable

    • ▲

      the response property card_present_details/emv_data/cryptogram became nullable for the status 201

      response-property-became-nullable

    • ▲

      the response property card_present_details/payment_type became nullable for the status 201

      response-property-became-nullable

  • 9db82db717c52See the full diff
    • ○

      added the optional property additional_motor_vehicle_rental_data/rental_rate to the response with the 201 status

      response-optional-property-added

    • ○

      added the optional property additional_motor_vehicle_rental_data/renter_name to the response with the 201 status

      response-optional-property-added

  • 7919e33b4853102See the full diff
    • ▲

      the response property additional_purchase_data/customs_duty_amount became nullable for the status 201

      response-property-became-nullable

    • ▲

      the response property additional_purchase_data/destination_country_code became nullable for the status 201

      response-property-became-nullable

    • ▲

      the response property additional_purchase_data/destination_postal_code became nullable for the status 201

      response-property-became-nullable

    • ▲

      the response property additional_purchase_data/discount_amount became nullable for the status 201

      response-property-became-nullable

    • ▲

      the response property additional_purchase_data/invoice_reference_number became nullable for the status 201

      response-property-became-nullable

    • ▲

      the response property additional_purchase_data/order_date became nullable for the status 201

      response-property-became-nullable

    • ▲

      the response property additional_purchase_data/sales_tax became nullable for the status 201

      response-property-became-nullable

    • ▲

      the response property additional_purchase_data/ship_from_postal_code became nullable for the status 201

      response-property-became-nullable

    • ▲

      the response property additional_purchase_data/shipping_amount became nullable for the status 201

      response-property-became-nullable

    • ▲

      the additional_purchase_data/item_data/items/quantity response's property type/format changed from number/decimal to number/ for status 201

      response-property-type-changed

    • ○

      added the optional property additional_purchase_data/item_data/items/sales_tax_amount to the response with the 201 status

      response-optional-property-added

    • ○

      added the optional property additional_purchase_data/item_data/items/sales_tax_rate to the response with the 201 status

      response-optional-property-added

  • 96653f0c196b25See the full diff
    • ▲

      the response property network_details became nullable for the status 201

      response-property-became-nullable

    • ▲

      the response property security_code_verification became nullable for the status 201

      response-property-became-nullable

    • ○

      added the optional property additional_lodging_data to the response with the 201 status

      response-optional-property-added

    • ○

      added the optional property additional_motor_vehicle_rental_data to the response with the 201 status

      response-optional-property-added

    • ○

      added the optional property card_present_details/digital_signature_file_id to the response with the 201 status

      response-optional-property-added

    • ○

      added the optional property card_present_details/emv_data/network_emv_response to the response with the 201 status

      response-optional-property-added

    • ○

      added the optional property messages to the response with the 201 status

      response-optional-property-added