Create a Transfer

Create a Transfer.

Request
header Parameters
Accept
string
Default: application/hal+json
Finix-Version
string
Default: 2018-01-01

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

Example: 2022-02-01
Request Body schema: application/json
Any of:
object or null

Object detailing any Buyer Charges that got included in the Authorization.

object

Additional information about the purchase. Used for Level 2 and Level 3 Processing.

adjustment_request
boolean or null

Details if the transfer was created to adjust funds.

amount
required
integer <int64>

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

currency
required
string

ISO 4217 3 letter currency code.

Enum: "AED" "AFN" "ALL" "AMD" "ANG" … 174 more
destination
string or null

ID of the Payment Instrument where funds will be sent.

device
string or null

The ID of the activated device.

fee
integer <int64>

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.
fraud_session_id
string

The fraud_session_session ID you want to review for fraud. For more info, see Fraud Detection.

idempotency_id
string or null

A randomly generated value that gets tied with the request.

merchant
required
string or null

ID of the Merchant the Transfer was created under.

operation_key
string or null

Details the operation that is be performed in the transaction.

Enum: "PUSH_TO_CARD" "PULL_FROM_CARD" "CARD_PRESENT_DEBIT" "CARD_PRESENT_UNREFERENCED_REFUND" "SALE" … 3 more
processor
string

Name of the transaction processor.

source
required
string

ID of the Payment Instrument where funds get debited.

security_code
string or null

The 3-4 digit security code for the card (i.e. CVV code). Include the CVV code of the card to include Card Verification Checks with the created Transfer.

statement_descriptor
string or null <= 20 characters
  • The description of the seller that appears on the buyer's bank or card statement.
  • If you are on our Flex Product, statement_descriptors for `Transfers` in live enviroments will have a FI * prefix if you are on LITLE_V1 or VANTIV_V1. If you are using a FINIX_V1 processor, there will be no FI * prefix.
    • object or 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)
    object or null

    The 3D secure information required to create a 3D secure Transfer.

    Array of objects or null or null
    • An array used to detail how funds from the Transfer will split and the amount Merchants receive.
    • The combined amounts under split_transfers must be equal to the amount submitted in the parent Transfer.
    • For more information, see Split Transactions.
    Responses
    201

    Single Transfer object

    400

    Error

    401

    Authentication information is missing or invalid

    402

    402 - Payment required

    403

    Forbidden

    404

    Object does not exist

    406

    Not Acceptable

    422

    Invalid field

    post/transfers
    Request samples 
    Response samples 
    application/json
    {}
    List Transfers
    Retrieve a list of Transfers.
    

    For details on how to query endpoints using the available parameters, see Query Parameters.
    

    Request 
    query Parameters
    after_cursor
    string
    Return every resource created after the cursor value.
    

     
     Example:  after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
    before_cursor
    string
    Return every resource created before the cursor value.
    

     
     Example:  before_cursor=TRnasXQ5AmjsLnPMwnme7TL4
    limit
    integer
    The numbers of items to return.
    

     
     Example:  limit=10
    amount
    integer
    Filter by an amount equal to the given value.
    

     
     Example:  amount=100
    amount.gt
    integer
    Filter by an amount greater than.
    

     
     Example:  amount.gt=100
    amount.gte
    integer
    Filter by an amount greater than or equal.
    

     
     Example:  amount.gte=100
    amount.lt
    integer
    Filter by an amount less than.
    

     
     Example:  amount.lt=100
    amount.lte
    integer
    Filter by an amount less than or equal.
    

     
     Example:  amount.lte=100
    bank_return_reason_code
    string
    Filter bank reversals by ACH Return Code. Use comma-separation to query for multiple values.
    

     
     Example:  bank_return_reason_code=R03,R07
    buyer_business_name
    string
    Filter by the Buyer Identity's business name (exact match).
    

     
     Example:  buyer_business_name=Finix%20Flowers
    buyer_business_name.like
    string
    Filter by the Buyer Identity's business name (partial match).
    

     
     Example:  buyer_business_name.like=finix
    buyer_doing_business_as
    string
    Filter by the Buyer Identity's Doing Business As (exact match).
    

     
     Example:  buyer_doing_business_as=Finix%20Flowers
    buyer_doing_business_as.like
    string
    Filter by the Buyer Identity's Doing Business As (partial match).
    

     
     Example:  buyer_doing_business_as.like=finix
    buyer_identity_first_name
    string
    Filter by the Buyer Identity's first name (exact match).
    

     
     Example:  buyer_identity_first_name=John
    buyer_identity_first_name.like
    string
    Filter by the Buyer Identity's first name (partial match).
    

     
     Example:  buyer_identity_first_name.like=joh
    buyer_identity_id
    string
    Filter by the Buyer Identity's ID.
    

     
     Example:  buyer_identity_id=ID6Qm3BQUxGFcCWZ185TS8sn
    buyer_identity_last_name
    string
    Filter by the Buyer Identity's last name (exact match).
    

     
     Example:  buyer_identity_last_name=Doe
    buyer_identity_last_name.like
    string
    Filter by the Buyer Identity's last name (partial match).
    

     
     Example:  buyer_identity_last_name.like=do
    buyer_identity_name
    string
    Filter by the Buyer Identity's full personal name (exact match).
    

     
     Example:  buyer_identity_name=John%20Doe
    buyer_identity_name.like
    string
    Filter by the Buyer Identity's full personal name (partial match).
    

     
     Example:  buyer_identity_name.like=john
    created_at.gte
    string <date-time> 
    Filter where created_at is after the given date.
    

     
     Example:  created_at.gte=2022-09-27T11:21:23
    created_at.lte
    string <date-time> 
    Filter where created_at is before the given date.
    

     
     Example:  created_at.lte=2022-09-27T11:21:23
    currency
    string
    Filter by the currency of the resource.
    

     
     Example:  currency=USD
    device
    string
    Filter by the device's ID.
    

     
     Example:  device=DVsEanpBtsAVvCHbNXkFaH6f
    id
    string
    Filter by id.
    

     
    idempotency_id
    string
    Filter by Idempotency ID.
    

     
     Example:  idempotency_id=15d32948-c766-4033-8d87-dfbdcabcbc5c
    instrument_account_last4
    string
    For BANK_ACCOUNT Payment Instruments, filter by the last-4 digits of the bank account number (i.e., from the Payment Instrument's masked_account_number).
    

     
     Example:  instrument_account_last4=1234
    instrument_bin
    string
    For PAYMENT_CARD Payment Instruments, filter by the first-6 digits of the card's number (i.e., the Payment Instrument's bin).
    

     
     Example:  instrument_bin=601100
    instrument_brand_type
    string
    For PAYMENT_CARD Payment Instruments, filter by the card's brand.
    

     
     Example:  instrument_brand_type=MASTERCARD
    instrument_card_last4
    string
    For PAYMENT_CARD Payment Instruments, filter by the last-4 digits of the card's number (i.e., the Payment Instrument's last_four).
    

     
     Example:  instrument_card_last4=4242
    instrument_issuer_country
    string
    For PAYMENT_CARD Payment Instruments, filter by the card's issuing country (i.e., the Payment Instrument's issuer_country). Use comma-separation to query for multiple values.
    

     
     Example:  instrument_issuer_country=USA,CAN
    instrument_name
    string
    Filter by the Payment Instrument's name (exact match).
    

     
     Example:  instrument_name=Business%20Card
    instrument_type
    string
    Filter by the Payment Instrument's type.
    

     Enum: "PAYMENT_CARD" "BANK_ACCOUNT"  
     Example:  instrument_type=PAYMENT_CARD
    merchant_id
    string
    Filter by the Merchant's ID (i.e., the Transfer's merchant).
    

     
     Example:  merchant_id=MUtAWVfXkf149BVi2cL2HvPU
    merchant_identity_id
    string
    Filter by the Merchant's Identity ID (i.e., the Transfer's merchant_identity).
    

     
     Example:  merchant_identity_id=IDtX3ciHPq2DDquCQJRwj7VW
    merchant_identity_name
    string
    Filter by the Merchant's name (i.e., the Merchant's merchant_name).
    

     
     Example:  merchant_identity_name=Finix%20Flowers
    merchant_mid
    string
    Filter by the Merchant's Merchant Identification Number (MID) (i.e., the Merchant's mid).
    

     
     Example:  merchant_mid=FNXkitpwdmgMJ8Vz9FxKBCSza
    merchant_processor_id
    string
    Filter by the Merchant's processor (i.e., the Merchant's processor).
    

     
     Example:  merchant_processor_id=DUMMY_V1
    ready_to_settle_at.gte
    string <date-time> 
    Filter where ready_to_settle_at is after the given date. Only available on Finix-Version: 2022-02-01. For more details, see Versioning.
    

     
     Example:  ready_to_settle_at.gte=2023-06-28T00:00:00
    ready_to_settle_at.lte
    string <date-time> 
    Filter where ready_to_settle_at is before the given date. Only available on Finix-Version: 2022-02-01. For more details, see Versioning.
    

     
     Example:  ready_to_settle_at.lte=2023-06-28T00:00:00
    state
    string
    Filter by the transfer's state.
    

     Enum: "ALL" "SUCCEEDED" "FAILED" "PENDING" "CANCELED"  
     Example:  state=SUCCEEDED
    statement_descriptor
    string
    Filter by statement_descriptor.
    

     
     Example:  statement_descriptor=Finix%20Flowers
    trace_id
    string
    Filter by trace_id.
    

     
     Example:  trace_id=021fc4ed-f0a8-4932-820c-b22b542526f8
    type
    string
    Filter by type.
    

     Enum: "ALL" "DEBIT" "CREDIT" "REVERSAL" "SETTLEMENT"  
     Example:  type=REVERSAL
    updated_at.gte
    string <date-time> 
    Filter where updated_at is after the given date.
    

     
     Example:  updated_at.gte=2022-09-27T11:21:23
    updated_at.lte
    string <date-time> 
    Filter where updated_at is before the given date.
    

     
     Example:  updated_at.lte=2023-01-21T10:17:22
    tags.key
    string
    Filter by the tag's key. For more information, see Tags.
    

     
     Example:  tags.key=card_type
    tags.value
    string
    Filter by the tag's value. For more information, see Tags.
    

     
     Example:  tags.value=business_card
    header Parameters
    Accept
    string
     Default:  application/hal+json
    Body Header
    

     
    Responses 
    200
    List of Transfer objects
    

    401
    Authentication information is missing or invalid
    

    403
    Forbidden
    

    404
    Object does not exist
    

    406
    Not Acceptable
    

    get/transfers
    Request samples 
    curl "https://finix.sandbox-payments-api.com/transfers" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

    Response samples 
    application/json
    {}
    Fetch a Transfer
    Retrieve a Transfer.
    

    Request 
    path Parameters
    transfer_id
    required
    string
    ID of Transfer resource.
    

     
    header Parameters
    Accept
    string
     Default:  application/hal+json
     
    Responses 
    200
    Single Transfer object
    

    401
    Authentication information is missing or invalid
    

    403
    Forbidden
    

    404
    Object does not exist
    

    406
    Not Acceptable
    

    get/transfers/{transfer_id}
    Request samples 
    curl "https://finix.sandbox-payments-api.com/transfers/TRvypRNBeqM597Zi4DcqJ2Vh" \
  -H "Content-Type: application/json" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

    Response samples 
    application/json
    {}
    Update a Transfer
    Update a Transfer.
    

    Request 
    path Parameters
    transfer_id
    required
    string
    ID of Transfer resource.
    

     
    header Parameters
    Accept
    string
     Default:  application/hal+json
     
    Request Body schema: application/json
    object or 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)
      • 

    

     
    Responses 
    200
    Updating a Transfer response.
    

    401
    Authentication information is missing or invalid
    

    403
    Forbidden
    

    404
    Object does not exist
    

    406
    Not Acceptable
    

    put/transfers/{transfer_id}
    Request samples 
    curl "https://finix.sandbox-payments-api.com/transfers/TRvypRNBeqM597Zi4DcqJ2Vh" \
  -H "Content-Type: application/json" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X PUT \
  -d '
  {
    "tags": {
      "test": "sale"
    }
  }'
    Response samples 
    application/json
    {}
    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
    

    Request 
    path Parameters
    transfer_id
    required
    string
    ID of Transfer object.
    

     
    header Parameters
    Finix-Version
    string
     Default:  2018-01-01
    Specify the API version of your request. For more details, see Versioning.
    

     
     Example:  2022-02-01
    Request Body schema: application/json
    Any of:
    idempotency_id
    string or null
    Pass any randomly generated or internal ID to idempotently identify Transfers, Authorizations, and refund requests.
    

     
    refund_amount
    required
    integer
    The amount of the refund in cents. It must be equal to or less than the amount of the original Transfer.
    

     
    object or 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)
      • 

    

     
    Responses 
    201
    Refunding/reversing a Transfer response.
    

    400
    Error
    

    401
    Authentication information is missing or invalid
    

    403
    Forbidden
    

    404
    Object does not exist
    

    406
    Not Acceptable
    

    422
    Error
    

    post/transfers/{transfer_id}/reversals
    Request samples 
    Response samples 
    application/json
    {}
    List Reversals on a Transfer
    Retrieve a list of reversals for a Transfer.
    

    For details on how to query endpoints using the available parameters, see Query Parameters.
    

    Request 
    path Parameters
    transfer_id
    required
    string
    ID of Transfer object.
    

     
    query Parameters
    limit
    integer <int64> 
    The number of entries to return.
    

     
    after_cursor
    string
    Return every resource created after the cursor value.
    

     
     Example:  after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
    before_cursor
    string
    Return every resource created before the cursor value.
    

     
     Example:  before_cursor=TRnasXQ5AmjsLnPMwnme7TL4
    header Parameters
    Accept
    string
     Default:  application/hal+json
    Body Header
    

     
    Responses 
    200
    List of Reversals
    

    401
    Authentication information is missing or invalid
    

    403
    Forbidden
    

    404
    Object does not exist
    

    406
    Not Acceptable
    

    get/transfers/{transfer_id}/reversals
    Request samples 
    curl "https://finix.sandbox-payments-api.com/transfers/TRacB6Q6GcW6yvFUKawSnMEP/reversals" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

    Response samples 
    application/json
    {}