Pull from Card

Debit funds from a Payment Instrument in real time.

With Finix Pull from Card, users can debit any Payment Instrument in real-time.

Instead of using the ACH, which can take a business day to settle funds, Finix's Push to Card solution can disburses funds to existing cards 24/7, 365 days a week With Finix Pull from Card, users can immediately pull (debit) funds from any Payment Instrument, including bank accounts, debit cards, credit cards, or prepaid cards.

You can use Finix's Pull from Card to:

Debit funds from a Payment Instrument .
Use Pull from Card to debit funds from a Payment Instrument . Then you can use Push to Card to the Payment Instrument that needs to be credited.

info

This API is available for Disbursement use cases only. If you have additional questions, please contact the Finix Support team.

Step 1: Create a Sender Identity

The first step to pull (or debit) funds is creating an Identity resource. Each Identity represents either a person or a business. We use this resource to associate cards and payouts. This structure makes it simple to manage and reconcile payment instruments and payout history. Accounting of funds is done using the Identity so it's recommended to have an Identity per recipient of funds. Additionally, the Identity resource is optionally used to collect KYC information.

Copy

Copied

curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u USte61SqeNkAZnpfavK3fQNG:bd98703c-d72c-458e-8873-4295f5bac713 \
    -d '
	{
	    "entity": {
	        "phone": "7145677612",
	        "first_name": "Amy",
	        "last_name": "Curry",
	        "email": "Amy@gmail.com",
	        "personal_address": {
	            "city": "San Mateo",
	            "country": "USA",
	            "region": "CA",
	            "line2": "Apartment 7",
	            "line1": "741 Douglass St",
	            "postal_code": "94114"
	        }
	    },
      "tags": {
	        "key": "value"
	    }
	}'

Example Response:

Copy

Copied

{
    "id": "IDiKENBHELZo3mi5Rrpyh38k",
    "created_at": "2022-10-10T06:53:25.83Z",
    "updated_at": "2022-10-10T06:53:25.83Z",
    "application": "APpJbVTLdEuwGfcxBJvb1qNH",
    "entity": {
        "amex_mid": null,
        "annual_card_volume": 0,
        "business_address": null,
        "business_name": null,
        "business_phone": null,
        "business_tax_id_provided": false,
        "business_type": null,
        "default_statement_descriptor": null,
        "discover_mid": null,
        "dob": null,
        "doing_business_as": null,
        "email": "Amy@gmail.com",
        "first_name": "Amy",
        "has_accepted_credit_cards_previously": false,
        "incorporation_date": null,
        "last_name": "Curry",
        "max_transaction_amount": 0,
        "mcc": null,
        "ownership_type": null,
        "personal_address": {
            "line1": "741 Douglass St",
            "line2": "Apartment 7",
            "city": "San Mateo",
            "region": "CA",
            "postal_code": "94114",
            "country": "USA"
        },
        "phone": "7145677612",
        "principal_percentage_ownership": null,
        "short_business_name": null,
        "tax_authority": null,
        "tax_id_provided": false,
        "title": null,
        "url": null
    },
    "tags": {
        "key": "value"
    },
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDiKENBHELZo3mi5Rrpyh38k"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDiKENBHELZo3mi5Rrpyh38k/verifications"
        },
        "merchants": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDiKENBHELZo3mi5Rrpyh38k/merchants"
        },
        "settlements": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDiKENBHELZo3mi5Rrpyh38k/settlements"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDiKENBHELZo3mi5Rrpyh38k/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDiKENBHELZo3mi5Rrpyh38k/transfers"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDiKENBHELZo3mi5Rrpyh38k/payment_instruments"
        },
        "associated_identities": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDiKENBHELZo3mi5Rrpyh38k/associated_identities"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDiKENBHELZo3mi5Rrpyh38k/disputes"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APpJbVTLdEuwGfcxBJvb1qNH"
        }
    }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/identities

Request Arguments

Field	Type	Description
`email`	string, optional	Email
`first_name`	string, optional	First name
`last_name`	string, optional	Last name
`personal_address`	object, optional	Customers shipping address or billing address (Full description of child attributes below)
`phone`	string, optional	Phone number
`tags`	object, optional	Key value pair for annotating custom metadata (e.g. order numbers)

Address-object Request Arguments

Field	Type	Description
`city`	string, optional	City (max 20 characters)
`country`	string, optional	3-Letter Country code
`line1`	string, optional	First line of the address (max 35 characters)
`line2`	string, optional	Second line of the address (max 35 characters)
`postal_code`	string, optional	Zip or Postal code (max 7 characters)
`region`	string, optional	2-letter State code

Step 2: Add a Payment Instrument for the Sender

attention

Please note that creating Payment Instruments and passing payment details (account number, card number, etc.) directly via the API should only be done for testing purposes. You must use the Tokenization Forms or Mobile Tokenization to accept payment details and remain out of PCI scope.

Now that we've created an Identity for our sender, we'll need to tokenize a payment card where funds will be pulled from.

In the API, payment cards are represented by the Payment Instrument resource.

To classify the Payment Instrument as a payment card you'll need to pass PAYMENT_CARD in the type field of your request, and you'll also want to pass the ID of the Identity that you created in the last step via the identity field to properly associate it with your sender.

attention

Including an address when tokenizing a card can lower interchange on credit card transactions.

Copy

Copied

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u USte61SqeNkAZnpfavK3fQNG:bd98703c-d72c-458e-8873-4295f5bac713 \
    -d '
	{
	    "address": {
	        "city": "San Francisco",
	        "country": "USA",
	        "line1": "900 Metro Center Blv",
	        "postal_code": "94404",
	        "region": "CA"
	    },
	    "expiration_month": 12,
	    "expiration_year": 2029,
	    "identity": "ID7xXmm4Qwq7FRreERno2KRC",
	    "name": "John Smith",
	    "number": "4895142232120006",
	    "security_code": "022",
	    "tags": {
	        "card_name": "Business Card"
	    },
	    "type": "PAYMENT_CARD"
	}'

Example Response:

Copy

Copied

{
    "id": "PIb1Um9S5byMZwGnweP3DbLW",
    "created_at": "2022-10-10T06:55:29.82Z",
    "updated_at": "2022-10-10T06:55:29.82Z",
    "application": "APpJbVTLdEuwGfcxBJvb1qNH",
    "created_via": "API",
    "currency": "USD",
    "enabled": true,
    "fingerprint": "FPRogKWsRQks2HGaau5eGR9AF",
    "identity": "ID7xXmm4Qwq7FRreERno2KRC",
    "instrument_type": "PAYMENT_CARD",
    "address": {
        "line1": "900 Metro Center Blv",
        "line2": null,
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94404",
        "country": "USA"
    },
    "address_verification": "UNKNOWN",
    "bin": "489514",
    "brand": "VISA",
    "card_type": "UNKNOWN",
    "expiration_month": 12,
    "expiration_year": 2029,
    "issuer_country": "UNKNOWN",
    "last_four": "0006",
    "name": "John Smith",
    "security_code_verification": "UNKNOWN",
    "tags": {
        "card_name": "Business Card"
    },
    "type": "PAYMENT_CARD",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIb1Um9S5byMZwGnweP3DbLW"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIb1Um9S5byMZwGnweP3DbLW/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIb1Um9S5byMZwGnweP3DbLW/transfers"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIb1Um9S5byMZwGnweP3DbLW/verifications"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APpJbVTLdEuwGfcxBJvb1qNH"
        },
        "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID7xXmm4Qwq7FRreERno2KRC"
        },
        "updates": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIb1Um9S5byMZwGnweP3DbLW/updates"
        }
    }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/payment_instruments

Request Arguments

Field	Type	Description
`address`	object, required	Billing address (Full description of child attributes below) Note: Including a postal or zip code when tokenizing a card can lower the interchange on credit card transactions
`currency`	string, required	3-letter ISO code designating the currency of the `Payment Instruments` (e.g. USD, CAD)
`expiration_month`	integer, required	Expiration month (e.g. 12 for December)
`expiration_year`	integer, required	4-digit expiration year
`identity`	string, required	ID of the `Identity` that the card should be associated
`name`	string, optional	Full name of the registered card holder
`number`	string, required	Primary card account number
`security_code`	string, required	The 3-4 digit security code for the card (i.e. CVV code)
`type`	string, required	Type of `Payment Instrument` (for cards input PAYMENT_CARD)

Address-object Request Arguments

Field	Type	Description
`city`	string, optional	City
`country`	string, optional	3-Letter Country code
`line1`	string, optional	First line of the address
`line2`	string, optional	Second line of the address
`postal_code`	string, required	Zip or Postal code
`region`	string, optional	2-letter State code

Step 3: Verify Address Verification System (AVS) and CVV

Now that we've associated a payment instrument to a sender, we have the ability to verify whether or not the card has passed AVS and CVV checks. How? By making a request to the Verifications endpoint. The returned Verification resource returns a set of general attributes and details about the card in question (e.g. card type, issuer information). Below you'll see a number of fields and the potential responses.

Copy

Copied

curl https://finix.sandbox-payments-api.com/payment_instruments/PIb1Um9S5byMZwGnweP3DbLW/verifications \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u USte61SqeNkAZnpfavK3fQNG:bd98703c-d72c-458e-8873-4295f5bac713 \
    -d '
	{
	    "processor": "VISA_V1"
	}'

Example Response:

Copy

Copied

{
    "id": "VInmEwhofrsXSsYHarfotPiX",
    "created_at": "2022-10-10T06:56:29.10Z",
    "updated_at": "2022-10-10T06:56:31.92Z",
    "application": "APpJbVTLdEuwGfcxBJvb1qNH",
    "identity": null,
    "merchant": null,
    "merchant_identity": null,
    "messages": [],
    "payment_instrument": "PIb1Um9S5byMZwGnweP3DbLW",
    "processor": "VISA_V1",
    "raw": {
        "validation_details": {
            "systems_trace_audit_number": "228306000168",
            "error_result": null,
            "transaction_identifier": "140725031801776",
            "approval_code": null,
            "action_code": "N7",
            "response_code": "5",
            "address_verification_results": "Y",
            "cvv2_result_code": "N"
        },
        "inquiry_details": {
            "systems_trace_audit_number": "228306000168",
            "error_result": null,
            "visa_network_info": [
                {
                    "card_type_code": "D",
                    "billing_currency_code": 840,
                    "billing_currency_minor_digits": 2,
                    "issuer_name": "Visa Test Bank",
                    "card_issuer_country_code": 840,
                    "fast_funds_indicator": "B",
                    "push_funds_block_indicator": "C",
                    "online_gambing_block_indicator": "N"
                }
            ],
            "ppgs_network_info": []
        }
    },
    "state": "SUCCEEDED",
    "tags": {},
    "trace_id": "228306000168",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/verifications/VInmEwhofrsXSsYHarfotPiX"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APpJbVTLdEuwGfcxBJvb1qNH"
        },
        "payment_instrument": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIb1Um9S5byMZwGnweP3DbLW"
        }
    }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/payment_instruments/:PAYMENT_INSTRUMENT_ID/verifications

URL Parameters

`Parameter`	Description
:PAYMENT_INSTRUMENT_ID	ID of the `Payment Instrument`

Request Arguments

Field	Type	Description
`country`	string, optional	3-Letter Country code. This attribute is currently only applicable for our Latin America partners.
`processor`	string, required	The name of the processor, which needs to be: `VISA_V1`

Address Verification Results (address_verification_results)

`Letter`	Description
D, F, M, Y	Address verified
A, B, C, G, I, N, P, R, S, U, W	Address not verified
`Z`	Postal/ZIP match, street addresses do not match or street address not included in request

Card Verification 2 Results (cvv2_result_code)

`Letter`	Description
`M`	CVV and expiration verified
N, P, S	Either CVV or expiration date is incorrect
`U`	Issuer does not participate in CVV2 service

Card Type (card_type_code)

This one-character code indicates whether the account is credit, debit, prepaid, deferred debit, or charge.

`Letter`	Description
`C`	Credit
`D`	Debit
`H`	Charge Card
`P`	Prepaid
`R`	Deferred Debit

Fast Funds Indicator (fast_funds_indicator)

Indicates whether or not the card is Fast Funds eligible (i.e. if the funds will settle in 30 mins or less). If not eligible, typically funds will settle within 2 business days.

`Letter`	Description
`B`	Fast Funds eligible for all transactions
`D`	Fast Funds eligible for only domestic transactions
`N`	Not eligible for Fast Funds

Push Funds Indicator (push_funds_block_indicator)

This code indicates if the associated card can receive push-to-card disbursements.

`Letter`	Description
A, B, C	Accepts push-to-card payments
`N`	Does not accept push-to-card payments

Online Gambling Block Indicator (online_gambing_block_indicator)

Indicates if the card can receive push-payments for online gambling payouts.

`Letter`	Description
`Y`	Blocked for online gambling payouts
`N`	Not blocked for online gambling payouts

Card Product ID (card_product_id)

A combination of card brand, platform, class and scheme.

`Letter`	Description
`A`	Visa Traditional
`AX`	American Express
`B`	Visa Traditional Rewards
`C`	Visa Signature
`D`	Visa Signature Preferred
`DI`	Discover
`DN`	Diners
`E`	Proprietary ATM
`F`	Visa Classic
`G`	Visa Business
`G1`	Visa Signature Business
`G2`	Visa Business Check Card
`G3`	Visa Business Enhanced
`G4`	Visa Infinite Business
`G5`	Visa Business Rewards
`I`	Visa Infinite
`I1`	Visa Infinite Privilege
`I2`	Visa UHNW
`J3`	Visa Healthcare
`JC`	JCB
`K`	Visa Corporate T&E
`K1`	Visa Government Corporate T&E
`L`	Visa Electron
`M`	MasterCard
`N`	Visa Platinum
`N1`	Visa Rewards
`N2`	Visa Select
`P`	Visa Gold
`Q`	Private Label
`Q1`	Private Label Prepaid
`Q2`	Private Label Basic
`Q3`	Private Label Standard
`Q4`	Private Label Enhanced
`Q5`	Private Label Specialized
`Q6`	Private Label Premium
`R`	Proprietary
`S`	Visa Purchasing
`S1`	Visa Purchasing with Fleet
`S2`	Visa Government Purchasing
`S3`	Visa Government Purchasing with Fleet
`S4`	Visa Commercial Agriculture
`S5`	Visa Commercial Transport
`S6`	Visa Commercial Marketplace
`U`	Visa Travel Money
`V`	Visa V PAY

Product Sub-Type (card_product_subtype)

Description of product subtype.

`Letter`	Description
`AC`	Agriculture Maintenance Account
`AE`	Agriculture Debit Account/Electron
`AG`	Agriculture
`AI`	Agriculture Investment Loan
`CG`	Brazil Cargo
`CS`	Construction
`DS`	Distribution
`HC`	Healthcare
`LP`	Visa Large Purchase Advantage
`MA`	Visa Mobile Agent
`MB`	Interoperable Mobile Branchless Banking
`MG`	Visa Mobile General
`VA`	Visa Vale - Supermarket
`VF`	Visa Vale - Fuel
`VR`	Visa Vale - Restaurant

Card Sub-Type (card_subtype_code)

The code for account funding source subtype, such as reloadable and non-reloadable.

`Letter`	Description
`N`	Non-Reloadable
`R`	Reloadable

Step 4: Provision a Sender Account

Now that we've associated a Payment Instrument with the sender's Identity we're ready to provision a Sender account. This is the last step before you can begin pulling from an Identity. Luckily you've already done most of the heavy lifting. Just make one final POST request, and you'll be returned a Merchant resource.

Copy

Copied

curl https://finix.sandbox-payments-api.com/identities/IDwz8pnpc483j9s1vnrsZuwo/merchants \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u USte61SqeNkAZnpfavK3fQNG:bd98703c-d72c-458e-8873-4295f5bac713 \
    -d '
	{
	    "processor": "VISA_V1"
	}'

curl https://finix.sandbox-payments-api.com/identities/ \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u USte61SqeNkAZnpfavK3fQNG:bd98703c-d72c-458e-8873-4295f5bac713

Example Response:

Copy

Copied

{
    "id": "MUh7FLQ9VNFcm4YERZZa8cHM",
    "created_at": "2022-10-10T07:01:41.46Z",
    "updated_at": "2022-10-10T07:01:41.96Z",
    "application": "APpJbVTLdEuwGfcxBJvb1qNH",
    "card_cvv_required": false,
    "card_expiration_date_required": true,
    "convenience_charges_enabled": false,
    "creating_transfer_from_report_enabled": true,
    "default_partial_authorization_enabled": false,
    "fee_ready_to_settle_upon": "RECONCILIATION",
    "gross_settlement_enabled": false,
    "identity": "IDwz8pnpc483j9s1vnrsZuwo",
    "level_two_level_three_data_enabled": false,
    "mcc": "4900",
    "merchant_name": "Finix Flowers",
    "merchant_profile": "MPt96xLrNqP6kwT46SMgJ58i",
    "mid": null,
    "onboarding_state": "APPROVED",
    "processing_enabled": true,
    "processor": "VISA_V1",
    "processor_details": {},
    "ready_to_settle_upon": "RECONCILIATION",
    "rent_surcharges_enabled": false,
    "settlement_enabled": true,
    "settlement_funding_identifier": "UNSET",
    "surcharges_enabled": false,
    "tags": {},
    "verification": "VIdYZb3pxvupkGCpHbSXLbmG",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MUh7FLQ9VNFcm4YERZZa8cHM"
        },
        "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDwz8pnpc483j9s1vnrsZuwo"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MUh7FLQ9VNFcm4YERZZa8cHM/verifications"
        },
        "merchant_profile": {
            "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPt96xLrNqP6kwT46SMgJ58i"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APpJbVTLdEuwGfcxBJvb1qNH"
        },
        "verification": {
            "href": "https://finix.sandbox-payments-api.com/verifications/VIdYZb3pxvupkGCpHbSXLbmG"
        }
    }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/identities/identityID/merchants

Request Arguments

Field	Type	Description
`processor`	string, optional	Name of Processor

Step 5: Pull Funds

Now it's time to pull funds from the sender.

Next you'll need to create a Transfer. What's a Transfer? Glad you asked! A Transfer represents any flow of funds either to or from a Payment Instrument. In this case we are pulling from a card.

To create a Transfer we'll simply supply the Payment Instrument ID of the previously tokenized card as the source field. In addition, you'll pass the an operational key which describes the action that you're taking.

You'll also want to store the ID from that Transfer for your records. Transfers can have two possible states SUCCEEDED and FAILED.

When the state of the Transfer updates to SUCCEEDED, you can use Finix Push to Card to push funds to any Payment Instrument.

Copy

Copied

curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u USte61SqeNkAZnpfavK3fQNG:bd98703c-d72c-458e-8873-4295f5bac713 \
    -d '
	{
	    "amount": 20000,
	    "currency": "USD",
	    "operation_key": "PULL_FROM_CARD",
	    "source": "PIaHGpBQYDc5fTpNxHgqoKMY",
	    "tags": {
	        "order_number": "21DFASJSAKAS"
	    }
	}'

Example Response:

Copy

Copied

{
    "id": "TRhCaABrump4Jr3eDb9CGrku",
    "created_at": "2022-10-10T07:02:38.56Z",
    "updated_at": "2022-10-10T07:02:40.31Z",
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "address_verification": null,
    "amount": 20000,
    "amount_requested": 20000,
    "application": "APpJbVTLdEuwGfcxBJvb1qNH",
    "currency": "USD",
    "destination": null,
    "externally_funded": "UNKNOWN",
    "failure_code": null,
    "failure_message": null,
    "fee": 0,
    "idempotency_id": null,
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "merchant_identity": "ID7JKYJBGDZf9CbQpfS7tDX7",
    "messages": [],
    "raw": null,
    "ready_to_settle_at": null,
    "security_code_verification": null,
    "source": "PIaHGpBQYDc5fTpNxHgqoKMY",
    "state": "SUCCEEDED",
    "statement_descriptor": null,
    "subtype": "API",
    "tags": {
        "order_number": "21DFASJSAKAS"
    },
    "trace_id": "228307000170",
    "type": "DEBIT",
    "_links": {
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APpJbVTLdEuwGfcxBJvb1qNH"
        },
        "self": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRhCaABrump4Jr3eDb9CGrku"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID7JKYJBGDZf9CbQpfS7tDX7"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRhCaABrump4Jr3eDb9CGrku/payment_instruments"
        },
        "reversals": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRhCaABrump4Jr3eDb9CGrku/reversals"
        },
        "fees": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRhCaABrump4Jr3eDb9CGrku/fees"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRhCaABrump4Jr3eDb9CGrku/disputes"
        },
        "source": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIaHGpBQYDc5fTpNxHgqoKMY"
        },
        "fee_profile": {
            "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPbDSnEPtaT8Nttxj9NJk7eC"
        }
    }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/transfers

Request Arguments

Field	Type	Description
`amount`	integer, required	The total amount that will be charged in cents (e.g. 100 cents to charge $1.00)
`country`	string, optional	3-Letter Country code. This attribute is currently only applicable for our Latin America partners.
`currency`	string, required	3-letter ISO code designating the currency of the `Transfers` (e.g. USD, CAD)
`operation_key`	string, required	PULL_FROM_CARD
`source`	string, required	ID of the `Payment Instrument` where funds will be pulled from
`tags`	object, optional	Key value pair for annotating custom metadata (e.g. order numbers)

Reverse a Pull-from-Card Transfer

A Transfer representing the refund (i.e. reversal) of a previously created transfer (type DEBIT). The refunded amount may be any value up to the amount of the original Transfer. These specific Transfers are distinguished by their type which return REVERSAL.

A Reversal can have one subtype indicating how it was created:

API: Transfer created via an end-user API request (e.g. POST)

Copy

Copied

curl https://finix.sandbox-payments-api.com/transfers/TRhCaABrump4Jr3eDb9CGrku/reversals \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USte61SqeNkAZnpfavK3fQNG:bd98703c-d72c-458e-8873-4295f5bac713 \
    -d  '
  {
  "refund_amount" : 100,
  "tags" : {
      "test" : "refund"
    }
  }'

Example Response:

Copy

Copied

{
    "id": "TRbHisDMuybvjNBj2sZnumY",
    "created_at": "2022-10-10T07:03:20.19Z",
    "updated_at": "2022-10-10T07:03:21.21Z",
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "address_verification": null,
    "amount": 100,
    "amount_requested": 100,
    "application": "APpJbVTLdEuwGfcxBJvb1qNH",
    "currency": "USD",
    "destination": "PIaHGpBQYDc5fTpNxHgqoKMY",
    "externally_funded": "UNKNOWN",
    "failure_code": null,
    "failure_message": null,
    "fee": 0,
    "idempotency_id": null,
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "merchant_identity": "ID7JKYJBGDZf9CbQpfS7tDX7",
    "messages": [],
    "raw": null,
    "ready_to_settle_at": null,
    "security_code_verification": null,
    "source": null,
    "state": "SUCCEEDED",
    "statement_descriptor": "FNX*FINIX",
    "subtype": "API",
    "tags": {
        "test": "refund"
    },
    "trace_id": "228307000171",
    "type": "REVERSAL",
    "_links": {
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APpJbVTLdEuwGfcxBJvb1qNH"
        },
        "self": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRbHisDMuybvjNBj2sZnumY"
        },
        "parent": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRhCaABrump4Jr3eDb9CGrku"
        },
        "destination": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIaHGpBQYDc5fTpNxHgqoKMY"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID7JKYJBGDZf9CbQpfS7tDX7"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRbHisDMuybvjNBj2sZnumY/payment_instruments"
        },
        "fee_profile": {
            "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPbDSnEPtaT8Nttxj9NJk7eC"
        }
    }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/transfers/:TRANSFER_ID/reversals

URL Parameters

`Parameter`	Description
:TRANSFER_ID	ID of the original `Transfer`

Request Arguments

Field	Type	Description
`refund_amount`	integer, required	The amount of the refund in cents (Must be equal to or less than the amount of the original `Transfer`)
`tags`	object, optional	Key value pair for annotating custom metadata (e.g. order numbers)