Create a Transfer

Create a Transfer.

Endpoint: POST /transfers
Security: BasicAuth

Header parameters:

• Finix-Version (string)
  Specify the API version of your request. For more details, see Versioning.
  Example: "2022-02-01"

• Content-Type (string)
  The data type being sent in the request body must be application/json.
  Example: "application/json"

Response 201 fields (application/json):

• id (string)
  The ID of the resource.

• created_at (string)
  Timestamp of when the object was created.

• updated_at (string)
  Timestamp of when the object was last updated.

• additional_buyer_charges (object, null)
  Details about any Buyer Charges included in the Transfer. The buyer charges are mutually exclusive.

• additional_buyer_charges.convenience_amount (integer, null)
  A convenience fee to charge the buyer for the transaction. This object property is mutually exclusive.

• additional_buyer_charges.rent_surcharge_amount (integer, null)
  A rent surcharge to charge the buyer for the transaction. This object property is mutually exclusive.

• additional_buyer_charges.surcharge_amount (integer, null)
  A surcharge amount to charge the buyer for the transaction. This object property is mutually exclusive.

• additional_healthcare_data (object, null)

• additional_healthcare_data.clinic_amount (integer, null)
  A clinic or other qualified medical amount for the transaction.

• additional_healthcare_data.dental_amount (integer, null)
  The dental amount for the transaction.

• additional_healthcare_data.prescription_amount (integer, null)
  The prescription/RX amount for the transaction.

• additional_healthcare_data.vision_amount (integer, null)
  The vision/optical amount for the transaction.

• additional_purchase_data (object, null) Additional information about the purchase used for Level 2 and Level 3 Processing. Please note that Visa is ending its Level 2 offering in April 2026.

• additional_purchase_data.customer_reference_number (string)
  The customer reference for the purchase (max 17 characters). For Visa, this field no longer qualifies for lower interchange after April 17, 2026. Include item_data for Level 3 processing.

• additional_purchase_data.customs_duty_amount (integer)
  The duty in cents on the total purchase amount for the order.

• additional_purchase_data.destination_country_code (string)
  The ISO country code of the order destination.

• additional_purchase_data.destination_postal_code (string)
  The postal code of the order destination (10 characters).

• additional_purchase_data.discount_amount (integer)
  The amount in cents of the discount for the order. You must include this field to qualify for Level 3 interchange benefits. Even if the value is (0), you should pass the field to qualify for Level 3.

• additional_purchase_data.invoice_reference_number (string)
  The order's invoice number (max 15 characters).

• additional_purchase_data.order_date (object)

• additional_purchase_data.order_date.day (integer)
  Day of purchase (between 1 and 31).

• additional_purchase_data.order_date.month (integer)
  Month of purchase (between 1 and 12).

• additional_purchase_data.order_date.year (integer)
  Year of purchase (4-digit).

• additional_purchase_data.sales_tax (integer)
  Total aggregate tax amount in cents for the entire purchase. Field is automatically calculated if you pass in the itemized tax amounts.

  • For non-taxable transactions either set sales_tax to 0 or omit from payload and also set tax_exempt to True.
  • Request must align so amount_excluding_sales_tax + sales_tax = amount_including_sales_tax.
  • For Visa, this field no longer qualifies for lower interchange after April 17, 2026. Include item_data for Level 3 processing.

• additional_purchase_data.sales_tax_finix_generated (integer, null)
  The sales tax amount in cents Finix calculated from the item_data line items.

• additional_purchase_data.ship_from_postal_code (string)
  The postal code from where order is shipped (10 characters).

• additional_purchase_data.shipping_amount (integer)
  The shipping cost in cents for the order.

• additional_purchase_data.tax_exempt (boolean)

  • For tax exempt purchases set to True.
  • If set to True, request can't include sales_tax.

• additional_purchase_data.item_data (array)
  Additional information about the transaction. Used for Level 2 and Level 3 Processing.

• additional_purchase_data.item_data.amount_excluding_sales_tax (integer)

  • Total cost of the line item in cents, excluding tax.
  • Must align with sales_tax so amount_excluding_sales_tax + sales_tax = amount_including_sales_tax.

• additional_purchase_data.item_data.amount_including_sales_tax (integer)

  • Total cost of the line item in cents, including tax.
  • Must align with sales_tax so amount_excluding_sales_tax + sales_tax = amount_including_sales_tax.

• additional_purchase_data.item_data.commodity_code (string)
  A commodity code is a numeric code representing a particular product or service as defined by the National Institute of Governmental Purchasing. The code can be 3, 5, 7, or 11 digits in length. The longer the code the more granular the description of the product/service. (max 12 characters).

• additional_purchase_data.item_data.cost_per_unit (integer)
  The price in cents, excluding tax, of one unit of the item purchased.

• additional_purchase_data.item_data.item_description (string)
  Required when item_data is supplied (max 25 characters).

• additional_purchase_data.item_data.item_discount_amount (integer)
  The item discount amount in cents. You must include this field to qualify for Level 3 interchange benefits. Even if the value is (0), you should pass the field to qualify for Level 3.

• additional_purchase_data.item_data.merchant_product_code (string)
  Merchant defined product code (max 12 characters).

• additional_purchase_data.item_data.quantity (number)
  The number of items purchased. Must be greater than 0.

• additional_purchase_data.item_data.unit_of_measure (string)
  The unit of measure of the purchased item (max 3 characters).

• address_verification (string, null)
  Details the results of the address verification checks.
  Enum: "POSTAL_CODE_AND_STREET_MATCH", "STREET_MATCH", "POSTAL_CODE_MATCH", "NO_ADDRESS", "NO_MATCH", "NOT_SUPPORTED", "UNKNOWN"

• amount (integer)
  The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).
  Example: 5000

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

• application (string)
  ID of the Application associated with the resource.

• bank_return_details (object, null)
  Details about a transfer that was returned and was unable to be processed. Only present when state is RETURNED

• bank_return_details.reason_code (string)
  Return response code from the bank.

• bank_return_details.reason_message (string)
  Detailed message explaining reason for the return.

• bank_return_details.reason_title (string)
  Short message categorizing reason for the return.

• card_present_details (object, null)
  Details needed to process card present transactions.

• card_present_details.approval_code (string, null)
  Unique ID used to identify the approval of the Transfer.

• card_present_details.brand (string, null)
  The brand of the card saved in the Payment Instrument.

• card_present_details.emv_data (object, null)
  Encrypted card data used to process the transaction.

• card_present_details.emv_data.application_identifier (string)
  ID of the application used in the transaction. Tag 9F06 from the EMVCo standard.

• card_present_details.emv_data.application_label (string)
  EMV application label. Tag 50 from the EMVCo standard.

• card_present_details.emv_data.application_preferred_name (string, null)
  EMV application label with formatting (if provided). Tag 9F12 from the EMVCo standard.

• card_present_details.emv_data.application_transaction_counter (string)
  Transaction number for the EMV application. Tag 9F36 from the EMVCo standard.

• card_present_details.emv_data.cryptogram (string)
  Cryptogram returned by the card. Tag 9F26 of the EMVCo standard.

• card_present_details.emv_data.issuer_code_table_index (string, null)
  The alphabet code table (according to ISO 8859) used by the EMV application (if provided). Tag 9F11.

• card_present_details.emv_data.pin_verified (boolean)
  Whether the cardholder's PIN number was verified.

• card_present_details.emv_data.tags (object, null)
  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)

• card_present_details.entry_mode (string, null)
  Details of the card payment method used to process the transaction.

  The possible enums are:

  • UNKNOWN - The method by which the payment card was used is unknown.
  • SWIPED - The card was swiped through a POS terminal.
  • CONTACTLESS - The payment was made by tapping a card on a POS terminal.
  • CHIP_ENTRY - The payment card was inserted into a card reader.
    Enum: "UNKNOWN", "SWIPED", "CONTACTLESS", "CHIP_ENTRY"

• card_present_details.masked_account_number (string, null)
  Last four digits of the bank account number.

• card_present_details.name (string, null)
  The name of the bank account or card owner.

• card_present_details.payment_type (string)
  The type of Payment Instrument used in the transaction (or the original payment).

• currency (string)
  ISO 4217 3-letter currency code.
  Enum: "CAD", "USD"

• created_via (string)
  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.
  Enum: "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"

• destination (string, null)
  ID of the Payment Instrument where funds will be sent.

• device (string)
  The ID of the Device resource the Transfer was created under.

• externally_funded (string)
  Details if the Transfer will be settled externally by card processors.

• failure_code (string, null)
  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_message (string, null)
  A human-readable description of why the transaction was declined. This will also include a suggestion on how to complete the payment.

• fee (integer)
  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_profile (string)
  The ID of the Fee Profile that will be used for calculating fees for this transfer.

• funds_flow_type (string, null)
  The type of disbursement to perform. Defaults to GENERAL_PAYOUT.
  Enum: "GENERAL_PAYOUT", "ME_TO_ME", "GOVERNMENT"

• idempotency_id (string, null)
  Pass any randomly generated or internal ID to idempotently identify Transfers, Authorizations, or refund requests.

• ip_address_details (object, null)
  Always returns null.

• merchant (string)
  The ID of the Merchant resource the Transfer was created under.
  Example: "MUxxxxxxxxxxxxxxxxxxxxxxx"

• merchant_identity (string)
  The ID of Identity resource used by the Merchant the Transfer was created under.
  Example: "IDxxxxxxxxxxxxxxxxxxxxxxxx"

• network_details (object)
  Contains network-specific fields used by issuers to identify transactions.

• network_details.brand (string)
  Card brand associated with the saved payment instrument.
  Example: "VISA"

• network_details.authorization_code (string)
  Code returned by the issuing bank when a transaction is authorized.
  Example: 840735

• network_details.acquirer_reference_number (string, null)
  Unique identifier banks use to trace chargebacks or refunds. Available only for Mastercard transactions; otherwise returns null.
  Example: 521600805857

• operation_key (string, null)
  Details the operation that's performed in the transaction.
  Enum: "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"

• parent_transfer (string, null)
  ID of the original parent Transfer. Only present when type is REVERSAL.

• parent_transfer_trace_id (string, null)
  The trace_id of the original parent Transfer. Only present when type is REVERSAL.

• pull_transfer_id (string, null)
  The ID of the corresponding pull Transfer linked in a ME_TO_ME transaction.

• raw (any)
  Raw response from the processor.

• ready_to_settle_at (string, null)
  The timestamp indicating when the Transfer is ready to be settled.

• receipt_last_printed_at (string, null)
  Timestamp when the receipt was last printed.

• security_code_verification (string)
  Details the results of the Card Verification Code check.
  Enum: "MATCHED", "UNKNOWN", "UNMATCHED"

• source (string, null)
  The ID of the Payment Instrument that will be debited and performing the Transfer.

• split_transfers (array)
  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 (string)
  The status of the Transfer.
  Enum: "CANCELED", "PENDING", "FAILED", "SUCCEEDED", "UNKNOWN", "RETURNED"

• statement_descriptor (string, null)
  The description of the Merchant that appears on the buyer's bank or card statement.

• subtype (string)
  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. Enum: "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"

• supplemental_fee (string, null)
  Amount in cents for which an additional fee will be created in addition to any fees created from the assigned fee profile.

• tags (object, null)
  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_amount (integer, null)
  The tip amount included in the total amount.

• trace_id (string, null)
  Trace ID of the Transfer. The processor sends back the trace_id so you can track the Transfer end-to-end.

• type (string)
  Type of Transfer.
  Enum: "DEBIT", "CREDIT", "REVERSAL", "ADJUSTMENT", "DISPUTE", "RESERVE", "SETTLEMENT", "UNKNOWN"

• third_party_details (object, null)
  Details about the third-party processor associated with the Transfer.

• third_party_details.external_trace_id (string, null)
  The trace ID returned by the third-party processor used to identify the Transfer.

• third_party_details.type (string, null)
  The name of the third-party processor associated with the Transfer.
  Enum: "CYBERSOURCE"

• _links (object)

• _links.application (object)
  Link to the Application the request was made under.

• _links.application.href (string)

• _links.destination (object)
  Link to the Payment Instrument where funds are getting sent.

• _links.destination.href (string)

• _links.device (object)
  Link to the Device the request was made under.

• _links.device.href (string)

• _links.disputes (object)
  Link to the Dispute the request was made under.

• _links.disputes.href (string)

• _links.fee_profile (object)
  Link to the fee_profile the request was made under.

• _links.fee_profile.href (string)

• _links.fees (object)
  Link to the fees the request is associated with.

• _links.fees.href (string)

• _links.merchant_identity (object)
  Link to the Identity the Merchant was created under and the Transfer was submitted with.

• _links.merchant_identity.href (string)

• _links.payment_instruments (object)
  Link to the Payment Instrument associated with the Transfer.

• _links.payment_instruments.href (string)

• _links.disputed_transfer (object)
  Link to the Transfer the Dispute is about.

• _links.disputed_transfer.href (string)

• _links.parent (object)
  Link to the original resource that was used in the request.

• _links.parent.href (string)

• _links.reversals (object)
  Link to the reversals associated with the Transfer.

• _links.reversals.href (string)

• _links.self (object)
  Link to the resource that was used in the request.

• _links.self.href (string)

• _links.source (object)
  Link to the Payment Instrument the Transfer was created under.

• _links.source.href (string)

Response 400 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

• _embedded.errors.logref (string)
  A log reference identifier for the error, useful for debugging and support purposes.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.

Response 401 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

• _embedded.errors.logref (string)
  A log reference identifier for the error, useful for debugging and support purposes.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.

Response 403 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

• _embedded.errors.logref (string)
  A log reference identifier for the error, useful for debugging and support purposes.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.

Response 404 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

• _embedded.errors.logref (string)
  A log reference identifier for the error, useful for debugging and support purposes.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.

Response 406 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

• _embedded.errors.logref (string)
  A log reference identifier for the error, useful for debugging and support purposes.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.

Response 422 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

• _embedded.errors.logref (string)
  A log reference identifier for the error, useful for debugging and support purposes.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.