Making a Payment

After you've onboarded a merchant, you're ready to process payments with Finix. You can use Finix to process several types of payments including, but not limited to:

This guide provides an overview of how to process an online payment; specifically, an online card sale. While each payment method has it's nuances, most concepts and actions remain the same.

Here are the essential steps to making payment:

  1. Creating an Identity for your Buyer
  2. Collecting and tokenizing payment information
  3. Creating a Payment Instrument
  4. Creating a Sale (or transfer when using the Finix API)
  5. Handling the post-payments experience (processing refunds, managing disputes, etc.)

Before you begin

Before you can process payments for a seller, you need the following:

Creating 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.

Create an Identity for your buyer.

  • Do not provide the business_type field. Including a value for business_type configures the Identity to get processed as a merchant.
  • When creating an Identity for a buyer, all fields are optional .
Copy
Copied
curl https://finix.sandbox-payments-api.com/identities \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -H 'Content-Type: application/hal+json' \
  -X POST \
  -d '{
    "entity": {
      "phone": "7145677613",
      "first_name": "John",
      "last_name": "Smith",
      "email": "user@example.org",
      "personal_address": {
        "city": "San Mateo",
        "country": "USA",
        "region": "CA",
        "line2": "Apartment 7",
        "line1": "741 Douglass St",
        "postal_code": "94114"
      },
      "tags": {
        "key": "value"
      }
    }
  }'

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

Copy
Copied
{
  "id" : "IDp7kvNNgcVFx2JeNzuMb41J",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "entity" : {
    "title" : null,
    "first_name" : "John",
    "last_name" : "Smith",
    "email" : "user@example.org",
    "business_name" : null,
    "business_type" : null,
    "doing_business_as" : null,
    "phone" : "7145677613",
    "business_phone" : null,
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : null,
    "mcc" : null,
    "dob" : null,
    "max_transaction_amount" : 0,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : null,
    "annual_card_volume" : 0,
    "has_accepted_credit_cards_previously" : false,
    "incorporation_date" : null,
    "principal_percentage_ownership" : null,
    "short_business_name" : null,
    "ownership_type" : null,
    "tax_authority" : null,
    "tax_id_provided" : false,
    "business_tax_id_provided" : false,
    "default_statement_descriptor" : null
  },
  "tags" : { },
  "created_at" : "2022-08-26T20:50:25.26Z",
  "updated_at" : "2022-08-26T20:50:25.26Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDp7kvNNgcVFx2JeNzuMb41J"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDp7kvNNgcVFx2JeNzuMb41J/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDp7kvNNgcVFx2JeNzuMb41J/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDp7kvNNgcVFx2JeNzuMb41J/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDp7kvNNgcVFx2JeNzuMb41J/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDp7kvNNgcVFx2JeNzuMb41J/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDp7kvNNgcVFx2JeNzuMb41J/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDp7kvNNgcVFx2JeNzuMb41J/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDp7kvNNgcVFx2JeNzuMb41J/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    }
  }
}

Collecting Payment Information

With the buyer's Identity created, the next step is collecting the payment details of the buyer.

Use Finix's hosted fields to collect the buyer's card payment data. When buyers enter their information into the hosted fields, Finix tokenizes the payment data and returns a token which you'll use to create a Payment Instrument.

Creating a Payment Instrument

A Payment Instrument represents the payment method details of a buyer. A buyer can have multiple payment instruments associated with their Identity. You can use Finix's system to safely store all of the payment instruments of your buyer.

To save the card payment data that was collected with the hosted field, create a Payment Instrument:

  • Provide the token that was generated.
  • Provide the Identity that was created for the buyer.
CVV and AVS checks

You can 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 \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -H 'Content-Type: application/hal+json' \
  -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"
    }
  }
}

To collect and process payment data in your own PCI compliant cardholder data environment (CDE), see Handling Raw Card Data.

Make the Payment

Once you have a Payment Instrument that represents the buyers tokenized payment data, you can make the payment.

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.

The transfer is the core of our payments flow.

This example uses the sale flow. To make a payment, create a transfer:

  • Use the id of the buyer's payment_instrument as the source .
  • Use the id of the seller's APPROVED merchant .
  • Include a fraud_session_id .
Fraud Detection

Reviewing transactions for fraud helps stop any potentially fraudulent transactions performed by bad actors. For more information, see Fraud Detection.

Copy
Copied
curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/vnd.json+api" \
    -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 an APPROVED response.

Most sandboxes are configured to for instant approval. But some may be configured for asynchronous approval flows, in which case, the transfer returns PENDING.

Copy
Copied
{
  "id" : "TR29av3LN1TAGPbXscsup1tt",
  "amount" : 662154,
  "tags" : { },
  "state" : "APPROVED",
  "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*DUNDER MIFFLIN",
  "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_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 APPROVED, the funds will be paid out to your seller after a short delay.

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

While most transfers are approved, some will be declined or pending and you will need to handle these failure states.

Transfer States and Failures

While most transfer are immediately approved, you need to be able to handle all potential states:

  • PENDING : The transfer is still processing. It will resolve to another state. If a transfer stays in PENDING for an extended period of time, reach out to Support.
  • SUCCEEDED : The Transfer was successful, and the funds will soon be available for Payout . The ready_to_settle_at field indicates when the transfer will be included and 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 support.
  • UNKNOWN : A connection or timeout issue occurred while the transfer got created or updated. Reattempt the transfer .

After the Payment

The funds from the payment are not immediately available. Instead, the ready_to_settle_at field on the transfer will be updated to indicate when it will be batched into a Settlement and payed out.

Though the payment has been completed and paid out, there are still other important aspects of processing payments that you must support:

Additional features

When making a payment, there are other features or functionalities you may be relevant to your needs: