# Online Payments Quickstart This guide explains how to get started with online payments. Finix offers multiple integration options for accepting payments online, including via API or our low-code / no-code solutions. Your buyers can make payments with their cards or bank accounts, which Finix lets you collect and store securely with our tokenization forms / SDKs, as well as our digital wallet and Plaid integrations. In addition, Finix offers many features for customizing your payments flow and managing risk. To learn about in-person payments, read our [In-Person Payments guide](/guides/in-person-payments). ## Making Payments via API Customers that want the most flexibility for their online payments needs can use our APIs to build out their own payments flows. This option works well for customers that want to integrate payment acceptance into their website or app, and have developer resources to build that integration. ### Step 1: Create a Buyer First, create an Identity to represent your buyer. The Identity resource represents both buyers and sellers. If you're a platform managing multiple sellers, see our [Platform Payments guide](/guides/platform-payments) to learn how to onboard sellers. Your buyer's Identity stores their personal data (such as name and email), and helps manage their payments, payment methods, identity verification, and more. Buyer Identity Data All buyer Identity fields are optional. However, Finix recommends including basic information (name, email, address, and phone) to make payment operations easier. #### Request Example API Definition #### Response Example Create Buyer Identity Response { "id": "IDmkDvJfxZWMEK56FDFtbozo", "created_at": "2024-08-09T09:34:36.87Z", "updated_at": "2024-08-09T09:34:36.87Z", "application": "APgPDQrLD52TYvqazjHJJchM", "entity": { "ach_max_transaction_amount": 0, "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": "finix_example@finix.com", "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 }, "identity_roles": [], "tags": { "key": "value" }, "type": "PERSONAL", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" } } } API Definition ### Step 2: Create a Payment Instrument Payment Instruments represent your buyer's payment methods (either cards or bank accounts), from which you can accept payments. Buyers can have multiple Payment Instruments associated with their Identity. Finix offers many different solutions for securely collecting payment method information from your buyers, including our tokenization forms / SDKs, as well as our digital wallet and Plaid integrations. Finix's vault securely encrypts and stores your buyers' Payment Instruments. When you use one of our secure options to tokenize your buyer's card or bank account information, you can use the `token` Finix sends you to create a Payment Instrument. (When you use one of our digital wallet or Plaid integrations, Finix will send you a `third_party_token`). Handling Raw Card Data If you are PCI-compliant and wish to handle raw card data directly, see [Handling Raw Card Data](/guides/online-payments/payment-tokenization/handling-raw-card-data). ```shell Payment Instrument Request 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" }' ``` ```json 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" } } } ``` ### Step 3: Create a Transfer With your buyer's Identity and their Payment Instrument created, you are ready to make the payment. Finix offers two flows: - **Direct Sale**: One-step transaction that charges the Payment Instrument directly. - **Authorization and Capture**: Two-step transaction that creates an Authorization you can capture later Customers use the authorization and capture flow when they want to create a hold on a card, and charge the full amount later. This flow is available for cards only. For more information, see [Auth and Captures](/guides/online-payments/payment-features/auth-and-captures). To make a direct sale, create a Transfer: - Set the `source` to your Buyer's Payment Instrument ID - Set the `merchant` to an `APPROVED` Merchant account - Include a `fraud_session_id` to reduce fraud risk Fraud Session ID Every integration with Finix must include the `fraud_session_id` to reduce fraud risk. For more information, see [Fraud Detection](/guides/online-payments/fraud-and-risk/fraud-detection). ```shell Transfer Request 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" }' ``` ```json Transfer { "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" } } } ``` #### Transfer States Use the Transfer's `state` to understand where it is in the payment lifecycle. While you should expect most Transfers to succeed, some may fail (for example, when the buyer's bank declines the transaction). Note that most Sandboxes are configured for instant Transfer approval, but can be configured for asynchronous approval where Transfers return as pending. | State | Description | | --- | --- | | `PENDING` | The Transfer is still processing and will resolve to another state. If the Transfer stays `PENDING` for an extended period of time, reach out to [Finix Support](mailto:support@finix.com). | | `SUCCEEDED` | The Transfer was successful, and the funds will soon be available in a [Payout](/guides/after-the-payment/payouts). The `ready_to_settle_at` field indicates when the Transfer will be included / batched into a Settlement. | | `FAILED` | The Payment was declined. Refer to the `failure_code` and `failure_message` to learn [why the transaction was declined](/additional-resources/developers/implementation-and-testing/error-codes/#transfer-and-authorization-errors). | | `CANCELED` | There was an issue with the processor, please reach out to [Finix Support](mailto:support@finix.com). | | `UNKNOWN` | A connection or timeout issue occurred while creating the Transfer. Reattempt the Transfer. | ## Low-Code / No-Code Solutions Businesses that want to get started accepting payments without building a custom integration can use Finix's low-code / no-code online payment solutions. Read the guides below to learn how to get started. Checkout Pages Build custom low-code Checkout Pages. Payment Links Create and send Payment Links to help buyers easily complete transactions. Virtual Terminal Create and process payments with Finix's Virtual Terminal. ## Payment Methods Finix lets you accept payments from both cards and bank accounts, which Finix lets you collect and store securely with out tokenization forms / SDKs, as well as our digital wallet and Plaid integrations. You can customize which payment methods you want to support depending on which integration paths you take. Tokenization Securely collect payment details for your buyers and sellers. Digital Wallets Integrate Apple Pay™ and Google Pay™. Plaid Add bank accounts to Finix with Plaid. ## Payment Features Finix supports a variety of different payment features to let you customize your payments integration: - [Use authorizations and captures](/guides/online-payments/payment-features/auth-and-captures) to create temporary holds before capturing full amounts later. - [Enable buyer charges](/guides/online-payments/payment-features/buyer-charges) to collect additional fees, such as convenience or service fees. - [Collect tips](/guides/online-payments/payment-features/collecting-tips) from buyers. - [Accept FSA and HSA cards](/guides/online-payments/payment-features/fsa-and-hsa-cards) for health-related payments. - [Enable Level 2 / Level 3](/guides/online-payments/payment-features/level-2-level-3-processing) processing to reduce interchange rates. - [Send receipts](/guides/online-payments/payment-features/sending-receipts) to your buyers. ## Fraud and Risk Learn about the variety of tools that Finix offers to manage fraud and risk: - [Use 3D Secure Authentication](/guides/online-payments/fraud-and-risk/3d-secure-authentication) for an extra security layer when accepting card payments. - [Disable payment instruments](/guides/online-payments/fraud-and-risk/disabling-instruments) you know to be fraudulent. - [Integrate into Finix's fraud detection solution](/guides/online-payments/fraud-and-risk/fraud-detection) to mitigate chargeback risk. - [Handle declined payments](/guides/online-payments/fraud-and-risk/handling-declined-payments) to learn what to do when payments fail. - [Enable risk rules and card checks](/guides/online-payments/fraud-and-risk/risk-rules-card-checks) to verify card details before accepting payments. ## After the Payment After accepting an online payment, there are some final steps: - [Learn how you get paid from the payments you've processed](/guides/after-the-payment/payouts). - [Learn how to refund payments](/guides/after-the-payment/refunds). - [Learn what to do when a buyer reports a payment to their issuing bank](/guides/after-the-payment/disputes).