Making a Payment

Learn about the key steps in making a card payment using the Finix API.

You can use Finix to process:

Online payments (also called ecommerce)
In-Person Payments
Apple Pay and Google Pay
ACH (eCheck)

This guide provides an overview of how to process a payment online that charges a card.

To process a card payment online:

Create an Identity for your Buyer
Tokenize payment details and Create a Payment Instrument
Create a sale
Handle the post-payments experience (processing refunds, managing disputes, etc.)

Before You Begin

Before you can process payments, you need the following:

An API Key
An approved Merchant.

Step 1: Create an Identity for your Buyer

The first step to process a card payment is to create an Identity to represent the buyer and their information.

An Identity resource can represent either a buyer (or a seller). The Identity resource helps manage payments, payment methods, bank accounts, transaction history, identity verification, and payouts between buyers and merchants.

Sales and Payment Instruments must be associated with an Identity to get processed successfully.

The first step of making a payment is to create an Identity for your buyer.

When creating an Identity for a buyer, all fields are optional.
Do not provide the business_type field. Including a value for business_type configures the Identity to get processed as a seller.

Copy

Copied

curl https://finix.sandbox-payments-api.com/identities \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -d '{
    "entity": {
      "email": "user@example.org",
      "first_name": "John",
      "last_name": "Smith",
      "personal_address": {
        "city": "San Mateo",
        "country": "USA",
        "line1": "741 Douglass St",
        "line2": "Apartment 7",
        "postal_code": "94114",
        "region": "CA"
      },
      "phone": "7145677613"
    },
    "tags": {
      "key": "value"
    }
  }'

A successful response returns 201 and the newly created Identity for the buyer.

Copy

Copied

{
  "id": "IDoWPMqaMxiBypnYc7huXVBR",
  "created_at": "2022-10-10T05:29:53.32Z",
  "updated_at": "2022-10-10T05:29:53.32Z",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "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": "user@example.org",
    "first_name": "John",
    "has_accepted_credit_cards_previously": false,
    "incorporation_date": null,
    "last_name": "Smith",
    "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": "7145677613",
    "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/IDoWPMqaMxiBypnYc7huXVBR"
    },
    "verifications": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDoWPMqaMxiBypnYc7huXVBR/verifications"
    },
    "merchants": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDoWPMqaMxiBypnYc7huXVBR/merchants"
    },
    "settlements": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDoWPMqaMxiBypnYc7huXVBR/settlements"
    },
    "authorizations": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDoWPMqaMxiBypnYc7huXVBR/authorizations"
    },
    "transfers": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDoWPMqaMxiBypnYc7huXVBR/transfers"
    },
    "payment_instruments": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDoWPMqaMxiBypnYc7huXVBR/payment_instruments"
    },
    "associated_identities": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDoWPMqaMxiBypnYc7huXVBR/associated_identities"
    },
    "disputes": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDoWPMqaMxiBypnYc7huXVBR/disputes"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    }
  }
}

Step 2: Create a Payment Instrument

A Payment Instrument represents the payment method of a buyer. A buyer can have multiple Payment Instruments associated with their Identity. You can use Finix's encrypted-vault to safely tokenize and store all of your buyers Payment Instruments.

To collect and process payment data in your own PCI compliant cardholder data environment (CDE), see Handling Raw Card Data. To store the card details that were collected with the hosted fields, create a Payment Instrument:

Include the token that was generated.
Include the Identity that was created for the buyer.

CVV and AVS checks

You can also perform a CVV or AVS check to verify the submitted information matches what the issuing bank has saved for the buyer.

Copy

Copied

curl https://finix.sandbox-payments-api.com/payment_instruments \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -d '{
    "token": "TKiMxe323RE5Dq3wLVtG8kSW",
    "type": "TOKEN",
    "identity": "IDpYDM7J9n57q849o9E9yNrG"
  }'

A successful response returns 201 and the newly created Payment Instrument.

Copy

Copied

{
  "id": "PIwWisLuZNwPBoLbCgQVTCoY",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "fingerprint": "FPRmYp7ejhA3yDjSor4A5Ji2D",
  "tags": {
    "card_name": "Business Card"
  },
  "expiration_month": 12,
  "expiration_year": 2029,
  "bin": "400000",
  "last_four": "9979",
  "brand": "VISA",
  "card_type": "UNKNOWN",
  "name": "Amy White",
  "address": {
    "line1": "900 Metro Center Blv",
    "line2": null,
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94404",
    "country": "USA"
  },
  "address_verification": "NO_MATCH",
  "security_code_verification": "UNMATCHED",
  "created_at": "2022-08-15T23:13:06.13Z",
  "updated_at": "2022-08-15T23:13:06.88Z",
  "instrument_type": "PAYMENT_CARD",
  "type": "PAYMENT_CARD",
  "currency": "USD",
  "identity": "IDgWxBhfGYLLdkhxx2ddYf9K",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwWisLuZNwPBoLbCgQVTCoY"
    },
    "authorizations": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwWisLuZNwPBoLbCgQVTCoY/authorizations"
    },
    "transfers": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwWisLuZNwPBoLbCgQVTCoY/transfers"
    },
    "verifications": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwWisLuZNwPBoLbCgQVTCoY/verifications"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K"
    },
    "updates": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwWisLuZNwPBoLbCgQVTCoY/updates"
    }
  }
}

Step 3: Make the Payment

Once you have a Payment Instrument that represents the buyers tokenized payment data, you can make the payment and charge the buyer's Payment Instrument.

There are two payment flows in Finix:

Sale: A one step transaction that immediately charges the payment instrument.
- This is done by creating a Transfer
Authorization and Capture: A two step transaction that is only available for cards.
- This is done by creating an Authorization, then capturing the authorized funds by creating a Transfer.
- See Creating and Capturing an Authorization for more details.

The Transfer is the core of our payments flow. This example details charging a Payment Instrument for a one-time sale. To make a payment, create a transfer:

Use the id of the buyer's Payment Instrument as the source.
Use the id of an APPROVED Merchant .
Include a fraud_session_id.

Fraud Detection

Every integration with Finix must include Fraud Detection. Reviewing transactions for fraud helps stop any potential bad actors. For more information, see Fraud Detection.

Copy

Copied

curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
      "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
      "currency": "USD",
      "amount": 662154,
      "source": "PIe2YvpcjvoVJ6PzoRPBK137",
      "fraud_session_id": "test_fraud"
    }'

A successful response returns 201, the newly created Transfer, and a SUCCEEDED response.

Copy

Copied

{
  "id" : "TR29av3LN1TAGPbXscsup1tt",
  "amount" : 662154,
  "tags" : { },
  "state" : "SUCCEEDED",
  "trace_id" : "34f40e87-2599-414b-874b-f472790ff521",
  "currency" : "USD",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "source" : "PIe2YvpcjvoVJ6PzoRPBK137",
  "destination" : null,
  "ready_to_settle_at" : null,
  "externally_funded" : "UNKNOWN",
  "fee" : 0,
  "statement_descriptor" : "FNX*FINIX FLOWERS",
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2022-08-25T20:39:37.59Z",
  "updated_at" : "2022-08-25T20:39:38.17Z",
  "idempotency_id" : null,
  "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
  "merchant_identity" : "IDuqZpDw28f2KK6YuDk4jNLg",
  "subtype" : "API",
  "failure_code" : null,
  "failure_message" : null,
  "additional_buyer_charges" : null,
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt/payment_instruments"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
    }
  }
}

Though the Transfer is SUCCEEDED, the funds will be paid out after a short delay.

The approval of the payment will also generate the fees you collect.

Most sandboxes are configured to instantly approve Transfers. But some may be configured for asynchronous approval flows, in which case, the Transfer returns as PENDING. Additionally, some Transfers won't be approved (e.g. a buyer's card getting declined) so you'll need to handle these declines and failures.

Transfer States

While most Transfers are immediately approved, you'll need to handle the following states:

State	Description
PENDING	The `Transfer` is still processing. It will resolve to another state. If a `Transfer` stays PENDING for an extended period of time, reach out to Support.
SUCCEEDED	The Transfer was successful, and the funds will soon be available in a Payout. The `ready_to_settle_at` field indicates when the `Transfer` will be include (or batched) into a `Settlement`.
FAILED	The Payment was declined. Refer to the `failure_code` and `failure_message` for details on why the transaction was declined.
CANCELED	There was an issue with the processor, please reach out to the Finix Support team.
UNKNOWN	A connection or timeout issue occurred while the `Transfer` got created or updated. Reattempt the `Transfer`.

Additional features

Finix supports additional features to enhance your payments experience.

Enable Buyer Charges to include an additional fee like a convenience or service fee.
Include an Idempotency ID to prevent duplicate transfers.
You can lower interchange costs by:
- Enabling Level 2/3 processing
- Processing 3D Secure transaction

After the Payment

There are other steps after the payment that you must support:

Next Steps

Collecting Payouts

Learn how to receive the the funds from payments.

Refunding Payments

Process refunds or reversals.

Manage Disputes

Learn how to manage the dispute lifecycle.