You can use Finix to process several types of payments including:
- Online payments (also called ecommerce)
- In-Person Payments
- Apple Pay and Google Pay
- ACH (eCheck)
While each payment method has it's nuances, many concepts and actions remain the same. 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 - Collect and tokenize payment details
- 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 for a seller, you need the following:
- An API Key
- The seller needs to complete Onboarding.
- When a seller completes Onboarding they'll have an approved
Merchant
. You'll use theMerchant#id
to initiate the payment.
- When a seller completes Onboarding they'll have an approved
Creating an Identity for your Buyer
The first step to process a card payment is to create anIdentity
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 forbusiness_type
configures theIdentity
to get processed as a seller.
curl https://finix.sandbox-payments-api.com/identities \
-H 'Content-Type: application/vnd.json+api' \
-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"
}
}'
Identity
for the buyer.{
"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"
}
}
}
Collecting Payment Details
With the buyer'sIdentity
created, the next step is collecting the payment details of the buyer.Use Finix Hosted Fields to collect the buyer's card details. 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
APayment 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 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.
curl https://finix.sandbox-payments-api.com/payment_instruments \
-H 'Content-Type: application/vnd.json+api' \
-H 'Finix-Version:2022-02-01' \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
-X POST \
-d '{
"token": "TKiMxe323RE5Dq3wLVtG8kSW",
"type": "TOKEN",
"identity": "IDpYDM7J9n57q849o9E9yNrG"
}'
Payment Instrument
.{
"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 aPayment 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
- This is done by creating a
- 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 aTransfer
. - See Creating and Capturing an Authorization for more details.
- This is done by creating an
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'sPayment Instrument
as thesource
. - Use the
id
of the seller's APPROVEDMerchant
. - 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.
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"
}'
Transfer
, and a SUCCEEDED response. {
"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*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"
}
}
}
Transfer
is SUCCEEDED, 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.
Most sandboxes are configured to instantly approvalTransfers
. 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 and Failures
While mostTransfer
are immediately approved, you'll need to handle all potential states:- PENDING: The
Transfer
is still processing. It will resolve to another state. If aTransfer
stays PENDING for an extended period of time, reach out to Support. - SUCCEEDED: The Transfer was successful, and the funds will soon be available for the seller in a Payout. The
ready_to_settle_at
field indicates when theTransfer
will be include (or batched) into aSettlement
. - FAILED: The Payment was declined. Refer to the
failure_code
andfailure_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 theTransfer
.
After the Payment
The funds from the payment are not immediately available. Instead, theTransfer#ready_to_settle_at
field gets updated and details when it'll 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:
- Process refunds or reversals
- Manage Disputes
- Understand the Payment Lifecycle
Additional features
When making a payment, there are other features or functionalities you may be relevant to your needs:
- 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:
Next Steps
Other important aspects of processing payments that you need to support include: