# Finix Docs > Explore our documentation, guides, and APIs to start building your world-class payments experience with Finix. This file is the full text of every page listed in https://docs.finix.com/llms.txt, in the same order. Each page starts with its title and a Source line giving the page URL; append `.md` to any page URL for that page alone. --- # Developer Quickstart Source: https://docs.finix.com/guides/getting-started/developer-quickstart Finix supports both Online Payments and In-Person Payments. This quickstart provides details on how your business can accept a payment with Finix. ## Online Payments Online Payments Hero Accept online payments with Finix's complete solution, whether you're building a custom checkout experience or need a quick payment solution. - **Flexible integrations:** Build custom payment flows with our APIs, or get started with our low-code / no-code solutions - **Multiple payment methods:** Accept credit cards, debit cards, bank accounts, digital wallets, and more. - **Security first:** Protect sensitive payment data with our PCI-compliant tokenization system. To see an example of our Tokenization Forms and Hosted Checkout, you can visit our [sample store](https://finixsamplestore.com) and related [GitHub Project](https://github.com/finix-payments/accept-a-payment). Tokenization Forms Tokenization Form Example br Our Tokenization Forms allow you to build a custom checkout page you own and control. This option is great if you want maximum customizability. ### Step 1: Create an Identity for your Buyer With your API Key and `Merchant` ID, you can start processing payments. To process a payment, you need to create an [`Identity`](/api/identities/createidentity) that represents your buyer. You won’t need to capture the same amount of information from your buyer. So long as you don’t pass a `identity#business_type` field all the other fields are optional. We recommend at least collecting the buyer’s name and email to help with accounting, reconciliation, and chargebacks. Do not pass the `business_type` field when creating an `Identity` for a buyer. Including `business_type` configures our API to treat the created `Identity` as a seller. Example API Definition A successful response returns the `Identity` you'll use in the next step. Example Identity - Buyer ```json Identity - Buyer { "id": "IDm1QmqySG8YQUth47dj2sV5", "created_at": "2026-09-25T20:05:10.29Z", "updated_at": "2026-09-25T20:05:10.29Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "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_fingerprint": null, "business_tax_id_provided": false, "business_type": null, "default_statement_descriptor": null, "discover_mid": null, "dob": null, "doing_business_as": null, "email": "johnsmithbuyer@gmail.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": "7147148784", "principal_percentage_ownership": null, "short_business_name": null, "tax_authority": null, "tax_id_fingerprint": null, "tax_id_provided": false, "title": null, "url": null }, "identity_roles": [ // [!code highlight] "BUYER" ], "tags": {}, "type": "PERSONAL", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ``` API Definition ### Step 2: Tokenize payment details Now that you have an `Identity` resource representing your buyer, you need to create a [`Payment Instrument`](/api/payment-instruments/createpaymentinstrument) for your buyer to represent the credit card you’ll be debiting (i.e. charging). You’ll also need to include your buyer’s `Identity#id` from the previous request to link the `Payment Instrument` that's created with your buyer's details. 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](/guides/online-payments/payment-tokenization/tokenization-forms) or mobile tokenization (see [Android](/guides/online-payments/payment-tokenization/mobile-tokenization-android) or [iOS](/guides/online-payments/payment-tokenization/mobile-tokenization-ios) tokenization) to accept payment details and remain out of PCI scope. Example API Definition A successful response returns the newly created `Payment Instrument` you'll use to process the buyer's payment. Example Payment Instrument - Card ```json Payment Instrument - Card { "id": "PImZV8WukUEgB8iFqoSouLt1", "created_at": "2026-09-25T20:05:27.37Z", "updated_at": "2026-09-25T20:05:27.37Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "PAYMENT_CARD", // [!code highlight] "account_updater_enabled": false, "address": { "line1": "900 Metro Center Blv", "line2": null, "city": "San Francisco", "region": "CA", "postal_code": "94404", "country": "USA" }, "address_verification": "UNKNOWN", "bin": "520082", "brand": "MASTERCARD", "card_type": "DEBIT", "expiration_month": 12, "expiration_year": 2029, "issuer_country": "NON_USA", "last_four": "8210", "name": "John Doe", "network_token_enabled": false, "network_token_state": "NOT_ENABLED", "security_code_verification": "UNKNOWN", "tags": {}, "third_party": null, "third_party_token": null, "type": "PAYMENT_CARD", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" }, "updates": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/updates" } } } ``` API Definition ### Step 3: Make a payment At this point, we've tokenized a buyer's payment details. We can now create a payment. To make a payment, you need to create a [`Transfer`](/api/transfers/createtransfer). Include the buyer’s `Payment Instrument#id` as the `source` field and the your `Merchant#id` in the `merchant` field. #### Finding your Merchant ID - If you are a Direct Merchant, you will be provided a `merchant_id` to use. You can find this in your Developer section on the Dashboard. If you need help finding this ID, please contact our support team or your Finix point of contact. - If you are a Platform, you will need to [onboard each of your sellers](/guides/platform-payments/onboarding-sellers/). Each seller will be provided a unique `merchant_id`. #### Creating a payment Example API Definition A successful request returns a `201 Created` status, with the response body containing a `Transfer` resource that includes: - `type` - either `DEBIT` or `CREDIT`, depending on the payment instrument - `state` - set to `SUCCEEDED` Example Transfer - USA ```json Transfer - USA { "id": "TRgQBFEUahEyLZ6zvu3hrqNJ", "created_at": "2026-09-25T20:05:48.72Z", "updated_at": "2026-09-25T20:05:48.72Z", "3d_secure_session": null, "additional_buyer_charges": { "convenience_amount": 150, "surcharge_amount": 0, "rent_surcharge_amount": 0 }, "additional_healthcare_data": null, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": { "customer_reference_number": "321xyz", "customs_duty_amount": 10, "destination_country_code": null, "destination_postal_code": null, "discount_amount": 100, "invoice_reference_number": null, "order_date": null, "sales_tax": null, "sales_tax_finix_generated": 200, "ship_from_postal_code": null, "shipping_amount": 100, "tax_exempt": false, "item_data": [ { "cost_per_unit": 500, "item_description": "printing paper", "item_discount_amount": 100, "merchant_product_code": "1149611", "quantity": 1, "amount_excluding_sales_tax": 400, "amount_including_sales_tax": 500, "unit_of_measure": "BX", "commodity_code": "175-62-20", "sales_tax_amount": 100, "sales_tax_rate": 0.25 }, { "cost_per_unit": 500, "item_description": "printing ink", "item_discount_amount": 0, "merchant_product_code": "2149612", "quantity": 1, "amount_excluding_sales_tax": 400, "amount_including_sales_tax": 500, "unit_of_measure": "CTN", "commodity_code": "207-72-54", "sales_tax_amount": 100, "sales_tax_rate": 0.25 } ] }, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 1000, "amount_requested": 1000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "USD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FP9F2KEnY4wt1XjFvhLBJVjb", "idempotency_id": null, "ip_address_details": null, "merchant": "MUe17jKSrfPetoeiJQzzjmA2", "merchant_identity": "ID6NvZy42D7PChZL8GKKD87F", "messages": [], "network_details": { "brand": "VISA", "authorization_code": "824912", "acquirer_reference_number": null }, "operation_key": "CARD_NOT_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "processed_at": "2026-09-25T20:05:49.20Z", "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": "MATCHED", "source": "PI6iQcTtJNCS8GZAVKYi5Ueb", "split_transfers": [ "split_transfer_gQSpMGjxZRQ452uTarEZZ4", "split_transfer_gQSr5EaDoRwr4A7E8EBPzH" ], "state": "SUCCEEDED", // [!code highlight] "statement_descriptor": "FLX*FLEX GYM", "subtype": "API", "supplemental_fee": null, "tags": { "tip": "50" }, "third_party_details": null, "tip_amount": null, "trace_id": "2c32aa3f-cd7a-4b44-9b53-56af75957d85", "type": "DEBIT", // [!code highlight] "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRgQBFEUahEyLZ6zvu3hrqNJ" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6NvZy42D7PChZL8GKKD87F" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRgQBFEUahEyLZ6zvu3hrqNJ/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRgQBFEUahEyLZ6zvu3hrqNJ/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRgQBFEUahEyLZ6zvu3hrqNJ" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRgQBFEUahEyLZ6zvu3hrqNJ/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6iQcTtJNCS8GZAVKYi5Ueb" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FP9F2KEnY4wt1XjFvhLBJVjb" } } } ``` API Definition The above response means the buyer was successfully charged and the funds will soon [be ready to pay out](/guides/platform-payments/seller-payouts). Finix creates a `Settlement` resource which maps transactions and fees to calculate your payout. Read [Payouts](/guides/platform-payments/seller-payouts) for more details on how to manage and reconcile payouts. #### Authorizations Alternatively, you can create an `Authorization` to capture the same `Authorization` in two API calls. This is useful when you want to verify the payment details and capture a specific amount at a later date. For more details, see [Creating and Capturing an Authorization](/guides/online-payments/payment-features/auth-and-captures). #### Idempotent requests We recommend including an `idempotency_id` to ensure that each request is processed only once. For more information, see [Idempotent Requests](/additional-resources/developers/authentication-and-api-basics/idempotent-request). Subscriptions Finix allows you to sign up and manage subscriptions for your buyers or customers. For a comprehensive guide on Subscriptions, see [Subscriptions](/guides/subscriptions/). ### Create a basic Subscription To create a Subscription, include: - The ID of the `Merchant` that the `Subscription` will be `linked_to` - The `amount` and `currency` of the `Subscription` - The `subscription_details` - The `buyer_details` including both the `identity_id` and `instrument_id` At this time, only APPROVED Merchants with one of the following processors can create subscriptions: - `DUMMY_V1` - `FINIX_V1` For detailed API information, please see our [Subscriptions API Reference](/api/subscriptions/createsubscription). The following example shows how to create a basic subscription: Example API Definition Example Subscription ```json Subscription { "id": "subscription_cEpKYsVx13tE7utwrEwSz", "created_at": "2026-09-25T20:05:44.63Z", "updated_at": "2026-09-25T20:05:44.63Z", "amount": 10000, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "billing_cycle_day": 25, "billing_interval": "MONTHLY", "buyer_details": { "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S", "instrument_id": "PImXAVgkKVshKWWHUk4xXbve", "requested_delivery_methods": [], "shipping_address": null }, "canceled_via": null, "currency": "USD", "expires_at": null, "first_charge_at": "2026-09-25T20:05:43.00Z", "has_usage_based_plan": false, "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ", "linked_type": "MERCHANT", "next_billing_date": { "year": 2026, "month": 9, "day": 25 }, "nickname": null, "start_subscription_at": "2026-09-25T20:04:43.651Z", "state": "ACTIVE", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false, "trial_details": null, "discount_phase_details": null, "notification_preferences": { "send_confirmation": false } }, "subscription_link_id": null, "subscription_phase": "EVERGREEN", "subscription_plan_id": null, "tags": {}, "total_billing_intervals": null, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cEpKYsVx13tE7utwrEwSz" } } } ``` API Definition ### Trial period You can create a subscription with a trial period by providing `trial_details` in the request body. For example, to include a trial period that lasts one month set `trial_details.interval_type` to `MONTH` and `trial_details.interval_count` to `1`. After creating a `Subscription`, a `Transfer` will occur after the trial period has elapsed. The `first_charge_at` property in the response determines when the `Transfer` will occur. Example API Definition Example Subscription - Trial Period ```json Subscription - Trial Period { "id": "subscription_cEpKYD3JD1iypyN3Vghiu", "created_at": "2026-09-25T20:05:47.00Z", "updated_at": "2026-09-25T20:05:47.00Z", "amount": 10000, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "billing_cycle_day": 25, "billing_interval": "MONTHLY", "buyer_details": { "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S", "instrument_id": "PImXAVgkKVshKWWHUk4xXbve", "requested_delivery_methods": [], "shipping_address": null }, "canceled_via": null, "currency": "USD", "expires_at": null, "first_charge_at": "2026-10-25T20:05:46.00Z", // [!code highlight] "has_usage_based_plan": false, "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ", "linked_type": "MERCHANT", "next_billing_date": { "year": 2026, "month": 10, "day": 25 }, "nickname": null, "start_subscription_at": "2026-09-25T20:04:46.243Z", "state": "ACTIVE", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false, "trial_details": { "interval_type": "MONTH", "interval_count": 1, "trial_started_at": "2026-09-25T20:04:46.24Z", "trial_expected_start_at": "2026-09-25T20:04:46.24Z", "trial_expected_end_at": "2026-10-26T06:33:52.24Z" }, "discount_phase_details": null, "notification_preferences": { "send_confirmation": false } }, "subscription_link_id": null, "subscription_phase": "TRIAL", // [!code highlight] "subscription_plan_id": null, "tags": {}, "total_billing_intervals": null, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cEpKYD3JD1iypyN3Vghiu" } } } ``` API Definition ### Discount period To apply a discount period, include `discount_phase_details` in the request body. For example, if the full subscription price is $20 per month, and you want to offer a discounted rate of $10 per month for three months, set `discount_phase_details.amount` to `1000` and `discount_phase_details.billing_interval_count` to `3`. After this discount period, the subscriber will be charged the full `amount` of the `Subscription`. Example API Definition Example Subscription - Discount Phase ```json Subscription - Discount Phase { "id": "subscription_cxe8oDnBbKKDGMQQaWZca", "created_at": "2026-02-17T18:38:50.28Z", "updated_at": "2026-02-17T18:38:50.28Z", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "first_charge_at": "2026-02-17T18:38:50.00Z", "next_billing_date": { "year": 2026, "month": 2, "day": 17 }, "amount": 2000, "buyer_details": { "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S", "instrument_id": "PImXAVgkKVshKWWHUk4xXbve", "requested_delivery_methods": [], "shipping_address": null }, "currency": "USD", "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ", "linked_type": "MERCHANT", "nickname": "Finflix Gold Package", "billing_interval": "MONTHLY", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false, "trial_details": null, "discount_phase_details": { "amount": 1000, "billing_interval_count": 3, "discount_phase_started_at": "2026-02-17T18:37:50.01Z", "discount_phase_expected_start_at": "2026-02-17T18:37:50.01Z", "discount_phase_expected_end_at": "2026-05-17T18:37:50.01Z" }, "notification_preferences": { "send_confirmation": false } }, "subscription_phase": "DISCOUNT", // [!code highlight] "state": "ACTIVE", "subscription_plan_id": null, "start_subscription_at": "2026-02-17T18:37:50.010Z", "total_billing_intervals": null, "expires_at": null, "canceled_via": null, "tags": {}, "subscription_link_id": null, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cxe8oDnBbKKDGMQQaWZca" } } } ``` API Definition ### Start date Finix allows you to specify a start date for subscriptions. The `starts_subscription_at` field takes an ISO8601 formatted timestamp to start the subscription. The timestamp must be in the future. Example API Definition Example Subscription - Future Start Date ```json Subscription - Future Start Date { "id": "subscription_cEpKYiFpEsQsgnRhoAP5G", "created_at": "2026-09-25T20:05:42.47Z", "updated_at": "2026-09-25T20:05:42.47Z", "amount": 10000, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "billing_cycle_day": 1, "billing_interval": "MONTHLY", "buyer_details": { "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S", "instrument_id": "PImXAVgkKVshKWWHUk4xXbve", "requested_delivery_methods": [], "shipping_address": null }, "canceled_via": null, "currency": "USD", "expires_at": null, "first_charge_at": "2027-06-01T00:00:00.00Z", // [!code highlight] "has_usage_based_plan": false, "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ", "linked_type": "MERCHANT", "next_billing_date": { "year": 2027, "month": 6, "day": 1 }, "nickname": null, "start_subscription_at": "2027-06-01T00:00:00.000Z", // [!code highlight] "state": "NOT_STARTED", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false, "trial_details": null, "discount_phase_details": null, "notification_preferences": { "send_confirmation": false } }, "subscription_link_id": null, "subscription_phase": "NONE", "subscription_plan_id": null, "tags": {}, "total_billing_intervals": null, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cEpKYiFpEsQsgnRhoAP5G" } } } ``` API Definition ### Fixed length Subscriptions To create fixed-length subscriptions, you can pass `total_billing_intervals` in the request body. The API will return an `expires_at` field to let you know when the `Subscription` will expire. The `subscription_phase` will also return a value of `FIXED`. Example API Definition Example Subscription - Fixed-Length ```json Subscription - Fixed-Length { "id": "subscription_cxe8rTTPCwzUu7p1zmk6t", "created_at": "2026-02-17T18:39:34.38Z", "updated_at": "2026-02-17T18:39:34.38Z", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "first_charge_at": "2026-02-17T18:39:33.00Z", "next_billing_date": { "year": 2026, "month": 2, "day": 17 }, "amount": 19900, "buyer_details": { "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S", "instrument_id": "PImXAVgkKVshKWWHUk4xXbve", "requested_delivery_methods": [], "shipping_address": null }, "currency": "USD", "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ", "linked_type": "MERCHANT", "nickname": null, "billing_interval": "MONTHLY", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false, "trial_details": null, "discount_phase_details": null, "notification_preferences": { "send_confirmation": false } }, "subscription_phase": "FIXED", // [!code highlight] "state": "ACTIVE", "subscription_plan_id": null, "start_subscription_at": "2026-02-17T18:38:33.747Z", "total_billing_intervals": 12, "expires_at": "2027-02-17T18:38:33.747Z", // [!code highlight] "canceled_via": null, "tags": {}, "subscription_link_id": null, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cxe8rTTPCwzUu7p1zmk6t" } } } ``` API Definition Low Code / No Code Customers that want to get started accepting payments right away can use Finix's suite of No-Code / Low-Code solutions. Payment Links Create and send Payment Links to help buyers easily complete transactions. Virtual Terminal Learn how to create and process payments with Finix's Virtual Terminal. Subscriptions You can create a Subscription in the Finix Dashboard without any development work. br ## In-Person Payments In-Person Payments Hero Accept in-person payments with Finix’s flexible, platform-ready solution—built for custom POS flows or turnkey hardware experiences. - **Flexible integrations** - Power your POS with our APIs or launch fast with our Standalone Terminals. - **Modern payment methods** - Accept chip, tap, swipe, mobile wallets, and contactless payments across supported devices. - **Security first:** Protect sensitive payment data with our PCI-compliant tokenization system. To get started with our In-Person Payments, select one of the links below. Select Your Device Learn about the payment terminals available for In-Person Payments integrations. Building your Integration Learn about Finix's POS and mobile in-person payments integrations. Standalone Terminals Learn about Finix's Standalone Terminals. ## Additional resources ### Payment features Finix supports several 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. - [Split Transactions](/guides/online-payments/payment-features/split-transactions) across different approved merchants. - [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. ### Wallet Payments - [Integrate Apple Pay](/guides/online-payments/digital-wallets/apple-pay/) to create a frictionless experience on web or mobile. - [Integrate Google Pay](/guides/online-payments/digital-wallets/google-pay) to let users pay on web or on android device. ### Fraud and risk Learn about the variety of tools that Finix offers to manage fraud and risk: - [Use 3D Secure](/guides/online-payments/fraud-and-risk/3d-secure) 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. - [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/). --- # Sign Up for a Finix Account Source: https://docs.finix.com/guides/getting-started/finix-sign-up Create a Finix account to start building and testing your payments integration in a Sandbox environment. This guide walks you through signing up, choosing the right dashboard for your business, and applying for Live access. ## Step 1: Sign up for a Finix Sandbox Create a Finix account by filling out and submitting the [account creation form](https://dashboard.finix.com/signup). Finix sign-up page with account creation fields ### Choose your dashboard When you sign up for a Finix account, you are prompted to choose a dashboard. Choose the option that best describes your business. Dashboard selection screen with business type options For most businesses, we recommend choosing **Direct Merchant**. If you onboard sellers or process payments on behalf of sellers, we recommend choosing either: - **Software Platforms**. - **Marketplaces**. To decide the best experience for your business, use the following questions. You can always reach out to your Finix point of contact or [Finix support](mailto:support@finix.com) if you have questions about which option works best for you. | Question | Answer | | --- | --- | | Do you onboard sellers and process payments on their behalf? | **No:** Choose [Direct Merchant](https://finix.com/who-we-serve/customers/businesses). **Yes:** Continue to the next question. | | Do your sellers process in-person payments, such as card swipes, Tap to Pay, or EMV chip payments? | **Yes:** Choose [Software Platform](https://finix.com/who-we-serve/customers/software-platforms). **No:** Choose [Marketplace](https://finix.com/who-we-serve/customers/marketplaces). | ### Log in to the dashboard The sandbox account you gain access to is an [`Application`](/additional-resources/developers/resources-and-payment-flows/key-resources#applications) that represents your business in the Finix API. After you gain access to the sandbox, you can log in to your Finix Dashboard and: - [Add new team members](/guides/managing-operations/managing-team-members/) from **Company** → **Team**. - [Create API keys](/additional-resources/developers/authentication-and-api-basics/api-keys) in the **Developer** tab and share them with your developers so they can start [building their integration](/guides/getting-started/developer-quickstart). - Create new roles. See [Roles and Permissions](/guides/managing-operations/managing-team-members/roles-permissions) for a breakdown of the different dashboard roles and permissions. Once you have a live account, you see an account selection screen where you can choose to enter a sandbox or live account. ## Step 2: Build your Finix integration With access to a sandbox account, you can begin building your integration with Finix. Once you decide on the dashboard to use, get started building your payment experience by reviewing the resources that fit your account type. | Finix account | Online payments | In-person payments | Onboard sellers | Manage sellers | Resources | | --- | --- | --- | --- | --- | --- | | [Finix for Businesses](https://finix.com/who-we-serve/customers/businesses) | X | X | | | [Developer Quickstart](/guides/getting-started/developer-quickstart), [Integration Checklist](/additional-resources/developers/implementation-and-testing/integration-checklist) | | [Finix for Software Platforms](https://finix.com/who-we-serve/customers/software-platforms) | X | X | X | X | [Platform Quickstart](/guides/platform-payments/platform-quickstart), [Platform Checklist](/guides/platform-payments/platform-checklist) | | [Finix for Marketplaces](https://finix.com/who-we-serve/customers/marketplaces) | X | | X | X | [Platform Quickstart](/guides/platform-payments/platform-quickstart), [Platform Checklist](/guides/platform-payments/platform-checklist) | Apply for Live access early We recommend applying for a live account before completing your integration. ### Sandbox and Live environments Finix maintains two separate systems, or *environments*: - A **Sandbox environment** where you build and test your integration with Finix. - A **Live environment** where you process live transactions and actual money movements. Nothing in the Sandbox environment affects real money, so you can experiment freely without moving funds. Once you are ready, you can apply for Live access. When you gain Live access, Finix grants you a Live environment. You keep your sandbox account, so your Sandbox and Live environments stay separate. ## Step 3: Apply for a Live account Before Finix can grant a Live environment, Finix evaluates your business and integration. Access to a Live environment lets you process live transactions and initiate real money movements. If you are interested in a live account, reach out to [the Finix Sales team](https://finix.com/contact-us). ## Next steps Developer Quickstart Start accepting online and in-person payments with the Finix API. Set up your development environment Configure your Sandbox credentials and make your first API request. --- # Getting Started with Finix Source: https://docs.finix.com/guides/getting-started Start accepting payments with Finix in three steps. Getting started hero graphic Finix offers no-code, low-code, and API solutions, so you can start accepting payments the way that fits your business. Sign up, build your integration, and receive your payouts. ## Three steps to process payments ### Step 1: Sign up for a Finix account The first step to processing payments is to sign up for a Finix account. We recommend creating a Sandbox account to test your integration. You can migrate data from payments you processed in the past over to Finix. Sign Up for a Finix Account Learn how to create a Finix Account. ### Step 2: Build your integration Build your integration and process payments from your buyers. Online Payments Accept mobile and web payments with no-code, low-code, or API solutions. In-Person Payments Learn about the payment terminals available for In-Person Payments integrations. Platform Payments Accept payments on your platform or marketplace. Sample Accept a Payment App Sample e-commerce application that shows how to use Finix's checkout forms and how to take a payment with Token Forms. ### Step 3: Receive Payouts Collect the payouts for the payments you've processed. Receive Payouts Learn how you get paid from the payments you've processed. --- # Set Up Development Environment Source: https://docs.finix.com/guides/getting-started/set-up-developer-environment Learn how to set up your development environment to make authenticated requests to the Finix API. After setup, you can send test API requests from your Sandbox environment. ## Overview This guide walks you through the credentials and configuration you need to call the Finix API, including HTTP Basic Authentication, environment base URLs, and how to find your `Merchant` ID. ## Before you begin Get started by [creating a sandbox account](https://finix.payments-dashboard.com/signup) with Finix. Before you can process payments using the Finix API, you need: - [An API key](/additional-resources/developers/authentication-and-api-basics/api-keys). - Your business's `Merchant` ID. ## Finix API overview The Finix API is resource oriented and relies on common REST principles. The Finix API uses JSON-encoded requests and responses. Finix provides separate Sandbox and Live accounts, along with the corresponding API credentials to access the Finix API. ## Authentication To communicate with the Finix API, you must authenticate your requests via HTTP Basic Authentication with a `username:password` combination, which you can get from your Finix Dashboard. If you do not have a Dashboard yet, you can test the Finix API with the Sandbox credentials below. | Parameter | Value | | --- | --- | | Sandbox Username | `USsRhsHYZGBPnQw8CByJyEQW` | | Sandbox Password | `8a14c2f9-d94b-4c72-8f5c-a62908e5b30e` | ```shell Request Format curl "https://finix.sandbox-payments-api.com/" \ -H "Content-Type: application/json" \ -H "Finix-Version: 2022-02-01" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e ``` ## Environments Finix provides two environments with distinct base URLs to make API requests. 1. A Sandbox environment for developing and testing your integration. 2. A Live environment for processing payments. These environments are entirely separate and do not share API Credentials. | Environment | Endpoint URL | | --- | --- | | Sandbox | `https://finix.sandbox-payments-api.com` | | Live | `https://finix.live-payments-api.com` | Live access To get access to the Live environment, reach out to your Finix point of contact. ## Supported countries Finix supports entities in the following countries: - United States - Canada ## Create an API key To create an API key from the dashboard, log in and click **Developer** → **Create API Key**. Save the username and password that get returned. You cannot access the credentials again after closing the window. As you use the credentials in your Finix API requests, that activity shows up in the Finix Dashboard. ## Find your Merchant ID Click **Developer** to find your business's `Merchant` ID under **Finix Processing Details**. Use the `Application` and `Merchant` IDs along with the API key to process payments in your integration. If you need additional help finding your `Merchant` ID, reach out to the Finix support team at [support@finix.com](mailto:support@finix.com). ## Next steps Developer Quickstart Create an Identity, tokenize payment details, and make your first payment. API Keys Learn how to create and manage the API keys that authenticate your requests. --- # Support at Finix Source: https://docs.finix.com/guides/getting-started/support-at-finix Get technical help, API answers, and payment issue resolution from the Finix support team. ## Overview The Finix support team is made up of technical engineers, product experts, payment experts, problem solvers, and customer advocates who care about your experience and business. This guide explains how to reach support, what the team can help with, and when to contact your Finix point of contact instead. ## Contact Finix support Email [support@finix.com](mailto:support@finix.com) for technical help and general support. To help the team resolve your issue quickly: 1. Add a clear description of the issue to the email's subject line. 2. Include as many details as possible, such as links, screenshots, videos, and code snippets. ### Request a callback Finix does not offer phone support. If you prefer to speak over the phone, include your phone number and the times that work best for you in your email to [support@finix.com](mailto:support@finix.com). The team calls you back during your availability. ## What Finix support can help with The Finix support team answers questions related to Finix products and services. If you are unsure about something related to Finix, reach out and the team responds with assistance. For business-related inquiries, such as questions about your contract, contact your Finix point of contact or Customer Delivery Manager. Finix support does not: - Share sensitive financial and customer information. - Support inquiries outside of Finix products and services. ## Next steps Sign up for a Finix account Create a sandbox account and choose the dashboard that fits your business. Developer Quickstart Start accepting online and in-person payments with the Finix API. --- # Online Payments Source: https://docs.finix.com/guides/online-payments Accept card and bank payments on your website and in your app. Online Payments Hero Accept online payments with Finix's complete solution, whether you're building a custom checkout experience or need a quick payment solution. - **Flexible integrations:** Build custom payment flows with our APIs, or get started with our low-code / no-code solutions. - **Multiple payment methods:** Accept credit cards, debit cards, bank accounts, digital wallets, and more. - **Security first:** Protect sensitive payment data with our PCI-compliant tokenization system. ## Choose your integration Finix offers multiple ways to accept payments online. Find the option that fits your use case. ### No-Code Create and manage everything directly from the Finix Dashboard — no development required. Payment Links Share a link with buyers and let them complete payment online — no integration required. Virtual Terminal Manually enter card details and process payments directly from the Finix Dashboard. Invoices Request payment from buyers with itemized invoices that support partial payments. ### Custom integration Build a fully branded checkout experience using Finix's SDKs and APIs. Tokenization Forms Embed a PCI-compliant payment form in your site or app using Finix's Web, iOS, or Android SDKs. Direct API Integration Build a fully custom payment flow using Finix's API. Best for teams with dedicated developer resources. ### Recurring Payments Automatically charge buyers on a recurring schedule. Subscriptions Set up recurring charges for memberships, services, or any fixed-amount billing cycle. ## Learn more Bank Payments Learn how to accept payments directly from buyer bank accounts. Digital Wallets Learn how to integrate Apple Pay™ and Google Pay™ with Finix. Fraud and Risk Learn how to manage fraud and risk when processing payments. Low-Code / No-Code Learn how to start accepting payments right away with Finix's Low-Code / No-Code solutions. Payment Features Learn about the different features Finix has available to help you process payments. Payment Tokenization Learn how to securely collect payment details for your buyers and sellers. --- # ACH Direct Debits Source: https://docs.finix.com/guides/online-payments/bank-payments/ach-direct-debits Sellers can accept payments from buyers' US-based bank accounts. Often, these payments are referred to as "ACH payments" or "ACH Direct Debits". ACH Direct Debits are an alternative to credit and debit card payments. ACH Direct Debits are processed through the Automated Clearing House (ACH) payments system, operated by the National Automated Clearinghouse Association (Nacha). In this guide, you can learn how to accept payments from US-based bank accounts. ## Overview ACH Return Risk ACH returns can lead to losses. We recommend taking ACH payments from buyers whom you have a known or prior established relationship with. Unlike card payments, ACH Direct Debits are not real-time. It can take between 4 and 10 business days to fully authorize the transaction with the buyer's bank and learn whether it failed or succeeded. Buyers can dispute the transaction up to 60 days after the initial payment date. Often, businesses mitigate risk or losses from ACH Return risk by: - Ensuring they are dealing with buyers whom they have a prior established relationship. - Implementing a hold time before shipping or providing a good or service. Finix requires the following details from buyers to process ACH Direct Debits: | Detail | Description | | --- | --- | | Bank Code | The routing number of the buyer's bank account | | Account Number | The account number of the buyer's bank account | | Buyer Name | The buyer's name | You can collect this bank account information using [Tokenization Forms or SDKs](/guides/online-payments/payment-tokenization), as well as [our Plaid integration](/guides/online-payments/bank-payments/plaid-integration). Bank accounts must also be [verified](#bank-account-verification) before they can be debited. ### Bank account verification Bank accounts must be verified before they can be used for ACH Direct Debits. Verification confirms the buyer owns the bank account, which protects you from fraud and reduces ACH returns. When microdeposit verification is required, new bank account Payment Instruments are created disabled and cannot be used for ACH Direct Debits until the buyer completes verification. For more information, see [Microdeposit Verification](/guides/online-payments/bank-payments/microdeposit-verification). Verification is separate from the [bank account validation check](#bank-account-validation) below, which validates that the account exists and accepts ACH debits. ### ACH direct debit flow ACH Direct Debits start as `PENDING`, and move to either `SUCCEEDED` or `FAILED` as the payment processes. ACH States | Transfer State | Description | | --- | --- | | `PENDING` | Finix is processing the ACH Direct Debit. | | `SUCCEEDED` | Finix has accepted the ACH Direct Debit. The buyer's bank may or may not have accepted the payment yet. | | `FAILED` | Finix did not accept the ACH Direct Debit. | Successful ACH Direct Debits `SUCCEEDED` means that Finix submitted the ACH direct debit details to the ACH networks. It can take 4-10 business days for the buyer's bank to process and confirm the debit was successful. ### ACH direct debit timing ACH Direct Debits take longer than credit card payments to move and settle funds. To account for this, Finix creates an "ACH Settlement Delay" to accommodate any ACH Returns that may occur. By default, the ACH Settlement Delay holds ACH Direct Debits for 5 days before Finix batches them into [payout Settlements](/guides/after-the-payment/payouts). ACH Timing Sellers may want ACH Direct Debits to appear in settlements faster or slower, depending on their business needs. For example, the ACH Settlement Delay can be: - Decreased, so ACH Direct Debits appear in `Settlements` faster. This can result in ACH Returns appearing after paying out an ACH Direct Debit. - Increased, so sellers have more certainty before paying out ACH Direct Debits. This helps make sure payouts to sellers always include ACH Returns. To customize this delay, reach out to your Finix point of contact or email the [Finix Support team](mailto:support@finix.com). ### Bank account validation In compliance with Nacha's bank account validation rule, Finix validates bank accounts before processing ACH payments. Finix validates the bank account the first time it's used, as well as after any changes are made. The Transfer's `bank_account_validation_check` field explains the results of this check. | Bank Account Validation Check | Description | | --- | --- | | `NOT_ATTEMPTED` | Default value for new bank accounts that haven't been validated yet. | | `VALID` | Bank account was found and confirmed to accept ACH Direct Debits. | | `INVALID` | Bank account couldn't be found or validated. A `Transfer` created with a bank account marked `INVALID` will fail. Please contact the account holder to confirm details or request a different payment method. | | `INCONCLUSIVE` | Bank account couldn't be found and validation was `INCONCLUSIVE`. Bank accounts marked as inconclusive can still be used to create an ACH `Transfer`. | ### Payment Authorization language Before processing any ACH Direct Debit payments, the buyer must agree to the following statement: > *By clicking submit, you authorize us to initiate an automated clearing house (ACH) one-time debit in your name to your bank account indicated above. The amount of this transaction as noted above will be presented to your financial institution by the next business day. You further agree that once you click submit you may not revoke this authorization or cancel this payment.* We recommend presenting this language in your checkout flow right before the buyer clicks the **Submit** button and triggers the creation of the payment. ### Payment confirmation language After the payment is submitted, present a confirmation screen and/or email a confirmation to the buyer with the following language: > *Thank you for your payment in the amount of $xx.xx. Please print this authorization for your records.* *You have authorized us to initiate an automated clearing house (ACH) one-time debit in your name to your bank account. This transaction will be presented to your financial institution by the next business day. You further agree that you may not revoke this authorization or cancel this payment.* ## Creating ACH direct debits To create an ACH Direct Debit, simply create an Identity, Payment Instrument, and Transfer. ### 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. Example API Definition Example Identity - Buyer ```json Identity - Buyer { "id": "IDm1QmqySG8YQUth47dj2sV5", "created_at": "2026-09-25T20:05:10.29Z", "updated_at": "2026-09-25T20:05:10.29Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "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_fingerprint": null, "business_tax_id_provided": false, "business_type": null, "default_statement_descriptor": null, "discover_mid": null, "dob": null, "doing_business_as": null, "email": "johnsmithbuyer@gmail.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": "7147148784", "principal_percentage_ownership": null, "short_business_name": null, "tax_authority": null, "tax_id_fingerprint": null, "tax_id_provided": false, "title": null, "url": null }, "identity_roles": [ // [!code highlight] "BUYER" ], "tags": {}, "type": "PERSONAL", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ``` API Definition ### Step 2: Create a Payment Instrument Next, create a Payment Instrument to save your buyer's bank account details. You can collect this data using our [Tokenization Forms or SDKs](/guides/online-payments/payment-tokenization), as well as [our Plaid integration](/guides/online-payments/bank-payments/plaid-integration). Microdeposit Verification If your Application requires microdeposit verification, manually added bank accounts are created disabled with `disabled_code: MICRODEPOSIT_VERIFICATION_REQUIRED` and must complete verification before you can create payments. For more information, see [Microdeposit Verification](/guides/online-payments/bank-payments/microdeposit-verification). Example API Definition Example Payment Instrument - Token - Bank Account ```json Payment Instrument - Token - Bank Account { "id": "PIkfiTDWYhQ4VbtQkC1U1ceJ", "created_at": "2024-06-21T04:09:03.77Z", "updated_at": "2024-06-21T04:09:03.77Z", "application": "APgPDQrLD52TYvqazjHJJchM", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRxpMNPZbZqVQfcHzRUJnzkR", "identity": "IDjvxGeXBLKH1V9YnWm1CS4n", "instrument_type": "BANK_ACCOUNT", "account_type": "BUSINESS_CHECKING", "bank_account_validation_check": "NOT_ATTEMPTED", "bank_code": "122105278", "country": "USA", "institution_number": null, "masked_account_number": "XXXXXX0019", "name": "Smith & Associates Consulting", "transit_number": null, "tags": {}, "third_party": null, "third_party_token": null, "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDjvxGeXBLKH1V9YnWm1CS4n" } } } ``` API Definition ### Step 3: Create a Transfer Finally, create a Transfer using the buyer's Payment Instrument as the `source`. This will debit funds directly from the buyer's bank account. ACH Direct Debits have `type: DEBIT`, and start with `state: PENDING`. The `ready_to_settle_at` field indicates when the `Transfer` will get batched into the next settlement. This field is updated asynchronously. Example API Definition Example Transfer ```json Transfer { "id": "TRheCfmbxcrZHriLeNbCvmPn", "created_at": "2026-09-25T20:05:54.11Z", "updated_at": "2026-09-25T20:05:54.11Z", "3d_secure_session": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 6031, "amount_requested": 6031, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "USD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj", "idempotency_id": null, "ip_address_details": null, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "messages": [], "network_details": null, "operation_key": "CARD_NOT_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "processed_at": "2026-09-25T20:05:54.47Z", "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": "PI9XuhFdFzJ5V9aGYUm6XtH", "split_transfers": [], "state": "PENDING", "statement_descriptor": "FLX*FINIX FLOWERS", "subtype": "API", "supplemental_fee": null, "tags": {}, "third_party_details": null, "tip_amount": null, "trace_id": "5f60656e-6841-437c-ad93-94d85cbb30bd", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRheCfmbxcrZHriLeNbCvmPn" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRheCfmbxcrZHriLeNbCvmPn/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRheCfmbxcrZHriLeNbCvmPn/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRheCfmbxcrZHriLeNbCvmPn" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRheCfmbxcrZHriLeNbCvmPn/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI9XuhFdFzJ5V9aGYUm6XtH" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj" } } } ``` API Definition ## ACH returns ACH Direct Debits can fail for multiple reasons, including: - Invalid bank account or routing number. - Buyer's bank account blocks ACH Direct Debits. - Insufficient funds from a buyer's bank account. - Buyer disputes an ACH Direct Debit. Most disputes arise within 3-5 business days of the transaction. However, buyers can dispute ACH Direct Debits for any reason up to 60 days after the payment got processed. ACH Direct Debits older than 60 days are guaranteed not to be disputed or get returned. When an ACH Direct Debit fails, Finix automatically creates an ACH Return to recover the original payment amount. ACH Returns are represented by Transfers with `type: REVERSAL` and `subtype: SYSTEM`. You can view ACH Returns in the Finix Dashboard. ACH Return ```json ACH Return Example { "id": "TR4YKKnhbCk54EXCc7pGxgNx", "amount": "8000", "tags": { "result_message_0": "ReasonCode: R04", "result_message_1": "ReasonDescription: Invalid Account Number" }, "state": "SUCCEEDED", "trace_id": "8e608a61-eeac-477e-93bf-a3032bfc1352", "currency": "USD", "application": "APg5RS31BShqrRvwheH63A6F", "source": null, "destination": "PIp6s3WFMBbiugrUo5QveQ8u", "ready_to_settle_at": "2025-01-03T20:01:02.34Z", "externally_funded": "FALSE", "fee": "0", "statement_descriptor": null, "type": "REVERSAL", "fee_type": null, "messages": [], "raw": null, "created_at": "2025-01-02T20:10:01.56Z", "updated_at": "2025-01-02T20:10:01.56Z", "idempotency_id": null, "merchant_identity": "ID76b9UfSem4ekbCDpRCZjwu", "operation_key": null, "failure_code": null, "failure_message": null, "additional_buyer_charges": null, "additional_purchase_data": null, "additional_healthcare_data": null, "address_verification": null, "security_code_verification": null, "links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APg5RS31BShqrRvwheH63A6N" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TR4YKKnhbCk54EXCc7pGxgNy" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID76b9UfSem4ekbCDpRBZjwu" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TR4YKKnhbCk54EXCc7pGxgNy/payment_instruments" }, "parent": { "href": "https://finix.sandbox-payments-api.com/transfers/TR6uHGCfpwNYwm2XXt5x32Y4" }, "destination": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIp6s3WFMBbiugrUo5QveQ8u" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d" } }, "device": null, "card_present_details": null, "amount_requested": 8000, "merchant": "MUwcLg8R5SsHeY7bg7rsjV2R", "receipt_last_printed_at": null, "split_transfers": [], "parent_transfer": "TR6uHGCfpwNYwm2XXt5x32Y4", "parent_transfer_trace_id": "8e608a61-eeac-477e-93bf-a3032bfc1352", "tip_amount": null, "related": {}, "subtype": "SYSTEM" } ``` ### ACH return reason codes The ACH Return Reason Code explains why the ACH Direct Debit failed and was ultimately returned. | Code | Description | | --- | --- | | `R01` | Insufficient funds in account | | `R02` | Account is closed | | `R03` | No account on file | | `R04` | Invalid account number | | `R05` | Unauthorized debit to consumer account | | `R06` | Returned at request of ODFI | | `R07` | Authorization revoked by customer | | `R08` | Payment stopped | | `R09` | Insufficient collected funds in account being charged | | `R10` | Customer advises not Authorized, notice not provided, improper source document, or amount of entry not accurately obtained from source document | | `R11` | Check truncation return | | `R12` | Account sold to another financial institution | | `R13` | Invalid ACH routing number | | `R14` | Representative payee is deceased or cannot continue in that capacity | | `R15` | Beneficiary or account holder other than representative payee deceased | | `R16` | Account funds have been frozen | | `R17` | Item returned because of invalid data; refer to addenda for information | | `R18` | Improper effective date | | `R19` | Amount error | | `R20` | Account does not allow ACH transactions or limit for transactions has been exceeded | | `R21` | Invalid company identification | | `R22` | Invalid individual ID | | `R23` | Credit entry refused by receiver | | `R24` | Duplicate entry | | `R25` | Addenda record error | | `R26` | Mandatory field error | | `R27` | Trace number error | | `R28` | Routing/transit number check digit error | | `R29` | Corporate customer advised not authorized | | `R30` | RDFI not participant in check truncation program | | `R31` | Permissible return entry | | `R32` | RDFI non-settlement | | `R33` | Return of item | | `R34` | Limited participation ODFI | | `R35` | Return of improper debit entry | | `R36` | Return of improper credit entry | | `R37` | Source document presented for payment | | `R38` | Stop payment on source document | | `R39` | Improper source document | | `R40` | Return of item by government agency | | `R41` | Invalid Transaction Code | | `R42` | Routing/transit number check digit error | | `R43` | Invalid account number | | `R44` | Invalid individual ID | | `R45` | Invalid individual name or company name | | `R46` | Invalid representative payee indicator | | `R47` | Duplicate enrollment | | `R50` | State law affecting RCK acceptance | | `R51` | Item is ineligible, notice not provided, signature not authentic, or original item altered for adjustment entry | | `R52` | Stop payment on item | | `R53` | Item and ACH entry presented for payment | | `R61` | Misrouted return - RDFI for original entry has placed incorrect routing/transit number in RDFI identification field | | `R67` | Duplicate return | | `R68` | Untimely return - return was not sent within the established time frame | | `R69` | Field errors | | `R70` | Permissible return entry not accepted | | `R71` | Misrouted dishonored return -incorrect routing/transit number in RDFI identification field | | `R72` | Untimely return - dishonored return was not sent within the established time frame | | `R73` | Timely original return - RDFI certifies the original return entry was sent within established time frame for original returns | | `R74` | Corrected return - RDFI is correcting a previous return entry that was dishonored because it contained incomplete or incorrect information | | `R75` | Original return not a duplicate | | `R76` | No errors found | | `R80` | Cross-border payment coding error | | `R81` | Non-participant in cross-border program | | `R82` | Invalid foreign RDFI identification | | `R83` | Foreign RDFI unable to settle | | `R84` | Cross-border entry not processed by originating gateway operator | ## ACH Refunds You can refund ACH Direct Debits, similar to how you can refund card payments. To initiate an ACH Refund, create a Reversal Transfer with the `/reversals` endpoint. You'll pass in the `id` of the original Transfer you'd like to reverse. This creates a Transfer with `type: REVERSAL`, with the original transfer linked in `_links.parent`. Wait for ACH settlement before refunding ACH has no void mechanism. Once a transfer is submitted to the network, it cannot be canceled. Wait until the original Transfer is `SUCCEEDED` and the buyer’s bank has had time to confirm the debit (typically 4–10 business days) before issuing a refund. Refunding earlier can lead to reconciliation issues if the original debit is later returned. ```shell Reversal Request # [!code word:TR6Gnj38UyPW3CoukdL9WaR1] curl https://finix.sandbox-payments-api.com/transfers/TR6Gnj38UyPW3CoukdL9WaR1/reversals \ -H "Content-Type: application/json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -d '{ "refund_amount": 6031, "tags": { "test": "refund" } }' ``` ```json Reversal { "id": "TRnqh2Mt6pnnPumxvenDmVjX", "created_at": "2022-10-10T05:36:19.18Z", "updated_at": "2022-10-10T05:36:19.27Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "address_verification": null, "amount": 6031, "amount_requested": 6031, "application": "APgPDQrLD52TYvqazjHJJchM", "currency": "USD", "destination": "PImmCg3Po7oNi7jaZcXhfkEu", "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "idempotency_id": null, "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg", "messages": [], "raw": null, "ready_to_settle_at": null, "security_code_verification": null, "source": null, "state": "PENDING", "statement_descriptor": "FNX*FINIX FLOWERS", "subtype": "API", "tags": { "test": "refund" }, "trace_id": "5cc0ab4e-3609-4a13-a9c3-b435328360c1", "type": "REVERSAL", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRnqh2Mt6pnnPumxvenDmVjX" }, "parent": { "href": "https://finix.sandbox-payments-api.com/transfers/TR6Gnj38UyPW3CoukdL9WaR1" }, "destination": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRnqh2Mt6pnnPumxvenDmVjX/payment_instruments" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8" } } } ``` After the refund is processed, the Transfer's `state` will change to `SUCCEEDED`. Buyers will see the refund returned as a credit within 5 to 10 business days, depending on their bank. ACH Direct Debit refunds can’t get canceled once processed. ## Refunded ACH returns Banks manage the ACH networks and often pre-fund transactions before debiting funds. In rare cases, ACH Refunds may be returned: - The bank account is closed or frozen. - The buyer made a mistake while entering their bank information. - The buyer requested to reverse a pre-funded transaction. When an ACH Refund is returned, Finix creates two Transfers to credit the funds back to the original bank account. You'll receive `transfer` `created` webhooks. - Merchant credit: one `Transfer` to return the funds back to the original bank account. - Platform debit: one `Transfer` to debit funds that got credited proactively. ```json Transfer Created Webhook for ACH Merchant Credit { "type": "created", "entity": "transfer", "occurred_at": "2022-09-01T20:49:23.437609", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 6031, "trace_id": "FNX3Rs9AKNwUVoVu112D40ec5", "failure_code": null, "fee": 603, "destination": null, "raw": null, "created_at": "2022-09-01T20:36:08.13Z", "source": "PIr1Ru7ewBkEYVVn7SP1u5FW", "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg", "failure_message": null, "type": "CREDIT", "tags": { "result_message_0": "ReasonCode: R03", "result_message_1": "ReasonDescription: No Account Unable to Locate Account" }, "statement_descriptor": "FNX*FINIX FLOWERS", "additional_buyer_charges": null, "ready_to_settle_at": null, "application": "APgPDQrLD52TYvqazjHJJchM", "updated_at": "2022-09-01T20:49:23.43", "subtype": "MERCHANT_CREDIT_ADJUSTMENT", "externally_funded": "UNKNOWN", "messages": [], "currency": "USD", "id": "TRzoL5FmpxIP2TRAmHKSlHgz", "state": "SUCCEEDED" } ] } } ``` ```json Transfer Created Webhook for ACH Platform Debit { "type": "created", "entity": "transfer", "occurred_at": "2022-09-01T20:49:23.437609", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 6031, "trace_id": "FNXff8f88c140908eb69f3321", "failure_code": null, "fee": 603, "destination": null, "raw": null, "created_at": "2022-09-01T20:36:08.13Z", "source": "PIr1Ru7ewBkEYVVn7SP1u5FW", "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg", "failure_message": null, "type": "DEBIT", "statement_descriptor": "FNX*FINIX FLOWERS", "additional_buyer_charges": null, "ready_to_settle_at": null, "application": "APgPDQrLD52TYvqazjHJJchM", "updated_at": "2022-09-01T20:49:23.43", "subtype": "PLATFORM_DEBIT_ADJUSTMENT", "externally_funded": "UNKNOWN", "messages": [], "currency": "USD", "id": "TRoom5emPxiP1TRAmHcSjHgz", "state": "SUCCEEDED" } ] } } ``` --- # EFT Payments Source: https://docs.finix.com/guides/online-payments/bank-payments/eft-payments Learn how sellers can process payments from Canada-based bank accounts. ## Data requirements To accept an EFT Payment, you must collect the following bank account information. | Field | Description | | --- | --- | | Account Type`account_type` | Bank account type | | Account Owner`name` | Bank account owner name | | Account Number`account_number` | Bank account number | | Routing Number`bank_code` | Bank account routing number/bank code | | Institution Number`institution_number` | Bank account institution number | | Transit Number`transit_number` | Bank account transit number | ## Step 1: Create an Identity for your Buyer To process an EFT payment, first create an `Identity` to represent the buyer. An `Identity` resource helps manage payments, payment methods, bank accounts, transaction history, and more. Example API Definition Example Buyer ```json Buyer { "id": "IDm1QmqySG8YQUth47dj2sV5", "created_at": "2026-09-25T20:05:10.29Z", "updated_at": "2026-09-25T20:05:10.29Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "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_fingerprint": null, "business_tax_id_provided": false, "business_type": null, "default_statement_descriptor": null, "discover_mid": null, "dob": null, "doing_business_as": null, "email": "johnsmithbuyer@gmail.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": "7147148784", "principal_percentage_ownership": null, "short_business_name": null, "tax_authority": null, "tax_id_fingerprint": null, "tax_id_provided": false, "title": null, "url": null }, "identity_roles": [ // [!code highlight] "BUYER" ], "tags": {}, "type": "PERSONAL", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ``` API Definition ## Step 2: Create a bank account ### Create a CAD bank account using Plaid We recommend using Plaid to create bank accounts for your buyers. Learn how to create Bank Accounts with Plaid by reading our [guide](/guides/online-payments/bank-payments/plaid-integration#migrating-plaid-access-tokens). ### Create a CAD bank account via API 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](/guides/online-payments/payment-tokenization/tokenization-forms) or mobile tokenization (see [Android](/guides/online-payments/payment-tokenization/mobile-tokenization-android) or [iOS](/guides/online-payments/payment-tokenization/mobile-tokenization-ios) tokenization) to accept payment details, and remain out of PCI scope. A `Payment Instrument` resource represents the payment details of a credit card or bank account. A Payment Instrument is associated with a single `Identity`. Example API Definition Example Payment Instrument - Canadian Bank Account ```json Payment Instrument - Canadian Bank Account { "id": "PIeHxmfnj5PzqF4JGtbf2Y2m", "created_at": "2026-09-25T20:05:27.04Z", "updated_at": "2026-09-25T20:05:27.04Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "CAD", // [!code highlight] "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPR8RAHfXm1BMYYVJyHWHhw4J", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "BANK_ACCOUNT", "account_type": "PERSONAL_CHECKING", "bank_account_validation_check": "NOT_ATTEMPTED", "bank_code": null, "country": "CAN", // [!code highlight] "institution_number": "123", "masked_account_number": "XXXXX3123", "name": "John Doe", "transit_number": "12345", "tags": {}, "third_party": null, "third_party_token": null, "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIeHxmfnj5PzqF4JGtbf2Y2m" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIeHxmfnj5PzqF4JGtbf2Y2m/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIeHxmfnj5PzqF4JGtbf2Y2m/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIeHxmfnj5PzqF4JGtbf2Y2m/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` API Definition ## Step 3: Create a CAD bank Transfer Once you have a CAD bank account, you can create an EFT Payment. Example API Definition Example Transfer - EFT ```json Transfer - EFT { "id": "TRp6LDrhdXaXNvnksSeTrrGw", "created_at": "2026-09-11T23:30:10.49Z", "updated_at": "2026-09-11T23:30:10.49Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 662154, "amount_requested": 662154, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "CAD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPmtT4MYmiAs1qjLjneQmk4d", "idempotency_id": null, "ip_address_details": null, "merchant": "MUaxXcUAU93JCJutWZVy6KJ5", "merchant_identity": "ID6V2Fppq1oUsEd9pzWUbrw6", "messages": [], "network_details": null, "operation_key": "CARD_NOT_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "processed_at": "2026-09-11T23:30:10.85Z", "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": "PIaRNMmrH4WtiBVhaZach99g", "split_transfers": [], "state": "PENDING", "statement_descriptor": "FLX*VIDEO SERVICES", "subtype": "API", "supplemental_fee": null, "tags": {}, "third_party_details": null, "tip_amount": null, "trace_id": "c9b6d473-d4bc-4c7d-9d18-ab444de10e4b", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRp6LDrhdXaXNvnksSeTrrGw" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6V2Fppq1oUsEd9pzWUbrw6" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRp6LDrhdXaXNvnksSeTrrGw/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRp6LDrhdXaXNvnksSeTrrGw/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRp6LDrhdXaXNvnksSeTrrGw" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRp6LDrhdXaXNvnksSeTrrGw/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIaRNMmrH4WtiBVhaZach99g" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d" } } } ``` API Definition ## EFT PAD requirements Canadian-based sellers must present a clear authorization to buyers. Before debiting a buyer's bank account, sellers must first collect authorization from the buyer defining a specific payment schedule or terms. The authorization must include the buyer's institution number, transit number, account number, name and email. [Read more about the required authorizations](https://www.payments.ca/sites/default/files/h1eng.pdf). ### Authorization agreement ("**PAD agreement**") requirements | Field | Description | | --- | --- | | Business Contact Information | The PAD agreement must contain reasonable and accurate contact information that the buyer can use to contact your business by a method of communication your buyer uses. | | Date and Signature of PAD Agreement Acceptance | Somewhere in the PAD Agreement presented to the buyer, the date of the PAD Agreement acceptance must be shown. Either a signature field must be included or the Agreement must be otherwise "Authorized" in accordance with [Rule H1](https://www.payments.ca/sites/default/files/h1eng.pdf). | | Pre-authorized debit Type | A clear statement indicating the amount (fixed or variable) of the debit and when you will debit the buyer (i.e. weekly, monthly, sporadic, or caused by a specific event). If each PAD is triggered by an event then an unambiguous description of that event. | | Authority to Debit Account with Variable Amounts | A clear and unambiguous statement outlining your buyer's agreement that your business is authorized to debit the account given. | | Payment Schedule | A clear statement indicating the amount (fixed or variable) of the debit and when you will debit the buyer (i.e. weekly, monthly, sporadic, or caused by a specific event). If each PAD is triggered by an event then an unambiguous description of that event. | | Payment Schedule | A clear statement indicating the amount (fixed or variable) of the debit and when you will debit the buyer (i.e. weekly, monthly, sporadic, or caused by a specific event). If each PAD is triggered by an event then an unambiguous description of that event. | | Sporadic Authorization | If the PAD Agreement authorizes Sporadic PADs, a clear statement must specify that the seller is required to obtain authorization from the buyer in accordance with Rule H1 for each Sporadic PAD that the seller issues against the buyer. | | One-Time Payment Authorization | If the PAD Agreement provides for a PAD that is One-Time, the PAD Agreement must specify that the PAD Agreement supports a One-Time PAD, and that the PAD Agreement will no longer be valid once the payment has been fulfilled. The seller shall then obtain a new PAD Agreement for any subsequent PADs. "One-Time" means occurring once, on a set date. | | Modification of PAD Confirmation Period | In order to improve the speed with which you can do business, Finix conducts verification on buyer's bank accounts that allows your business to begin debiting after a PAD is accepted so long as the buyer has agreed to this in the PAD Agreement. | | Modification of Pre-Notification Period | Pre-notifications are required if not expressly waived. If you opt out of sending these emails, the text for waiving the pre-notification must be included instead, also bolded, highlighted or underlined. | | Recourse / Reimbursement Statement | The PAD Agreement must contain this exact text in its entirety: "You [or I/We, depending on the context] have certain recourse rights if any debit does not comply with this agreement. For example, you [I/we] have the right to receive reimbursement for any debit that is not authorized or is not consistent with this PAD Agreement. To obtain more information on your [my/our] recourse rights, [I/we may] contact your [my/our] financial institution or visit ." | | Cancellation of Agreement | A statement outlining a buyer's ability to revoke their authorization at any time, specifying an amount of notice required by your business. The authorization agreement should also advise that the buyer may obtain a sample cancellation form, or further information on their right to cancel a PAD Agreement at their financial institution or by visiting . | | Notice of Use of a Payment Service Provider | The PAD Agreement must disclose Finix as the payment processor. | ### Sample one-time PAD agreement blockquote Customer First Commerce 631 Main Street, Toronto, ON M2F 234 Telephone: Email: [support@customer-commerce.com](mailto:support@customer-commerce.com) Date: Account Holder: John Smith Type: Personal Institution: 001 Account # 0000124432244 Email: [john@example.com](mailto:john@example.com) Transit: 12345 Pre-authorized Debit ("**PAD**") Agreement By clicking submit, you accept this one-time PAD Agreement and authorize Customer First Commerce to debit the specified bank account for any amount owed for charges arising from the use of services and/or purchase of products. Payments will be debited from the specified account on [INSERT SPECIFIC DATE]. Where a scheduled debit date is not a business day, Customer First Commerce will debit the specified account on the next business day. You agree that any payments due will be debited from your account immediately upon acceptance of this PAD Agreement and that confirmation of this PAD Agreement may be sent within five (5) days of acceptance of this PAD Agreement. **You further agree that your authority under this PAD Agreement is to remain in effect until we complete the one-time payment at which time your PAD Agreement will automatically terminate.** You have certain recourse rights if any debit does not comply with this PAD Agreement. For example, you have the right to receive reimbursement for any debit that is not authorized or is not consistent with this PAD Agreement. To obtain more information on your recourse rights, contact your financial institution or visit . You may amend or cancel this PAD Agreement at any time by providing Customer First Commerce with thirty (30) days’ advanced notice at [support@customer-first-commerce.com](mailto:support@customer-first-commerce.com). To obtain a sample cancellation form, or further information on cancelling this PAD Agreement, please contact your financial institution or visit . Customer First Commerce partners with Finix Canada, Inc. to provide payment processing services. --- # Bank Payments Source: https://docs.finix.com/guides/online-payments/bank-payments Finix supports accepting payments directly from your buyers' bank accounts. These are known as ACH Direct Debits in the US, and EFT Payments in Canada. Offering pay-by-bank can be beneficial for customers who don't wish to use card. Use the guides below to learn how to use Finix's pay-by-bank solutions. ## Learn more ACH Direct Debits Learn how to accept payments from US-based bank accounts. EFT Payments Learn how sellers can process payments from Canada-based bank accounts. Plaid Integration Learn how to add bank accounts to Finix with Plaid. Microdeposit Verification Learn how buyers verify manually added bank accounts with a $0.01 microdeposit. --- # Microdeposit verification Source: https://docs.finix.com/guides/online-payments/bank-payments/microdeposit-verification Bank accounts must be verified before they can be used for payments. Verification confirms that the person adding a bank account is its owner, which protects you from fraud and reduces ACH returns. Finix supports two ways to verify a bank account: - **Plaid**: Buyers log in to their bank, and [Plaid](/guides/online-payments/bank-payments/plaid-integration) verifies account existence and ownership instantly. Bank accounts created with Plaid are verified and ready to use immediately. - **Microdeposits:** When buyers enter their bank account details manually, Finix sends a single $0.01 deposit carrying a unique verification code. The buyer confirms ownership by finding the code on their bank statement and submitting it. Plaid bank accounts skip microdeposit verification Bank accounts created with [Plaid](/guides/online-payments/bank-payments/plaid-integration) are already verified and do not require microdeposit verification. Plaid bank account linking flow showing instant verification without a microdeposit Microdeposit verification applies to buyers only Microdeposit verification is required only for **buyer** bank accounts before debiting them. Sellers (sub-merchants) are not required to complete microdeposit verification during onboarding or when updating their bank account information. ## Verification methods Microdeposit verification is available in two ways: - **Low-code products:** Payment Links, Virtual Terminal, Checkout Forms, Invoices, Subscriptions, and Subscription Links prompt buyers to verify their bank account, either through Plaid or by entering a microdeposit code. Buyers are redirected to a hosted verification page to enter the code. - **API:** Integrate microdeposit verification directly using the Finix API. When you create a bank account Payment Instrument manually, Finix initiates the microdeposit flow. See [Verifying a Bank Account using the API](#verifying-a-bank-account-using-the-api). ## How it works The following uses a [Payment Link](/low-code-no-code/payment-links) configured to accept bank account payments as an example. The same process applies to all of Finix's low-code solutions. 1. When a buyer submits a payment, they can manually enter their bank account details. Hosted checkout showing bank account payment option 1. The buyer enters their bank account details manually. Hosted form for entering bank account details manually 1. Finix sends a single $0.01 deposit to the bank account. The deposit's statement descriptor carries a unique verification code that begins with `FNX` (for example, `FNX7Q2M`). 2. The buyer finds the code on their bank statement and submits it using a hosted form. Hosted form where the buyer enters the FNX verification code from their bank statement Microdeposits arrive quickly When available, Finix sends the $0.01 microdeposit via FedNow or RTP, so buyers may see the deposit in their bank account within minutes. - The buyer is granted 3 tries to submit the correct code and must complete verification within 30 days or the microdeposit verification expires. - When the code matches, Finix confirms ownership and processes the payment. ## Verifying a Bank Account using the API ### 1. Create a Bank Account Payment Instrument Send a POST /payment_instruments request to create a Payment Instrument, specifying banking details and the buyer's [identity](/api/identities) ID. After creating a Payment Instrument, the following fields are set: `enabled: false` and `disabled_code: MICRODEPOSIT_VERIFICATION_REQUIRED`, indicating the Payment Instrument cannot be used for payments until it is verified. In the response, the Payment Instrument resource is pending microdeposit verification: Bank account Payment Instrument - Pending microdeposit verification ```json Bank account Payment Instrument - Pending microdeposit verification { "id": "PIvSQVFLTPkbTLiPq3xFdrDt", "created_at": "2026-09-24T21:48:03.07Z", "updated_at": "2026-09-24T21:48:03.07Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": "MICRODEPOSIT_VERIFICATION_REQUIRED", // [!code highlight] "disabled_message": "Bank account is pending microdeposit verification.", // [!code highlight] "enabled": false, // [!code highlight] "fingerprint": "FPRxpMNPZbZqVQfcHzRUJnzkR", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "BANK_ACCOUNT", "microdeposit": "microdeposit_faGgpfFJdRKhxRKkg2zk5U", // [!code highlight] "microdeposit_verification_url": "https://link.sandbox-payment-form.com/REDACTED", // [!code highlight] "account_type": "BUSINESS_CHECKING", "bank_account_validation_check": "NOT_ATTEMPTED", "bank_code": "122105278", "country": "USA", "institution_number": null, "masked_account_number": "XXXXXX0019", "name": "Smith & Associates Consulting", "transit_number": null, "tags": {}, "third_party": null, "third_party_token": null, "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIvSQVFLTPkbTLiPq3xFdrDt" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIvSQVFLTPkbTLiPq3xFdrDt/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIvSQVFLTPkbTLiPq3xFdrDt/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIvSQVFLTPkbTLiPq3xFdrDt/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` The `microdeposit` field contains the ID of the Microdeposit resource. The `microdeposit_verification_url` field contains a link to Finix's hosted verification form, which you can share with the buyer as an alternative to collecting the code in your own form. See [Submit the verification code](#3-submit-the-verification-code). A sale created with a Payment Instrument that has not completed microdeposit verification will fail. ### 2. Retrieve the Microdeposit (optional) You can retrieve the Microdeposit to determine how many tries they have left and when the 30-day window expires. Use the `microdeposit` ID from the previous response to send a GET /microdeposits/{id} request: Microdeposit - Pending verification ```json Microdeposit - Pending verification { "id": "microdeposit_faGgpfFJdRKhxRKkg2zk5U", "created_at": "2026-09-24T21:48:03.095703Z", "updated_at": "2026-09-24T21:48:03.366698Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "expires_at": "2026-10-24T21:48:03.095710Z", // [!code highlight] "instrument": "PIvSQVFLTPkbTLiPq3xFdrDt", "rail": "RTP", "state": "PENDING", // [!code highlight] "verification_attempts": 0, "verification_attempts_remaining": 3, // [!code highlight] "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/microdeposits/microdeposit_faGgpfFJdRKhxRKkg2zk5U" }, "instrument": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIvSQVFLTPkbTLiPq3xFdrDt" } } } ``` | Field | Description | | --- | --- | | `expires_at` | When the 30-day verification window expires. | | `state` | The current state of the Microdeposit. Retrieve the Microdeposit while `state` is `PENDING` to surface `verification_attempts_remaining` and `expires_at` to the buyer. Moves to `VERIFIED` when the buyer submits the correct code, or `FAILED` when all 3 code submissions are used or the 30-day window expires. A failed Microdeposit does not permanently lock the bank account; see [Attempt limits](#attempt-limits). Once resolved, the Payment Instrument's `disabled_code` is the authoritative record of account status. | | `verification_attempts` | The number of verification attempts made. | | `verification_attempts_remaining` | The number of verification attempts remaining. | ### 3. Submit the verification code There are two ways to submit the verification code: #### Option A: Use Finix's hosted verification form Share the `microdeposit_verification_url` from the Payment Instrument response with your buyer (via email, a redirect, or another delivery method). The buyer opens the link and submits their code on Finix's hosted page. After the buyer submits, send a GET /payment_instruments/{id} request to confirm the Payment Instrument is enabled: Payment Instrument - verified ```json Payment Instrument - verified { "id": "PIvSQVFLTPkbTLiPq3xFdrDt", "created_at": "2026-09-24T21:48:03.07Z", "updated_at": "2026-09-24T21:48:12.80Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, // [!code highlight] "disabled_message": null, // [!code highlight] "enabled": true, // [!code highlight] "fingerprint": "FPRxpMNPZbZqVQfcHzRUJnzkR", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "BANK_ACCOUNT", "microdeposit": "microdeposit_faGgpfFJdRKhxRKkg2zk5U", "microdeposit_verification_url": "https://link.sandbox-payment-form.com/REDACTED", "account_type": "BUSINESS_CHECKING", "bank_account_validation_check": "NOT_ATTEMPTED", "bank_code": "122105278", "country": "USA", "institution_number": null, "masked_account_number": "XXXXXX0019", "name": "Smith & Associates Consulting", "transit_number": null, "tags": {}, "third_party": null, "third_party_token": null, "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIvSQVFLTPkbTLiPq3xFdrDt" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIvSQVFLTPkbTLiPq3xFdrDt/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIvSQVFLTPkbTLiPq3xFdrDt/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIvSQVFLTPkbTLiPq3xFdrDt/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` You can also confirm verification by fetching the Microdeposit, which now has `state: VERIFIED`: Microdeposit - Verified ```json Microdeposit - Verified { "id": "microdeposit_faGgpfFJdRKhxRKkg2zk5U", "created_at": "2026-09-24T21:48:03.095703Z", "updated_at": "2026-09-24T21:48:12.795985Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "expires_at": "2026-10-24T21:48:03.095710Z", "instrument": "PIvSQVFLTPkbTLiPq3xFdrDt", "rail": "RTP", "state": "VERIFIED", // [!code highlight] "verification_attempts": 1, "verification_attempts_remaining": 2, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/microdeposits/microdeposit_faGgpfFJdRKhxRKkg2zk5U" }, "instrument": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIvSQVFLTPkbTLiPq3xFdrDt" } } } ``` If the buyer opens the `microdeposit_verification_url` after verification is already complete, the page displays: "Bank account verified. Your bank account ending in __ is now ready to use." #### Option B: Collect the code in your own form If you are building your own verification UI, collect the verification code from the buyer and submit it via a PUT /payment_instruments/{id} request with `verification_code` and `verify_microdeposits` set to `true`: ```shell Verify microdeposit request curl -i -X PUT \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/payment_instruments/PI5NEZUkKPCPkwCLAuZnCEmP \ -H 'Content-Type: application/json' \ -d '{ "verification_code": "FNX0000", "verify_microdeposits": true }' ``` If the code matches, the Payment Instrument is enabled and ready for payments: Payment Instrument - verified ```json Payment Instrument - verified { "id": "PIvSQVFLTPkbTLiPq3xFdrDt", "created_at": "2026-09-24T21:48:03.07Z", "updated_at": "2026-09-24T21:48:12.80Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, // [!code highlight] "disabled_message": null, // [!code highlight] "enabled": true, // [!code highlight] "fingerprint": "FPRxpMNPZbZqVQfcHzRUJnzkR", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "BANK_ACCOUNT", "microdeposit": "microdeposit_faGgpfFJdRKhxRKkg2zk5U", "microdeposit_verification_url": "https://link.sandbox-payment-form.com/REDACTED", "account_type": "BUSINESS_CHECKING", "bank_account_validation_check": "NOT_ATTEMPTED", "bank_code": "122105278", "country": "USA", "institution_number": null, "masked_account_number": "XXXXXX0019", "name": "Smith & Associates Consulting", "transit_number": null, "tags": {}, "third_party": null, "third_party_token": null, "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIvSQVFLTPkbTLiPq3xFdrDt" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIvSQVFLTPkbTLiPq3xFdrDt/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIvSQVFLTPkbTLiPq3xFdrDt/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIvSQVFLTPkbTLiPq3xFdrDt/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` You can also confirm verification by fetching the Microdeposit, which now has `state: VERIFIED`: Microdeposit - Verified ```json Microdeposit - Verified { "id": "microdeposit_faGgpfFJdRKhxRKkg2zk5U", "created_at": "2026-09-24T21:48:03.095703Z", "updated_at": "2026-09-24T21:48:12.795985Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "expires_at": "2026-10-24T21:48:03.095710Z", "instrument": "PIvSQVFLTPkbTLiPq3xFdrDt", "rail": "RTP", "state": "VERIFIED", // [!code highlight] "verification_attempts": 1, "verification_attempts_remaining": 2, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/microdeposits/microdeposit_faGgpfFJdRKhxRKkg2zk5U" }, "instrument": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIvSQVFLTPkbTLiPq3xFdrDt" } } } ``` ## Troubleshooting unsuccessful verifications These are two different sets of codes that represent the same underlying events. **422 error codes** are returned at request time when a verification attempt fails and tell you what went wrong with that specific submission. The **`disabled_code` on the Payment Instrument** is the persistent state set on the Payment Instrument afterward. Some codes (`MICRODEPOSIT_VERIFICATION_ATTEMPTS_EXCEEDED` and `MICRODEPOSIT_VERIFICATION_EXPIRED`) appear in both: the 422 fires at the moment of failure, and the `disabled_code` captures the same event as the permanent state of the Payment Instrument. Unsuccessful Microdeposit verification requests return a `422` status: ```json Example error response { "total": 1, "_embedded": { "errors": [ { "logref": "d4ee0b6cdb67686f0c1ec0780e5b4296", "message": "The microdeposit verification code provided is incorrect. 2 tries remaining.", "code": "INCORRECT_MICRODEPOSIT_VERIFICATION_CODE", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ" } } } ] } } ``` One of the following errors are possible: | Scenario | Error Code | Message | | --- | --- | --- | | The code is incorrect and there are tries remaining. | `INCORRECT_MICRODEPOSIT_VERIFICATION_CODE` | The microdeposit verification code provided is incorrect. 2 tries remaining. | | The code is incorrect and there are no tries remaining. | `MICRODEPOSIT_VERIFICATION_ATTEMPTS_EXCEEDED` | Microdeposit verification has failed for this bank account. Please create a new bank account to try again. | | The 30-day verification window has passed. | `MICRODEPOSIT_VERIFICATION_EXPIRED` | The microdeposit verification window for this bank account has passed. Please create a new bank account to verify it again. | | The bank account is already verified. | `UNPROCESSABLE_ENTITY` | This payment instrument does not have a pending microdeposit verification. | | The Payment Instrument has no pending microdeposit. | `UNPROCESSABLE_ENTITY` | This payment instrument does not have a pending microdeposit verification. | | The `verification_code` is missing. | `INVALID_FIELD` | A microdeposit verification code is required. | When `INCORRECT_MICRODEPOSIT_VERIFICATION_CODE` is returned, the Payment Instrument's `disabled_code` remains `MICRODEPOSIT_VERIFICATION_REQUIRED`. The bank account isn't locked until all attempts are exhausted or the 30-day window expires. A bank account pending microdeposit verification can only be enabled by completing verification. Requests that set `enabled: true` will also return a `422` status code. To check why a verification failed, retrieve the Payment Instrument with GET /payment_instruments/{id} and inspect its `disabled_code` and `disabled_message`. See [Payment Instrument disabled code states](#payment-instrument-disabled-code-states) below. ### Payment Instrument disabled code states The Payment Instrument's `disabled_code` explains the different verification states. | Disabled Code | Description | Next Step | | --- | --- | --- | | `MICRODEPOSIT_VERIFICATION_REQUIRED` | The bank account is pending microdeposit verification. | Submit the correct verification code to enable the bank account. | | `INVALID_BANK_ACCOUNT_ROUTING_NUMBER` | Bank account routing number was invalid. | Create a new bank account to start a new verification. | | `MICRODEPOSIT_VERIFICATION_ATTEMPTS_EXCEEDED` | Microdeposit verification has failed for this bank account. Please create a new bank account to try again. | Create a new bank account to start a new verification. | | `MICRODEPOSIT_VERIFICATION_EXPIRED` | The microdeposit verification window for this bank account has passed. Please create a new bank account to verify it again. | Create a new bank account to start a new verification. | | `MICRODEPOSIT_RETURNED` | A microdeposit for this bank account was returned and the account has been disabled. | Create a new bank account to start a new verification. | | `TOTAL_MICRODEPOSIT_ATTEMPTS_EXCEEDED_ACCOUNT_LOCKED` | This bank account has reached the maximum number of microdeposit verification attempts and cannot be re-verified. This account is now locked. | Please use a different bank account or payment method. | ### Attempt limits - **3 code submissions per Microdeposit:** After 3 incorrect submissions, the verification fails and a new bank account must be created. - **30 days per Microdeposit:** A Microdeposit that is not verified within 30 days expires. - **3 failed verifications per bank account:** After 3 failed verifications for the same bank account, the bank account is permanently blocked with `disabled_code: TOTAL_MICRODEPOSIT_ATTEMPTS_EXCEEDED_ACCOUNT_LOCKED` and cannot be verified again. ## Testing in Sandbox To test Microdeposit verification in Sandbox, see [Testing Microdeposit verifications](/additional-resources/developers/implementation-and-testing/testing-your-integration#testing-microdeposit-verifications). --- # Plaid Integration Source: https://docs.finix.com/guides/online-payments/bank-payments/plaid-integration Plaid Bank Accounts Finix and Plaid have partnered to let you add your customers' bank accounts to Finix's platform seamlessly and securely. Plaid instantly verifies bank account existence and ownership, providing a fast and secure way to board your customers onto Finix. Finix offers multiple ways to add bank accounts with Plaid: - Add bank accounts with an existing Plaid Account - Use Finix's Hosted Onboarding Forms for sellers, which have Plaid Link embedded by default ## Example use cases You can use Finix `payment_instruments` connected and verified with Plaid for: - **[ACH Direct Debits](/guides/online-payments/bank-payments/ach-direct-debits):** debit buyer bank accounts for goods and services - **[Bank Payouts](/guides/payouts/bank-payouts):** send money to recipients - **[Onboarding Sellers](/guides/platform-payments/onboarding-sellers) and [Recipients](/guides/payouts/bank-payouts/):** onboard sellers and recipients with our APIs or onboarding forms This guide explains how Plaid fits into those Finix use cases. Once you have a specific use case in mind, please refer to its respective guide to understand its full process (for example, how to [onboard a seller](/guides/platform-payments/onboarding-sellers)). ## Using your Plaid account This section of the guide is for Finix customers who have existing Plaid accounts and want to use Finix for one of the payments use cases above. If you do not have a Plaid account and would like a referral to Plaid, please email `sales@finix.com`. A Finix Sales Representative will assist you. ### Step 1: Embed Plaid Link into your Application The first step is embedding [Plaid Link](https://plaid.com/docs/link/) into your application. Link is a client-side experience that lets your customers connect their bank accounts securely through Plaid. After Link, you can use your customers' bank account connections to create Plaid `processor_tokens` and, ultimately, Finix `payment_instruments`. To guide your integration, we recommend familiarizing yourself with [Plaid's guide to the Plaid + Finix integration](https://plaid.com/docs/auth/partnerships/finix/). Plaid's guide has information on how to embed Plaid Link into your application and create Plaid `processor_tokens`. Creating the Plaid Link Token Finix uses Plaid's Auth and Identity endpoints to tokenize Payment Instruments from Plaid tokens. You must include both `auth` and `identity` in the Plaid Link Token `products` array. ### Step 2: Create a Plaid processor token for the Finix processor With Plaid Link embedded into your application, you can exchange your customers' Plaid `access_tokens` for `processor_tokens` with `processor: finix`. Finix uses `processor_tokens` to get and save your customers' bank account details in the next step. ```shell Plaid Processor Token Request curl "https://sandbox.plaid.com/processor/token/create" \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "${ACCESS_TOKEN}", "account_id": "${ACCOUNT_ID}", "processor": "finix" }' ``` ```json Plaid Processor Token { "processor_token": "processor-sandbox-0asd1-a92nc", "request_id": "kxiMB5rN03wiLMD" } ``` ### Step 3: Create a Finix Payment Instrument Now, you can use the Plaid `processor_token` to create a Finix `payment_instrument`: Example API Definition Example Payment Instrument - Plaid Bank Account ```json Payment Instrument - Plaid Bank Account { "id": "PI9RvCXMLzSHkQpUWxX7dgY4", "created_at": "2026-09-25T20:36:43.89Z", "updated_at": "2026-09-25T20:36:43.89Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRxAutj19xH1AH6ykGx2dwa7", "identity": "ID3YZagNmW2bXhJkA6RdUkdS", "instrument_type": "BANK_ACCOUNT", "account_type": "CHECKING", "bank_account_validation_check": "VALID", "bank_code": "011401533", "country": "USA", "institution_number": null, "masked_account_number": "XXXXXXXXXXX0000", "name": "John Smith", "transit_number": null, "tags": {}, "third_party": "PLAID", // [!code highlight] "third_party_token": "processor-sandbox-ab3cff03-8948-1291-f2fe-05634be2c38c", "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI9RvCXMLzSHkQpUWxX7dgY4" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI9RvCXMLzSHkQpUWxX7dgY4/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI9RvCXMLzSHkQpUWxX7dgY4/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI9RvCXMLzSHkQpUWxX7dgY4/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID3YZagNmW2bXhJkA6RdUkdS" } } } ``` API Definition This diagram summarizes that process across the Plaid and Finix platforms: Alt text ### Migrating Plaid Access tokens If you have previously connected your customers' bank accounts with Plaid, you can migrate those bank account connections onto Finix's platform. To do this, you will need to use Plaid's `/processor/token/create` endpoint to exchange each customer's Plaid `access_token` for a `processor_token` with `processor: finix`. For more information on creating the `processor_token`, please see [Plaid's guide to the Plaid + Finix integration](https://plaid.com/docs/auth/partnerships/finix/). ## Using Finix's Plaid account By default our Finix.js JavaScript library creates Bank Accounts using Plaid. All you need to do is implement Finix.js and Finix handles the heavy lifting of using Plaid. Your responsibility will be claiming the `TOKEN` generated by Finix.js with your authenticated credentials in the Step 2 below. ### Step 1: Integrate our Finix.js library and get a `TOKEN` Our Finix.js library automatically enables Plaid for all `BANK_ACCOUNT` creation. This is to minimize returns and fraud. You will get a `TOKEN` back from the `finix.js`. ```json Example Token Response { "id": "TKeD6uad8xZc52Rqg1VhvSBw", "created_at": "2025-06-10T00:31:53.54Z", "updated_at": "2025-06-10T00:31:53.54Z", "currency": "USD", "expires_at": "2025-06-11T00:31:53.54Z", "fingerprint": "FPRrcobjtdU98gr4sjiqYR1Qg", "instrument_type": "BANK_ACCOUNT" } ``` Once you've handled the response, store the ID to utilize the token in the future. You will eventually send the `token` ID from your front-end client to your back-end server. ```javascript Sample Javascript workflow const tokenData = res.data || {}; // get token ID from response const token = tokenData.id; function handleResponse(response) // This would be your custom logic ``` Many customers implement additional logic after a buyer enters their payment information, using the returned `token`. For example, some customers choose to implement a different workflow depending if a `PAYMENT_CARD` or `BANK_ACCOUNT` is returned by Finix.js. ### Step 2: Claim the `TOKEN` using your authenticated credentials Now that you have the `token`, you should send this to your backend. You will need this ID to eventually do an authenticated call to Finix in the next step. Token usage and expiration Tokens should be used to create a `Payment Instrument` right away in the next step. Tokens expire within 30 minutes and cannot be used after expiring. ```Sample Javascript workflow fetch('/your/backend', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ token: token }), }) ``` ## Seller Onboarding If you prefer a low-code or no-code solution, you can use [Finix's Onboarding Forms](/guides/platform-payments/onboarding-sellers/seller-onboarding-forms) to let your sellers connect their bank accounts with Plaid during the Finix onboarding process. Finix's Onboarding Forms let sellers on your platform choose whether to connect their bank accounts through Plaid Link or manually, giving them the flexibility to pick the option that works best for them. Alt text ## Verifying bank accounts When you create `payment_instruments` with Plaid `processor_tokens`, Finix uses Plaid Auth to securely get and save the account and routing numbers. Finix also uses Plaid Identity to verify the ownership of the bank account, which is critical for mitigating fraud and protecting our customers. Bank accounts created with Plaid never require [microdeposit verification](/guides/online-payments/bank-payments/microdeposit-verification) — they're verified and ready to use as soon as they're created. Bank accounts connected and verified with Plaid will have `bank_account_validation_check: VALID`: ```json Plaid-Connected Payment Instrument { "id": "PI3AbkuRR1JbT5kPiGQCXvD9", "created_at": "2022-10-11T01:42:53.29Z", "updated_at": "2022-10-11T01:42:53.29Z", "application": "APgPDQrLD52TYvqazjHJJchM", "created_via": "API", "currency": "USD", "enabled": true, "third_party": "PLAID", "third_party_token": "processor-sandbox-0asd1-a92nc", "fingerprint": "FPRd5moHxL3Ltuvk4cczxetCg", "identity": "IDpYDM7J9n57q849o9E9yNrG", "instrument_type": "BANK_ACCOUNT", "account_type": "PERSONAL_CHECKING", "bank_account_validation_check": "VALID", "bank_code": "123123123", "country": "USA", "masked_account_number": "XXXXX3123", "name": "John Doe", "tags": {}, "type": "BANK_ACCOUNT", "_links": {} } ``` ## Plaid benefits Connecting bank accounts with Plaid is advantageous by offering: - **Better customer experience:** Plaid lets your customers add their bank account details simply by logging into their bank account, rather than providing their bank account and routing numbers manually - **Faster onboarding:** Plaid verifies bank account existence and ownership instantly, providing the fastest onboarding experience for your customers - **Increased security** - Plaid limits the need for Finix customers to handle bank account data directly, which is preferable from a security standpoint - **No microdeposit verification:** Plaid verifies ownership instantly, so buyers skip the [microdeposit verification](/guides/online-payments/bank-payments/microdeposit-verification) flow entirely ## Supported bank accounts Finix supports U.S. and Canadian Plaid bank account connections. Finix uses Plaid's Auth API to create Payment Instruments with the following details. ### U.S. bank accounts - Account Number - Routing Number ### Canadian bank accounts - Account Number - Transit Number - Institution Number --- # Buy Now, Pay Later Source: https://docs.finix.com/guides/online-payments/buy-now-pay-later Buy Now, Pay Later (BNPL) payment methods let buyers split their purchase into installments over time, while merchants are paid immediately and in full. Offering BNPL at checkout can increase conversion rates, boost average order values, and reduce cart abandonment. Finix supports the following BNPL providers: | Provider | Repayment Options | Availability | Recurring Payments | | --- | --- | --- | --- | | **[Afterpay](/guides/online-payments/buy-now-pay-later/afterpay)** | Pay-in-4 (interest-free installments) | US merchants, USD transactions | No (one-time payments only) | ## Why offer BNPL? ### Increase average order value BNPL options encourage buyers to make larger purchases by spreading payments over time. Merchants that offer installment payments at checkout typically see higher average order values. ### Reduce cart abandonment Price is a leading cause of cart abandonment. BNPL removes the friction of paying the full amount upfront, helping more buyers complete their purchase. ### Get paid upfront With BNPL, merchants receive the full payment amount immediately. The BNPL provider handles collecting installment payments from the buyer and absorbs the credit and fraud risk. ### Reach more Buyers BNPL appeals to buyers who prefer not to use traditional credit or who want to manage cash flow across installments. Offering BNPL at checkout gives these buyers a payment option they trust. ## How it works 1. The buyer selects a BNPL payment method at checkout. 2. The buyer is guided through the BNPL provider's authorization flow to review and confirm their installment plan. 3. Once approved, Finix creates a payment instrument and processes the transaction. 4. The merchant receives the full payment amount. The BNPL provider collects installments from the buyer over time. ## Available providers Afterpay Let buyers pay in 4 interest-free installments. Available for US merchants processing USD transactions. --- # Digital Wallets Source: https://docs.finix.com/guides/online-payments/digital-wallets Learn how to integrate Apple Pay, Google Pay, and Cash App Pay with Finix. Finix supports Apple Pay, Google Pay, and Cash App Pay integrations. While integrating into these digital wallets is optional, offering your buyers additional ways to pay can increase conversion and revenue. You can integrate digital wallets into your web or mobile app. Use the guides below to get started. ## Learn more Apple Pay Accept Apple Pay on your website or iOS application using Finix. Google Pay Accept Google Pay on your website or Android application using Finix. Cash App Pay Accept Cash App Pay on your website using Finix. --- # Disabling Instruments Source: https://docs.finix.com/guides/online-payments/fraud-and-risk/disabling-instruments You can disable Payment Instruments to help make seller and buyer data more manageable. ## Disabling Instruments To disable a Payment Instrument, make a `PUT` request setting `enabled` to `false`: Example API Definition Example Payment Instrument - Disabled ```json Payment Instrument - Disabled { "id": "PIwbvcQGrEP33HShmYM7BR8o", "created_at": "2023-02-28T19:05:56.24Z", "updated_at": "2023-02-28T21:16:18.80Z", "application": "APgPDQrLD52TYvqazjHJJchM", "created_via": "API", "currency": "USD", "disabled_code": "USER_INITIATED", "disabled_message": "The card has been disabled by a user.", "enabled": false, "fingerprint": "FPRd5moHxL3Ltuvk4cczxetCg", "identity": "IDpYDM7J9n57q849o9E9yNrG", "instrument_type": "BANK_ACCOUNT", "account_type": "SAVINGS", "bank_account_validation_check": "NOT_ATTEMPTED", "bank_code": "123123123", "country": "USA", "masked_account_number": "XXXXX3123", "name": null, "tags": { "card_name": "Personal Card" }, "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwbvcQGrEP33HShmYM7BR8o" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwbvcQGrEP33HShmYM7BR8o/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwbvcQGrEP33HShmYM7BR8o/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwbvcQGrEP33HShmYM7BR8o/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG" } } } ``` API Definition ## Troubleshooting Transfer and Authorization requests submitted with a disabled Payment Instrument return a `message` stating an enabled Payment Instrument is required and to try again. For details on why a Payment Instrument would fail and get disabled, see [Failure Codes](/additional-resources/developers/implementation-and-testing/failure-codes). ```json Failed Authorization Request { "total": 1, "_embedded": { "errors": [ { "logref": "d6210f60e1102624", "message": "Payment could not be submitted since Payment Instrument PIr247oEh3RScPo2nuNa1d8G is marked as disabled. Please use a Payment Instrument that’s enabled and try again.", "code": "DECLINED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations" } } } ] } } ``` --- # Handling Declined Payments Source: https://docs.finix.com/guides/online-payments/fraud-and-risk/handling-declined-payments Learn why some payments fail and how to handle declines. [Payments](/guides/online-payments) can fail for several reasons. Most times, payments fail because: - [The card issuer declined the payment](#card-declined-by-issuer). - [The payment was attempted in a restricted country and blocked](#restricted-countries). - [The API calls used to make the payment were invalid](#api-calls-declined). When a payment, or `Transfer`, fails: - The `Transfer` gets marked as `FAILED`. - The `Transfer` gets updated to include an ACH return code in `failure_code` and steps you need to take to complete the payment in `failure_message`. For more details, see [Errors](/additional-resources/developers/implementation-and-testing/error-codes/#transfer-and-authorization-errors). - If the payment was a debit, the return of the `Transfer` could indicate a situation where suspicious behavior is involved. Most times you can get the payment processed by confirming the payment details with your buyer and following the steps in `failure_message`. Finix offers several tools to help minimize the risk of declines and ensure payments you process get submitted and completed. ## Card declined by issuer When a charge gets submitted to the issuer of your buyer's card, they have automated systems and models in place that determine whether or not to authorize payments. These systems analyze various signals, such as your customer’s spending habits, account balance, and card information such as the expiration date, address information and CVC. If your customer’s card issuer declines a payment, Finix shares with you the information we receive from the issuer via Finix's `failure_code` and `failure_message`. One common reason card issuers decline payments is because the information used was incorrect, or a bank account couldn't be located using the information provided. Use [Finix's Account Updater](/guides/after-the-payment/account-updater/) to keep the payment information of your buyers correct and up-to-date. Doing so will reduce the likely hood of having a transaction fail due to incorrect information. You can also use our [Card Verification Checks](/guides/online-payments/fraud-and-risk/risk-rules-card-checks) to confirm a card is valid and will process a transaction. Using [3D Secure](/guides/online-payments/fraud-and-risk/3d-secure) and [Level 2/3 processing](/guides/online-payments/payment-features/level-2-level-3-processing) to authenticate transactions can also decrease decline rates by confirming the cardholder's identity at the time of payment. ## Restricted countries Finix supports transactions from all countries (e.g., United States, Canada, United Kingdom, Mexico) except for: - Afghanistan (AF) - Albania (AL) - Belarus (BY) - Burma/Myanmar (MM) - Central African Republic (CF) - Cuba (CU) - Democratic Republic of the Congo (CD) - Ethiopia (ET) - Iran (IR) - Iraq (IQ) - Lebanon (LB) - Libya (LY) - Mali (ML) - Nicaragua (NI) - North Korea aka Democratic People's Republic of Korea (KP) - Russia (RU) - Somalia (SO) - South Sudan (SS) - Sudan (SD) - Syria aka Syrian Arab Republic (SY) - Turkey (TR) - Ukraine (UA) - Venezuela (VE) - Yemen (YE) - Zimbabwe (ZW) Transactions from these high-risk countries will not be accepted and will be blocked at an API level. Finix supports transactions from all other countries in either USD or CAD. ## API calls declined As you develop your integration with Finix, good testing should identify any bugs or requests that would lead to invalid API calls. With good testing in sandbox, these failures should be rare when you take your integration live. Refer to our [API Reference](/api) for a guide on how to make requests to Finix's API. --- # Fraud and Risk Source: https://docs.finix.com/guides/online-payments/fraud-and-risk Learn how to manage fraud and risk when processing payments. Finix offers several solutions to mitigate the risk of fraud and minimize chargeback losses. ## Learn more 3D Secure Authentication Authenticate cardholders and shift chargeback liability to their bank. Disabling Instruments Disable Payment Instruments that are no longer being used. Handling Declined Payments Learn why some payments fail and how to handle declines. Risk Rules / Card Checks Learn how to verify cardholder details to mitigate fraud. --- # Risk Rules and Card Checks Source: https://docs.finix.com/guides/online-payments/fraud-and-risk/risk-rules-card-checks Learn how to verify cardholder details to mitigate fraud. When a payment is submitted to card issuers for authorization, Finix submits the included billing address and Card Verification Code (also referred to as CVC/CVV) data to card issuers to verify this information against the information the card issuer has on file for the cardholder. - For the `address verification` check (also referred to as AVS), the card issuer verifies if the postal code and billing address submitted by Finix matches what the card issuer has on file for the cardholder. - For the `card verification code` (CVC/CVV) check, the card issuer verifies if the security code submitted by Finix in the authorization or sale matches what the card issuer has on file for the cardholder. Finix uses these checks (also called *Risk Rules*) and the data returned from card issuers to review and decline transactions that Finix is unable to verify successfully. Including an `address` when tokenizing a card can lower interchange on credit card transactions. ## Review Verification checks To review an Address or Card Verification Code check, first [create a $0 `Authorization`](/api/authorizations/getauthorization) and then [fetch the `Payment Instrument`](/api/payment-instruments/getpaymentinstrument) that was used in the `Authorization`. The results of the Address and Card Verification Code check are available under the following fields: - `address_verification` - `security_code_verification` For info on how to tokenize a card, see: - [Using Tokenization Forms](/guides/online-payments/payment-tokenization/tokenization-forms) - [Payment Instruments](/api/payment-instruments/createpaymentinstrument) ## Address Verification (AVS) checks | `address_verification` | Description | Transfer Result | | --- | --- | --- | | `POSTAL_CODE_AND_STREET_MATCH` | `postal_code` and `address` match. Includes International cards. | `SUCCEEDED` | | `POSTAL_CODE_MATCH` | `postal_code` matches, `address` doesn’t match or isn’t verified. | `SUCCEEDED` | | `STREET_MATCH` | `address` matches, `postal_code` doesn’t match. | `SUCCEEDED` | | `NO_MATCH` | `address` and `postal_code` don’t match. | `FAILED` | | `NOT_SUPPORTED` | Address Verification isn’t supported by the card issuer. | `SUCCEEDED` | | `NO_ADDRESS` | Address unavailable. | `SUCCEEDED` | | `UNKNOWN` | General error from the card issuer or processor. Address Verification check not performed. | `SUCCEEDED` | ## Card Verification code (CVC/CVV) checks For newly tokenized cards, Card Verification Code is required. You can pass in Card Verification Code with `security_code`. Finix reserves the right to modify Card Verification Check rules. | `security_code_verification` | Description | Transfer Result | | --- | --- | --- | | `MATCHED` | Match | `SUCCEEDED` | | `UNMATCHED` | No Match | `FAILED` | | `UNKNOWN` | This code can come up due to the card issuer, Card Verification Code verification system, or when Card Verification Code isn’t provided. | `SUCCEEDED` | ## Card brand blocking Finix supports blocking specific card brands — for example, preventing American Express cards from being accepted — at the Application level. This configuration cannot be set per-merchant or per-transaction through the API. When a blocked card brand is presented, Finix declines the transaction before it reaches the card network. The buyer sees a standard decline. To request card brand blocking for your Application, contact your Customer Delivery Manager (CDM). --- # Authorize.net Integration Source: https://docs.finix.com/guides/online-payments/gateway-integration/authorize-net Authorize.net, A Visa Solution logo Authorize.net, a Visa-owned payment gateway, connects to hundreds of shopping carts, billing platforms, and software tools. When integrated with Finix, Authorize.net acts as the gateway layer and routes transactions to the card networks, while Finix handles merchant onboarding, settlements, payouts, and reporting. Merchants keep the checkout they already use and manage their payments from the Finix Dashboard. Contact Finix to enable Authorize.net Finix sets up Authorize.net integrations for you. To enable Authorize.net for your business or your merchants, reach out to [Finix Sales](https://finix.com/contact-us) or email [support@finix.com](mailto:support@finix.com). ## Benefits - **Keep your checkout integration:** Continue using any shopping cart, billing system, or invoicing tool that supports Authorize.net. No changes to your buyer-facing checkout are needed. - **One place for payouts and reporting:** Authorize.net transactions settle alongside payments you process directly with Finix, so you reconcile, pay out, and report from a single Finix Dashboard. ## How it works 1. Onboard the merchant with Finix. To learn more, see [Seller onboarding](/guides/platform-payments/onboarding-sellers/seller-onboarding-process). 2. Reach out to Finix to enable Authorize.net. Finix sets up the merchant's Authorize.net account and works with the merchant to activate it and retrieve their Authorize.net credentials. 3. Add the Authorize.net credentials to the merchant's shopping cart or billing platform and begin processing payments through Authorize.net. After that, no additional steps are needed on your end: - Authorize.net routes the transactions to the card networks, while Finix handles merchant onboarding, settlements, payouts, and reporting. - Finix creates a Transfer for each settled transaction, calculates interchange and fees, and includes the transactions in the merchant's Settlements and payouts. You cannot create, void, or refund Authorize.net transactions through the Finix API or the Finix Dashboard. Manage voids and refunds in the Authorize.net Merchant Interface or in your shopping cart. Payments created with the Finix API, Payment Links, or Subscriptions continue to process through Finix directly. ## Locating Authorize.net transactions Once Authorize.net is enabled, transactions processed through Authorize.net are visible in two places: - **Finix** - Each settled Authorize.net transaction creates a Transfer that is visible in the Finix API and the Finix Dashboard. - **Authorize.net** - Transactions are visible in the Authorize.net Merchant Interface as soon as they are submitted. ## Learn more Cybersource Integration Route transactions through Cybersource, Visa's enterprise gateway, with Finix handling onboarding and payouts. Plugins & Partners Connect Finix to the shopping carts, ERPs, and billing platforms your business already uses. Accruing Settlements Learn how Finix groups settled transactions into Settlements and pays out merchants. --- # Cybersource Integration Source: https://docs.finix.com/guides/online-payments/gateway-integration/cybersource Cybersource Hero Cybersource, a Visa-owned payment gateway, enables secure online payments and fraud management. When integrated with Finix, Cybersource acts as the gateway layer, routing transactions to acquiring banks and card networks. Merchants can retain their existing checkout solutions while leveraging Finix’s merchant onboarding, payout features, and dashboard. You can create a Cybersource integration using the [Finix Dashboard](#creating-a-cybersource-integration-using-the-dashboard) or [API](#creating-a-cybersource-integration-using-the-api). Merchants must use a Finix-issued Cybersource account. Existing Cybersource accounts cannot be used, and a new Cybersource account will need to be created with Finix. ## Prerequisites To enable Cybersource for a Finix merchant, create a Gateway Integration [after the merchant is successfully onboarded](/guides/platform-payments/onboarding-sellers/seller-onboarding-process). ## Creating a Cybersource integration using the Dashboard You can create a Cybersource integration using the Finix Dashboard. Direct Merchants 1. In the Finix Dashboard, click **Company**. 2. Click the **Integrations** tab. - Your Cybersource integration status is displayed here. If Cybersource is not enabled, the status shows **Not Connected**. 3. Click **Set Up** to begin the Cybersource integration. Software Platforms 1. In the Finix Dashboard, go to **Merchants** and select the merchant you want to enable Cybersource for. 2. Click the **Account Settings** tab › **Integrations** tab. - The merchant’s Cybersource integration status is displayed here. If Cybersource is not enabled, the status shows **Not Connected**. 3. Click **Set Up** to begin the Cybersource integration. Cybersource Integration - ISV 1. You will be prompted to enter an email address. - To have the Cybersource invitation sent to a *different email* than the one listed on the merchant's `Identity` › `email`, you can enter the desired email here. Otherwise, the invitation will be sent to the pre-populated address. - Click **Next** to send the email invitation to set up your Cybersource dashboard and retrieve your production Transacting ID. See [Invitation Email](#setting-up-cybersource) for next steps. 2. Click **Done** to activate Cybersource as a Gateway Integration and return to the Finix Dashboard. ## Setting up Cybersource After the `Gateway Integration` is created, Cybersource sends an email invitation. You will be prompted to confirm the Organization ID from your invitation email and email address. Click **Submit** to continue the onboarding process. Cybersource Sign Up This email allows the merchant to: - Activate their Cybersource account. - Create login credentials. - Access the CyberSource dashboard. - Obtain a Transacting ID to create transactions. Accept the invitation within 24 hours. If it expires, contact Finix Support to request a new invitation from Cybersource. Invitation Expiration Not accepting the Cybersource email invitation will cause onboarding delays. ## Locating Cybersource transactions Once Cybersource is enabled, transactions processed through Cybersource can be viewed in two locations: - **Finix** - Transfers are visible via the Finix API and dashboard. - **Cybersource** - Transactions are visible in the Cybersource dashboard. Transaction identifiers can be used to reconcile records between Finix and Cybersource. Cybersource allows end users to view transactions only after 24 hours from their creation. ### Locating Cybersource transactions in the Finix Dashboard To check if a transaction was processed by Cybersource, open the Finix Dashboard, go to **Transactions**, click **Payments**, and select the transaction. You can confirm the transaction was processed by Cybersource by checking the Integration Field. Check the **Integration** field in the **Payment Details** section. If Cybersource processed the transaction, the field will display `Cybersource`. Cybersource Integration Field ### Locating transactions in Cybersource Dashboard To locate a transaction in the Cybersource dashboard, you must first copy the Cybersource transaction's `external_trace_id` from the Finix Dashboard. #### 1. Copy the external trace ID from the Finix Dashboard If you are on the payment details page of a Cybersource payment in the Finix Dashboard, skip to the next step. Otherwise, open the Finix Dashboard, go to **Transactions** › **Payments**, and select the transaction. #### Option 1: Copy the external trace ID from the detail page Copy the `external_trace_id` value by hovering over `External Trace ID`. View API Response #### Option 2: Copy the external trace ID from API response Click **View API Response** to view the payment's API response. View API Response Copy the `external_trace_id` value from the API response. Cybersource External Trace ID API Response #### 2. Locate the transaction in the Cybersource Dashboard 1. Expand **Transaction Management** in the left-hand menu. 2. In the **Quick Search** form field, input the External Trace ID copied from the Finix Dashboard and update the **Date Range** to match. 3. Click **Search** to view the transaction details. ## Voiding a Cybersource transaction To void a Cybersource authorization, perform an authorization reversal directly in the Cybersource Dashboard. 1. [Locate the transaction in the Cybersource Dashboard](#locating-transactions-in-cybersource-dashboard). 2. On the **Transaction Details** page, click **Authorization reversal**. 3. Confirm the authorization reversal when prompted. ## Creating a Cybersource integration using the API You can also create a Cybersource integration using the Finix API instead of the [Dashboard](#creating-a-cybersource-integration-using-the-dashboard). ### 1. Create a gateway integration After [onboarding a merchant](/guides/platform-payments/onboarding-sellers/seller-onboarding-via-api), [create a Gateway Integration](/api/gateway-integrations/creategatewayintegration) to send an onboarding request to Cybersource. Provide the email address to receive the Cybersource dashboard invitation, which allows you to retrieve your Cybersource transacting credentials. Example API Definition A successful request returns a `201 Created` status code, with the response body containing the newly created `Gateway Integration` resource with a `state: PENDING`: Example Gateway Integration ```json Gateway Integration { "id": "gateway_integration_j1KV2mwRgA8pSGGrWWVijc", "created_at": "2026-05-22T01:41:01.30Z", "updated_at": "2026-05-22T01:41:01.30Z", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "email": "user@example.com", "linked_to": "MUeg77opgdgQpwejzC9wCNmK", "linked_type": "MERCHANT", "state": "PENDING", // [!code highlight] "tags": { "gateway_name": "shopify" }, "type": "CYBERSOURCE", // [!code highlight] "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/gateway_integrations/gateway_integration_j1KV2mwRgA8pSGGrWWVijc" } } } ``` API Definition The `Gateway Integration` remains in a pending state (i.e., `Gateway Integration` › `state` is `PENDING`) until Cybersource approves the `Merchant`, after which the `state` changes to `SUCCEEDED`. If there are issues with the onboarding request, the state changes to `FAILED`, and Finix Support will contact you to update any required information. Finix will [send a webhook event](/additional-resources/developers/webhooks/webhook-events#gateway-integration-updated) and update the dashboard whenever the state changes. ### 2. Accept the Cybersource email invitation After the `Gateway Integration` is created, Cybersource sends an email invitation to the address provided in the request. See [Cybersource Email Invitation](#setting-up-cybersource) for next steps. --- # Gateway Integrations Source: https://docs.finix.com/guides/online-payments/gateway-integration Finix supports two gateway integrations that work alongside the Finix REST API and no-code and low-code products. These gateways connect to hundreds of ecommerce checkout and ERP solutions. Finix supports Cybersource (the recommended gateway) and Authorize.net. Finix handles processing, settlements, reconciliation, reporting, and payouts. - **Keep your checkout:** Preserve your existing gateway configuration, plugins, and partner integrations. Your buyer-facing checkout does not change. - **Unified back-end:** Use the Finix platform for settlements, reconciliation, reporting, and payouts alongside your gateway, without replacing your checkout integration. - **See settled transactions in one place:** Settled gateway payments appear in the Finix Dashboard next to your Payment Links, Subscriptions, Invoices, and in-person terminals. - **Add products later:** Onboard once, then add no-code, low-code, and API products to the same Merchant account as needed. - **Built for Software Platforms:** Onboard merchants through Finix and enable a gateway integration only for the merchants who need one. Available now Gateway integrations are available to new and existing Finix customers. To add a gateway to your account or to learn what a move to Finix looks like, reach out to [Finix Sales](https://finix.com/contact-us) or your Finix point of contact. ## Supported gateways Cybersource Visa's enterprise gateway with 100+ partner integrations, including Shopify, Salesforce, NetSuite, BigCommerce, and Adobe Commerce. Set up from the Finix Dashboard or with a single API call. Authorize.net Visa's gateway for small and mid-sized businesses, connected to hundreds of shopping carts, billing platforms, and business tools. Contact Finix to enable it for your business or your merchants. ## Get started Set Up Cybersource For Finix customers with Cybersource-connected software. Link your Merchant from the Finix Dashboard or the Finix API. Enable Authorize.net Learn how Authorize.net works with Finix, then contact Finix to enable it for your business or your merchants. Talk to Finix Sales For businesses new to Finix. Finix walks you through onboarding and gateway setup. ## Available integrations Cybersource connects Finix to the platforms below. Each guide walks you through connecting the platform to your Cybersource account so payments settle and pay out through Finix. For the full partner directory, see [Plugins & Partners](/additional-resources/plugins). Shopify Accept card payments on your Shopify store. Odoo Accept card payments in Odoo ERP and ecommerce. BigCommerce Accept card payments on your BigCommerce store. Adobe Commerce Accept card payments on your Adobe Commerce (Magento) store. ## Learn more Finix Launches Cybersource Integration Why Finix built gateway integrations and what merchants gain from modernizing without a migration. Plugins & Partners Step-by-step guides for Shopify, Salesforce, NetSuite, BigCommerce, Adobe Commerce, and other gateway-connected platforms. Gateway Integrations API Create and retrieve Gateway Integrations with the Finix API. Webhook Events Subscribe to Gateway Integration created and updated events. Accruing Settlements Learn how Finix groups settled transactions into Settlements and pays out merchants. --- # Auth and Captures Source: https://docs.finix.com/guides/online-payments/payment-features/auth-and-captures Learn how to authorize funds on a card before making a payment. An `Authorization` (also known as a card hold) reserves a specific amount on the card, confirming that the buyer's payment method has sufficient funds to cover the transaction. All authorizations must be captured (i.e., debited) within seven days. ## Creating an Authorization To create an authorization: - Use the `Payment Instrument` ID provided by Finix as the `source`. - Use the seller's `Merchant` ID as the `merchant` for the authorization. ### Request Example API Definition ### Response 201 Created - Authorization Created A successful request returns a `201 Created` status code, with the response body containing: - an `expires_at` timestamp for its expiration - the authorization's `state` as `SUCCEEDED` Example Authorization ```json Authorization { "id": "AUbnRuZ3jpApRxGBukigsXai", "created_at": "2026-09-25T20:04:56.95Z", "updated_at": "2026-09-25T20:04:56.95Z", "3d_secure_session": null, "3ds_redirect_url": null, "additional_buyer_charges": { // [!code highlight] "convenience_amount": 10, "surcharge_amount": 0, "rent_surcharge_amount": 0 }, "additional_healthcare_data": { // [!code highlight] "clinic_amount": 50, "dental_amount": 200, "prescription_amount": 300, "vision_amount": 300 }, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": { // [!code highlight] "customer_reference_number": "PO-2024-3842", "customs_duty_amount": 10, "destination_country_code": null, "destination_postal_code": null, "discount_amount": 100, "invoice_reference_number": null, "order_date": null, "sales_tax": null, "sales_tax_finix_generated": 200, "ship_from_postal_code": null, "shipping_amount": 100, "tax_exempt": false, "item_data": [ { "cost_per_unit": 500, "item_description": "Consulting Services", "item_discount_amount": 100, "merchant_product_code": "SKU 12312", "quantity": 1, "amount_excluding_sales_tax": 400, "amount_including_sales_tax": 500, "unit_of_measure": "BX", "commodity_code": "175-62-20", "sales_tax_amount": 100, "sales_tax_rate": 0.25 }, { "cost_per_unit": 500, "item_description": "GPT-5.6", "item_discount_amount": 0, "merchant_product_code": "SKU 2222", "quantity": 1, "amount_excluding_sales_tax": 400, "amount_including_sales_tax": 500, "unit_of_measure": "CTN", "commodity_code": "207-72-54", "sales_tax_amount": 100, "sales_tax_rate": 0.25 } ] }, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 10000, "amount_requested": 10000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "USD", "expires_at": "2026-10-05T20:04:56.95Z", // [!code highlight] "failure_code": null, "failure_message": null, "idempotency_id": null, "ip_address_details": null, "is_void": false, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "messages": [], "network_details": { "brand": "VISA", "authorization_code": "908105" }, "raw": null, "receipt_last_printed_at": null, "security_code_verification": "MATCHED", "source": "PIkxmtueemLD6dN9ZoWGHT44", "state": "SUCCEEDED", // [!code highlight] "supplemental_fee": null, "tags": { "order_id": "ORD-123" }, "trace_id": "453af9f5-5016-40c6-9e3c-efcddbe45d7b", "transfer": null, "void_state": "UNATTEMPTED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUbnRuZ3jpApRxGBukigsXai" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" } } } ``` API Definition Authorization Expiration The authorization must be captured before the `expires_at` time passes, or the funds will be released. If `transfer` is `null`, the authorization has not been captured yet. ## Capturing an Authorization Capture the succeeded authorization when you're ready to debit the buyer's `Payment Instrument`. [Capturing an authorization](/api/authorizations/captureauthorization) initiates the movement of funds. ### Request Example API Definition ### Response 200 OK - Authorization Capture Submitted A successful request returns a `200 OK` status code, and the response body contains a `transfer` property that corresponds to the ID of the `Transfer` resource created to debit funds. Example Captured Authorization ```json Captured Authorization { "id": "AUbWeT4YfQRgjKwfXk1pwb5E", "created_at": "2026-09-25T20:36:20.39Z", "updated_at": "2026-09-25T20:36:21.28Z", "3d_secure_session": null, "3ds_redirect_url": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": null, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 10000, "amount_requested": 10000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "USD", "expires_at": "2026-10-05T20:36:20.39Z", "failure_code": null, "failure_message": null, "idempotency_id": null, "ip_address_details": null, "is_void": false, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "messages": [], "network_details": { "brand": "VISA", "authorization_code": "004086" }, "raw": null, "receipt_last_printed_at": null, "security_code_verification": "MATCHED", "source": "PIkxmtueemLD6dN9ZoWGHT44", "state": "SUCCEEDED", // [!code highlight] "supplemental_fee": null, "tags": {}, "trace_id": "6aa71f62-504c-40e3-8598-c074f98b3183", "transfer": "TRj2ac3ocT3UKfSCvNt2eGFr", // [!code highlight] "void_state": "UNATTEMPTED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUbWeT4YfQRgjKwfXk1pwb5E" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "transfer": { "href": "https://finix.sandbox-payments-api.com/transfers/TRj2ac3ocT3UKfSCvNt2eGFr" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" } } } ``` API Definition ### Next steps - Use the [Fetch the Transfer](/api/transfers/gettransfer) endpoint with its ID to check the `state` of the `Transfer` when it will be ready to settle or to view its details. - Settle the `Transfer` (see [Seller Payouts](/guides/platform-payments/seller-payouts)). ## Void an Authorization As opposed to `Transfers` which can only be reversed or refunded, [authorizations can be voided](/api/authorizations/voidauthorization) to release funds and stop a transaction from completing. ### Request Example API Definition ### Response 200 OK - Authorization Voided A successful request returns a `200 OK` status code, and the response body indicates the `void_state` transitioned from `UNATTEMPTED` to `PENDING`. When the `Authorization` is voided, the `void_state` updates to `SUCCEEDED`. Example Voided Authorization ```json Voided Authorization { "id": "AU7gwXbxWSWHhGjqz6HGtXPV", "created_at": "2026-09-25T20:36:23.45Z", "updated_at": "2026-09-25T20:36:24.09Z", "3d_secure_session": null, "3ds_redirect_url": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": null, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 10000, "amount_requested": 10000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "USD", "expires_at": "2026-10-05T20:36:23.45Z", "failure_code": null, "failure_message": null, "idempotency_id": null, "ip_address_details": null, "is_void": true, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "messages": [], "network_details": { "brand": "VISA", "authorization_code": "064062" }, "raw": null, "receipt_last_printed_at": null, "security_code_verification": "MATCHED", "source": "PIkxmtueemLD6dN9ZoWGHT44", "state": "SUCCEEDED", "supplemental_fee": null, "tags": {}, "trace_id": "1b0d63c1-797a-4521-879a-d55ad8333c7d", "transfer": null, "void_state": "PENDING", // [!code highlight] "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AU7gwXbxWSWHhGjqz6HGtXPV" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" } } } ``` API Definition If an `Authorization` is voided, it can no longer be captured. --- # Collecting Tips Source: https://docs.finix.com/guides/online-payments/payment-features/collecting-tips Learn how to include tips when processing payments. Sellers can easily collect tips with Finix while processing both: - [Online Payments](#tipping-online-payments) - [In-Person Payments](#tipping-in-person-payments) ## Tipping online Payments There are two ways to collect tips while processing Online Payments. Both methods rely on when and how the tip is requested from the cardholder. - If the seller wants [to collect the tip while the buyer makes their payment,](#time-of-payment) include the tip in `amount` when creating the `Authorization` or `Transfer`. This is the most common method of collecting tips when processing Online Payments. - If the seller wants [to collect the tip after providing a service or good,](#after-the-payment) first create an `Authorization` to verify funds are available. Then create a `Transfer` that includes the tip in `amount` along with the cost of the transaction. ### Time of payment Here's an example of a `Transfer` that processes a $20 transaction with a $2 tip. The `amount` represents the total amount (cost of the goods or services + tip) that's collected from the cardholder. To track the tip within Finix, create a tag. Include the part of the `amount` that is a tip in the `tags` field like the example below. Example API Definition ### After the payment To collect the tip after a service or good is provided, first create an `Authorization` to confirm the `Payment Instrument` has enough funds. Below is an example of a transaction that is $22 and will be collecting a tip of $8. The first `Authorization` assumes a general tip of $5. ```shell curl https://finix.sandbox-payments-api.com/authorizations \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X POST \ -d '{ "amount": 2700, "currency": "USD", "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "source": "PIe2YvpcjvoVJ6PzoRPBK137" }' ``` After the service or good is provided, if the total `amount` with the tip included is: | | | | --- | --- | | Less than the initial `Authorization` | [Capture the initial `Authorization`](/guides/online-payments/payment-features/auth-and-captures#capturing-an-authorization) for that smaller `amount`. | | Greater than the initial `Authorization` | [Void the initial `Authorization`](/guides/online-payments/payment-features/auth-and-captures#void-an-authorization), and create a `Transfer` for that greater `amount`. | If the buyer tips $8, here's the `Transfer` you create after voiding the initial `Authorization`. Include the tip the buyer provided in `amount` (cost of the goods or services + tip). To track the tip within Finix, create a tag. Include the part of the `amount` that is a tip in the `tags` field like the example below. Example API Definition ## Tipping In-Person Payments There are two ways to collect tips while processing In-Person Payments: | | | | --- | --- | | [Tipping on the Receipt](#tipping-on-the-receipt) | The tip is collected when the initial `Authorization` is captured. The buyer usually writes the tip on the receipt; this is one of the most widely used options to collect tips. | | [Tipping on Point of Sale Software](#tipping-in-person-payments) | The buyer enters the tip on your point-of-sale software or app. The buyer usually enters the tip on a tablet like an iPad or an Android device. | ### Tipping on the receipt To collect a tip on a receipt: | | | | --- | --- | | 1. [Create an `Authorization`](#create-an-authorization) | Create an `Authorization` for the transaction `amount`. | | 2. [Collect the buyer's tip](#collect-the-tip) | At a later point, collect the buyer's tip either digitally or from the receipt. | | 3. [Capture the `Authorization`](#capture-the-authorization) | Capture the `Authorization` for the transaction `amount` including the tip. | #### Create an Authorization The following authorizes a `Payment Instrument` for a restaurant bill of $20. This `amount` doesn't include the buyer's tip. ```shell curl https://finix.sandbox-payments-api.com/authorizations \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X POST \ -d '{ "amount": 2000, "currency": "USD", "device": "DVf2H8sh4LZZC52GTUrwCPPf", "operation_key": "CARD_PRESENT_AUTHORIZATION" }' ``` A successful response returns a 200 and the newly created `Authorization` resource. ```json { "id": "AUarp7Pz21Low4u2Urw5Ub4W", "created_at": "2019-04-29T20:44:00.13Z", "updated_at": "2022-10-10T05:59:17.59Z", "3ds_redirect_url": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "address_verification": null, "amount": 2000, "amount_requested": 2000, "application": "APeUbTUjvYb1CdPXvNcwW1wP", "capture_amount": null, "card_present_details": { "emv_data": { "application_identifier": "A0000001523010", "application_label": "DISCOVER", "application_preferred_name": null, "application_transaction_counter": "0005", "cryptogram": "ARCQ F666F8891F870D33", "issuer_code_table_index": null, "pin_verified": false, "tags": null }, "masked_account_number": "************0059", "name": "Test Card 05", "brand": "DISCOVER", "entry_mode": "CHIP_ENTRY", "payment_type": "CREDIT", "approval_code": "004839" }, "currency": "USD", "device": "DVfKLD9GZtsjcJxLtc2yCcfd", "expires_at": "2019-05-06T20:44:00.13Z", "failure_code": null, "failure_message": null, "idempotency_id": null, "is_void": false, "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDsbTBawhnLBAVeinRb84vFR", "messages": [], "raw": null, "security_code_verification": null, "source": "PImTHaz7XVPx4M7mhu9x8gkU", "state": "SUCCEEDED", "tags": { "TicketNumber": "45878" }, "trace_id": "FNX35FSuraeKKJr65wkGVFJni", "transfer": "TRqQCAX7nYHUnkE5YPFTknqd", "void_state": "UNATTEMPTED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUbrumLihwhdLixtbU1mfMiF" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "transfer": { "href": "https://finix.sandbox-payments-api.com/transfers/TRs6APHuUAvSYq2FfTDkb5d8" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg" } } } ``` #### Collect the tip Collect the dollar amount of the tip from the *Tip* written on the receipt, or from the tip the buyer entered into your app. If you are using a `FINIX_V1` / `DUMMY` terminal with printing capabilities, you can enable/disable the tip field on the receipt with the below API call: ```shell curl https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X PUT \ -d '{ "configuration": { "display_tip_on_receipt": true } }' ``` #### Capture the Authorization Capture the `Authorization` with the tip included in `capture_amount`. The `capture_amount` should include the total amount of funds you’d like to collect from the cardholder. In this example, the cardholder tipped $2, so the `capture_amount` for a $20 bill will be $22. We also capture the tip amount in the `tags` to track and record. ```shell curl https://finix.sandbox-payments-api.com/authorizations/AUarp7Pz21Low4u2Urw5Ub4W \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X PUT \ -d '{ "capture_amount": 2200, "tags": { "tip": "200" } }' ``` A successful response returns a 200 and the `Authorization` resource. ```json { "id": "AUarp7Pz21Low4u2Urw5Ub4W", "created_at": "2022-10-06T20:22:42.25Z", "updated_at": "2022-10-07T17:09:22.85Z", "3ds_redirect_url": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 2200, "amount_requested": 2200, "tip": 200, "application": "APgPDQrLD52TYvqazjHJJchM", "currency": "USD", "expires_at": "2022-10-13T20:22:42.25Z", "failure_code": null, "failure_message": null, "idempotency_id": null, "is_void": false, "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg", "messages": [], "raw": null, "security_code_verification": "MATCHED", "source": "PIe2YvpcjvoVJ6PzoRPBK137", "state": "SUCCEEDED", "tags": { "tip": "200" }, "trace_id": "2724719e-6cc4-4cba-a859-2e6ac0bffb9b", "transfer": "TRs6APHuUAvSYq2FfTDkb5d8", "void_state": "UNATTEMPTED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUbrumLihwhdLixtbU1mfMiF" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "transfer": { "href": "https://finix.sandbox-payments-api.com/transfers/TRs6APHuUAvSYq2FfTDkb5d8" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg" } } } ``` --- # HSA / FSA Cards Source: https://docs.finix.com/guides/online-payments/payment-features/fsa-and-hsa-cards Learn how to accept Health Savings Account (HSA) or Flexible Spending Account (FSA) cards with Finix. HSA (Health Savings Account) and FSA (Flexible Spending Account) cards are prepaid debit cards linked to tax-advantaged accounts that consumers use to pay for qualified medical expenses (prescriptions, doctor visits, medical equipment, etc.). To accept HSA and FSA cards, a merchant must meet **one** of the following requirements: - a healthcare-related [Merchant Category Code (MCC)](#healthcare-related-merchant-category-codes-mccs) has been obtained, or - the merchant has met the [requirements for processing HSA and FSA cards with a non-healthcare MCC](#non-healthcare-mcc-requirements). Requesting API access for Non-healthcare MCC To access the APIs used to process non-healthcare MCC transactions, contact your Finix point of contact or [Finix Support](/guides/getting-started/support-at-finix) Accepting HSA or FSA payments does not ensure cards will get processed successfully. Like other transactions, card issuers ultimately decide to authorize or decline a payment. ## Healthcare-Related Merchant category codes (MCCs) Medical service providers with one of the following MCCs can process transactions made with HSA and FSA cards **without** Special Interest Group for IIAS Standards (SIGIS) registration and Inventory Information Approval System (IIAS) certification. | Merchant Category Code (MCC) | Description | | --- | --- | | 4119 | Ambulance Services (Dependent on Plan Administrator) | | 5047 | Medical, Dental, Ophthalmic, and Hospital Equipment and Supplies | | 5975 | Hearing Aids - Sales, Service, Supply Stores | | 7277 | Counseling Service - Debt, Marriage, and Personal (Dependent on Plan Administrator) | | 8011 | Doctors and Physicians (not elsewhere classified) | | 8021 | Dentists, Orthodontists | | 8031 | Osteopaths | | 8041 | Chiropractors | | 8042 | Optometrists, Ophthalmologists | | 8043 | Opticians, Optical Goods, and Eyeglasses | | 8049 | Podiatrists and Chiropodists | | 8050 | Nursing and Personal Care Facilities | | 8062 | Hospitals | | 8071 | Medical and Dental Laboratories | | 8099 | Health Practitioners, Medical Services (not elsewhere classified) | ## Non-Healthcare MCC requirements To accept HSA and FSA cards with a non-healthcare MCC, the merchant needs a SIGIS registration and IIAS certification. *Here’s how to process HSA and FSA cards with a non-healthcare MCC:* 1. The merchant submits their registration directly to SIGIS for approval. 2. The merchant must certify with Finix support engineers that they can pass the required additional healthcare data fields in their transactions. 3. After SIGIS approves the merchant’s registration, Finix registers with Visa and Mastercard to obtain a Visa Merchant Verification Value (MVV) and MCID (Mastercard Assigned ID). This process takes about 3 to 4 weeks. For questions about non-healthcare MCC requirements, contact your Finix point of contact or [Finix Support](/guides/getting-started/support-at-finix). ## Making a payment with HSA or FSA cards How you make payments with HSA or FSA cards depends on whether the merchant has a healthcare-related MCC or a non-healthcare-related MCC. - **Healthcare-related MCC transactions** - If the merchant has a [healthcare MCC](#healthcare-related-merchant-category-codes-mccs), they do not need to provide healthcare data in their transactions. Follow the standard process for sending [Transfer](/api/transfers/createtransfer) and [Authorizations](/api/authorizations/createauthorization) requests using the API. - **Non-healthcare-related MCC transactions** - To accept HSA and FSA cards with a non-healthcare MCC, the merchant needs a SIGIS registration and IIAS certification before processing payments. --- # Payment Features Source: https://docs.finix.com/guides/online-payments/payment-features Finix has several features available that helps extend the functionality of your payments experience. ## Learn more Auth and Captures Learn how to authorize funds on a card before making a payment. Accept HSA or FSA Cards Learn about accepting HSA and FSA cards. Collecting Tips Learn how to include tips when processing payments. Buyer Charges Charge additional fees using Buyer Charges. Level 2 / Level 3 Processing Capture more information to reduce interchange rates. Sending Receipts Learn how to provide receipts for In-Person payments. Split Transactions Learn how to split a transaction across multiple sellers or recipients. --- # Level 2 / Level 3 Processing Source: https://docs.finix.com/guides/online-payments/payment-features/level-2-level-3-processing Card payment processing has three levels: Level 1, Level 2, and Level 3. Level 2 and Level 3 processing allows eligible business-to-business (B2B) merchants to qualify for lower interchange rates by submitting additional purchase data alongside Visa and Mastercard transactions. Level 2 / Level 3 Processing is available for: - [Transfers](#create-a-sale-with-level-2-processing) - [Authorizations](#create-an-authorization-with-level-2-processing) - [Payment Links](/low-code-no-code/payment-links/quickstart-dashboard) ## Availability - Available for merchants located in the **United States** processing **USD** transactions. - Only available in **Live** environments. Not available in Sandbox. ## Eligibility ### Card networks that support Level 2 / Level 3 Processing - **Mastercard**: Supports Level 2 and Level 3 processing. - **Visa**: Supports Level 3 processing only. | Network | Level 2 | Level 3 | | --- | --- | --- | | Visa | ⚠️ Deprecated April 17, 2026 | Yes | | Mastercard | Yes | Yes | ### Eligible Merchant types Only business-to-business (B2B) merchants and government entities qualify for lower interchange rates. [The merchant must be enabled](#enable-level-2--level-3-processing) for Level 2 / Level 3 processing. Corporate and purchase credit cards are eligible for Level 2 and Level 3 processing. Consumer cards are only eligible for Level 1 processing. Ineligible Merchants Some businesses are not eligible for Level 2 and Level 3 transaction processing. For details, see our list of [ineligible Merchant Category Codes (MCC)](#ineligible-merchants). ### Data Quality An eligible Merchant Category Code (MCC) alone does not guarantee interchange qualification. Card networks also evaluate the accuracy of submitted data. See Finix's [Data Quality](#data-quality-best-practices) best practices for Level 2 / Level 3 processing. ### Tax Exemption Tax-exempt transactions are not eligible for Level 2. Tax-exempt transactions are eligible for Level 3 when you pass `tax_exempt: true` and omit `sales_tax`. ## Minimum Field Requirements The table below summarizes the minimum fields required to qualify for Level 2 and Level 3 interchange rates. The card network and cardholder issuing bank ultimately determine whether a transaction qualifies. | L2 or L3 Rates Eligibility | Level 2 | Level 3 | | --- | --- | --- | | **Minimum Field Requirements** | - `customer_reference_number` - `sales_tax` | - Everything in Level 2: - `shipping_amount` - `customs_duty_amount` - `discount_amount` - Plus `item_data` for each line item: - `item_description` - `cost_per_unit` - `quantity` - `commodity_code` - `merchant_product_code` - `unit_of_measure` - `amount_excluding_sales_tax` - `amount_including_sales_tax` - `item_discount_amount` | ### Level 2 fields | Field | API Field | Required | Description | | --- | --- | --- | --- | | **Customer Reference Number** | `customer_reference_number` | Required | A unique reference ID for the order such as a purchase order (PO) number or invoice number. A purchase order number (PO number) is a unique code assigned to a specific order of goods or services. The buyer creates this number when they make a purchase order. It helps both the buyer and the seller track the order, match invoices, and keep accurate financial records. (max `17` characters) | | **Sales Tax** | `sales_tax` | Required | The total tax amount for the transaction in cents. Must be greater than 0.1% of the transaction amount. For non-taxable transactions, set to `0` and set `tax_exempt` to `true`. | ### Level 3 fields Everything in Level 2, plus: | Field | API Field | Required | Description | | --- | --- | --- | --- | | **Shipping Amount** | `shipping_amount` | Required | The costs related to shipping and handling in cents. Must be at least `0`. | | **Customs Duty Amount** | `customs_duty_amount` | Required | The costs related to import or export duties in cents. Must be at least `0`. | | **Discount Amount** | `discount_amount` | Required | The order-level discount amount in cents. Must be at least `0`. | | **Tax Exempt** | `tax_exempt` | Optional | Set to `true` for tax-exempt purchases. | Plus `item_data` fields for each line item: | Field | API Field | Required | Description | | --- | --- | --- | --- | | **Item Description** | `item_description` | Required | A short, human-readable description of the line item (max `25` characters). | | **Cost per Item** | `cost_per_unit` | Required | The price per unit of the item purchased, in cents. | | **Item Discount** | `item_discount_amount` | Required | The discount amount in cents applied to this individual line item. For an order-level discount, use `discount_amount`. | | **Quantity** | `quantity` | Required | The number of units purchased. Must be greater than `0`. | | **Unit of Measure** | `unit_of_measure` | Required | The unit of measure for the item (max `3` characters). | | **Commodity Code** | `commodity_code` | Required | A numeric code identifying the product or service (`3`, `5`, `7`, or `11` digits; max `12` characters). | | **Merchant Product Code** | `merchant_product_code` | Required | Your product/SKU code for the line item (max `12` characters). | | **Amount Excluding Sales Tax** | `amount_excluding_sales_tax` | Required | Total cost of the line item excluding tax in cents (must be greater than `0`). | | **Amount Including Sales Tax** | `amount_including_sales_tax` | Required | Total cost of the line item including tax in cents (must be greater than `0`). | ## Enable Level 2 / Level 3 Processing Before a Merchant can process Level 2 or Level 3 transactions, send a PUT /merchants/{merchant_id} request to enable Level 2 / Level 3 processing. ### Request Example API Definition ### Response A successful request returns a `200 OK` status code and includes a Merchant resource with `level_two_level_three_data_enabled: true`. Example Merchant - Level 2/3 Processing Enabled ```json Merchant - Level 2/3 Processing Enabled { "id": "MUiV7ntxfY4eyJxp6E7cZvym", "created_at": "2026-04-03T22:05:19.34Z", "updated_at": "2026-09-25T20:05:19.51Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "card_cvv_required": false, "card_expiration_date_required": true, "card_network_details": null, "convenience_charges_enabled": true, "country": "USA", "creating_transfer_from_report_enabled": false, "currencies": [ "USD" ], "default_partial_authorization_enabled": false, "disbursements_ach_pull_enabled": true, "disbursements_ach_push_enabled": true, "disbursements_card_pull_enabled": true, "disbursements_card_push_enabled": true, "disbursements_same_day_ach_pull_enabled": false, "disbursements_same_day_ach_push_enabled": false, "fee_ready_to_settle_upon": "PROCESSOR_WINDOW", "first_approved_at": "2026-04-03T22:06:04.00Z", "gateway": null, "gross_settlement_enabled": false, "identity": "IDa4fdEuy57uLT95prqoBDxx", "instant_payouts_card_push_enabled": false, "is_terminated": false, "level_two_level_three_data_enabled": true, // [!code highlight] "loan_repayment": null, "mcc": "4900", "merchant_name": "Finix Flowers", "merchant_profile": "MP6pzw61XykboCKVbMhCgYuk", "microdeposit_verification_required_buyer": false, "microdeposit_verification_required_sender": false, "mid": "FNXwXimxKRxzJ34EX4bAcv6q3", "onboarding_state": "APPROVED", "pending_refunds_strategy": "NONE", "processing_enabled": true, "processor": "DUMMY_V1", "processor_details": { "mid": "FNXwXimxKRxzJ34EX4bAcv6q3", "api_key": "secretValue" }, "ready_to_settle_upon": "PROCESSOR_WINDOW", "ready_to_settle_upon_delay_alignment": "NONE", "refunds_disabled": false, "rent_surcharges_enabled": false, "settlement_enabled": true, "settlement_funding_identifier": "UNSET", "settlement_queue_mode": "MANUAL", "surcharges_enabled": false, "tags": { "key_2": "value_2" }, "termination_details": null, "unreferenced_refund_card_present_enabled": false, "unreferenced_refund_manual_entry_enabled": false, "verification": "VIeDkhAdS91Cw4Hu324YR6Te", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/merchants/MUiV7ntxfY4eyJxp6E7cZvym" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDa4fdEuy57uLT95prqoBDxx" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/merchants/MUiV7ntxfY4eyJxp6E7cZvym/verifications" }, "merchant_profile": { "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MP6pzw61XykboCKVbMhCgYuk" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "verification": { "href": "https://finix.sandbox-payments-api.com/verifications/VIeDkhAdS91Cw4Hu324YR6Te" } } } ``` API Definition Once `level_two_level_three_data_enabled` is updated to `true`, the Merchant resource can process [Level 2 and Level 3 Transfers and Authorizations](#create-a-sale-with-level-2-processing). - There are no changes in the post-payment experience (reversals, refunds, settlements, etc.) when processing Level 2 or Level 3 transactions. - The [fields noted as required](#minimum-field-requirements) are the minimum needed for Level 2 or Level 3 interchange rates. There's no additional benefit in passing every available field for a given level. - The sales tax amount must be greater than 0.1% of the transaction amount. - For tax-exempt transactions, pass `tax_exempt` as `true` and omit `sales_tax`. ## Create a Sale with Level 2 processing Send a POST /transfers request and include the required fields for Level 2 processing. ### Level 2 Fields Include the following fields within the `additional_purchase_data` object: | Field | API Field | Type | Description | | --- | --- | --- | --- | | **Customer Reference Number** | `customer_reference_number` | *string*, **required** | A unique reference ID for the order such as a purchase order (PO) number or invoice number. A purchase order number (PO number) is a unique code assigned to a specific order of goods or services. The buyer creates this number when they make a purchase order. It helps both the buyer and the seller track the order, match invoices, and keep accurate financial records. (max `17` characters) | | **Sales Tax** | `sales_tax` | *integer*, **required** | Total aggregate tax amount in cents for the entire purchase. Field is automatically calculated if you pass in the itemized tax amounts. For non-taxable transactions either set `sales_tax` to `0` or omit from payload and also set `tax_exempt` to `true`.` | ### Request ```shell curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/transfers \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "additional_purchase_data": { "customer_reference_number": "PO-2024-3842", "sales_tax": 200 }, "amount": 10000, "currency": "USD", "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "source": "PIs3rzrjP9orEjBwtJjhxEjL", "tags": { "order_id": "ORD-123" } }' ``` ### Response A successful request returns a `201 Created` status code and includes a Transfer resource with Level 2 processing details: Example Transfer - Level 2 Processing ```json Transfer - Level 2 Processing { "id": "TRhxcLi5xeLc6S6cw15RFFFe", "created_at": "2026-09-25T20:05:58.23Z", "updated_at": "2026-09-25T20:05:58.23Z", "3d_secure_session": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": { "customer_reference_number": "PO-2024-3842", // [!code highlight] "customs_duty_amount": null, "destination_country_code": null, "destination_postal_code": null, "discount_amount": null, "invoice_reference_number": null, "order_date": null, "sales_tax": 200, // [!code highlight] "sales_tax_finix_generated": null, "ship_from_postal_code": null, "shipping_amount": null, "tax_exempt": false, "item_data": [] }, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 10000, "amount_requested": 10000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "USD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj", "idempotency_id": null, "ip_address_details": null, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "messages": [], "network_details": { "brand": "MASTERCARD", "authorization_code": "179463", "acquirer_reference_number": "79996936117050932176855" }, "operation_key": "CARD_NOT_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "processed_at": "2026-09-25T20:05:58.57Z", "raw": null, "ready_to_settle_at": "2026-09-26T20:05:58.23Z", "receipt_last_printed_at": null, "security_code_verification": "MATCHED", "source": "PIs3rzrjP9orEjBwtJjhxEjL", "split_transfers": [], "state": "SUCCEEDED", "statement_descriptor": "FLX*FINIX FLOWERS", "subtype": "API", "supplemental_fee": null, "tags": { "order_id": "ORD-123" }, "third_party_details": null, "tip_amount": null, "trace_id": "4c050b39-9589-4253-b3b6-f71428629e22", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhxcLi5xeLc6S6cw15RFFFe" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhxcLi5xeLc6S6cw15RFFFe/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhxcLi5xeLc6S6cw15RFFFe/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRhxcLi5xeLc6S6cw15RFFFe" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhxcLi5xeLc6S6cw15RFFFe/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIs3rzrjP9orEjBwtJjhxEjL" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj" } } } ``` API Definition ## Create a Sale with Level 3 processing Send a POST /transfers request and include the required fields for Level 3 processing. ### Level 3 Fields Include the following `additional_purchase_data` fields: | Field | API Field | Type | Description | | --- | --- | --- | --- | | **Customer Reference Number** | `customer_reference_number` | *string*, **required** | A unique reference ID for the order such as a purchase order (PO) number or invoice number. A purchase order number (PO number) is a unique code assigned to a specific order of goods or services. The buyer creates this number when they make a purchase order. It helps both the buyer and the seller track the order, match invoices, and keep accurate financial records. (max `17` characters) | | **Customs Duty Amount** | `customs_duty_amount` | *integer*, **required** | The costs related to import or export duties in cents. This field must have a value of at least `0`. | | **Discount Amount** | `discount_amount` | *integer*, **required** | The amount in cents of the discount for the order. This field must have a value of at least `0`. | | **Shipping Amount** | `shipping_amount` | *integer*, **required** | The costs related to shipping and handling in cents. This field must have a value of at least `0`. | | **Tax Exempt** | `tax_exempt` | *boolean*, **optional** | For tax exempt purchases set to `true`. | Include the following `item_data` fields for each line item: | Field | API Field | Type | Description | | --- | --- | --- | --- | | **Amount Excluding Sales Tax** | `amount_excluding_sales_tax` | *integer*, **required** | Total cost in cents of the line item excluding tax (must be greater than `0`). | | **Amount Including Sales Tax** | `amount_including_sales_tax` | *integer*, **required** | Total cost in cents of the line item including tax (must be greater than `0`). | | **Commodity Code** | `commodity_code` | *string*, **required** | A commodity code is a numeric code representing a particular product or service as defined by the National Institute of Governmental Purchasing. The code can be `3`, `5`, `7`, or `11` digits in length. The longer the code the more granular the description of the product/service. (max 12 characters) | | **Cost per Item** | `cost_per_unit` | *integer*, **required** | The price in cents of one unit of the item purchased. | | **Item Description** | `item_description` | *string*, **required** | A short, human-readable description of the line item (max `25` characters). | | **Item Discount** | `item_discount_amount` | *integer*, **required** | The discount amount in cents applied to this individual line item. For an order-level discount, use `discount_amount`. | | **Merchant Product Code** | `merchant_product_code` | *string*, **required** | Merchant defined product code (max `12` characters). | | **Quantity** | `quantity` | *integer*, **required** | The number of items purchased. Must be greater than `0`. | | **Unit of Measure** | `unit_of_measure` | *string*, **required** | The unit of measure of the purchased item (max `3` characters). | Example ### Request ```shell curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/transfers \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "additional_purchase_data": { "customer_reference_number": "PO-2024-3842", "customs_duty_amount": 0, "discount_amount": 100, "item_data": [ { "amount_excluding_sales_tax": 400, "amount_including_sales_tax": 440, "commodity_code": "175-62-20", "cost_per_unit": 500, "item_description": "IT Network Assessment", "item_discount_amount": 100, "merchant_product_code": "SVC-NET-ASMT", "quantity": 1, "unit_of_measure": "HUR" }, { "amount_excluding_sales_tax": 500, "amount_including_sales_tax": 550, "commodity_code": "207-72-54", "cost_per_unit": 500, "item_description": "USB-C Charging Cable 6ft", "item_discount_amount": 0, "merchant_product_code": "CBL-USBC-6FT", "quantity": 1, "unit_of_measure": "EA" } ], "shipping_amount": 100 }, "amount": 990, "currency": "USD", "merchant": "MU7noQ1wdgdAeAfymw2rfBMq", "source": "PIkxmtueemLD6dN9ZoWGHT44" }' ``` API Definition ### Response A successful request returns a `201 Created` status code and includes a Transfer resource with Level 3 processing details: Example Transfer - Level 3 Processing ```json Transfer - Level 3 Processing { "id": "TRfwbgfgsSV664hPUPfpvScc", "created_at": "2026-10-27T20:24:49.75Z", "updated_at": "2026-10-27T20:24:49.75Z", "3d_secure_session": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": { // [!code highlight] "customer_reference_number": "PO-2024-3842", // [!code highlight] "customs_duty_amount": 0, // [!code highlight] "destination_country_code": null, // [!code highlight] "destination_postal_code": null, // [!code highlight] "discount_amount": 100, // [!code highlight] "invoice_reference_number": null, // [!code highlight] "order_date": null, // [!code highlight] "sales_tax": null, // [!code highlight] "sales_tax_finix_generated": 90, // [!code highlight] "ship_from_postal_code": null, // [!code highlight] "shipping_amount": 100, // [!code highlight] "tax_exempt": false, // [!code highlight] "item_data": [ // [!code highlight] { // [!code highlight] "cost_per_unit": 500, // [!code highlight] "item_description": "IT Network Assessment", // [!code highlight] "item_discount_amount": 100, // [!code highlight] "merchant_product_code": "SVC-NET-ASMT", // [!code highlight] "quantity": 1, // [!code highlight] "amount_excluding_sales_tax": 400, // [!code highlight] "amount_including_sales_tax": 440, // [!code highlight] "unit_of_measure": "HUR", // [!code highlight] "commodity_code": "175-62-20", // [!code highlight] "sales_tax_amount": 40, // [!code highlight] "sales_tax_rate": 0.1 // [!code highlight] }, // [!code highlight] { // [!code highlight] "cost_per_unit": 500, // [!code highlight] "item_description": "USB-C Charging Cable 6ft", // [!code highlight] "item_discount_amount": 0, // [!code highlight] "merchant_product_code": "CBL-USBC-6FT", // [!code highlight] "quantity": 1, // [!code highlight] "amount_excluding_sales_tax": 500, // [!code highlight] "amount_including_sales_tax": 550, // [!code highlight] "unit_of_measure": "EA", // [!code highlight] "commodity_code": "207-72-54", // [!code highlight] "sales_tax_amount": 50, // [!code highlight] "sales_tax_rate": 0.1 // [!code highlight] } // [!code highlight] ] // [!code highlight] }, // [!code highlight] "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 990, "amount_requested": 990, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "USD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPryaDMUDq9Tcc5epVpro1Jj", "idempotency_id": null, "ip_address_details": null, "merchant": "MU7noQ1wdgdAeAfymw2rfBMq", "merchant_identity": "IDjvxGeXBLKH1V9YnWm1CS4n", "messages": [], "network_details": { "brand": "VISA", "authorization_code": "099376", "acquirer_reference_number": null }, "operation_key": "CARD_NOT_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "processed_at": "2026-10-27T20:24:50.21Z", "raw": null, "ready_to_settle_at": "2026-10-28T20:24:49.75Z", "receipt_last_printed_at": null, "security_code_verification": "MATCHED", "source": "PIkxmtueemLD6dN9ZoWGHT44", "split_transfers": [], "state": "SUCCEEDED", "statement_descriptor": "FLX*FLEX", "subtype": "API", "supplemental_fee": null, "tags": {}, "third_party_details": null, "tip_amount": null, "trace_id": "73f9986c-58fe-4459-99b7-fa0775eefbc1", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRfwbgfgsSV664hPUPfpvScc" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDjvxGeXBLKH1V9YnWm1CS4n" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRfwbgfgsSV664hPUPfpvScc/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRfwbgfgsSV664hPUPfpvScc/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRfwbgfgsSV664hPUPfpvScc" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRfwbgfgsSV664hPUPfpvScc/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkxmtueemLD6dN9ZoWGHT44" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPryaDMUDq9Tcc5epVpro1Jj" } } } ``` API Definition ## Create an Authorization with Level 2 processing Send a POST /authorizations request and include the required fields for Level 2 processing. ### Level 2 Fields Include the following `additional_purchase_data` fields: | Field | API Field | Type | Description | | --- | --- | --- | --- | | **Customer Reference Number** | `customer_reference_number` | *string*, **required** | A unique reference ID for the order such as a purchase order (PO) number or invoice number. A purchase order number (PO number) is a unique code assigned to a specific order of goods or services. The buyer creates this number when they make a purchase order. It helps both the buyer and the seller track the order, match invoices, and keep accurate financial records. (max `17` characters) | | **Sales Tax** | `sales_tax` | *integer*, **required** | Total aggregate tax amount in cents for the entire purchase. Field is automatically calculated if you pass in the itemized tax amounts. For non-taxable transactions either set `sales_tax` to `0` or omit from payload and also set `tax_exempt` to `true`.` | ### Request ```shell curl https://finix.sandbox-payments-api.com/authorizations \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ -d '{ "additional_purchase_data": { "customer_reference_number": "PO-2024-3842", "sales_tax": 200 }, "amount": 10000, "currency": "USD", "merchant": "MU7noQ1wdgdAeAfymw2rfBMq", "source": "PIs3rzrjP9orEjBwtJjhxEjL" }' ``` ### Response A successful request returns a `201 Created` status code and includes an Authorization resource with Level 2 processing details: Example Authorization - Level 2 Processing ```json Authorization - Level 2 Processing { "id": "AUpkHPontypnra6ixQ6nKaCD", "created_at": "2026-09-25T20:05:02.19Z", "updated_at": "2026-09-25T20:05:02.19Z", "3d_secure_session": null, "3ds_redirect_url": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": { "customer_reference_number": "PO-2024-3842", // [!code highlight] "customs_duty_amount": null, "destination_country_code": null, "destination_postal_code": null, "discount_amount": null, "invoice_reference_number": null, "order_date": null, "sales_tax": 200, // [!code highlight] "sales_tax_finix_generated": null, "ship_from_postal_code": null, "shipping_amount": null, "tax_exempt": false, "item_data": [] }, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 10000, "amount_requested": 10000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "USD", "expires_at": "2026-10-02T20:05:02.19Z", "failure_code": null, "failure_message": null, "idempotency_id": null, "ip_address_details": null, "is_void": false, "merchant": "MU7noQ1wdgdAeAfymw2rfBMq", "merchant_identity": "IDjvxGeXBLKH1V9YnWm1CS4n", "messages": [], "network_details": { "brand": "MASTERCARD", "authorization_code": "899854" }, "raw": null, "receipt_last_printed_at": null, "security_code_verification": "MATCHED", "source": "PIs3rzrjP9orEjBwtJjhxEjL", "state": "SUCCEEDED", "supplemental_fee": null, "tags": {}, "trace_id": "0e189372-9f27-4475-80f0-9e755be33d3b", "transfer": null, "void_state": "UNATTEMPTED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUpkHPontypnra6ixQ6nKaCD" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDjvxGeXBLKH1V9YnWm1CS4n" } } } ``` API Definition ## Create an Authorization with Level 3 processing Send a POST /authorizations request and include the required fields for Level 3 processing. ### Level 3 Fields Include the following `additional_purchase_data` fields: | Field | API Field | Type | Description | | --- | --- | --- | --- | | **Customer Reference Number** | `customer_reference_number` | *string*, **required** | A unique reference ID for the order such as a purchase order (PO) number or invoice number. A purchase order number (PO number) is a unique code assigned to a specific order of goods or services. The buyer creates this number when they make a purchase order. It helps both the buyer and the seller track the order, match invoices, and keep accurate financial records. (max `17` characters) | | **Customs Duty Amount** | `customs_duty_amount` | *integer*, **required** | The costs related to import or export duties in cents. This field must have a value of at least `0`. | | **Discount Amount** | `discount_amount` | *integer*, **required** | The amount in cents of the discount for the order. This field must have a value of at least `0`. | | **Shipping Amount** | `shipping_amount` | *integer*, **required** | The costs related to shipping and handling in cents. This field must have a value of at least `0`. | | **Tax Exempt** | `tax_exempt` | *boolean*, **optional** | For tax exempt purchases set to `true`. | Include the following `item_data` fields for each line item: | Field | API Field | Type | Description | | --- | --- | --- | --- | | **Amount Excluding Sales Tax** | `amount_excluding_sales_tax` | *integer*, **required** | Total cost in cents of the line item excluding tax (must be greater than `0`). | | **Amount Including Sales Tax** | `amount_including_sales_tax` | *integer*, **required** | Total cost in cents of the line item including tax (must be greater than `0`). | | **Commodity Code** | `commodity_code` | *string*, **required** | A commodity code is a numeric code representing a particular product or service as defined by the National Institute of Governmental Purchasing. The code can be `3`, `5`, `7`, or `11` digits in length. The longer the code the more granular the description of the product/service. (max 12 characters) | | **Cost per Item** | `cost_per_unit` | *integer*, **required** | The price in cents of one unit of the item purchased. | | **Item Description** | `item_description` | *string*, **required** | A short, human-readable description of the line item (max `25` characters). | | **Item Discount** | `item_discount_amount` | *integer*, **required** | The discount amount in cents applied to this individual line item. For an order-level discount, use `discount_amount`. | | **Merchant Product Code** | `merchant_product_code` | *string*, **required** | Merchant defined product code (max `12` characters). | | **Quantity** | `quantity` | *integer*, **required** | The number of items purchased. Must be greater than `0`. | | **Unit of Measure** | `unit_of_measure` | *string*, **required** | The unit of measure of the purchased item (max `3` characters). | ### Request ```shell curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/authorizations \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "additional_purchase_data": { "customer_reference_number": "PO-2024-3842", "customs_duty_amount": 0, "discount_amount": 100, "item_data": [ { "amount_excluding_sales_tax": 400, "amount_including_sales_tax": 440, "commodity_code": "175-62-20", "cost_per_unit": 500, "item_description": "IT Network Assessment", "item_discount_amount": 100, "merchant_product_code": "SVC-NET-ASMT", "quantity": 1, "unit_of_measure": "HUR" }, { "amount_excluding_sales_tax": 500, "amount_including_sales_tax": 550, "commodity_code": "207-72-54", "cost_per_unit": 500, "item_description": "USB-C Charging Cable 6ft", "item_discount_amount": 0, "merchant_product_code": "CBL-USBC-6FT", "quantity": 1, "unit_of_measure": "EA" } ], "shipping_amount": 100 }, "amount": 990, "currency": "USD", "merchant": "MU7noQ1wdgdAeAfymw2rfBMq", "source": "PIkxmtueemLD6dN9ZoWGHT44" }' ``` ### Response A successful request returns a `201 Created` status code and includes an Authorization resource with Level 3 processing details: Example Authorization - Level 3 Processing ```json Authorization - Level 3 Processing { "id": "AUzck2De5WUgJY1kCUkwLtT", "created_at": "2026-10-27T20:24:47.60Z", "updated_at": "2026-10-27T20:24:47.60Z", "3d_secure_session": null, "3ds_redirect_url": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": { // [!code highlight] "customer_reference_number": "PO-2024-3842", // [!code highlight] "customs_duty_amount": 0, // [!code highlight] "destination_country_code": null, // [!code highlight] "destination_postal_code": null, // [!code highlight] "discount_amount": 100, // [!code highlight] "invoice_reference_number": null, // [!code highlight] "order_date": null, // [!code highlight] "sales_tax": null, // [!code highlight] "sales_tax_finix_generated": 90, // [!code highlight] "ship_from_postal_code": null, // [!code highlight] "shipping_amount": 100, // [!code highlight] "tax_exempt": false, // [!code highlight] "item_data": [ // [!code highlight] { // [!code highlight] "cost_per_unit": 500, // [!code highlight] "item_description": "IT Network Assessment", // [!code highlight] "item_discount_amount": 100, // [!code highlight] "merchant_product_code": "SVC-NET-ASMT", // [!code highlight] "quantity": 1, // [!code highlight] "amount_excluding_sales_tax": 400, // [!code highlight] "amount_including_sales_tax": 440, // [!code highlight] "unit_of_measure": "HUR", // [!code highlight] "commodity_code": "175-62-20", // [!code highlight] "sales_tax_amount": 40, // [!code highlight] "sales_tax_rate": 0.1 // [!code highlight] }, // [!code highlight] { // [!code highlight] "cost_per_unit": 500, // [!code highlight] "item_description": "USB-C Charging Cable 6ft", // [!code highlight] "item_discount_amount": 0, // [!code highlight] "merchant_product_code": "CBL-USBC-6FT", // [!code highlight] "quantity": 1, // [!code highlight] "amount_excluding_sales_tax": 500, // [!code highlight] "amount_including_sales_tax": 550, // [!code highlight] "unit_of_measure": "EA", // [!code highlight] "commodity_code": "207-72-54", // [!code highlight] "sales_tax_amount": 50, // [!code highlight] "sales_tax_rate": 0.1 // [!code highlight] } // [!code highlight] ] // [!code highlight] }, // [!code highlight] "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 990, "amount_requested": 990, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "USD", "expires_at": "2026-11-06T20:24:47.60Z", "failure_code": null, "failure_message": null, "idempotency_id": null, "ip_address_details": null, "is_void": false, "merchant": "MU7noQ1wdgdAeAfymw2rfBMq", "merchant_identity": "IDjvxGeXBLKH1V9YnWm1CS4n", "messages": [], "network_details": { "brand": "VISA", "authorization_code": "517554" }, "raw": null, "receipt_last_printed_at": null, "security_code_verification": "MATCHED", "source": "PIkxmtueemLD6dN9ZoWGHT44", "state": "SUCCEEDED", "supplemental_fee": null, "tags": {}, "trace_id": "9670df3e-bbe6-4def-a2a4-a59b99e056a7", "transfer": null, "void_state": "UNATTEMPTED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUzck2De5WUgJY1kCUkwLtT" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDjvxGeXBLKH1V9YnWm1CS4n" } } } ``` API Definition ## Capture an Authorization with Level 2 / Level 3 processing Finix will automatically include the Level 2 / Level 3 data with the [capture](/api/authorizations/captureauthorization) request. ## Ineligible Merchants Specific businesses are excluded from processing Level 2 and Level 3 transactions. If a merchant has one of the following Merchant Category Codes (MCC), they are not eligible to process Level 2 / Level 3 transactions: | MCC Code | Merchant Description | | --- | --- | | **3000-3299, 4511** | Airlines/Passenger Transport | | **3351-3500, 7512** | Car Rentals/Auto Rental | | **4411** | Cruise Lines | | **5962, 5966, 5967** | High Risk Direct Marketing | | **3501-4010, 7011** | Hotels/Lodging | | **4112** | Passenger Railways | | **5812, 5814** | Restaurants | | **4722** | Travel Agents | | **7513** | Truck and Utility Trailer Rentals | ## Data Quality Best Practices The Level 2 / Level 3 processing data you submit should be accurate and of high quality. The card network's validation technology will identify generic descriptions, placeholder data, and artificially generated content. The data must be real, accurate, and descriptive of the actual products or services being sold. The examples below are meant to help point you in the right direction, but they are not exhaustive. Ultimately, the card network decides whether the data a merchant submits qualifies. | Finix Line Item Field | Card Network Recommendation | Avoid | | --- | --- | --- | | `item_description` | Must provide meaningful information about purchased items/services. | Do not provide merchant name, single characters, or generic descriptions. | | `merchant_product_code` | Typically the SKU or identifier by which the merchant tracks and prices the item or service. Must always be provided for every line item. The product code can be the merchant's, manufacturer's, or buyer's product code. This field must provide information about the purchase, not the customer. | Do not use erroneous data, such as the card product or MCC. | --- # Managing Receipts Source: https://docs.finix.com/guides/online-payments/payment-features/sending-receipts Learn how to provide receipts for In-Person or Online payments. ## How to manage receipts If you want to manage and print your own receipts using your own receipt printer, you can use the `card_present_details` object in the response body of the `Authorization` or `Transfer` resource. Here's an example of the `card_present_details` object and the data that should be printed on the receipt: ```json { "id": "AUarp7Pz21Low4u2Urw5Ub4W", "amount": 150, "other fields": null, "card_present_details": { "emv_data": { "application_identifier": "A0000001523010", "application_label": "DISCOVER", "application_preferred_name": null, "application_transaction_counter": "0005", "cryptogram": "ARCQ F666F8891F870D33", "issuer_code_table_index": null, "pin_verified": false, "tags": null }, "masked_account_number": "************0059", "name": "Test Card 05", "brand": "DISCOVER", "entry_mode": "CHIP_ENTRY", "payment_type": "CREDIT", "approval_code": "004839" }, "merchant": "MU4LYrniAvqVKUBqcATb7Y7p", "merchant_identity": "IDsbTBawhnLBAVeinRb84vFR", "state": "SUCCEEDED", "trace_id": "FNXsK76MxJWPkbGqpKymgkzK" } ``` The following example outlines the receipt data elements (not the visual layout) and maps each element to its corresponding field in the Finix API response. **Sample Receipt:** Sample receipt **Receipt Data:** | No. | Name | ReceiptProtocol Field | Finix API Location | | --- | --- | --- | --- | | 1 | Merchant Name & Address | `merchantName`, `merchantAddress` | Generate independently or pull from the merchant identity. | | 2 | Date & Time | `date` | `created_at` from the transaction response or generate independently. | | 3 | Application Label | `applicationLabel` | `application_label` in `emv_data` in `card_present_details`. | | 4 | Application Identifier | `applicationIdentifier` | `application_identifier` in `emv_data` in `card_present_details`. | | 5 | Merchant Id | `merchantId` | `merchant_identity` in the response. | | 6 | Reference Number | `referenceNumber` | `trace_id` in the response. | | 7 | Account Number | `accountNumber` | `masked_account_number` in `card_present_details`. | | 8 | Card Brand | `cardBrand` | `brand` in `card_present_details`. | | 9 | Entry Mode | `entryMode` | `entry_mode` in `card_present_details`. | | 10 | Transaction Id | `transactionId` | `id` of the transaction. | | 11 | Approval Code | `approvalCode` | `approval_code` in `card_present_details`. | | 12 | Response Code | `responseCode` | null | | 13 | Response Message | `responseMessage` | `state` of the transaction. | | 14 | Amount | `amount` | `amount` in $ format. | | 15 | Cryptogram | `cryptogram` | `cryptogram` in `emv_data` in `card_present_details`. | | 16 | Transaction Type | `transactionType` | either `Sale` or `Authorization` depending on the method used. | ### Printing receipts with the Finix API Use the following request to print a receipt for an `Authorization` or `Transfer`. - Available values for `type` include **MERCHANT** or **BUYER**. - Be sure to include **true** for `send_receipt_to_buyer` for the action to be taken. - If the original transaction included a tip or surcharge, use the breakdown to specify for the receipt how it should be broken down. It will not automatically pull these values from the original transaction. ```shell Create Receipt Request curl https://finix.sandbox-payments-api.com/receipts \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \ -X POST \ -d '{ "send_receipt_to_buyer": true, "amount_breakdown": { "subtotal_amount": 1700, "additional_buyer_charges": { "surcharge_amount": 100 }, "tip_amount": 100 }, "requested_delivery_methods": [ { "type": "PRINT", "destinations": ["DV864n6gKbgGNgQg9LyHpnMR"] } ], "entity_id": "TRrieLrWspuN3W72BP3nD6hh", "type": "BUYER" }' ``` A successful response returns the `receipt` resource. The receipt will print from the `Device` used in the request. ```json Create Receipt Response { "id": "receipt_ccBeL2iWn3V1wWSfqjuaE", "created_at": "2024-06-26T18:06:12.68Z", "updated_at": "2024-06-26T18:06:12.68Z", "amount": 500, "currency": "USD", "amount_breakdown": null, "send_receipt_to_buyer": true, "device_id": "DVmiLSwXdYxC7U3wtGCpF7iD", "entity_details": { "id": "TR3rNtUhV4dC82vNsVGLENVD", "created_at": "2024-05-23T21:26:11.71Z", "type": "TRANSFER" }, "type": "BUYER", "merchant_details": { "id": "MUrcHDvsFUp4PjJzWo7WzF82", "business_name": "Smith & Associates Consulting", "doing_business_as": "Smith & Associates Consulting", "business_address": { "city": "Allen", "country": "USA", "line1": "1113 Shade Tree Ln", "line2": null, "postal_code": "75013", "region": "TX" } }, "payment_instrument_details": { "id": "PIkXm2YP4isGwpRpfjrDkEc8", "type": "PAYMENT_CARD_PRESENT", "bin": "476173", "brand": "VISA", "card_type": "CREDIT", "last_four": "0010" }, "network_details": { "application_label": "VISA CREDIT", "application_identifier": "A0000000031010", "approval_code": "031475", "cryptogram": "ARCQ A09FDACC9F024838" }, "requested_delivery_methods": [ { "type": "PRINT", "destinations": ["DVmiLSwXdYxC7U3wtGCpF7iD"] } ], "receipt_url": "https://receipt.sb-payments-checkout.com/W3Qoh1", "_links": { "self": { "href": "https://finix.sb-payments-api.com/receipts/receipt_ccBeL2iWn3V1wWSfqjuaE" } } } ``` ### Customizing the PDF Receipt Use `customization_details` to add structured metadata and free-text content to the PDF receipt. This field supports three arrays of objects: | Field | Description | Max Items | Constraints | | --- | --- | --- | --- | | `subheader_attributes` | Key-value pairs rendered as labeled fields near the top of the PDF (e.g. PO Number, Contract ID). Cannot be used together with `additional_details` in the same request. | 5 | `name` ≤ 25 chars, `value` ≤ 25 chars | | `summary_sections` | Free-text sections rendered **above** the line items. | 5 | `name` ≤ 200 chars, `value` ≤ 2000 chars | | `footer_sections` | Free-text sections rendered **below** the line items. | 5 | `name` ≤ 200 chars, `value` ≤ 2000 chars | Example API Definition A successful response returns a `201 Created` status code with the newly created resource: Example Receipt ```json Receipt { "id": "receipt_cEpKXnvNACvGVrJFNRbCK", "created_at": "2026-09-25T20:05:29.95Z", "updated_at": "2026-09-25T20:05:29.95Z", "additional_details": null, "amount": 1000, "amount_breakdown": { "additional_buyer_charges": { "convenience_amount": 150, "rent_surcharge_amount": null, "surcharge_amount": null }, "customs_duty_amount": null, "discount_amount": 100, "estimated_tax_amount": 200, "shipping_amount": 100, "subtotal_amount": 600, "tip_amount": 50 }, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "customization_details": { // [!code highlight] "subheader_attributes": [ // [!code highlight] { // [!code highlight] "name": "Contract ID", // [!code highlight] "value": "CTR-9988" // [!code highlight] }, // [!code highlight] { // [!code highlight] "name": "PO Number", // [!code highlight] "value": "PO-12345" // [!code highlight] } // [!code highlight] ], // [!code highlight] "summary_sections": [ // [!code highlight] { // [!code highlight] "name": "Terms", // [!code highlight] "value": "Payment due within 30 days." // [!code highlight] }, // [!code highlight] { // [!code highlight] "name": "Memo", // [!code highlight] "value": "Thank you for your business." // [!code highlight] } // [!code highlight] ], // [!code highlight] "footer_sections": [ // [!code highlight] { // [!code highlight] "name": "Return Policy", // [!code highlight] "value": "All sales final." // [!code highlight] } // [!code highlight] ] // [!code highlight] }, // [!code highlight] "device_id": null, "entity_details": { "id": "TRdJKpiu8WgRYEzCfqxVr66P", "created_at": "2026-03-20T14:59:32.57Z", "operation_key": "CARD_NOT_PRESENT_SALE", "type": "TRANSFER" }, "items": [ { "description": "Printing paper (1 box).", "image_details": null, "item_details": null, "name": "Printing Paper", "price_details": { "sale_amount": 250, "currency": "USD", "price_type": "PROMOTIONAL", "regular_amount": 350, "amount_excluding_sales_tax": 200, "item_discount_amount": 100 }, "quantity": 1 }, { "description": "Printing ink (1 carton).", "image_details": null, "item_details": null, "name": "Printing Ink", "price_details": { "sale_amount": 350, "currency": "USD", "price_type": "REGULAR", "regular_amount": 350, "amount_excluding_sales_tax": 300, "item_discount_amount": 0 }, "quantity": 1 } ], "merchant_details": { "id": "MUe17jKSrfPetoeiJQzzjmA2", "business_address": { "city": "San Mateo", "country": "USA", "line1": "741 Douglass St", "line2": "Apartment 8", "postal_code": "94114", "region": "CA" }, "business_name": "Finix Flowers", "doing_business_as": "Finix Flowers" }, "network_details": null, "payment_instrument_details": { "id": "PI6iQcTtJNCS8GZAVKYi5Ueb", "billing_address": { "city": "San Mateo", "country": "USA", "line1": "741 Douglass St", "line2": "Apartment 8", "postal_code": "94114", "region": "CA" }, "bin": "489514", "brand": "VISA", "card_type": "UNKNOWN", "last_four": "0006", "name": "John Smith", "type": "PAYMENT_CARD" }, "receipt_url": "https://receipt-link.sandbox-payment-form.com/UgX9XP", "requested_delivery_methods": [ { "type": "EMAIL", "destinations": [ "johndoe@gmail.com" ] }, { "type": "SMS", "destinations": [ "3346497818" ] }, { "type": "PRINT", "destinations": [ "DV12343234" ] } ], "send_receipt_to_buyer": true, "type": "BUYER", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/receipts/receipt_cEpKXnvNACvGVrJFNRbCK" } } } ``` API Definition ## Additional requirements ### Prompting users for preferred receipts If the `prompt_receipt_confirmation` value is set to true for the terminal, it will present a page to the cardholder that will prompt them to select how they want their receipt. When enabled, the terminal will display a screen asking the customer how they'd like to receive their receipt. You control the available options by setting `available_receipt_methods`. Supported values include: - `PRINT` - `EMAIL` - `SMS` Once the customer selects a method and submits relevant contact information, Finix will trigger a webhook: - `entity: receipt` - `type: created` This webhook includes all receipt details, including the delivery method and destination (e.g., email address or phone number), so you can take the appropriate action—like printing or sending the receipt. ### Receipt requirements To stay compliant with card networks and processing requirements, merchant must be able to print two copies of the receipt: - **Cardholder Copy** – A separate receipt for the buyer. "Cardholder Copy" must be printed on the last line of the receipt. - **Merchant Copy** - A second copy for your business records. "Merchant Copy" must be printed on the last line of the receipt. Depending on the transaction, many of the fields can return null. You can either omit the line or display a placeholder value such as `N/A` or `0`. ### Integrating with receipt printers - **Serial Printers** - Encode the receipt data using the required printer command set (e.g., ESC/POS or Star commands). Use programs like [Socket.IO](https://socket.io/) to send the formatted data to the printer. - **Network Printers** - Send receipt data directly over the network to supported IP printers. ### Digital vs. paper receipts You may provide digital receipts (email or SMS), but you must always be able to provide a printed receipt if the customer requests one. While the receipt doesn't have to be printed on thermal receipt paper, it's recommended, as thermal printers don't require ink and are more cost-effective over time. --- # Split Transactions Source: https://docs.finix.com/guides/online-payments/payment-features/split-transactions Learn how to split a transaction across multiple sellers. When processing an online payment or transaction, you can split the funds that get paid out across several different sellers. Specifically, the funds from `Transfers` can be split across any number of approved `Merchants.` Please note: - `Transfers` can only be split between `Merchants` created under the same `Application.` - Each `split_transfer` is placed into the `Settlement` of the `split_transfers#merchant.` - No changes need to be made to your `Application` or `Merchants` to enable Split Transactions. ## Splitting a Transfer across Sellers ### Finix API To split a transaction, [when creating the `Transfer`](/api/transfers/createtransfer) include: - The **ID** of the `Merchants` that the funds will get split across. - The `amount` to distribute into the `Settlements` of each `Merchant.` The combined `amounts` in the `split_transfers` object must be equal to the `amount` of the `Transfer.` In the following example, a $10.00 `Transfer` is split so: - The primary merchant receives $6.00 (before subtracting processing fees) - The second merchant receives $3.00 (before subtracting processing fees) - The third merchant receives $1.00 (before subtracting processing fees) Processing fees get deducted when `Merchants` receive their payouts. For more details, see [Payouts](/guides/platform-payments/seller-payouts). The primary merchant is the `merchant` specified in the parent `Transfer` request; outside the `split_transfers` object. Example API Definition Example response: Example Split Transaction ```json Split Transaction { "id": "TRhXDYSYqqRXxUQc6X1d4EW9", "created_at": "2026-09-25T20:06:03.96Z", "updated_at": "2026-09-25T20:06:03.96Z", "3d_secure_session": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 1000, "amount_requested": 1000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "USD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj", "idempotency_id": null, "ip_address_details": null, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "messages": [], "network_details": null, "operation_key": "CARD_NOT_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "processed_at": "2026-09-25T20:06:04.39Z", "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": "PI5benj4eVhCL4ALMv6SFxJG", "split_transfers": [ // [!code highlight] "split_transfer_hXQKj2XHpuCYpv28wFBCkp", "split_transfer_hXQLzkbV8j2GwN76pmyhDZ", "split_transfer_hXQLW9Vy52QmS2wDpffKyd" ], "state": "PENDING", "statement_descriptor": "FLX*FINIX FLOWERS", "subtype": "API", "supplemental_fee": null, "tags": {}, "third_party_details": null, "tip_amount": null, "trace_id": "e0c6b87f-017e-442c-97d5-2704b21bcd60", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhXDYSYqqRXxUQc6X1d4EW9" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhXDYSYqqRXxUQc6X1d4EW9/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhXDYSYqqRXxUQc6X1d4EW9/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRhXDYSYqqRXxUQc6X1d4EW9" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhXDYSYqqRXxUQc6X1d4EW9/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI5benj4eVhCL4ALMv6SFxJG" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj" } } } ``` API Definition #### Split Transfers The `split_transfers` array returned in the response contains the resource **IDs** of the `split_transfers` generated from the `Transfer` that was split. Use the **ID** to review how the transaction was split for the specified `Merchant.` Example response: Example Split Transfer ```json Split Transfer { "id": "split_transfer_97gaitUpcmzqjYYpQbei9j", "created_at": "2026-01-12T22:15:51.99Z", "updated_at": "2026-01-12T22:15:51.99Z", "amount": 400, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "fee": 100, "fee_profile_id": "FPryaDMUDq9Tcc5epVpro1Jj", "identity_id": "IDjvxGeXBLKH1V9YnWm1CS4n", "merchant_id": "MU7noQ1wdgdAeAfymw2rfBMq", "parent_transfer_id": "TR96ZCp2GLvDHPPTMpcsabZi", // [!code highlight] "ready_to_settle_at": "2026-01-13T22:16:03.67Z", "tags": {}, "type": "DEBIT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/split_transfers/split_transfer_97gaitUpcmzqjYYpQbei9j" } } } ``` API Definition ### Finix Dashboard Split Transactions appear on the Finix Dashboard under **Payments**. You can identify Split Transactions using the **Payment Type** in the **Amount** column: Identify split transactions Click on the individual entry to review the Split Transaction in detail: View split transactions ## Splitting a capture across Sellers ### Step 1: Create an Authorization The first step is to create an Authorization. If you are interested in learning more about Authorizations, you can see the [Auth and Captures guide](/guides/online-payments/payment-features/auth-and-captures). ```shell curl 'https://finix.sandbox-payments-api.com/authorizations' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X POST \ -d '{ "amount": 1000, "currency": "USD", "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "source": "PIe2YvpcjvoVJ6PzoRPBK137" }' ``` Example Response: ```json { "id": "AUirsgFc8drp1LPzNFcxP2r", "created_at": "2024-03-15T20:47:09.60Z", "updated_at": "2024-03-15T20:47:09.60Z", "3ds_redirect_url": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 1000, "amount_requested": 1000, "application": "APgPDQrLD52TYvqazjHJJchM", "currency": "USD", "expires_at": "2024-03-22T20:47:09.60Z", "failure_code": null, "failure_message": null, "idempotency_id": null, "is_void": false, "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg", "messages": [], "raw": null, "receipt_last_printed_at": null, "security_code_verification": "MATCHED", "source": "PIe2YvpcjvoVJ6PzoRPBK137", "state": "SUCCEEDED", "tags": {}, "trace_id": "a4f7612f-a09e-4c35-ae92-9a1f44fcd2a7", "transfer": null, "void_state": "UNATTEMPTED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUirsgFc8drp1LPzNFcxP2r" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg" } } } ``` ### Step 2: Create a capture When you capture an `Authorization`, Finix creates a `Transfer` resource. You can capture an Authorization by using the following API. The `split_transfers` array is optional. If you omit the `split_transfer` array, the Capture will not be split. ```shell curl 'https://finix.sandbox-payments-api.com/authorizations/AUirsgFc8drp1LPzNFcxP2r' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X PUT \ -d '{ "capture_amount": 1000, "split_transfers": [ { "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "amount": 600, "tags": { "key": "value" } }, { "merchant": "MUeHUEPKybMjqV1STcqrFTSH", "amount": 300, "fee": 100 }, { "merchant": "MU3Gh6DT5fCBxVtWB8VJc1St", "amount": 100 } ] }' ``` **Example Authorization Response:** The `transfer` field contains the ID of the `Transfer` created from the captured `Authorization`. ```json { "id": "AUirsgFc8drp1LPzNFcxP2r", "created_at": "2024-03-15T20:47:09.60Z", "updated_at": "2024-03-15T20:56:38.31Z", "3ds_redirect_url": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 1000, "amount_requested": 1000, "application": "APgPDQrLD52TYvqazjHJJchM", "currency": "USD", "expires_at": "2024-03-22T20:47:09.60Z", "failure_code": null, "failure_message": null, "idempotency_id": null, "is_void": false, "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg", "messages": [], "raw": null, "receipt_last_printed_at": null, "security_code_verification": "MATCHED", "source": "PIe2YvpcjvoVJ6PzoRPBK137", "state": "SUCCEEDED", "tags": {}, "trace_id": "a4f7612f-a09e-4c35-ae92-9a1f44fcd2a7", "transfer": "TRs2sPQ9pd8nr4BRprsXy78H", "void_state": "UNATTEMPTED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUirsgFc8drp1LPzNFcxP2r" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "transfer": { "href": "https://finix.sandbox-payments-api.com/transfers/TRs2sPQ9pd8nr4BRprsXy78H" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg" } } } ``` **Example Transfer Response:** Inside the `Transfer`, the `split_transfers` array contains the split transfers you specified when capturing the `Authorization`. ```json { "id": "TRs2sPQ9pd8nr4BRprsXy78H", "created_at": "2024-03-15T20:56:38.16Z", "updated_at": "2024-03-15T20:57:00.73Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 1000, "amount_requested": 1000, "application": "APgPDQrLD52TYvqazjHJJchM", "currency": "USD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "idempotency_id": null, "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg", "messages": [], "parent_transfer": null, "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": "2024-03-15T20:57:00.82Z", "receipt_last_printed_at": null, "security_code_verification": null, "source": "PIe2YvpcjvoVJ6PzoRPBK137", "split_transfers": [ "split_transfer_hkckq21uy6qWWYzcS2e14r", "split_transfer_hkdqpd4mSGTGbAhsPuFubF", "split_transfer_hkdqFSfgCtWdRcVjwWxfyZ" ], "state": "SUCCEEDED", "statement_descriptor": "FNX*DUNDER MIFFLIN", "subtype": "API", "tags": {}, "trace_id": "a4f7612f-a09e-4c35-ae92-9a1f44fcd2a7", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRs2sPQ9pd8nr4BRprsXy78H" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRs2sPQ9pd8nr4BRprsXy78H/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRs2sPQ9pd8nr4BRprsXy78H/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TRs2sPQ9pd8nr4BRprsXy78H/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRs2sPQ9pd8nr4BRprsXy78H/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8" } } } ``` ## Splitting a card present transaction ```shell curl 'https://finix.sandbox-payments-api.com/transfers' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ -X POST \ -d '{ "amount": 300, "currency": "USD", "device": "DVae7HFLS7BXNaFpKhdH1K6x", "operation_key": "CARD_PRESENT_SALE", "split_transfers": [ { "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "amount": 200, "tags": { "key": "value" } }, { "merchant": "MUcgYZswyRfqSSbvMsxuaHxZ", "amount": 100, "fee": 10 } ], "tags": { "test": "sale" } }' ``` Example response: ```json { "id": "TRtAsvgPKhGcJJtrV8fAXUgC", "created_at": "2025-03-04T16:08:12.55Z", "updated_at": "2025-03-04T16:08:12.55Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 300, "amount_requested": 300, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "card_present_details": { "emv_data": { "application_identifier": "A0000000031010", "application_label": "VISA CREDIT", "application_preferred_name": null, "application_transaction_counter": "00D0", "cryptogram": "ARCQ 99902411B7B0B26E", "issuer_code_table_index": null, "network_emv_response": null, "pin_verified": false, "tags": null }, "masked_account_number": "476173******0010", "name": null, "brand": "VISA", "entry_mode": "CONTACTLESS", "payment_type": "CREDIT", "approval_code": "956682", "digital_signature_file_id": null }, "currency": "USD", "destination": null, "device": "DVae7HFLS7BXNaFpKhdH1K6x", "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj", "idempotency_id": null, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "messages": [], "operation_key": "CARD_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": "PIkXKGqRMswqxKN9YbnRir26", "split_transfers": [ "split_transfer_tAVzHxjXfXFdTx7XtLZgUZ", "split_transfer_tAVJEs5ZaNu6iAJDbtdTYs" ], "state": "SUCCEEDED", "statement_descriptor": "FLX*FINIX FLOWERS", "subtype": "API", "supplemental_fee": null, "tags": { "test": "sale" }, "tip_amount": 0, "trace_id": "e3ecb181-3c00-4ade-805b-6b35bb85eb61", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtAsvgPKhGcJJtrV8fAXUgC" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" }, "device": { "href": "https://finix.sandbox-payments-api.com/devices/DVae7HFLS7BXNaFpKhdH1K6x" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtAsvgPKhGcJJtrV8fAXUgC/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtAsvgPKhGcJJtrV8fAXUgC/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtAsvgPKhGcJJtrV8fAXUgC/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtAsvgPKhGcJJtrV8fAXUgC/disputes" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj" } } } ``` ### HTTP request `POST https://finix.sandbox-payments-api.com/transfers` ### Request arguments | Field | Type | Description | | --- | --- | --- | | `amount` | *integer*, **required** | The total amount that will be debited in cents (e.g. 100 cents to debit $1.00) | | `currency` | *string*, **required** | 3-letter ISO code designating the currency of the `Transfers` (e.g. USD) | | `idempotency_id` | *string*, **optional** | A randomly generated value that you want to be associated with the request | | `device` | *string*, **required** | ID of the primary `Device` that's processing the `Transfer` for the buyer | | `split_transfers` | *array*, **required** | An array of objects you use to detail how the Transfer will get split and the amount Merchants should receive.The sum of the `split_transfer#amounts` must be equal to the amount submitted in the Transfer request. | | `tags` | *object*, **optional** | Key value pair for annotating custom metadata (e.g. order numbers) | | `operation_key` | *string*, **required** | The operation key for the `Transfer` | ### Request arguments - Split Transfers object | Field | Type | Description | | --- | --- | --- | | `amount` | *integer*, **required** | The amount of funds that get split and paid out to the specifiedMerchant.Must be less than or equal to the `amount` of the Transfer.The sum of the `split_transfer#amounts` must equal the `amount` in the parent `Transfer.` | | `fee` | *integer*, **optional** | The minimum amount of the `split_transfer` you'd like to collect as your fee in cents. Defaults to zero (must be less than or equal to the `amount` being split for the specified `Merchant`).Please note, for split transaction,`fees` are only supported when included in the `split_transfers` object. | | `merchant` | *string*, **required** | The ID of the Merchant that will receive the specified `amount` under the `split_transfers` object.In Split Transfers, the primary Merchants is specified outside the split_transfers object. | | `tags` | *object*, **optional** | Key value pair for annotating custom metadata (e.g. order numbers) | ## Refunding Split transactions Refund Split Transactions by following the usual steps to refund transactions in Finix. For more information, see [Refund](/guides/after-the-payment/refunds). When processing a refund, you can split the funds across the `Merchants` included in the original `Transfer` so they get paid back across the different sellers. Please note, the `amount` refunded to each `Merchant` can't exceed that `Merchant`'s original split amount in the parent `Transfer.` ```shell curl 'https://finix.sandbox-payments-api.com/transfers/TR2kKxKDu2nJCvjD2djuDktv/reversals' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X POST \ -d '{ "refund_amount": 1000, "split_transfers": [ { "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "amount": 600, "tags": { "key": "value" } }, { "merchant": "MUeHUEPKybMjqV1STcqrFTSH", "amount": 300 }, { "merchant": "MU3Gh6DT5fCBxVtWB8VJc1St", "amount": 100 } ], "tags": { "test": "refund" } }' ``` Example response: ```json { "id": "TR7KSrpZWc9UoB6bcxqYu978", "created_at": "2023-08-08T20:29:14.88Z", "updated_at": "2023-08-08T20:29:14.98Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "address_verification": null, "amount": 1000, "amount_requested": 1000, "application": "APgPDQrLD52TYvqazjHJJchM", "currency": "USD", "destination": "PIe2YvpcjvoVJ6PzoRPBK137", "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "idempotency_id": null, "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg", "messages": [], "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": null, "split_transfers": [ "split_transfer_8DUfRhXpZDiM6rZcyfNGGD", "split_transfer_8DUgkBtytEtSPQKKCCmG3m", "split_transfer_8DUgvBbUwJiN2pWw6P4cMH" ], "state": "PENDING", "statement_descriptor": "FNX*DUNDER MIFFLIN", "subtype": "API", "tags": { "test": "refund" }, "trace_id": "dfc18365-d862-46e0-8acb-9c290a1aed7b", "type": "REVERSAL", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TR7KSrpZWc9UoB6bcxqYu978" }, "parent": { "href": "https://finix.sandbox-payments-api.com/transfers/TR2kKxKDu2nJCvjD2djuDktv" }, "destination": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TR7KSrpZWc9UoB6bcxqYu978/payment_instruments" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8" } } } ``` Example response: ```json { "id": "split_transfer_8DUfRhXpZDiM6rZcyfNGGD", "created_at": "2023-08-08T20:29:15.08Z", "updated_at": "2023-08-08T20:29:15.08Z", "amount": 600, "application_id": "APgPDQrLD52TYvqazjHJJchM", "currency": "USD", "fee": 0, "fee_profile_id": "FPbDSnEPtaT8Nttxj9NJk7eC", "identity_id": "IDuqZpDw28f2KK6YuDk4jNLg", "merchant_id": "MUeDVrf2ahuKc9Eg5TeZugvs", "parent_transfer_id": "TR7KSrpZWc9UoB6bcxqYu978", "ready_to_settle_at": null, "tags": { "key": "value" }, "type": "CREDIT" } ``` ## Settlements and Payouts Every `split_transfer` gets placed into a `Settlement.` `Merchants` get paid out when `Settlements` are approved. For more information, see our Platform Payments guide on [Payouts](/guides/platform-payments/seller-payouts). ### Settlement entries To query all the transactions for a specific settlement, use the following API: ```shell curl "https://finix.sandbox-payments-api.com/settlements/STivxR2KrnVdD75TQtitnsG8/entries" \ -H "Finix-Version: 2022-02-01" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e ``` Example Response: ```json { "_embedded": { "settlement_entries": [ { "id": "SEix6ptbScYkWFN1id25KbN5", "created_at": "2022-08-12T21:41:42.36Z", "updated_at": "2022-08-12T21:41:42.36Z", "amount": 100, "currency": "USD", "entity_id": "TR8yiKY6ju988aUZhfqJFjag", "entity_type": "TRANSFER", "should_fund": true, "subtype": "FEE", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/STivxR2KrnVdD75TQtitnsG8/entries/SEix6ptbScYkWFN1id25KbN5" }, "entries": { "href": "https://finix.sandbox-payments-api.com/settlement_engine/settlement/STivxR2KrnVdD75TQtitnsG8" } } }, { "id": "SEiwmJxC3u8gfPuLiwMSrn1a", "created_at": "2022-08-12T21:41:42.18Z", "updated_at": "2022-08-12T21:41:42.18Z", "amount": 2, "currency": "USD", "entity_id": "TRwgubpxAJWbaDZE1kKP6SSi", "entity_type": "TRANSFER", "should_fund": true, "subtype": "FEE", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/STivxR2KrnVdD75TQtitnsG8/entries/SEiwmJxC3u8gfPuLiwMSrn1a" }, "entries": { "href": "https://finix.sandbox-payments-api.com/settlement_engine/settlement/STivxR2KrnVdD75TQtitnsG8" } } }, { "id": "SEivAwLLW6c62Nbvvj7TcDAN", "created_at": "2022-08-12T21:41:41.99Z", "updated_at": "2022-08-12T21:41:41.99Z", "amount": 100, "currency": "USD", "entity_id": "TRm9ppvqX43CbwmNzhckf2gb", "entity_type": "TRANSFER", "should_fund": true, "subtype": "DEBIT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/STivxR2KrnVdD75TQtitnsG8/entries/SEivAwLLW6c62Nbvvj7TcDAN" }, "entries": { "href": "https://finix.sandbox-payments-api.com/settlement_engine/settlement/STivxR2KrnVdD75TQtitnsG8" } } } ] }, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/settlements/STivxR2KrnVdD75TQtitnsG8/entries" }, "next": { "href": "https://finix.sandbox-payments-api.com/settlements/STivxR2KrnVdD75TQtitnsG8/entries?after_cursor=SEivAwLLW6c62Nbvvj7TcDAN" } }, "page": { "limit": 100, "next_cursor": "SEivAwLLW6c62Nbvvj7TcDAN" } } ``` #### Response | Field | Type | Description | | --- | --- | --- | | `id` | string | ID of the `Settlement Entry` | | `amount` | integer | Amount of the `Entry` | | `currency` | string | Currency of the `Entry` | | `entity_id` | string | ID of the entity. For example, this can be the `id` of a `Transfer` or `Split Transfer`. | | `should_fund` | boolean | Whether this entry will get paid out as part of the `funding_transfer` calculations. | | `entity_type` | string | Type of Entity. Values include `TRANSFER`, `SPLIT_TRANSFER`, `CUSTOM_FEE`, and `FEE`. | | `subtype` | string | Subtype of the Entity. Values include `DEBIT`, `CREDIT`, `CUSTOM`, `FEE`, `REVERSAL`, `ADJUSTMENT`, `DISPUTE`, `DISPUTE_MERCHANT_DEBIT`, `DISPUTE_MERCHANT_CREDIT`, `REFUND_MERCHANT_DEBIT_ADJUSTMENT`, and `REFUND_MERCHANT_CREDIT_ADJUSTMENT`. | ## Fees Processing fees for split transactions get created according to: - The fee profile created for the `Merchant.` For more details, see [Fee Profiles](/api/fee-profiles). - Any fees included in `split_transfer#fee` when the initial `Transfer` was first created. For more information, see [Create a Transfer.](/api/transfers/createtransfer) - If `charge_interchange` is enabled in the seller's `fee_profile,` they'll be charged interchange for the full transaction amount. ## Disputes There are two ways you can handle disputes with Split Transactions. ### Option 1 - full amount of dispute debited to primary Merchant (default behavior) This is the default behavior for split transactions and operates the same as if you get a dispute in a regular sale. The primary merchant will be debited the full amount of the dispute. ### Option 2: Disputes are split proportionally to the amount of the original sale To enable this option, reach out to [Finix Support](mailto:support@finix.com). When a buyer disputes a split transaction, the `Dispute` › `amount` is split proportionally among all participants based on their share of the original sale. Consider a split transaction where a $10.00 sale is split between two merchants: - Merchant A (primary): $6.00 (60%) - Merchant B: $4.00 (40%) When the buyer disputes this transaction, the following occurs: #### 1. Dispute created A `Dispute` resource is created for the primary `Merchant` defined at the root level of the split transaction. #### 2. Adjustment Transfer created When Finix pulls funds (chargeback), a dispute adjustment `Transfer` is created for the full `Dispute` › `amount`. This `Transfer` includes a `split_transfers` array containing IDs for each participant. The dispute adjustment will not be put in a settlement. **Key fields on the adjustment transfer:** - `type: DISPUTE` - Indicates this is a dispute adjustment `Transfer` - `subtype: MERCHANT_DEBIT` - Funds are being pulled from merchants (proportionally from all merchants, not just the primary) - `split_transfers` - Array of `Split Transfer` IDs representing each participant's proportional share ```json { "id": "TRpxCZRBtMbcGYbtvCxVYSpe", "created_at": "2025-06-25T18:46:18.52Z", "updated_at": "2025-06-25T18:46:18.52Z", "amount": 1000, "amount_requested": 1000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "destination": null, "fee": 0, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "split_transfers": [ "split_transfer_6iVWXfDjxm84cvTeNZNXPc", "split_transfer_6iW81ie9XwDyttX4sWK3cg" ], "state": "SUCCEEDED", "subtype": "MERCHANT_DEBIT", "type": "DISPUTE", ... } ``` #### 3. Split Transfers created Each `Split Transfer` has `type: DISPUTE_MERCHANT_DEBIT` and an amount proportional to the merchant's share of the original sale. **Split Transfer for Merchant A (primary) - 60% of $10.00 = $6.00**: ```json { "id": "split_transfer_6iVWXfDjxm84cvTeNZNXPc", "amount": 600, "currency": "USD", "merchant_id": "MUmfEGv5bMpSJ9k5TFRUjkmm", "parent_transfer_id": "TRpxCZRBtMbcGYbtvCxVYSpe", "type": "DISPUTE_MERCHANT_DEBIT", ... } ``` **Split Transfer for Merchant B - 40% of $10.00 = $4.00**: ```json { "id": "split_transfer_6iW81ie9XwDyttX4sWK3cg", "amount": 400, "currency": "USD", "merchant_id": "MU7noQ1wdgdAeAfymw2rfBMq", "parent_transfer_id": "TRpxCZRBtMbcGYbtvCxVYSpe", "type": "DISPUTE_MERCHANT_DEBIT", ... } ``` #### 4. Settlement entries created `Settlement Entries` are created for each `Split Transfer`. The adjustment `Transfer` itself is **not** placed in a settlement—instead, `Settlement Entries` reference each `Split Transfer`. **Key fields on the settlement entry:** - `entity_type: SPLIT_TRANSFER` - Indicates this entry is for a `Split Transfer` - `subtype: DISPUTE_MERCHANT_DEBIT` - Mirrors the `Split Transfer` › `type`, indicating funds are being pulled due to a `Dispute` **Settlement Entry for Merchant A's Split Transfer ($6.00)**: ```json { "id": "SEmA6iVWXfDjxm84cvTeNZNX", "amount": 600, "currency": "USD", "entity_id": "split_transfer_6iVWXfDjxm84cvTeNZNXPc", "entity_type": "SPLIT_TRANSFER", "subtype": "DISPUTE_MERCHANT_DEBIT", "should_fund": true, ... } ``` **Settlement Entry for Merchant B's Split Transfer ($4.00)**: ```json { "id": "SEmB6iW81ie9XwDyttX4sWK3", "amount": 400, "currency": "USD", "entity_id": "split_transfer_6iW81ie9XwDyttX4sWK3cg", "entity_type": "SPLIT_TRANSFER", "subtype": "DISPUTE_MERCHANT_DEBIT", "should_fund": true, ... } ``` #### Rounding When proportional calculations result in amounts that don't divide evenly, the primary merchant absorbs the rounding difference to ensure the total equals exactly the dispute amount. #### Dispute outcomes - **Ruled in favor of buyer** - No additional money movement occurs - **Ruled in favor of merchant** - A `MERCHANT_CREDIT` adjustment `Transfer` is created with `Split Transfers` of `type: DISPUTE_MERCHANT_CREDIT`, returning funds proportionally to each `Merchant`. For more information on disputes in general, see [Disputes](/guides/after-the-payment/disputes/how-disputes-work). ## ACH returns ACH return handling for split transactions is configured at the `Application`-level by Finix. By default, the primary `Merchant` is debited for the return. To change the default behavior, contact your Finix point of contact or email [Finix Support](/guides/getting-started/support-at-finix). Viewing your ACH return configuration Your `Application`'s ACH return configuration can be viewed in the Finix Dashboard on the **Company** page, under the **Split Transfer Configurations** section. There are two options for how the return can be handled: ### Option 1 - primary Merchant-only debited for ACH return (default) The default behavior is to apply the return amount to the primary merchant only. The `Application` › `split_transfer_configuration` ACH settings are set to `PRIMARY_MERCHANT` for all ACH returns. ```json { "id": "AP7jSy5H46TXXo8MsTWHcfNK", "created_at": "2025-03-21T16:03:17.13Z", "updated_at": "2025-05-20T22:21:01.35Z", ... "split_transfer_configuration": { "ach_debit_return_strategy": "PRIMARY_MERCHANT", "ach_credit_return_strategy": "PRIMARY_MERCHANT", } ... } ``` ### Option 2 - proportionally distribute amounts against original Merchants ratio To enable this option, reach out to [Finix Support](mailto:support@finix.com). The other option is to proportionally distribute the return amount against the original merchants ratio. For example, if Merchant A and Merchant B are 60/40 and the return is $10.00, Merchant A would be debited $6.00 and Merchant B would be debited $4.00. The `Application` › `split_transfer_configuration` ACH settings are set to `PROPORTIONALLY_DISTRIBUTE_AMOUNTS_AGAINST_ORIGINAL_MERCHANTS_RATIO` for all ACH returns. ```json { "id": "AP7jSy5H46TXXo8MsTWHcfNK", "created_at": "2025-03-21T16:03:17.13Z", "updated_at": "2025-05-20T22:21:01.35Z", ... "split_transfer_configuration": { "ach_debit_return_strategy": "PROPORTIONALLY_DISTRIBUTE_AMOUNTS_AGAINST_ORIGINAL_MERCHANTS_RATIO", "ach_credit_return_strategy": "PROPORTIONALLY_DISTRIBUTE_AMOUNTS_AGAINST_ORIGINAL_MERCHANTS_RATIO", } ... } ``` #### 1. ACH return When an ACH Direct Debit fails, Finix automatically creates an ACH Return to recover the original payment amount. The `Transfer` will have: - `split_transfers` array containing IDs for each participant. - `subtype: SYSTEM` to indicate that the `Transfer` was created by Finix. - The return reason code will appear in the `tags` field (e.g., `"result_message_0": "ReasonCode: R04")`. - `type: REVERSAL` to indicate that the `Transfer` is a reversal of the original `Transfer`. ```json ACH Return For Split Transaction { "id": "TR8K7zFd9wvEwAG7AvCMLShg", "created_at": "2025-07-29T17:19:11.26Z", "updated_at": "2025-07-29T17:20:02.68Z", ... "parent_transfer": "TRjAnCNNSxDCW8GDsxYobHHe", "split_transfers": [ "split_transfer_6iVWXfDjxm84cvTeNZNXPc", "split_transfer_6iW81ie9XwDyttX4sWK3cg" ], "subtype": "SYSTEM", "supplemental_fee": null, "tags": { "result_message_0": "ReasonCode: R04", "result_message_1": "ReasonDescription: Invalid Account Number", }, "third_party_details": null, "tip_amount": null, "trace_id": "2cdfa359-b9d5-4185-aa66-252a00001ea5", "type": "REVERSAL", ... } ``` #### 2. Split Transfers created Each `Split Transfer` has `type: CREDIT` and an amount proportional to the merchant's share of the original sale. **Split Transfer for Merchant A (primary) - 60% of $10.00 = $6.00**: ```json { "id": "split_transfer_6iVWXfDjxm84cvTeNZNXPc", "amount": 600, "currency": "USD", "merchant_id": "MUmfEGv5bMpSJ9k5TFRUjkmm", "parent_transfer_id": "TR8K7zFd9wvEwAG7AvCMLShg", "type": "CREDIT", ... } ``` **Split Transfer for Merchant B - 40% of $10.00 = $4.00**: ```json { "id": "split_transfer_6iW81ie9XwDyttX4sWK3cg", "amount": 400, "currency": "USD", "merchant_id": "MU7noQ1wdgdAeAfymw2rfBMq", "parent_transfer_id": "TR8K7zFd9wvEwAG7AvCMLShg", "type": "CREDIT", ... } ``` #### 3. Settlement entries created `Settlement Entries` are created for each `Split Transfer`. The adjustment `Transfer` itself is **not** placed in a settlement—instead, `Settlement Entries` reference each `Split Transfer`. **Key fields on the settlement entry:** - `entity_type: SPLIT_TRANSFER` - Indicates this entry is for a `Split Transfer` - `subtype: CREDIT` - Mirrors the `Split Transfer` › `type` indicates this is a credit entry. **Settlement Entry for Merchant A's Split Transfer ($6.00)**: ```json { "id": "SEmA6iVWXfDjxm84cvTeNZNX", "amount": 600, "currency": "USD", "entity_id": "split_transfer_6iVWXfDjxm84cvTeNZNXPc", "entity_type": "SPLIT_TRANSFER", "subtype": "CREDIT", "should_fund": true, ... } ``` **Settlement Entry for Merchant B's Split Transfer ($4.00)**: ```json { "id": "SEmB6iW81ie9XwDyttX4sWK3", "amount": 400, "currency": "USD", "entity_id": "split_transfer_6iW81ie9XwDyttX4sWK3cg", "entity_type": "SPLIT_TRANSFER", "subtype": "CREDIT", "should_fund": true, ... } ``` #### Rounding When proportional calculations result in amounts that don't divide evenly, the primary merchant absorbs the rounding difference to ensure the total equals exactly the ACH return amount. --- # Finix.js Migration Guide (v1 -> v2) Source: https://docs.finix.com/guides/online-payments/payment-tokenization/finix-js-migration-guide-v1-to-v2 This guide walks through the changes required to migrate from **Finix Tokenization Library v1** to **v2**. ## Why do we have a Finix.js v2? Our Finix.js v2 is a major architectural improvement over v1. While the migration path is intentionally minimal, v2 delivers major improvements in **security**, **performance**, and **flexibility**. The underlying tokenization model remains the same, but the delivery, initialization flow, and internal design are now optimized. ### What stays the same - Same tokenization flow - Drop-in form component with no PCI exposure - Same conceptual model of “embed → receive token” ### What’s improved - Cleaner initialization - Simpler integration code - Better separation of configuration vs. runtime behavior - Improved form UI ### What’s new under the hood - 10× smaller bundle size - Fewer internal dependencies - Improved security - More resilient communication between parent + iframe - Stronger isolation of sensitive payment fields ### Why this matters v2 is built for: - Embedded payment experiences - Component-based UI frameworks - Shadow DOM use cases - Web app environments where isolation, reliability, and performance are critical By simplifying the integration API and optimizing the internal runtime, v2 enables customers to ship more secure and performant PCI-compliant payment experiences with less code. ## Overview of what changed The migration from **v1 to v2** introduces a cleaner initialization model. Most of the library remains familiar, but a few key responsibilities have shifted. Here are the primary differences: ### ✔️ Updated script version You'll load v2 instead of v1: - v1: `https://js.finix.com/v/1/finix.js` - v2: `https://js.finix.com/v/2/finix.js` ### ✔️ TokenForm → PaymentForm The entry point for embedding changes: ```diff - Finix.TokenForm(...) + Finix.PaymentForm(...) ``` ### ✔️ Initialization now includes environment + Application ID In v1 these values were passed into `.submit()`: ```js form.submit("sandbox", "APP_ID", ...) ``` In v2, they become part of initialization: ```js Finix.PaymentForm(..., "sandbox", "APP_ID", ...) ``` ### ✔️ Submit callback moves into options In **v1**, your `onSubmit` handler existed, but it was only a trigger — you still had to call `form.submit()` from inside it, and you needed to pass both the **environment** and the **Application ID** at that moment. Example v1 flow: ```js onSubmit(...) { form.submit("sandbox", "APP_ID", (error, response) => { ... }); } ``` In **v2**, the form takes care of all submit logic internally, as long as you provide an onSubmit callback upfront. The environment and application are already bound during initialization, so your callback is now **just** a response handler — much simpler and much safer. v2 usage: ```js Finix.PaymentForm(..., { onSubmit: (error, response) => { // Your callback logic } }); ``` ### But what if you still want manual submission? You can still invoke `form.submit()` in v2. However, the behavior has changed in an important way: - You **no longer pass** environment and application parameters - You **do still pass** a callback function (just like v1) In **v1**, a manual submission looked like: ```js form.submit("sandbox", "APP_ID", (error, response) => { // your code }); ``` In **v2**, a manual submission looks like: ```js form.submit((error, response) => { // your callback logic }); ``` This callback receives: - `error` - any validation or network errors - `response` - the tokenization response Manual submission is useful when: - You want to control **precisely when** a submission occurs - You want to implement **custom UI flows** - You want to handle **additional validation or analytics** - You want to **prevent auto-submit** and only submit manually ### Summary - v1 required you to **call submit manually** and pass the environment and application ID parameters every time. - v2 only requires passing **onSubmit once**, and **Finix handles submission automatically**. - You can still call `.submit()` manually, but it is now fully context-aware and requires **no additional arguments**. The result is a drastically simpler and safer integration model, especially for larger or event-driven applications. ## Step-by-Step migration ### 1. Update the ` ``` After (v2): ```js ``` ### 2. Replace TokenForm with PaymentForm Before: ```js Finix.TokenForm(...) ``` After: ```js Finix.PaymentForm(...) ``` ### 3. Move Application ID and environment to initialization v1: ```js form.submit("sandbox", "APP_ID", ...) ``` v2: ```js Finix.PaymentForm("finix-form", "sandbox", "APP_ID", options); ``` ### 4. Move submit callback into options v1: ```js form.submit(..., (error, response) => { ... }) ``` v2: ```js Finix.PaymentForm("finix-form", "sandbox", "APP_ID", { onSubmit: (error, response) => { ... } }); ``` ## Complete v1 example (before migration) ```html
``` ## Full v2 example (after migration) ```html
``` ## PaymentForm API reference ```ts Finix.PaymentForm( element, // required: DOM ID string OR HTMLElement reference environment, // required: "sandbox" | "prod" applicationId, // required: must belong to chosen environment options, // optional: behavior customization, including onSubmit ); ``` ## Element parameter details You may pass either: ### 1) A DOM element ID (string) ```js Finix.PaymentForm("finix-form", "sandbox", "APP_ID"); ``` ### 2) A DOM reference ```js const container = document.getElementById("finix-form"); Finix.PaymentForm(container, "sandbox", "APP_ID"); ``` DOM references improve compatibility with: - Shadow DOM - Web components - Micro frontends - Modern UI frameworks ## Environment + Application ID rules - Allowed environments: `sandbox` and `prod` - Your Application ID **must** belong to the same environment to ensure you are tokenizing against the correct environment/services. - Sandbox ID + `prod` = will fail - Prod ID + `sandbox` = will fail ## Migration checklist - [ ] Update script reference to `/v/2/` - [ ] Replace `TokenForm` with `PaymentForm` - [ ] Move Application ID from submit to initialization - [ ] Move environment from submit to initialization - [ ] (Optional) Move submission callback to `onSubmit` option - [ ] Test token generation ## Complete example (v2) ```html Payment Form Minimal

Payment Form Test Page

``` ## Accepted payment methods (cards vs. bank accounts) In **v1**, you needed to control accepted payment methods at the initializer level, which required switching payment methods and swapping initializer functions. - `TokenForm()` - supported **both card + bank** - `CardTokenForm()` - supported **card only** - `BankTokenForm()` - supported **bank only** ### V2 simplifies this with a single initializer In **v2**, there is only **one initializer** (`Finix.PaymentForm()`), and you configure the acceptable payment methods with the `paymentMethods` option. #### Default behavior ```js paymentMethods: ["card", "bank"]; ``` This matches `TokenForm()` from v1 (both are accepted). #### To accept **only card** ```js paymentMethods: ["card"]; ``` #### To accept **only bank** ```js paymentMethods: ["bank"]; ``` ## Migration mapping | v1 initializer | v2 equivalent | | --- | --- | | `TokenForm()` | `Finix.PaymentForm(..., { paymentMethods: ["card","bank"] })` (default) | | `CardTokenForm()` | `Finix.PaymentForm(..., { paymentMethods: ["card"] })` | | `BankTokenForm()` | `Finix.PaymentForm(..., { paymentMethods: ["bank"] })` | ## Example usage ### Example: Card-only form ```js Finix.PaymentForm("finix-form", "sandbox", "APP_ID", { paymentMethods: ["card"], onSubmit: (error, response) => { console.log("Generated token:", response?.data?.id); }, }); ``` ### Example: Bank-only form ```js Finix.PaymentForm("finix-form", "sandbox", "APP_ID", { paymentMethods: ["bank"], onSubmit: (error, response) => { console.log("Generated token:", response?.data?.id); }, }); ``` ### Example: (Default) card + bank ```js Finix.PaymentForm("finix-form", "sandbox", "APP_ID", { // paymentMethods default to ["card", "bank"], onSubmit: (error, response) => { console.log("Generated token:", response?.data?.id); }, }); ``` ## Support For migration assistance: - Email: [Finix Support](mailto:support@finix.com) - Contact your Finix representative We want to help you transition as smoothly as possible. --- # Handling Raw Card Data Source: https://docs.finix.com/guides/online-payments/payment-tokenization/handling-raw-card-data This guide outlines the steps for building your own payment form for processing raw card data instead of using Finix’s Tokenization Forms (requires full PCI compliance). Finix is certified as a Level 1 Payment Card Industry Data Security Standards (PCI DSS) compliant Service Provider. For more details, see [Security and Compliance at Finix](/guides/managing-operations/security-compliance). If you have a Level 1 PCI compliant card data environment (CDE), you don't have to use the forms offered by Finix and can create your own form or flow to collect buyer information. Processing raw card data If you're interested in processing raw card data, contact the [Finix Support Team](mailto:support@finix.com). A Level 1 or 2 PCI Attestation of Compliance (AoC) needs to be provided to Finix to process raw card data. If you don't have a CDE and want to process payments, use [Finix's Tokenization Form](/guides/online-payments/payment-tokenization/tokenization-forms) to collect buyer information. To collect raw card data, you need to be [fully PCI compliant](/guides/managing-operations/security-compliance/pci-dss-compliance). If you're not fully PCI compliant, use our [Tokenization Form](/guides/online-payments/payment-tokenization/tokenization-forms) instead. Processing raw card data is similar to processing [other payments](/guides/online-payments) that use our Tokenization Forms. Steps include: - Building a payment form for cards - When handling raw card data, you'll need to create the form as opposed to hosting a form created by Finix. - [Creating a Payment Instrument](/guides/getting-started/developer-quickstart#step-2-tokenize-payment-details) - [Creating a Sale or Authorization](/guides/getting-started/developer-quickstart#step-3-make-a-payment) - [Handling the post-payments experience](/guides/after-the-payment) ## Building a payment form The form you create must collect enough information to successfully create an `Identity` and [`Payment Instrument`](/api/payment-instruments/createpaymentinstrument) for the buyer. The information also needs to be collected in a PCI compliant environment. - Once the buyer submits the information, submit a request from your PCI server to [Create an Identity](/api/identities/createidentity). - Use that `Identity` to [Create a Payment Instrument](/guides/getting-started/developer-quickstart#step-2-tokenize-payment-details) and proceed with the usual steps you'd take to process a payment, such as [Creating a Transfer](/api/transfers/createtransfer). --- # Payment Tokenization Source: https://docs.finix.com/guides/online-payments/payment-tokenization Learn how to securely collect payment details for your buyers and sellers. Tokenization is the process of encrypting your buyer's and seller's sensitive data into a non-sensitive equivalent. To pass off the burden of PCI DSS compliance, you can use Tokenization Forms to collect and tokenize the details of your buyers and sellers. Finix is certified as a Level 1 PCI DSS compliant Service Provider. This is the most stringent level of security certification available in the payments ecosystem. ## Learn more Handling Raw Card Data Learn how to build your own payment form for processing raw card data instead of using Finix’s Tokenization Forms (requires full PCI compliance). Mobile Tokenization (Android) Learn how to build a tokenization form for your Android app to accept payment details securely. Mobile Tokenization (iOS) Learn how to accept and secure payment details cards in your iOS app. Tokenization Forms Learn how to use Tokenization Forms to securely accept the payment details of your buyers. --- # Mobile Tokenization (Android) Source: https://docs.finix.com/guides/online-payments/payment-tokenization/mobile-tokenization-android This article details how to build a tokenization form for your Android app. The payment details buyers submit in the tokenization form are secured via [tokenization](/guides/online-payments/payment-tokenization) and stored in Finix's vault, so payment information is never exposed and minimizes your PCI scope. If you have questions about building your app's tokenization form, reach out to your Finix point of contact or email the [Finix Support team](/guides/getting-started/support-at-finix/). ## Prerequisites The library is built 100% on Kotlin utilizing the Jetpack Compose library for the UI. A demo app is available in the following Github repo: [Finix Android Payment Sheet app](https://github.com/finix-payments/finix-android-payment-sheet-app). Latest version of the library can be found on [Maven Central](https://central.sonatype.com/artifact/com.finix/finix-android-payment-sheet). Import by including `mavenCentral()` in your buildscript inside the `build.gradle` project. ```java buildscript { repositories { mavenCentral() } } ``` After you confirm Maven Central is in your buildscript, you can import our library by adding the following to your gradle file: ```java buildscript { ext.finix_version = '0.4.1' } dependencies { implementation 'com.finix:finix-android-payment-sheet:finix_version' } ``` ## Step 1: Create a Kotlin file Create a new Kotlin file and save it with the `.kt` extension. Next, create a function to handle the tokenization form. You can define it using the following: ```java @Composable fun showMyPaymentSheet() { CompletePaymentSheetOutlined( onDismiss = { /*TODO*/ }, onNegativeClick = { /*TODO*/ }, onPositiveClick = { token -> } ) } ``` ## Step 2: Launch the Tokenization Form Using the `viewModel`, you can control when exactly the tokenization form is called on the `MainCheckOutScreen` and prompts the buyer to enter their information. Add in the relevant logic so the tokenization form gets called when you'd want your buyers to enter their information: ```java @Composable fun MainCheckOutScreen() { val viewModel = viewModel() val state = viewModel.state if(state.showMyPaymentSheet ) { showMyPaymentSheet() } } ``` When the tokenization form is returned successfully, save the token response contained in `onPositiveClick`: ```java onPositiveClick = { token -> viewModel.saveTokenResponse(token) } ``` It contains the results of the tokenization request and the buyer's tokenized payment details. The structure of the token is: ```java data class TokenizedResponse( val id:String?, val fingerprint:String?, val createdAt:String?, val updatedAt:String?, val type:String?, val expiresAt:String?, val currency:String?, ) ``` For a detailed example of how to use our Android tokenization library, see the following GitHub repo: [Finix Android Payment Sheet app](https://github.com/finix-payments/finix-android-payment-sheet-app). ## Step 3: Create a Payment Instrument With the token saved, you're ready to process a transaction. Before you can use the tokenized details in a transaction, you must create a `Payment Instrument`. Make a POST request to the `/payment_instrument` endpoint and [create a Payment Instrument](/api/payment-instruments/createpaymentinstrument) with the relevant token and `Identity` information. The token to use is available in the `TokenResponse`. The structure of the `TokenResponse` is: ```java id: \(instrument.id) fingerprint: \(instrument.fingerprint) created: \(instrument.created) updated: \(instrument.updated) instrument: \(instrument.instrument) expires: \(instrument.expires) isoCurrency: \(instrument.isoCurrency) ``` Token usage and expiration Use new tokens immediately to create a Payment Instrument. Tokens expire 30 minutes after being created. Example API Definition ### 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 creating a Payment Instrument can lower the interchange on credit card transactions | | `identity` | *string*, **required** | ID for the Identity resource which the account is to be associated | | `name` | *string*, **required** | Full name of the registered card holder | | `token` | *string*, **required** | ID for the Token that was returned via the tokenization client | | `type` | *string*, **required** | Must pass TOKEN as the value | ### 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*, **required** | Zip or Postal code (max 7 characters) | | `region` | *string*, **optional** | 2-letter State code | Example Response: ```json { "id": "PImmCg3Po7oNi7jaZcXhfkEu", "created_at": "2022-10-10T05:32:17.78Z", "updated_at": "2022-10-10T05:35:04.55Z", "application": "APgPDQrLD52TYvqazjHJJchM", "created_via": "API", "currency": "USD", "enabled": true, "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY", "identity": "IDgWxBhfGYLLdkhxx2ddYf9K", "instrument_type": "PAYMENT_CARD", "address": { "line1": "900 Metro Center Blv", "line2": null, "city": "San Francisco", "region": "CA", "postal_code": "94404", "country": "USA" }, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "bin": "520082", "brand": "MASTERCARD", "card_type": "DEBIT", "expiration_month": 12, "expiration_year": 2029, "issuer_country": "NON_USA", "last_four": "8210", "name": "Amy White", "security_code_verification": "MATCHED", "tags": { "card_name": "Business Card" }, "type": "PAYMENT_CARD", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/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/PImmCg3Po7oNi7jaZcXhfkEu/updates" } } } ``` ## Step 4: Processing Live transactions When you've completed testing, you can take your tokenization form live by making the following changes: - Set `sandbox` to **false** - Add your `Application_id` ```java @Composable fun showMyPaymentSheet(viewModel: CheckOutViewModel) { CompletePaymentSheetOutlined( onDismiss = { viewModel.setShowMyPaymentSheet(false) }, onNegativeClick = { viewModel.setShowMyPaymentSheet(false) }, onPositiveClick = { token -> viewModel.saveTokenResponse(token) viewModel.setShowMyPaymentSheet(false) }, applicationId = MY_APPLICATION_ID, isSandbox = false, ) } ``` Taking your tokenization form live will process real money movements. For details on how to take your sandbox live, see [Signing Up for a Finix Account.](/guides/getting-started/finix-sign-up/) ## Customize Tokenization Forms You can customize several parts of the tokenization forms to match your brand and voice. ### Style There are two styles available for your app's tokenization form: - **OutlinedTextField** has text fields with rounded corners. - **ClassicTextField** has text fields with square corners and is boxier. details summary Tokenization Form Styles | Classic Text Field | Outlined Text Field | | --- | --- | | | | Once you’ve selected a style, decide on how much information the Tokenization Form should request from buyers. - Collect the most information to reduce fraud via Card and AVS checks. - Collect less information to speed up the cardholder experience. For more details on the different Card and AVS checks, see [Card and Address Verification Checks](/guides/online-payments/fraud-and-risk/risk-rules-card-checks#address-verification-avs-checks). ### Types of Tokenization Forms Several tokenization forms are available to choose from that differ in how much information is requested. We recommend using either the *Complete* or *Partial* tokenization form for most use cases. Sheet charts details summary Tokenization Form Types | Information Collected | COMPLETE sheet | PARTIAL sheet | BASIC sheet | MINIMAL sheet | INTERNATIONAL sheet | BANK ACCOUNT sheet | | --- | --- | --- | --- | --- | --- | --- | | ClassicTextField Function Name | CompletePaymentSheet | PartialPaymentSheet | BasicPaymentSheet | MinimalPaymentSheet | InternationalPaymentSheet | BankAccountSheet | | OutlinedTextField Function Name | CompletePaymentSheetOutlined | PartialPaymentSheetOutlined | BasicPaymentSheetOutlined | MinimalPaymentSheetOutlined | InternationalPaymentSheetOutlined | BankAccountSheetOutlined | | Name | X | X | X | | | | | Card | X | X | X | X | | | | Expiration Date | X | X | X | X | | | | CVV | X | X | X | X | X | | | Address | X | | | | | | | Address Ext. | X | | | | | | | City | X | | | | | | | State | X | | | | | | | ZIP/Postal Code | X | X | | | X | | | Country and Region | | | | | | | | Accounting Number | | | | | | X | | Routing Number | | | | | | X | ### Customizing Tokenization Forms Once you’ve chosen a tokenization form, you can begin customizing it to fit the look and feel of your application. The complete list of items you can add to the tokenization form includes the following: ```javascript @Composable fun CompletePaymentSheetOutlined( modifier: Modifier = Modifier, applicationId: String = "", isSandbox: Boolean = true, paymentSheetResources: PaymentSheetResources = PaymentSheetResources(), paymentSheetColors: PaymentSheetColors = PaymentSheetColors(), logoTextStyle: TextStyle = MaterialTheme.typography.headlineSmall, textStyle: TextStyle = LocalTextStyle.current, buttonTextFont: TextUnit = BUTTON_TEXT_FONT, onDismiss: () -> Unit, onNegativeClick: () -> Unit, onPositiveClick: (TokenizedResponse) -> Unit ) ``` | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `applicationID` | *String*, **optional** | none | Update this to your `Application#id`, so you can manage the tokens. If not included, you won't be able to create [`Payment Instruments`](/api/payment-instruments) with the results of the sheet. | | `isSandbox` | *Boolean*, **optional** | true (Sandbox) | Update this to false if you want to create tokens in a live environment. | | `paymentSheetResources` | *object*, **optional** | See below | Add custom images and text to the tokenization form. | | `paymentSheetColors` | *object*, **required** | See below | Customize the colors of the tokenization form. | | `logoTextStyle` | *TextStyle*, **required** | `MaterialTheme.typography.headlineSmall` | Configure the styling of the text in the logo. | | `textStyle` | *TextStyle*, **required** | `LocalTextStyle.current` | Configure the styling of the text in the input fields. | #### PaymentSheetResources ```java data class PaymentSheetResources( @DrawableRes val logoDrawable: Int = R.drawable.ic_default_logo, @StringRes val logoText: Int = R.string.default_logo_text, @StringRes val tokenizeButtonText: Int = R.string.btn_tokenize, @StringRes val cancelButtonText: Int = R.string.btn_cancel, val cancelButtonWeight: Float = 0.6f, val tokenizeButtonWeight: Float = 0.8f, ) ``` | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `logoDrawable` | *int*, **required** | Defaults to a logo for Daphne's Corner. | The image at the top of the tokenization form. Replace this with your own logo. The uploaded logo will have a 76.dp radius. | | `logoText` | *int*, **required** | **Daphne’s Corner** | The header to the right of `logoDrawable`. Update this with your company name or the name of the tokenization form. The header will be centered on the page. | | `tokenizeButtonText` | *int*, **required** | **Tokenize** | The text inside the button buyers press to submit the sheet. | | `cancelButtonText` | *int*, **required** | **Cancel** | The text buyers press to leave the tokenization form. | | `tokenizeButtonWeight` | *float*, **required** | **Tokenize** | Control the spacing of the **Tokenize** button. | | `cancelButtonWeight` | *float*, **required** | **Cancel** | Control the spacing of the **Cancel** button. | #### PaymentSheetColors ```java data class PaymentSheetColors( val surface: Color = Color.White, val logoTextColor: Color = Color.Black, val textColor: Color = Color.Black, val errorContainerColor: Color = FinixErrorTextSurface, val containerColor: Color = FinixGray, val focusedIndicatorColor: Color = FinixBlue, val unfocusedIndicatorColor: Color = Color.Transparent, //hide the indicator val focusedLabelColor: Color = FinixBlue, val unfocusedLabelColor: Color = Color.Black, val placeholderColor: Color = FinixPlaceHolderTextGray, val errorIndicatorColor: Color = FinixErrorRed, val errorLabelColor: Color = FinixErrorRed, val errorPlaceholderColor: Color = FinixPlaceHolderTextGray, val tokenizeButtonColor: Color = FinixBlue, val tokenizeButtonTextColor: Color = Color.White, val cancelButtonColor: Color = FinixRed, val cancelButtonTextColor: Color = Color.White, ) ``` | | | | | | --- | --- | --- | --- | | **Name** | **Type** | **Default** | **Description** | | surface | *Color*, **Required** | Color.White | The color of the tokenization form background. | | logoTextColor | *Color*, **Required** | Color.Black | The color of the title text. | | textColor | *Color*, **Required** | Color.Black | The color of the input text used in text fields. | | containerColor | *Color*, **Required** | FinixGray | The surface color of the `textfield`. | | errorContainerColor | *Color*, **Required** | FinixErrorTextSurface | The surface color of the `textfield` when there's an error. | | errorBorderColor | *Color*, **Required** | FinixErrorRed | The color of the `textfield` border when there's an error. | | focusedIndicatorColor | *Color*, **Required** | FinixBlue | The color of the `textfield` border when the field is active. | | unfocusedIndicatorColor | *Color*, **Required** | Color.Transparent | The color of the `textfield` border when the field is inactive and not being used. | | focusedLabelColor | *Color*, **Required** | FinixBlue | The color of the `textfield` label when the field is active. | | unfocusedLabelColor | *Color*, **Required** | Color.Black | The color of the `textfield` label when the field is inactive and not being used. | | errorLabelColor | *Color*, **Required** | FinixErrorRed | The color of the `textfield` label when there's an error. | | placeholderColor | *Color*, **Required** | FinixPlaceHolderTextGray | The color of the `textfield` placeholder. | | tokenizeButtonColor | *Color*, **Required** | FinixBlue | The surface color of the tokenize button. | | tokenizeButtonTextColor | *Color*, **Required** | Color.White | The color of the text in the tokenize button. | | cancelButtonColor | *Color*, **Required** | FinixRed | The surface color of the cancel button | | cancelButtonTextColor | *Color*, **Required** | Color.White | The color of the text in the cancel button. | ## Debugging Tokenization Forms Our Android tokenization library uses the following libraries and dependencies: ```java android { ... compileSdk 33 defaultConfig { minSdk 24 targetSdk 33 aarMetadata { minCompileSdk = 24 } } .... kotlinOptions { jvmTarget = 11 } buildFeatures { compose true } composeOptions { kotlinCompilerExtensionVersion '1.4.0-alpha02' } } ``` | | | | --- | --- | | **Name** |  **Version** | | Kotlin |  `org.jetbrains.kotlin:kotlin-bom:1.8.10` | | Kotlin Compose |  `androidx.compose:compose-bom:2023.01.00` | | Kotlin Compiler |  `kotlinCompilerExtensionVersion '1.4.0-alpha02'` | | Material3 | androidx.compose.material3:material3:1.2.0-alpha01androidx.compose.material3:material3-window-size-class:1.2.0-alpha01 | Before using our Android Tokenization library, verify you're using a compatible versions of our SDK and have a compatible version of Kotlin installed: - `minSdk` - **24** - `targetSdk` - **33** - `compileSdk` - **33** If you run into any issues, verify you have the minimum or latest version of the relevant dependency installed. For details on how to update any of the above, see: [Compose to Kotlin Compatibility Map](https://developer.android.com/jetpack/androidx/releases/compose-kotlin). If you continue to run into issues, reach out to the [Finix Support Team](mailto:support@finix.com). --- # Mobile Tokenization (iOS) Source: https://docs.finix.com/guides/online-payments/payment-tokenization/mobile-tokenization-ios This article details how to accept the payments details of your buyer and secure their information in your iOS app. Payment details get secured via [tokenization](/guides/online-payments/payment-tokenization) and stored in Finix's vault, so payment information is never exposed and minimizes your PCI scope. If you have any questions about using Finix, reach out to your Finix point of contact or email the [Finix Support team](/guides/getting-started/support-at-finix/) at anytime! ## Step 1: Add the FinixPaymentSheet framework Use the FinixPaymentSheet SDK and Test App. Add the SDK to your application. FinixPaymentSheet This framework provides a Payment Sheet that you can use to tokenize credit cards. It provides a presenter or you can present the PaymentInputController yourself. ## Step 2: Import library You can access PaymentsSDK by importing the library. ```swift import FinixPaymentSheet ``` ## Step 3: Initialize tokenizer class The PaymentsSDK provides a Test app that you can utilize to build your own application. It's composed of 2 delegates and 2 ViewControllers - ResultViewController: used to react to the result of the tokenization form - ViewController: used to initialize and configure the tokenization form to your specifications ## Step 4: Create a Payment Instrument Before you can use the newly tokenized card or bank account you will need to associate it with an `Identity`. To do this, make an authenticated `POST` request to the `/payment_instrument` and create a `Payment Instrument` with the relevant token and `Identity` information. You can access the Token from the `TokenResponse`. TokenResponse is of the following structure: ```swift id: \(instrument.id) fingerprint: \(instrument.fingerprint) created: \(instrument.created) updated: \(instrument.updated) instrument: \(instrument.instrument) expires: \(instrument.expires) isoCurrency: \(instrument.isoCurrency) ``` Token invalidation Tokens should be associated right away. Tokens that don't get associated within 30 mins of creation get invalidated. Example API Definition Example Payment Instrument - Token - Card ```json Payment Instrument - Token - Card { "id": "PImmCg3Po7oNi7jaZcXhfkEu", "created_at": "2022-10-10T05:32:17.78Z", "updated_at": "2022-10-10T05:32:17.78Z", "account_updater_enabled": false, "application": "APgPDQrLD52TYvqazjHJJchM", "created_via": "API", "currency": "USD", "enabled": true, "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY", "identity": "IDjvxGeXBLKH1V9YnWm1CS4n", "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": "520082", "brand": "MASTERCARD", "card_type": "DEBIT", "expiration_month": 12, "expiration_year": 2029, "issuer_country": "USA", "last_four": "8210", "name": "Amy White", "network_token_enabled": false, "network_token_state": "NOT_ENABLED", "security_code_verification": "UNKNOWN", "tags": { "card_name": "Business Card" }, "type": "PAYMENT_CARD", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDjvxGeXBLKH1V9YnWm1CS4n" }, "updates": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/updates" } } } ``` API Definition --- # Tokenization Forms Source: https://docs.finix.com/guides/online-payments/payment-tokenization/tokenization-forms Token forms Use Tokenization Forms to collect and tokenize the payment details of buyers. Our Tokenization Form offers a low-code solution to easily take in credit card and bank data and tokenize in a PCI-compliant way. Finix’s Tokenization Forms provide flexible customization options, including the ability to: - Show and hide specific fields - Customize labels and placeholder text - Modify error messages to match your brand's voice - Control input styling both inside and outside the iframe - Accept both card and ACH payment methods in a single form - Use custom fonts within the embedded iframe - Pre-fill values for select fields - Manage multiple forms on the same page simultaneously The primary method for creating a Tokenization Form is `Finix.PaymentForm`. Use the `paymentMethods` option to control which payment types to accept: | Payment Methods Option | Description | | --- | --- | | `["card", "bank"]` | Accept both card and bank accounts (default) | | `["card"]` | Accept only credit or debit cards | | `["bank"]` | Accept only bank accounts (USA and CAN) | Every Tokenization Form uses a versioned `finix.js` JavaScript library to secure sensitive card and bank account data. Having buyers input their data into a Tokenization Form prevents third parties from accessing the submitted information. Once initialized, the library communicates the state of the form through a JavaScript callback. The `state` object includes logic that validates the payment details submitted by the buyer. ## Tokenization overview Tokenization Form Sequence Diagram ### Tokenization example ### Step 1: Send token information via **Finix.js** #### Install Finix.js library First, we'll need to add the `finix.js` library to the webpage hosting the form that collects payment details. To add the library, include the following the script: ```html ``` To remain compliant with security standards, the library should always be loaded directly from https://js.finix.com and should never be self hosted or included in your own code bundle. #### Initialize the Tokenization Form Use the `Finix.PaymentForm` function to create an instance of the Finix object and automatically render the payment form into your desired location: ```javascript Finix.PaymentForm(element, environment, application, options); ``` | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `element` | `string` or `HTMLElement` | Yes | The location in your website where you want to load the payment form. This can either be a string of the ID of the element or a direct reference to the HTML Element object itself. When using a string, the element must have the exact matching `id` attribute (class references are not supported). | | `environment`                | `string` | Yes | The environment to use. Must match the environment of the Application ID. Supported values: `sandbox`, `prod`. | | `application` | `string` | Yes | Your Application ID assigned by Finix when you create your account. Applications can exist in both Sandbox and Prod environments. | | `options` | `object` | No | An optional object to customize the Payment Form. See below for available options. | V1 Deprecated Methods The following methods are deprecated and should be replaced with `Finix.PaymentForm`: - `Finix.TokenForm` → Use `PaymentForm` with `paymentMethods: ["card", "bank"]` - `Finix.CardTokenForm` → Use `PaymentForm` with `paymentMethods: ["card"]` - `Finix.BankTokenForm` → Use `PaymentForm` with `paymentMethods: ["bank"]` See [Migrating from V1 to V2](#migrating-from-v1-to-v2) for migration instructions. #### Define input fields Next, define and customize what exact fields will be included and required in the Tokenization Form. Lowering interchange on credit cards Requesting an address in your Tokenization Form can lower interchange on credit card transactions. Aspects of the input fields you can change include: | Field | Type | Description | | --- | --- | --- | | `paymentMethods` | `array[string]` | Specify which payment methods to allow. Options: `["card", "bank"]`, `["card"]`, or `["bank"]`. Defaults to `["card", "bank"]`. | | `showAddress` | `boolean` | Show address fields in the form (defaults to `false`). To require specific address fields, use `requiredFields`. | | `showLabels` | `boolean` | Show labels in the form (defaults to `true`). | | `labels` | `object` | Set custom labels for each field. | | `showPlaceholders` | `boolean` | Turn on or off placeholder text in the fields (defaults to `true`). | | `placeholders` | `object` | Set custom placeholders for each field. | | `hideFields` | `array[string]` | Specify which fields to hide. Not all fields can be hidden as some are required by networks. | | `requiredFields` | `array[string]` | Require any specific fields that are not required by default. | | `requireSecurityCode` | `boolean` | Set whether to require security code (CCV/CVV) for card information (defaults to `true`). | | `confirmAccountNumber` | `boolean` | Show a double confirmation input for bank account numbers to validate both entries match (defaults to `true`). | | `hidePotentialIssueMessages` | `boolean` | Hide warning messages for non-standard but valid card numbers (defaults to `true`). | | `hideErrorMessages` | `boolean` | If you want to require a field, but not hide input error messages (defaults to `false`). | | `errorMessages` | `object` | Set custom error messages for each field if you are showing error messages. | | `defaultValues` | `object` | Set default values for each field. Cannot pre-fill card or bank information due to PCI compliance. | | `fonts` | `array[object]` | Set custom fonts to be used inside the form inputs. | | `enableDarkMode` | `boolean` | Enable dark mode styling for the payment form to match dark-themed websites (defaults to `false`). Further customization available in `styles`. | | `theme` | `string` | Set the visual theme of the form. Options: `finix`, `amethyst`, `sapphire`, `topaz`, `ruby`, `emerald`, `midnight`, `elevated`. Defaults to `finix`. | | `plaidLinkSettings` | `object` | Configure Plaid bank account settings. See below for supported fields. | | `onLoad` | `function` | Callback function that triggers once the Payment Form iframe has completed initialization. | | `onUpdate` | `function` | Callback function that triggers every time the form state changes. Returns `(state, binInformation, hasErrors)`. | | `onSubmit` | `function` | Callback function for form submission. Returns `(error, response)`. When provided, automatically creates a submit button. | | `submitLabel` | `string` | Text used for the automatically generated submit button (when auto-submit behavior is used). Defaults to a generic label; override to match your checkout copy (e.g., `"Pay Now"` or `"Add Payment Method"`). | ##### Supported field IDs For `labels`, `placeholders`, `hideFields`, `requiredFields`, `errorMessages`, and `defaultValues`, the following field IDs are supported: - **Card fields:** `card_holder_name`, `number`, `expiration_date`, `security_code` - **Bank fields:** `account_holder_name`, `account_number`, `bank_code`, `account_type` - **Address fields:** `address_line1`, `address_line2`, `address_city`, `address_region`, `address_postal_code`, `address_country` Field ID restrictions Not all field IDs are supported for every option. For example, `hideFields` does not support hiding `number` or `expiration_date` as these are required by networks. The `defaultValues` option cannot pre-fill `number`, `expiration_date`, `security_code`, `account_number`, `bank_code`, `institution_number`, or `transit_number` due to PCI compliance. ##### Plaid Link settings The `plaidLinkSettings` object supports the following fields: | Field | Type | Description | | --- | --- | --- | | `displayName` | `string` | The name shown at the top of the Plaid modal. Defaults to your application name. | | `language` | `string` | The language for the Plaid link experience (defaults to `"en"`). | | `countries` | `array[string]` | ISO-3 country codes defining which banks appear in the search (defaults to `["USA", "CAN"]`). | Example: ```javascript plaidLinkSettings: { displayName: "Finix Test Merchant", language: "en", countries: ["USA", "CAN"], } ``` ##### Callback functions **`onLoad`** - Triggers once when the Payment Form iframe has completed initialization. Takes no parameters. ```javascript onLoad: function () { console.log("Payment form loaded"); } ``` **`onUpdate`** - Triggers every time the form state changes. Returns three parameters: - `state` - Object showing form state including metadata like which inputs are valid, dirty, or pristine (does not expose PI data) - `binInformation` - Object with high-level BIN data such as BIN number and card brand - `hasErrors` - Boolean indicating if the form currently has errors (useful for enabling/disabling custom submit buttons) ```javascript onUpdate: function (state, binInformation, hasErrors) { console.log("Form state:", state); console.log("BIN info:", binInformation); console.log("Has errors:", hasErrors); } ``` **`onSubmit`** - Triggers when the form is submitted. Returns two parameters: - `error` - Error object if submission failed, `null` otherwise - `response` - Response object containing the token data on success ```javascript onSubmit: function (error, response) { if (error) { console.error("Tokenization error:", error); return; } const token = response?.data?.id; console.log("Token ID:", token); } ``` Using onSubmit We highly recommend using the `onSubmit` callback rather than manually calling submit. It simplifies the integration by automatically handling submit button enabling/disabling based on form errors. If you don't use `onSubmit`, you'll need to create your own button, handle enabling/disabling based on `hasErrors` from `onUpdate`, and manually call the `submit` function. #### Style Tokenization Form Style the Tokenization Form using the `styles` option. Styles are organized by theme (`default` or `dark`), then by target element, then by state. ```js styles: { default: { /* base (light) theme */ }, dark: { /* optional dark mode overrides */ } } ``` **Available targets and states:** | Target | Supported States | Description | | --- | --- | --- | | `form` | `default` | Form global styling. | | `section` | `default` | Each section wrapper (`card`, `bank`, or `address`). | | `sectionHeader` | `default`, `focused` | Section heading text. `focused` applies when a field inside the section is focused. | | `input` | `default`, `success`, `error`, `focused` | All input fields. `success` applies when the input has a valid value. `error` applies when the input has a validation error and `showErrors` is `true`. `focused` applies while the input is focused. | | `submitButton` | `default`, `disabled` | Built-in submit button. `disabled` applies when the form has errors. | Style values are plain CSS-in-JS objects. For example: ```js styles: { default: { input: { default: { border: "1px solid #ccc", borderRadius: "8px" }, error: { border: "1px solid red" }, }, submitButton: { disabled: { opacity: 0.5 }, }, }, } ``` For full details including dark mode and available CSS properties, see [Styles & Fonts](/js/styles-and-fonts). #### Handle form submission Configure what happens when the buyer submits the form. There are two approaches: ##### Option 1: Use the `onSubmit` callback (recommended) Add the `onSubmit` callback to your options object. This automatically creates a submit button and handles enabling/disabling based on form validation: ```javascript Finix.PaymentForm("form-element", "sandbox", "APgPDQrLD52TYvqazjHJJchM", { onSubmit: function (error, response) { if (error) { console.error("Tokenization error:", error); return; } const tokenData = response.data || {}; const token = tokenData.id; // Use the token to create a payment instrument }, }); ``` ##### Option 2: Use a custom submit button If you need a custom submit button, use the `onUpdate` callback to track form errors and call `form.submit()` manually: ```javascript const submitButton = document.getElementById("submit"); const form = Finix.PaymentForm( "form-element", "sandbox", "APgPDQrLD52TYvqazjHJJchM", { onUpdate: function (state, binInformation, hasErrors) { submitButton.disabled = hasErrors; }, }, ); submitButton.addEventListener("click", function () { form.submit(function (error, response) { if (error) { console.error("Tokenization error:", error); return; } const tokenData = response.data || {}; const token = tokenData.id; // Use the token to create a payment instrument }); }); ``` ##### Callback parameters | Field | Type | Description | | --- | --- | --- | | `error` | `object` | Error object if submission failed, `null` otherwise. | | `response` | `object` | Response object containing the token data on success. | ### Step 2. Handle response from Finix.js Finix will return back a `token` with a prefix of `TK`. ```json Example Token Response { "id": "TKeD6uad8xZc52Rqg1VhvSBw", "created_at": "2025-06-10T00:31:53.54Z", "updated_at": "2025-06-10T00:31:53.54Z", "currency": "USD", "expires_at": "2025-06-11T00:31:53.54Z", "fingerprint": "FPRrcobjtdU98gr4sjiqYR1Qg", "instrument_type": "PAYMENT_CARD" } ``` Once you've handled the response, store the ID to utilize the token in the future. You will eventually send the `token` ID from your front-end client to your back-end server. ```javascript Sample Javascript workflow const tokenData = res.data || {}; // get token ID from response const token = tokenData.id; function handleResponse(response) // This would be your custom logic ``` Many customers implement additional logic after a buyer enters their payment information, using the returned `token`. For example, some customers choose to implement a different workflow depending if a `PAYMENT_CARD` or `BANK_ACCOUNT` is returned by Finix.js. ### Step 3. Send response to your backend Now that you have the `token`, you should send this to your backend. You will need this ID to eventually do an authenticated call to Finix in the next step. Token usage and expiration Tokens should be used to create a `Payment Instrument` right away in the next step. Tokens expire within 30 minutes and cannot be used after expiring. ```Sample Javascript workflow fetch('/your/backend', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ token: token }), }) ``` ### Step 4: Send an authenticated request to Finix to claim the Payment Instrument #### Create Buyer Identity Optional step if you already have a buyer identity created If you already created a Buyer Identity beforehand, you can skip this step. Before you can run a Sale or an Authorization, you'll need: - Create an `Identity` for the buyer. - Create a `Payment Instrument` with the created `Identity` and the `token` from the previous step. You can create an `Identity` with minimal or no information. - To avoid asking for the same info multiple times, you don't need to request additional information from the buyer when creating an `Identity`. - You don't need to create an additional `Identity` for the buyer if one already exists. To create an `Identity`, make a `POST` request with whatever details you've gathered (e.g. name, email, phone), or create an empty `Identity` by leaving the `entity` empty: Blank Buyer Identity Example response: Blank Buyer Identity ```json Blank Buyer Identity { "id": "ID8CKX7vwrDDrMNc7D1Cg8mb", "created_at": "2026-09-25T20:05:10.69Z", "updated_at": "2026-09-25T20:05:10.69Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "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_fingerprint": null, "business_tax_id_provided": false, "business_type": null, "default_statement_descriptor": null, "discover_mid": null, "dob": null, "doing_business_as": null, "email": null, "first_name": null, "has_accepted_credit_cards_previously": false, "incorporation_date": null, "last_name": null, "max_transaction_amount": 0, "mcc": null, "ownership_type": null, "personal_address": { "line1": null, "line2": null, "city": null, "region": null, "postal_code": null, "country": null }, "phone": null, "principal_percentage_ownership": null, "short_business_name": null, "tax_authority": null, "tax_id_fingerprint": null, "tax_id_provided": false, "title": null, "url": null }, "identity_roles": [ "BUYER" ], "tags": {}, "type": "PERSONAL", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/ID8CKX7vwrDDrMNc7D1Cg8mb" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/ID8CKX7vwrDDrMNc7D1Cg8mb/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/ID8CKX7vwrDDrMNc7D1Cg8mb/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/ID8CKX7vwrDDrMNc7D1Cg8mb/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/ID8CKX7vwrDDrMNc7D1Cg8mb/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/ID8CKX7vwrDDrMNc7D1Cg8mb/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/ID8CKX7vwrDDrMNc7D1Cg8mb/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/ID8CKX7vwrDDrMNc7D1Cg8mb/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/ID8CKX7vwrDDrMNc7D1Cg8mb/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ``` Filled-out Buyer Identity Example Response: Filled-out Buyer Identity ```json Filled-out Buyer Identity { "id": "IDm1QmqySG8YQUth47dj2sV5", "created_at": "2026-09-25T20:05:10.29Z", "updated_at": "2026-09-25T20:05:10.29Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "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_fingerprint": null, "business_tax_id_provided": false, "business_type": null, "default_statement_descriptor": null, "discover_mid": null, "dob": null, "doing_business_as": null, "email": "johnsmithbuyer@gmail.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": "7147148784", "principal_percentage_ownership": null, "short_business_name": null, "tax_authority": null, "tax_id_fingerprint": null, "tax_id_provided": false, "title": null, "url": null }, "identity_roles": [ // [!code highlight] "BUYER" ], "tags": {}, "type": "PERSONAL", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ``` Some customers choose to update this `Identity` at a later time with a `PUT` request using the information from the `Payment Instrument` below. #### Create a Payment Instrument Create a `Payment Instrument` by making a `POST` request to `/payment_instruments` with the relevant token and the `Identity#id` created for the buyer. To learn the available fields, please see [create a `payment_instrument`](/api/payment-instruments/createpaymentinstrument). Card Payment Instrument To create a Card Payment Instrument: Example response after creating a card payment instrument: Payment Instrument - Token - Card ```json Payment Instrument - Token - Card { "id": "PImmCg3Po7oNi7jaZcXhfkEu", "created_at": "2022-10-10T05:32:17.78Z", "updated_at": "2022-10-10T05:32:17.78Z", "account_updater_enabled": false, "application": "APgPDQrLD52TYvqazjHJJchM", "created_via": "API", "currency": "USD", "enabled": true, "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY", "identity": "IDjvxGeXBLKH1V9YnWm1CS4n", "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": "520082", "brand": "MASTERCARD", "card_type": "DEBIT", "expiration_month": 12, "expiration_year": 2029, "issuer_country": "USA", "last_four": "8210", "name": "Amy White", "network_token_enabled": false, "network_token_state": "NOT_ENABLED", "security_code_verification": "UNKNOWN", "tags": { "card_name": "Business Card" }, "type": "PAYMENT_CARD", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDjvxGeXBLKH1V9YnWm1CS4n" }, "updates": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/updates" } } } ``` Bank Payment Instrument To create a Bank Payment Instrument: Example response after creating a bank account payment instrument: Payment Instrument - Token - Bank Account ```json Payment Instrument - Token - Bank Account { "id": "PIkfiTDWYhQ4VbtQkC1U1ceJ", "created_at": "2024-06-21T04:09:03.77Z", "updated_at": "2024-06-21T04:09:03.77Z", "application": "APgPDQrLD52TYvqazjHJJchM", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRxpMNPZbZqVQfcHzRUJnzkR", "identity": "IDjvxGeXBLKH1V9YnWm1CS4n", "instrument_type": "BANK_ACCOUNT", "account_type": "BUSINESS_CHECKING", "bank_account_validation_check": "NOT_ATTEMPTED", "bank_code": "122105278", "country": "USA", "institution_number": null, "masked_account_number": "XXXXXX0019", "name": "Smith & Associates Consulting", "transit_number": null, "tags": {}, "third_party": null, "third_party_token": null, "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDjvxGeXBLKH1V9YnWm1CS4n" } } } ``` #### Card type For cards, the type is saved in `card_type`. Available values for `Payment Instruments` with `type: PAYMENT_CARD` include: - `CREDIT` - `DEBIT` - `HSA_FSA` - `NON_RELOADABLE_PREPAID` - `RELOADABLE_PREPAID` - `UNKNOWN` #### Updating a Payment Instrument If you are interested in updating a `payment_instrument`, you can do so. This is helpful if you already have buyer address and don't want to collect it on the token_form. To learn the available fields to update, please see [update an `payment_instrument`](/api/payment-instruments/updatepaymentinstrument). ## Additional examples ### Minimal HTML/JavaScript example The example below shows a minimal implementation using `Finix.PaymentForm`: JavaScript ```javascript document.addEventListener("DOMContentLoaded", () => { Finix.PaymentForm("finix-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", { onSubmit(error, response) { if (error) { console.error(error); alert("Error creating token"); return; } const tokenId = response?.data?.id; alert("Your token ID is: " + tokenId); console.log("Token Response:", response); }, }); }); ``` HTML ```html Finix Form Minimal

Finix Payment Form Minimal

``` ### Custom submit button example If you prefer to use your own submit button instead of the auto-generated one, you can handle form submission manually: JavaScript ```javascript document.addEventListener("DOMContentLoaded", () => { const submitElement = document.getElementById("submit"); const form = Finix.PaymentForm( "finix-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", { onUpdate: function (state, binInformation, hasErrors) { submitElement.disabled = hasErrors; }, }, ); submitElement.addEventListener("click", function () { form.submit(function (error, response) { if (error) { console.error(error); alert("Error creating token"); return; } const tokenId = response?.data?.id; alert("Your token ID is: " + tokenId); console.log("Token Response:", response); }); }); }); ``` HTML ```html Finix Form Custom Button

Finix Payment Form - Custom Button

``` ### Finix sample store If you want to see our Tokenization Forms in action, visit our [sample store](https://finixsamplestore.com). You can view our [related GitHub project](https://github.com/finix-payments/accept-a-payment). ### React example The example below shows how to integrate `Finix.PaymentForm` with React: br JavaScript ```javascript import React, { useEffect } from "https://esm.sh/react@18.2.0"; import ReactDOM from "https://esm.sh/react-dom@18.2.0"; const FinixForm = () => { useEffect(() => { // Create finix.js V2 Payment Form const form = Finix.PaymentForm( "form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", { showAddress: true, // onSubmit callback automatically creates a submit button onSubmit: function (error, response) { if (error) { console.error("Tokenization error:", error); return; } // get token ID from response const tokenData = response.data || {}; const token = tokenData.id; alert("Your token ID is: " + token); }, }, ); }, []); return React.createElement("div", null, [ React.createElement("h2", { key: "header" }, "Finix Payment Form Demo"), React.createElement("div", { id: "form", key: "form" }), ]); }; ReactDOM.render(React.createElement(FinixForm), document.getElementById("app")); ``` HTML ```html Finix Payment Form - React
``` ### Complete HTML example Below is a complete example of all the available options for the `Finix.PaymentForm` function. br JavaScript (with comments) ```javascript document.addEventListener("DOMContentLoaded", () => { const options = { // ============================================================ // PAYMENT METHOD CONFIGURATION // ============================================================ // Specify which payment methods to allow // Options: ["card", "bank"], ["card"], or ["bank"] // Default: ["card", "bank"] // paymentMethods: ["card", "bank"], // ============================================================ // ADDRESS FIELDS // ============================================================ // Show address fields in the form // Default: false showAddress: true, // ============================================================ // LABELS // ============================================================ // Show labels above each input field // Default: true showLabels: true, // Custom labels for each field // Card fields: card_holder_name, number, expiration_date, security_code // Bank fields: account_holder_name, account_number, bank_code, account_type // Address fields: address_line1, address_line2, address_city, address_region, address_postal_code, address_country labels: { card_holder_name: "Full Name", // number: "Card Number", // expiration_date: "Expiration Date", // security_code: "CVV", // account_holder_name: "Account Holder Name", // account_number: "Account Number", // bank_code: "Routing Number", // account_type: "Account Type", // address_line1: "Street Address", // address_line2: "Apt, Suite, etc.", // address_city: "City", // address_region: "State/Region", // address_postal_code: "Postal Code", // address_country: "Country", }, // ============================================================ // PLACEHOLDERS // ============================================================ // Show placeholder text in input fields // Default: true showPlaceholders: true, // Custom placeholders for each field // Card fields: card_holder_name, number, expiration_date, security_code // Bank fields: account_holder_name, account_number, bank_code, account_type // Address fields: address_line1, address_line2, address_city, address_region, address_postal_code, address_country placeholders: { card_holder_name: "Full Name", // number: "4111 1111 1111 1111", // expiration_date: "MM/YY", // security_code: "123", // account_holder_name: "John Doe", // account_number: "000123456789", // bank_code: "110000000", // account_type: "Checking", // address_line1: "123 Main St", // address_line2: "Apt 4B", // address_city: "San Francisco", // address_region: "CA", // address_postal_code: "94102", // address_country: "USA", }, // ============================================================ // DEFAULT VALUES // ============================================================ // Pre-fill values for fields (cannot pre-fill card/bank numbers due to PCI compliance) // Supported: card_holder_name, account_holder_name, address_line1, address_line2, // address_city, address_region, address_postal_code, address_country defaultValues: { // card_holder_name: "John Doe", // account_holder_name: "John Doe", // address_line1: "123 Main St", // address_line2: "Apt 4B", // address_city: "San Francisco", // address_region: "CA", // address_postal_code: "94102", // address_country: "USA", }, // ============================================================ // HIDE FIELDS // ============================================================ // Hide specific fields that you do not need // Note: "number" and "expiration_date" cannot be hidden as they are required by networks // Supported: card_holder_name, security_code, account_holder_name, address_line1, // address_line2, address_city, address_region, address_postal_code, address_country hideFields: [ // "card_holder_name", // "security_code", // "account_holder_name", // "address_line1", // "address_line2", // "address_city", // "address_region", // "address_postal_code", // "address_country", ], // ============================================================ // REQUIRED FIELDS // ============================================================ // Require specific fields that are not required by default // Supported: card_holder_name, account_holder_name, address_line1, address_line2, // address_city, address_region, address_postal_code, address_country requiredFields: [ "card_holder_name", "address_line1", "address_city", "address_region", "address_country", "address_postal_code", ], // ============================================================ // SECURITY & VALIDATION OPTIONS // ============================================================ // Require security code (CVV/CVC) for card payments // Default: true // requireSecurityCode: true, // Show double confirmation input for bank account numbers // Validates both entries match to reduce incorrect account numbers // Default: true // confirmAccountNumber: true, // Hide warning messages for non-standard but valid card numbers // Default: true // hidePotentialIssueMessages: true, // ============================================================ // ERROR MESSAGES // ============================================================ // Hide input error messages entirely // Default: false hideErrorMessages: false, // Custom error messages for each field // Card fields: card_holder_name, number, expiration_date, security_code // Bank fields: account_holder_name, account_number, bank_code, account_type // Address fields: address_line1, address_line2, address_city, address_region, address_postal_code, address_country errorMessages: { card_holder_name: "Please enter a valid name", // number: "Please enter a valid card number", // expiration_date: "Please enter a valid expiration date", // security_code: "Please enter a valid security code", // account_holder_name: "Please enter the account holder name", // account_number: "Please enter a valid account number", // bank_code: "Please enter a valid routing number", // account_type: "Please select an account type", // address_line1: "Please enter a valid street address", // address_line2: "Please enter a valid address line 2", address_city: "Please enter a valid city", // address_region: "Please enter a valid state/region", // address_postal_code: "Please enter a valid postal code", // address_country: "Please enter a valid country", }, // ============================================================ // THEME & APPEARANCE // ============================================================ // Set the visual theme of the form // Options: finix, amethyst, sapphire, topaz, ruby, emerald, midnight, elevated // Default: "finix" // theme: "finix", // Enable dark mode styling for the payment form // Default: false // enableDarkMode: false, // ============================================================ // PLAID SETTINGS (for bank account linking) // ============================================================ // Configure Plaid bank account settings // plaidLinkSettings: { // displayName: "Your Merchant Name", // Name shown at top of Plaid modal // language: "en", // Language for Plaid experience (default: "en") // countries: ["USA", "CAN"], // ISO-3 country codes (default: ["USA", "CAN"]) // }, // ============================================================ // CUSTOM STYLES // ============================================================ // Custom styles for the form inputs. // Organized by theme (default/dark), then target element, then state. // Available targets: form, input, sectionHeader, section, submitButton styles: { // Base (light) theme default: { input: { // Default input state default: { color: "#000", border: "1px solid #CCCDCF", borderRadius: "8px", padding: "8px 16px", fontFamily: "Noto Sans Thaana", fontSize: "16px", boxShadow: "0px 1px 1px rgba(0, 0, 0, 0.03), 0px 2px 4px rgba(0, 0, 0, 0.03)", }, // Styling when the field is valid success: { // border: "1px solid #5cb85c", }, // Styling when the field has errors error: { // color: "#d9534f", border: "1px solid rgba(255,0,0,0.3)", }, // Styling when the field is focused focused: { // border: "1px solid #0070f3", }, }, submitButton: { default: {}, disabled: { // opacity: 0.5, }, }, }, // Optional dark mode overrides (applied on top of default when dark mode is active) // dark: {}, }, // ============================================================ // CUSTOM FONTS // ============================================================ // Custom fonts for input text (requires HTTPS hosted font file) // To use custom fonts, set the fontFamily in the styles.default above fonts: [ { fontFamily: "Noto Sans Thaana", url: "https://fonts.cdnfonts.com/s/107457/NotoSansThaana[wght].woff", format: "woff", }, ], // ============================================================ // SUBMIT BUTTON // ============================================================ // Label for the auto-generated submit button submitLabel: "Create Token", // ============================================================ // CALLBACK FUNCTIONS // ============================================================ // Callback function that triggers after the form has loaded onLoad: function () { console.log("Payment form loaded"); }, // Callback function that triggers when form state changes // Parameters: // state: Object with form metadata (valid, dirty, pristine - no PI data exposed) // binInformation: Object with BIN data (BIN number, card brand) // hasErrors: Boolean indicating if form has errors (useful for custom submit buttons) onUpdate: function (state, binInformation, hasErrors) { // console.log("Form state:", state); // console.log("BIN info:", binInformation); // console.log("Has errors:", hasErrors); }, // Callback function for form submission // Adding this option automatically creates a submit button // Parameters: // error: Error object if submission failed, null otherwise // response: Response object containing token data onSubmit: function (error, response) { if (error) { console.error(error); alert("Error creating token"); return; } const tokenId = response?.data?.id; alert("Your token ID is: " + tokenId); console.log("Token Response:", response); }, }; // ============================================================ // INITIALIZE THE PAYMENT FORM // ============================================================ // Create finix.js V2 Payment Form // Parameters: // element: The ID of the HTML element where the form will render // environment: "sandbox" or "live" // applicationId: Your Finix application ID // options: Configuration options object Finix.PaymentForm( "form-element", "sandbox", "APgPDQrLD52TYvqazjHJJchM", options, ); }); ``` JavaScript (without comments) ```javascript document.addEventListener("DOMContentLoaded", () => { const options = { showAddress: true, showLabels: true, showPlaceholders: true, labels: { card_holder_name: "Full Name", }, placeholders: { card_holder_name: "Full Name", }, requiredFields: [ "card_holder_name", "address_line1", "address_city", "address_region", "address_country", "address_postal_code", ], hideErrorMessages: false, errorMessages: { card_holder_name: "Please enter a valid name", address_city: "Please enter a valid city", }, styles: { default: { input: { default: { color: "#000", border: "1px solid #CCCDCF", borderRadius: "8px", padding: "8px 16px", fontFamily: "Noto Sans Thaana", fontSize: "16px", boxShadow: "0px 1px 1px rgba(0, 0, 0, 0.03), 0px 2px 4px rgba(0, 0, 0, 0.03)", }, error: { border: "1px solid rgba(255,0,0,0.3)", }, }, }, }, fonts: [ { fontFamily: "Noto Sans Thaana", url: "https://fonts.cdnfonts.com/s/107457/NotoSansThaana[wght].woff", format: "woff", }, ], submitLabel: "Create Token", onSubmit(error, response) { if (error) { console.error(error); alert("Error creating token"); return; } const tokenId = response?.data?.id; alert("Your token ID is: " + tokenId); console.log("Token Response:", response); }, }; // Initialize the Finix Payment Form Finix.PaymentForm( "form-element", "sandbox", "APgPDQrLD52TYvqazjHJJchM", options, ); }); ``` HTML ```html Finix PaymentForm Demo

Finix Payment Form Demo

``` ## Migrating from V1 to V2 For customers that are on our earlier Finix.js v1 library, see the [Finix.js v1 to v2 migration guide](/guides/online-payments/payment-tokenization/finix-js-migration-guide-v1-to-v2). Making a Payment Learn how to create a transfer and debit funds. Creating and Capturing an Authorization Learn how authorize funds on a card. --- # Afterpay with Low-Code / No-Code Source: https://docs.finix.com/guides/online-payments/buy-now-pay-later/afterpay/after-pay-low-code Afterpay login and authorization popup Finix's low-code products handle the heavy lifting of the Afterpay integration for you. Afterpay is supported across the following Finix low-code products: | Product | Afterpay Support | Notes | | --- | --- | --- | | **Payment Links** | Supported | Available via Dashboard. | | **Subscriptions** | Not Supported | Afterpay is not available for recurring payments. | | **Subscription Links** | Not Supported | Afterpay is not available for Subscription Links. | Afterpay is in Early Access Afterpay is currently in Early Access. To enable it on your Finix Application, reach out to your Finix point of contact or email [support@finix.com](mailto:support@finix.com). ## How it works When a buyer opens a Payment Link that has Afterpay enabled, they'll see Afterpay as a checkout option. The buyer selects Afterpay and is guided through the Afterpay authorization flow where they confirm their installment plan. Finix handles creating the payment instrument and processing the transaction automatically. ## What the Buyer sees When a buyer opens a Payment Link with Afterpay enabled, they'll see an **Afterpay** button alongside any other enabled payment methods. Payment Links - Buyer Page - After Pay Option ### Afterpay Authorization After selecting Afterpay, the buyer is prompted to log in to their Afterpay account in a popup modal, where they review their installment plan and confirm the payment. This flow is the same on desktop and mobile. Afterpay login and authorization popup ### Completing transaction Once the buyer completes authorization, Finix automatically creates the payment instrument and processes the transaction. No additional steps are needed on your end. ## Enabling Afterpay for your Application Before you can use Afterpay in any low-code product, it must be enabled on your Finix Application. ## Enabling Afterpay on low-code / no-code ### Payment Link 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login). 2. Navigate to **Payment Tools** → **Payment Links**. 3. Click **Create Payment Link** or select an existing link to edit. 4. Under **Allowed Payment Methods**, enable **Afterpay**. 5. Complete the remaining fields and save. Payment Links Creation Form - Payment Options - After Pay --- # Afterpay Source: https://docs.finix.com/guides/online-payments/buy-now-pay-later/afterpay Afterpay You can easily enable Afterpay through [Finix's low-code products](/guides/online-payments/buy-now-pay-later/afterpay/after-pay-low-code). Afterpay lets your buyers split their purchase into four equal, interest-free installments paid every two weeks—known as **Pay-in-4**—giving them a flexible way to pay without entering card details upfront. Afterpay is available for US-based merchants. Transactions must be in USD. Afterpay supports transactions between **$1.00 and $2,000.00 USD**. Afterpay is in Early Access Afterpay is currently in Early Access. To enable it on your Finix Application, reach out to your Finix point of contact or email [support@finix.com](mailto:support@finix.com). ## How Afterpay works When a buyer selects Afterpay at checkout, Finix handles the authorization and processing flow automatically: | Step | Action | Details | | --- | --- | --- | | 1 | **Buyer opens checkout** | The buyer navigates to a Payment Link or Checkout Page with Afterpay enabled. Afterpay appears alongside any other enabled payment methods. | | 2 | **Buyer selects Afterpay** | The buyer taps the **Afterpay** button to begin the authorization flow. | | 3 | **Afterpay authorization** | A popup modal opens. The buyer logs into their Afterpay account, reviews their installment schedule, and confirms the payment. | | 4 | **Finix processes the transaction** | Once the buyer confirms, Finix automatically creates the payment instrument and processes the transaction. No additional steps are needed on your end. | ## Pay-in-4 installments Afterpay splits the purchase total into four equal, interest-free payments—one charged at checkout, then one every two weeks. For example, a $200.00 purchase becomes four payments of $50.00 each. Afterpay determines the buyer's eligibility and presents the schedule before the buyer confirms. ## Why offer Afterpay ### Increase average order value Afterpay's installment plans encourage buyers to make larger purchases by spreading payments over time. Merchants typically see higher average order values when offering Buy Now, Pay Later options at checkout. ### Reduce cart abandonment By offering a flexible payment option at checkout, buyers are less likely to abandon their cart due to price concerns. Afterpay removes the friction of paying the full amount upfront, helping more buyers complete their purchase. ### One-Time Payments Afterpay payment instruments are designed for one-time use. Each checkout session creates a short-lived token that is consumed after the transaction is processed. This is ideal for single purchases where the buyer selects Afterpay at checkout. Afterpay instruments are one-time use Unlike Cash App Pay which supports saved payment methods for recurring use, Afterpay instruments are tied to a specific checkout session and are automatically disabled after use or when the token expires (~60 minutes). Higher decline rates Afterpay has higher decline rates than traditional card payments. Finix recommends offering Afterpay alongside other payment methods—such as card or bank account payments—so buyers have an alternative if Afterpay is unavailable for their transaction. ## Afterpay eligibility Afterpay is not available for all business types. Review Afterpay's acceptable use policies to confirm your business is eligible before integrating. ## Shipping address and item information Finix does not send shipping address or item-level data to Afterpay. Collecting a shipping address in a Payment Link or Checkout Page does not affect Afterpay approval rates. ## Refunds and Disputes Refunds for Afterpay transactions are handled the same as all other Finix refunds. See [Refunds](/guides/after-the-payment/refunds) for more information. Disputes follow the standard Finix dispute process, which runs approximately 45 days. For fraud disputes, Block Inc bears the fraud liability. Finix receives a notification for fraud disputes but takes no action, and fraud disputes do not appear in the Finix UI. See [Disputes](/guides/after-the-payment/disputes) for more information. ## Learn more Afterpay with Low-Code Products Accept Afterpay using Payment Links -- no custom integration required. --- # Apple Pay on iOS Source: https://docs.finix.com/guides/online-payments/digital-wallets/apple-pay/apple-pay-on-ios Let buyers pay with Apple Pay in your iOS application, authorizing each payment with Touch ID or Face ID. ## Overview Adding Apple Pay to your iOS app has two parts. First, you register your app with Apple through the Finix Dashboard and create a payment processing certificate. Then, you add the Apple Pay button and PassKit payment request to your app and process the resulting token with the Finix API. After setup, buyers can complete checkout with Apple Pay and you process the payment like any other Finix transaction. Collect the billing address to avoid extra fees Finix recommends passing the address field shown in the steps below. If you do not pass the address, the card network charges additional dues and assessments per transaction. ## Prerequisites Before you start, familiarize yourself with the [Apple Pay requirements](/guides/online-payments/digital-wallets/apple-pay) for Finix, including the Finix API key, seller onboarding, and Apple Developer account steps. ## Integration steps ### Step 1: Register your app on the Finix Dashboard Before you can accept Apple Pay, verify and register your application with Apple. You complete this step in the Finix Dashboard. Finix Core customers If you are a Finix Core customer, you do not need to complete the onboarding and registration in the prerequisites. Instead, register directly on the Finix Application you want to enable for Apple Pay. Register at either the Application level or the Merchant level. Application level To register at the [Application level](/guides/online-payments/digital-wallets/apple-pay): 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login) and click **Developer**. 2. Click the **Alt Payment Methods** tab. 3. Click **Add iOS Application** and follow the on-screen instructions to [create a payment processing certificate](https://developer.apple.com/documentation/passkit/apple_pay/setting_up_apple_pay#3735192). Alt Payment Methods tab with the Add iOS Application option 1. Enter an iOS application name. Add iOS Application modal with an application name field 1. Download the Certificate Signing Request (CSR) file. Add iOS Application modal with the CSR file download Don't close the modal until you've uploaded the payment processing certificate Keep this modal open while you complete steps 6 through 9 on the Apple Developer Portal. 1. Go to your [Apple Developer Portal](https://idmsa.apple.com/IDMSWebAuth/signin?appIdKey=891bd3417a7776362562d2197f89480a8547b108fd934911bcbea0110d07f757&path=%2Faccount%2Fresources%2Fidentifiers%2Flist%2Fmerchant&rv=1). 2. Select the [Apple Merchant ID](https://developer.apple.com/help/account/capabilities/configure-apple-pay#create-a-merchant-identifier) you want to add this certificate to, then click **Create Certificate** in the **Apple Pay Payment Processing Certificate** section. 3. When prompted to upload a Certificate Signing Request, choose the CSR file you downloaded in step 5. 4. Click **Activate** to enable the certificate, then click **Download** to save it to your computer. 5. Click **Next** in the **Add iOS Application** modal. Add iOS Application modal ready for the payment processing certificate 1. Upload the payment processing certificate. Add iOS Application modal with the certificate uploaded Merchant level To register at the [Merchant level](/guides/online-payments/digital-wallets/apple-pay): 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login) and select the Merchant account. 2. Click **Data Resources**, then **Identities**. 3. Select a **Seller** Identity. 4. Click the **Alt Payment Methods** tab. 5. Click **Add iOS Application** and follow the on-screen instructions to [create a payment processing certificate](https://developer.apple.com/documentation/passkit/apple_pay/setting_up_apple_pay#3735192). Seller Identity Alt Payment Methods tab with the Add iOS Application option 1. Enter an iOS application name. Add iOS Application modal with an application name field 1. Download the Certificate Signing Request (CSR) file. Add iOS Application modal with the CSR file download Don't close the modal until you've uploaded the payment processing certificate Keep this modal open while you complete steps 8 through 11 on the Apple Developer Portal. 1. Go to your [Apple Developer Portal](https://idmsa.apple.com/IDMSWebAuth/signin?appIdKey=891bd3417a7776362562d2197f89480a8547b108fd934911bcbea0110d07f757&path=%2Faccount%2Fresources%2Fidentifiers%2Flist%2Fmerchant&rv=1). 2. Select the [Apple Merchant ID](https://developer.apple.com/help/account/capabilities/configure-apple-pay#create-a-merchant-identifier) you want to add this certificate to, then click **Create Certificate** in the **Apple Pay Payment Processing Certificate** section. 3. When prompted to upload a Certificate Signing Request, choose the CSR file you downloaded in step 7. 4. Click **Activate** to enable the certificate, then click **Download** to save it to your computer. 5. Click **Next** in the **Add iOS Application** modal. Add iOS Application modal ready for the payment processing certificate 1. Upload the payment processing certificate. Add iOS Application modal with the certificate uploaded ### Step 2: Add the Apple Pay button After your app is registered, it is authorized to accept Apple Pay payments. Add an [Apple Pay button](https://developer.apple.com/documentation/passkit/apple_pay/offering_apple_pay_in_your_app#:~:text=Add%20the%20Apple%20Pay%20Button) to your iOS app's checkout flow. ### Step 3: Make a payment request to Apple When the buyer taps the Apple Pay button, your iOS app creates a payment by calling the `startPayment` method of Apple's `PaymentHandler`. Include `requiredBillingContactFields` with `name` and `postalAddress` to collect billing information. For full implementation details, see [Apple's PassKit documentation](https://developer.apple.com/documentation/passkit/apple_pay/offering_apple_pay_in_your_app#:~:text=calling%20the%20startPayment). Collect the billing address If you do not collect the address, additional fees apply. When the buyer authorizes the payment, Apple's completion handler reports the success or failure of the payment. Successful payments return a payment token that you include in your request to Finix to create a Payment Instrument. ### Step 4: Use a Buyer Identity A Buyer Identity is required before you can process a payment. You can create a new Buyer Identity with the Finix API, or use an existing one. Buyer Identity data All Buyer Identity fields are optional. Finix recommends including basic information (name, email, address, and phone) to make payment operations easier. Use an existing Buyer To find and reuse an existing Buyer Identity: 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login). 2. In the left sidebar, select **Data Resources** → **Identities**. 3. Search for the Buyer Identity you want to use, and confirm its **Role** is **Buyer**. 4. Copy the Buyer Identity ID (for example, `IDjWktr7BPDGhz4amrPJZoXg`). Create a new Buyer Send a `POST` request to POST /identities with the `BUYER` role to create a new Buyer Identity. ```shell Buyer Identity Request curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/identities \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "entity": { "phone": "7145677613", "first_name": "John", "last_name": "Smith", "email": "finix_example@finix.com", "personal_address": { "city": "San Mateo", "country": "USA", "region": "CA", "line2": "Apartment 7", "line1": "741 Douglass St", "postal_code": "94114" } }, "identity_roles": [ "BUYER" ], "tags": { "key": "value" }, "type": "PERSONAL" }' ``` A successful request returns the Buyer Identity. Copy its `id` to use in the following steps. ```json 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": [ "BUYER" ], "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" } } } ``` ### Step 5: Create a Payment Instrument with Finix After the buyer pays with Apple, use the returned payment token to create a Payment Instrument with Finix. Your app [sends the payment token](https://developer.apple.com/documentation/passkit/apple_pay/offering_apple_pay_in_your_app#3846471) and [billing address](https://developer.apple.com/documentation/passkit/pkpayment) returned by Apple's completion handler to Finix as the `third_party_token`, `name`, and `address` fields when creating the Payment Instrument. Example API Definition A successful request returns the newly created Payment Instrument, which you use to process the payment. Example Payment Instrument - Apple Pay ```json Payment Instrument - Apple Pay { "id": "PIpc4vhEkanrNcPihgqMzXw5", "created_at": "2026-09-25T20:05:24.67Z", "updated_at": "2026-09-25T20:05:24.67Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPR88YBDbK4TqYMUNU8t8fbeQ", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "APPLE_PAY", // [!code highlight] "address": { "line1": "900 Metro Center Blv", "line2": "APT 200", "city": "San Francisco", "region": "CA", "postal_code": "94404", "country": "USA" }, "bin": "370382", "brand": "AMERICAN_EXPRESS", "card_type": "CREDIT", "expiration_month": 11, "expiration_year": 2024, "issuer_country": "USA", "last_four": "8576", "name": "John Doe", "tags": {}, "third_party": null, "third_party_token": null, "type": "APPLE_PAY", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIpc4vhEkanrNcPihgqMzXw5" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIpc4vhEkanrNcPihgqMzXw5/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIpc4vhEkanrNcPihgqMzXw5/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIpc4vhEkanrNcPihgqMzXw5/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` API Definition ### Step 6: Create a payment After the Payment Instrument is created, use it to create a Transfer or an Authorization, the same as any other Finix transaction. To process a sale: 1. Set the `source` to the buyer's Payment Instrument ID. 2. Set the `merchant` to an `APPROVED` Merchant account. 3. Set the `amount` in cents. ```shell Example 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": "PIwpqpJZCharsZAt6WKVopPS" }' ``` ```json Example Transfer Response { "id": "TR29av3LN1TAGPbXscsup1tt", "amount": 662154, "tags": {}, "state": "SUCCEEDED", "trace_id": "34f40e87-2599-414b-874b-f472790ff521", "currency": "USD", "application": "APgPDQrLD52TYvqazjHJJchM", "source": "PIwpqpJZCharsZAt6WKVopPS", "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": "IDpYDM7J9n57q849o9E9yNrG", "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/IDpYDM7J9n57q849o9E9yNrG" }, "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/PIwpqpJZCharsZAt6WKVopPS" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8" } } } ``` Alternatively, create an Authorization and capture it later with two separate API calls. This is useful when you need to verify the payment details first and capture a specific amount later. For more information, see [Creating and capturing an Authorization](/guides/online-payments/payment-features/auth-and-captures). ## Next steps Refunds Refund all or part of an Apple Pay payment. Disputes Respond to buyer disputes on Apple Pay transactions. Apple Pay on web Accept Apple Pay on your website using Finix. --- # Apple Pay on Web Source: https://docs.finix.com/guides/online-payments/digital-wallets/apple-pay/apple-pay-on-web Let buyers who use Safari pay with Apple Pay on your website, authorizing each payment with Touch ID or Face ID. ## Overview Adding Apple Pay to your website has two parts. First, you register and verify your domain with Apple through the Finix Dashboard. Then, you add the Apple Pay button and session logic to your site and process the resulting token with the Finix API. After setup, buyers on Safari can complete checkout with Apple Pay and you process the payment like any other Finix transaction. Collect the billing address to avoid extra fees Finix recommends passing the address field shown in the steps below. If you do not pass the address, the card network charges additional dues and assessments per transaction. ## Prerequisites Before you start, familiarize yourself with the [Apple Pay requirements](/guides/online-payments/digital-wallets/apple-pay) for Finix, including the Finix API key, seller onboarding, and Apple Developer account steps. ## Apple Pay demo See a live demo of Apple Pay on the [Finix sample store](https://finixsamplestore.com). All of the sample store code is available in the [accept-a-payment GitHub project](https://github.com/finix-payments/accept-a-payment). Log in to the Apple Developer site The Apple Pay button does not render in the Finix sample store unless you are logged in on the Apple Developer site. In the sample store, add a few items to your cart and click **Pay with Tokenization Form**. Sample store checkout with a tokenization form and express checkout option An express checkout button brings up the Apple Pay button. The sample store uses Sandbox credentials, so you are not charged. Express checkout with the Apple Pay button ## Integration steps ### Step 1: Register your domain on the Finix Dashboard Before you can accept Apple Pay, verify and register your domain with Apple. You complete this step in the Finix Dashboard. After you register the domain, download the verification file and host it on your website. Register at either the Application level or the Merchant level. Application level To register at the [Application level](/guides/online-payments/digital-wallets/apple-pay): 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login) and click **Developer**. 2. Click the **Alt Payment Methods** tab. 3. Click **Add Web Domain** and follow the instructions to host the verification file. Alt Payment Methods tab with the Add Web Domain option Don't close the modal until you've hosted the verification file Do not click **Submit** on step 3 in the modal until you've uploaded the verification file that Finix generates in the steps below. 1. Enter a domain name. Add Web Domain modal with a domain name field 1. Download the verification file. Add Web Domain modal with the verification file download 1. Host the verification file at `/.well-known/apple-developer-merchantid-domain-association`. Verification file hosted at the well-known path Merchant level To register at the [Merchant level](/guides/online-payments/digital-wallets/apple-pay): 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login) and select the Merchant account. 2. Click **Customers**, then **Identities**. 3. Select a **Seller** Identity. 4. Click the **Alt Payment Methods** tab. 5. Click **Add Web Domain** and follow the instructions to host the verification file. Seller Identity Alt Payment Methods tab with the Add Web Domain option Don't close the modal until you've hosted the verification file Do not click **Submit** on step 3 in the modal until you've uploaded the verification file that Finix generates in the steps below. 1. Enter a domain name. Add Web Domain modal with a domain name field 1. Download the verification file. Add Web Domain modal with the verification file download 1. Host the verification file at `/.well-known/apple-developer-merchantid-domain-association`. Verification file hosted at the well-known path ### Step 2: Add the Apple Pay library After you verify and register your domain with Apple, add the Apple Pay library. This script lets your site call the Apple Pay API. ```html Apple Pay Library Snippet ``` ### Step 3: Add the Apple Pay button After you add the Apple Pay library, add an HTML element named `apple-pay-button`. Apple requires the button to be named `apple-pay-button`. The button element supports the following attributes. | Field | Type | Description | | --- | --- | --- | | `buttonstyle` | *string*, **optional** | Color of the button. Available values are `black`, `white`, and `white-outline`. | | `type` | *string*, **required** | The button type that initiates the transaction. For the full list of [available button types](https://developer.apple.com/documentation/applepayontheweb/applepaybuttontype), pass one of `Buy` (default), `Plain`, `Add Money`, `Book`, `Checkout`, `Continue`, `Contribute`, `Donate`, `Order`, `Pay`, `Reload`, `Rent`, `Set Up`, `Subscribe`, `Support`, `Tip`, or `Top Up`. | | `locale` | *string*, **required** | The language of the button. | To preview every Apple Pay button style, see [Apple Pay's interactive demo](https://applepaydemo.apple.com/). ```html Apple Pay Button ``` ### Step 4: Create and begin the Apple Pay session After you add the Apple Pay button, create an `ApplePaySession` by passing a version number and an `ApplePayPaymentRequest` object to the constructor. To collect a billing address, include `requiredBillingContactFields` in the request. Then call `begin()` on the session to start the payment flow. The `ApplePayPaymentRequest` object accepts the following fields. | Field | Type | Description | | --- | --- | --- | | `countryCode` | *string*, **required** | The ISO country code. | | `currencyCode` | *string*, **required** | The currency code of the locale. | | `merchantCapabilities` | *array*, **required** | The payment types, such as credit or debit, that the merchant supports. The value `supports3DS` is required. | | `supportedNetworks` | *array*, **optional** | The payment networks the merchant supports. Included networks are `amex`, `discover`, `jcb`, `masterCard`, and `visa`. | | `total` | *object*, **required** | The `label` field is a short, localized description of the line item. The `amount` field is the monetary amount of the line item in the format `0.00`. | | `requiredBillingContactFields` | *array*, **optional** | Pass `postalAddress` to obtain a postal address and the buyer's name after the buyer authorizes the transaction. If you do not retrieve the address to pass to Finix, additional fees apply. | ```javascript Apple Pay Session var createAndStartApplePaySession = function (description, amount) { var applePaySession = new ApplePaySession(6, { countryCode: "US", currencyCode: "USD", merchantCapabilities: ["supports3DS"], supportedNetworks: ["visa", "masterCard", "amex", "discover"], total: { label: description, amount: amount }, requiredBillingContactFields: ["postalAddress"], }); applePaySession.begin(); }; ``` ### Step 5: Use a Buyer Identity A Buyer Identity is required before you can process a payment. You can create a new Buyer Identity with the Finix API, or use an existing one. Buyer Identity data All Buyer Identity fields are optional. Finix recommends including basic information (name, email, address, and phone) to make payment operations easier. Use an existing Buyer To find and reuse an existing Buyer Identity: 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login). 2. In the left sidebar, select **Data Resources** → **Identities**. 3. Search for the Buyer Identity you want to use, and confirm its **Role** is **Buyer**. 4. Copy the Buyer Identity ID (for example, `IDjWktr7BPDGhz4amrPJZoXg`). Create a new Buyer Send a `POST` request to POST /identities with the `BUYER` role to create a new Buyer Identity. ```shell Buyer Identity Request curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/identities \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "entity": { "phone": "7145677613", "first_name": "John", "last_name": "Smith", "email": "finix_example@finix.com", "personal_address": { "city": "San Mateo", "country": "USA", "region": "CA", "line2": "Apartment 7", "line1": "741 Douglass St", "postal_code": "94114" } }, "identity_roles": [ "BUYER" ], "tags": { "key": "value" }, "type": "PERSONAL" }' ``` A successful request returns the Buyer Identity. Copy its `id` to use in the following steps. ```json 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": [ "BUYER" ], "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" } } } ``` ### Step 6: Validate the Apple Pay merchant session After you start an Apple Pay session, validate and complete an Apple Pay merchant session with POST /apple_pay_sessions. Your server securely exchanges certificates with Apple's servers and Finix to complete the setup. To validate the session, set up the `onvalidatemerchant` function to capture the validation URL and send it, along with the merchant details, to your backend. Your server processes the request with Finix and returns Apple's validation response. Then, call `completeMerchantValidation()` with the response to authorize the session. ```javascript Validate Merchant Session var validateMerchantSession = function (applePaySession) { applePaySession.onvalidatemerchant = function (event) { try { var validationURL = event.validationURL; console.log("Validating merchant with url: " + validationURL); if (validationURL) { var request = { provider: "APPLE_PAY", validation_url: validationURL, merchant_identity: merchantIdentity, domain: "www.finixtestmerchant.com", display_name: "Finix Test Merchant", }; // call your server, which then calls Finix's /apple_pay_sessions fetch(serverUrl, { method: "POST", headers, body: JSON.stringify(request), }) .then((response) => response.json()) .then((data) => { // the session details return as a string; parse them into an object var merchantSession = JSON.parse(data["session_details"]); applePaySession.completeMerchantValidation(merchantSession); }); } else { console.log("Merchant validation failed"); } } catch (err) { console.log(err); throw err; } }; }; ``` Next, pass the `validation_url` into a `POST` request to `apple_pay_sessions`. Finix returns a `merchantSession` object that you use in the next step. The request accepts the following arguments. | Field | Type | Description | | --- | --- | --- | | `display_name` | *string*, **required** | The merchant name shown to buyers when they pay with Apple Pay and Touch ID. | | `domain` | *string*, **required** | The domain where the buyer initiates the payment. | | `merchant_identity` | *string*, **required** | The merchant identity ID used when registering the business with Apple Pay through the registration API. To find it, log in to your Finix Dashboard and go to **Developer** → **Finix Integration** → **Merchant Identity ID** (for example, `IDmULj61C8ke6Y7qQiKENJ7`). | | `validation_url` | *string*, **required** | A validation URL that the Apple SDK front end provides for every payment. | ```shell Apple Pay Session Request curl https://finix.sandbox-payments-api.com/apple_pay_sessions \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \ -d '{ "display_name": "Finix Test Merchant", "domain": "www.finixtestmerchant.com", "merchant_identity": "IDmULj61C8ke6Y7qQiKENJ7", "validation_url": "https://apple-pay-gateway-cert.apple.com/paymentservices/paymentSession" }' ``` ```json Apple Pay Session Response { "id": "APPLEPAYSESSION_xxx", "created_at": "2021-11-22T23:58:19.50Z", "updated_at": "2021-11-22T23:58:19.50Z", "session_details": "{\"epochTimestamp\":1640213041060,\"expiresAt\":1640216641060,\"merchantSessionIdentifier\":\"SSH1524BA9006A944B8B9B8FB60227D9990_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24\",\"nonce\":\"a5ee8554\",\"merchantIdentifier\":\"23D5E1F154400B277E14CC8361878AA0AAFD46B2DF74003C7587B256269102BD\",\"domainName\":\"tj.ngrok.io\",\"displayName\":\"Christmas Shopping\",\"signature\":\"...\",\"operationalAnalyticsIdentifier\":\"Christmas Shopping:23D5E1F154400B277E14CC8361878AA0AAFD46B2DF74003C7587B256269102BD\",\"retries\":0}", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/apple_pay_sessions/APPLEPAYSESSION_xxx" } } } ``` ### Step 7: Create a Payment Instrument After the merchant session validates, Apple Pay prompts the buyer to authenticate with Touch ID, Face ID, or a device passcode. When the buyer authorizes the payment, the `onpaymentauthorized` function provides an encrypted token. Your site sends this token to your backend for processing with Finix. Your backend returns the result, which you use to call `completePayment()` and finalize the Apple Pay session. ```javascript Create Payment Token var processPayment = function (applePaySession) { applePaySession.onpaymentauthorized = function (event) { try { //token received from Apple var paymentToken = event.payment; if (paymentToken) { console.log("Payment token from Apple: " + paymentToken); // extract billing details var addressData = { country: paymentToken.billingContact.countryCode, postal_code: paymentToken.billingContact.postalCode, }; var name = paymentToken.billingContact.givenName + " " + paymentToken.billingContact.familyName; // send Finix API stringified form of the isolated token var third_party_token = { token: paymentToken.token, }; var stringifiedPaymentToken = JSON.stringify(third_party_token); // call the server to handle the orchestration of Finix calls processPaymentFromServer(stringifiedPaymentToken, addressData, name); applePaySession.completePayment(applePaySession.STATUS_SUCCESS); console.log( "Finix processed transaction successfully with token: " + paymentToken, ); } else { console.log( "Payment token from Apple is null - payment failed to process.", ); applePaySession.completePayment(applePaySession.STATUS_FAILURE); } } catch (err) { console.log(err); throw err; } }; }; ``` Then, your server passes the payment token as `third_party_token`, the address data as `address`, and the value for `name` when creating a Payment Instrument. Example API Definition A successful request returns the newly created Payment Instrument, which you use to process the payment. Example Payment Instrument - Apple Pay ```json Payment Instrument - Apple Pay { "id": "PIpc4vhEkanrNcPihgqMzXw5", "created_at": "2026-09-25T20:05:24.67Z", "updated_at": "2026-09-25T20:05:24.67Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPR88YBDbK4TqYMUNU8t8fbeQ", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "APPLE_PAY", // [!code highlight] "address": { "line1": "900 Metro Center Blv", "line2": "APT 200", "city": "San Francisco", "region": "CA", "postal_code": "94404", "country": "USA" }, "bin": "370382", "brand": "AMERICAN_EXPRESS", "card_type": "CREDIT", "expiration_month": 11, "expiration_year": 2024, "issuer_country": "USA", "last_four": "8576", "name": "John Doe", "tags": {}, "third_party": null, "third_party_token": null, "type": "APPLE_PAY", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIpc4vhEkanrNcPihgqMzXw5" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIpc4vhEkanrNcPihgqMzXw5/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIpc4vhEkanrNcPihgqMzXw5/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIpc4vhEkanrNcPihgqMzXw5/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` API Definition ### Step 8: Create a payment After the Payment Instrument is created, use it to create a Transfer or an Authorization, the same as any other Finix transaction. To process a sale: 1. Set the `source` to the buyer's Payment Instrument ID. 2. Set the `merchant` to an `APPROVED` Merchant account. 3. Set the `amount` in cents. ```shell Example 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": "PIwpqpJZCharsZAt6WKVopPS" }' ``` ```json Example Transfer Response { "id": "TR29av3LN1TAGPbXscsup1tt", "amount": 662154, "tags": {}, "state": "SUCCEEDED", "trace_id": "34f40e87-2599-414b-874b-f472790ff521", "currency": "USD", "application": "APgPDQrLD52TYvqazjHJJchM", "source": "PIwpqpJZCharsZAt6WKVopPS", "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": "IDpYDM7J9n57q849o9E9yNrG", "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/IDpYDM7J9n57q849o9E9yNrG" }, "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/PIwpqpJZCharsZAt6WKVopPS" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8" } } } ``` Alternatively, create an Authorization and capture it later with two separate API calls. This is useful when you need to verify the payment details first and capture a specific amount later. For more information, see [Creating and capturing an Authorization](/guides/online-payments/payment-features/auth-and-captures). ## Next steps Refunds Refund all or part of an Apple Pay payment. Disputes Respond to buyer disputes on Apple Pay transactions. Apple Pay on iOS Accept Apple Pay in your iOS application using Finix. --- # Apple Pay Passthrough Source: https://docs.finix.com/guides/online-payments/digital-wallets/apple-pay/apple-pay-passthrough If you decrypt Apple Pay tokens outside of Finix, use the passthrough path to send the wallet authentication fields including the Electronic Commerce Indicator (ECI) directly to Finix. The ECI is a one-or-two-digit value that card networks and issuers factor into liability and risk decisions on the authorization. PCI Level 1 Required The passthrough path transmits raw PAN (DPAN) data. Only customers that are PCI Level 1 compliant are permitted to use it. Sending `number` without PCI Level 1 approval returns a `422` error. ## How it works There are two ways to submit Apple Pay or Google Pay data to `POST /payment_instruments`: | Path | How it works | | --- | --- | | **Encrypted token** (default) | Send the encrypted `third_party_token`. Finix decrypts it and extracts all fields, including ECI. | | **Passthrough** | Decrypt the token yourself and send the individual fields (`number`, `cryptogram`, `expiration_month`, `expiration_year`, `electronic_commerce_indicator_code`) directly. | You cannot send both `number` and `third_party_token` in the same request. Doing so returns a `422` error. ## Passthrough fields | Field | Type | Required | Description | | --- | --- | --- | --- | | `number` | *string* | **Yes** | Network token PAN (DPAN) from the decrypted token. For Google Pay, this may be a raw PAN. | | `cryptogram` | *string* | **Yes** | Wallet-generated cryptogram from the decrypted token. Required for Apple Pay. Optional for Google Pay — PAN_ONLY tokens do not produce a cryptogram. | | `expiration_month` | *integer* | No | Card expiration month (1–12). | | `expiration_year` | *integer* | No | Card expiration year (4-digit). | | `electronic_commerce_indicator_code` | *string* | No | One-or-two-digit value indicating the authentication method. The card network and issuer factor this into liability and risk decisions on the authorization. | ## Create a Payment Instrument (passthrough) When your server receives the decrypted fields from the Apple Pay token, pass them directly in the `POST /payment_instruments` request body instead of `third_party_token`. Example API Definition Example Payment Instrument - Apple Pay - Passthrough ```json Payment Instrument - Apple Pay - Passthrough { "id": "PIwgh7555RYfKoLPCeu5G1HL", "created_at": "2026-09-25T20:05:25.04Z", "updated_at": "2026-09-25T20:05:25.04Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "APPLE_PAY", // [!code highlight] "address": { "line1": "900 Metro Center Blv", "line2": "APT 200", "city": "San Francisco", "region": "CA", "postal_code": "94404", "country": "USA" }, "bin": "520082", "brand": "MASTERCARD", "card_type": "DEBIT", "expiration_month": 11, "expiration_year": 2026, "issuer_country": "NON_USA", "last_four": "8210", "name": "John Doe", "tags": {}, "third_party": null, "third_party_token": null, "type": "APPLE_PAY", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwgh7555RYfKoLPCeu5G1HL" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwgh7555RYfKoLPCeu5G1HL/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwgh7555RYfKoLPCeu5G1HL/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwgh7555RYfKoLPCeu5G1HL/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` API Definition The response shape is identical to the standard Apple Pay path. The `electronic_commerce_indicator_code` value is not echoed back in the response. ## Error responses | Scenario | Status | Error code | Message | | --- | --- | --- | --- | | `number` and `third_party_token` both sent | 422 | `INVALID_FIELD` | `Only one of number or third_party_token is allowed in a request.` | | `number` sent without `cryptogram` | 422 | `INVALID_FIELD` | `cryptogram field is required.` | | Neither `number` nor `third_party_token` sent | 422 | `INVALID_FIELD` | `Either number or third_party_token must be provided` | | `electronic_commerce_indicator_code` is not 1 or 2 numeric digits | 422 | `INVALID_FIELD` | `electronic_commerce_indicator_code must be 1 or 2 numeric digits` | | Customer is not PCI Level 1 compliant | 422 | `UNPROCESSABLE_ENTITY` | `Unless you are PCI Level 1 compliant, you must send the encrypted APPLE_PAY token in the third_party_token field.` | --- # Apple Pay Source: https://docs.finix.com/guides/online-payments/digital-wallets/apple-pay Apple Pay *Images courtesy of [Apple Developers](https://developer.apple.com/apple-pay/)* Add Apple Pay to your [website](/guides/online-payments/digital-wallets/apple-pay/apple-pay-on-web) or [iOS application](/guides/online-payments/digital-wallets/apple-pay/apple-pay-on-ios) with the Finix API, so buyers can authorize payments with Touch ID or Face ID instead of entering card details. ## Why offer Apple Pay - **Streamlined checkout:** Set Apple Pay as the default, prominent payment method to reduce cart abandonment and increase conversion. - **Enhanced security:** Every transaction on the buyer's iPhone or iPad requires Face ID, Touch ID, or a passcode, which can be more secure than accepting card details directly. ## Requirements Before you integrate Apple Pay, complete the following Finix and Apple requirements. ### Finix requirements 1. Create a [Finix API key](/additional-resources/developers/authentication-and-api-basics/api-keys). 2. Complete the [seller onboarding](/guides/platform-payments/onboarding-sellers) process. After approval, the seller has an [approved Merchant](/guides/platform-payments/onboarding-sellers/seller-onboarding-process). ### Apple requirements 1. Review Apple Pay's [Acceptable Use Policy](https://developer.apple.com/apple-pay/acceptable-use-guidelines-for-websites/). 2. Serve your website over HTTPS with a valid SSL certificate and TLS support. To confirm your server meets the requirements, see the [Apple Pay server guidelines](https://developer.apple.com/documentation/apple_pay_on_the_web/setting_up_your_server). 3. Create an [Apple Developer Sandbox account](https://developer.apple.com/help/app-store-connect/test-in-app-purchases/create-a-sandbox-apple-account/). 4. Log in to this developer account through iCloud on your Mac. 5. Use Apple Pay test card numbers from the [Apple Developer website](https://idmsa.apple.com/IDMSWebAuth/signin?appIdKey=891bd3417a7776362562d2197f89480a8547b108fd934911bcbea0110d07f757&path=%2Faccount%2F&rv=1). ## Choose a Merchant identifier value The `merchantIdentifier` value corresponds to a merchant identity beginning with a prefix `IDxxx`. There are two options for which value to pass in. ### Application owner Identity ID (default) If the Apple Pay button is hosted on your domain, use your application Identity ID. This flow is common when a single website hosts all of your checkout flows. This is the default option for Direct Merchants and most Platforms. You can find the application owner Identity ID from the [`merchant.identity`](/api/merchants/getmerchant#merchants/getmerchant/t=response&c=200&path=identity) field on the Merchant you use to process payments. ### Merchant owner Identity ID If you are a Platform that hosts websites on custom URLs, provide the owner Identity of your merchants. For example, a Platform that creates a website for each of its sellers on a custom URL uses this value. Finix recommends reaching out to your Finix point of contact if your flow fits this criterion. ## Learn more Apple Pay on iOS Accept Apple Pay in your iOS application using Finix. Apple Pay on web Accept Apple Pay on your website using Finix. --- # Cash App Pay with Low-Code / No-Code Source: https://docs.finix.com/guides/online-payments/digital-wallets/cash-app-pay/cash-app-pay-low-code Payment Links Buyer Page - Cash App - Scan to Pay Cash-App Pay is available on Finix's no-code / low Code Products. Cash App Pay is supported across the following Finix no-code / low-code products: | Product | Cash App Pay Support | Notes | | --- | --- | --- | | **Payment Links** | Supported | Available via Dashboard and API. | | **Checkout Pages** | Supported | Available via API only. | | **Subscriptions** | Supported | Available via Dashboard and API. | | **Subscription Links** | Supported | Available via Dashboard and API. | Cash App Pay is in Early Access Cash App Pay is currently in Early Access. To enable it on your Finix Application, reach out to your Finix point of contact or email [support@finix.com](mailto:support@finix.com). ## How it works When a buyer opens a Payment Link, Checkout Page, or Subscription Link that has Cash App Pay enabled, they'll see Cash App Pay as a checkout option. The buyer selects Cash App Pay and is guided through the Cash App authorization flow. Finix handles creating the payment instrument and processing the transaction automatically. ## What the Buyer sees When a buyer opens a Payment Link, Checkout Page, or Subscription Link with Cash App Pay enabled, they'll see a **Cash App Pay** button alongside any other enabled payment methods. Payment Links - Buyer Page - Cash App Option ### Desktop view of Cash App The buyer scans a QR code with their Cash App to authorize the payment. Payment Links Buyer Page - Cash App - Scan to Pay ### Mobile view of Cash App Tapping Cash App Pay redirects the buyer to the Cash App to confirm the payment. After authorization, they're returned to your checkout. Mobile view of Cash App Pay approval ### Completing transaction Once the buyer completes authorization, Finix automatically creates the payment instrument and processes the transaction. No additional steps are needed on your end. When a Buyer approves the Cash App Pay transaction, the payment will be complete on any of Finix's low-code products. ## Enabling Cash App Pay for your Application Before you can use Cash App Pay in any low-code product, it must be enabled on your Finix Application. ## Enabling Cash App Pay on low-code / no-code You can enable Cash App Pay when creating or editing a Payment Link or Subscription Link in the Finix Dashboard. ### Payment Link 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login). 2. Navigate to **Payment Tools** → **Payment Links**. 3. Click **Create Payment Link** or select an existing link to edit. 4. Under **Allowed Payment Methods**, enable **Cash App Pay**. 5. Complete the remaining fields and save. Payment Links Creation Form - Payment Options - Cash App ### Subscription Link 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login). 2. Navigate to **Payment Tools** → **Subscriptions** → **Subscription Links**. 3. Click **Create Subscription Link**. 4. Under **Allowed Payment Methods**, enable **Cash App Pay**. 5. Complete the remaining fields and save. --- # Cash App Pay Source: https://docs.finix.com/guides/online-payments/digital-wallets/cash-app-pay Cash App Pay *Images courtesy of [Cash App](https://cash.app/)* You can easily enable Cash App Pay through [Finix's low-code products](/guides/online-payments/digital-wallets/cash-app-pay/cash-app-pay-low-code). Cash App Pay lets your buyers pay directly from their Cash App balance, linked debit card, or bank account—giving them a fast, familiar checkout experience without entering card details. Cash App Pay is available for US-based merchants processing USD transactions. Cash App Pay is in Early Access Cash App Pay is currently in Early Access. To enable it on your Finix Application, reach out to your Finix point of contact or email [support@finix.com](mailto:support@finix.com). ## How Cash App Pay works When a buyer selects Cash App Pay at checkout, the authorization flow differs depending on whether they're on a desktop or mobile device: ### Desktop | Step | Action | Details | | --- | --- | --- | | 1 | **Buyer opens checkout** | The buyer navigates to a Payment Link, Checkout Page, or Subscription Link with Cash App Pay enabled. | | 2 | **Buyer selects Cash App Pay** | The buyer clicks the **Cash App Pay** button. A QR code appears on screen. | | 3 | **Buyer scans the QR code** | The buyer opens Cash App on their phone and scans the QR code to authorize the payment. | | 4 | **Finix processes the transaction** | Once authorized, Finix automatically creates the payment instrument and processes the transaction. No additional steps are needed on your end. | ### Mobile | Step | Action | Details | | --- | --- | --- | | 1 | **Buyer opens checkout** | The buyer navigates to a Payment Link, Checkout Page, or Subscription Link with Cash App Pay enabled. | | 2 | **Buyer taps Cash App Pay** | The buyer taps the **Cash App Pay** button and is redirected to the Cash App. | | 3 | **Buyer confirms in Cash App** | The buyer reviews and confirms the payment inside the Cash App, then is returned to your checkout page. | | 4 | **Finix processes the transaction** | Once authorized, Finix automatically creates the payment instrument and processes the transaction. No additional steps are needed on your end. | ### Payment source Whether Cash App draws from the buyer's Cash App balance or a linked card is determined internally by Cash App—Finix has no visibility into or control over this decision. ### Statement Descriptor Cash App Pay transactions are not prefixed with `CashApp*` in the buyer's statement. Your configured statement descriptor is used as-is. ## Why offer Cash App Pay ### Reach more Buyers Cash App is used by millions of people across the United States. By adding Cash App Pay as a payment option, you give buyers a way to pay with a method they already trust and use daily—increasing the likelihood of a completed purchase. ### Streamlined Checkout Cash App Pay reduces checkout friction by replacing manual card entry with a single tap or QR code scan. The experience is quick and familiar, helping reduce cart abandonment and boost conversion. ### One-Time and recurring Payments Cash App Pay supports both single transactions and saved payment methods. With Finix's support for ON_FILE grants, you can offer Cash App Pay as a saved payment method for subscriptions and repeat purchases—without requiring buyers to re-authorize each time. ## Cash App Pay eligibility Cash App Pay is not available for all business types. The following categories are **not eligible** to accept Cash App Pay: - Business-to-business (B2B) merchants - Financial services businesses - Platforms focused on fundraising, donations, or alcohol sales - Businesses selling gift cards Review [Cash App Pay's Acceptable Use Policy](https://cash.app/legal/us/en-us/acceptable-use-policy) to confirm your business is eligible before integrating. ## Refunds and Disputes Refunds for Cash App Pay transactions are handled the same as all other Finix refunds. See [Refunds](/guides/after-the-payment/refunds) for more information. Disputes follow the standard Finix dispute process, which runs approximately 45 days. For fraud disputes, Block Inc bears the fraud liability. Finix receives a notification for fraud disputes but takes no action, and fraud disputes do not appear in the Finix UI. See [Disputes](/guides/after-the-payment/disputes) for more information. ## Learn more Cash App Pay with Low-Code Products Accept Cash App Pay using Payment Links, Checkout Pages, and Subscription Links—no custom integration required. --- # Google Pay on Android Source: https://docs.finix.com/guides/online-payments/digital-wallets/google-pay/google-pay-on-android Let buyers pay with Google Pay in your Android application, using any debit or credit card saved to their Google account. ## Overview To add Google Pay to your Android app, you configure the payment methods and tokenization your app accepts, add the Google Pay button, and request payment data. When a buyer pays, you process the resulting token with the Finix API. After setup, buyers can complete checkout with Google Pay and you process the payment like any other Finix transaction. The examples below show both Kotlin and Java. Collect the billing address to avoid extra fees Finix recommends passing the address field shown in the steps below. If you do not pass the address, the card network charges additional dues and assessments per transaction. ## Prerequisites Before you start, familiarize yourself with the [Google Pay requirements](/guides/online-payments/digital-wallets/google-pay) for Finix, including the Finix API key, seller onboarding, and Google Pay merchant account steps. ## Integration steps ### Step 1: Define the Google Pay API version Declare the version of the Google Pay API that your application uses. The major and minor versions affect the fields expected in each passed object and are included in the response. Create a base request object that contains the properties present in all other request objects. Kotlin ```kotlin Google Pay API Version private val baseRequest = JSONObject() .put("apiVersion", 2) .put("apiVersionMinor", 0) ``` Java ```java Google Pay API Version private static JSONObject getBaseRequest() throws JSONException { return new JSONObject() .put("apiVersion", 2) .put("apiVersionMinor", 0); } ``` ### Step 2: Request a Finix payment token Configure the tokenization specification so Google Pay returns a Finix payment token. - Set `gateway` to `finix`. - Set `gatewayMerchantId` to the application owner Identity or merchant owner Identity. To choose the appropriate Identity ID, see [Choose a Merchant identifier value](/guides/online-payments/digital-wallets/google-pay#choose-a-merchant-identifier-value). Kotlin ```kotlin Google Pay Tokenization Specification private fun gatewayTokenizationSpecification(): JSONObject { return JSONObject().apply { put("type", "PAYMENT_GATEWAY") put("parameters", JSONObject(mapOf( "gateway" to "finix", "gatewayMerchantId" to "IDxxx"))) } } ``` Java ```java Google Pay Tokenization Specification private static JSONObject getGatewayTokenizationSpecification() throws JSONException { return new JSONObject() .put("type", "PAYMENT_GATEWAY") .put("parameters", new JSONObject() .put("gateway", "finix") .put("gatewayMerchantId", "IDxxx") ); } ``` ### Step 3: Define allowed card networks Set which card networks your application accepts. Kotlin ```kotlin Google Pay Allowed Card Networks private val allowedCardNetworks = JSONArray(listOf( "AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA")) ``` Java ```java Google Pay Allowed Card Networks private static JSONArray getAllowedCardNetworks() { return new JSONArray() .put("AMEX") .put("DISCOVER") .put("INTERAC") .put("JCB") .put("MASTERCARD") .put("VISA"); } ``` Define `allowedCardAuthMethods` to set the authentication methods your application and gateway support. Kotlin ```kotlin Google Pay Allowed Card Auth Methods private val allowedCardAuthMethods = JSONArray(listOf( "PAN_ONLY", "CRYPTOGRAM_3DS")) ``` Java ```java Google Pay Allowed Card Auth Methods private static JSONArray getAllowedCardAuthMethods() { return new JSONArray() .put("PAN_ONLY") .put("CRYPTOGRAM_3DS"); } ``` For both `PAN_ONLY` and `CRYPTOGRAM_3DS` authorization methods, support for 3D Secure depends on the processors you integrate with in `allowedCardNetworks`. Finix accepts both `PAN_ONLY` and `CRYPTOGRAM_3DS` authorization methods. ### Step 4: Describe allowed payment methods After you define the supported card networks, describe your allowed payment methods: 1. Combine `allowedAuthMethods` and `allowedCardNetworks` to describe how your application supports the `CARD` payment method. 2. Extend the `baseCardPaymentMethod` object with the information you expect returned to your application, including a description of the tokenized payment data. Kotlin ```kotlin Google Pay Payment Methods private fun baseCardPaymentMethod(): JSONObject = JSONObject() .put("type", "CARD") .put("parameters", JSONObject() .put("allowedAuthMethods", allowedCardAuthMethods) .put("allowedCardNetworks", allowedCardNetworks) .put("billingAddressRequired", true) .put("billingAddressParameters", JSONObject() .put("format", "FULL") ) ) private val cardPaymentMethod: JSONObject = baseCardPaymentMethod() .put("tokenizationSpecification", gatewayTokenizationSpecification()) ``` Java ```java Google Pay Payment Methods private static JSONObject getBaseCardPaymentMethod() throws JSONException { return new JSONObject() .put("type", "CARD") .put("parameters", new JSONObject() .put("allowedAuthMethods", getAllowedCardAuthMethods()) .put("allowedCardNetworks", getAllowedCardNetworks()) .put("billingAddressRequired", true) .put("billingAddressParameters", new JSONObject() .put("format", "FULL") ) ); } private static JSONObject getCardPaymentMethod() throws JSONException { return getBaseCardPaymentMethod() .put("tokenizationSpecification", getGatewayTokenizationSpecification()); } ``` ### Step 5: Create a PaymentsClient instance Create a `PaymentsClient` instance to interact with the Google Pay API. Kotlin ```kotlin PaymentsClient Instance fun createPaymentsClient(context: Context): PaymentsClient { val walletOptions = Wallet.WalletOptions.Builder() .setEnvironment(Constants.PAYMENTS_ENVIRONMENT) .build() return Wallet.getPaymentsClient(context, walletOptions) } ``` Java ```java PaymentsClient Instance public static PaymentsClient createPaymentsClient(Context context) { Wallet.WalletOptions walletOptions = new Wallet.WalletOptions.Builder().setEnvironment(Constants.PAYMENTS_ENVIRONMENT).build(); return Wallet.getPaymentsClient(context, walletOptions); } ``` ### Step 6: Check readiness to pay with Google Pay After you describe your allowed payment methods, check readiness to pay with the Google Pay API: 1. Add `allowedPaymentMethods` to the `baseRequest` object. 2. Call `isReadyToPay()` to determine whether the user can pay with the Google Pay API. Kotlin ```kotlin Google Pay Readiness Check fun isReadyToPayRequest(): JSONObject? = try { baseRequest .put("allowedPaymentMethods", JSONArray().put(baseCardPaymentMethod())) } catch (e: JSONException) { null } private fun possiblyShowGooglePayButton() { val isReadyToPayJson = PaymentsUtil.isReadyToPayRequest() ?: return val request = IsReadyToPayRequest.fromJson(isReadyToPayJson.toString()) ?: return // The call to isReadyToPay is asynchronous and returns a Task. We need to provide an // OnCompleteListener to be triggered when the result of the call is known. val task = paymentsClient.isReadyToPay(request) task.addOnCompleteListener { completedTask -> try { completedTask.getResult(ApiException::class.java)?.let(::setGooglePayAvailable) } catch (exception: ApiException) { // Process error Log.w("isReadyToPay failed", exception) } } } ``` Kotlin (coroutines) ```kotlin Google Pay Readiness Check private suspend fun fetchCanUseGooglePay(): Boolean { val request = IsReadyToPayRequest.fromJson(PaymentsUtil.isReadyToPayRequest().toString()) return paymentsClient.isReadyToPay(request).await() } ``` The Tasks API lets you resolve task operations with coroutines. For more information, see [Google Pay integration](https://developers.google.com/pay/api/android/guides/tutorial#kotlincoroutines). Java ```java Google Pay Readiness Check public static JSONObject getIsReadyToPayRequest() { try { return getBaseRequest() .put("allowedPaymentMethods", new JSONArray().put(getBaseCardPaymentMethod())); } catch (JSONException e) { return null; } } private void possiblyShowGooglePayButton() { final Optional isReadyToPayJson = PaymentsUtil.getIsReadyToPayRequest(); if (!isReadyToPayJson.isPresent()) { return; } // The call to isReadyToPay is asynchronous and returns a Task. We need to provide an // OnCompleteListener to be triggered when the result of the call is known. IsReadyToPayRequest request = IsReadyToPayRequest.fromJson(isReadyToPayJson.get().toString()); Task task = paymentsClient.isReadyToPay(request); task.addOnCompleteListener(this, new OnCompleteListener() { @Override public void onComplete(@NonNull Task task) { if (task.isSuccessful()) { setGooglePayAvailable(task.getResult()); } else { Log.w("isReadyToPay failed", task.getException()); } } }); } ``` ### Step 7: Add the Google Pay button After you check readiness to pay, add a Google Pay payment button to your app. - For the different button types and display requirements, see [Google's brand guidelines](https://developers.google.com/pay/api/web/guides/brand-guidelines). - To try every Google Pay button, see [Google Pay's interactive demo](https://developers.google.com/pay/api/web/guides/resources/customize). Kotlin (compose) ```kotlin Google Pay Button PayButton( modifier = Modifier .testTag("payButton") .fillMaxWidth(), onClick = onGooglePayButtonClick, allowedPaymentMethods = PaymentsUtil.allowedPaymentMethods.toString() ) ``` To use the Jetpack Compose element, add the `com.google.pay.button:compose-pay-button` library to the list of dependencies in your Gradle build file. For more information, see [Google Pay payment button](https://developers.google.com/pay/api/android/guides/tutorial#add-button). XML ```xml Google Pay Button ``` If you add the Google Pay button with XML, initialize it in your Android activity along with your other UI elements. Kotlin ```kotlin Initialize Google Pay Button override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // Use view binding to access the UI elements layout = ActivityCheckoutBinding.inflate(layoutInflater) setContentView(layout.root) // Setup buttons googlePayButton = layout.googlePayButton googlePayButton.initialize( ButtonOptions.newBuilder() .setAllowedPaymentMethods(PaymentsUtil.allowedPaymentMethods.toString()).build() ) googlePayButton.setOnClickListener { requestPayment() } // Check Google Pay availability model.canUseGooglePay.observe(this, Observer(::setGooglePayAvailable)) } ``` Java ```java Initialize Google Pay Button private void initializeUi() { // Use view binding to access the UI elements ActivityCheckoutBinding layoutBinding = ActivityCheckoutBinding.inflate(getLayoutInflater()); setContentView(layoutBinding.getRoot()); // The Google Pay button is a layout file – take the root view googlePayButton = layoutBinding.googlePayButton; try { googlePayButton.initialize( ButtonOptions.newBuilder() .setAllowedPaymentMethods(PaymentsUtil.getAllowedPaymentMethods().toString()).build() ); googlePayButton.setOnClickListener(this::requestPayment); } catch (JSONException e) { // Keep Google Pay button hidden (consider logging this to your app analytics service) } } ``` ### Step 8: Create a payment data request After you add the Google Pay button, create a `PaymentDataRequest` object. The `PaymentDataRequest` takes in the merchant and transaction information required to start the payment process with Google Pay. Kotlin ```kotlin paymentDataRequest private fun getTransactionInfo(price: String): JSONObject = JSONObject() .put("totalPrice", price) .put("totalPriceStatus", "FINAL") .put("countryCode", Constants.COUNTRY_CODE) .put("currencyCode", Constants.CURRENCY_CODE) private val merchantInfo: JSONObject = JSONObject().put("merchantName", "Example Merchant") ``` Java ```java paymentDataRequest private static JSONObject getTransactionInfo(String price) throws JSONException { return new JSONObject() .put("totalPrice", price) .put("totalPriceStatus", "FINAL") .put("countryCode", Constants.COUNTRY_CODE) .put("currencyCode", Constants.CURRENCY_CODE) .put("checkoutOption", "COMPLETE_IMMEDIATE_PURCHASE"); } private static JSONObject getMerchantInfo() throws JSONException { return new JSONObject().put("merchantName", "Example Merchant"); } ``` The `getTransactionInfo` object accepts the following arguments. | Field | Type | Description | | --- | --- | --- | | `countryCode` | *string*, **required** | The ISO country code. | | `currencyCode` | *string*, **required** | The currency code of the locale. | | `totalPrice` | *string*, **required** | Total value of the transaction, with optional decimal precision of two places. | | `totalPriceStatus` | *string*, **required** | The status of the total price. Pass `FINAL` if the total price does not change from the amount presented to the buyer. Pass `ESTIMATED` if the total price might adjust based on the response, such as sales tax based on a billing address. Pass `NOT_CURRENTLY_KNOWN` when using `totalPriceStatus` for a capability check. | The `getMerchantInfo` object accepts the following arguments. | Field | Type | Description | | --- | --- | --- | | `merchantId` | *string*, **required** | A Google merchant identifier issued after registration with the Google Pay Business Console. Required when `PaymentsClient` is initialized with an `environment` property of `PRODUCTION`. | | `merchantName` | *string*, **required** | The name of the Merchant. | Strong Customer Authentication (SCA) Merchants that process transactions in the European Economic Area (EEA) or any other region subject to Strong Customer Authentication (SCA) must include the `countryCode`, `totalPrice`, and `merchantName` parameters to meet SCA requirements. Assign your base request object to a new `PaymentDataRequest` JSON object. Then add the payment methods your application supports, along with any configuration of additional data expected in the response. Finally, add the transaction and merchant information for the request. For more information, see [Step 5 of Google Pay integration](https://developers.google.com/pay/api/android/guides/tutorial#payment-data-request). ### Step 9: Use a Buyer Identity A Buyer Identity is required before you can process a payment. You can create a new Buyer Identity with the Finix API, or use an existing one. Buyer Identity data All Buyer Identity fields are optional. Finix recommends including basic information (name, email, address, and phone) to make payment operations easier. Use an existing Buyer To find and reuse an existing Buyer Identity: 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login). 2. In the left sidebar, select **Data Resources** → **Identities**. 3. Search for the Buyer Identity you want to use, and confirm its **Role** is **Buyer**. 4. Copy the Buyer Identity ID (for example, `IDjWktr7BPDGhz4amrPJZoXg`). Create a new Buyer Send a `POST` request to POST /identities with the `BUYER` role to create a new Buyer Identity. ```shell Buyer Identity Request curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/identities \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "entity": { "phone": "7145677613", "first_name": "John", "last_name": "Smith", "email": "finix_example@finix.com", "personal_address": { "city": "San Mateo", "country": "USA", "region": "CA", "line2": "Apartment 7", "line1": "741 Douglass St", "postal_code": "94114" } }, "identity_roles": [ "BUYER" ], "tags": { "key": "value" }, "type": "PERSONAL" }' ``` A successful request returns the Buyer Identity. Copy its `id` to use in the following steps. ```json 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": [ "BUYER" ], "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" } } } ``` ### Step 10: Create a Payment Instrument Call `loadPaymentData` using the Google Pay `PaymentsClient` object, which returns a `Task` object. Extract the payment token from the `PaymentData` result object. For more information, see [Step 6 of Google Pay integration](https://developers.google.com/pay/api/android/guides/tutorial#initiate-payment). Kotlin ```kotlin paymentDataRequest fun getLoadPaymentDataTask(priceLabel: String): Task { val paymentDataRequestJson = PaymentsUtil.getPaymentDataRequest(priceLabel) val request = PaymentDataRequest.fromJson(paymentDataRequestJson.toString()) return paymentsClient.loadPaymentData(request) } ``` Java ```java paymentDataRequest public Task getLoadPaymentDataTask(String priceLabel) { JSONObject paymentDataRequestJson = PaymentsUtil.getPaymentDataRequest(priceLabel); if (paymentDataRequestJson == null) { return null; } PaymentDataRequest request = PaymentDataRequest.fromJson(paymentDataRequestJson.toString()); return paymentsClient.loadPaymentData(request); } ``` To process the result, use one of the activity result contracts in the API. For more information, see [Step 6 of Google Pay integration](https://developers.google.com/pay/api/android/guides/tutorial#initiate-payment). Before you present the buyer with a confirmation of their purchase, extract the payment token from the `PaymentData` result object and use it in the Payment Instrument request below. Pass the `third_party_token`, `name`, and billing `address` that Google Pay returns when creating a Payment Instrument. Example API Definition A successful request returns the newly created Payment Instrument, which you use to process the payment. Example Payment Instrument - Google Pay ```json Payment Instrument - Google Pay { "id": "PIxr84Gjvm6Wee3wUbAaBRzK", "created_at": "2026-09-25T20:36:37.61Z", "updated_at": "2026-09-25T20:36:37.61Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRrcobjtdU98gr4sjiqYR1Qg", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "GOOGLE_PAY", "address": { "line1": "900 Metro Center Blv", "line2": "APT 200", "city": "San Francisco", "region": "CA", "postal_code": "94404", "country": "USA" }, "bin": "411111", "brand": "VISA", "card_type": "UNKNOWN", "expiration_month": 12, "expiration_year": 2028, "issuer_country": "UNKNOWN", "last_four": "1111", "name": "John Doe", "tags": {}, "third_party": null, "third_party_token": null, "type": "GOOGLE_PAY", // [!code highlight] "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIxr84Gjvm6Wee3wUbAaBRzK" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIxr84Gjvm6Wee3wUbAaBRzK/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIxr84Gjvm6Wee3wUbAaBRzK/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIxr84Gjvm6Wee3wUbAaBRzK/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` API Definition For security, [Google Pay tokens](https://support.google.com/pay/merchants/answer/6345242?hl=en#) are active for only a short period of time. The `third_party_token` in the request above has expired. To test the request, use your own `third_party_token` and Finix credentials. ### Step 11: Create a payment After the Payment Instrument is created, use it to create a Transfer or an Authorization, the same as any other Finix transaction. To process a sale: 1. Set the `source` to the buyer's Payment Instrument ID. 2. Set the `merchant` to an `APPROVED` Merchant account. 3. Set the `amount` in cents. ```shell Example 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": "PIwpqpJZCharsZAt6WKVopPS" }' ``` ```json Example Transfer Response { "id": "TR29av3LN1TAGPbXscsup1tt", "amount": 662154, "tags": {}, "state": "SUCCEEDED", "trace_id": "34f40e87-2599-414b-874b-f472790ff521", "currency": "USD", "application": "APgPDQrLD52TYvqazjHJJchM", "source": "PIwpqpJZCharsZAt6WKVopPS", "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": "IDpYDM7J9n57q849o9E9yNrG", "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/IDpYDM7J9n57q849o9E9yNrG" }, "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/PIwpqpJZCharsZAt6WKVopPS" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8" } } } ``` Alternatively, create an Authorization and capture it later with two separate API calls. This is useful when you need to verify the payment details first and capture a specific amount later. For more information, see [Creating and capturing an Authorization](/guides/online-payments/payment-features/auth-and-captures). ## Next steps Refunds Refund all or part of a Google Pay payment. Disputes Respond to buyer disputes on Google Pay transactions. Google Pay on web Accept Google Pay on your website using Finix. --- # Google Pay on Web Source: https://docs.finix.com/guides/online-payments/digital-wallets/google-pay/google-pay-on-web Let buyers pay with Google Pay on your website, using any debit or credit card saved to their Google account. ## Overview To add Google Pay to your website, you load the Google Pay JavaScript library, configure the payment methods and tokenization your site accepts, and add the Google Pay button. When a buyer pays, you process the resulting token with the Finix API. After setup, buyers can complete checkout with Google Pay and you process the payment like any other Finix transaction. Collect the billing address to avoid extra fees Finix recommends passing the address field shown in the steps below. If you do not pass the address, the card network charges additional dues and assessments per transaction. ## Prerequisites Before you start, familiarize yourself with the [Google Pay requirements](/guides/online-payments/digital-wallets/google-pay) for Finix, including the Finix API key, seller onboarding, and Google Pay merchant account steps. ## Google Pay demo See a live demo of Google Pay on the [Finix sample store](https://finixsamplestore.com). All of the sample store code is available in the [accept-a-payment GitHub project](https://github.com/finix-payments/accept-a-payment). In the sample store, add a few items to your cart and click **Checkout with Tokenization Form**. Sample store checkout with a tokenization form and express checkout option An express checkout button brings up the Google Pay modal. Express checkout with the Google Pay button The sample store uses Sandbox credentials, so you are not charged. Google Pay payment modal in the sample store ## Integration steps ### Step 1: Add the Google Pay library First, load the Google Pay API JavaScript library into your site. 1. Include the following script in your website so your site can call the Google Pay API. ```javascript Google Pay JS Script ``` 1. After the library loads, create a `PaymentsClient` object. - For a Sandbox environment, use `environment: "TEST"`. This returns test payment methods for Sandbox transactions. - For a Live environment, use `environment: "PRODUCTION"`. ```javascript Google Pay PaymentsClient Object const paymentsClient = new google.payments.api.PaymentsClient({ environment: "TEST", }); ``` ### Step 2: Define the Google Pay API version After you add the library, declare the version of the Google Pay API that your site uses. The major and minor versions are required in each passed object and are included in the response. ```javascript Google Pay API Version const baseRequest = { apiVersion: 2, apiVersionMinor: 0, }; ``` ### Step 3: Request a Finix payment token Configure the tokenization specification so Google Pay returns a Finix payment token. - Set `gateway` to `finix`. - Set `gatewayMerchantId` to the application owner Identity or merchant owner Identity. To choose the appropriate Identity ID, see [Choose a Merchant identifier value](/guides/online-payments/digital-wallets/google-pay#choose-a-merchant-identifier-value). ```javascript Google Pay Tokenization Specification const tokenizationSpecification = { type: "PAYMENT_GATEWAY", parameters: { gateway: "finix", gatewayMerchantId: "IDxxx", }, }; ``` ### Step 4: Define allowed card networks Set which card networks your site accepts: - Define `allowedCardNetworks` to list the accepted networks. - Define `allowedCardAuthMethods` to set the authentication methods your site and gateway support. ```javascript Google Pay Allowed Card Networks const allowedCardNetworks = [ "AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA", ]; const allowedCardAuthMethods = ["PAN_ONLY", "CRYPTOGRAM_3DS"]; ``` For both `PAN_ONLY` and `CRYPTOGRAM_3DS` authorization methods, support for 3D Secure depends on the processors you integrate with in `allowedCardNetworks`. Finix accepts both `PAN_ONLY` and `CRYPTOGRAM_3DS` authorization methods. ### Step 5: Describe allowed payment methods After you define the supported card networks, describe your allowed payment methods: 1. Combine `allowedAuthMethods` and `allowedCardNetworks` to describe how your site supports the `CARD` payment method. 2. Extend the `baseCardPaymentMethod` object with the information you expect returned to your site, including a description of the tokenized payment data. ```javascript Google Pay Payment Methods const baseCardPaymentMethod = { type: "CARD", parameters: { allowedAuthMethods: allowedCardAuthMethods, allowedCardNetworks: allowedCardNetworks, }, }; const cardPaymentMethod = Object.assign( { tokenizationSpecification: tokenizationSpecification }, baseCardPaymentMethod, ); ``` ### Step 6: Check readiness to pay with Google Pay After you describe your allowed payment methods, check readiness to pay with the Google Pay API: 1. Add `allowedPaymentMethods` to the `baseRequest` object. 2. Call `isReadyToPay()` to check whether the current device and browser support the Google Pay API for the payment methods you specified. ```javascript Google Pay Readiness Check const isReadyToPayRequest = Object.assign({}, baseRequest); isReadyToPayRequest.allowedPaymentMethods = [baseCardPaymentMethod]; paymentsClient .isReadyToPay(isReadyToPayRequest) .then(function (response) { if (response.result) { // add a Google Pay payment button } }) .catch(function (err) { // show error in developer console for debugging console.error(err); }); ``` ### Step 7: Add the Google Pay button After you check readiness to pay, add a Google Pay payment button to your website. - For the different button types and display requirements, see [Google's brand guidelines](https://developers.google.com/pay/api/web/guides/brand-guidelines). - To try every Google Pay button, see [Google Pay's interactive demo](https://developers.google.com/pay/api/web/guides/resources/customize). JavaScript ```javascript Google Pay Button – JS Example const button = paymentsClient.createButton({ onClick: () => console.log("TODO: click handler"), allowedPaymentMethods: [], }); // make sure to provide an allowed payment method document.getElementById("container").appendChild(button); ``` HTML ```html Google Pay Button – HTML Example ``` The button element supports the following attributes. | Field | Type | Description | | --- | --- | --- | | `button-color` | *string*, **optional** | Color of the button. Available values are `default`, `black`, and `white`. | | `button-type` | *string*, **optional** | The button type that initiates the transaction. Available values include `book`, `buy`, `checkout`, `donate`, `order`, `pay`, `plain`, and `subscribe`. | | `button-locale` | *string*, **required** | The language of the button. | ### Step 8: Create a payment data request After you add the Google Pay button, create a `PaymentDataRequest` object. 1. Build a JavaScript object that describes your site's support for the Google Pay API. For the supported properties, see the `PaymentDataRequest` object. ```javascript paymentDataRequest const paymentDataRequest = Object.assign({}, baseRequest); paymentDataRequest.allowedPaymentMethods = [cardPaymentMethod]; paymentDataRequest.transactionInfo = { countryCode: "US", currencyCode: "USD", totalPrice: "123.45", totalPriceStatus: "FINAL", }; paymentDataRequest.merchantInfo = { merchantId: "12345678901234567890", merchantName: "Example Merchant", }; ``` The `transactionInfo` object accepts the following arguments. | Field | Type | Description | | --- | --- | --- | | `countryCode` | *string*, **required** | The ISO country code. | | `currencyCode` | *string*, **required** | The currency code of the locale. | | `totalPrice` | *string*, **required** | Total value of the transaction, with optional decimal precision of two places. | | `totalPriceStatus` | *string*, **required** | The status of the total price. Pass `FINAL` if the total price does not change from the amount presented to the buyer. Pass `ESTIMATED` if the total price might adjust based on the response, such as sales tax based on a billing address. Pass `NOT_CURRENTLY_KNOWN` when using `totalPriceStatus` for a capability check. | The `merchantInfo` object accepts the following arguments. | Field | Type | Description | | --- | --- | --- | | `merchantId` | *string*, **required** | A Google merchant identifier issued after registration with the Google Pay Business Console. Required when `PaymentsClient` is initialized with an `environment` property of `PRODUCTION`. | | `merchantName` | *string*, **required** | The name of the Merchant. | 1. Add the payment methods your site supports and any additional data you expect in the response. 2. Set a `totalPrice` and `currencyCode` for the buyer to authorize. 3. Provide a buyer-visible `merchantName`. In a Sandbox environment, use the `TEST` Merchant ID. Strong Customer Authentication (SCA) Merchants that process transactions in the European Economic Area (EEA) or any other region subject to Strong Customer Authentication (SCA) must include the `countryCode`, `totalPrice`, and `merchantName` parameters to meet SCA requirements. ### Step 9: Use a Buyer Identity A Buyer Identity is required before you can process a payment. You can create a new Buyer Identity with the Finix API, or use an existing one. Buyer Identity data All Buyer Identity fields are optional. Finix recommends including basic information (name, email, address, and phone) to make payment operations easier. Use an existing Buyer To find and reuse an existing Buyer Identity: 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login). 2. In the left sidebar, select **Data Resources** → **Identities**. 3. Search for the Buyer Identity you want to use, and confirm its **Role** is **Buyer**. 4. Copy the Buyer Identity ID (for example, `IDjWktr7BPDGhz4amrPJZoXg`). Create a new Buyer Send a `POST` request to POST /identities with the `BUYER` role to create a new Buyer Identity. ```shell Buyer Identity Request curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/identities \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "entity": { "phone": "7145677613", "first_name": "John", "last_name": "Smith", "email": "finix_example@finix.com", "personal_address": { "city": "San Mateo", "country": "USA", "region": "CA", "line2": "Apartment 7", "line1": "741 Douglass St", "postal_code": "94114" } }, "identity_roles": [ "BUYER" ], "tags": { "key": "value" }, "type": "PERSONAL" }' ``` A successful request returns the Buyer Identity. Copy its `id` to use in the following steps. ```json 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": [ "BUYER" ], "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" } } } ``` ### Step 10: Create a Payment Instrument After you call `loadPaymentData` using the Google Pay payments client object, the response returns a token. ```javascript paymentsClient paymentToken paymentsClient .loadPaymentData(paymentDataRequest) .then(function (paymentData) { // if using gateway tokenization, pass this token without modification paymentToken = paymentData.paymentMethodData.tokenizationData.token; // for billing details name = paymentData.paymentMethodData.info.billingAddress.name; address = { postal_code: paymentData.paymentMethodData.info.billingAddress.postalCode, country: paymentData.paymentMethodData.info.billingAddress.countryCode, }; }) .catch(function (err) { // show error in developer console for debugging console.error(err); }); ``` Pass the `third_party_token`, `address`, and `name` when creating a Payment Instrument. Example API Definition A successful request returns the newly created Payment Instrument, which you use to process the payment. Example Payment Instrument - Google Pay ```json Payment Instrument - Google Pay { "id": "PIxr84Gjvm6Wee3wUbAaBRzK", "created_at": "2026-09-25T20:36:37.61Z", "updated_at": "2026-09-25T20:36:37.61Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRrcobjtdU98gr4sjiqYR1Qg", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "GOOGLE_PAY", "address": { "line1": "900 Metro Center Blv", "line2": "APT 200", "city": "San Francisco", "region": "CA", "postal_code": "94404", "country": "USA" }, "bin": "411111", "brand": "VISA", "card_type": "UNKNOWN", "expiration_month": 12, "expiration_year": 2028, "issuer_country": "UNKNOWN", "last_four": "1111", "name": "John Doe", "tags": {}, "third_party": null, "third_party_token": null, "type": "GOOGLE_PAY", // [!code highlight] "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIxr84Gjvm6Wee3wUbAaBRzK" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIxr84Gjvm6Wee3wUbAaBRzK/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIxr84Gjvm6Wee3wUbAaBRzK/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIxr84Gjvm6Wee3wUbAaBRzK/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` API Definition For security, [Google Pay tokens](https://support.google.com/pay/merchants/answer/6345242?hl=en#) are active for only a short period of time. The `third_party_token` in the request above has expired. To test the request, use your own `third_party_token` and Finix credentials. ### Step 11: Create a payment After the Payment Instrument is created, use it to create a Transfer or an Authorization, the same as any other Finix transaction. To process a sale: 1. Set the `source` to the buyer's Payment Instrument ID. 2. Set the `merchant` to an `APPROVED` Merchant account. 3. Set the `amount` in cents. ```shell Example 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": "PIwpqpJZCharsZAt6WKVopPS" }' ``` ```json Example Transfer Response { "id": "TR29av3LN1TAGPbXscsup1tt", "amount": 662154, "tags": {}, "state": "SUCCEEDED", "trace_id": "34f40e87-2599-414b-874b-f472790ff521", "currency": "USD", "application": "APgPDQrLD52TYvqazjHJJchM", "source": "PIwpqpJZCharsZAt6WKVopPS", "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": "IDpYDM7J9n57q849o9E9yNrG", "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/IDpYDM7J9n57q849o9E9yNrG" }, "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/PIwpqpJZCharsZAt6WKVopPS" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8" } } } ``` Alternatively, create an Authorization and capture it later with two separate API calls. This is useful when you need to verify the payment details first and capture a specific amount later. For more information, see [Creating and capturing an Authorization](/guides/online-payments/payment-features/auth-and-captures). ## Next steps Refunds Refund all or part of a Google Pay payment. Disputes Respond to buyer disputes on Google Pay transactions. Google Pay on Android Accept Google Pay in your Android application using Finix. --- # Google Pay Passthrough Source: https://docs.finix.com/guides/online-payments/digital-wallets/google-pay/google-pay-passthrough If you decrypt Google Pay tokens outside of Finix, use the passthrough path to send the wallet authentication fields including the Electronic Commerce Indicator (ECI) directly to Finix. The ECI is a one-or-two-digit value that card networks and issuers factor into liability and risk decisions on the authorization. PCI Level 1 Required The passthrough path transmits raw PAN (DPAN) data. Only customers that are PCI Level 1 compliant are permitted to use it. Sending `number` without PCI Level 1 approval returns a `422` error. ## How it works There are two ways to submit Google Pay data to `POST /payment_instruments`: | Path | How it works | | --- | --- | | **Encrypted token** (default) | Send the encrypted `third_party_token`. Finix decrypts it and extracts all fields, including ECI. | | **Passthrough** | Decrypt the token yourself and send the individual fields (`number`, `cryptogram`, `expiration_month`, `expiration_year`, `electronic_commerce_indicator_code`) directly. | You cannot send both `number` and `third_party_token` in the same request. Doing so returns a `422` error. ## Passthrough fields | Field | Type | Required | Description | | --- | --- | --- | --- | | `number` | *string* | **Yes** | Network token PAN (DPAN) from the decrypted token. May be a raw PAN for Google Pay. | | `cryptogram` | *string* | No | Wallet-generated cryptogram from the decrypted token. Optional for Google Pay — PAN_ONLY tokens do not produce a cryptogram. | | `expiration_month` | *integer* | No | Card expiration month (1–12). | | `expiration_year` | *integer* | No | Card expiration year (4-digit). | | `electronic_commerce_indicator_code` | *string* | No | One-or-two-digit value indicating the authentication method. The card network and issuer factor this into liability and risk decisions on the authorization. | ## Create a Payment Instrument (passthrough) When your server receives the decrypted fields from the Google Pay token, pass them directly in the `POST /payment_instruments` request body instead of `third_party_token`. Example API Definition Example Payment Instrument - Google Pay - Passthrough ```json Payment Instrument - Google Pay - Passthrough { "id": "PIrDh9YjhuDhtwMdwm8pCDqq", "created_at": "2026-09-25T20:05:27.70Z", "updated_at": "2026-09-25T20:05:27.70Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "GOOGLE_PAY", // [!code highlight] "address": { "line1": "900 Metro Center Blv", "line2": "APT 200", "city": "San Francisco", "region": "CA", "postal_code": "94404", "country": "USA" }, "bin": "520082", "brand": "MASTERCARD", "card_type": "DEBIT", "expiration_month": 11, "expiration_year": 2026, "issuer_country": "NON_USA", "last_four": "8210", "name": "John Doe", "tags": {}, "third_party": null, "third_party_token": null, "type": "GOOGLE_PAY", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIrDh9YjhuDhtwMdwm8pCDqq" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIrDh9YjhuDhtwMdwm8pCDqq/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIrDh9YjhuDhtwMdwm8pCDqq/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIrDh9YjhuDhtwMdwm8pCDqq/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` API Definition The response shape is identical to the standard Google Pay path. The `electronic_commerce_indicator_code` value is not echoed back in the response. ## Error responses | Scenario | Status | Error code | Message | | --- | --- | --- | --- | | `number` and `third_party_token` both sent | 422 | `INVALID_FIELD` | `Only one of number or third_party_token is allowed in a request.` | | Neither `number` nor `third_party_token` sent | 422 | `INVALID_FIELD` | `Either number or third_party_token must be provided` | | `electronic_commerce_indicator_code` is not 1 or 2 numeric digits | 422 | `INVALID_FIELD` | `electronic_commerce_indicator_code must be 1 or 2 numeric digits` | | Customer is not PCI Level 1 compliant | 422 | `UNPROCESSABLE_ENTITY` | `Unless you are PCI Level 1 compliant, you must send the encrypted GOOGLE_PAY token in the third_party_token field.` | --- # Google Pay Source: https://docs.finix.com/guides/online-payments/digital-wallets/google-pay Google Pay *Images courtesy of [Google Developers](https://developers.google.com/pay/api)* Add Google Pay to your [website](/guides/online-payments/digital-wallets/google-pay/google-pay-on-web) or [Android application](/guides/online-payments/digital-wallets/google-pay/google-pay-on-android) with the Finix API, so buyers can pay with any debit or credit card saved to their Google account. ## Why offer Google Pay - **Streamlined checkout:** Set Google Pay as the default, prominent payment method to reduce friction, minimize cart abandonment, and increase conversion. - **Enhanced security:** Google Pay's built-in security features help protect buyer data on every transaction. ## Requirements Before you integrate Google Pay, complete the following Finix and Google requirements. ### Finix requirements 1. Create a [Finix API key](/additional-resources/developers/authentication-and-api-basics/api-keys). 2. Complete the [seller onboarding](/guides/platform-payments/onboarding-sellers) process. After approval, the seller has an [approved Merchant](/guides/platform-payments/onboarding-sellers/seller-onboarding-process). ### Google requirements 1. Review Google Pay's [Acceptable Use Policy](https://payments.developers.google.com/terms/sellertos). 2. Serve your website over HTTPS with a valid SSL certificate and TLS support. For the full requirements, see: - [Google Pay Web developer documentation](https://developers.google.com/pay/api/web/overview). - [Google Pay Web integration checklist](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist). - [Google Pay Web brand guidelines](https://developers.google.com/pay/api/web/guides/brand-guidelines). 3. Set up a Google Pay merchant account: - Review [Google Pay's developer documentation](https://developers.google.com/pay/api/web/overview) to gain production access to the Google Pay API. - Register with the [Google Pay Business Console](https://pay.google.com/business/console/home) to set up a merchant account. 4. Choose your platform: - For web integrations, see [Google Pay for Payments (Web)](https://developers.google.com/pay/api/web/guides/tutorial#tokenization). - For Android integrations, see [Google Pay for Payments (Android)](https://developers.google.com/pay/api/android/guides/tutorial#tokenization). ## Choose a Merchant identifier value The `gatewayMerchantId` value corresponds to a merchant identity beginning with a prefix `IDxxx`. There are two options for which value to pass in. ### Application owner Identity ID (default) If the Google Pay button is hosted on your domain, use your application Identity ID. This flow is common when a single website hosts all of your checkout flows. This is the default option for Direct Merchants and most Platforms. You can find the application owner Identity ID from the [`merchant.identity`](/api/merchants/getmerchant#merchants/getmerchant/t=response&c=200&path=identity) field on the Merchant you use to process payments. ### Merchant owner Identity ID If you are a Platform that hosts websites on custom URLs, provide the owner Identity of your merchants. For example, a Platform that creates a website for each of its sellers on a custom URL uses this value. Finix recommends reaching out to your Finix point of contact if your flow fits this criterion. ## Learn more Google Pay on Android Accept Google Pay in your Android application using Finix. Google Pay on web Accept Google Pay on your website using Finix. --- # 3D Secure liability shift Source: https://docs.finix.com/guides/online-payments/fraud-and-risk/3d-secure/3ds-liability-shift US only 3D Secure is currently supported for US-based merchants only. Canada support is coming soon. 3D Secure can shift liability for fraud chargebacks from you to the issuing bank under card network rules. It does not prevent cardholders from disputing a payment or guarantee that a dispute will resolve in your favor. Authenticated payments can still be disputed, and you may still need to respond to those disputes. ## Overview 3D Secure authentication creates a record of whether the cardholder was verified. Under card network rules, that record determines whether certain fraud chargebacks are assigned to the issuer or to you. Liability shift is not dispute protection. Even on fully authenticated payments: - Cardholders can still raise fraud disputes. - Issuers can still process chargebacks, including under reason codes outside the fraud liability-shift rules. - You may still receive dispute inquiries and chargebacks that you need to defend, and representment can still fail. Outcomes depend on the evidence, the reason code, and the issuer, not on the authentication record alone. Treat 3DS as a reduction in your fraud exposure, not as immunity from fraud losses. When authentication completes, one of three outcomes is recorded: - **Fully authenticated**: The issuer authenticated the cardholder, either through frictionless authentication or a successful challenge. Fraud chargeback liability can shift to the issuing bank under card network rules. - **Authentication attempted**: Authentication was attempted but the issuer or card does not support full 3DS verification. In some cases, the card network may be involved in the authentication. Fraud chargeback liability can shift to the issuing bank under card network rules. - **Not authenticated**: The cardholder did not pass authentication. This can happen if they failed the challenge, abandoned the flow, or were flagged as suspicious by the issuer. Liability stays with you. When authentication does not complete: - If the authentication process fails entirely, for example because the card is not enrolled in 3DS or the issuer's server was unavailable, no authentication record is created and liability stays with you. - If you process the payment without 3DS, the payment is handled without authentication and liability also stays with you. Flowchart showing how 3D Secure authentication outcomes map to liability ## API details ### Session state vs. authentication outcome The 3D Secure Session has two distinct concepts: - **Session state** (`state`): Whether the 3DS flow ran to completion. `SUCCEEDED` means the process completed; `FAILED` means it did not. - **Authentication outcome** (`electronic_commerce_indicator`): The result of authentication. This field is only present when `state` is `SUCCEEDED`. To determine liability, read `electronic_commerce_indicator`, not `state`. A `SUCCEEDED` state does not mean the cardholder was authenticated. ### Electronic Commerce Indicator values | Value | Meaning | Liability | | --- | --- | --- | | `AUTHENTICATED` | Cardholder was fully authenticated | Can shift to issuing bank | | `ATTEMPTED` | Authentication attempted; issuer or card does not support full 3DS | Can shift to issuing bank | | `NON_AUTHENTICATED` | Cardholder was not authenticated | Stays with you | ### When state is FAILED If `state` is `FAILED`, authentication did not run to completion. The `failure_code` and `failure_message` fields describe the reason. Common causes include: - The card is not enrolled in 3DS - The issuer's authentication server was unavailable - The card network's directory server was unreachable --- # 3D Secure using the Finix API Source: https://docs.finix.com/guides/online-payments/fraud-and-risk/3d-secure/finix-api US only 3D Secure is currently supported for US-based merchants only. Canada support is coming soon. Authenticate a buyer from your server, with no Finix code in your checkout page. Use this integration when your server drives checkout, or when you can't add a JavaScript library to your front end. It's also the route for mobile apps until the Finix iOS and Android SDKs support 3D Secure. ## Prerequisites You need the following: - The card to authenticate as a Payment Instrument ID. If you have a token from a [tokenization form](/guides/online-payments/payment-tokenization), use it to create a Payment Instrument first. - The ID of the Merchant the payment is processed under. - An HTTPS URL on your site to return the buyer to. ## Step 1: Create the 3D Secure Session Create the session when the buyer is ready to pay, by calling POST /3d_secure_sessions. Server-side only This request must originate from your server, not the browser. A client-accessible endpoint is an endpoint anyone can call, which exposes your integration to BIN enumeration attacks and allows an attacker to forge a session and attach it to a payment. The request accepts the following fields: | Field | Description | | --- | --- | | `amount` | Required. The amount to authenticate, in cents. This must match the amount you charge. | | `currency` | Required. The three-letter ISO currency code for the payment. | | `merchant_id` | Required. The ID of the Merchant the payment is processed under. | | `payment_instrument_id` | Required for this flow. The ID of the Payment Instrument to authenticate. | | `redirect_url` | Required for this flow. The HTTPS URL to return the buyer to after authentication. Finix passes it to the hosted page as a redirect parameter. | | `tags` | Key-value data to store on the session, such as your own order number. | Example API Definition 3D Secure Session ```json 3D Secure Session { "id": "3d_secure_session_9hK2mNp4T761RBv8qwLDYc", "created_at": "2026-08-13T16:41:12.884210Z", "updated_at": "2026-08-13T16:41:13.102994Z", "3d_secure_authentication": null, "3d_secure_authentication_session_id": "tds_visa_5c21a4de91b7", "3d_secure_authentication_url": "https://3ds.evervault.com/?team=team_77f6348bb6fd&app=app_ecd782a41696&session=tds_visa_5c21a4de91b7&redirect=https%3A%2F%2Fexample.com%2F3d-secure%2Freturn", "3d_secure_version": null, "amount": 92169, "authentication_type": null, "currency": "USD", "failure_code": null, "failure_message": null, "merchant_id": "MUmfEGv5bMpSJ9k5TFRUjkmm", "payment_instrument_id": "PI6iQcTtJNCS8GZAVKYi5Ueb", "redirect_url": "https://example.com/3d-secure/return", "state": "PENDING", "tags": { "info": "Create 3DS Session with Payment Instrument" } } ``` The session normally starts in the `PENDING` state, and the five-minute expiry starts at the `created_at` timestamp. If the card is not enrolled in 3DS, the session can return `FAILED` immediately — check `state` before sending the buyer to the authentication URL. In that case, read `failure_code` and `failure_message` for the reason. ## Step 2: Authenticate the buyer The buyer authenticates with their bank on a page Finix hosts, then returns to your site. Confirm the outcome from your server before you charge anything. ### Send the buyer to the authentication page The session carries a `3d_secure_authentication_url`. Open it in the buyer's browser, either by redirecting the whole page or by loading the URL in a frame embedded in your checkout. Treat the URL as opaque. Send the buyer to it exactly as Finix returned it, rather than constructing or parsing it yourself. What the buyer sees depends on what the issuer decides: - Low-risk payments authenticate in the background, and the buyer returns without seeing anything. - Otherwise the issuer presents a challenge, such as a one-time passcode or a prompt in the buyer's banking app. ### Read the result on your return URL Once authentication finishes, the buyer returns to your `redirect_url` with two query parameters appended: ```text Return URL https://example.com/3d-secure/return?status=success&session=3d_secure_session_9hK2mNp4T761RBv8qwLDYc ``` | Parameter | Description | | --- | --- | | `status` | How the authentication flow ended. One of `success`, `failure`, or `error`. | | `session` | The ID of the 3D Secure Session. | status is not the session state The `status` parameter has its own lowercase values and is not the session `state`. It reports how the browser flow ended, not what the issuer decided. ### Confirm the outcome from your server The query parameters arrive through the buyer's browser, where they can be edited, so retrieve the session from your server to confirm what actually happened. 3D Secure Session ```json 3D Secure Session { "id": "3d_secure_session_9hK2mNp4T761RBv8qwLDYc", "created_at": "2026-08-13T16:41:12.884210Z", "updated_at": "2026-08-13T16:41:58.774391Z", "3d_secure_authentication": { "cardholder_authentication": "BwABBJQ1AgAAAAAgJDUCAAAAAAA=", "electronic_commerce_indicator": "AUTHENTICATED", "transaction_id": "EaOMucALHQqLAEGAgk" }, "3d_secure_authentication_session_id": "tds_visa_5c21a4de91b7", "3d_secure_authentication_url": "https://3ds.evervault.com/?team=team_77f6348bb6fd&app=app_ecd782a41696&session=tds_visa_5c21a4de91b7&redirect=https%3A%2F%2Fexample.com%2F3d-secure%2Freturn", "3d_secure_version": "2.2.0", "amount": 92169, "authentication_type": "CHALLENGE", "currency": "USD", "failure_code": null, "failure_message": null, "merchant_id": "MUmfEGv5bMpSJ9k5TFRUjkmm", "payment_instrument_id": "PI6iQcTtJNCS8GZAVKYi5Ueb", "redirect_url": "https://example.com/3d-secure/return", "state": "SUCCEEDED", "tags": { "info": "Create 3DS Session with Payment Instrument" } } ``` A `SUCCEEDED` state means authentication ran to completion, not that the buyer was authenticated. Read `electronic_commerce_indicator` to find out whether liability shifts. Buyers close the tab mid-challenge, lose connectivity, or never return to your site at all. In each of those cases no query parameters reach you, so subscribe to the session webhook and treat it as the record of what happened. For more information, see [3D Secure Session webhooks](/guides/online-payments/fraud-and-risk/3d-secure#3d-secure-session-webhooks). ## Step 3: Run the sale or Authorization Reference the completed session as `3d_secure_session` on the Transfer or Authorization. Finix reads the authentication values from the session and sends them to the card network with the payment. ```shell Transfer with a 3D Secure Session 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 '{ "amount": 92169, "currency": "USD", "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "source": "PI6iQcTtJNCS8GZAVKYi5Ueb", "3d_secure_session": "3d_secure_session_9hK2mNp4T761RBv8qwLDYc" }' ``` A successful request returns a `201 Created` status code, with the response body containing the newly created Transfer resource. To authorize the payment now and capture it later, create an Authorization with the same `3d_secure_session` field, then [capture it](/guides/online-payments/payment-features/auth-and-captures#capturing-an-authorization). Don't send both 3D Secure fields `3d_secure_session` and `3d_secure_authentication` are mutually exclusive. Use `3d_secure_session` when Finix runs the authentication, and `3d_secure_authentication` only when you authenticate with [your own vendor](/guides/online-payments/fraud-and-risk/3d-secure/passthrough). ## Next steps 3D Secure Authentication How 3D Secure works, session webhooks, and best practices. 3D Secure Sessions API Every field on the 3D Secure Session resource. --- # 3D Secure using Finix.js Source: https://docs.finix.com/guides/online-payments/fraud-and-risk/3d-secure/finix-js US only 3D Secure is currently supported for US-based merchants only. Canada support is coming soon. Render the 3D Secure challenge inside your own checkout page. Finix.js shows the challenge in an in-page modal overlay, so the buyer never leaves your checkout. How you raise it depends on whether you're tokenizing a card at checkout or authenticating one you already have on file. ## Prerequisites Before you start, make sure you have the following. ### The Finix.js library Add the library to your checkout page with a script tag: ```html ``` ### A session endpoint on your backend Finix.js never creates a 3D Secure Session itself. You need an endpoint on your own backend that calls POST /3d_secure_sessions with your API credentials and returns the response to your page unmodified. Leave `redirect_url` out of the sessions you create for Finix.js. The challenge renders in your page, so there's nowhere to send the buyer. Keep credentials and trusted values on your server Your browser calls this backend endpoint, but it must never receive your Finix API credentials. Authenticate the checkout, derive and validate the merchant and amount on the server, and rate-limit requests to prevent BIN enumeration and forged sessions. ### Your environment and Application ID The payment-form option requires an Application ID and environment. The standalone `Finix.ThreeDSecure` class takes only the environment. In both flows, the environment must match the credentials your backend uses. ## Option 1 - 3DS authentication when tokenizing a card Use this option when the buyer enters card details at checkout. Finix.js tokenizes the card, calls your session endpoint, and raises the challenge in one pass. ### Step 1: Add the ThreeDSecure option to your payment form Add a `ThreeDSecure` object to the options you already pass to [Finix.PaymentForm](/js/payment-form). Its `createSession` hook is the backend endpoint from the prerequisites. ```javascript Checkout page async function createThreeDSecureSession(token) { // Your backend calls POST /3d_secure_sessions with your API credentials. const response = await fetch("/checkout/3d-secure-session", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ tokenId: token.id, amount: 92169, currency: "USD", }), }); // Return the session response unmodified. return response.json(); } Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", { ThreeDSecure: { createSession: createThreeDSecureSession, onStatusChange: function ({ status }) { console.log("3DS status:", status); }, }, // ...existing options like onSubmit, etc. }); ``` Finix.js calls `createSession` after it generates a token, waits for your endpoint to resolve, then renders the challenge if the issuer asks for one. Return the session unmodified: Finix.js reads `state` from it to decide whether a challenge is possible, and hands the whole object back to you. `onStatusChange` is optional. It reports `initialized` as an advisory, then exactly one of `succeeded` or `failed`, just before `onSubmit` runs. ### Step 2: Read the result in onSubmit Your existing [onSubmit](/js/callbacks) callback fires exactly once per submission. It receives the token on `response.data`, plus the authentication result on `response.threeDSecure` as `{ session, status, error }`. ```javascript Checkout page onSubmit: function (error, response) { // This error argument covers tokenization only. It says nothing about 3D Secure. if (error) { console.error("Tokenization failed:", error); return; } const token = response.data; // Absent on bank and Plaid submissions, which bypass the hook entirely. const { session, status, error: threeDSecureError } = response.threeDSecure || {}; if (status === "failed") { if (threeDSecureError.code === "CARD_NOT_ENROLLED") { // Nothing went wrong. The card simply cannot be authenticated. console.log("No challenge possible:", threeDSecureError.reason); } else { console.error(`3DS failed [${threeDSecureError.code}]:`, threeDSecureError.reason); return; } } // Charge the card from your server. fetch("/checkout/pay", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ tokenId: token.id, sessionId: status === "succeeded" ? session.id : undefined, status, }), }); }, ``` A null error does not mean the card was authenticated The `error` argument reports tokenization failures only. Read `response.threeDSecure.status` before you charge, or you'll charge cards that failed the challenge. Two cases deserve their own handling: - `CARD_NOT_ENROLLED` means no challenge was possible, not that something broke. You can still charge the card, but the payment is unauthenticated and liability stays with you. Gate on this if your integration requires 3D Secure. - Bank and Plaid submissions never call your hook, so `response.threeDSecure` is absent. Guard for it rather than assuming it's there. Branch on `status`, never on `session.state`. The session updates asynchronously on the server and still reads `PENDING` when your callback runs. For every `error.code` value, see [Error codes](/js/three-d-secure#error-codes). ### Step 3: Run the sale or Authorization On your backend, convert the token from `response.data.id` to a Payment Instrument by calling `POST /payment_instruments` with `type: TOKEN` and the token ID. Use the resulting Payment Instrument ID as `source`, and reference the session as `3d_secure_session` on the Transfer or Authorization. Finix sends the authentication values to the card network with the payment. ```shell Transfer with a 3D Secure Session 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 '{ "amount": 92169, "currency": "USD", "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "source": "PI6iQcTtJNCS8GZAVKYi5Ueb", "3d_secure_session": "3d_secure_session_9hK2mNp4T761RBv8qwLDYc" }' ``` Use `succeeded` to trigger payment submission on the client. On your server, verify the authentication outcome by fetching the session or confirming via webhook before charging — don't rely on the client-supplied status alone. Don't send both 3D Secure fields `3d_secure_session` and `3d_secure_authentication` are mutually exclusive. Use `3d_secure_session` when Finix runs the authentication, and `3d_secure_authentication` only when you authenticate with [your own vendor](/guides/online-payments/fraud-and-risk/3d-secure/passthrough). ## Option 2 - 3DS authentication when a card is already tokenized Use this option when there's no Finix payment form on the page. That covers charging a Payment Instrument you already have on file, and checkouts that collect the card number in your own PCI-compliant form. Here your backend creates the session before the challenge runs, because there's no tokenization step to trigger the hook. ### Step 1: Create the session on your server Call your session endpoint with the Payment Instrument you're about to charge, and return the session to the page. The amount must match what you charge in Step 3. ```javascript Checkout page const response = await fetch("/checkout/3d-secure-session", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ amount: 92169, currency: "USD", paymentInstrument: "PI6iQcTtJNCS8GZAVKYi5Ueb", }), }); const session = await response.json(); ``` ### Step 2: Raise the challenge Pass the whole session object to `validate`, and listen for the outcome. ```javascript Checkout page Finix.ThreeDSecure("sandbox") .validate(session) .on("succeeded", function ({ session }) { // Charge the card from your server. fetch("/checkout/pay", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ paymentInstrument: "PI6iQcTtJNCS8GZAVKYi5Ueb", sessionId: session.id, }), }); }) .on("failed", function ({ error }) { console.error(`3DS failed [${error.code}]:`, error.reason); }); ``` Pass the session through whole rather than picking fields out of it. The `environment` argument takes the same values as the rest of Finix.js, and must match the environment your API credentials belong to. Register a `failed` listener to handle a buyer who cancels the overlay or an issuer that declines the authentication. ### Step 3: Run the sale or Authorization Reference the session the same way as in Option 1, using the saved Payment Instrument as the `source`. ```shell Transfer with a 3D Secure Session 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 '{ "amount": 92169, "currency": "USD", "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "source": "PI6iQcTtJNCS8GZAVKYi5Ueb", "3d_secure_session": "3d_secure_session_9hK2mNp4T761RBv8qwLDYc" }' ``` The same two rules apply. Submit when the success listener fires rather than waiting for `state` to reach `SUCCEEDED`, and never send `3d_secure_session` and `3d_secure_authentication` together. ## Next steps Finix.ThreeDSecure Every method, option, event, and error code for 3D Secure in Finix.js. 3D Secure Authentication How 3D Secure works, session webhooks, and best practices. --- # 3D Secure authentication Source: https://docs.finix.com/guides/online-payments/fraud-and-risk/3d-secure US only 3D Secure is currently supported for US-based merchants only. Canada support is coming soon. Verify that your buyer is the real cardholder before you charge their card. 3D Secure (3DS) is a card authentication protocol that adds a verification step between your buyer and their issuing bank. Before the payment is authorized, the buyer confirms their identity with a one-time passcode, a biometric prompt, or their banking app. The card networks brand the protocol under their own names: Visa Secure, Mastercard Identity Check, Discover ProtectBuy, and American Express SafeKey. The underlying protocol is the same for all four. Finix supports 3DS2 (EMV 3-D Secure), the current version. ## Why use 3D Secure - **Reduced fraud:** The buyer proves their identity to their bank before the payment is authorized, which stops most unauthorized card-not-present payments. - **Reduced fraud liability:** When a payment authenticates successfully, card network rules can shift liability for fraud chargebacks to the issuing bank. 3DS does not prevent disputes — see [3D Secure liability shift](/guides/online-payments/fraud-and-risk/3d-secure/3ds-liability-shift) for what shift does and does not cover. - **Regulatory compliance:** 3DS is the standard way to meet Strong Customer Authentication requirements, which are mandatory in several regions. ## How 3D Secure works Every Finix-managed 3DS payment begins with a 3D Secure Session, which holds the authentication for a single payment. You create the session before you submit the payment, and then reference it on the resulting Transfer or Authorization. If you authenticate with your own vendor, use the [passthrough integration](/guides/online-payments/fraud-and-risk/3d-secure/passthrough) instead. 3DS session pipeline The issuer decides how much verification each payment needs, so some buyers complete a challenge and others are authenticated in the background without seeing one. ## 3D Secure Session webhooks Finix sends a webhook when a session changes state. Subscribe to it and treat it, not the browser, as the record of what happened. The round trip through the buyer's browser is the part of this flow you don't control. Buyers close the tab mid-challenge, lose connectivity, or never come back. The webhook tells your server how the authentication ended in every one of those cases. For sample event payloads, see [3D Secure Session created](/additional-resources/developers/webhooks/webhook-events#3d-secure-session-created) and [3D Secure Session updated](/additional-resources/developers/webhooks/webhook-events#3d-secure-session-updated). For general webhook setup, see [Integrating into Webhooks](/additional-resources/developers/webhooks/integrating-into-webhooks). ## Best practices - **Authenticate the exact amount you charge.** If the total changes after you create the session, because of a tip, a shipping choice, or a discount code, create a new session for the new amount. A mismatch downgrades the liability shift even when the payment succeeds. - **Create the session when the buyer is ready to pay.** Sessions expire five minutes after creation. A session that runs out while the buyer is still on the challenge fails with `AUTHENTICATION_TIMED_OUT`, and the buyer needs a new one. - **Use each session once.** Submitting a second Transfer or Authorization against a session that has already been used returns a `422`. - **Decide what a `FAILED` session means for you.** Finix does not block a payment that references one. Avoid sending authentication data from a failed authentication, because the failure is itself a fraud signal. We recommend creating a new session, asking the buyer for another payment method, or submitting the payment without 3D Secure and accepting that liability stays with you. ## Choose your integration 3D Secure using Finix.js Render the challenge inside your own checkout page. 3D Secure using the Finix API Send the buyer to a hosted page, with no Finix code in your checkout. 3D Secure Passthrough Pass authentication values from your own 3D Secure vendor to Finix. 3D Secure Liability Shift Understand how authentication outcomes determine chargeback liability. --- # 3D Secure Passthrough Source: https://docs.finix.com/guides/online-payments/fraud-and-risk/3d-secure/passthrough US only 3D Secure is currently supported for US-based merchants only. Canada support is coming soon. Authenticate payments with your own 3D Secure vendor and send the results to Finix. If you already authenticate payments through a 3D Secure vendor, you can pass the values that vendor produces to Finix on an Authorization or Transfer. Finix forwards them to the card network with the payment, and liability shifts the same way it does for any other 3D Secure payment. Your vendor is responsible for producing the values passed in `3d_secure_authentication`. Finix does not create or validate them. Finix can handle authentication for you You don't need your own vendor to accept 3D Secure payments. For the integrations where Finix manages authentication, see [3D Secure](/guides/online-payments/fraud-and-risk/3d-secure). ## Authorizations with 3D Secure To authorize a payment, your server must send a POST /authorizations request to create an Authorization and provide the `3d_secure_authentication` data in the request body: Example API Definition A successful request returns a `201 Created` status code, with the response body containing the newly created Authorization resource. Capturing the Authorization The Authorization still needs to be [captured](/guides/online-payments/payment-features/auth-and-captures#capturing-an-authorization). ## Transfers with 3D Secure To charge a card directly, send a POST /transfers request and provide the `3d_secure_authentication` data: Example API Definition A successful request returns a `201 Created` status code, with the response body containing a Transfer resource: Example Transfer ```json Transfer { "id": "TRgKTSSCydKysw1GYbJAcFTB", "created_at": "2026-09-25T20:05:47.61Z", "updated_at": "2026-09-25T20:05:47.61Z", "3d_secure_session": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": null, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 92169, "amount_requested": 92169, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "USD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj", "idempotency_id": null, "ip_address_details": null, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "messages": [], "network_details": { "brand": "VISA", "authorization_code": "911286", "acquirer_reference_number": null }, "operation_key": "CARD_NOT_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "processed_at": "2026-09-25T20:05:48.01Z", "raw": null, "ready_to_settle_at": "2026-09-26T20:05:47.61Z", "receipt_last_printed_at": null, "security_code_verification": "MATCHED", "source": "PI6iQcTtJNCS8GZAVKYi5Ueb", "split_transfers": [], "state": "SUCCEEDED", "statement_descriptor": "FLX*FINIX FLOWERS", "subtype": "API", "supplemental_fee": null, "tags": {}, "third_party_details": null, "tip_amount": null, "trace_id": "226ea8e9-30be-4f5a-ad91-5bbec49f481e", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRgKTSSCydKysw1GYbJAcFTB" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRgKTSSCydKysw1GYbJAcFTB/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRgKTSSCydKysw1GYbJAcFTB/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRgKTSSCydKysw1GYbJAcFTB" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRgKTSSCydKysw1GYbJAcFTB/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6iQcTtJNCS8GZAVKYi5Ueb" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj" } } } ``` API Definition ## Learn more 3D Secure Authentication How 3D Secure works, and the other ways to authenticate a payment. Auth and Captures Capture an Authorization once the payment is authenticated. --- # Common Fees Source: https://docs.finix.com/guides/online-payments/payment-features/buyer-charges/common-fees Learn about the requirements and what you can do with Common Fees. A common fee is a buyer charge that passes any additional cost to the buyer (e.g. tip, delivery fee, processing fee). Common fees are flexible and used for many situations; however, common fees can't be named or presented to buyers in a way to offset the cost of processing payments or accepting cards. ## Examples Here are a few examples of the different fees you can charge buyers using common fees. Please note that this is only a selection of the different names sellers can call common fees: | Name | Description | | --- | --- | | Administrative Fee | A fee charged to buyers to cover costs related to administrative services as part of a service or good. | | Bottle Deposit and Bag Fees | A fee charged to the buyer for containers and packaging. | | Cleaning Fee | A fee charged to the buyer for costs related to cleaning property. | | Delivery Fee | A fee charged to buyers to cover costs related to delivery. | | Fuel Surcharge | A fee used to cover costs related to fuel which can fluctuate greatly. This can be in addition to any other fee, including delivery. | | Marketplace Fee | A fee charged to marketplace users to cover costs related to the regulatory, safety and operational requirements the marketplace must follow. | | Priority Fees | A fee charged to the buyer for faster delivery or service. | | Processing Fee | A fee charged to buyers to cover costs associated with processing an order. | | Regulatory Fee | A fee charged to buyers to cover costs associated with government regulation. | | Shipping Fee | A fee charged to buyers to cover costs associated with shipping or mailing out goods. | ## Requirements Sellers and your integration must meet these requirements to charge Common Fees: - Sellers can name the Common Fee anything as long as it sufficiently describes the fee's purpose. - The fee should be priced in line with the actual cost of the fee's purpose. - The fee needs to be consistently used throughout your integration. - The fee cannot be related to the costs of processing cards or payments. - The fee must be disclosed to the buyer and included in the receipt. - After the fee gets disclosed, the buyer must have the option to cancel the transaction without any consequences. ## Finix API When creating a `Transfer` (or `Authorization`) with Common Fees, you don't need to pass any additional information in the request. The `amount` value should represent the total amount of the transaction. - Name and present the field to avoid confusion with any Convenience, Service, or Surcharge Fees. - Consult with your legal counsel to ensure you're compliant with government rules - If you'd like to track the fee, we recommend either storing the value on your system, or passing the field in the `tags`. See the following for a `Transfer` that includes a delivery fee. - The example is a $50 food delivery payment with a delivery fee of $3. - The fee is included in `tags` for tracking purposes. ```shell Common Fee Example 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 '{ "amount": 5300, "currency": "USD", "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "source": "PIe2YvpcjvoVJ6PzoRPBK137", "tags": { "delivery_fee": "300" } }' ``` --- # Buyer Charges Source: https://docs.finix.com/guides/online-payments/payment-features/buyer-charges This guide outlines the fees eligible merchants are able to charge their customers to offset the cost of payment processing when using certain card brands. Use the Finix Dashboard to verify buyer charges are enabled for sellers: Buyer Charges Dashboard ## Available Buyer charges The buyer charges available to sellers include: - [Common Fees:](#common-fees) Any additional charges passed to the buyer that ***is not*** used to offset the cost of processing payments. (e.g. delivery fees, fuel costs, priority fees, handling fees, utensil fees, etc.) - [Card Brand Fees:](#card-brand-fees) Charges used to offset the cost of processing payments. Card Brand Fees are regulated and monitored by card networks. (e.g. Visa Rent Fees, Convenience Fees, Service Fees) For most situations, we recommend using common fees. ### Common fees Here are a few examples of the different fees you can charge buyers using [Common Fees](#common-fees). Please note that this is only a selection of the different names sellers can call common fees: | Name | Description | | --- | --- | | Administrative Fee | A fee charged to buyers to cover costs related to administrative services as part of a service or good. | | Bottle Deposit and Bag Fees | A fee charged to the buyer for containers and packaging. | | Cleaning Fee | A fee charged to the buyer for costs related to cleaning property. | | Delivery Fee | A fee charged to buyers to cover costs related to delivery. | | Fuel Surcharge | A fee used to cover costs related to fuel which can fluctuate greatly. This can be in addition to any other fee, including delivery. | | Marketplace Fee | A fee charged to marketplace users to cover costs related to the regulatory, safety and operational requirements the marketplace must follow. | | Priority Fees | A fee charged to the buyer for faster delivery or service. | | Processing Fee | A fee charged to buyers to cover costs associated with processing an order. | | Regulatory Fee | A fee charged to buyers to cover costs associated with government regulation. | | Shipping Fee | A fee charged to buyers to cover costs associated with shipping or mailing out goods. | ### Card brand fees Here are the different Card Brand Fees sellers can charge buyers using Buyer Charges. Card-Related Fees are regulated by card networks and include: | Name | Description | | --- | --- | | [Card Surcharge Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/surcharge-fees) | A fee to charge buyers to offset the cost of processing that the seller would normally incur. | | [Card Convenience Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/convenience-fees) | A fee to charge buyers for providing a more convenient payment channel. | | [Card Service Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/service-fees) | A fee to charge buyers that only certain MCCs are eligible to charge (specifically in the education or government industry). | | [Rent Surcharge](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/rent-surcharge) | A fee to charge renters for making payments to qualified landlords under the Visa Rent Program. | ## Comparing Buyer charges Please consult your legal counsel if you have questions about a seller's eligibility to use Buyer Charges. Eligibility is determined by card brands and their operating rules. Verifying the seller complies with the fee and surcharge rules listed in [Visa Core Rules and Visa Product and Service Rules](https://usa.visa.com/content/dam/VCOM/download/about-visa/visa-rules-public.pdf) (*section 5.5.1.8 - Credit Card Surcharge Requirements*) is an excellent guideline to confirm if the seller can use buyer charge. See the following for a comparison and questions to help you determine if Buyer Charges are appropriate for your seller's use case. details summary Comparison of Buyer Charges | Name | Environment | Fee Structure | Fee Amount | Card Types | Additional Registration Required | Other Limits | | --- | --- | --- | --- | --- | --- | --- | | [Common Fees](/guides/online-payments/payment-features/buyer-charges/common-fees) | Online or In-Person | Flat or Percent | Similar to the purpose of the fee | Credit or Debit | No | Can't be related to processing payments. | | [Surcharge Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/surcharge-fees) | Online or In-Person | Flat or Percent | Max 3% of transaction | Credit | Yes | Not allowed in all 50 states (consult your legal counsel). | | [Convenience Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/convenience-fees) | Online | Flat | Suggested 3% of avg. transaction | Credit or Debit | No | Seller's primary payment channel must be In-Person. | | [Service Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/service-fees) | Online | Flat or Percent | Suggested 3% of avg. transaction | Credit or Debit | No | Only education and government MMCs. | | [Visa Rent Surcharge](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/rent-surcharge) | Online | Flat or Percent | Max $10 for Debit or 4% for Credit | Credit or Debit | Yes | Only real estate MCCs. | details summary Buyer Charges Questionnaire ### 1) Do you want to offset an operational cost? | | | | | --- | --- | --- | | Yes | [Common Fees](/guides/online-payments/payment-features/buyer-charges/common-fees) | Examples include delivery fees, fuel fees, administrative fees, fuel charges, servicing fees, priority fees, taxes, etc. This fee can't be tied to a cost related to accepting card payments. | | No | Next Question | N/A | ### 2) Are you in the education or government industry? | | | | | --- | --- | --- | | Yes | [Card Service Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/service-fees) | See the following list for eligible MCCs. | | No | Next Question | N/A | Eligible Education and Government MCCs include: | MCC | Description | | --- | --- | | 8211 | Elementary and Secondary Schools | | 8220 | Colleges, Universities, Professional Schools, and Junior Colleges | | 8244 | Business and Secretarial Schools | | 8249 | Vocational and Trade Schools | | 9211 | Court Costs, Including Alimony and Child Support | | 9222 | Fines | | 9311 | Tax Payments | | 9399 | Government Services (Not Elsewhere Classified) | ### 3) Are you collecting rent payments online? | | | | | --- | --- | --- | | Yes | [Card Visa Rent Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/rent-surcharge) | This fee enables sellers to collect fees from buyers on both Debit and Credit cards for rent payments. | | No | Next Question | N/A | ### 4) Is your primary payment channel In-Person Payments? | | | | | --- | --- | --- | | Yes | [Convenience Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/convenience-fees) | Qualified sellers can collect fees on Online payments if it's an alternative to how they primarily accept payments. The fee must be a flat fixed amount. | | No | [Surcharge Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/surcharge-fees) | This fee allows you to collect fees on exclusively credit cards in any environment. The fee can either be a fixed flat fee or fixed percent fee. | ## Buyer charges and the API Once enabled, `Merchants` can include a buyer charge with the [Transfers](/api/transfers/createtransfer) or [Authorizations](/api/authorizations/createauthorization) they create to process transactions and move funds. To include a buyer charge with a transaction, when creating a `Transfer` or `Authorization`, include the `additional_buyer_charges` object to detail what portion of the `amount` should get paid out as a buyer charge. The value passed for a buyer charge will not impact the amount charged to a cardholder. Instead, only `amount` determines how much the buyer gets charged. ### Buyer charges and Payouts Transactions with buyer charges pay out funds [the same way](/guides/platform-payments/seller-payouts) as other transactions in Finix. - Transactions with Buyer Charges can be identified by the `Transfer#additional_buyer_charges` (or `Authorizations#additional_buyer_charges`) fields. - The seller gets paid out `Transfer#amount` (or `Authorization#amount`) minus any fees that were applied to that transaction or configured in the seller's `Fee Profile`. ## Update Merchant to enable Buyer charges Finix Core customers can use a PUT request to enable buyer charges for a `Merchant`. For Finix Flex customers reach out to [Finix Support](/guides/getting-started/support-at-finix/) and request the seller's `Merchant` account be enabled to use Buyer Charges. Complying with card requirements If Buyer Charges are enabled, as the platform, it is your responsibility to ensure every enabled Merchant account complies with card brand rules and applicable legal requirements. Rules and requirements can be found in [Visa Core Rules and Visa Product and Service Rules](https://usa.visa.com/content/dam/VCOM/download/about-visa/visa-rules-public.pdf). ### Body parameters The APIs to update `Merchant` flags are only available for Finix Core customers. If you have additional questions, please reach out to your Finix point of contact or [Finix Support](mailto:support@finix.com). ## Buyer charges and Fee Profiles For accounting purposes, if you plan on categorizing Buyer Charges as fees, we recommend making these changes to the Payout Settings and `fee_profile` of `Merchants`: - Set the Payout Type in Payout Settings to **Net.** For more details, see [Managing Your Sellers and Payouts](/guides/platform-payments/seller-payouts/managing-seller-payouts). - Set the `fixed_fee` on the `fee_profile` to `0`. For more details, see [Collecting Seller Fees](/guides/platform-payments/monetizing-payments/collecting-seller-fees) and [Fee Profiles](/api/fee-profiles). - In the dashboard, update **Per Item** next to **All Card Brands.** - Set `basis_points` on the `fee_profile` to the Buyer Charge you'll pass on to buyers. Use the following equation to calculate `basis_points`. Be sure the entered value is converted into basis points (BPS = Buyer Charge Percentage X 100): Buyer Charge Equation Once calculated, update `basis_points` in [`fee_profiles`](/api/fee-profiles) with the new figure (converted to basis points). Alternatively, in the dashboard, update **Per Item** next to **All Card Brands.** --- # Convenience Fees Source: https://docs.finix.com/guides/online-payments/payment-features/buyer-charges/card-brand-fees/convenience-fees Learn about the requirements and what you can do with Convenience Fee. A convenience fee is a Buyer Charge that can only get passed to buyers when the seller is providing a method of payment (usually internet or over the phone) different from its standard payment channel (historically mail or in-person). ## Requirements Sellers and your integration must meet these requirements to charge Convenience Fees: - The fee is charged only when the seller provides buyers with a method of payment different from its standard payment channel. - The fee can only be charged when processing Online Payments. - The seller must support In-Person Payments. - The buyer must be aware of the fee and its purpose before making a payment. - After the fee gets disclosed, the buyer must have the option to cancel the transaction without any consequences. - The Convenience Fee amount must be the same fixed amount across all card transactions. - The fee must be in the total transaction `amount` . A separate transaction can't be created. - Convenience Fees can't be alongside any other buyer charges. - Convenience Fees can't be charged on a recurring or installment basis. We recommend setting the convenience fee to about 3% of the seller's average transaction. ## Convenience fees with Virtual Terminal You can charge convenience fees using the Virtual Terminal. To do so, navigate to the Virtual Terminal on the Dashboard. ### Step 1: Add Buyer Fees Convenience Fees Buyer Fees - Virtual Terminal 1 ### Step 2: Enter convenience fee amount Convenience Fees Buyer Fees - Virtual Terminal 2 ### Step 3: Confirm convenience fee amount Convenience Fees Buyer Fees - Virtual Terminal 3 After you confirm the subtotal and convenience fee amount, you can then process the payment. ## Convenience fees with Payment Links When you create a Payment Link, you have the option to add a convenience fee. ### Step 1: Add Buyer Fees Convenience Fees Buyer Fees - Payment Links 1 ### Step 2: Enter convenience fees Convenience Fees Buyer Fees - Payment Links 2 ### Step 3. Buyer sees convenience fee amount Convenience Fees Buyer Fees - Payment Links 3 ## Convenience fees using Finix API - online Payments Include the convenience fee in `convenience_amount` when creating a `Transfer` or an `Authorization`. See the following for an example where a vehicle is getting paid for online instead of in-person or via check. - The transaction is for a $5200 car payment with a fixed Convenience Fee of $150. - The fee is included in `tags` for tracking purposes. Example API Definition --- # Card Brand Fees Source: https://docs.finix.com/guides/online-payments/payment-features/buyer-charges/card-brand-fees Learn about the requirements and what you can do with Card Brand Fees. Card Brand Fees are [buyer charges](/guides/online-payments/payment-features/buyer-charges), regulated by card brands, that are available to sellers that can't use Common Fees. Card Brand Fees include: | Fee Type | Description | | --- | --- | | [Convenience Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/convenience-fees) | A fee to charge buyers for providing a more convenient payment channel. Convenience fees can only get charged to buyers when the seller is providing a method of payment (usually internet or over the phone) different from its standard payment channel (historically mail or in-person). | | [Service Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/service-fees) | A fee to charge buyers that only certain MCCs are eligible to charge (specifically in the education or government industry). | | [Surcharge Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/surcharge-fees) | A fee to charge buyers to offset the cost of processing that the seller would normally incur. | | [Rent Surcharge](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/rent-surcharge) | A fee to charge renters for making payments to qualified landlords under the Visa Rent Program. | These Card Brand Fees get used for various reasons depending on the transaction: - Any fee that gets charged must fit into one of the categories above. - Sellers can only pass one Buyer Charge per transaction (e.g., sellers can’t pass a Convenience Fee and a Rental Fee in a single transaction). Sellers collect the funds from Buyer Charges as a part of [their payout](/guides/platform-payments/seller-payouts). --- # Rent Surcharge Source: https://docs.finix.com/guides/online-payments/payment-features/buyer-charges/card-brand-fees/rent-surcharge Learn about the requirements and what you can do with the Rent Surcharge. The Rent Surcharge is available to sellers to charge renters a fee for making payments to qualified landlords under the Visa Rent Payment Program. ## Requirements Through the [Visa Rent Payment Program](https://usa.visa.com/dam/VCOM/download/about-visa/visa-rules-public.pdf) (section 5.8.21 - Visa Rent Payment Program), Visa allows landlords to collect a fee from renters who use their credit or debit cards to pay for rent in an online environment. `Merchants` must be registered for the [Visa Rent Payment Program](https://usa.visa.com/dam/VCOM/download/about-visa/visa-rules-public.pdf) (section 5.8.21 - Visa Rent Payment Program) through Finix. To register, reach out to your Finix Point of Contact or Finix Support. Please allow up to 35 days for registration to be completed. Please note each individual `Merchant` account needs to be registered before charging a Rent Surcharge. Sellers and your integration must meet these requirements to charge a Rent Surcharge: - The Rent Surcharge needs to be clearly displayed to the buyer before they approve a transaction. - If the transaction is with a debit card, the Rent Surcharge can't be greater than $10. - If the transaction is with a credit card, the fee needs to follow the same requirements as [Surcharge Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/surcharge-fees). - The buyer must be aware of the fee and its purpose before making a payment. - After the fee gets disclosed, the buyer must have the option to cancel the transaction without any consequences. The Payment `Instrument#card_type` field details if a debit (`DEBIT`) or credit card (`CREDIT`) was used. ## Using the API Include the Rent Surcharge in `rent_surcharge_amount` when creating a `Transfer` or an `Authorization`. Use `rent_surcharge_amount` to mark which portion of `Transfer#amount` is a Rent Surcharge. See the following for an example where: - The transaction is for a $10,000 in rent with a Rent Surcharge of $10. - The fee is included in `tags` for tracking purposes. Example API Definition --- # Service Fees Source: https://docs.finix.com/guides/online-payments/payment-features/buyer-charges/card-brand-fees/service-fees Learn about the requirements and what you can do with Service Fee. Service fees are available to sellers in the education or government industry to help offset the cost of processing payments. ## Requirements Service fees are only available to eligible Merchant Category Codes (MCCs) under Education and Government. - The seller must be enrolled in the appropriate programs for each card network: - [Visa Government and Education Payment Program](https://usa.visa.com/support/small-business/regulations-fees.html) - [Mastercard Convenience Fee Program](https://www.mastercard.us/en-us/business/overview.html) - Eligible sellers can use a third party to charge service fees. This includes your own platform and application. - The buyer must be aware of the fee and its purpose before making a payment. - After the fee gets disclosed, the buyer must have the option to cancel the transaction without any consequences. - The fee must be similar to the sum of all costs of accepting a card (suggested 3%). Sellers who are not eligible and can't join the card network programs can use [Convenience Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/convenience-fees) as an alternative. ## Recommended Service Fees Finix recommends the following service fees. ### MCCs excluding MCC 9311 For MCCs **other than 9311 - Tax Payments**, we recommend setting the service fee to about 3% of the seller's average transaction. ### MCC 9311 - Tax Payments For **MCC 9311 - Tax Payments**, cardholders must be charged a fixed, flat fee, no greater than $10 per transaction. Compliance Deadline: 23 January 2027 Merchants processing tax payments under MCC 9311 must comply with this fee cap by **23 January 2027**. ## Eligible MCCs MCCs that are eligible to use Service Fees include: | Code | Description | | --- | --- | | 9211 | Court Costs, including Alimony and Child Support | | 9222 | Fines | | 9223 | (MasterCard only) - Bail and Bond Payments | | 9311 | Tax Payments | | 9399 | Government Services (Not Elsewhere Classified) | | 8211 | Elementary and Secondary Schools | | 8220 | Colleges, Junior Colleges, Universities, and Professional Schools | | 8244 | (Visa only) - Business and Secretarial Schools | | 8249 | (Visa only) - Vocational Schools and Trade Schools | | 8299 | (Mastercard only) - Schools and Educational Services (Not Elsewhere Classified) | ## Using the API Include the service fee in `convenience_amount` when creating a `Transfer` or an `Authorization`. See the following for an example where a $5200 delivery has a service fee: - The transaction is for a $5200 delivery with a Convenience Fee of $150. - The fee is included in `tags` for tracking purposes. Example API Definition --- # Surcharge Fees Source: https://docs.finix.com/guides/online-payments/payment-features/buyer-charges/card-brand-fees/surcharge-fees Learn about the requirements and what you can do with Surcharge Fees. Surcharge fees are available to sellers to help cover the cost of processing payments in any environment. For more details about surcharge fees, see the following articles from Visa and Mastercard: [Visa Surcharge FAQ](https://usa.visa.com/content/dam/VCOM/global/support-legal/documents/merchant-surcharging-qa-for-web.pdf) and [Mastercard Surcharge FAQ](https://www.mastercard.us/content/dam/public/mastercardcom/na/us/en/documents/Merchant_Surcharge_FAQ.pdf). ## Requirements `Merchants` must be enabled by Finix to process surcharge fees. Reach out to your Finix Point of Contact or Finix Support at least 35 days in advance before processing surcharge fees. Please note each individual `Merchant` account needs to be registered before they can process surcharge fees. Sellers and your integration must meet these requirements to charge Surcharge Fees: - Limit surcharging to credit cards only (debit cards and prepaid cards cannot be surcharged). - The surcharge fee must be included in the `Transfer#amount` or `Authorization#amount` you include when creating transaction. - The fee must be a percent. - The amount or percent you set must be the same for all transactions that include a surcharge fee. - The surcharge fee can't exceed 3% of the transaction or your total average cost of credit card acceptance. - The buyer must be aware of the fee and its purpose before making a payment. - After the fee gets disclosed, the buyer must have the option to cancel the transaction without any consequences. - Controls must be in place so surcharges are only applied in states where allowed. The `Payment Instrument#card_type` field details if a debit (`DEBIT`) or credit card (`CREDIT`) was used. ## Refunds for surcharges When refunding a transaction that includes a surcharge, the surcharge must also be refunded to the cardholder per card brand rules. For a full refund, the entire surcharge amount must be returned. For a partial refund, a proportional portion of the original surcharge must be refunded. Learn more about [how to manage refunds](/guides/after-the-payment/refunds). ## Surcharging with the Virtual Terminal You can surcharge using the Virtual Terminal. To do so, navigate to the Virtual Terminal on the Dashboard. ### Step 1: Add Buyer Fees Surcharging Buyer Fees - Virtual Terminal 1 ### Step 2: Enter surcharge percentage Surcharging Buyer Fees - Virtual Terminal 2 You cannot surcharge more than 3% on the Virtual Terminal. The surcharge option only appears if your merchant account is enabled for surcharging. If you have additional questions, email our support team. Finix will always floor the rounding. For example, if you enter 3%, it may come out to be lower percentage for smaller dollar amounts. ### Step 3: Confirm surcharge amount Surcharging Buyer Fees - Virtual Terminal 3 After you confirm surcharge amount, you can then process the payment. Surcharging Buyer Fees - Virtual Terminal Confirmation Surcharging Buyer Fees - Virtual Terminal - Payment Page - Surcharge Amount A surcharge amount will not appear if the card you've chosen is a debit card. ## Surcharging with Payment Links When you create a Payment Link, you have the option to add a surcharge if the merchant is enabled for it. ### Step 1: Add Buyer Fees Surcharging Buyer Fees - Payment Links 1 ### Step 2: Enter surcharge amount and confirm Surcharging Buyer Fees - Payment Links 2 Finix will always floor the rounding. For example, if you enter 3%, it may come out to be lower percentage for smaller dollar amounts. ### Step 3. Buyer sees surcharge amount Surcharging Buyer Fees - Payment Links 3 When you send the payment link to your buyer, they'll see a notice that paying with a credit card will get surcharged. ## Surcharging using Finix API - online Payments When making a transaction with a surcharge fee, include the surcharge fee in `surcharge_amount` when creating a `Transfer` or an `Authorization`. See the following for an example of paying a $100 parking ticket with a $7 (7%) surcharge fee. Before including the `surcharge_amount` verify the buyer's Payment `Instrument#card_type` is `CREDIT`. ```shell curl -i -X POST \ -u USxxxx:xyz-123 \ https://finix.sandbox-payments-api.com/transfers \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "additional_buyer_charges": { "surcharge_amount": 700 }, "amount": 10000, "currency": "USD", "merchant": "MU3PLsrxmHcKRKhSoHDJ2FPP", "source": "PImn9EAtceoUcBoXG2n73LY9" }' ``` ## Surcharging using Finix API - In-Person Payments You can enable buyer surcharge fees for your merchants for in-person payments. You will need to use the same API call as for online payments. --- # In-Person Payments Source: https://docs.finix.com/guides/in-person-payments Elevate your point of sale with in-person payments powered by Finix: seamless, secure, and built to scale. In-Person Payments Hero Accept in-person payments with Finix’s flexible, platform-ready solution, built for custom POS flows or turnkey hardware experiences. - **Flexible integrations** - Power your POS with our APIs or launch fast with our Standalone Terminals. - **Modern payment methods** - Accept chip, tap, swipe, mobile wallets, and contactless payments across supported devices. - **Security first:** Protect sensitive payment data with our PCI-compliant tokenization system. ## Choose your device Start by picking the terminal that fits your business, then order it from the Device Store. Select Your Device Compare Finix-supported terminals by use case, connectivity, and integration type. Order Devices Browse, purchase, and track payment terminals through the Device Store in the Finix Dashboard. ## Choose your integration Finix offers multiple ways to accept in-person payments. Find the option that fits your use case. ### No-Code Start taking payments right away, with no development required. Standalone Terminals Process payments on a Finix terminal right out of the box. This is the fastest way to start accepting in-person payments. Finix Checkout App Take payments on your iPhone or Android device with a PAX D135 card reader, manual entry, or Payment Links. Tap to Pay on iPhone Accept contactless payments using only your iPhone. No card reader required. ### Custom integration Build in-person payments into your own software using Finix's APIs and SDKs. Not sure which option to choose? See [Building Your Integration](/guides/in-person-payments/building-your-integration) for a comparison. POS Integration Connect Finix terminals to your point of sale using the Finix API. Mobile Integration Accept payments in your iOS or Android app with the PAX D135 and Finix's mobile SDKs. Deploy Apps to Your Terminals Run your own Android app directly on Finix-supported PAX terminals with the Device Reader SDK. Device API Reference Explore the Devices endpoints for activating, updating, and monitoring terminals. ## Learn more Device Capabilities Configure tipping, manual entry, receipts, and other features on your terminals. Managing Your Devices Monitor the health, connectivity, and status of your device fleet. Testing Your Integration Validate your integration end to end in Sandbox with test cards and approved test amounts. Receipts for In-Person Payments Deliver print, email, or SMS receipts from your terminals. Troubleshooting Your Terminal Resolve common issues with battery, connectivity, printing, and power. --- # Design Your Custom Integration Source: https://docs.finix.com/guides/in-person-payments/building-your-integration Finix offers two integration options for in-person payments: ## POS integration - Integrate with your existing point-of-sale system using the Finix API. - Process payments directly through Finix with full control over the transaction flow. - Ideal for businesses with established POS systems looking for a flexible, API-first approach. - Supports many payment terminals and processing scenarios. In-person API integration diagram ## Mobile integration - Use the [Finix mobile SDKs](/guides/in-person-payments/building-your-integration/mobile-integration) to integrate with supported payment terminals. - Get started quickly with minimal development effort. - Delivers a reliable payment experience across all supported devices. In-person mobile SDK integration diagram Don't want to build your own integration? The Finix [standalone terminals](/guides/in-person-payments/standalone-terminals) are a simple option for accepting in-person payments without custom development. ## Learn more POS Integration Build out your in-person payments integration using Finix's API. Mobile Integration Build out your in-person payments integration using Finix's mobile SDK. Deploy Apps to Your Terminals Run your own Android app directly on Finix-supported PAX terminals with the Device Reader SDK. Testing Your Integration Validate your integration end to end in Sandbox with test cards and approved test amounts. --- # Testing Your In-Person Integration Source: https://docs.finix.com/guides/in-person-payments/building-your-integration/testing-your-integration Before testing, confirm you have everything needed to validate your integration end to end: - **Finix Sandbox Environment** - Your testing environment for simulating transactions without using real money. - **Finix Payment Terminal** - A physical device connected to your Sandbox account for processing test payments. - **Finix Test Card** - Simulates different payment scenarios, including approvals and declines. If you’re missing something, contact your Finix point of contact to get set up. ## Testing In-Person Payments ### `DUMMY_V1` On the `DUMMY_V1` Processor, you can conduct the following tests on Sales to confirm the integration is processing payments as expected: | Amount | Expected Response | | --- | --- | | `499` | `APPROVED` | | `6299` | `APPROVED` | | `51` | `GENERIC_DECLINE` | | `1` | `CALL_ISSUER` | | `3` | `RESTRICTED_CARD` | | `260` | `INVALID_TRANSACTION` | | `4` | `PICK_UP_CARD` | | `40` | `RESTRICTED_CARD` | | `41` | `PICK_UP_CARD` | | `57` | `TRANSACTION_NOT_PERMITTED` | | `252` | `INVALID_AMOUNT` | | `253` | `INVALID_ACCOUNT_NUMBER` | | `267` | `EXPIRED_CARD` | | `269` | `PICK_UP_CARD` | | `500` | `APPROVED` | ## Next steps Managing Your Devices Monitor device health and connectivity as you go live. Troubleshooting Your Terminal Resolve common issues with battery, connectivity, printing, and power. --- # App Requirements Source: https://docs.finix.com/guides/in-person-payments/deploy-apps-terminals/app-requirements Make sure your Android app meets these requirements before deploying it to Finix-supported PAX terminals. ## Supported terminals You can deploy your own apps to the following Finix-supported terminals: - [PAX A800](/guides/in-person-payments/select-your-device/pax-a800) - [PAX A920 Pro](/guides/in-person-payments/select-your-device/pax-a920-pro) - [PAX A35](/guides/in-person-payments/select-your-device/pax-a35) - [PAX A3700](/guides/in-person-payments/select-your-device/pax-a3700) - [PAX IM30](/guides/in-person-payments/select-your-device/pax-im30) See [each device page](/guides/in-person-payments/select-your-device) for developer specifications such as the Android version and screen resolution. ## Supported Android Version The SDK has a minSdkVersion of `Android API Level 26 (Android 8.0)+`. ## Packaging and signing - Build your app as a standard Android APK targeting the Android version of your terminal models. - Each release must have a unique `versionCode`. Terminals only move forward: to replace a release, publish a higher version. - Apps are signed and distributed through PAX's app management platform. You do not distribute builds to production terminals directly. ## Platform differences from standard Android hardware PAX terminals are payment devices first, so they differ from consumer Android hardware: - **No Google Play**: Apps are distributed through PAX's app management platform, not the Play Store. Do not depend on the Play Store for installs or updates. - **Google Mobile Services**: Services such as Google Maps and Firebase may be limited or unavailable. Verify any Google-dependent functionality on a debug device before you build around it. - **No production debugging**: Android Debug Bridge (`adb`) is only available on debug devices purchased from PAX. Production terminals cannot sideload apps or attach a debugger. For more information, see [Testing Your App](/guides/in-person-payments/deploy-apps-terminals/quickstart#testing-your-app). ## Payment processing requirements - Use the [Finix Android SDK for PAX Device Readers](/guides/in-person-payments/deploy-apps-terminals/quickstart) for all card processing. Your app must not read, store, or transmit card data itself. - **Remote key injection**: The Finix Android SDK for PAX Device Readers uses key slot 3 in Sandbox and key slot 4 in Production. If your app uses remote key injection, avoid using either of these key slots. ## Questions If you're unsure whether your app meets these requirements, reach out to your Finix point of contact or email [support@finix.com](mailto:support@finix.com). --- # Creating a Push Task for Your Application Source: https://docs.finix.com/guides/in-person-payments/deploy-apps-terminals/creating-a-push-task A push task is a job that PAX's terminal management system (TMS) sends to a terminal to execute. The TMS pushes the instruction directly to the device. Push tasks can: - Deploy a new payment application to the device. - Send a software or firmware update to the terminal. To push your app, first create a dynamic group of terminals, then push the app to that group. ## 1. Open Group Management Navigate to **Group Management** in the nav bar, under the intended reseller. Reseller nav bar with an arrow pointing to the Group Management item ## 2. Add a dynamic group From the **Group List** page, click **+** and select **Add Dynamic Group**. Group List page with an arrow pointing to the + button and the Add Dynamic Group option highlighted ## 3. Configure the group In the **Create Dynamic Group** dialog, enter a **Group Name**, then configure the following and click **OK**: - **Model**: The models of devices that will be supported. - **Contain sub-reseller terminals**: Checked. - **Activate group**: Checked. Create Dynamic Group dialog with the Model field, Contain sub-reseller terminals checkbox, and Activate group checkbox highlighted ## 4. Open the Push Task tab Select the dynamic group you created, go to the **Push Task** tab, then click **+ APP**. Group Detail page with arrows pointing to the Push Task tab and the + APP button ## 5. Add your app In the **Add Push App** dialog, search for your app, select it, and click **OK** to push it to every terminal in the group. Add Push App dialog with an app selected from the search results --- # Deploying Your App Source: https://docs.finix.com/guides/in-person-payments/deploy-apps-terminals/deploying-your-app Once your app is built and tested, deploy it to your production terminals through PAX's terminal management system (TMS). ## Roles and responsibilities | Role | Responsibilities | | --- | --- | | You | Build and test your app, upload your release, and choose which terminals receive it. | | PAX | Signs your app and provides the TMS infrastructure that distributes it to terminals. | | Finix | Registers your team for TMS access under the Finix sub-reseller account and associates your terminals with your fleet. | ## 1. Register for TMS access Finix grants all TMS access through its sub-reseller structure: 1. Send Finix a list of the users who need access to PAX's TMS product. To initiate this process, reach out to your Finix point of contact or email [support@finix.com](mailto:support@finix.com). 2. Finix invites each user to be registered under the Finix sub-reseller account. If you already have an existing PAX account (for example, from a prior relationship), you can maintain that account separately. Finix-related terminals must be managed exclusively under the Finix sub-reseller account. ## 2. Upload your app Upload your release build through PAX's PAXSTORE developer marketplace. PAX reviews and signs the app before it can be installed on terminals. Make sure your app meets the [App Requirements](/guides/in-person-payments/deploy-apps-terminals/app-requirements) before uploading. For the full click-through, see the [Upload Your App to PAXSTORE Walkthrough](/guides/in-person-payments/deploy-apps-terminals/upload-app-pax-walkthrough). ## 3. Distribute to your terminals Distribute the app to the terminals in your fleet through TMS. Terminals install the app the next time they check in with TMS, so allow time for the rollout to reach every device. ## Updating your app To update your app, upload a new release with a higher `versionCode` and distribute it the same way. Terminals only move forward across versions. To roll back a bad release, publish a new build with a higher version number. Managing Your Devices Monitor the health, connectivity, and status of your device fleet. Device API Reference Explore the Devices endpoints for device connection details and metrics. --- # Enabling P2PE on Debug Devices Source: https://docs.finix.com/guides/in-person-payments/deploy-apps-terminals/enabling-p2pe-debug-terminals The Finix Android SDK for PAX Device Readers uses point-to-point encryption (P2PE), so every device must have an encryption key injected before it can process transactions. Production devices receive this key automatically over the air. Debug devices, however, require manual key injection using the steps below. The screenshots in this guide were taken on a PAX A800 payment terminal, but the process is identical across all supported PAX models. ## 1. Open the Settings app From the home screen, locate and open the **Settings** app. You may be prompted for a passcode. Each PAX model uses a different passcode, so try the following combinations, in order, until one works: - `pax9876@@` - `Pax9876@@` - `9876@@` - `9876` `pax9876@@` is the most common passcode. PAX home screen with Settings app ## 2. Open Security settings Scroll down the Settings page and select **Security**. PAX A800 Settings page with Security option highlighted ## 3. Start RKI download Select **RKI Download**. PAX A800 Security page with RKI Download option ## 4. Select key injection On the RKI screen, select **Key Injection**. PAX A800 RKI screen with Key Injection option ## 5. Select Internal PED When prompted to select a pinpad, choose **1. InternalPED**. PAX A800 pinpad selection screen showing InternalPED option ## 6. Enter the connection details and start the injection Enter the following connection details, then select **Start Key Injection**: | Field | Value | | --- | --- | | Host | `rkilt.pax.us` | | Port | `33619` | PAX A800 RKI connection details entry screen ## 7. Confirm success If the key is injected correctly, a **Download Success!** screen appears. If you do not see this confirmation, contact [customer support](mailto:support@finix.com) for assistance. PAX A800 RKI Download Success confirmation screen --- # Deploy Apps to Your Terminals Source: https://docs.finix.com/guides/in-person-payments/deploy-apps-terminals Run your Android app directly on Finix-supported PAX terminals to control the entire checkout experience. Android app built with the Finix Android SDK for PAX Device Readers running on a PAX terminal ## Overview With the Finix Android SDK for PAX Device Readers, you can deploy your Android application onto the payment terminal. No separate POS device or card reader is required. The SDK handles card processing on the terminal while your app owns the rest of the experience. Deploying your app to a terminal provides the following advantages: - **A single device at checkout**: Your app and payment processing run on the same terminal. - **Full control of the experience**: Design the ordering, checkout, and post-payment flows around your business. - **Support across PAX smart terminals**: Deploy to Finix-supported devices such as the PAX A800, A920 Pro, A35, A3700, and IM30. ## How it works To deploy your app, follow these steps: 1. **Build**: Create your Android app with the [Finix Android SDK for PAX Device Readers](/guides/in-person-payments/deploy-apps-terminals/quickstart) handling card processing. 2. **Test**: Validate your app in Sandbox on [debug devices from PAX](/guides/in-person-payments/deploy-apps-terminals/quickstart#testing-your-app). 3. **Meet the requirements**: Confirm your app satisfies the [App Requirements](/guides/in-person-payments/deploy-apps-terminals/app-requirements) for packaging, permissions, and payment processing. 4. **Deploy**: [Distribute your app](/guides/in-person-payments/deploy-apps-terminals/deploying-your-app) to production terminals through PAX's terminal management system. 5. **Monitor**: Track the health and connectivity of your fleet with [device management](/guides/in-person-payments/managing-your-devices). Development Devices To develop and test your app, you need debug devices purchased directly from PAX, and Finix must register your team for TMS access. To get started, reach out to your Finix point of contact or email [support@finix.com](mailto:support@finix.com). ## Learn More Quickstart Build in-person payment flows on PAX terminals with the Device Reader SDK. App Requirements Review the packaging, platform, and payment processing requirements for terminal apps. Deploying Your App Register for TMS access, distribute your app, and roll out updates to your fleet. Device Reader Demo App Explore a sample Android app built with the Finix Android SDK for PAX Device Readers. Devices Compare Finix-supported terminals by use case, connectivity, and integration type. --- # Device Reader SDK Integration Prerequisites Source: https://docs.finix.com/guides/in-person-payments/deploy-apps-terminals/integration-prerequisites Before integrating the Finix Android SDK for PAX Device Readers, complete the following one-time setup. These steps register your PAX developer account, establish your API credentials, and create your Device resource in Finix. ## Prerequisites - You are registered as a [developer](https://developer.pax.us/) with PAX. ## 1. Choose the credential type The SDK supports either `ROLE_PARTNER` or `ROLE_MERCHANT` credentials. Use `ROLE_MERCHANT` credentials to scope your app to a single Merchant. Use `ROLE_PARTNER` credentials if your app processes payments across multiple devices or Merchants. `ROLE_PARTNER` credentials are required for [Split Transactions](/guides/online-payments/payment-features/split-transactions). ### Creating ROLE_MERCHANT credentials Create a User with `role: ROLE_MERCHANT`. ```shell curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/users \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "role": "ROLE_MERCHANT", "identity_id": "ID6YeRojM2ppNkPt4mP8ExNH" }' ``` You can use the credentials across multiple devices as long as the devices are associated with the same Merchant. ### Creating ROLE_PARTNER credentials To create `ROLE_PARTNER` credentials: 1. Log in to the [Finix Dashboard](https://live.payments-dashboard.com/Login). 2. Select the environment for which you would like to create the API credentials (Sandbox or Live). 3. In the bottom left-hand corner, click **Developer**. 4. From the **API Keys** tab, click **Create API Key**. Create API Key ## 2. Creating a Device Creating a Device resource can be done either via the Finix Dashboard or via API. The steps below use the API. Create a Device under the Merchant provisioned to process in-person payments. Include the `model` of the payment terminal you will be using to process cards. Set `integration_mode` to `SDK` to designate that this Device uses the Finix Android SDK for PAX Device Readers. For more details about the payment terminals available, see our [available devices](/guides/in-person-payments/select-your-device). ```shell Request curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/merchants/MUwfZPNW3r4EqLMzwgr6txw4/devices \ -H 'Content-Type: application/json' \ -d '{ "description": "Cashier Three", "model": "PAX_A800", "name": "PAX_A800 Finix Android SDK for PAX Device Readers", "integration_mode": "SDK", "serial_number": "19046260947" }' ``` ```json Response { "id": "DVxcL2fiBdt9frYCKAbZikZK", "created_at": "2025-05-21T19:01:32.000581Z", "updated_at": "2025-05-21T19:01:32.000581Z", "configuration_details": null, "description": "Cashier Three", "enabled": false, "idle_message": null, "integration_mode": "SDK", "merchant": "MU7noQ1wdgdAeAfymw2rfBMq", "model": "PAX_A800", "name": "PAX_A800 Finix Android SDK for PAX Device Readers", "serial_number": "19046260947", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/devices/DVxcL2fiBdt9frYCKAbZikZK" }, "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MU7noQ1wdgdAeAfymw2rfBMq" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/transfers" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/authorizations" } } } ``` --- # PAX Device Reader SDK Quickstart Source: https://docs.finix.com/guides/in-person-payments/deploy-apps-terminals/quickstart Use the Finix Android SDK for PAX Device Readers to integrate PAX Android-based terminals into your app and accept in-person payments. This guide covers SDK installation, initialization, and processing your first transaction. Prerequisites Before starting, complete the [Integration Prerequisites](/guides/in-person-payments/deploy-apps-terminals/integration-prerequisites) to set up your PAX developer account, credentials, and a Device resource. ## 1. SDK setup ### Installation Add the dependency to your Gradle file. See [Maven Central](https://central.sonatype.com/artifact/com.finix/pax-device-reader-sdk) or [MVN Repository](https://mvnrepository.com/artifact/com.finix/pax-device-reader-sdk) for the latest version. ```kotlin implementation("com.finix:pax-device-reader-sdk:0.3.0") ``` ### Initialization Add permissions to the AndroidManifest to interact with the mPOS device via Bluetooth. ```xml ``` To interact with the device, first register and create it. ```kotlin Initialize fun VendorBindings.register(driver: VendorTerminalDriver) fun FinixTerminalSDK.createDevice( activity: Activity, merchantData: MerchantData, options: TerminalOptions? = null, ) ``` - `driver`: The type of device (e.g., `PaxTerminalDriver`) - `activity`: Android activity - `merchantData`: Merchant data class containing data specific to your merchant - `options`: Optional data that can affect transaction processing ```kotlin class MerchantData( // Merchant Id from Finix starting with MUxxxx val merchantId: String, // Device ID - device registers with Finix, starting with DVxxxx val deviceId: String, // Sandbox or Production val env: Environment = Environment.SB, // ROLE_MERCHANT or ROLE_PARTNER UserId val userId: String, // ROLE_MERCHANT or ROLE_PARTNER password val password: String ) Example : val merchantData = MerchantData( merchantId = "MUxxxxxx", deviceId = "DVxxxxx", userId = "USxxxxxxxxx", password = "" ) ``` ### Remote key injection If your app uses remote key injection, avoid the key slots reserved by the Finix Android SDK for PAX Device Readers. For more information, see [App Requirements](/guides/in-person-payments/deploy-apps-terminals/app-requirements). ## 2. Starting a transaction Call `startTransaction()` to prompt the device to accept card input (swipe, tap, or insert). Use the returned `TransactionHandle` to track updates during the transaction or cancel it. ```kotlin Start Transaction fun startTransaction( request: TransactionRequest ): TransactionHandle data class TransactionRequest( val amount: Long, val transactionType: TransactionType, val splitTransfers: List? = null, val tags: Map? = null, val buyerIdentityId: String? = null, val tipAmount: Long = 0L, val surchargeAmount: Long = 0L, val idempotencyId: String? = null, val disabledCardEntryMethods: Set = emptySet(), val timeoutSeconds: Int = 30 ) interface TransactionHandle( val id: String val updates: Flow suspend fun cancel(): Result ) sealed class TransactionUpdate( data class Processing(val step: TransactionStep) : TransactionUpdate() data class Success(val result: TransactionResult) : TransactionUpdate() data class Error(val result: TransactionResult, val failureType: CardEntryFailureType) : TransactionUpdate() data class Retry( val disabledCardEntryMethods: Set, val failureType: CardEntryFailureType, val cardReadMethod: CardReadMethod ) : TransactionUpdate() ) enum class TransactionStep { INITIALIZING, AWAITING_CARD, READING_CARD, CARD_READ_COMPLETE, AUTHORIZE_CARD, PROCESSING, SENT_TO_SERVER } ``` ## 3. Referenced Refunds Refund a previously successful transaction using the `initiateReferencedRefund` function. ```kotlin Referenced Refund fun initiateReferencedRefund( request: ReferencedRefundRequest, ) data class ReferencedRefundRequest( val amount: Long, // Must be less than or equal to the original transfer amount val transferId: String, // Unique ID of the transfer beginning with TR val tags: Map? = null ) ``` ## 4. Signature upload When a transaction succeeds, a signature upload can be performed if `TransactionResult.signaturePending` in `TransactionUpdate.Success` is true. Your app should capture a signature from the user and call `uploadSignature`. ```kotlin Signature Upload fun uploadSignature( // Base64 encoded png of the signature pngEncodedBase64: String, // traceId of the successful transaction, found in TransactionResult traceId: String, ) ``` ## Testing your app To develop and test your app on PAX devices, you will need to purchase debug devices directly from PAX. Debug devices allow apps to be installed directly from Android Studio but cannot be used in production. You can order debug devices through PAX's developer [account](https://developer.pax.us/). Debug devices may have an extended delivery time of 6-8 weeks depending on inventory. ### Finix Device Reader sample app See the [sample app](https://github.com/finix-payments/finix-pax-device-reader-android-sdk-demo-app) for an example integration. If you encounter issues while using the SDK, reach out to the Finix Support Team at [support@finix.com](mailto:support@finix.com). ## Next steps When your app is built and tested, deploy it to your production terminals. App Requirements Review the packaging, platform, and payment processing requirements for terminal apps. Deploying Your App Register for TMS access, distribute your app, and roll out updates to your fleet. Device Reader Demo App Explore a sample Android app built with the Finix Android SDK for PAX Device Readers. --- # Upload Your App to PAXSTORE Walkthrough Source: https://docs.finix.com/guides/in-person-payments/deploy-apps-terminals/upload-app-pax-walkthrough This walkthrough covers how to upload your Android app to PAX's PAXSTORE developer marketplace. PAX reviews and signs your app before it can be distributed to terminals through TMS. Prerequisites You must be registered as a [PAX developer](https://developer.pax.us/) and have access to the PAXSTORE marketplace before starting. See [Deploying Your App](/guides/in-person-payments/deploy-apps-terminals/deploying-your-app) for how Finix grants TMS access. Confirm your build meets the [App Requirements](/guides/in-person-payments/deploy-apps-terminals/app-requirements) before uploading. ## 1. Open the Developer Center From the marketplace list, select the PAXSTORE marketplace to open the Developer Center. Marketplace List with an arrow pointing to the PAXSTORE developer marketplace icon ## 2. Create a new app From the **App List** page, click **+ NEW APP**. App List page with an arrow pointing to the NEW APP button ## 3. Name your app In the **Create App** dialog, enter an **App Name** (64 characters or fewer) and click **OK**. Create App dialog with an App Name field filled in ## 4. Add a new app version PAXSTORE creates the app shell and takes you to the **App Detail** page. Select **Version Management**, then click **+ NEW VERSION** to start uploading a build. App Detail page with an arrow pointing to the NEW VERSION button under Version Management ## 5. Upload your app package Upload your build. The package must be under 350MB. Upload App Package screen prompting the user to click to upload an app file Wait for the upload to finish. A progress bar tracks the upload while the file transfers. Upload App Package screen showing a file uploading with a progress bar ## 6. Fill out the app details Once the package finishes processing, PAXSTORE reads details like file size, version, OS, and package name directly from the build. Complete the remaining required fields. App Detail form showing the App Package summary and fields for App Icon, Business Category, Model, App Name, and Short Description ## 7. Add screenshots and submit for approval Scroll down and provide at least 3 Screenshots (required). A Featured Image and Promotional Video are optional. When you're ready, click **SUBMIT FOR APPROVAL**. App Detail form with Screenshots, Featured Image, and Promotional Video fields, and an arrow pointing to the SUBMIT FOR APPROVAL button PAX reviews and signs your app before it becomes available to distribute. Once it's approved, you can push it to the terminals in your fleet through TMS. See [Deploying Your App](/guides/in-person-payments/deploy-apps-terminals/deploying-your-app) for the distribution steps. --- # Device Idle Screen Source: https://docs.finix.com/guides/in-person-payments/device-capabilities/device-idle-screen By default, Finix terminals display a standard welcome screen when idle. You can replace the default idle screen image with your own logo or image using the Finix Dashboard or API. Example device idle screen on A800 Terminal ## Using the Finix Dashboard You can replace the default idle screen image on the Finix Dashboard. 1. From the **Device Management** screen, click the device you want to update from the device list. Device management list page 1. From the device details screen, click **Edit** in the **Idle Screen** section. Device details page - edit idle screen 1. In the **Update Idle Screen** modal, upload your idle screen image. Optionally provide an idle message to display along with the idle screen image. Device details page - update idle screen modal The next time the device goes idle, your idle screen image displays instead of the default idle screen. To reset the idle screen to the default, click **Reset** from the **Update Idle Screen** modal. ## Using the API To replace the default idle screen image using the API, you must: 1. Create a File resource. 2. Upload the idle image to the File resource. 3. Verify the image file is approved. 4. Update the Device resource to use the idle image. Image file vs. the File resource Your image file is not the same as a File resource. [Create a File resource](#1-create-a-file-resource) first to obtain an ID, then use that ID to upload your image file to it. ### 1. Create a File resource Send a POST /files request to create a File resource. In the request, include the following fields: - `linked_to`: The Merchant `id`. - `type`: Set to `DEVICE_IDLE_IMAGE`. - `display_name`: A human-readable name for the File. ```shell Create a File resource for device idle image curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/files \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "display_name": "Custom device idle image", "linked_to": "MUvWVhLpLj9w7kV1EXA7yvzc", "type": "DEVICE_IDLE_IMAGE" }' ``` A successful request returns a `201 Created` status with the response body containing the newly created File resource. The `REQUIRES_UPLOAD` status indicates that the image upload step is still pending. Save the resource `id` for the next step. ```json { "id" : "FILE_eUN3CgqaEiYS84QhrDy42T", "status" : "REQUIRES_UPLOAD", "created_at" : "2026-09-16T22:58:39.586982Z", "updated_at" : "2026-09-16T22:58:39.586982Z", "linked_type" : "MERCHANT", "linked_to" : "MUvWVhLpLj9w7kV1EXA7yvzc", "extension" : null, "display_name" : "Custom device idle image", "type" : "DEVICE_IDLE_IMAGE", "platform_id" : "PLoMxXWbqwEMT5N1upSaNUbJ", "application_id" : "APc9vhYcPsRuTSpKD9KpMtPe", "tags" : { }, "identity_id" : "IDnT3ff71VShf6dB2ShcPozq", "entity_id" : null, "entity_type" : null, "size_in_bytes" : null, "file_name" : null } ``` ### 2. Upload the device idle image Send a POST /files/{file_id}/upload request as `multipart/form-data`, using the File resource `id` from the previous step. ```shell curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/files/FILE_eUN3CgqaEiYS84QhrDy42T/upload \ -H 'Content-Type: multipart/form-data' \ -H 'Finix-Version: 2022-02-01' \ -F file=@/Users/Desktop/device-idle-image.png ``` ### 3. Verify the image is approved Wait until the File resource reports `status: UPLOADED` before assigning it to a device. You can confirm the status in one of two ways: - **Poll for status:** Send a GET /files/{file_id} request and check the `status` field in the response. - **Subscribe to webhooks:** Register a [webhook](/additional-resources/developers/webhooks/webhook-events#file-approved) to receive a notification when the File's status changes. ### 4. Update device idle image Now that the image is approved, update the Device resource by sending a PUT /devices/{device_id} request with your custom idle image. You can also customize the text shown on the idle screen using the `idle_message` field. Example API Definition A successful request returns a `200 OK` status with the response body containing the Device with the updated idle image and idle message. The next time the device goes idle, your idle screen image displays instead of the default idle screen. To reset the idle screen to the default, send a PUT /devices/{device_id} request with `configuration.idle_image_file_id` set to `null`. --- # Device Capabilities Source: https://docs.finix.com/guides/in-person-payments/device-capabilities Finix terminals do more than just process payments. They’re equipped with a range of capabilities designed to help you create a smooth, branded, and flexible checkout experience. Whether you're customizing the checkout flow or simplifying backend processes, our devices come packed with features to support your use case: ## Enhanced Checkout Experience - **Tip Customization:** Configure fixed or variable tip options directly on the terminal. - **Manual Entry:** Allow card details to be entered directly on the terminal when needed. - **Surcharging:** Add surcharging to your transactions. ## Branded & Operational Tools - **Upload a Logo:** Display your brand logo on the terminal during idle or checkout states. - **Send Receipts:** Email or print receipts using Finix's Receipt API. - **Device Overrides:** Configure terminal behavior using transaction-level flags. - **Standalone Mode Filters:** Control which transactions appear on the terminal in Standalone Mode. Finix terminals support the features below to improve the in-person payment experience. ## Explore capabilities Tip Customization Configure fixed or percentage-based tip prompts directly on the terminal. Manual Entry Accept payments by entering card details directly on the terminal. Surcharging Add a surcharge to in-person credit card payments to help cover processing costs. Device Idle Screen Configure your brand logo as the custom idle image and message on PAX terminals. Sending Receipts Send email or print receipts from the terminal using our Receipt API. Configuration Overrides Adjust terminal behavior per transaction using transaction-level flags. Standalone Mode Filters Find transactions quickly in Standalone Mode by filtering on amount, date, buyer, or state. --- # Manual Entry Source: https://docs.finix.com/guides/in-person-payments/device-capabilities/manual-entry Not every transaction starts with a tap or swipe. Manual entry gives your business the flexibility to accept payments even when cards can’t be read physically. With Finix, you can enable secure, network-compliant manual card entry right on the terminal, ideal for phone orders, card damage, or remote checkout scenarios. In this guide, you can learn how to manually enter card details on the terminal. ## Standalone Terminals All Standalone Terminals come with the capability to manually enter card details. Follow the steps below to process a manual entry transaction. ### Steps to manually enter card details 1. Navigate to the **Checkout Screen** on your terminal. 2. Enter the amount you wish to charge the customer. 3. Click on **Next**. 4. Select **Manually enter a card**. 5. Enter the card details. 6. Click **Confirm and Pay**. The screenshots below show the manual entry flow on Standalone Terminals. div div img div img div img div img div img ## POS Terminals To enable manual entry for your POS integration, update your device's configuration via the Finix API, then create a sale as normal. Once enabled, the terminal prompts the cashier to enter card details manually before processing. For full reference, see the [Update Device API](https://finix.com/docs/api/tag/Devices/#tag/Devices/operation/updateDevice). **Prerequisites:** - You have a POS Integration with Finix. - You have a terminal associated with your POS Integration. - You have a Finix Device ID for the terminal you want to update. ### Step 1: Update the device configuration to enable manual entry #### Sample request ```shell Enable Manual Entry Request curl https://finix.sandbox-payments-api.com/devices/DVc9sV7fddxiJQqjqNEKrETg \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ -X PUT \ -d '{ "configuration": { "prompt_manual_entry": true } }' ``` #### Sample response ```json Enable Manual Entry Response { "id": "DVc9sV7fddxiJQqjqNEKrETg", "created_at": "2025-04-20T23:33:55.600925Z", "updated_at": "2025-04-20T23:33:55.600925Z", "configuration_details": { "allow_debit": true, "check_for_duplicate_transactions": true, "prompt_amount_confirmation": true, "prompt_manual_entry": true, "signature_threshold_amount": 10000, "bypass_device_on_capture": true, "prompt_receipt_confirmation": true, "display_tip_on_receipt": false, "prompt_tip_on_screen": false, "allow_standalone_authorizations": false, "allow_standalone_sales": false, "allow_standalone_refunds": false, "tipping_details": { "percent_tipping_threshold": 0, "percent_options": [20, 30, 35], "fixed_options": [100, 150, 200] }, "idle_message": null, "idle_image_file_id": null, "automatic_receipt_delivery_methods": ["PRINT", "EMAIL", "SMS"], "available_receipt_methods": ["PRINT", "EMAIL", "SMS"], "prompt_for_signature": "NEVER", "surcharge_basis_points": null }, "description": "Cashier One", "enabled": false, "idle_message": null, "merchant": "MU7noQ1wdgdAeAfymw2rfBMq", "model": "PAX_A800", "name": "My PAX_A800 Finix Device", "serial_number": "19046260945", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/devices/DVc9sV7fddxiJQqjqNEKrETg" }, "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MU7noQ1wdgdAeAfymw2rfBMq" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/transfers" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/authorizations" } } } ``` ### Step 2: Create a Sale #### Sample request ```shell Create Sale Request curl -i -X POST \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ https://finix.sandbox-payments-api.com/transfers \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "amount": 150, "currency": "USD", "device": "DV7DvjGoZ2AEdhAKhtKXVv4b", "operation_key": "CARD_PRESENT_SALE", "tags": { "order_number": "chris123transfer" } }' ``` #### Sample response ```json Create Sale Response { "id": "TRarp7Pz21Low4u2Urw5Ub4W", "created_at": "2019-04-29T20:44:00.13Z", "updated_at": "2022-10-10T05:59:17.59Z", "3ds_redirect_url": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "address_verification": null, "amount": 3138, "amount_requested": 3138, "application": "APeUbTUjvYb1CdPXvNcwW1wP", "capture_amount": 150, "card_present_details": { "emv_data": { "application_identifier": "A0000001523010", "application_label": "DISCOVER", "application_preferred_name": null, "application_transaction_counter": "0005", "cryptogram": "ARCQ F666F8891F870D33", "issuer_code_table_index": null, "pin_verified": false, "tags": null }, "masked_account_number": "************0059", "name": "Test Card 05", "brand": "DISCOVER", "entry_mode": "CHIP_ENTRY", "payment_type": "CREDIT", "approval_code": "004839" }, "currency": "USD", "device": "DVfKLD9GZtsjcJxLtc2yCcfd", "expires_at": "2019-05-06T20:44:00.13Z", "failure_code": null, "failure_message": null, "idempotency_id": null, "is_void": false, "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDsbTBawhnLBAVeinRb84vFR", "messages": [], "raw": null, "security_code_verification": null, "source": "PImTHaz7XVPx4M7mhu9x8gkU", "state": "SUCCEEDED", "tags": { "TicketNumber": "45878" }, "trace_id": "FNX35FSuraeKKJr65wkGVFJni", "void_state": "UNATTEMPTED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUarp7Pz21Low4u2Urw5Ub4W" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP" }, "transfer": { "href": "https://finix.sandbox-payments-api.com/transfers/TRqQCAX7nYHUnkE5YPFTknqd" }, "device": { "href": "https://finix.sandbox-payments-api.com/devices/DVfKLD9GZtsjcJxLtc2yCcfd" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR" } } } ``` The screenshots below show the manual entry flow on POS Terminals after a sale is initiated. div div img div img div img div img --- # Device Configuration Overrides Source: https://docs.finix.com/guides/in-person-payments/device-capabilities/overrides Device configuration overrides are a feature of Finix devices that allow you to modify the configuration of a device for a single transaction. ## Overview Sometimes, a single transaction needs different rules. Device configuration overrides let you temporarily adjust how a Finix terminal behaves without changing its default settings. Using the override capability below gives you precise control. Device configuration overrides are only supported in POS API Integrations. ## Prerequisites - You must have a POS API Integration. - You must have a terminal that supports device configuration overrides. - Pax A800 - Pax A920Pro - Payment App Version 4.5.0 or higher. ## Supported overrides Device configuration overrides is supported for the following features: - Prompt for Tip If there is a configuration override that is not listed above, please reach out to [Finix Support](mailto:support@finix.com) to submit the request. ## How to use device configuration overrides Prompt for Tip Overriding the Prompt for Tip Configuration will determine if the device will prompt the customer for a tip in that specific transaction. img The example below shows how to override the `prompt_tip_on_screen` to `false` to prevent the device from prompting the customer for a tip regardless of the device configuration. ### Sample request with prompt for tip override ```shell Sale Request curl -i -X POST \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ https://finix.sandbox-payments-api.com/transfers \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "amount": 150, "currency": "USD", "device": "DVcCqBNZQiarkAwjoYsExyNJ", "operation_key": "CARD_PRESENT_SALE", "device_configuration": { "prompt_tip_on_screen": false } }' ``` ### Sample response with prompt for tip override ```json Prompt for Tip Response { "id": "TRkaudFBuGvv4ArjateKKMfw", "created_at": "2025-05-08T18:59:45.16Z", "updated_at": "2025-05-08T18:59:45.16Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 4, "amount_requested": 4, "application": "AP9xuCgCd3bi2eLGzbPis5yW", "card_present_details": { "emv_data": { "application_identifier": "A0000000031010", "application_label": "VISA CREDIT", "application_preferred_name": null, "application_transaction_counter": "01B4", "cryptogram": "ARQC 62ACBDCEDDF58F03", "issuer_code_table_index": null, "network_emv_response": null, "pin_verified": false, "tags": null }, "masked_account_number": "411398******1014", "name": null, "brand": "VISA", "entry_mode": "CONTACTLESS", "payment_type": "CREDIT", "approval_code": "03725D", "digital_signature_file_id": null }, "currency": "USD", "destination": null, "device": "DVcCqBNZQiarkAwjoYsExyNJ", "externally_funded": "FALSE", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPn8SyC3wkWbGmkaQKprdjSW", "idempotency_id": null, "merchant": "MUi6m4mp2Cd4U7mWDS9u5Tms", "merchant_identity": "IDmboPwEiLn6KcKsmuBKL5Ln", "messages": [], "operation_key": "CARD_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": "2025-05-09T18:59:51.15Z", "receipt_last_printed_at": null, "security_code_verification": null, "source": "PItb7zqATwkt3P6ggN9LsNWp", "split_transfers": [], "state": "SUCCEEDED", "statement_descriptor": "Oscar Consulting", "subtype": "API", "supplemental_fee": null, "tags": {}, "tip_amount": null, "trace_id": "FNXeATKUpcs5VeFJdNXXT9Pt7", "type": "DEBIT", "_links": { "application": { "href": "https://finix.live-payments-api.com/applications/AP9xuCgCd3bi2eLGzbPis5yW" }, "self": { "href": "https://finix.live-payments-api.com/transfers/TRkaudFBuGvv4ArjateKKMfw" }, "merchant_identity": { "href": "https://finix.live-payments-api.com/identities/IDmboPwEiLn6KcKsmuBKL5Ln" }, "device": { "href": "https://finix.live-payments-api.com/devices/DVcCqBNZQiarkAwjoYsExyNJ" }, "payment_instruments": { "href": "https://finix.live-payments-api.com/transfers/TRkaudFBuGvv4ArjateKKMfw/payment_instruments" }, "reversals": { "href": "https://finix.live-payments-api.com/transfers/TRkaudFBuGvv4ArjateKKMfw/reversals" }, "fees": { "href": "https://finix.live-payments-api.com/transfers/TRkaudFBuGvv4ArjateKKMfw/fees" }, "disputes": { "href": "https://finix.live-payments-api.com/transfers/TRkaudFBuGvv4ArjateKKMfw/disputes" }, "fee_profile": { "href": "https://finix.live-payments-api.com/fee_profiles/FPn8SyC3wkWbGmkaQKprdjSW" } } } ``` If you have any questions or need assistance, please reach out to [Finix Support](mailto:support@finix.com). --- # Configuring Receipts Source: https://docs.finix.com/guides/in-person-payments/device-capabilities/receipts Learn how to configure and deliver receipts for in-person payments via print, email, or SMS. Receipts are more than a formality. They’re a key part of the customer experience. With Finix, you can easily provide professional, network-compliant receipts for every in-person payment, whether they’re printed at the terminal or sent digitally. Card networks have strict receipt requirements, and Finix ensures every receipt meets network standards. ## Understanding receipt settings When **Prompt Receipt Confirmation** is enabled, customers will be asked to choose their preferred receipt delivery method after each transaction. Under **Receipt Delivery Method**, select which options you want to make available to customers: - **Email** - Send digital receipts to customer email addresses - **Print** - Print physical receipts from the terminal - **SMS** - Send digital receipts via text message For automatic receipt delivery, we recommend enabling all three options under **Supported Automatic Receipt Delivery Types** unless you are implementing custom receipt handling. ## Configure receipts delivery methods Standalone ### Configure receipts directly on the Standalone Terminal #### Prerequisites Before updating the receipt settings, ensure the following: - The device supports receipt printing and has paper loaded. - The terminal is powered on. - The terminal is connected to the internet. - The Finix Payment App is open on the terminal. #### Steps to configure receipt settings 1. Navigate to the **Settings** menu on your terminal. 2. Click on **Checkout**. 3. Find the **Receipts** section. 4. Choose your preferred **Receipt Settings**. 5. Click **Save** to apply your changes. #### Screenshots below show the configuration and receipt settings screens div div img div img div img div img API ### Configure receipt settings with the Finix API Below is an example of how to configure receipt settings via the Finix API.[View full API Reference](https://finix.com/docs/api/tag/Devices/#tag/Devices/operation/updateDevice). #### Sample request ```shell Configure Receipt Settings curl https://finix.sandbox-payments-api.com/devices/DVc9sV7fddxiJQqjqNEKrETg \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ -X PUT \ -d '{ "configuration": { "automatic_receipt_delivery_methods": [ "PRINT", "EMAIL", "SMS" ], "available_receipt_methods": [ "PRINT", "EMAIL", "SMS" ] } }' ``` #### Sample response ```json Configure Receipt Settings Response { "id": "DVc9sV7fddxiJQqjqNEKrETg", "created_at": "2025-04-20T23:33:55.600925Z", "updated_at": "2025-04-20T23:33:55.600925Z", "configuration_details": { "allow_debit": true, "check_for_duplicate_transactions": true, "prompt_amount_confirmation": true, "prompt_manual_entry": false, "signature_threshold_amount": 10000, "bypass_device_on_capture": true, "prompt_receipt_confirmation": true, "display_tip_on_receipt": false, "prompt_tip_on_screen": false, "allow_standalone_authorizations": false, "allow_standalone_sales": false, "allow_standalone_refunds": false, "tipping_details": { "percent_tipping_threshold": 0, "percent_options": [18, 20, 22], "fixed_options": [100, 150, 200] }, "idle_message": null, "idle_image_file_id": null, "automatic_receipt_delivery_methods": ["PRINT", "EMAIL", "SMS"], "available_receipt_methods": ["PRINT", "EMAIL", "SMS"], "prompt_for_signature": "NEVER", "surcharge_basis_points": null }, "description": "Cashier One", "enabled": false, "idle_message": null, "merchant": "MU7noQ1wdgdAeAfymw2rfBMq", "model": "PAX_A800", "name": "My PAX_A800 Finix Device", "serial_number": "19046260945", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/devices/DVc9sV7fddxiJQqjqNEKrETg" }, "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MU7noQ1wdgdAeAfymw2rfBMq" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/transfers" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/authorizations" } } } ``` Dashboard ### Configure receipts on the Dashboard #### Prerequisites Before updating the receipt settings, ensure the following: - The device supports receipt printing and has paper loaded. - The terminal is powered on. - The terminal is connected to the internet. - The Finix Payment App is open on the terminal. #### Steps to configure receipt settings 1. Log in to the [Finix Dashboard](https://finix.payments-dashboard.com/). 2. Navigate to **Device Management**. 3. Select the device you want to configure. 4. Go to the **Configuration** section. 5. Choose your preferred **Receipt Settings**. 6. Click **Save** to apply your changes. #### Screenshots below show the configuration and receipt settings screens img img ## Sending In-Person receipts ### Printing receipts with the Finix API Below is a sample request that you can use to print receipts for any `Authorization` or `Transfer`. The receipt will print to the Device specified under `destinations`. When creating a Receipt request, keep the following parameters in mind: - `type` - Specify who the receipt is for (`MERCHANT` or `BUYER`) - `send_receipt_to_buyer` - Set to `true` to send the receipt to the customer - `amount_breakdown` - Include tip and surcharge details if applicable (these won't automatically carry over from the original transaction) #### Sample request ```shell Create Receipt Request curl https://finix.sandbox-payments-api.com/receipts \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \ -X POST \ -d '{ "send_receipt_to_buyer": true, "amount_breakdown": { "subtotal_amount": 1700, "additional_buyer_charges": { "surcharge_amount": 100 }, "tip_amount": 100 }, "requested_delivery_methods": [ { "type": "PRINT", "destinations": [ "DV864n6gKbgGNgQg9LyHpnMR" ] } ], "entity_id": "TRrieLrWspuN3W72BP3nD6hh", "type": "BUYER" }' ``` #### Sample response ```json Create Receipt Response { "id": "receipt_ccBeL2iWn3V1wWSfqjuaE", "created_at": "2024-06-26T18:06:12.68Z", "updated_at": "2024-06-26T18:06:12.68Z", "amount": 500, "currency": "USD", "amount_breakdown": null, "send_receipt_to_buyer": true, "device_id": "DVmiLSwXdYxC7U3wtGCpF7iD", "entity_details": { "id": "TR3rNtUhV4dC82vNsVGLENVD", "created_at": "2024-05-23T21:26:11.71Z", "type": "TRANSFER" }, "type": "BUYER", "merchant_details": { "id": "MUrcHDvsFUp4PjJzWo7WzF82", "business_name": "Smith & Associates Consulting", "doing_business_as": "Smith & Associates Consulting", "business_address": { "city": "Allen", "country": "USA", "line1": "1113 Shade Tree Ln", "line2": null, "postal_code": "75013", "region": "TX" } }, "payment_instrument_details": { "id": "PIkXm2YP4isGwpRpfjrDkEc8", "type": "PAYMENT_CARD_PRESENT", "bin": "476173", "brand": "VISA", "card_type": "CREDIT", "last_four": "0010" }, "network_details": { "application_label": "VISA CREDIT", "application_identifier": "A0000000031010", "approval_code": "031475", "cryptogram": "ARCQ A09FDACC9F024838" }, "requested_delivery_methods": [ { "type": "PRINT", "destinations": ["DVmiLSwXdYxC7U3wtGCpF7iD"] } ], "receipt_url": "https://receipt.sb-payments-checkout.com/W3Qoh1", "_links": { "self": { "href": "https://finix.sb-payments-api.com/receipts/receipt_ccBeL2iWn3V1wWSfqjuaE" } } } ``` ### Adding custom fields to receipts If you want to add custom fields to receipts, you can use the `receipt_options` object in the request body. For more details, API Reference: [Custom Fields in Receipts](https://finix.com/docs/api/tag/Receipts/#tag/Receipts/operation/createReceipt). When a transfer is created using the `/transfers` endpoint, you can include the `receipt_options` object for card-present transactions only to send rich receipt data and deliver a receipt. Below is a sample request that shows how to add custom fields to a receipt. #### Sample request ```shell Create Receipt Request with Custom Fields curl https://finix.sandbox-payments-api.com/transfers \ -H "Content-Type: application/json" \ -H "Finix-Version: 2022-02-01" \ -u USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \ -X POST \ -d '{ "amount": 2000, "currency": "USD", "device": "DVcg7T4QtjaMqrUrvW4wN9ZK", "operation_key": "CARD_PRESENT_SALE", "tags": { "order_number": "Test Transaction" }, "receipt_options": { "additional_details": [ { "name": "Invoice Number", "value": "123123123123" } ] } }' ``` #### Sample response ```json Create Receipt Response with Custom Fields { "id": "TRweNhbvaAFtp9ufhkfNhVJq", "created_at": "2025-06-04T04:54:11.74Z", "updated_at": "2025-06-04T04:54:11.74Z", "additional_buyer_charges": { "convenience_amount": 0, "surcharge_amount": 0, "rent_surcharge_amount": 0 }, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 1800, "amount_requested": 2000, "application": "AP6SikwRjvG2pibYPqsauUfp", "card_present_details": { "emv_data": { "application_identifier": "A0000000031010", "application_label": "VISA CREDIT", "application_preferred_name": null, "application_transaction_counter": "004E", "cryptogram": "ARQC AF834FFFF6439655", "issuer_code_table_index": null, "network_emv_response": null, "pin_verified": false, "tags": null }, "masked_account_number": "476173******0010", "name": null, "brand": "VISA", "entry_mode": "CONTACTLESS", "payment_type": "CREDIT", "approval_code": "046299", "digital_signature_file_id": null }, "currency": "USD", "destination": null, "device": "DVcg7T4QtjaMqrUrvW4wN9ZK", "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FP7TWCCKnEXLrY8R5Z6FYwXy", "idempotency_id": null, "merchant": "MUvnJCJShHXdCNeYGZfeaGz5", "merchant_identity": "IDkkrwinknP5yijVCHrEWz9t", "messages": [], "operation_key": "CARD_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": "PIdQuhTX6SgzguYPHmrTB1gg", "split_transfers": [], "state": "SUCCEEDED", "statement_descriptor": "ACME Anchors", "subtype": "API", "supplemental_fee": null, "tags": { "order_number": "Test Transaction" }, "tip_amount": null, "trace_id": "FNXbSQMzDLYE7gM79Dn1q5o36", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/AP6SikwRjvG2pibYPqsauUfp" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRweNhbvaAFtp9ufhkfNhVJq" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDkkrwinknP5yijVCHrEWz9t" }, "device": { "href": "https://finix.sandbox-payments-api.com/devices/DVcg7T4QtjaMqrUrvW4wN9ZK" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRweNhbvaAFtp9ufhkfNhVJq/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRweNhbvaAFtp9ufhkfNhVJq/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TRweNhbvaAFtp9ufhkfNhVJq/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRweNhbvaAFtp9ufhkfNhVJq/disputes" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FP7TWCCKnEXLrY8R5Z6FYwXy" } } } ``` --- # Standalone Mode Filters Source: https://docs.finix.com/guides/in-person-payments/device-capabilities/standalone-mode-filters Quickly zero in on the transactions you care about. Finix Standalone Mode supports powerful filters to speed up your search. Finix makes it easy to find the transactions that matter by supporting many filters in Standalone Mode. Whether you're searching by amount, date, payment method, or buyer info, filters help you narrow results and save time. img ## Filter types Finix Standalone Mode Terminals support the following filters | **Main Filter** | **Filter Options** | **Description / Example** | | --- | --- | --- | | **Amount** | • Choose a comparison type (e.g., equal to, greater than, less than)• Enter an amount | Filter by transaction amount.*e.g., "Greater than $100"* | | **Buyer** | • Person's Name• Business Name• "Doing Business As" name | Filter by who made the purchase.*e.g., Name: "Miguel", Business: "ACME Inc."* | | **Date Range** | • Start Date• End Date | Filter transactions that occurred within a specific time range.*e.g., "Jan 1 to Jan 31, 2024"* | | **Description** | • Text from the checkout description field | Filter by notes or labels added during checkout.*e.g., "Invoice #78912"* | | **State** | • Select transaction status (e.g., Succeeded, Failed, Pending) | Filter by transaction status.*e.g., Show only "Succeeded" transactions* | | **Payment Instrument** | • Last 4 digits of a bank account• Card brand (e.g., Visa, Mastercard)• Last 4 digits of a card• Cardholder's name• Currency (e.g., USD, CAD) | Filter by payment method details.*e.g., Visa ending in 4242, charged in USD* | If there is a filter that you would like to see added, please reach out to [Finix Support](mailto:support@finix.com). --- # Surcharging on Terminals Source: https://docs.finix.com/guides/in-person-payments/device-capabilities/surcharging Add a surcharge to in-person credit card payments to help cover the cost of processing. ## Overview Finix terminals support surcharging through the device configuration. The `surcharge_basis_points` field sets the surcharge as a percentage of the transaction amount and cannot exceed `300` (3%). For more information, see the [Update Device API](https://finix.com/docs/api/tag/Devices/#tag/Devices/operation/updateDevice). How the surcharge gets applied depends on your integration: - **Standalone Terminals:** The Finix Payment App on the terminal calculates the surcharge and adds it to the `Transfer` or `Authorization` automatically. No additional steps are needed on your end. - **POS API integrations:** Reach out to your Finix point of contact or email [support@finix.com](mailto:support@finix.com) to incorporate surcharging appropriately into your integration. Requirements Merchants must be enabled by Finix before processing surcharge fees. Reach out to your Finix point of contact or email [support@finix.com](mailto:support@finix.com) at least 35 days in advance. Card brand rules also apply: surcharges are limited to credit cards, capped at 3%, and must be disclosed to the buyer before payment. For more information, see [Surcharge Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/surcharge-fees). ## Learn more Surcharge Fees Review the full card brand requirements and refund rules for surcharge fees. Configuration Overrides Adjust terminal behavior per transaction using transaction-level flags. --- # Tip Customization Source: https://docs.finix.com/guides/in-person-payments/device-capabilities/tipping Enable tip prompts on your Finix terminals to collect gratuities during the checkout experience. Whether you’re building a custom integration or using a plug-and-play terminal, Finix makes it easy to configure tip behavior that fits your business. Tip customization is supported on all Finix-compatible terminals and can be managed through the Finix API or directly on the terminal or Dashboard. Standalone ## Configure tip settings directly on the Standalone Terminal ### Prerequisites Before customizing tip settings, make sure: - Your terminal is powered on. - It’s connected to the internet. - The Finix Payment App is open. ## Configure tips on the Terminal You can configure tips directly from the terminal: 1. Navigate to the **Settings** menu on your terminal. 2. Click on **Checkout**. 3. Find the **Tipping** section. 4. Choose your preferred setup: - **No Tip** - Uncheck the two Tip related boxes - **Percentages** (e.g., 10%, 15%, 20%) - **Fixed Amounts** (e.g., $1, $2, $5) 5. Click **Save** to apply your changes. ### Screenshots below show the configuration and tip settings screens div div img div img div img API ## Configure tip settings with the Finix API Below is an example of how to configure tip settings via the Finix API. [View full API Reference](https://finix.com/docs/api/tag/Devices/#tag/Devices/operation/updateDevice). ### Sample request ```shell Configure Tip Settings curl https://finix.sandbox-payments-api.com/devices/DVc9sV7fddxiJQqjqNEKrETg \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ -X PUT \ -d '{ "configuration": { "tipping_details": { "percent_tipping_threshold": 0, "percent_options": [ 20, 30, 35 ], "fixed_options": [ 100, 150, 200 ] } } }' ``` ### Sample response ```json Configure Tip Settings Response { "id": "DVc9sV7fddxiJQqjqNEKrETg", "created_at": "2025-04-20T23:33:55.600925Z", "updated_at": "2025-04-20T23:33:55.600925Z", "configuration_details": { "allow_debit": true, "check_for_duplicate_transactions": true, "prompt_amount_confirmation": true, "prompt_manual_entry": false, "signature_threshold_amount": 10000, "bypass_device_on_capture": true, "prompt_receipt_confirmation": true, "display_tip_on_receipt": false, "prompt_tip_on_screen": false, "allow_standalone_authorizations": false, "allow_standalone_sales": false, "allow_standalone_refunds": false, "tipping_details": { "percent_tipping_threshold": 0, "percent_options": [20, 30, 35], "fixed_options": [100, 150, 200] }, "idle_message": null, "idle_image_file_id": null, "automatic_receipt_delivery_methods": ["PRINT", "EMAIL", "SMS"], "available_receipt_methods": ["PRINT", "EMAIL", "SMS"], "prompt_for_signature": "NEVER", "surcharge_basis_points": null }, "description": "Cashier One", "enabled": false, "idle_message": null, "merchant": "MU7noQ1wdgdAeAfymw2rfBMq", "model": "PAX_A800", "name": "My PAX_A800 Finix Device", "serial_number": "19046260945", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/devices/DVc9sV7fddxiJQqjqNEKrETg" }, "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MU7noQ1wdgdAeAfymw2rfBMq" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/transfers" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/authorizations" } } } ``` Dashboard ## Configure tips on the Dashboard ### Prerequisites Before updating the tip settings, ensure the following: - The terminal is powered on. - The terminal is connected to the internet. - The Finix Payment App is open on the terminal. ### Steps to configure tip settings 1. Log in to the [Finix Dashboard](https://finix.payments-dashboard.com/). 2. Navigate to **Device Management**. 3. Select the device you want to configure. 4. Go to the **Configuration** section. 5. Choose your preferred **Tip Settings**. 6. Click **Save** to apply your changes. ### Screenshots below show the configuration and tip settings screens img img ### Fixed amounts vs. percentage-based tips - **Fixed Tip Amounts** allow you to offer set dollar amounts (e.g., $1, $2, $5) based on an amount you set. - **Percentage-Based Tips** calculate the tip based on the transaction amount (e.g., 10%, 15%, 20%). ## Best practices - Choose tip options that match your business model and customer expectations. - Test tip flows in the **Sandbox** environment before deploying to production. - Use the API for per-transaction tip control: disable for wholesale transactions or enable for service-based transactions. --- # Managing Your Devices Source: https://docs.finix.com/guides/in-person-payments/managing-your-devices In this guide, you can learn how to manage your fleet of devices. ## Device status and monitoring Monitor, analyze, and manage your payment devices with Finix's enhanced device monitoring capabilities. Our enhanced device monitoring system provides full visibility into your device's status, health, and performance metrics. Monitor connection states, view historical data, and access real-time device information all in one place. ## Supported devices for Device Management To access device metrics, please ensure you have the latest version of the Finix Payment App installed. Currently, device monitoring features are available on the following models: - Pax A800 - Pax A920Pro ## Key features ### 1. Device connection status - **Connection State:** View your device's current online/offline status - **Last Seen Timestamp:** Track when your device was last connected to Finix servers - **Connection Type:** Monitor how your device is connected (WiFi, Ethernet, or Cellular) #### Online device example Online Device Example #### Offline device example Offline Device Example ### 2. Device snapshot Get a comprehensive view of your device's current state across four key areas: - Connectivity Information - System & Hardware - Payment Application - Device Health Device Snapshot ### 3. Device status history - Access a new dedicated tab showing historical device status - Track changes in device connectivity over time - View timeline of device events and status changes Device Status History ### 4. On-Demand status updates - You can check device connection to get the latest status and metrics from your device - Manually trigger device status checks when needed - Receive immediate feedback on device health Device Refresh Status ## Device metrics | Field | Description | | --- | --- | | Connection State | Current connection state of the device (e.g., `OPEN`) | | Payment App State | Current state of the payment application (e.g., `FOREGROUND`) | | Payment App Version | Version of the Finix Payment Application installed | | IP Address | Device's current IP address | | Network Type | Current network connection type (e.g., `WIFI`) | | Signal Strength | Wireless signal strength indicator (e.g., `EXCELLENT`) | | Battery Level | Current battery percentage | | Battery Temperature | Temperature of device | | Charging Status | Whether the device is currently charging | | Time Zone | Device's configured time zone | | System Time | Current operating system time | | Firmware Version | Version of the device's operating system firmware | | Android Version | Version of the Android operating system | | Available Storage | Available storage space in megabytes | | RAM Usage | Percentage of RAM currently in use | ## Learn more Troubleshooting Your Terminal Resolve common issues with battery, connectivity, printing, and power. Device API Reference Explore the Devices endpoints for device connection details and metrics. --- # Order Devices Source: https://docs.finix.com/guides/in-person-payments/ordering-devices Finix Device Store lets you simplify your device ordering process, offering a convenient and centralized platform. Within the Device Store, you can browse, select, and purchase the devices you need, all in one place. The Device Store offers the following benefits: - **Simplified Checkout:** A quick and easy process that allows you to purchase devices with a few clicks. - **Managing and Tracking Orders:** Keep track of your orders and view shipping status. - **Device Catalog:** Find the perfect device for your needs with our easy-to-navigate catalog. ## Ordering a device on the Finix Dashboard ### Step 1: Navigate to the Device Store To order devices in the Finix Dashboard: 1. Log into the [Finix Dashboard](https://finix.payments-dashboard.com/login). 2. Click Devices > Device Store. 3. Review the device catalog and select the device(s) that fit your needs. Device Stores - ### Step 2: Add device(s) to cart 1. Decide on the type and quantity of device(s). 2. Click on Add to Cart to add the device(s) to your cart. 3. Click on the shopping cart icon in the top right corner. Device Store - Cart Button ### Step 3: Checkout 1. Review your cart and click Checkout on the bottom right. Device Store - Checkout Button 1. Review your Order Summary. 2. Fill out the form. 3. Click Place Order. Device Store - Checkout Form ### Step 4: Device order confirmation After placing your order, you'll be directed to the Device Order Details page. Here, you can - Verify your Contact Details - Confirm your Shipping Details - Check your Billing Details This page ensures you have all the necessary information about your order at a glance. Device Store - Order Details Order Cancellations While you may place an order via the Finix Dashboard, our team based on our discretion can cancel an order if Finix is unable to fulfill the order for any reason. Please contact your Finix point of contact or any questions. Finix Device Ordering Terms and Conditions can be found here. ## Managing Device Orders After you place an order, you can view its status, track shipments, and cancel pending orders directly in the Finix Dashboard. ### Viewing Device Orders To view device orders on the Finix Dashboard: 1. Log into the [Finix Dashboard](https://finix.payments-dashboard.com/login). 2. Click **Devices > Device Orders**. Review Device Orders ### Understanding the status of your order | Status | Meaning | | --- | --- | | Order Received | The order has been received and will be reviewed for approval prior to fulfillment. | | Confirmed | The order has been approved and is being prepared for shipment. | | Shipped | The order has been shipped. | | Cancelled | The order has been cancelled. | ### Cancelling an order Cancelling Orders You can only cancel an order if the status is "Order Received". Please contact your Finix Point of Contact for questions regarding refunds on a cancelled order. To cancel an order: 1. Click **Devices > Device Orders**. 2. Select the order you want to cancel. 3. Click **Action** on the top right corner 4. Click **Cancel Order**. Review Device Orders - Cancel Order Option 1. Click **Cancel Order**. Review Device Orders - Cancel Order Modal Building your Integration Learn about Finix's POS and mobile in-person payments integrations. --- # Select Your Device Source: https://docs.finix.com/guides/in-person-payments/select-your-device Finix has several payment terminals to meet all of your business needs. You can see our available devices below. If you're not sure which reader is right for you, contact your Finix point of contact and we can help you choose a reader that best fits your needs. | Image | Terminal Name | Use Case | Integration | Connectivity | Power | Supported Countries | | --- | --- | --- | --- | --- | --- | --- | | | [PAX A800](/guides/in-person-payments/select-your-device/pax-a800) | Smart Combo for handheld and tabletop use. Embedded receipt printer included. | API, Standalone, Device Reader SDK | Wi-Fi, Ethernet, 4G LTE | Battery Powered | U.S. and Canada | | | [PAX A920 Pro](/guides/in-person-payments/select-your-device/pax-a920-pro) | Handheld terminal with built-in receipt printer. Ideal for mobile use. | API, Standalone, Device Reader SDK | Wi-Fi, Ethernet, 4G LTE | Battery Powered | U.S. and Canada | | | [Tap to Pay on iPhone](/low-code-no-code/mobile-apps/finix-checkout/tap-to-pay-on-iphone) | Accept contactless payments on iPhone. No card reader required. | [Finix Checkout iOS app](/low-code-no-code/mobile-apps/finix-checkout/tap-to-pay-on-iphone) | Wi-Fi / Cellular | N/A | U.S. | | | [PAX A35](/guides/in-person-payments/select-your-device/pax-a35) | Compact Android smart PIN pad for retail checkout. Ideal for countertop and multilane POS deployments. | API, Device Reader SDK | Wi-Fi, Ethernet | Plug-in Power | U.S. and Canada | | | [PAX A3700](/guides/in-person-payments/select-your-device/pax-a3700) | Customer-facing Android payment tablet for retail checkout. Ideal for countertop and mobile use. | API, Device Reader SDK | Wi-Fi, Ethernet, 4G LTE | Battery Powered | U.S. and Canada | | | [PAX IM30](/guides/in-person-payments/select-your-device/pax-im30) | Compact, Android-based smart payment terminal designed for self-service, semi-attended, and unattended environments. | API, Device Reader SDK | Wi-Fi, Ethernet, 4G | Plug-in Power | U.S. and Canada | | | [PAX D135](/guides/in-person-payments/select-your-device/pax-d135) | Lightweight mobile device designed for on-the-go transactions. | SDK | Bluetooth | Battery Powered | U.S. | ## SIM connectivity - The PAX A800 and A920PRO devices both support SIM connectivity. Finix does not provide SIM cards; they must be sourced independently by the customer. - While SIM cards are supported by the device hardware, Finix recommends using Wi-Fi or Ethernet connections for optimal network performance and reliability. - Customers who choose to use SIM connectivity should verify that signal strength and data reliability meet their operational needs. Order a Terminal Order in Production via the Device Store or reach out to your Finix contact to order a terminal for Sandbox. Building Your Integration Choose the integration path that fits your devices. --- # PAX A35 Source: https://docs.finix.com/guides/in-person-payments/select-your-device/pax-a35 In this guide, you can learn how to use the PAX A35 payment terminal. div div The PAX A35 is a compact Android smart PIN pad designed for retail checkout. It typically connects to a POS system. Ideal for countertop and multilane environments where customers tap, dip, or swipe to pay. div img ## PAX A35 package contents div | **Item** | **Quantity** | | --- | --- | | PAX A35 POS Terminal | 1 | | A35 Quick Setup Guide | 1 | | Communication Cable | 1 | | AC Power Adapter | 1 | ## Device view The following section points out the hardware features and functions of the PAX A35 PIN pad. div img ## Powering on the device The A35 is powered through the communication cable. Power is supplied either by connecting the AC adapter to the DC port on the communication cable, or via a powered USB cable. 1. Remove the back cover and insert the communication cable into the Type-C interface. 2. Connect the AC power adapter to the DC port on the communication cable, or use a powered USB cable. 3. Connect the other end of the communication cable to your POS system, ECR, or payment terminal. The terminal has successfully been powered on. ## Connecting to the internet The PAX A35 payment terminal can connect to the internet using: - Wi-Fi - Ethernet (via the communication cable) We strongly recommend using a wired Ethernet or Wi-Fi network to connect the PAX A35 to the internet. To connect to Wi-Fi, follow the steps below: 1. Tap on Settings 2. Enter the password. 3. Tap on Network & Internet 4. Tap WiFi 5. Select your Network and Connect ## Card readers ### Magnetic stripe card reader Face the card’s magstripe inwards toward the A35, then swipe the card completely up or down in a constant, steady manner. The A35 supports bi-directional swiping. ### IC/Smart card reader Face the card’s microchip upward and insert firmly into the slot. Make sure that the card is fully inserted into the card reader while scanning the card. ### Contactless card reader Tap the contactless card or mobile wallet near the top of the A35’s LCD screen, indicated by the universal contactless icon. For best results, place as close to the reader as possible and center the card over the indicated area. ## Cleaning the device - Do not use industrial strength or abrasive cleaner as it may damage or scratch the screen. - Do not immerse the device in water or liquid. - Do not spray water or cleaner into ports. - To clean the screen, apply distilled water or mild glass cleaner onto a soft, lint-free cloth and gently wipe terminal. ## Developer specifications If you're [deploying your own app](/guides/in-person-payments/deploy-apps-terminals) to this terminal, these specifications apply to app development: | Specification | Details | | --- | --- | | Operating System | PAXBiz, powered by Android 10 | | Processor | ARM Cortex-A53 | | Memory | 1GB DDR RAM, 8GB flash (microSD up to 128GB) | | Display | 4" WVGA capacitive touchscreen, 480 x 800 pixels, Corning Gorilla Glass | ## Resources A few resources are available for the PAX A35 which you can share with sellers to help explain how to get the terminal setup: | Resource | Description | | --- | --- | | [PAX A35 Quick Setup Guide](https://www.pax.us/support/documents/a35-quick-setup-guide/) | Review the quick setup guide for the PAX A35 from the terminal's manufacturer. | | [PAX A35 Data Sheet](https://uploads.strikinglycdn.com/files/45390008-8a4b-492d-8e46-06bb6b71eff7/A35-PINpad-PAX-EMEA-February2026.pdf) | Data Sheet with specifications for the PAX A35. | Order a Terminal Order in Production via the Device Store or reach out to your Finix contact to order a terminal for Sandbox. --- # PAX A3700 Source: https://docs.finix.com/guides/in-person-payments/select-your-device/pax-a3700 In this guide, you can learn how to use the PAX A3700 payment terminal. div div The PAX A3700 (Elys Tablet) is a customer-facing Android payment tablet designed for retail checkout. It can connect to an Elys Station or be used on its own as a mobile payment device. Ideal for countertop and on-the-floor environments where customers tap, dip, or swipe to pay. div img ## PAX A3700 package contents div | **Item** | **Quantity** | | --- | --- | | A3700 Smart Payment Terminal | 1 | | Power Cable | 1 | | Power Adapter | 1 | ## Device view The following section shows the hardware of the PAX A3700 payment tablet. img ## Powering on the device The PAX A3700 terminal comes with a power cable and an AC power adapter. 1. Connect the power adapter and cable to a power source and charge the device. 2. Press and hold the power button for 3 to 5 seconds, then release. To power off, press and hold the power button for 3 to 5 seconds, then release. The terminal has successfully been powered on. ## Connecting to the internet The PAX A3700 payment terminal can connect to the internet using: - Wi-Fi - 4G LTE - Ethernet (via an optional hub) We strongly recommend using a wired Ethernet or Wi-Fi network to connect the PAX A3700 to the internet. To connect to Wi-Fi, follow the steps below: 1. Tap on Settings 2. Enter the password. 3. Tap on Network & Internet 4. Tap WiFi 5. Select your Network and Connect ## SIM/SAM card installation 1. Uncover the silicone strip on the back of the terminal. 2. Insert the SAM/SIM card into the corresponding card slot. ## Card readers ### Magnetic stripe card reader Slide the card through the card reader slot from left to right or from right to left with the magnetic strip oriented towards the body of the device. Make sure that the card is fully inserted into the card reader while swiping the card. ### IC/Smart card reader Insert the card fully into the reader with the metallic contacts facing up and towards the device. Make sure that the card is fully inserted into the card reader while scanning the card. ### Contactless card reader The contactless card reader reads cards and devices placed roughly within an inch (2.5 mm). For best results, place as close to the reader as possible and center the card over the indicated area at the top of the terminal. ## Cleaning the device - Do not use industrial strength or abrasive cleaner as it may damage or scratch the screen. - Do not immerse the device in water or liquid. - Do not spray water or cleaner into EMV Card Reader or ports. - To clean the screen, apply distilled water or mild glass cleaner onto a soft, lint-free cloth and gently wipe terminal. ## Lithium ion battery - The terminal is equipped with a non-removable built-in battery. Do not replace the battery yourself. - Do not use or place the battery in direct sunlight and/or smokey, dusty environments. - Do not strike, squeeze, and/or tread on battery. - Do not throw the battery in any liquids or place in/near fires. - The charging time cannot exceed 24 hours. If the battery is out of power, recharge it to 100% capacity and then disconnect the device to avoid shortening its life. - Please recharge the battery at least once every 6 months to avoid shortening its life. - Replace battery every two years. - Be sure to follow the instructions to dispose of wasted batteries. Battery life expectancy varies based on usage conditions and environment. For best results, keep the battery above a 50% charge. Repeatedly allowing it to drain fully may shorten its life and decrease its overall capacity. ## Developer specifications If you're [deploying your own app](/guides/in-person-payments/deploy-apps-terminals) to this terminal, these specifications apply to app development: | Specification | Details | | --- | --- | | Operating System | Android 11 | | Processor | Octa-core, 1.8GHz | | Memory | 2GB RAM, 64GB flash (microSD up to 256GB) | | Display | 7" IPS capacitive touchscreen, 1280 x 800 pixels | ## Resources A few resources are available for the PAX A3700 which you can share with sellers to help explain how to get the terminal setup: | Resource | Description | | --- | --- | | [PAX A3700 Quick Setup Guide](https://www.pax.us/support/documents/elys-tablet-a3700-quick-setup-guide/) | Review the quick setup guide for the PAX A3700 from the terminal's manufacturer. | | [PAX A3700 Data Sheet](https://www.pax.us/wp-content/uploads/2024/03/Elys-A3700-Datasheet.pdf) | Data Sheet with specifications for the PAX A3700. | Order a Terminal Order in Production via the Device Store or reach out to your Finix contact to order a terminal for Sandbox. --- # PAX A800 Source: https://docs.finix.com/guides/in-person-payments/select-your-device/pax-a800 In this guide, you can learn how to use the PAX A800 payment terminal. div div The PAX A800 is a hybrid tabletop and handheld payment terminal. Ideal for businesses requiring flexibility and reliable transaction processing in areas with limited network connectivity. Includes an embedded receipt printer, enabling you to effortlessly process payments and print receipts on the go. div img ## PAX A800 package contents div | **Item** | **Quantity** | | --- | --- | | A800 Smart Terminal | 1 | | Paper Roll | 1 | | AC Power Adapter | 1 | | Cable | 1 | | Manual | 1 | ## Device view img ## Powering on the device The PAX A800 terminal comes with a USB-C cable and an AC power adapter. 1. Connect the power adapter or USB-C cable to a power source. 2. Charge the device to at least 70%. 3. Once the device is charged, press and hold the power button down for 2 seconds until the LCD backlight turns on. The terminal has successfully been powered on. ## Connecting to the internet The PAX A800 payment terminal can connect to the internet using: a Wi-Fi network 4G LTE We strongly recommend using a Wi-Fi network to connect the PAX A800 to the internet. To connect to Wi-Fi, follow the steps below: 1. Tap on Settings 2. Enter the password. 3. Tap on Network & Internet 4. Tap WiFi 5. Select your Network and Connect ## Card readers ### Magnetic stripe card reader Slide the card through the card reader slot from top to bottom with the magnetic strip oriented towards the body of the device. Make sure that the card is fully inserted into the card reader while swiping the card. ### IC/Smart card reader Insert the card fully into the reader with the metallic contacts facing up and towards the device. Make sure that the card is fully inserted into the card reader while scanning the card. ### Contactless card reader The contactless card reader reads cards and devices placed roughly within an inch (2.5 mm). For best results, place as close to the reader as possible and center the card over the indicated area at the top of the terminal. ## Cleaning the device - Do not use industrial strength or abrasive cleaner as it may damage or scratch the screen. - Do not immerse the device in water or liquid. - Do not spray water or cleaner into EMV Card Reader or ports. - To clean the screen, apply distilled water or mild glass cleaner onto a soft, lint-free cloth and gently wipe terminal. ## Lithium ion battery - Do not use or place the battery in direct sunlight and/or smokey, dusty environments. - Do not strike, squeeze, and/or tread on battery. - Do not throw the battery in any liquids or place in/near fires. - If the battery is deformed or damaged, please stop using immediately and replace it. - If the continuous working time is only half of a new battery, the battery life may be at its end. Please replace it. - The specified battery model and charger must be used, otherwise there may be an explosion. - The charging time cannot exceed 24 hours. If the battery is out of power, recharge it to 100% capacity and then disconnect the device to avoid shortening its life. - Please recharge the battery at least once every 6 months to avoid shortening its life. - Replace battery every two years. - Be sure to follow the instructions to dispose of wasted batteries. Battery life expectancy varies based on usage conditions and environment. Internal testing shows that fully charging and discharging the battery 500 times results in the battery retaining over 80% of its original capacity. For best results, keep the battery above a 50% charge. Repeatedly allowing it to drain fully may shorten its life and decrease its overall capacity. ## Developer specifications If you're [deploying your own app](/guides/in-person-payments/deploy-apps-terminals) to this terminal, these specifications apply to app development: | Specification | Details | | --- | --- | | Operating System | PayDroid, powered by Android 10 | | Processor | Quad-core ARM Cortex-A53, 2.0GHz | | Memory | 1GB DDR RAM, 8GB eMMC flash (16GB optional) | | Display | 5.7" capacitive touchscreen, 720 x 1440 pixels | ## Resources A few resources are available for the PAX A800 which you can share with sellers to help explain how to get the terminal setup: | Resource | Description | | --- | --- | | [PAX A800 User Manual](https://www.pax.us/support/documents/a800-qsg/) | Review the user manual for the PAX A800 from the terminal's manufacturer. | | [PAX A800 Data Sheet](https://www.pax.us/wp-content/uploads/2023/02/A800_EN_20211115.pdf) | Data Sheet with specifications for the PAX A800. | Order a Terminal Order in Production via the Device Store or reach out to your Finix contact to order a terminal for Sandbox. --- # PAX A920 Pro Source: https://docs.finix.com/guides/in-person-payments/select-your-device/pax-a920-pro In this guide, you can learn how to use the PAX A920 Pro payment terminal. div div The PAX A920 Pro is a hybrid tabletop and handheld payment terminal. Ideal for businesses requiring flexibility and reliable transaction processing in areas with limited network connectivity. Includes an embedded receipt printer, enabling you to effortlessly process payments and print receipts on the go. div img ## PAX A920 Pro package contents div | **Item** | **Quantity** | | --- | --- | | A920 Pro Smart Terminal | 1 | | Paper Roll | 1 | | Power Adapter | 1 | | Cable | 1 | ## Device views div div div h3 Front View img div h3 Back View img div h3 Side View img ## Powering on the device The PAX A920 Pro terminal comes with a USB-C cable and an AC power adapter. 1. Connect the power adapter or USB-C cable to a power source. 2. Charge the device to at least 70%. 3. Once the device is charged, press and hold the power button down for 2 seconds until the LCD backlight turns on. The terminal has successfully been powered on. ## Connecting to the internet The PAX A920 Pro payment terminal can connect to the internet using: - a Wi-Fi network - 4G LTE We strongly recommend using a Wi-Fi network to connect the PAX A920 Pro to the internet. To connect to Wi-Fi, follow the steps below: 1. Tap on Settings 2. Enter the password. 3. Tap on Network & Internet 4. Tap WiFi 5. Select your Network and Connect ## Card readers ### Magnetic stripe card reader Slide the card through the card reader slot from left to right or from right to left with the magnetic strip oriented towards the body of the device. Make sure that the card is fully inserted into the card reader while swiping the card. ### IC/Smart card reader Insert the card fully into the reader with the metallic contacts facing up and towards the device. Make sure that the card is fully inserted into the card reader while scanning the card. ### Contactless card reader The contactless card reader reads cards and devices placed roughly within an inch (2.5 mm). For best results, place as close to the reader as possible and center the card over the indicated area at the top of the terminal. ## Cleaning the device - Do not use industrial strength or abrasive cleaner as it may damage or scratch the screen. - Do not immerse the device in water or liquid. - Do not spray water or cleaner into EMV Card Reader or ports. - To clean the screen, apply distilled water or mild glass cleaner onto a soft, lint-free cloth and gently wipe terminal. ## Lithium ion battery - Do not use or place the battery in direct sunlight and/or smokey, dusty environments. - Do not strike, squeeze, and/or tread on battery. - Do not throw the battery in any liquids or place in/near fires. - If the battery is deformed or damaged, please stop using immediately and replace it. - If the continuous working time is only half of a new battery, the battery life may be at its end. Please replace it. - The specified battery model and charger must be used, otherwise there may be an explosion. - The charging time cannot exceed 24 hours. If the battery is out of power, recharge it to 100% capacity and then disconnect the device to avoid shortening its life. - Please recharge the battery at least once every 6 months to avoid shortening its life. - Replace battery every two years. - Be sure to follow the instructions to dispose of wasted batteries. Battery life expectancy varies based on usage conditions and environment. Internal testing shows that fully charging and discharging the battery 500 times results in the battery retaining over 80% of its original capacity. For best results, keep the battery above a 50% charge. Repeatedly allowing it to drain fully may shorten its life and decrease its overall capacity. ## Developer specifications If you're [deploying your own app](/guides/in-person-payments/deploy-apps-terminals) to this terminal, these specifications apply to app development: | Specification | Details | | --- | --- | | Operating System | PAXBiz, powered by Android 8.1 | | Processor | Quad-core ARM Cortex-A53, 1.4GHz | | Memory | 1GB DDR RAM, 8GB eMMC flash (2GB RAM / 16GB flash optional, microSD up to 128GB) | | Display | 5.5" HD capacitive touchscreen, 1280 x 720 pixels | ## Resources A few resources are available for the PAX A920 Pro which you can share with sellers to help explain how to get the terminal setup: | Resource | Description | | --- | --- | | [PAX A920 Pro User Manual](https://www.pax.us/support/documents/a920-pro-qsg-preview/) | Review the user manual for the PAX A920 Pro from the terminal's manufacturer. | | [PAX A920 Pro Data Sheet](https://www.pax.us/wp-content/uploads/2023/12/A920Pro-Datasheet.pdf) | Data Sheet with specifications for the PAX A920 Pro. | Order a Terminal Order in Production via the Device Store or reach out to your Finix contact to order a terminal for Sandbox. --- # PAX D135 Source: https://docs.finix.com/guides/in-person-payments/select-your-device/pax-d135 The PAX D135 is a compact, mobile smart card reader. It connects to Android or iOS devices via Bluetooth, allowing your phone or tablet to function as a payment terminal. PAX D135 Product Charging the Device Charge the battery only with PAX-approved power supplies. Using others may damage the product and void the warranty. Charging time must not exceed 24 hours. If the battery is empty, recharge it fully, then disconnect the device to avoid shortening its life. ## Device view PAX D135 front view with dimensions and specifications PAX D135 back view with dimensions and specifications ## Basic operating instructions ### Power ON/OFF - **Power ON:** Press and hold the power button until the device beeps, then release - **Power OFF:** Press and hold the power button until the four colored lights flash simultaneously ### Power indicator - **Green light:** More than 20% power - **Orange light with a solid red or solid green light:** The D135 has not been paired with a device (phone/tablet) yet and is ready for pairing. - **Red light:** Less than 20% power - **Flashing red light:** Insufficient power; device will shut down automatically ### Charging indicator - **Slow flashing red light:** Charging in progress - **Solid green light:** Fully charged ## Connectivity options ### Bluetooth connection 1. Turn on the D135 2. Scan for the D135 signal in your device's settings (default name: `PAX D135_XXXX`) 3. Pair your device with the D135 (you may need to enter a passkey) ## Card readers ### Magnetic stripe cards - Slide the card through the reader slot in either direction - Ensure the magnetic strip faces toward the device - Card must be fully inserted while swiping ### Contactless cards - Hold card within one inch of the reader - Center the card over the indicated area at the top of the terminal - For best results, place as close to the reader as possible ## Maintenance and care ### Cleaning guidelines - Do not use industrial strength or abrasive cleaners - Do not immerse in water or liquid - Avoid spraying cleaners into EMV Card Reader or ports ### Usage tips - Replace damaged cables immediately - Do not insert foreign materials into device ports - Contact professional technicians for repairs - Avoid exposure to excessive heat, dust, or strong electromagnetic environments - Do not vibrate, shake, or drop the device ### Status indicator The D135 comes with both hardware and software mechanisms that prevent the terminals from being opened and modified. If the D135 has been tampered with, the following lights will indicate that it not safe for use: - Blue indicator 1 and 4 are on: The machine is compromised at present. - Blue indicator 1, 2, 3 and 4 are all on: The machine has been tampered with in the past. ## Resources Resources are available for the PAX D135 which you can share with sellers to help explain how to get the terminal setup: | Resource | Description | | --- | --- | | [PAX D135 Setup Guide](https://www.pax.us/support/documents/d135-qsg/) | Review the user setup guide for the PAX D135 from the terminal's manufacturer. | | [PAX D135 Data Sheet](https://www.pax.us/wp-content/uploads/2023/12/D135-Datasheet.pdf) | Data Sheet with specifications for the PAX D135. | Order a Terminal Order in Production via the Device Store or reach out to your Finix contact to order a terminal for Sandbox. --- # PAX IM30 Source: https://docs.finix.com/guides/in-person-payments/select-your-device/pax-im30 In this guide, you can learn how to use the PAX IM30 payment terminal. div div The PAX IM30 is a compact, Android-based smart payment terminal designed for self-service, semi-attended, and unattended environments. Ideal for businesses seeking a modern, customer-facing payment experience, it supports EMV chip, contactless, and mobile wallet payments. Its sleek form factor and flexible connectivity options make it well-suited for retail, hospitality, and unattended use cases where space and reliability are critical. div img ## PAX IM30 package contents div | **Item** | **Quantity** | | --- | --- | | IM30 Unattended Payment Terminal | 1 | | Locking USB-A to Micro-B Cable (1m) | 1 | | Power Supply, PAX, 12V/1A Adapter | 1 | | GPRS 4G Antenna | 1 | | M4 Nuts | 4 | | M4 Screws | 4 | ## Device view img 1. Front Facing Camera 2. Contactless Card Reader Interface 3. LCD Touchscreen 4. Smart Card Reader 5. Magnetic Strip Card Reader 6. Proximity and Light Detector 7. Code Scanning Camera 8. Camera Lighting img 1. Anti-removal Switches 2. 4G Antenna SMA Connector (Optional) 3. GPS Antenna SMA Connector (Optional) 4. 4G Module & SIM Card Slot 5. RS232-B (RJ45) 6. RS232-A (RJ45) 7. Ethernet Port (RJ45) 8. Auxiliary Port (Mic + Speaker) 9. Digital IO Port 10. MDB Master Port 11. USB Type-A Port 12. USB Type-C Port 13. Service Button 14. Reset Button 15. HDMI Port 16. Status Indicator LED 17. MDB Slave Port ## Powering on the device ### Power on Plug the IM30 into an appropriate power source via the MDB port, the digital IO port, or the RS232-A RJ45 port. ### Power off Disconnect the IM30 from the power source it is connected to. ## Settings and exiting the Finix payment app To access the settings or exit the Finix Payment App: 1. Tap each corner of the screen in this order: - Top left - Top right - Bottom right - Bottom left 2. Swipe up from the bottom of the screen. 3. A passcode dialog will appear. Enter **61424**. 4. Once the correct passcode is entered, you’ll be able to access the app’s settings page and choose to exit the app. img ## Connecting to the internet The PAX IM30 payment terminal can connect to the internet using Direct connection via Ethernet a Wi-Fi network To connect to Wi-Fi, follow the steps below: 1. Tap on Settings 2. Enter the password. 3. Tap on Network & Internet 4. Tap WiFi 5. Select your Network and Connect ## Developer specifications If you're [deploying your own app](/guides/in-person-payments/deploy-apps-terminals) to this terminal, these specifications apply to app development: | Specification | Details | | --- | --- | | Operating System | PayDroid, powered by Android 10 | | Processor | Quad-core ARM Cortex-A53, 1.6GHz | | Memory | 4GB LPDDR4 RAM, 32GB flash | | Display | 5" IPS touchscreen, 1280 x 720 pixels | --- # Standalone Terminals Source: https://docs.finix.com/guides/in-person-payments/standalone-terminals img You can use our Standalone Terminals to process payments without any engineering or development work. Standalone Terminals are our fastest way to start accepting in-person payments and requires no development or engineering work. This is a great solution if you simply want to process payments without building a POS Integration. Standalone Terminals provide you with even greater control and streamlined daily operations directly on your terminal. It brings a powerful new features eliminating the need to constantly switch to the Finix Dashboard for essential tasks. ## Requirements - A Standalone Terminal - [Pax A800](/guides/in-person-payments/select-your-device/pax-a800) - [Pax A920Pro](/guides/in-person-payments/select-your-device/pax-a920-pro) - Payment App version 4.0.0 or higher installed on your terminal - Standalone Mode enabled for your terminal ## Elevating your payment experience ### Streamlined Checkout experience - **Faster and More Intuitive Transactions:** We've redesigned the core checkout flow for speed and ease of use. From initiating a sale to completing the transaction, the process is intuitive and efficient. - **Enhanced Payment Confirmation:** Clearer on-screen confirmations and receipt options ensure both you and your customers have a seamless checkout experience. - **Add Custom Description to Each Transaction:** Add a custom description to each transaction with data such as invoice number, order number, or any other relevant information. div div div img div img div img div img div img div img div small Swipe or scroll to view more screens ### A clear view of your business - **Comprehensive Transaction History:** View a complete list of your transactions directly on the terminal, making it easy to track sales, identify trends, and resolve any discrepancies. You can also filter by the transactions specifically taken on that device. - **Detailed Transaction Information:** Access detailed information for each transaction, including date, time, amount, payment method, and status, providing a complete audit trail. - **Filter by Device:** Easily filter transactions by the device they were taken on, making it easier to track sales. div div div img div img div small Swipe or scroll to view more screens ### Manage your business directly on the Terminal - **Process Refunds with Ease:** Issue refunds directly from the terminal, simplifying the return process for both you and your customers. - **Print Receipts On-Demand:** Easily reprint receipts for past transactions whenever needed, providing convenient record-keeping. - **Configure Settings On-Device:** Take control of your terminal's configuration by adjusting settings like tipping options and surcharging directly on the device, eliminating the need to access the Finix Dashboard for these common tasks. - **Manage Authorizations:** Quickly void or capture authorizations directly on the terminal, giving you greater flexibility in managing transactions before they settle. div div div img div img div img div img div small Swipe or scroll to view more screens ### More ways to take Payments **Manual Card Entry:** Process payments even by manually entering card details directly on the terminal. This provides a convenient backup option and expands your payment acceptance capabilities. Standalone Mode Manual Entry ### We're here to help If you have any questions or need assistance, please reach out to [support@finix.com](mailto:support@finix.com). ## Learn more Standalone Terminals Quickstart Follow this guide to activate Standalone Mode on your terminal and process your first transaction. Standalone Terminal Experience Explore the Standalone Mode interface and the tasks you can complete directly on your terminal. --- # Standalone Terminal Experience Source: https://docs.finix.com/guides/in-person-payments/standalone-terminals/standalone-terminals-experience Learn about the experience of using your Pax terminal in standalone mode. We're continually improving our Standalone Mode experience on Finix's Pax terminals, and the latest enhancements provide you with even greater control and streamlined daily operations directly on your terminal. This update brings a refreshed user interface and powerful new features, eliminating the need to constantly switch to the Finix Dashboard for essential tasks. ## Getting started with the update ### Supported Terminals Standalone Terminal is available for the following Pax terminals. - Pax A800 - Pax A920Pro ### Requirements The new features require: - Payment App version 4.0.0 or higher installed on your terminal - The App will typically auto-update, but if it doesn't, follow the update steps under How to Update - Standalone Mode enabled for your terminal ### How to update If your terminal hasn't automatically updated, you can manually update by following these steps: - Open the Pax Store App on your device - Search for the Payment App - Select Update For detailed instructions, see our [Finix Payment App Update Instructions](/guides/in-person-payments/troubleshooting-your-terminal/update-your-payment-version). ### Need help? If you have any questions or need assistance, please reach out to [support@finix.com](mailto:support@finix.com). ## Elevating your payment experience ### Streamlined Checkout experience - **Faster and More Intuitive Transactions:** We've redesigned the core checkout flow for speed and ease of use. From initiating a sale to completing the transaction, the process is intuitive and efficient. - **Enhanced Payment Confirmation:** Clearer on-screen confirmations and receipt options ensure both you and your customers have a seamless checkout experience. div div div img div img div img div img div img div img div small Swipe or scroll to view more screens ### A clear view of your business - **Comprehensive Transaction History:** View a complete list of your transactions directly on the terminal, making it easy to track sales, identify trends, and resolve any discrepancies. You can also filter by the transactions specifically taken on that device. - **Detailed Transaction Information:** Access detailed information for each transaction, including date, time, amount, payment method, and status, providing a complete audit trail. - **Filter by Device:** Easily filter transactions by the device they were taken on, making it easier to track sales and identify trends. Standalone Mode Transaction List Standalone Mode Filter by Device ### Manage your business directly on the Terminal - **Process Refunds with Ease:** Issue refunds directly from the terminal, simplifying the return process for both you and your customers. - **Print Receipts On-Demand:** Easily reprint receipts for past transactions whenever needed, providing convenient record-keeping. - **Configure Settings On-Device:** Take control of your terminal's configuration by adjusting settings like tipping options and surcharging directly on the device, eliminating the need to access the Finix Dashboard for these common tasks. - **Manage Authorizations:** Quickly void or capture authorizations directly on the terminal, giving you greater flexibility in managing transactions before they settle. Standalone Mode Create Refund Standalone Mode Print Receipt Standalone Mode Auth Capture Standalone Mode Configurations ### More ways to take Payments - **Manual Card Entry:** Process payments even by manually entering card details directly on the terminal. This provides a convenient backup option and expands your payment acceptance capabilities. Standalone Mode Manual Entry --- # Standalone Terminal Quickstart Source: https://docs.finix.com/guides/in-person-payments/standalone-terminals/standalone-terminals-quickstart Follow this guide to activate [Standalone Mode](/guides/in-person-payments/standalone-terminals) on your terminal and process your first transaction. ## 1. Unbox the Terminal Finix ships your terminal, and your Point of Contact provides a tracking number. If you order a device using the Device Store, you can find that information in your Finix Dashboard. Pax A800 Boxed Pax A800 Unboxed ## 2. Connect device to Wi-Fi and install updates ### Powering on the device The PAX A800 and PAX A920Pro come with a USB-C cable and a power adapter. *To power on the device*: 1. Connect the power adapter or USB-C cable to a power source. 2. Charge the device to at least 70%. 3. Once the device is charged, press and hold the power button down for 2 seconds until the LCD backlight turns on. ### Connecting to the internet Your device can connect to the internet via Wi-Fi or ethernet. To connect via ethernet, you will need a [PAX A800 Cable Hub](https://store.mpipos.com/products/a800-cable-hub-part-number-cm8-ng-1e0-cm8-ng-3e0?srsltid=AfmBOopILB4RDsodCXfgfhxy4dg-X28EiIotehl9vQQuLN9K6tFskAWO). Follow the provided instructions to connect the device. div div *To connect to the internet via Wi-Fi*: 1. From your device’s Home screen, tap on **Settings**. div img div 1. Tap on **Network & Internet**. Periodically, when accessing network settings, you will be prompted to enter a password. Try these password combinations. Contact [Finix Support](mailto:support@finix.com) if none work. - `pax9876@@` - `Dev9876@@` - `9876` - `9876@@` 1. Tap **Wi-Fi**. 2. Tap your network and connect to it. div img ### Install updates From the **Settings** screen, click **System Updates** to see if any updates are available; if so, update the device to the latest version. ## 3. Locate serial number div div You need the device's S/N to activate it later. If your device is not activated, you will see the Serial Number in the Payment app. div img If the S/N is not displayed, you can find it in two ways. ### Option A: On the device Find the S/N on the bottom of the device. ### Option B: Payment app div div *To find the S/N within the Payment App*: 1. Go to the Home screen. 2. Tap the **Payment App** icon. - The **Payment App** displays. div img div 1. Tap **Diagnostics**. - The **Diagnostics** screen appears. 2. Under the **Overview** section, write down the serial number. div img ## 4. Log into Finix Dashboard and activate device Ensure your device is connected to the internet, the Finix Payment App is open, and you have the serial number available. You should have received your invitation to access your Finix Dashboard account. *To add a new device*: 1. Log in to the [Finix Dashboard](https://finix.payments-dashboard.com/Login). 2. Click **Devices** from the left navigation. 3. Click **Add Payment Device**. Device Management - Add New Device If you have any questions, contact your Customer Delivery Manager. They can walk you through this activation step. ## 5. Select your device model 1. From the **Device Model** screen, select your device (e.g., PAX A800). 2. Click **Next Step**. Payment Devices - Device Model The **Device Details** screen displays. ## 6. Enter device details 1. On the **Device Details** screen, enter the device's **Serial Number**. Payment Devices - Device Details If you have already activated the device, Finix will display a warning for an existing device with the same serial number. Finix also provides a link to the activated device, warning that adding it again will override previous settings. 1. Enter a **Device Name**. 2. Enter a **Description** for the device. 3. Click **Next Step**. - The **Device Configuration** screen displays. ## 7. Configure the device *To enable standalone mode*: 1. Toggle **Allow Standalone Mode** and, if desired, **Allow Standalone Authorizations**. 2. Toggle any other settings you want to enable on the terminal. Payment Devices - Enable Standalone 1. Click **Add Device**. - You will see a confirmation message indicating that you added the device to your dashboard. - A **Payment Device** details page displays. ## 8. Activate the device Now that you have added the device to your dashboard, activate it next. 1. From the device details page, click **Activate Device**. Payment Devices - Activate Device An **Activate Device** popup displays. 1. Open the Payment App on your device. 2. From the dashboard, on the **Activate Device** popup, click **Activate Device**. - A **Device Activated** confirmation popup displays. 3. Click **Done**. You should now see the device as online on the **Payment Device** details page. Payment Devices - Device Online ## 9. Create your first transaction div div The payment device displays a screen where you can create a sale or authorization (if you enabled authorizations in standalone mode). *To create a transaction*: 1. Using the keypad, type the amount of the sale. 2. Tap **Next**. div img div Two options: - Tap **Confirm and Pay** to allow the buyer to tap, insert or swipe their card to pay. - Tap **Manually enter a card** to manually enter the card details. If you enabled tips when adding the device, a **Tip** screen displays that allows the user to leave a tip or tap **No Tip** to skip it. div img div ### Option 1: Confirm and Pay A page displays asking the buyer to tap, insert, or swipe their card. If the payment is approved, a **Payment Approved** screen displays, asking the user, "Would you like a receipt?". The options include **Print**, **Email**, **Text**, or **No Receipt**. div img div ### Option 2: Manually enter a card Manually enter the card details. You can use one of the [test codes](/additional-resources/developers/implementation-and-testing/testing-your-integration#testing-card-type). If the payment is approved, you can print the merchant receipt copy or tap **Done** to exit. div img ## Transactions and settings screens You have now completed your first transaction in standalone mode. Besides the **Checkout** screen, there are two other screens of the payment app that may be useful to know about: **Transactions** and **Settings**. div div ### Transactions You can view transactions on the Transactions screen in the Payment App. You can filter transactions by Payments, Authorizations, and Refunds, and tap the hamburger icon in the top-right corner to access advanced filtering. div img div ### Settings - **Checkout** - Configure device settings like tipping, receipts, surcharging, signatures - **Diagnostics** - View device, system, and connectivity details div img --- # Adjusting Volume on Pax A800 Source: https://docs.finix.com/guides/in-person-payments/troubleshooting-your-terminal/adjusting-volume-pax-a800 Follow these steps to adjust the volume on your Pax A800. ## Step-by-Step ### Adjusting volume on your Pax A800 1. Exit Payment App 2. Click on **Settings** 3. Click on **Sound** 4. Adjust the Media Volume to the desired level 5. Open Payment App The volume should now be adjusted to the selected level. img If the above options do not solve the problem, [contact the Finix Support Team](mailto:support@finix.com). --- # Battery Issues Source: https://docs.finix.com/guides/in-person-payments/troubleshooting-your-terminal/battery-issues Follow these steps to resolve battery-related problems with your payment terminal. ## Step-by-Step troubleshooting guide If you're experiencing battery issues with your payment terminal, try the following solutions: ### 1. Ensure proper charging - Charge the terminal for at least 30 minutes before use. - If charging fails, try a different charger if available. - For optimal performance, charge the terminal overnight. - Refer to your terminal's user guide for information on monitoring battery levels and factors affecting battery performance. ### 2. Return and replace the Terminal If the above options do not solve the problem, [contact the Finix Support Team](mailto:support@finix.com). --- # Charging Pax Device Source: https://docs.finix.com/guides/in-person-payments/troubleshooting-your-terminal/charging-pax Follow these steps to diagnose and resolve charging-related problems with your Finix payment device. ## Step-by-step troubleshooting guide ### Charger issues If you're experiencing issues with your device's charger or suspect damage to the power connector, try the following solutions: #### 1. Inspect the charger and device - Make sure you are using the cable that came with your device or a compatible charger. - If you have a second device, test the charger with on the second device of the same model to isolate the issue. - Carefully examine the connectors on both the charger and device for any signs of damage. - Clean any dust or debris from the charging ports. #### 2. Perform a device restart - Power off the device completely. - Wait for 10 seconds, then turn it back on. After restarting, check if the charger is now functioning properly and charging the battery (if applicable). #### 3. Replace the charger or device - Try using a new charger compatible with your device model. - If problems persist with a new charger, the device's power connector may be faulty. #### 4. Contact Finix support If the above options do not solve the problem, [contact the Finix Support Team](mailto:support@finix.com). ### Battery charge modes for Pax A800 and A920Pro You can set the battery charge mode for your device that best suits your business needs. To access the battery charge mode, follow the steps below: 1. Navigate to the **Settings** 2. Click on **Battery** 3. Click on **Battery Manager** 4. Click on **Select Charging Mode** 5. Select the desired battery charge mode. #### Battery charge mode descriptions - **Desktop Mode** - Device is allowed to charge up to 80%. - **Mobile Mode** - Device is allowed to charge up to 100%. - **Smart Charging** - Devices will automatically recognize user behavior and adapt to a battery mode every 7 days. - If time spent on the charger exceeds the amount of time spent not on the charger, terminal battery mode is set to Desktop Mode. - If time spent off of the charger exceeds time spent on the charger, terminal battery mode is set to Mobile Mode. Pax Charging Modes --- # Device Connectivity Source: https://docs.finix.com/guides/in-person-payments/troubleshooting-your-terminal/device-connectivity Learn how to troubleshoot issues around device connectivity. ## Network requirements - Your network must support IPv4. IPv6-only networks aren’t supported. ## Step-by-Step troubleshooting guide If you're encountering issues with device connectivity please verify the following settings. ### Disable e-Sim settings The devices operate only on Wifi or Ethernet connectivity please verify that cellular eSim is disabled. 1. Access the Settings Menu - Tap the "Settings" app (usually represented by a gear icon). 2. Navigate to SIM Settings - In the Settings menu, scroll and tap on "Network & Internet" 3. Open ESIM Network Settings - Toggle off eSIM Card option 4. Return to Network & Internet and tap on "Advanced" - Tap on "SIM cards" 5. Disable the SIM - Toggle off all the sim slots. ie "SIM slot 1" and "SIM slot 2". ### Troubleshoot wifi Network connectivity #### 1. Verify Wi-Fi router functionality - Test the Wi-Fi network with another device (e.g., smartphone or laptop) - If other devices cannot connect, it may be an issue with the router. - You can try restarting the router and retest the connection. - If other devices connect successfully but the terminal does not, continue to the next step. #### 2. Refresh Terminal's Wi-Fi connection - Access the terminal's Admin menu - Navigate to Network > Wi-Fi - Select your network, disable and re-enable the Wi-Fi - If the issue persists, proceed to the next step #### 3. Perform a Terminal reboot - Power off the device completely - Wait a few seconds, then turn it back on #### 4. Verify firewall settings If you have a firewall on your network please verify you have whitelisted the following URLs: - Sandbox: - `https://api.paxstore.us/` - `rkilt.pax.us:33619` - Production: - `https://api.paxstore.us/` - `rki.pax.us:33519` #### 5. Contact support If the above options do not solve the problem, [contact the Finix Support Team](mailto:support@finix.com). ### Ethernet connectivity To connect the Pax A800 via ethernet you'll need to have an additional Pax communication hub. Please reach out to support about acquiring additional hubs. Each Pax communication hub will have its own unique MAC address that will be associated with the connected A800 device. If the above options do not solve the problem, contact the [Finix Support Team](mailto:support@finix.com). --- # Device Unreachable Source: https://docs.finix.com/guides/in-person-payments/troubleshooting-your-terminal/device-unreachable Learn how to troubleshoot Device Unreachable issues. ## Step-by-Step troubleshooting guide If you're encountering a "Device Unreachable" error, it means your terminal is unable to connect to the Finix backend server. This guide will walk you through several steps to try and resolve this connectivity issue and get your device back online. ### 1. Verify payment app status - Ensure the Payment App is running on the device - If not, launch the Payment App and perform a test transaction ### 2. Check device time zone - Confirm that the Time Zone displayed on the device matches your current location - If incorrect, adjust the time zone in the Device settings ### 3. Verify Wi-Fi router functionality - Test the Wi-Fi network with another device (e.g., smartphone or laptop) - If other devices cannot connect, it may be an issue with the router. - You can try restarting the router and retest the connection. - If other devices connect successfully but the terminal does not, continue to the next step. ### 4. Refresh Terminal's Wi-Fi connection - Access the terminal's Admin menu - Navigate to Network > Wi-Fi - Select your network, disable and re-enable the Wi-Fi - If the issue persists, proceed to the next step ### 5. Perform a Terminal reboot - Power off the device completely - Wait a few seconds, then turn it back on ### 6. Verify firewall settings If you have a firewall on your network please verify you have whitelisted the following urls: - Sandbox: - `https://api.paxstore.us/` - `rkilt.pax.us:33619` - Production: - `https://api.paxstore.us/` - `rki.pax.us:33519` ### 7. Contact support If the above options do not solve the problem, [contact the Finix Support Team](mailto:support@finix.com). --- # Troubleshooting Your Terminal Source: https://docs.finix.com/guides/in-person-payments/troubleshooting-your-terminal In this guide, you can learn common issues that can arise with payment terminals when the Payment Terminal turns on. ## What problems does your device have? Battery Issues There is a problem with the battery on the terminal. Charging Pax Device The charger is not operating as expected. Device Connectivity Learn how to troubleshoot issues around device connectivity. Device Unreachable Payments failing due to Device Unreachable Error. Powering Off Device I want to power off my terminal. Printer Issues The terminal's printer is not functioning correctly. Scheduled Reboot Time I want to configure the scheduled reboot time. Terminal Not Powering On Follow these steps to resolve power-related problems with your Finix payment terminal. Time Settings The terminal's time settings are incorrect. Update Your Payment Version I need to update my Pax Payment App Version. PAX D135 Troubleshooting Resolve common PAX D135 device issues. --- # PAX D135 Troubleshooting Source: https://docs.finix.com/guides/in-person-payments/troubleshooting-your-terminal/pax-d135-troubleshooting Common error codes and solutions for the PAX D135 card reader. ## Error 4002 — Card Read Failure (EL_TRANS_RET_READ_CARD_FAIL) This error indicates a general card read failure from the PAX D135. ### Possible causes - Card not positioned properly over the NFC reader - Card removed before the read completed - Weak or damaged card NFC antenna - Dirty or damaged chip contacts (for chip cards) - RF/EMI interference from nearby electronics - Poor Bluetooth connection between the phone and the reader - Dirty magnetic stripe or reader head (for swipe transactions) Hold your card steady on the reader for 1–2 seconds until you see confirmation. ## Error 4006 — NFC Interference Devices with their own NFC reader can cause interference with the D135. It is advised not to directly mount the D135 to the back of a phone. ### Disabling NFC on Android Certain Android models allow you to disable the phone's NFC via settings: 1. Go to **System Settings** Android System Settings 1. Tap **Connected Devices** Connected Devices menu 1. Tap **Connection Preferences** Connection Preferences menu 1. Tap **NFC** and switch the toggle off NFC toggle off ## Restarting the Device If the device is unresponsive, you may need to hold the power button for up to 30 seconds to fully restart it. ## Charging the Device Charge the battery only with PAX-approved power supplies. Using others may damage the product and void the warranty. Charging time must not exceed 24 hours. If the battery is empty, recharge it fully, then disconnect the device to avoid shortening its life. --- # Powering Off Device Source: https://docs.finix.com/guides/in-person-payments/troubleshooting-your-terminal/powering-off-device Follow these steps to power off your terminal. ## Step-by-Step troubleshooting guide If you need to power off your terminal, follow the steps below. ### Powering off your Terminal 1. Navigate to the **Settings** within the Payment App. 2. Click on **Exit App**. Pax A800 Exit App 1. Confirm the action by clicking on **Exit**. Pax A800 Exit App Modal 1. Hold down the **Power button** until the prompt appears to power off the terminal. Pax A800 Power Off Button If the above options do not solve the problem, [contact the Finix Support Team](mailto:support@finix.com). --- # Printer Issues Source: https://docs.finix.com/guides/in-person-payments/troubleshooting-your-terminal/printer-issues Follow these steps to resolve printer-related problems with your Finix payment terminal. ## Common printer issues - Terminal does not print any receipts - Receipts are faded or incomplete ## Step-by-Step troubleshooting guide ### 1. Verify receipt functionality is enabled Before troubleshooting hardware issues, ensure that receipt functionality is enabled for your terminal in the Finix Dashboard. ### 2. Check the receipt paper - Ensure that there is sufficient paper in the roll. - If the paper is low or empty, replace the receipt roll with a new one. If you need to order more receipt paper, please [contact our support team](mailto:support@finix.com). ### 3. Inspect the Terminal's printer - Open the receipt roll cover. - Remove any dust and paper scraps. - Check for any obstructions that could block the receipt roll. - Inspect for loose or broken parts. ### 4. Test the printer After completing the inspection and any necessary cleaning or replacement: - Close the receipt roll cover securely. - Attempt to print a test receipt. ### 5. Contact Finix support If the above options do not solve the problem, [contact the Finix Support Team](mailto:support@finix.com). --- # Scheduled Reboot Time Source: https://docs.finix.com/guides/in-person-payments/troubleshooting-your-terminal/scheduled-reboot-time Follow these steps to schedule a reboot time for your payment terminal. ## Step-by-Step troubleshooting guide If you need to schedule a specific time for your payment terminal to reboot, follow the steps below. Please note that your terminal will need to be powered on for the scheduled reboot to occur. ### Setting scheduled reboot time 1. Navigate to the Security in the Settings App on your terminal Pax Settings UI Pax A800 Security Settings 1. Select Scheduled Reboot Time Pax A800 Security Scheduled Reboot 1. Toggle Scheduled Reboot Time to On Pax A800 Security Scheduled Reboot Off Pax A800 Security Scheduled Reboot On 1. Click on Set Reboot Time and select the desired reboot time Pax A800 Security Scheduled Reboot Clock If the above options do not solve the problem, [contact the Finix Support Team](mailto:support@finix.com). --- # Terminal Not Powering On Source: https://docs.finix.com/guides/in-person-payments/troubleshooting-your-terminal/terminal-not-powering-on Follow these steps to resolve power-related problems with your Finix payment terminal. ## Step-by-Step troubleshooting guide ### 1. Check power connection - Ensure that the power cord is properly plugged into both the terminal and the power outlet. - If using a power strip or surge protector, make sure it's turned on and functioning. ### 2. Charge the Terminal - Connect the terminal to its power source and allow it to charge for at least 30 minutes. - Look for any indicators that show the device is charging. ### 3. Attempt manual power on - Hold the power button for at least 3 seconds to attempt powering on the device. - If successful, allow the terminal to complete its startup process. ### 4. Inspect for physical damage - Check the terminal and power cord for any signs of physical damage. - Look for bent pins in the charging port or frayed wires on the power cord. ### 5. Contact Finix support If the above options do not solve the problem, [contact the Finix Support Team](mailto:support@finix.com). --- # Time Settings Source: https://docs.finix.com/guides/in-person-payments/troubleshooting-your-terminal/time-settings Follow these steps to resolve your payment terminal showing the incorrect time. ## Step-by-Step troubleshooting guide If your payment terminal is showing the incorrect time, try the following solution: ### Setting correct time setting 1. Navigate to the **System** in the Settings App on your terminal PAX terminal Settings menu screen Pax System Settings 1. Select **Date & Time** PAX terminal Date and Time settings screen 1. Temporarily disable "Use network-provided time zone" 2. Manually set your correct time zone 3. Re-enable "Use network-provided time zone" 4. Enable "Use network-provided time" PAX terminal Date and Time settings with network-provided time option enabled If the above options do not solve the problem, [contact the Finix Support Team](mailto:support@finix.com). --- # Update Your Payment Version Source: https://docs.finix.com/guides/in-person-payments/troubleshooting-your-terminal/update-your-payment-version Follow these steps to update your Pax Payment App Version. ## Step-by-Step troubleshooting guide ### Step 1: Navigate to the App Store on your terminal Pax A800 Pax Store ### Step 2: Search for payment app and click update Pax A800 Pax Store If the above options do not solve the problem, [contact the Finix Support Team](mailto:support@finix.com). --- # Updating Pax Termlink Source: https://docs.finix.com/guides/in-person-payments/troubleshooting-your-terminal/updating-pax-termlink You do not need to manually update your Pax Termlink, this update is handled by Finix. However, you can follow these steps to confirm that your Pax Termlink has updated. By swiping down from the top of the screen on the terminal you should see the following screen: Pax Termlink Update If you do not see the above screen, please contact [Finix Support](mailto:support@finix.com) to help you update your Pax Termlink. If you see the above screen, you can confirm that your Pax Termlink has updated. --- # Building Your Mobile Integration Source: https://docs.finix.com/guides/in-person-payments/building-your-integration/mobile-integration Finix offers the following mobile in-person payments integrations: 1. **Tap to Pay on iPhone**: Accept contactless payments directly on iPhone with no card reader or extra hardware. 2. **PAX D135 Android SDK**: Connect a PAX D135 Bluetooth card reader to your Android app. 3. **PAX D135 iOS SDK**: Connect a PAX D135 Bluetooth card reader to your iOS app. ## Tap to Pay on iPhone integrations Tap to Pay on iPhone Branding Accept contactless payments on iPhone with no card reader or extra hardware using the Finix Tap to Pay on iPhone SDK. For additional details on the Tap to Pay on iPhone SDK, see [Tap to Pay on iPhone Overview](/guides/in-person-payments/building-your-integration/mobile-integration/tap_to_pay_iphone_quickstart). ## PAX D135 integrations The D135 connects via Bluetooth and supports Tap, Insert, and Swipe payments without a dedicated terminal. Finix provides native SDKs for both Android and iOS to handle device pairing, payment processing, and receipts. PAX D135 Bluetooth card reader with Finix branding Read the [PAX D135 Overview](/guides/in-person-payments/select-your-device/pax-d135) to learn more about the PAX D135's capabilities. ### Environment designation When ordering a PAX D135, specify whether each Device is designated for Sandbox or Production. Finix provides you with the serial number assigned to each Device. Device Designation A D135 Device can be designated for either Sandbox development or Production transaction processing **but not both**. We recommend requesting enough devices to utilize in both your Sandbox development and Production testing. ### Prerequisites - Your PAX D135 device is fully charged. - **For Android devices**: Android 8.0 (API level 26) or higher. - **For iOS devices**: iOS 18.1 or higher. Charging the Device Charge the battery only with PAX-approved power supplies. Using others may damage the product and void the warranty. Charging time must not exceed 24 hours. If the battery is empty, recharge it fully, then disconnect the device to avoid shortening its life. ### Device limits The D135 card reader accepts payments via Tap, Insert, or Swipe. You can accept Tap payments for amounts under $1,000. For larger amounts, insert the card into the card reader. ## Next steps Integration Prerequisites Complete the prerequisite steps for integrating the PAX D135 with the Finix Android or iOS SDK. Android SDK Install and initialize the Finix Android SDK, connect to your D135, and process your first transaction. iOS SDK Install and initialize the Finix iOS SDK, connect to your D135, and process your first transaction. Tap to Pay on iPhone Accept contactless payments on iPhone with no card reader or extra hardware using the Finix Tap to Pay on iPhone SDK. Android Demo App Explore a sample Android app built with the Finix mobile SDK and PAX D135. iOS Demo App Explore a sample iOS app built with the Finix mobile SDK and PAX D135. --- # PAX D135 integration prerequisites Source: https://docs.finix.com/guides/in-person-payments/building-your-integration/mobile-integration/integration-prerequisites Before integrating the PAX D135 with the Android or iOS SDK, complete the following one-time setup. These steps configure your device's environment, establish your API credentials, and register your PAX D135 with Finix. ## Environment designation When ordering a PAX D135, specify whether each Device is designated for Sandbox or Production. Finix provides you with the serial number assigned to each Device. Device Designation A D135 Device can be designated for either Sandbox development or Production transaction processing **but not both**. We recommend requesting enough devices to utilize in both your Sandbox development and Production testing. ## Prerequisites - Your PAX D135 device is fully charged. - **iOS:** iOS 18.1 or higher. - **Android:** Android 8.0 (API level 26) or higher. Charging the Device Charge the battery only with PAX-approved power supplies. Using others may damage the product and void the warranty. Charging time must not exceed 24 hours. If the battery is empty, recharge it fully, then disconnect the device to avoid shortening its life. ### Network requirements The PAX D135 downloads its encryption keys from PAX servers during first-time configuration. This traffic uses the internet connection of the phone or tablet the D135 is paired with. If that network has a firewall, allow the following PAX hosts for the environment your Device is designated for: | Environment | Host | | --- | --- | | Sandbox | `rkilt.pax.us:33619` | | Production | `rki.pax.us:33519` | ## 1. Creating user credentials The SDK supports the use of either `ROLE_PARTNER` or `ROLE_MERCHANT` credentials. If you would like to scope your device to a single Merchant, it is recommended to use `ROLE_MERCHANT` credentials. If you plan to use the Device across multiple merchants, you should use `ROLE_PARTNER` credentials. [Split Transactions](/guides/online-payments/payment-features/split-transactions) require the use of `ROLE_PARTNER` credentials. ### Creating ROLE_MERCHANT credentials Create a User with `role: ROLE_MERCHANT`. ```shell curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/users \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "role": "ROLE_MERCHANT", "identity_id": "ID6YeRojM2ppNkPt4mP8ExNH" }' ``` You can use the credentials across multiple devices as long as the devices are associated with the same Merchant. ### Creating ROLE_PARTNER credentials To create `ROLE_PARTNER` credentials: 1. Log in to the [Finix Dashboard](https://live.payments-dashboard.com/Login). 2. Select the environment for which you would like to create the API credentials (Sandbox or Live). 3. In the bottom left-hand corner, click **Developer**. 4. From the **API Keys** tab, click **Create API Key**. Create API Key ## 2. Creating a Device Creating a Device can be done either using the Finix Dashboard or the Finix API. Below are the steps for creating a Device using the API. Create a Device under the Merchant provisioned to process in-person payments. Include the `model` of the payment terminal you'll be using to process cards. Choose the payment terminal that best fits your business needs. View our [available devices](/guides/in-person-payments/select-your-device) to compare options. ```shell Request curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/merchants/MUwfZPNW3r4EqLMzwgr6txw4/devices \ -H 'Content-Type: application/json' \ -d '{ "description": "Cashier Three", "model": "PAX_D135", "name": "My PAX_D135 Finix Device", "serial_number": "19046260947" }' ``` ```json Response { "id": "DVxcL2fiBdt9frYCKAbZikZK", "created_at": "2025-05-21T19:01:32.000581Z", "updated_at": "2025-05-21T19:01:32.000581Z", "configuration_details": { "allow_debit": true, "check_for_duplicate_transactions": true, "prompt_amount_confirmation": true, "prompt_manual_entry": false, "signature_threshold_amount": 10000, "bypass_device_on_capture": true, "prompt_receipt_confirmation": true, "display_tip_on_receipt": false, "prompt_tip_on_screen": false, "allow_standalone_authorizations": false, "allow_standalone_sales": false, "allow_standalone_refunds": false, "tipping_details": { "percent_tipping_threshold": 0, "percent_options": [18, 20, 22], "fixed_options": [100, 150, 200] }, "idle_message": null, "idle_image_file_id": null, "automatic_receipt_delivery_methods": null, "available_receipt_methods": null, "prompt_for_signature": "NEVER", "surcharge_basis_points": null }, "description": "Cashier Three", "enabled": false, "idle_message": null, "merchant": "MU7noQ1wdgdAeAfymw2rfBMq", "model": "PAX_D135", "name": "My PAX_D135 Finix Device", "serial_number": "19046260947", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/devices/DVxcL2fiBdt9frYCKAbZikZK" }, "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MU7noQ1wdgdAeAfymw2rfBMq" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/transfers" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/authorizations" } } } ``` ## Next steps Android SDK Install and initialize the Finix Android SDK, connect to your D135, and process your first transaction. iOS SDK Install and initialize the Finix iOS SDK, connect to your D135, and process your first transaction. --- # PAX D135 Android Quickstart Source: https://docs.finix.com/guides/in-person-payments/building-your-integration/mobile-integration/pax_d135_android_quickstart Use the Finix Android SDK to integrate the PAX D135 Bluetooth card reader into your Android app and accept in-person payments. This guide covers SDK installation, initialization, and processing your first transaction. Prerequisites Before starting, complete the [Integration Prerequisites](/guides/in-person-payments/building-your-integration/mobile-integration/integration-prerequisites) to configure your environment, credentials, and a Device resource. ## 1. Installation and initialization ### Installation Add the dependency to your Gradle file. See [Maven Central](https://central.sonatype.com/artifact/com.finix/pax-mpos-sdk-android) or [MVN Repository](https://mvnrepository.com/artifact/com.finix/pax-mpos-sdk-android) for the latest version. ```kotlin implementation("com.finix:pax-mpos-sdk-android:3.7.0") ``` Upgrading SDK version from v2.x SDK version 3.0.0 is a major update and is not compatible with earlier versions (2.x.x or below). If you use D135 readers in Production on SDK version 2.0.0 or above, contact Finix before updating. We will help guide the rollout and provide extra devices if needed. ### Initialization Add permissions to the AndroidManifest to interact with the mPOS device via Bluetooth. ```xml ``` To interact with the MPOS device, the SDK first needs to be initialized. This can be done by initializing the `mposFinix` class. ```kotlin Initialize class mposFinix(private val context: Context, private val merchantData: MerchantData) context: Android application context merchantData: Specific values which help identify the merchant class MerchantData ( // Merchant Id from Finix starting with MUxxxx val merchantId: String, // Finix mid (GUID representation) val mid: String, // Device ID - device registers with Finix, starting with DVxxxx val deviceId: String, val currency: Currency = Currency.USD, // Sandbox or Production val env: EnvEnum = EnvEnum.SB, // ROLE_MERCHANT or ROLE_PARTNER UserId val userId : String, // ROLE_MERCHANT or ROLE_PARTNER password val password: String ) Example : val mpos = mposFinix( context, MerchantData( merchantId = "MUxxxxxx", mid = "", deviceId = "DVxxxxx", env = EnvEnum.SB, userId = "USxxxxxxxxx", password = "" ) ) ``` Once initialized, connect to the device. When the device is ready for pairing, it will show an orange light and a green light. Once connected, the orange light will disappear and only the green light will stay on. First Time Device Configuration When first pairing a PAX D135 the initial configuration may take a few minutes to complete. We recommend that the user experience you build factors in the configuration time to ensure that the user knows the device configuration is in progress. ```kotlin Connect fun connect(deviceName: String, deviceAddress: String, callback: MPOSConnectionCallback) deviceName : bluetooth name of the device deviceAddress : bluetooth address of the device callback: exposes functions which are invoked to propagate success, error, progress interface MPOSConnectionCallback { fun onSuccess() // Called if the connection is successfully established fun onError(errorMessage: String) // Called if the connection fails for some reason fun onProcessing(currentStepMessage: String) // Provides status messages of what's currently happening } ``` ## 2. Creating a Device Create a Device under the Merchant provisioned to process in-person payments. Include the `model` of the payment terminal you'll be using to process cards. Example API Definition A successful response returns the Device resource you will use to initialize the SDK. Example Model PAX_D135 Device ```json Model PAX_D135 Device { "id": "DVepZf9V5c4tDPFC9qFe4fnD", "created_at": "2026-09-25T20:05:16.506309Z", "updated_at": "2026-09-25T20:05:16.506309Z", "configuration_details": { // [!code highlight] "allow_debit": true, "allow_standalone_authorizations": false, "allow_standalone_refunds": false, "allow_standalone_sales": false, "automatic_receipt_delivery_methods": null, "available_receipt_methods": null, "bypass_device_on_capture": true, "check_for_duplicate_transactions": true, "display_tip_on_receipt": false, "idle_image_file_id": null, "idle_message": null, "prompt_amount_confirmation": true, "prompt_for_signature": "NEVER", "prompt_manual_entry": false, "prompt_receipt_confirmation": true, "prompt_tip_on_screen": false, "signature_threshold_amount": 10000, "surcharge_basis_points": null, "tipping_details": { "fixed_options": [ 100, 150, 200 ], "percent_options": [ 18, 20, 22 ], "percent_tipping_threshold": 0 } }, "description": "Cashier Three", "enabled": true, "idle_message": null, "integration_mode": "PAYMENT_APP", "merchant": "MUiV7ntxfY4eyJxp6E7cZvym", "model": "PAX_D135", "name": "My PAX_D135 Finix Device", "serial_number": "1904626094", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/devices/DVepZf9V5c4tDPFC9qFe4fnD" }, "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MUiV7ntxfY4eyJxp6E7cZvym" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/transfers" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/authorizations" } } } ``` API Definition ## 3. Starting a transaction To start a transaction, call the `startTransaction()` function. This will prep the mPOS device to accept card input (swipe, tap, insert). A blue status light displays. Once any action is performed with the card, the device will show a red light to indicate the card has been read. Remove the card at this point. ```kotlin Start Transaction fun startTransaction( amount: Long, idempotencyId: String? = null, transactionType: TransactionType, transactionCallback: MPOSTransactionCallback, splitTransfers: List? = null, tags: Map? = null, buyerIdentityId: String? = null, surcharge: Long? = null, tipAmount: Long? = null, promptForSignature: PromptForSignature = PromptForSignature.Never ) ``` | Field | Type | Description | | --- | --- | --- | | `amount` | *Long*, **required** | Amount in cents. e.g. for $10.10, this value would be 1010. | | `idempotencyId` | *String?*, **optional** | A randomly generated or internal ID to idempotently identify Transfers, Authorizations, or refund requests. | | `transactionType` | *TransactionType*, **required** | TransactionType enum - Sale, Refund, or Authorization. | | `transactionCallback` | *MPOSTransactionCallback*, **required** | Callback invoked with the status of the transaction or the Transaction Result. | | `splitTransfers` | *List?*, **optional** | Optional list of split transfer request data. | | `tags` | *Map?*, **optional** | Optional map of key/value strings to be provided in the request. | | `buyerIdentityId` | *String?*, **optional** | Optional buyer identity associated with this transaction. | | `surcharge` | *Long?*, **optional** | Optional surcharge amount in cents. | | `tipAmount` | *Long?*, **optional** | Optional tip amount in cents. | | `promptForSignature` | *PromptForSignature*, **optional** | Setting that determines whether a signature should be collected. | ```kotlin MPOSTransactionCallback interface MPOSTransactionCallback { // Called if the transaction is successfully processed fun onSuccess(result: TransactionResult?) // Called if the transaction fails for any reason fun onError(errorMessage: String) // Provides status messages of what's currently happening fun onProcessing(currentStepMessage: String) } ``` ```kotlin PromptForSignature sealed interface PromptForSignature { // A signature should always be collected object Always : PromptForSignature // A signature should never be collected object Never : PromptForSignature // A signature is collected if the amount is greater than or equal to the [thresholdAmount] class ThresholdAmount( val thresholdAmount: Long, ) : PromptForSignature // A signature is collected based on the response from the card network object OnNetworkRecommendation : PromptForSignature } ``` ## Signature upload When a transaction succeeds, a signature upload can be performed if `TransactionResult.signaturePending` in `MPOSTransactionCallback.onSuccess` is true. `signaturePending` is determined by the `promptForSignature` value passed with the transaction. For example, if a transaction was made with `amount=500` and `promptForSignature=PromptForSignature.ThresholdAmount(400)`, `signaturePending` will be true. In this case your app should capture a signature from the user and call `uploadSignature`. ```kotlin Signature Upload fun uploadSignature( // Base64 encoded png of the signature pngEncodedBase64: String, // traceId of the successful transaction, found in TransactionResult traceId: String, ) ``` ## Referenced refund A referenced refund refunds the amount specified (refund amount) of a particular transaction (transaction id) to the card on file. ```kotlin Referenced Refund fun startRefund( idempotencyId: String? = null, transactionId: String, refundAmount: Long, refundCallback: MPOSRefundCallback ) ``` | Field | Type | Description | | --- | --- | --- | | `idempotencyId` | *String?*, **optional** | A randomly generated or internal ID to idempotently identify Transfers, Authorizations, or refund requests. | | `transactionId` | *String*, **required** | The transaction ID correlating to a previous transaction. Returned as part of the `TransactionResult`. | | `refundAmount` | *Long*, **required** | Amount in cents. e.g. for $10.10, this value would be 1010. | | `refundCallback` | *MPOSRefundCallback*, **required** | Callback invoked with the status of the refund or the Refund Result. | ## Proguard rules If you are using ProGuard, please add the following to your ProGuard rules. ```txt #Retrofit -dontwarn retrofit.** -keep class retrofit.** { *; } -keepattributes Signature -keepattributes Exceptions -keepattributes RuntimeVisibleAnnotations -keepattributes RuntimeInvisibleAnnotations -keepattributes RuntimeVisibleParameterAnnotations -keepattributes RuntimeInvisibleParameterAnnotations #OkHttp3 -keepattributes Signature -keepattributes *Annotation* -keep class okhttp3.** { *; } -keep interface okhttp3.** { *; } -dontwarn okhttp3.** -dontwarn java.nio.file.* -dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement #Gson -keep class com.google.gson.stream.** { *; } #Finix -dontwarn com.finix.mpos.sdk.** -keep class com.finix.mpos.sdk.** { *; } -keep class com.finix.mpos.models.** { *; } -keep class com.finix.common.networking.models.** { *; } -dontwarn java.lang.invoke.StringConcatFactory ``` ## Troubleshooting If you encounter issues, use `sendDebugReport` to collect diagnostic information from the Device and send the logs to Finix Support to help troubleshoot the issue. ```kotlin Send Report - Android fun sendDebugReport(sendReportCallback: MPOSSendReportCallback) interface MPOSSendReportCallback { fun onError(errorMessage: String?) fun onSuccess(result: LogsResponse?) } ``` Note Alternatively, you can [send debug logs using the Sample App](/guides/in-person-payments/building-your-integration/mobile-integration/pax_d135_sample_app_troubleshooting). ### Firewall settings The PAX D135 downloads its encryption keys from PAX servers during first-time configuration. This traffic uses the internet connection of the phone or tablet the D135 is paired with. If that network has a firewall, allow the following PAX hosts for the environment your Device is designated for: | Environment | Host | | --- | --- | | Sandbox | `rkilt.pax.us:33619` | | Production | `rki.pax.us:33519` | --- # PAX D135 iOS Quickstart Source: https://docs.finix.com/guides/in-person-payments/building-your-integration/mobile-integration/pax_d135_ios_quickstart Use the Finix iOS SDK to integrate the PAX D135 Bluetooth card reader into your iOS app and accept in-person payments. This guide covers SDK installation, initialization, and processing your first transaction. Prerequisites Before starting, complete the [Integration Prerequisites](/guides/in-person-payments/building-your-integration/mobile-integration/integration-prerequisites) to configure your environment, credentials, and a Device resource. ## 1. SDK setup and connection ### Installation Add the [SDK](https://github.com/finix-payments/finix-pax-mpos-ios-sdk) to your project via Swift Package Manager using: ```text https://github.com/finix-payments/finix-pax-mpos-ios-sdk ``` ### Initialization Pre-requisites - iOS 15.6 or later - iOS device. Simulator not supported - Add Bluetooth permission in Info.plist using key Privacy - `Bluetooth Always Usage Description` To interact with the MPOS device, first initialize the SDK ```swift import PaxMposSDK let finixClient = FinixClient(config: FinixConfig( environment: TEST_ENVIRONMENT, credentials: Finix.APICredentials(username: TEST_USERNAME, password: TEST_PASSWORD), application: TEST_APPLICATION, version: TEST_VERSION, merchantId: TEST_MERCHANT_ID, mid: TEST_MERCHANT_MID, deviceType: .Pax, deviceId: "") //Device ID - device registers with Finix, starting with DV (i.e. DVxxxx) ) finixClient.delegate = self finixClient.interactionDelegate = self ``` Once initialized, connect to the Device. When the Device is ready for pairing, it will show an orange light and green light. Once connected, the orange light will disappear and only the green light will stay on. First Time Device Configuration When first pairing a PAX D135 the initial configuration may take a few minutes to complete. We recommended that the user experience you build factors in the configuration time to ensure that the user knows the device configuration is in progress. ### Scanning for devices Call `startScan()` to scan for nearby D135 devices over Bluetooth. The `didDiscoverDevice` callback fires for each Device found. ```swift finixClient.startScan() extension ViewController: FinixDelegate { func didDiscoverDevice(_ deviceInfo: DeviceInfo) { devices.append(deviceInfo) } } ``` ### Connecting to the device Pass the selected device's Bluetooth ID (`device.id`) to `connectDevice()`. The `deviceDidConnect` callback fires when the connection is established. ```swift finixClient.connectDevice(device.id) extension ViewController: FinixDelegate { func deviceDidConnect(_ deviceInfo: DeviceInfo) { connectedDevice = deviceInfo } } ``` ## 2. Creating a Device Create a Device under the Merchant provisioned to process in-person payments. Include the `model` of the payment terminal you'll be using to process cards. Example API Definition A successful response returns the Device resource you'll use to initialize the SDK. Example Model PAX_D135 Device ```json Model PAX_D135 Device { "id": "DVepZf9V5c4tDPFC9qFe4fnD", "created_at": "2026-09-25T20:05:16.506309Z", "updated_at": "2026-09-25T20:05:16.506309Z", "configuration_details": { // [!code highlight] "allow_debit": true, "allow_standalone_authorizations": false, "allow_standalone_refunds": false, "allow_standalone_sales": false, "automatic_receipt_delivery_methods": null, "available_receipt_methods": null, "bypass_device_on_capture": true, "check_for_duplicate_transactions": true, "display_tip_on_receipt": false, "idle_image_file_id": null, "idle_message": null, "prompt_amount_confirmation": true, "prompt_for_signature": "NEVER", "prompt_manual_entry": false, "prompt_receipt_confirmation": true, "prompt_tip_on_screen": false, "signature_threshold_amount": 10000, "surcharge_basis_points": null, "tipping_details": { "fixed_options": [ 100, 150, 200 ], "percent_options": [ 18, 20, 22 ], "percent_tipping_threshold": 0 } }, "description": "Cashier Three", "enabled": true, "idle_message": null, "integration_mode": "PAYMENT_APP", "merchant": "MUiV7ntxfY4eyJxp6E7cZvym", "model": "PAX_D135", "name": "My PAX_D135 Finix Device", "serial_number": "1904626094", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/devices/DVepZf9V5c4tDPFC9qFe4fnD" }, "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MUiV7ntxfY4eyJxp6E7cZvym" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/transfers" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/authorizations" } } } ``` API Definition ## 3. Starting a transaction Update the client with the Finix Device ID, then call `startTransaction()`. The device shows a blue light and prompts the customer to tap, swipe, or insert their card. Once the card is read, the light turns red, indicating the customer should remove their card. ```swift finixClient.update(deviceId: "DVxxxxx") ``` ```swift let transactionAmount = Currency(amount: Int(amountDouble * 100), code: .USD) finixClient.startTransaction( amount: transactionAmount, type: transactionType, splitTransfers: nil, tags: nil, buyerIdentityId: nil ) { transferResponse, error in Task { @MainActor in // Handle using transferResponse and error } } ``` ## Referenced refund A referenced refund refunds the amount specified (refund amount) of a particular transaction (transaction ID) to the card on file. ```swift /// Start a referenced refund func startRefund(transactionID: String, amount: Currency, completion: ((RefundResponse?, Error?) -> Void)?) { let mainCompletion: (RefundResponse?, Error?) -> Void = { response, error in if let error { self.logger.error("startRefund failed with error: \(error)") } DispatchQueue.main.async { completion?(response, error) } } let externalEndpoint = FinixAPIEndpoint.externalEndpoint(config.environment) let endPoint = "transfers/\(transactionID)/reversals" guard let url = URL(string: endPoint, relativeTo: externalEndpoint) else { mainCompletion(nil, FinixError(code: .MalformedRequest, message: "Could not encode path!")) return } guard let request = requestBuilder(url: url, method: .POST, payload: ["refund_amount": amount.amount]) else { mainCompletion(nil, FinixError(code: .CannotEncodeParameters, message: "Cannot encode request parameters")) return } finixRequest(request: request) { (response: RefundResponse?, error: Error?) in print(response as Any, error as Any) mainCompletion(response, error) } } ``` ## Troubleshooting If you encounter issues, use `sendDebugReport` to collect diagnostic information from the Device and send the logs to Finix Support to help troubleshoot the issue. ```swift Send Debug Data - iOS func sendDebugData() {} ``` Note Alternatively, you can [send debug logs using the Sample App](/guides/in-person-payments/building-your-integration/mobile-integration/pax_d135_sample_app_troubleshooting). ### Firewall settings The PAX D135 downloads its encryption keys from PAX servers during first-time configuration. This traffic uses the internet connection of the phone or tablet the D135 is paired with. If that network has a firewall, allow the following PAX hosts for the environment your Device is designated for: | Environment | Host | | --- | --- | | Sandbox | `rkilt.pax.us:33619` | | Production | `rki.pax.us:33519` | --- # Troubleshooting with the PAX D135 Sample App Source: https://docs.finix.com/guides/in-person-payments/building-your-integration/mobile-integration/pax_d135_sample_app_troubleshooting If you encounter issues with a PAX D135 while using the SDK, contact the Finix Support Team at [support@finix.com](mailto:support@finix.com). Before reaching out, follow the steps below to send debug logs from the sample app. Alternatively, you can collect logs programmatically. See the **Troubleshooting** section in the [Android quickstart](/guides/in-person-payments/building-your-integration/mobile-integration/pax_d135_android_quickstart) or [iOS quickstart](/guides/in-person-payments/building-your-integration/mobile-integration/pax_d135_ios_quickstart). ## Step 1: Launch the Finix D135 sample app Finix iOS D135 sample app home screen ## Step 2: Connect to the PAX D135 Finix iOS D135 sample app showing a connected device ## Step 3: Tap **Send Debug Data** Finix iOS D135 sample app showing the Send Debug Data option --- # Tap to Pay on iPhone Quickstart Source: https://docs.finix.com/guides/in-person-payments/building-your-integration/mobile-integration/tap_to_pay_iphone_quickstart Accept in-person contactless payments on iPhone with no extra hardware. `FinixTapToPaySDK` uses Apple's Tap to Pay on iPhone technology and processes payments through Finix from start to finish. Your app starts a transaction, the Buyer taps a card or digital wallet on the merchant's iPhone, and the SDK returns a completed Finix `Transfer`. Using the Finix Checkout app? This guide is for developers integrating `FinixTapToPaySDK` into their own iOS app. To accept Tap to Pay on iPhone payments without writing code, see [Accept Payments with Tap to Pay on iPhone](/low-code-no-code/mobile-apps/finix-checkout/tap-to-pay-on-iphone) in the Finix Checkout app. ## How it works 1. Your app starts a transaction with an amount and a transaction type. 2. The SDK presents Apple's secure card-reading sheet and the Buyer taps a card or device. The card read happens inside Apple's Tap to Pay on iPhone technology, and neither your app nor the SDK ever sees raw card data. 3. The SDK submits the payment to Finix and waits for the outcome. You do not make a separate API call to create the `Transfer`. 4. The SDK returns a `TapToPayTransactionResult` with the Finix `Transfer` ID, its state, and masked card details. The SDK also publishes progress events during the transaction (card reading, processing, success or failure) that you can use to drive your UI. ## System requirements ### Device and OS | Requirement | Value | | --- | --- | | Device | iPhone XS or later. | | iOS version | 18.1 or later. | | Passcode | A device passcode must be set (**Settings ▸ Face ID & Passcode**). Tap to Pay on iPhone can't link an account or accept payments on an iPhone without one. | | Testing | Physical iPhone required. The simulator cannot accept taps. | iPad is not supported Tap to Pay on iPhone is not available on iPad. ### Development environment | Requirement | Value | | --- | --- | | Xcode | 16.0 or later. | | Swift | 5.9 or later. | ### Apple requirements - Membership in the [Apple Developer Program](https://developer.apple.com/support/enrollment/) with an organization account. - The Tap to Pay on iPhone entitlement, `com.apple.developer.proximity-reader.payment.acceptance`, granted by Apple. See [Configure Xcode and verify entitlement support](/ios/tap-to-pay/integration#2-configure-xcode-and-verify-entitlement-support) in the Integration Guide. ### Finix requirements - A Finix account with access to the Finix Dashboard. - API credentials (username and password) for the environment you are targeting. - An approved merchant (`MUxxxxxxxxxxxxx`), its processing MID, and its display name. - An activated Finix `Device` resource representing the iPhone. See [Set up a Device](/ios/tap-to-pay/device-setup) in the iOS SDK reference. ## Environments Finix Sandbox and Production are separate environments, and credentials and merchants in one don't exist in the other. The environment is explicit in the SDK configuration (`.sandbox` or `.production`), and a configuration's credentials, `Merchant`, and `Device` must all belong to the same environment. All examples in this guide run against Sandbox. See [Collect your SDK values](/ios/tap-to-pay/integration#3-collect-your-sdk-values) in the Integration Guide for details. ## Integration steps Work through the steps below in order. Each links to the detailed section in the iOS SDK reference that covers it. ### Step 1: Confirm system requirements Verify you have an iPhone XS or later running iOS 18.1 or later with a passcode set, and a physical device for testing. ### Step 2: Set up your Apple entitlement Request the `com.apple.developer.proximity-reader.payment.acceptance` entitlement from Apple and configure your Xcode project. See [Configure Xcode and verify entitlement support](/ios/tap-to-pay/integration#2-configure-xcode-and-verify-entitlement-support) in the Integration Guide. ### Step 3: Gather your Finix credentials Collect your Finix Sandbox API credentials and merchant details (`Merchant` ID, MID, and display name). See [Collect your SDK values](/ios/tap-to-pay/integration#3-collect-your-sdk-values) in the Integration Guide. ### Step 4: Create a Device resource Provision a Finix `Device` resource for the iPhone from your backend. Create it once and cache the `Device` ID. See [Set up a Device](/ios/tap-to-pay/device-setup). ### Step 5: Install and initialize the SDK Add the Swift package and build a `TapToPayConfiguration` with your credentials, merchant details, and `Device` ID, then create the SDK entry point with `FinixTapToPay(configuration:)`. The SDK is hosted on [GitHub](https://github.com/finix-payments/finix-taptopay-ios-sdk). See [Installation and initialization](/ios/tap-to-pay/installation). ### Step 6: Link the merchant's Apple Account Present Apple's account-linking flow so the merchant accepts Apple's Terms and Conditions. This must complete before the first transaction. See [Account linking](/ios/tap-to-pay/account-linking). ### Step 7: Warm up the reader Call `prepareReader()` at app launch and enable `autoPrepareOnForeground` so the session stays warm. This keeps the first tap fast. See [Prepare the reader](/ios/tap-to-pay/transactions#prepare-the-reader). ### Step 8: Run a transaction Start a transaction with `startTransaction(amount:currency:type:identityId:)`, subscribe to `transactionEvents` to drive your UI, and handle the `TapToPayTransactionResult`. See [Transactions](/ios/tap-to-pay/transactions). ### Step 9: Test and submit for App Review Test end to end on a physical iPhone, review privacy disclosures, and prepare your App Review submission. See [Test your integration](/ios/tap-to-pay/testing), [Privacy and data collection](/ios/tap-to-pay/privacy), and [Prepare for App Review](/ios/tap-to-pay/app-review). ## Demo App Finix provides a [demo app](https://github.com/finix-payments/finix-taptopay-ios-sdk-demo-app) you can use as a reference for your integration. ## Learn more iOS SDK Reference Full SDK reference for Tap to Pay on iPhone, including installation, transactions, errors, and App Review guidance. Configure Xcode and verify entitlement support Request the entitlement and configure your Xcode project. Set up a Device Provision and activate a Finix Device resource for the iPhone. Transactions Run payments, handle results, and issue refunds. --- # POS Integration Source: https://docs.finix.com/guides/in-person-payments/building-your-integration/pos-integration Finix's POS integration connects your point-of-sale system to PAX payment terminals through the Finix API. You initiate sales, check device status, and cancel transactions entirely through API calls. No proprietary POS software is required. In-Person Payments API Diagram View our [available devices](/guides/in-person-payments/select-your-device) to compare PAX terminals supported for POS integrations. Finix supports the following PAX terminals for POS integrations: - [PAX A800](/guides/in-person-payments/select-your-device/pax-a800) - [PAX A920 Pro](/guides/in-person-payments/select-your-device/pax-a920-pro) - [PAX A35](/guides/in-person-payments/select-your-device/pax-a35) - [PAX A3700](/guides/in-person-payments/select-your-device/pax-a3700) - [PAX IM30](/guides/in-person-payments/select-your-device/pax-im30) ## Learn more POS Quickstart Set up your payment terminal and process your first transaction in three steps. Sending Receipts Print or email card-network-compliant receipts after a payment. Testing Your Integration Learn how to test your in-person payments integration. Device API Reference Explore the Devices endpoints for activating, updating, and monitoring terminals. --- # POS quickstart Source: https://docs.finix.com/guides/in-person-payments/building-your-integration/pos-integration/pos-quickstart Follow these steps to connect a PAX payment terminal to Finix and process your first in-person payment. ## Step 1: Power on the terminal Place the payment terminal where you'll use it to process payments, then power it on. To set up the payment terminal, you'll need: - A Wi-Fi network and router. - The Wi-Fi network's name and password. - Physical access to the payment terminal being activated. Once the terminal is on, connect it to your Wi-Fi network and open the Finix Payment App. ## Step 2: Create and activate a Device ### Create a Device Create a Device under the Merchant provisioned to process in-person payments. Include the `model` of the payment terminal you'll be using to process cards. Choose the payment terminal that best fits your business needs. View our [available devices](/guides/in-person-payments/select-your-device) to compare options. Pax A800 Model PAX_A800 Device ```json Model PAX_A800 Device { "id": "DV8oMUP5ME1rnxpgoXn5V2GD", "created_at": "2026-09-28T20:31:57.874129Z", "updated_at": "2026-09-28T20:31:57.874129Z", "configuration_details": { // [!code highlight] "allow_debit": true, "allow_standalone_authorizations": false, "allow_standalone_refunds": false, "allow_standalone_sales": false, "automatic_receipt_delivery_methods": null, "available_receipt_methods": null, "bypass_device_on_capture": true, "check_for_duplicate_transactions": true, "display_tip_on_receipt": false, "idle_image_file_id": null, "idle_message": null, "prompt_amount_confirmation": true, "prompt_for_signature": "NEVER", "prompt_manual_entry": false, "prompt_receipt_confirmation": false, "prompt_tip_on_screen": false, "signature_threshold_amount": 10000, "surcharge_basis_points": null, "tipping_details": { "fixed_options": [ 100, 150, 200 ], "percent_options": [ 18, 20, 22 ], "percent_tipping_threshold": 0 } }, "description": "Cashier One", "enabled": false, "idle_message": null, "integration_mode": "PAYMENT_APP", "merchant": "MU7noQ1wdgdAeAfymw2rfBMq", "model": "PAX_A800", "name": "PAX_A800_FRONT_COUNTER", "serial_number": "2210172205", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/devices/DV8oMUP5ME1rnxpgoXn5V2GD" }, "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MU7noQ1wdgdAeAfymw2rfBMq" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/transfers" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/authorizations" } } } ``` Pax A920 Pro Model PAX_A920PRO Device ```json Model PAX_A920PRO Device { "id": "DVi2m7ots9aaE2YW9cFNro98", "created_at": "2026-09-25T20:05:15.944531Z", "updated_at": "2026-09-25T20:05:15.944531Z", "configuration_details": { // [!code highlight] "allow_debit": true, "allow_standalone_authorizations": false, "allow_standalone_refunds": false, "allow_standalone_sales": false, "automatic_receipt_delivery_methods": null, "available_receipt_methods": null, "bypass_device_on_capture": true, "check_for_duplicate_transactions": true, "display_tip_on_receipt": false, "idle_image_file_id": null, "idle_message": null, "prompt_amount_confirmation": true, "prompt_for_signature": "NEVER", "prompt_manual_entry": false, "prompt_receipt_confirmation": true, "prompt_tip_on_screen": false, "signature_threshold_amount": 10000, "surcharge_basis_points": null, "tipping_details": { "fixed_options": [ 100, 150, 200 ], "percent_options": [ 18, 20, 22 ], "percent_tipping_threshold": 0 } }, "description": "Cashier Two", "enabled": false, "idle_message": null, "integration_mode": "PAYMENT_APP", "merchant": "MUiV7ntxfY4eyJxp6E7cZvym", "model": "PAX_A920PRO", "name": "My PAX_A920PRO Finix Device", "serial_number": "1904626094", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/devices/DVi2m7ots9aaE2YW9cFNro98" }, "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MUiV7ntxfY4eyJxp6E7cZvym" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/transfers" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/authorizations" } } } ``` Pax IM30 Model PAX_IM30 Device ```json Model PAX_IM30 Device { "id": "DVdUi9WYEs56L1NrZRomDaLG", "created_at": "2026-09-25T20:05:17.063334Z", "updated_at": "2026-09-25T20:05:17.063334Z", "configuration_details": { // [!code highlight] "allow_debit": true, "allow_standalone_authorizations": false, "allow_standalone_refunds": false, "allow_standalone_sales": false, "automatic_receipt_delivery_methods": null, "available_receipt_methods": null, "bypass_device_on_capture": true, "check_for_duplicate_transactions": true, "display_tip_on_receipt": false, "idle_image_file_id": null, "idle_message": null, "prompt_amount_confirmation": true, "prompt_for_signature": "NEVER", "prompt_manual_entry": false, "prompt_receipt_confirmation": true, "prompt_tip_on_screen": false, "signature_threshold_amount": 10000, "surcharge_basis_points": null, "tipping_details": { "fixed_options": [ 100, 150, 200 ], "percent_options": [ 18, 20, 22 ], "percent_tipping_threshold": 0 } }, "description": "Kiosk Three", "enabled": false, "idle_message": null, "integration_mode": "PAYMENT_APP", "merchant": "MUiV7ntxfY4eyJxp6E7cZvym", "model": "PAX_IM30", "name": "My PAX_IM30 Finix Device", "serial_number": "1234567890", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/devices/DVdUi9WYEs56L1NrZRomDaLG" }, "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MUiV7ntxfY4eyJxp6E7cZvym" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/transfers" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/authorizations" } } } ``` ### Activate the Device Once the Device is created and the `serial_number` is set, you can link the Device resource with the payment terminal by sending an activation request. To activate the Device: - The Device must be online and connected to the network. - The Finix Payment App is open on the Device. ```shell Activate Device curl -i -X PUT \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ https://finix.sandbox-payments-api.com/devices/DV7DvjGoZ2AEdhAKhtKXVv4b \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "action": "ACTIVATE" }' ``` A successful request returns `enabled: true`. Optionally [check the device connection](#checking-the-connection). ## Step 3: Create a sale With the payment terminal connected, you can begin processing in-person payments. Use the Device you enabled to create a sale. ```shell Transfer Request curl -i -X POST \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ https://finix.sandbox-payments-api.com/transfers \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "amount": 150, "currency": "USD", "device": "DV7DvjGoZ2AEdhAKhtKXVv4b", "operation_key": "CARD_PRESENT_DEBIT", "tags": { "order_number": "chris123transfer" } }' ``` ```json Transfer Response { "id": "TRarp7Pz21Low4u2Urw5Ub4W", "created_at": "2019-04-29T20:44:00.13Z", "updated_at": "2022-10-10T05:59:17.59Z", "3ds_redirect_url": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "address_verification": null, "amount": 3138, "amount_requested": 3138, "application": "APeUbTUjvYb1CdPXvNcwW1wP", "capture_amount": 150, "card_present_details": { "emv_data": { "application_identifier": "A0000001523010", "application_label": "DISCOVER", "application_preferred_name": null, "application_transaction_counter": "0005", "cryptogram": "ARCQ F666F8891F870D33", "issuer_code_table_index": null, "pin_verified": false, "tags": null }, "masked_account_number": "************0059", "name": "Test Card 05", "brand": "DISCOVER", "entry_mode": "CHIP_ENTRY", "payment_type": "CREDIT", "approval_code": "004839" }, "currency": "USD", "device": "DVfKLD9GZtsjcJxLtc2yCcfd", "expires_at": "2019-05-06T20:44:00.13Z", "failure_code": null, "failure_message": null, "idempotency_id": null, "is_void": false, "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDsbTBawhnLBAVeinRb84vFR", "messages": [], "raw": null, "security_code_verification": null, "source": "PImTHaz7XVPx4M7mhu9x8gkU", "state": "SUCCEEDED", "tags": { "TicketNumber": "45878" }, "trace_id": "FNX35FSuraeKKJr65wkGVFJni", "void_state": "UNATTEMPTED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUarp7Pz21Low4u2Urw5Ub4W" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP" }, "transfer": { "href": "https://finix.sandbox-payments-api.com/transfers/TRqQCAX7nYHUnkE5YPFTknqd" }, "device": { "href": "https://finix.sandbox-payments-api.com/devices/DVfKLD9GZtsjcJxLtc2yCcfd" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR" } } } ``` You may proceed with [managing payouts](/guides/payouts) and the post-payments lifecycle. ## Platform setup If you are a Software Platform or Marketplace that is onboarding sellers, you will have multiple Merchants available to choose from when activating your device. Select the Merchant you want to process in-person payments for before activating your device. See our [Platform Quickstart](/guides/platform-payments/platform-quickstart) to learn how to quickly onboard sellers. ## Additional functionality After completing the initial setup, you may also want to verify your device connection or cancel operations as needed. ### Checking the connection Prior to initiating a payment, you can check the connection to verify that the Device is ready to process payments. Checking the connection will confirm that the: - Device is powered on. - Finix Payment App is open. - Device is connected to the internet. - Device was able to connect to the Finix Server. Use the ID of the Device you enabled to check the Connection. Below is a sample request and response. - The `connection` field in the response has two potential values: - `open`: the Device is ready to process payments. - `closed`: the Device has not met the criteria outlined above to process payment. If the `connection` is `closed` and a payment is initiated, the Transfer will fail with an error of `DEVICE_UNREACHABLE`. Device ```json Device { "id": "DVcazsRGCXuRgxYAqwkbvvci", "created_at": "2026-09-28T21:13:37.292622Z", "updated_at": "2026-09-28T21:13:37.292622Z", "android_version": "10", "configuration_details": { "allow_debit": true, "allow_standalone_authorizations": false, "allow_standalone_refunds": false, "allow_standalone_sales": false, "automatic_receipt_delivery_methods": null, "available_receipt_methods": null, "bypass_device_on_capture": true, "check_for_duplicate_transactions": true, "display_tip_on_receipt": false, "idle_image_file_id": "FILE_fJnt6o1h36YHXdqX2Hidwn", "idle_message": "Device is idle", "prompt_amount_confirmation": true, "prompt_for_signature": "NEVER", "prompt_manual_entry": false, "prompt_receipt_confirmation": false, "prompt_tip_on_screen": false, "signature_threshold_amount": 10000, "surcharge_basis_points": null, "tipping_details": { "fixed_options": [ 100, 150, 200 ], "percent_options": [ 18, 20, 22 ], "percent_tipping_threshold": 0 } }, "connection": "Open", // [!code highlight] "description": "Cashier One", "enabled": true, "firmware_version": "PayDroid_10.0.0_Eucalyptus_V20.1.33_20260407", "idle_message": null, "integration_mode": "PAYMENT_APP", "merchant": "MU54k9jqhxipR4TV5UjD4x5u", "model": "PAX_A800", "name": "PAX_A800_FRONT_COUNTER", "payment_app_version": "5.9.0", "serial_number": "2210172205", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/devices/DVcazsRGCXuRgxYAqwkbvvci" }, "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MU54k9jqhxipR4TV5UjD4x5u" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/transfers" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/authorizations" } } } ``` ### Canceling a Device To deactivate a Device and prevent it from processing future payments, send a PUT /devices/{device_id} request with the `DEACTIVATE` action. ### Canceling a transaction To cancel an in-progress transaction, send a PUT /devices/{device_id} request to cancel the transaction. If successful, the `failure_code` and `failure_message` on the Transfer resource will indicate the transaction was cancelled. ```json Cancel Transfer Response { "id": "TRt3LfP6ot6s5HG1ZN9QE5qc", "created_at": "2025-07-18T23:20:55.95Z", "updated_at": "2025-07-18T23:20:55.95Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 2000, "amount_requested": 2000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "card_present_details": { "emv_data": { "application_identifier": null, "application_label": null, "application_preferred_name": null, "application_transaction_counter": null, "cryptogram": null, "issuer_code_table_index": null, "network_emv_response": null, "pin_verified": false, "tags": null }, "masked_account_number": null, "name": null, "brand": "UNKNOWN", "entry_mode": "UNKNOWN", "payment_type": null, "approval_code": null, "digital_signature_file_id": null }, "currency": "USD", "destination": null, "device": "DVae7HFLS7BXNaFpKhdH1K6x", "externally_funded": "UNKNOWN", "failure_code": "CANCELLATION_VIA_API", "failure_message": "The transaction was canceled via API before the transaction was completed. The cardholder needs to attempt the transaction again.", "fee": 0, "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj", "idempotency_id": null, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "messages": ["RAW MESSAGE"], "operation_key": "CARD_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": "PIhGjmMzFiT3oorhhBoMHdKc", "split_transfers": [], "state": "FAILED", "statement_descriptor": "FLX*FINIX FLOWERS", "subtype": "API", "supplemental_fee": null, "tags": { "order_number": "Test Transaction" }, "tip_amount": null, "trace_id": "433ca932-11c4-4667-8a21-90db472b7691", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRt3LfP6ot6s5HG1ZN9QE5qc" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" }, "device": { "href": "https://finix.sandbox-payments-api.com/devices/DVae7HFLS7BXNaFpKhdH1K6x" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRt3LfP6ot6s5HG1ZN9QE5qc/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRt3LfP6ot6s5HG1ZN9QE5qc/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TRt3LfP6ot6s5HG1ZN9QE5qc/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRt3LfP6ot6s5HG1ZN9QE5qc/disputes" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj" } } } ``` ## Next steps Testing Your Integration Learn how to test your In-Person Payments integration. Sending Receipts Learn how to print or email card-network-compliant receipts after a payment. Device API Reference Explore the Devices endpoints for activating, updating, and monitoring terminals. --- # Sending Receipts from Your POS Integration Source: https://docs.finix.com/guides/in-person-payments/building-your-integration/pos-integration/sending-receipts While processing in-person payments, Finix lets you provide receipts to buyers upon request. Card networks require receipts to have specific data elements for the buyer’s convenience. This guide covers how to provide receipts for in-person payments via print or email. ## Where to find receipt data When using the Finix API, the response body to the Authorization contains everything you need to print a receipt in the `card_present_details` object. Here's an example of the `card_present_details` object and the data that gets printed on the receipt: ```json Authorization Resource Example { "id": "AUarp7Pz21Low4u2Urw5Ub4W", "amount": 150, "other fields": null, "card_present_details": { "emv_data": { "application_identifier": "A0000001523010", "application_label": "DISCOVER", "application_preferred_name": null, "application_transaction_counter": "0005", "cryptogram": "ARCQ F666F8891F870D33", "issuer_code_table_index": null, "pin_verified": false, "tags": null }, "masked_account_number": "************0059", "name": "Test Card 05", "brand": "DISCOVER", "entry_mode": "CHIP_ENTRY", "payment_type": "CREDIT", "approval_code": "004839" }, "merchant": "MU4LYrniAvqVKUBqcATb7Y7p", "merchant_identity": "IDsbTBawhnLBAVeinRb84vFR", "state": "SUCCEEDED", "trace_id": "FNXsK76MxJWPkbGqpKymgkzK" } ``` ### Sample receipt Here's an example of the information (not the layout) available in receipts and where to find the information in the Finix response. Sample receipt showing card transaction fields including merchant name, amount, cryptogram, and approval code ### Receipt data | No. | Name | ReceiptProtocol Field | Finix API Location | | --- | --- | --- | --- | | 1 | Merchant Name & Address | `merchantName`, `merchantAddress` | Create independently or pull from the merchant identity. | | 2 | Date & Time | `date` | `created_at` from the transaction response, or create independently. | | 3 | Application Label | `applicationLabel` | `application_label` in `emv_data` in `card_present_details`. | | 4 | Application Identifier | `applicationIdentifier` | `application_identifier` in `emv_data` in `card_present_details`. | | 5 | Merchant Id | `merchantId` | `merchant_identity` in the response. | | 6 | Reference Number | `referenceNumber` | `trace_id` in the response. | | 7 | Account Number | `accountNumber` | `masked_account_number` in `card_present_details`. | | 8 | Card brand | `cardBrand` | `brand` in `card_present_details`. | | 9 | Entry Mode | `entryMode` | `entry_mode` in `card_present_details`. | | 10 | Transaction Id | `transactionId` | `id` of the transaction. | | 11 | Approval Code | `approvalCode` | `approval_code` in `card_present_details`. | | 12 | Response Code | `responseCode` | — | | 13 | Response Message | `responseMessage` | `state` of the transaction. | | 14 | Amount | `amount` | `amount` in $ format. | | 15 | Cryptogram | `cryptogram` | `cryptogram` in `emv_data` in `card_present_details`. | | 16 | Transaction Type | `transactionType` | either `Sale` or `Authorization` depending on the method used. | ### Prompting buyers for preferred receipts If the `prompt_receipt_confirmation` value is set to `true` for the terminal, it will present a page to the cardholder that will prompt them to select from several receipt preferences. The values you include in `available_receipt_methods` are the ones that will appear in the prompt menu. Acceptable values are: - `PRINT` - `EMAIL` - `SMS` When the cardholder selects an option and submits contact information, Finix creates a receipt webhook that you can listen to and use to trigger printing. The webhook is `entity: receipt` and `type: created`. It will include all the relevant receipt information and the appropriate contact information to route the printing. ## Additional requirements Merchant processing agreements require that a separate receipt document must be able to be printed along with the POS receipt. 1. One for the cardholder (a separate receipt from the usual receipt). The **Cardholder Copy** must be printed as the last line. 2. One for the seller. The **Merchant Copy** must be printed as the last line of the second receipt copy. Depending on the transaction, many of the fields can return `null`. If they return `null`, you can either print an empty value (`0`, `N/A`, etc.) or remove the line. Integrating to receipt printers: For serial connections, you'll need to encode the receipt data into the respective printer format (ESC/Star) and then use programs such as [Socket.io](https://socket.io/) to send the message to the printer. You can also use network-based printers to send receipt information over the network. Alternatively, you can provide digital receipts, but you must be able to provide a paper receipt at the buyer's request. The receipt does not need to be printed on receipt paper, but receipt paper is recommended because it does not require ink and is more economical. ## Printing receipts with the Finix API Use the following request to print a receipt for an Authorization or Transfer. - Available values for `type` include `MERCHANT` or `BUYER`. - Set `send_receipt_to_buyer` to `true` to trigger receipt delivery. - If the original transaction included a tip or surcharge. Use `amount_breakdown` to specify individual charges/fees. Finix will not automatically pull these values from the original transaction. ```shell Create Receipt Request curl https://finix.sandbox-payments-api.com/receipts \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \ -X POST \ -d '{ "send_receipt_to_buyer": true, "amount_breakdown": { "subtotal_amount": 1700, "additional_buyer_charges": { "surcharge_amount": 100 }, "tip_amount": 100 }, "requested_delivery_methods": [ { "type": "PRINT", "destinations": [ "DV864n6gKbgGNgQg9LyHpnMR" ] } ], "entity_id": "TRrieLrWspuN3W72BP3nD6hh", "type": "BUYER" }' ``` ```json Create Receipt Response { "id": "receipt_ccBeL2iWn3V1wWSfqjuaE", "created_at": "2024-06-26T18:06:12.68Z", "updated_at": "2024-06-26T18:06:12.68Z", "amount": 500, "currency": "USD", "amount_breakdown": null, "send_receipt_to_buyer": true, "device_id": "DVmiLSwXdYxC7U3wtGCpF7iD", "entity_details": { "id": "TR3rNtUhV4dC82vNsVGLENVD", "created_at": "2024-05-23T21:26:11.71Z", "type": "TRANSFER" }, "type": "BUYER", "merchant_details": { "id": "MUrcHDvsFUp4PjJzWo7WzF82", "business_name": "Smith & Associates Consulting", "doing_business_as": "Smith & Associates Consulting", "business_address": { "city": "Allen", "country": "USA", "line1": "1113 Shade Tree Ln", "line2": null, "postal_code": "75013", "region": "TX" } }, "payment_instrument_details": { "id": "PIkXm2YP4isGwpRpfjrDkEc8", "type": "PAYMENT_CARD_PRESENT", "bin": "476173", "brand": "VISA", "card_type": "CREDIT", "last_four": "0010" }, "network_details": { "application_label": "VISA CREDIT", "application_identifier": "A0000000031010", "approval_code": "031475", "cryptogram": "ARCQ A09FDACC9F024838" }, "requested_delivery_methods": [ { "type": "PRINT", "destinations": ["DVmiLSwXdYxC7U3wtGCpF7iD"] } ], "receipt_url": "https://receipt.sb-payments-checkout.com/W3Qoh1", "_links": { "self": { "href": "https://finix.sb-payments-api.com/receipts/receipt_ccBeL2iWn3V1wWSfqjuaE" } } } ``` --- # Applying Credits to Subscriptions Source: https://docs.finix.com/guides/subscriptions/apply-credits-to-subscriptions Learn how to apply Credits to a Subscription Finix's Subscriptions will take into account any Credits for upcoming charges. There are many situations where you might want to apply a Credit to a Subscription. For example, a customer might ask to: - Temporarily reduce the subscription amount for the next charge - Request a temporary pause for 1-2 months on being billed - Apply a one-time credit for an issue that may have occurred ## Apply credits to a Subscription using the Dashboard Subscriptions Credits ### Steps to apply a credit 1. Navigate to an Active Subscription 2. Click into a Subscription and find the Billing Credit Section 3. Create a Credit Once the Credit is created, you'll be able to see all the Credits for that Subscription. Applying Credits are irreversible. ## Apply credits to a Subscription using the Finix API If you are interested in applying a credit using the Finix API, you can use the structure below. ```shell Subscription Credit Request curl https://finix.sandbox-payments-api.com/subscriptions/subscription_cmhURdrg2KX5Kp1emKdvh/subscription_balance_entries \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USksBJMwkNUz5GyxPevL2yFY:71b641c1-861d-435b-9a9c-532760731c5e \ -X POST \ -d '{ "type": "CREDIT", "amount": 1000, "currency": "USD", "description": "10.00 credit due to order issue", "tags": {} }' ``` ```json Subscription Credit Response { "id": "subscription_balance_entry_cmhV4HNbhJJ242SRNqcH9", "created_at": "2025-03-19T19:00:30.25Z", "updated_at": "2025-03-19T19:00:30.25Z", "type": "CREDIT", "subscription_id": "subscription_cmhURdrg2KX5Kp1emKdvh", "amount": 1000, "currency": "USD", "description": "10.00 credit due to order issue", "tags": {} } ``` --- # Handling Failed Subscription Payments Source: https://docs.finix.com/guides/subscriptions/handling-failed-subscription-payments Learn how Finix handles failed subscription payments and retries charges on your behalf. ## First payment for a Subscription When a Subscription is created, Finix creates a `first_charge_at` field that tells you when Finix will attempt a payment. This is based on whether the `Subscription` has a trial phase and when the start date of the `Subscription` is. You can view the First Payment Description in the Dashboard on the Subscriptions List Page for easy reference. When Finix attempts to debit the `payment_instrument` associated with the Subscription, a `Transfer` resource will be created. The `Transfer` resource contains information about the `state`, `payment_instrument`, and more. Once a Subscription is created, you can [view all its associated payments](/guides/subscriptions/viewing-subscription-payments) from the subscription details page. ## Subscription payment re-attempts (dunning) If the initial `Transfer` fails, Finix will automatically retry the payment according to the following dunning schedule: - 1 day after the initial failure - 3 days after the initial failure - 8 days after the initial failure - 15 days after the initial failure If the final `Transfer` at 15 days fails, the subscription will be canceled automatically 19 days after the initial failure. --- # Subscriptions Source: https://docs.finix.com/guides/subscriptions Set up recurring payments using no-code tools, manage changes at scale with bulk updates, customize plans by applying one-off pricing changes, and more. Illustration of recurring billing statements Finix has recurring billing options for companies of all sizes. Set up recurring payments using no-code tools, customize plans by applying one-off pricing changes, and more. Subscriptions Learn how to get started with Subscriptions ## Learn more Managing Subscriptions Learn how to manage your recurring subscriptions on the dashboard or via API. Subscription Plans Learn how to create Subscription Plans to manage Subscriptions at scale. Apply Credits to Subscriptions Learn how to apply credits to a Subscription. --- # Managing Subscriptions Source: https://docs.finix.com/guides/subscriptions/managing-subscriptions Learn how to manage your recurring subscriptions on the dashboard or via API. ## Editing a Subscription You can edit Subscriptions in the Finix Dashboard or via API. To edit a Subscription via the Dashboard: 1. Navigate to the Subscription you would like to Edit. 2. On the top right, select Edit Subscription. 3. Update the editable fields and save the form. - Please see the [Recurring Payment Guidelines](/guides/subscriptions/recurring-payment-guidelines#recurring-payments-guidelines) if you want to change an amount for a subscription. We also suggest you discuss this with your legal counsel. - For ACH payments, you must obtain a new Authorization for modified amounts. ### Editable fields You can edit the following fields from the Dashboard: - Subscription Name - Recurring Price - Payment Instrument associated with a subscription - Associated subscription plan - Tags ### Editing amounts Subscriptions that are edited after a successful payment, will have the following charge_date correspond with the change in pricing. ### Editing a Subscription via API To edit a Subscription via API, see our API reference. ## Canceling a Subscription Canceling a Subscription is available via the Finix Dashboard and via API. Canceling a subscription is irreversible. If you would like to re-activate this subscription, you will need to create a new Subscription. To cancel a Subscription on the Dashboard: 1. Navigate to the Subscription you would like to cancel 2. On the top right, select Cancel Subscription 3. Confirm you want to cancel the Subscription ### Canceling a Subscription via API To cancel your Subscription via API, please see our [API Reference](/api/subscriptions/removesubscription). --- # Recurring Payments Guidelines Source: https://docs.finix.com/guides/subscriptions/recurring-payment-guidelines Learn how to stay in compliance with Recurring Payments and Subscriptions This product requires an additional fee. Please contact your Finix Point of Contact for pricing on this feature. Subscriptions allow you to charge a fixed amount to `payment_instrument` on a recurring time period. You can use Subscriptions to charge buyers, customers, or even `merchants`. ## 1. General disclaimer Important: There are federal, state, card network, and NACHA requirements that govern a merchant’s use of recurring, subscription, negative option, and automatic renewal payment plans (collectively, “automatic renewal requirements”). These automatic renewal requirements impose obligations on merchants to disclose the key terms of any automatic renewal payment plan, obtain the customer’s informed consent and authorization, provide simple mechanisms to cancel, and provide confirmation of the authorization to the customer, among other notice requirements. Before implementing any automatic renewal payment plan you should consult with legal counsel on compliance with applicable requirements. By using the Finix Platform, you represent and warrant that your use of any automatic renewal payment plan complies with applicable automatic renewal requirements. You also acknowledge and agree that Finix shall have no responsibility or liability for your compliance or failure to comply with same. The information provided on this website does not, and is not intended to, constitute legal advice. All information, content, and materials available on this website are provided for general informational purposes only. Information on this website may not constitute the most up-to-date legal or other information. Finix makes no representations about the content of the information provided on this website and disclaims all liability for the content. ## 2. Card brand requirements Visa and Mastercard impose disclosure and related requirements on merchants that sell goods or services through automatic renewal payment plans (referred to as recurring or subscription payments). You can find more information on the Visa and Mastercard requirements by consulting the [Mastercard Rules](https://www.mastercard.us/content/dam/public/mastercardcom/na/global-site/documents/transaction-processing-rules.pdf) and [Visa Rules](https://usa.visa.com/content/dam/VCOM/download/about-visa/visa-rules-public.pdf). A summary of the Mastercard and Visa rules for automatic renewal payment plans is provided below. **Visa and Mastercard requirements do not take the place of federal and state automatic renewal laws; compliance with Visa and Mastercard rules may not ensure your compliance with federal or state automatic renewal laws.** ### Mastercard - Disclose the subscription terms when collecting the payment credential, including the price that will be billed and the frequency of the billing, as well as any trial period. - Display the subscription terms on any payment or order summary webpage and capture cardholder’s affirmative acceptance before completing the order. - After cardholder completes the subscription order, send an email confirmation or other electronic message that includes: - The subscription terms - A transaction receipt - Clear instructions about how to cancel the subscription. - For any subscription where billing frequency is every 6 months or less, send an electronic reminder to the cardholder at least 7 days but no more than 30 days prior to the next billing date that includes the subscription terms and instructions for how to cancel the subscription. - Provide an online or electronic cancellation mechanism or clear instructions on how to cancel that are easily accessible online (such as “Manage Subscription” or “Cancel Subscription” links on the merchant’s home page). - Provide the cardholder with written confirmation in either hard copy or electronic format at least 7 days in advance when any of the following events occur: - Trial period expires - Changes to subscription billing terms - Recurring payment schedule has been terminated by either the merchant or cardholder, in which case the notice must be sent no more than 7 days after the cardholder’s decision to cancel. - For trial periods longer than 7 days, send a reminder notice to the cardholder at least 3 days before the renewal and include basic terms of the subscription and instructions on how to cancel. After trial period expires, provide cardholder with information on the recurring payments and obtain explicit consent for recurring payments. - For negative option plans, each time the merchant receives an approved authorization request, provide the cardholder with a receipt through an email or SMS text message with instructions for terminating the recurring payment plan. ### Visa - At the time of enrollment, obtain the cardholder’s express consent to the recurring transactions. Disclose the fixed dates or intervals on which recurring transactions will be processed. - At the time of enrollment, send an electronic copy of the terms and conditions of the recurring payments to the cardholder. - If the recurring payments involve a trial period, disclose the length of the trial period, and send an electronic reminder notice with a link to online cancellation at least 7 days before initiating a recurring transaction after the trial period ends. Visa has specific billing statement descriptors for indicating that a transaction is related to a trial period. - Provide a simple cancellation procedure. If the purchase was online, provide at least an online cancellation procedure. ## 3. Common practices for compliance Before implementing an automatic renewal payment plan you should consult with legal counsel. You can find more information on the Mastercard and Visa requirements by consulting the [Mastercard Rules](https://www.mastercard.us/content/dam/public/mastercardcom/na/global-site/documents/transaction-processing-rules.pdf) and [Visa Rules](https://usa.visa.com/content/dam/VCOM/download/about-visa/visa-rules-public.pdf). Common practices for recurring payments compliance may include: - Disclose clearly and conspicuously the material terms and conditions of the transaction and payment schedule before collecting the payment credential. Material terms and conditions may include, without limitation: - the identity of the merchant; - a description of the goods or services; - the cost or price of the goods or services, including any introductory or trial price and the regular price that will be charged after any introductory period; - the existence of the recurring payment plan, including the amount and payment schedule; - the length of any introductory or trial period, if applicable; - the amount of any subsequent charges, and the dates or frequency of any subsequent charges; and - how to cancel the recurring payment plan, including the date by when the consumer must cancel to avoid the next charge. - Display the subscription terms on any payment or order summary webpage and capture cardholder’s affirmative acceptance before completing the order. - Obtain the customer’s informed consent and authorization for the transaction and recurring payment schedule through a written agreement, which may include having the purchaser check a box or provide a similar electronic signature confirming review and consent to the terms and conditions of the transaction and recurring payment schedule. - Provide an online or electronic cancellation mechanism or clear instructions on how to cancel that are easily accessible online (such as “Manage Subscription” or “Cancel Subscription” links on the merchant’s home page). - Send the purchaser a confirmation of the transaction and recurring payment schedule that includes: (1) the subscription terms, (2) the amount of each recurring payment and payment schedule, (3) the cancellation policy, and (4) how to cancel (including an online cancellation mechanism for online purchases) - Send a reminder notice with the payment amount and information on how to cancel prior to the next scheduled payment. For annual payment plans, a written reminder notification that includes the material terms and conditions, including cancellation policy, sent no less than 30 days but no more than 60 days before the cancellation deadline. - Mastercard: For any subscription where billing frequency is every six months or less, send an electronic reminder to the cardholder at least 7 days but no more than 30 days prior to the next billing date that includes the subscription terms and instructions for how to cancel the subscription. - If there is a material change in the terms of the recurring payment plan, before implementing the change, provide the customer with clear and conspicuous notice of the material change and information regarding how to cancel prior to the change being implemented. - Mastercard: Provide the cardholder with written confirmation in either hard copy or electronic format at least 7 days in advance when any of the following events occur: - Trial period expires - Changes to the subscription billing terms - The recurring payment plan has been terminated by either the merchant or the cardholder, in which case the notice must be sent no more than 7 days after the cardholder’s decision to cancel. - If offering a trial period in connection with a recurring payment plan, disclose the length of the trial period. - Mastercard: For trial periods longer than 7 days, send a reminder notice (via email) to the cardholder at least 3 days before the renewal and include basic terms of the subscription and instructions on how to cancel. After trial period expires, provide cardholder with information on the recurring payments and obtain explicit consent for recurring payments. - Visa: Send an electronic reminder notice with a link to online cancellation at least 7 days before initiating a recurring transaction after the trial period ends. --- # Bulk Importing Subscriptions Source: https://docs.finix.com/guides/subscriptions/subscription-imports Instead of creating subscriptions one by one, you can import multiple subscriptions at once with a CSV file in the Finix Dashboard. During the import process, Finix provides a link to download a sample template (CSV) to help format your data. ## Pre-requisites - You must have a [subscription plan](/guides/subscriptions/subscription-plans) created before you can import subscriptions. At this time, you cannot import subscriptions without providing a `subscription_plan_id`. - You must have the `identity_id` and payment `instrument_id` for the subscriber. ## Getting started 1. From the Subscriptions page, click the options (**...**) drop-down and select **Bulk Import CSV**. - A **Select Merchant Account** popover displays. 2. Select a **Merchant Account**. 3. Click **Proceed**. - An **Import Subscriptions** page displays. 4. Follow the instructions to prepare your subscription import file, including downloading the sample template (CSV) and filling in the fields. ## CSV file requirements The following table shows the required and optional columns for importing subscriptions from an existing plan. Currently, you can only import subscriptions that were created from [subscription plans](/guides/subscriptions/subscription-plans). For each subscription, you need to provide a `subscription_plan_id`. | Column Name | Type | Description | | --- | --- | --- | | `billing_overrides.` `collection_method` | string, optional | - The method by which subscription payments are collected. Currently, automatically billing the `Payment Instrument` is the only method available. - Example: `BILL_AUTOMATICALLY` | | `billing_overrides.` `send_invoice` | boolean, optional | - Whether to send the user an invoice. - Example: `true` | | `billing_overrides.` `send_receipt` | boolean, optional | - Whether to send the user a receipt. - Example: `true` | | `buyer_details.` `identity_id` | string, **required** | - The identity ID of the subscriber. - Example: `IDtEnKsZyJNUGK83ZTx4C45S` | | `buyer_details.` `instrument_id` | string, **required** | - The ID of the Payment Instrument from which the subscription payments get debited. - Example: `PImXAVgkKVshKWWHUk4xXbve` | | `buyer_details.` `requested_delivery_methods.` `email_destinations` | string, optional | - Email address(es) where receipts should be sent. Multiple values may be separated by a semicolon. - Example: `subscriber@example.com` | | `buyer_details.` `requested_delivery_methods.` `sms_destinations` | string, optional | - Phone number(s) where receipts should be sent via SMS. Multiple values may be separated by a semicolon. - Example: `2348765431` | | `buyer_details.` `shipping_address.` `city` | string, optional | - City (max 20 characters). - Example: `Middletown` | | `buyer_details.` `shipping_address.` `country` | string, optional | - 3-letter country code. - Example: `USA` | | `buyer_details.` `shipping_address.` `line1` | string, optional | - First line of the address (max 35 characters). - Example: `324 Oak Avenue` | | `buyer_details.` `shipping_address.` `line2` | string, optional | - Second line of the address (max 35 characters). - Example: `Apartment 7` | | `buyer_details.` `shipping_address.` `postal_code` | string, optional | - Zip or Postal code (max 7 characters). - Example: `19734` | | `buyer_details.` `shipping_address.` `region` | string, optional | - 2-letter State code. - Example: `DE` | | `currency` | string, **required** | - ISO 4217 3-letter currency code. At this time, the only currencies supported are `USD` and `CAD`. - Example: `USD` | | `linked_to` | string, **required** | - The ID of the Merchant resource that you wish to link to the Subscription. - Example: `MUxdJCr9xTMnmt1vGUAqV9z4` | | `nickname` | string, optional | - A human-readable name for the resource. - Example: `Finflix Gold Package` | | `start_subscription_at` | string (date-time), optional | - Indicates that the subscription is scheduled to begin in the future. The timestamp specifies the exact start date for subscription billing. - Example: `2025-05-05T22:42:05.490Z` | | `subscription_details.` `notification_preferences.` `send_confirmation` | boolean, optional | - Whether to send a confirmation email to the user. - Example: `true` | | `subscription_plan_id` | string, **required** | - The ID of the Subscription Plan from which to create the Subscription. - Example: `subscription_plan_ctBbJ1ihsC8Hpju4RQfZE` | | `total_billing_intervals` | integer, optional | - The total number of billing intervals for the Subscription. - Example: `12` | ## Uploading and verifying your file 1. From the **Import Subscriptions** page, name your import file and upload the CSV file you filled out with your information. 2. After uploading the file, click **Verify File**. - A **Subscription Import** page displays with an "Uploading and Verifying File" banner indicating the file is being verified. Viewing Import Status You don’t need to wait for the import to complete. You can leave and return later to check the status from the **Subscription Imports** tab [on the main Subscriptions page](#viewing-your-imported-subscriptions). ### If Verification fails If file verification fails, the banner title changes to "File Verification Failed" with a link to **Download the verification errors (CSV)** and the option to **Upload a Corrected File**. ### If Verification succeeds If file verification succeeds, the banner title changes to "File Verified" to show your subscriptions were successfully verified. A **Confirm Import** popover appears with a message showing how many subscriptions will be imported and asks if you want to proceed. Click **Import Now** to import all subscriptions in the file. The banner text updates to show the import is in progress. When the import finishes, the banner text updates to show completion. It also provides an option to download CSV results. Imported subscriptions now appear under **Imported Subscriptions**. ## Viewing your imported Subscriptions You can view the imported subscriptions from the main **Subscriptions** page › **Subscription Imports** tab. Subscription Imports Page Imported Subscriptions This page is helpful to view the status of your subscription imports. --- # Subscription Links Source: https://docs.finix.com/guides/subscriptions/subscription-links Subscription Links allow your buyers to easily sign up for subscriptions. These links can be shared via email, SMS, or other channels, making it easy to sign up for a recurring service. Early Access This product is in early access. This feature is enabled in Sandbox by default. If you would like to have this enabled on your Live environment, email your Finix point of contact. ## Creating a Subscription Link on the Finix Dashboard You can create a `Subscription Link` in the Finix Dashboard without any development work. To create a Subscription Link, you must first have a pre-existing Subscription Plan. Using the Finix Dashboard, you can: - Create `Subscription Links` - View all existing `Subscription Links` - De-Activate a `Subscription Link` if you no longer want to use a Subscription Link ### Step 1: Navigate to Subscription Links To create a Subscription Link in the Finix Dashboard: 1. Log into the [Finix Dashboard](https://finix.payments-dashboard.com/Login). 2. Click the **Subscriptions** page > **Subscription Links** tab. 3. Click on **Create Subscription Link** Subscriptions List Page - Create Subscription Link ### Step 2. Create a Link When you click on **Create Subscription Link**, a form will appear allowing you to create a Subscription. Subscriptions List Page #### Subscription plan selection - **Plan Template:** To create a subscription link, you must have an existing Subscription Plan. - **Subscription Name:** You will need to enter a Subscription Name that buyers will see. We recommend using a name that the buyers will recognize, which defaults to the same name as the plan template. - **Plan Image URL:** You can include an image URL to be used for a Subscription. #### Adding additional Subscription plans Finix's Subscription Links allow you to attach multiple Subscription Plans to a Subscription. This allows buyers to select which Subscription Plan to subscribe to. For example, you could offer a Gold, Silver, and Bronze plan with different pricing. Subscriptions List Page #### Subscription settings On the following page, you can configure: - **Single Use or Multi-Use:** You can choose whether the Subscription Link is one-time or multi-use. - **Link Validity:** You can configure the default validity of the subscription link. - **Terms of Service URL:** A Terms of Service URL is required for using subscription links. We recommend linking to your terms that dictate Subscription or recurring payment guidelines and policies. - **Buyer Details:** We collect email by default. You have additional options you can collect, such as name, phone number, and more. - **Accepted Payment Details:** We support Cards and Bank Payments. You can configure to support both or just one of each. - **Receipt Settings:** You can choose to send a receipt to your buyer and include additional recipients. #### Customize your Subscription Link On the Subscription Link itself you can customize the following: - **Button Text:** You can customize the text that appears on the Subscription Link. The default value is Subscribe. - **Custom success return URL:** A URL to redirect buyers to if their subscription signup is successful. This can be used to show a custom success page or link to a good or service. - **Custom failure return URL:** A URL to redirect buyers to if their subscription signup is unsuccessful. This can be used to provide additional instructions or allow them to restart the process. - **Custom expired session URL:** A URL to redirect buyers to if their session expires before completing the subscription process. This can be used to provide additional instructions or allow them to restart the process. #### Customize your branding Each Subscription Link can have custom branding. This is helpful if you manage multiple brands in the same Application. ## Example Subscription Link To see an example Subscription Link, you can paste this sandbox subscription link in your browser. ```text https://link.sandbox-payments-checkout.com/jNGmn6 ``` --- # Subscription Notifications Source: https://docs.finix.com/guides/subscriptions/subscription-notifications Learn how to send notifications for Subscriptions and Subscription Links. ## Confirmation email Finix allows you to provide a confirmation email when a buyer signs up for a subscription. We recommend sending out this email to ensure your buyers know the details of their subscription. A confirmation email can include: - Amount charged at signup - Subscription start date - Trial phase details - Discount phase details - End date ### Examples Basic Subscription Example: Subscription Confirmation Example of a subscription notification with: - Trial phase - Discount phase - End date Subscription Confirmation ## Send a Subscription confirmation email using the Finix Dashboard ### Subscriptions When creating a Subscription, you'll see an option to send out a Subscription confirmation email. Subscription Notification Select ### Subscription Links On Subscription Links, we strongly recommend sending out a confirmation email to your buyers. You'll see it checked by default. Subscription Links Notification Select --- # Subscription Plans Source: https://docs.finix.com/guides/subscriptions/subscription-plans Learn how to create Subscription Plans to manage Subscriptions at scale. Subscription plans are templates with set recurring costs and frequencies that can be used to create subscriptions for individual buyers. Example use cases for Subscription Plans: - You have pricing tiers (e.g., Basic, Premium, Deluxe, Enterprise). You can use the pricing tiers to group subscriptions under them. - You have different products or services you offer that have different recurring costs and frequencies (e.g. 30 min guitar lessons, 60 min guitar lessons,) - You charge different recurring rates based on the location ## Creating a Subscription plan on the Finix Dashboard You can create a `Subscription Plan` in the Finix Dashboard without any development work. Using the Finix Dashboard, you can: - Create `Subscription Plans` - View all existing `Subscription Plans` - De-Activate a `Subscription Plan` if you no longer want to add new subscriptions under that Subscription Plan. ### Step 1: Navigate to Subscription plans To create a Subscription Plan in the Finix Dashboard: 1. Log into the [Finix Dashboard](https://finix.payments-dashboard.com/Login). 2. Click **Subscriptions** page > **Subscription Plans** tab. 3. Click **Create Subscription Plan** Create Subscription Plan 1. Fill out the form with the requested details. Subscription Plan Creation Form ### Step 2. Create a Subscription plan When you click on **Create Subscription Plan**, a form will appear with the following options: #### Billing settings This section specifies how you want to bill your buyers. - Subscription Name - Billing Frequency - Recurring Price #### Trial phase You can enter a trial phase if your `Subscription` requires a set number of days before charging the buyer. For example, a 30-day trial, 3-month trial, or other combinations are possible. #### Discount phase You can enter a discount phase if you would like to have a discounted rate for a set of amount of intervals. These take place after the Trial Phase is completed. #### Review and create Subscription plans After filling out the previous section, you can create the `Subscription Plan`. ## Creating a Subscription from a Subscription plan You have two options to create a Subscription from a Subscription Plan. ### From the Subscription plan details page 1. Navigate to a Subscription Plan 2. Click on the Actions dropdown on the top right 3. Select Create Subscription 4. Enter the buyer information and complete the form. ### From the Subscriptions list page 1. Click **Billing** → **Subscriptions**. 2. Click **Create Subscription** 3. Unselect **Create subscription without a plan** 4. Select a Subscription Plan 5. Enter the buyer information and complete the form. ## Creating a Subscription plan via API To create a Subscription Plan, include: - The ID of the `Merchant` that the Subscription Plan will be `linked_to` - The `amount` and `currency` of the Subscription Plan - Additional details of the Subscription Plan. For detailed API information, please see our [Subscriptions Plans API Reference](/api/subscription-plans/createsubscriptionplan). At this time, only APPROVED Merchants with one of the following processors can create Subscription Plans: - `DUMMY_V1` - `FINIX_V1` ```shell Create Subscription Plan Request curl https://finix.sandbox-payments-api.com/subscription_plans \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USksBJMwkNUz5GyxPevL2yFY:71b641c1-861d-435b-9a9c-532760731c5e \ -X POST \ -d '{ "amount": 1099, "currency": "USD", "plan_name": "Bronze Plan", "description": "Test", "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N", "linked_type": "MERCHANT", "billing_interval": "MONTHLY", "billing_defaults": { "collection_method": "BILL_AUTOMATICALLY" }, "trial_defaults": { "interval_type": "MONTH", "interval_count": "1" } }' ``` ```json Create Subscription Plan Response { "id": "subscription_plan_cd92Tzs8qNPbNbd2JMhN5", "created_at": "2024-07-13T00:28:58.42Z", "updated_at": "2024-07-13T00:28:58.42Z", "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N", "linked_type": "MERCHANT", "billing_interval": "MONTHLY", "nickname": null, "plan_name": "Bronze Plan", "description": "Test", "amount": 1099, "currency": "USD", "billing_defaults": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false }, "trial_defaults": { "interval_type": "MONTH", "interval_count": 1 }, "state": "ACTIVE", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscription_plans/subscription_plan_cd92Tzs8qNPbNbd2JMhN5" } } } ``` ## Creating a Subscription from a Subscription plan via the API To create a Subscription from a Subscription Plan, specify the `subscription_plan_id` in the request body of a `Subscription`. Example API Definition Example Subscription - From Subscription Plan ```json Subscription - From Subscription Plan { "id" : "subscription_cA2DeRbnuvrPQHK2HooT7", "created_at" : "2026-05-14T14:46:30.73Z", "updated_at" : "2026-05-14T14:46:30.73Z", "amount" : 19900, "application_id" : "APc9vhYcPsRuTSpKD9KpMtPe", "billing_interval" : "MONTHLY", "buyer_details" : { "identity_id" : "IDtEnKsZyJNUGK83ZTx4C45S", "instrument_id" : "PImXAVgkKVshKWWHUk4xXbve", "requested_delivery_methods" : [ { "type" : "EMAIL", "destinations" : [ "abc@test.com" ] }, { "type" : "SMS", "destinations" : [ "2348765431" ] } ], "shipping_address" : { "city" : "Middletown", "country" : "USA", "line1" : "324 Oak Avenue", "line2" : "Apartment 7", "postal_code" : "19734", "region" : "DE" } }, "canceled_via" : null, "currency" : "USD", "expires_at" : "2028-06-01T00:00:00.000Z", "first_charge_at" : "2027-06-01T00:00:00.000Z", "has_usage_based_plan" : false, "linked_to" : "MUxdJCr9xTMnmt1vGUAqV9z4", "linked_type" : "MERCHANT", "next_billing_date" : { "year" : 2027, "month" : 6, "day" : 1 }, "nickname" : "Finflix Gold Package", "start_subscription_at" : "2027-06-01T00:00:00.000Z", "state" : "NOT_STARTED", "subscription_details" : { "collection_method" : "BILL_AUTOMATICALLY", "send_invoice" : false, "send_receipt" : false, "trial_details" : null, "discount_phase_details" : null, "notification_preferences" : { "send_confirmation" : false } }, "subscription_link_id" : null, "subscription_phase" : "NONE", "subscription_plan_id" : "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE", // [!code highlight] "tags" : { "order_number" : "21DFASJSAKAS" }, "total_billing_intervals" : 12, "_links" : { "self" : { "href" : "https://finix.sandbox-payments-api.com/subscriptions/subscription_cA2DeRbnuvrPQHK2HooT7" } } } ``` API Definition ## Creating a Subscription from a Subscription plan via the API with a start date You can specify a start date for a `Subscription` that uses a [Subscription Plan](/guides/subscriptions/subscription-plans). To do so, include a `start_subscription_at` timestamp in the request body: Example API Definition Example Subscription - From Subscription Plan - Future Start Date ```json Subscription - From Subscription Plan - Future Start Date { "id" : "subscription_cA2DeRbnuvrPQHK2HooT7", "created_at" : "2026-05-14T14:46:30.73Z", "updated_at" : "2026-05-14T14:46:30.73Z", "amount" : 19900, "application_id" : "APc9vhYcPsRuTSpKD9KpMtPe", "billing_interval" : "MONTHLY", "buyer_details" : { "identity_id" : "IDtEnKsZyJNUGK83ZTx4C45S", "instrument_id" : "PImXAVgkKVshKWWHUk4xXbve", "requested_delivery_methods" : [ { "type" : "EMAIL", "destinations" : [ "abc@test.com" ] }, { "type" : "SMS", "destinations" : [ "2348765431" ] } ], "shipping_address" : { "city" : "Middletown", "country" : "USA", "line1" : "324 Oak Avenue", "line2" : "Apartment 7", "postal_code" : "19734", "region" : "DE" } }, "canceled_via" : null, "currency" : "USD", "expires_at" : "2028-06-01T00:00:00.000Z", "first_charge_at" : "2027-06-01T00:00:00.000Z", "has_usage_based_plan" : false, "linked_to" : "MUxdJCr9xTMnmt1vGUAqV9z4", "linked_type" : "MERCHANT", "next_billing_date" : { "year" : 2027, "month" : 6, "day" : 1 }, "nickname" : "Finflix Gold Package", "start_subscription_at" : "2027-06-01T00:00:00.000Z", "state" : "NOT_STARTED", "subscription_details" : { "collection_method" : "BILL_AUTOMATICALLY", "send_invoice" : false, "send_receipt" : false, "trial_details" : null, "discount_phase_details" : null, "notification_preferences" : { "send_confirmation" : false } }, "subscription_link_id" : null, "subscription_phase" : "NONE", "subscription_plan_id" : "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE", // [!code highlight] "tags" : { "order_number" : "21DFASJSAKAS" }, "total_billing_intervals" : 12, "_links" : { "self" : { "href" : "https://finix.sandbox-payments-api.com/subscriptions/subscription_cA2DeRbnuvrPQHK2HooT7" } } } ``` API Definition --- # Subscriptions Quickstart Source: https://docs.finix.com/guides/subscriptions/subscriptions-quickstart Learn how to create subscriptions quickly using the Finix Dashboard or using the Finix API. Subscriptions allow you to charge a fixed amount to card or bank account on a recurring time period. You can use Subscriptions to charge buyers, customers, and more. Example use cases for Subscriptions: - Charging buyers a recurring monthly fee to access a gym or health club - Charging buyers an annual membership fee for services or goods rendered - Charging merchants a monthly or annual fee for using your software Pricing This product requires an additional fee. Please get in touch with your Finix Point of Contact for pricing on this feature. ## Creating a Subscription on the Finix Dashboard You can create a `Subscription` in the Finix Dashboard without any development work. Using the Finix Dashboard, you can: - Create subscriptions from existing buyers and payment instruments - View the existing `Subscriptions` - Cancel a `Subscription` if a buyer or customer chooses to end their goods or services ### Step 1: Navigate to Subscriptions To create a Subscription in the Finix Dashboard: 1. Log into the [Finix Dashboard](https://finix.payments-dashboard.com/Login). 2. Click **Subscriptions**. Subscriptions List Page 1. Click **Create Subscription** Subscriptions List Page 1. Fill out the form with the requested details. ### Step 2. Create a Subscription When you click on **Create Subscription**, a form will appear with the following options: #### Billing settings This section specifies how you want to bill your buyers. - Subscription Name - Billing Frequency - Recurring Price Create Subscriptions #### Trial phase You can enter a trial phase if your `Subscription` requires a set number of days before charging the buyer. For example, a 30-day trial, 3-month trial, or other combinations are possible. #### Discount phase You can enter a discount phase if you would like to have a discounted rate for a set of amount of intervals. These take place after the Trial Phase is completed. #### Start date You can specify a start date for the subscription in the future. This can be useful if you would like all your subscriptions to start on the same day. #### Interval length If you want to create a Subscription for a set amount of time, you can specify an interval length. For example, if you have a monthly subscription, you can specify an interval length of 6 and the subscription will bill for 6 months. #### Select Buyer When you create a Subscription, you'll need to: 1. Select a buyer you want to charge. This can be either a buyer, seller, or recipient identity. 2. Select the payment instrument you want to bill. #### Creating a Buyer and Payment Instrument On the **Create Subscription** page, we allow you to create a buyer and a card payment instrument. If you would like to add a bank account on this page, you will need to use our API. If you require an exception, email our support team. #### Review and create Subscriptions After filling out the previous section, you can create the subscription. Depending on whether there is a trial phase or not, the subscription will create a transfer shortly after creation. The initial transfer will be made within 60 minutes of the subscription creation. ##### Card validation with $0 Authorization When a subscription is created using a card-type payment instrument, Finix automatically performs a **$0 `Authorization`** to validate the card. This soft check confirms that the card is active and that the billing address and security code match the card issuer’s records (AVS and CVV checks). By performing this check up front, Finix helps reduce failed payments and prevent fraudulent transactions — ensuring a smoother experience for both you and your customers. ## Additional details ### Supported payment methods Subscriptions currently support: - Recurring Card payments - Recurring Bank account payments (ACH in USA and EFTs in Canada) For more details about ACH payments, see [ACH Direct Debit](/guides/online-payments/bank-payments/ach-direct-debits). ### Supported time periods Finix supports the following time periods for Subscriptions: - Daily - Weekly - Monthly - Quarterly - Yearly When creating a Subscription, you can specify the `billing_frequency`. ## Creating a Subscription via API To create a Subscription, include: - The ID of the `Merchant` that the `Subscription` will be `linked_to` - The `amount` and `currency` of the `Subscription` - The `subscription_details` - The `buyer_details` including both the `identity_id` and `instrument_id` At this time, only APPROVED Merchants with one of the following processors can create subscriptions: - `DUMMY_V1` - `FINIX_V1` For detailed API information, please see our [Subscriptions API Reference](/api/subscriptions/createsubscription). The following example shows how to create a basic subscription: Example API Definition Example Subscription ```json Subscription { "id": "subscription_cEpKYsVx13tE7utwrEwSz", "created_at": "2026-09-25T20:05:44.63Z", "updated_at": "2026-09-25T20:05:44.63Z", "amount": 10000, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "billing_cycle_day": 25, "billing_interval": "MONTHLY", "buyer_details": { "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S", "instrument_id": "PImXAVgkKVshKWWHUk4xXbve", "requested_delivery_methods": [], "shipping_address": null }, "canceled_via": null, "currency": "USD", "expires_at": null, "first_charge_at": "2026-09-25T20:05:43.00Z", "has_usage_based_plan": false, "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ", "linked_type": "MERCHANT", "next_billing_date": { "year": 2026, "month": 9, "day": 25 }, "nickname": null, "start_subscription_at": "2026-09-25T20:04:43.651Z", "state": "ACTIVE", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false, "trial_details": null, "discount_phase_details": null, "notification_preferences": { "send_confirmation": false } }, "subscription_link_id": null, "subscription_phase": "EVERGREEN", "subscription_plan_id": null, "tags": {}, "total_billing_intervals": null, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cEpKYsVx13tE7utwrEwSz" } } } ``` API Definition ### Trial period You can create a subscription with a trial period by providing `trial_details` in the request body. For example, to include a trial period that lasts one month set `trial_details.interval_type` to `MONTH` and `trial_details.interval_count` to `1`. After creating a `Subscription`, a `Transfer` will occur after the trial period has elapsed. The `first_charge_at` property in the response determines when the `Transfer` will occur. Example API Definition Example Subscription - Trial Period ```json Subscription - Trial Period { "id": "subscription_cEpKYD3JD1iypyN3Vghiu", "created_at": "2026-09-25T20:05:47.00Z", "updated_at": "2026-09-25T20:05:47.00Z", "amount": 10000, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "billing_cycle_day": 25, "billing_interval": "MONTHLY", "buyer_details": { "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S", "instrument_id": "PImXAVgkKVshKWWHUk4xXbve", "requested_delivery_methods": [], "shipping_address": null }, "canceled_via": null, "currency": "USD", "expires_at": null, "first_charge_at": "2026-10-25T20:05:46.00Z", // [!code highlight] "has_usage_based_plan": false, "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ", "linked_type": "MERCHANT", "next_billing_date": { "year": 2026, "month": 10, "day": 25 }, "nickname": null, "start_subscription_at": "2026-09-25T20:04:46.243Z", "state": "ACTIVE", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false, "trial_details": { "interval_type": "MONTH", "interval_count": 1, "trial_started_at": "2026-09-25T20:04:46.24Z", "trial_expected_start_at": "2026-09-25T20:04:46.24Z", "trial_expected_end_at": "2026-10-26T06:33:52.24Z" }, "discount_phase_details": null, "notification_preferences": { "send_confirmation": false } }, "subscription_link_id": null, "subscription_phase": "TRIAL", // [!code highlight] "subscription_plan_id": null, "tags": {}, "total_billing_intervals": null, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cEpKYD3JD1iypyN3Vghiu" } } } ``` API Definition ### Discount period To apply a discount period, include `discount_phase_details` in the request body. For example, if the full subscription price is $20 per month, and you want to offer a discounted rate of $10 per month for three months, set `discount_phase_details.amount` to `1000` and `discount_phase_details.billing_interval_count` to `3`. After this discount period, the subscriber will be charged the full `amount` of the `Subscription`. Example API Definition Example Subscription - Discount Phase ```json Subscription - Discount Phase { "id": "subscription_cxe8oDnBbKKDGMQQaWZca", "created_at": "2026-02-17T18:38:50.28Z", "updated_at": "2026-02-17T18:38:50.28Z", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "first_charge_at": "2026-02-17T18:38:50.00Z", "next_billing_date": { "year": 2026, "month": 2, "day": 17 }, "amount": 2000, "buyer_details": { "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S", "instrument_id": "PImXAVgkKVshKWWHUk4xXbve", "requested_delivery_methods": [], "shipping_address": null }, "currency": "USD", "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ", "linked_type": "MERCHANT", "nickname": "Finflix Gold Package", "billing_interval": "MONTHLY", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false, "trial_details": null, "discount_phase_details": { "amount": 1000, "billing_interval_count": 3, "discount_phase_started_at": "2026-02-17T18:37:50.01Z", "discount_phase_expected_start_at": "2026-02-17T18:37:50.01Z", "discount_phase_expected_end_at": "2026-05-17T18:37:50.01Z" }, "notification_preferences": { "send_confirmation": false } }, "subscription_phase": "DISCOUNT", // [!code highlight] "state": "ACTIVE", "subscription_plan_id": null, "start_subscription_at": "2026-02-17T18:37:50.010Z", "total_billing_intervals": null, "expires_at": null, "canceled_via": null, "tags": {}, "subscription_link_id": null, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cxe8oDnBbKKDGMQQaWZca" } } } ``` API Definition ### Start date Finix allows you to specify a start date for subscriptions. The `start_subscription_at` field takes an ISO8601 formatted timestamp to start the subscription. The timestamp must be in the future. Example API Definition Example Subscription - Future Start Date ```json Subscription - Future Start Date { "id": "subscription_cEpKYiFpEsQsgnRhoAP5G", "created_at": "2026-09-25T20:05:42.47Z", "updated_at": "2026-09-25T20:05:42.47Z", "amount": 10000, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "billing_cycle_day": 1, "billing_interval": "MONTHLY", "buyer_details": { "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S", "instrument_id": "PImXAVgkKVshKWWHUk4xXbve", "requested_delivery_methods": [], "shipping_address": null }, "canceled_via": null, "currency": "USD", "expires_at": null, "first_charge_at": "2027-06-01T00:00:00.00Z", // [!code highlight] "has_usage_based_plan": false, "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ", "linked_type": "MERCHANT", "next_billing_date": { "year": 2027, "month": 6, "day": 1 }, "nickname": null, "start_subscription_at": "2027-06-01T00:00:00.000Z", // [!code highlight] "state": "NOT_STARTED", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false, "trial_details": null, "discount_phase_details": null, "notification_preferences": { "send_confirmation": false } }, "subscription_link_id": null, "subscription_phase": "NONE", "subscription_plan_id": null, "tags": {}, "total_billing_intervals": null, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cEpKYiFpEsQsgnRhoAP5G" } } } ``` API Definition ### Billing cycle day By default, a subscription bills on the day the subscription starts. For example, a monthly subscription that starts on March 15 bills on the 15th of every month. To bill on a different day of the month, include `billing_cycle_day` in the request body. This field sets the day of the month the buyer is charged, no matter what day the subscription starts. The value must be a whole number between 1 and 31. You can set a billing cycle day for the following `billing_interval` values: - `MONTHLY` - `BIMONTHLY` - `QUARTERLY` - `SEMIYEARLY` - `YEARLY` - `BIYEARLY` - `TRIYEARLY` `DAILY`, `WEEKLY`, and `BIWEEKLY` subscriptions do not support a billing cycle day. #### End of month handling If a month does not include the day you selected, Finix charges the buyer on the last day of that month instead. For example, a subscription with a `billing_cycle_day` of `31` bills on April 30, then on May 31. #### Proration period If a subscription starts on a day that does not match the `billing_cycle_day`, Finix prorates the first invoice so the buyer only pays for the days between the start date and the first billing cycle day. This partial period is called the **proration period**. After the proration period, the buyer is charged the full amount on the billing cycle day. ##### Example 1 - Proration period A monthly subscription is created on **March 15** with a `billing_cycle_day` of `1`: - The buyer is charged a prorated amount for the proration period, March 15 to April 1. - Starting April 1, the buyer is charged the full amount on the 1st of every month. Proration period for a subscription created on March 15 with a billing cycle day of 1 ##### Example 2 - Proration period with 7-day free trial The same subscription with a 7-day free trial added: - The trial runs from March 15 to March 22. - The buyer is charged a prorated amount for the proration period, March 22 to April 1. - Starting April 1, the buyer is charged the full amount on the 1st of every month. Proration period for a subscription created on March 15 with a 7-day trial #### Proration formula Finix calculates the prorated amount as follows: `prorated amount` = (`days in proration period` / `days in month`) × `amount of period` To visualize this, the following examples all use a subscription created on **March 15**: | Subscription Created | `billing_cycle_day` | Proration Period | Billing Starts | Days in Month | | --- | --- | --- | --- | --- | | March 15 | `1` | 17 days (March 15 to April 1) | April 1 | 31 days (March 1 to April 1) | | March 15 | `20` | 5 days (March 15 to March 20) | March 20 | 28 days (February 20 to March 20) | | March 15 | `31` | 16 days (March 15 to March 31) | March 31 | 31 days (February 28 to March 31) | In the last row, one month before March 31 would be February 31. That date does not exist, so Finix uses the last day of February instead. As a full example: a $20.00 monthly subscription created on March 15 with a `billing_cycle_day` of `1` results in a prorated first charge of (17 / 31) × $20.00 = $10.97. #### Updating the billing cycle day You can change the `billing_cycle_day` of an existing subscription. When you do: - Invoices that have already been issued do not change. - The current billing period still completes at the full amount. - On the next billing date, the buyer is charged a prorated amount that bridges the gap from the old billing cycle day to the new one. Full billing then resumes on the new billing cycle day. For example, a monthly subscription is created on March 15, and the buyer is charged the full amount for March 15 to April 15. On April 12, you change the `billing_cycle_day` to `1`: 1. On April 15 (the next billing date), the buyer is charged a prorated amount covering April 15 to May 1. 2. Starting May 1, the buyer is charged the full amount on the 1st of every month. Update Billing Cycle Day API Request Example: ```shell curl -i -X PUT \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/subscriptions \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "billing_cycle_day": 1 }' ``` API Response: ```json { "id": "subscription_cAcHtdprA5N9Nw6nKfWbt", "created_at": "2026-05-19T22:27:55.83Z", "updated_at": "2026-05-19T22:27:55.83Z", "amount": 19900, "application_id": "AP1", "billing_cycle_day": 21, "billing_interval": "MONTHLY", "buyer_details": { "identity_id": "IDe8MHoq9cevVGocJwpAN8tR", "instrument_id": "PIh5syYGDw2SnvFjPVLcV3oD", "requested_delivery_methods": [], "shipping_address": null }, "canceled_via": null, "currency": "USD", "expires_at": null, "first_charge_at": "2026-05-20T22:26:55.576Z", "has_usage_based_plan": false, "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N", "linked_type": "MERCHANT", "next_billing_date": { "year": 2026, "month": 5, "day": 20 }, "nickname": "Michael Gym Membership - Gold Gym #22919132", "start_subscription_at": "2026-05-20T22:26:55.576Z", "state": "ACTIVE", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false, "trial_details": null, "discount_phase_details": null, "notification_preferences": { "send_confirmation": false } }, "subscription_link_id": null, "subscription_phase": "EVERGREEN", "subscription_plan_id": null, "tags": { "key1": "value1", "key2": "value2" }, "total_billing_intervals": null, "_links": { "self": { "href": "http://localhost/subscriptions/subscription_cAcHtdprA5N9Nw6nKfWbt" } } } ``` ### Fixed length Subscriptions Fixed-length subscriptions automatically expire after a set period. There are two ways to define the end of a subscription: - **By billing intervals**: pass `total_billing_intervals` to expire the subscription after a fixed number of billing cycles. - **By end date**: pass `end_subscription_at` to set an explicit end date. Finix prorates the final charge if the subscription ends mid-cycle. You cannot use both fields in the same request. In both cases, the response returns `subscription_phase: FIXED`, and both `total_billing_intervals` and `end_subscription_at` are populated. One echoes the request value and the other is calculated by Finix. The `expires_at` field mirrors `end_subscription_at`. #### By billing intervals Example API Definition Example Subscription - Fixed-Length ```json Subscription - Fixed-Length { "id": "subscription_cxe8rTTPCwzUu7p1zmk6t", "created_at": "2026-02-17T18:39:34.38Z", "updated_at": "2026-02-17T18:39:34.38Z", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "first_charge_at": "2026-02-17T18:39:33.00Z", "next_billing_date": { "year": 2026, "month": 2, "day": 17 }, "amount": 19900, "buyer_details": { "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S", "instrument_id": "PImXAVgkKVshKWWHUk4xXbve", "requested_delivery_methods": [], "shipping_address": null }, "currency": "USD", "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ", "linked_type": "MERCHANT", "nickname": null, "billing_interval": "MONTHLY", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false, "trial_details": null, "discount_phase_details": null, "notification_preferences": { "send_confirmation": false } }, "subscription_phase": "FIXED", // [!code highlight] "state": "ACTIVE", "subscription_plan_id": null, "start_subscription_at": "2026-02-17T18:38:33.747Z", "total_billing_intervals": 12, "expires_at": "2027-02-17T18:38:33.747Z", // [!code highlight] "canceled_via": null, "tags": {}, "subscription_link_id": null, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cxe8rTTPCwzUu7p1zmk6t" } } } ``` API Definition #### By end date Example API Definition Example Subscription - Fixed-Length - End Date ```json Subscription - Fixed-Length - End Date { "id": "subscription_cEQ6BbGxhCZuK8GcxWd7Z", "created_at": "2026-10-08T16:37:27.96Z", "updated_at": "2026-10-08T16:37:27.96Z", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "first_charge_at": "2026-10-08T16:37:25.00Z", "next_billing_date": { "year": 2026, "month": 10, "day": 8 }, "amount": 19900, "billing_cycle_day": 8, "billing_interval": "MONTHLY", "buyer_details": { "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S", "instrument_id": "PImXAVgkKVshKWWHUk4xXbve", "requested_delivery_methods": [], "shipping_address": null }, "currency": "USD", "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ", "linked_type": "MERCHANT", "nickname": null, "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false, "trial_details": null, "discount_phase_details": null, "notification_preferences": { "send_confirmation": false } }, "subscription_phase": "FIXED", // [!code highlight] "state": "ACTIVE", "subscription_plan_id": null, "start_subscription_at": "2026-10-08T16:36:25.591Z", "end_subscription_at": "2026-12-31T18:39:34.38Z", // [!code highlight] "total_billing_intervals": 3, // [!code highlight] "expires_at": "2026-12-31T18:39:34.380Z", // [!code highlight] "canceled_via": null, "has_usage_based_plan": false, "tags": {}, "subscription_link_id": null, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cEQ6BbGxhCZuK8GcxWd7Z" } } } ``` API Definition --- # Updating a Subscription Plan on an Existing Subscription Source: https://docs.finix.com/guides/subscriptions/updating-subscription-plan-existing-subscription Learn how to update Subscription Plans for an existing subscription. ## Overview Finix supports the ability to upgrade or downgrade a customer’s subscription between different plans — for example, moving from the Basic plan to the Enterprise plan, or vice versa. This can be done at any time using the Subscriptions API. Plan changes are applied immediately, and billing is automatically adjusted based on the timing and direction of the change. ### How plan changes work When a subscription’s plan is changed: - **The new plan takes effect immediately.** As soon as the change is made, the customer is moved to the new plan. - **The new plan picks up where the old one left off.** The subscription continues from the same point in time; for example, if you’re 60 days in, the new plan also starts at day 60. - **Billing is prorated based on the change.** Finix automatically adjusts billing depending on whether the new plan is more or less expensive than the previous one: - If upgrading to a more expensive plan (e.g., from Basic to Enterprise): A prorated charge is immediately applied for the remainder of the billing period at the new plan’s rate. - If downgrading to a less expensive plan (e.g., from Enterprise to Basic): A prorated credit is issued for the unused portion of the previous plan. - **The billing cycle remains unchanged.** This means that the subscription continues to follow its original billing schedule. - If the current subscription is still in an initial phase (such as TRIAL or DISCOUNT), and the new plan has a longer initial phase, the remaining initial phase will be extended to match the new plan’s phase duration. - If the current subscription is in an initial phase but the new plan does not include an initial phase, the trial ends immediately and the subscription transitions into the next phase of the new plan (typically the EVERGREEN phase). ### Examples If a customer on the Basic plan upgrades to the Enterprise plan on June 10, the Enterprise plan takes effect immediately on June 10. A prorated charge for the remaining days of the billing period will occur right away. If a customer downgrades from the Enterprise plan to the Basic plan on the same date, the Basic plan takes effect immediately, and a credit is applied for the remaining, unused portion of the Enterprise plan. ## Using the Finix API This feature is currently only available using our API. To update an existing Subscription to a new Subscription Plan, you can simply use a PUT to replace the previous `subscription_plan_id` with a new `subscription_plan_id`. ```bash curl "https://finix.sandbox-payments-api.com/subscriptions/subscription_cdhqdXjTQfg62wHzJ41g5" \ -H "Content-Type: application/json" \ -H "Finix-Version: 2022-02-01" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X PUT \ -d ' { "subscription_plan_id": "subscription_plan_cdgZcXBNDwWcqC4CwgGRS" }' ``` When this request is run, we will return a new response that will override the previous settings for the subscription. Below is a set of the impacted fields: ```json { "id" : "subscription_cdhqdXjTQfg62wHzJ41g5", "created_at" : "2024-06-05T22:42:05.49Z", "updated_at" : "2024-06-05T22:42:05.49Z", "first_charge_at" : "2024-07-05T22:41:46.00Z", "next_billing_date" : { "year" : 2024, "month" : 7, "day" : 22 }, "amount" : 10000, <- potentially impacted field, will need to be updated "buyer_details" : { "identity_id" : "IDeDVrf2ahuKc9Eg5TeZugvz", "instrument_id" : "PIeDVrf2ahuKc9Eg5TeZugvb", "requested_delivery_methods" : [] }, "currency" : "USD", "linked_to" : "MUeDVrf2ahuKc9Eg5TeZugvs", "linked_type" : "MERCHANT", "nickname" : "My Gym Membership", "billing_interval" : "MONTHLY", "subscription_details" : { "collection_method" : "BILL_AUTOMATICALLY", "send_invoice" : false, "send_receipt" : false, "trial_details" : { "interval_type" : "DAY", <- potentially impacted field, will need to be updated "interval_count" : 30, <- potentially impacted field, will need to be updated "trial_started_at": "2024-06-05T22:41:46.00Z", <- potentially impacted field, will need to be updated "trial_expected_start_at": "2024-06-05T22:41:46.00Z", <- potentially impacted field, will need to be updated "trial_expected_end_at" : "2024-07-05T22:41:46.00Z" <- potentially impacted field, will need to be updated }, "discount_phase_details": { "amount": 1000, <- potentially impacted field, will need to be updated "billing_interval_count": 3 <- potentially impacted field, will need to be updated } }, "subscription_phase" : "TRIAL", <- potentially impacted field, will need to be updated "state" : "ACTIVE", "subscription_plan_id" : "subscription_plan_cdgZcXBNDwWcqC4CwgGRS", <- new plan id is here "start_subscription_at" : "2024-06-05T22:42:05.49Z", "total_billing_intervals": null, "expires_at": null, "canceled_via": null, "tags": {}, "_links" : { "self" : { "href" : "http://localhost/subscriptions/subscription_5MRiVJdsK8iJNT9mKQ6WEk" } } } ``` ## Common Subscription plan change scenarios | Scenario | Description | What Happens | | --- | --- | --- | | Upgrade Mid-Cycle | Customer moves from Basic ($50) to Enterprise ($100) mid-billing cycle | New plan takes effect immediately; customer receives a prorated credit ($25) from the old plan and a prorated charge ($50) for the new plan, resulting in a net charge of $25 | | Downgrade Mid-Cycle | Customer moves from Enterprise ($100) to Basic ($50) mid-billing cycle | New plan takes effect immediately; customer receives a prorated credit ($50) from the old plan and a prorated charge ($25) for the new plan, resulting in a net credit of $25 | | In Trial → Upgrade to Longer Trial Plan | Customer is in a trial and switches to a plan with a longer trial | Trial period is extended to match the new plan's trial duration | | In Trial → Switch to No-Trial Plan | Customer is in a trial and switches to a plan without a trial | Trial ends immediately; customer is billed a prorated charge for the new plan | | No Trial → Switch to Trial Plan | Customer on a paid plan switches to a plan with a trial | Trial phase of the new plan starts immediately; no charge until trial ends | | Discount → No Discount | Customer switches from a discounted plan to one without a discount | Discount ends immediately; new plan charges apply starting from the change date | | No Discount → Discounted Plan | Customer switches to a plan with a discount phase | Discount phase on the new plan begins; any prior billing rate is replaced by new plan terms | | Back-to-Back Plan Changes | Customer changes plans twice in a short period (e.g., $50 → $100 → $120) | Each plan takes effect immediately; billing is prorated for time spent on each plan | --- # Viewing Subscription Payments Source: https://docs.finix.com/guides/subscriptions/viewing-subscription-payments Once a Subscription is created, you can view all its associated payments from the subscription details page. *To view a subscription's payments*: 1. In the Finix Dashboard, click **Subscriptions**. Alternatively, search for the subscription by its ID if known. 2. Click the Subscription you want to view. - The subscription details page displays. From this page, you can view all payments associated with the subscription, including when each payment occurred, each payment's status, and the buyer's details. 3. Click a payment to view its details. - The payment details page displays. ## Payment details page The payment details page gives you a full view of an individual subscription payment. ### Summary At the top of the page, the following information is displayed: | Field | Description | | --- | --- | | ID | The unique ID of the payment (Transfer). | | Trace ID | A trace ID you can use to track the payment across systems. | | Amount | The total amount charged, including currency. | | State | The current state of the payment (e.g., **Succeeded**). | | Created On | The date and time the payment was created. | | Type | The payment method type (e.g., **Card**). | | Buyer Payment Instrument | The masked payment instrument used and the buyer's name. | ### Transaction flow The transaction flow section shows the lifecycle of the payment as it moves through processing and settlement: - **Payment Succeeded** - The payment was successfully processed, showing the payment ID, amount, type, and timestamp. - **Payment Added to Accruing Settlement** - The payment was added to an open settlement. Click **View Settlement** to see the full settlement details. - **Settlement Approved** - The settlement containing this payment was approved. Click **View Settlement** to see the approved settlement. ### Payment details | Field | Description | | --- | --- | | Settlement State | The current state of the settlement this payment belongs to (e.g., **Approved**). | | Ready to Settle At | The date and time the payment became ready for settlement. | | Created Via | How the payment was initiated (e.g., **API**). | | Processor | The payment processor used to process the payment. | | Authorization Code | The authorization code returned by the card network. | | Statement Descriptor | The descriptor that appears on the buyer's card statement. | ### Buyer details | Field | Description | | --- | --- | | ID | The ID of the buyer's Identity resource. Click **View Recipient Details** to open it. | | Name | The buyer's full name. | | Email | The buyer's email address. | | Billing Address | The billing address associated with the payment. | | Phone | The buyer's phone number. | ### Additional fraud signals | Field | Description | | --- | --- | | Payment Instruments with Same Fingerprint ID | The number of other payment instruments that share the same card fingerprint. | | Payments with Same Fingerprint ID | The number of other payments that share the same card fingerprint. | ### Payment Instrument This section shows the details of the card or bank account used for the payment. | Field | Description | | --- | --- | | ID | The ID of the Payment Instrument resource. | | Fingerprint ID | A unique identifier for the card, consistent across tokenizations. | | State | Whether the payment instrument is **Enabled** or disabled. | | Created On | The date the payment instrument was created. | | Name | The cardholder name. | | Type | The payment instrument type (e.g., **Card**). | | Created Via | How the payment instrument was created (e.g., **API**). | | Card Brand | The card network (e.g., Visa, Mastercard). | | Card Type | The type of card (e.g., Debit, Credit). | | Masked Number | The masked card number. | | Expiration Date | The card's expiration date. | | CVV Verification | Whether the CVV provided matched the card (e.g., **Matched**). | | Address | The address on file for the payment instrument. | | Address Verification | The result of the address verification check (e.g., **Postal Code and Street Match**). | | Issuer Country | The country that issued the card. | ### Associated fees This table lists all fees applied to the payment. Click **View Fee Profile** to see the full fee profile. Each fee entry includes: | Column | Description | | --- | --- | | ID | The ID of the fee. | | Created On | The date the fee was applied. | | Fee Category | The category of the fee (e.g., **Processor**). | | Fee Type | The specific fee type (e.g., **Card Fixed**, **Card Basis Points**). | | Amount | The amount of the fee. | An **Estimated Total** for all associated fees is displayed at the bottom of the table. ### Refunds Displays any refunds associated with the payment. Click **Issue Refund** to initiate a refund directly from this page. ### Disputes Displays any disputes associated with the payment. ### Receipt history Displays any receipts that have been created or sent for this payment. Click **Create Receipt** to generate a new receipt. ### Tags Displays any tags associated with the payment. Subscription payments automatically include a `subscription_id` tag that links back to the originating Subscription. --- # Account Updater Source: https://docs.finix.com/guides/after-the-payment/account-updater Account Updater is a feature that automatically refreshes expired or updated card details for enabled Payment Instruments, eliminating the need for manual updates and ensuring uninterrupted payment processing. There are three main reasons why a card may need to be updated: 1. New account number 2. New expiration date 3. Account closed There are two ways to enable Account Updater: 1. **Enabling Account Updater for All New Payment Instruments of Type `PAYMENT_CARD`**: You can choose to enable Account Updater for all new cards. This ensures that all of your cards will always be up-to-date. 2. **Enabling Account Updater for an Individual Payment Instrument of Type `PAYMENT_CARD`**: You can enable Account Updater at an individual card level. This can be particularly useful if you just want a subset of your payment instruments to be enabled for Account Updater. When you enable a card for Account Updater, Finix will check the card networks daily to see if there is an update. ## Option 1: Enabling account updater for all new Payment Instruments This is a setting that will make it so all new Payment Instruments of type PAYMENT_CARD are enabled for Account Updater. To enable all new Payment Instruments for Account Updater: 1. Navigate to the Company Page on the Dashboard. 2. Clicking on **Company Settings** tab > **Payment Methods** tab. 3. Enable via the **Value Added Services** section Company Payment Instrument Settings ## Option 2: Enabling account updater for an individual Payment Instrument ### Finix Dashboard To enable a Payment Instrument for Account Updater: 1. Navigate to a Payment Instrument detail page 2. Find the Settings section 3. Click on the Edit Button and enable Payment Instrument Details - Edit Settings ### Using the Finix API You can use the Finix API to specify Payment Instruments to be enabled for Account Updater. You can pass in `account_updater_enabled` field. By default, we'll return false unless you enable `account_updater_enabled` at an Application level. ```shell Create Payment Instrument curl -X POST \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ https://finix.sandbox-payments-api.com/payment_instruments \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "account_updater_enabled": true, "address": { "city": "San Francisco", "country": "USA", "line1": "900 Metro Center Blv", "postal_code": "94404", "region": "CA" }, "expiration_month": 12, "expiration_year": 2029, "identity": "IDgWxBhfGYLLdkhxx2ddYf9K", "name": "John Smith", "number": "5200828282828210", "security_code": "022", "type": "PAYMENT_CARD" }' ``` ## Account updater logs ### Viewing Instrument history updates When a Card is updated, we generate a `Instrument History` resource. You can see this instrument history resource on the Dashboard and via API. Company Payment Instrument Settings ### Available card updates If Finix generates a card update, we'll create an Instrument History resource with one of the following enumerators. You can expect card update results within two to seven days, depending on how quickly the Issuing bank delivers the new card information to Finix. | Enumerator | Description | | --- | --- | | `CLOSED_CARD` | The cardholder's card has been closed. | | `CONTACT_CARDHOLDER` | The cardholder has opted out of Account Updater service with their bank. | | `EXPIRATION_UPDATED` | The expiration date has been updated. | | `FRAUD_REPORTED` | The cardholder has reported fraud with the Merchant who is requesting an update. This only applies to American Express. | | `INACTIVE_MERCHANT` | The Merchant has not been onboarded successfully. This only applies to American Express. | | `NO_TRANSACTIONAL_ACTIVITY` | Requires the card to have at least one transaction associated to the Application before returning updates. This only applies to American Express. | | `NOT_FOUND` | Card’s Issuing Bank does not participate in Account Updater. This enumerator will only be returned once. | | `NUMBER_AND_EXPIRATION_UPDATED` | Both the expiration date and card number have been updated. | | `NUMBER_UPDATED` | The card number has been updated. | ## How Account Updater works Enrollment happens automatically when `account_updater_enabled` is set to `true` on a Payment Instrument. There is no additional opt-in step per individual token. Once enrolled, Finix checks for updates before the next transaction attempt rather than on a fixed schedule. Keep these limitations in mind when enrolling cards: - **Processor eligibility:** Account Updater does not run on FINIX_V1 processor tokens. Only Payment Instruments on newer processor configurations are eligible for enrollment. - **First update lag:** After a card is first enrolled, several days may pass before the initial update cycle runs. Do not assume a card is current immediately after enabling `account_updater_enabled`. - **Already-expired cards:** Tokens created from cards that are already expired at the time of enrollment may not enroll successfully. Finix recommends enrolling cards while they are still active. ## Card brand specific rules American Express requires that a successful transfer be performed at least once with the payment instrument before it can be subscribed for updates. If a payment instrument is enabled and no successful transfers were done previously or occur within six months the payment instrument will automatically have its `account_updater_enabled` flag set to false. --- # After the Payment Source: https://docs.finix.com/guides/after-the-payment Learn about the post-payment lifecycle. After the Payment Hero Part of processing payments includes supporting the post-payments lifecycle. Finix offers several different ways you can support buyers and learn from transactions after funds have settled. In this section you'll learn about managing refunds, handling disputes, and more. ## Learn more Your Payout Schedule Learn when and how you get paid from the payments you've processed. Refunds Learn how to refund payments. Disputes Learn what to do when a buyer reports a payment to their issuing bank. Receipts Create and deliver itemized receipts for payments, authorizations, and refunds. Instant Payouts Move settled funds to an eligible debit card within minutes instead of waiting for the standard schedule. Account Updater Keep stored card details current automatically when buyers' cards are reissued. Network Tokens Improve authorization rates and security by replacing card numbers with network tokens. --- # Instant Payouts Source: https://docs.finix.com/guides/after-the-payment/instant-payouts You can request a `Settlement` to be paid out instantly to an eligible debit card. Funds are typically received in minutes. ## Instant Payouts eligibility Finix selectively enables Instant Payouts on merchant accounts. Instant Payouts are not enabled for all merchants. If you have any questions, please get in touch with your Finix Point of Contact. High-risk merchants are typically excluded from this feature. ## Requesting an instant Payout on the Dashboard When creating a sale using either our low-code products (payment links, virtual terminal, subscriptions), our payment terminals/devices, or the Finix API, Finix will create a `Settlement`. Settlements contain these transactions along with fees, sales, and any captures. Finix allows you to "pay out" these transactions earlier than usual, subject to an additional **1.5% fee**. This fee is added to the future `Settlement`. ## Instant Payouts restrictions and limits Instant Payouts are USA-only, and only Visa and Mastercard debit cards are eligible. Applications have the following limits on the number and volume of Instant Payouts: - $10,000 USD per day with a 10,000 USD maximum - $50,000 USD per month Merchants also have count and volume limits applied on a rolling basis. If you would like higher limits, reach out to your Finix point of contact or email the [Finix Support team](mailto:support@finix.com). ### Step 1: Navigate to a Settlement To request an instant payout, you first need to navigate to the **Merchant Payouts** page and select a settlement. Settlements List ### Step 2: Request an instant Payout - When you click on a settlement, click the **Payout Instantly** button. - A **Get Paid Instantly** pop-up displays. Instant Payouts Sidepanel ### Step 3: Select a debit card - From the **Get Paid Instantly** drop-down, select a debit card to payout to. - Instant Payouts are only eligible for Visa and MasterCard Debit Cards. If you don't have a debit card already associated with your merchant account, you will need to add one. ### Step 4: Request the instant Payout Instant Payouts Review Screen - After you select your debit card, click **Confirm**. - A "processing" pop-up displays. - Finix will initiate the Instant Payout. - When the Instant Payout succeeds, a confirmation page loads. Instant Payouts Funding Transfer Confirmation - You can optionally **View the Settlement** or **View All Settlements**. ## Issuer restrictions Some banks may reject the Instant Payout. If this happens, reach out to the [Finix Support team](mailto:support@finix.com). You may need to use a different debit card and retry the Instant Payout. ## Requesting an instant Payout using the API In addition to requesting an Instant Payout via the Finix Dashboard, you can also use the API. ### Prerequisites - Your `Application` is enabled for Instant Payouts - A `Merchant` has been enabled for Instant Payout - A debit card has been created and linked to the merchant’s `Identity` you want to request a payout for. ### Step 1: Identify the Settlement Instant Payouts are based on settlements. You can pay out settlements that have a `state` of `PENDING` or `AWAITING_APPROVAL`. #### Additional notes - The `Merchant` will receive the `net_amount` of the `Settlement` - You cannot instantly pay out a `Settlement` that has a negative `net_amount` The `net_amount` is the amount in cents that will be deposited into the merchant's bank account. ### Step 2: Request an instant Payout Send a request to the POST `/settlements/{settlement_id}/funding_transfer_attempts` endpoint, passing the following data in the request body: - the payment card to submit the funds to as the `instrument_Id`, and - the `amount` of the instant payout (the `net_amount` from the `Settlement`) #### Request ```shell Funding Transfer Request curl https://finix.sandbox-payments-api.com/settlements/STjRXh8DAJs7HsDgregrSuiK/funding_transfer_attempts \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USksBJMwkNUz5GyxPevL2yFY:71b641c1-861d-435b-9a9c-532760731c5e \ -X POST \ -d '{ "instrument_id": "PIfbd85QZnb4dAGHHBrLiTeh", "amount": 101059 }' ``` #### Response ```json Funding Transfer Response { "id": "funding_transfer_attempt_mocGf9ygfXdspxftzqizFW", "created_at": "2025-01-30T01:01:00.47Z", "updated_at": "2025-01-30T01:01:00.47Z", "amount": 101059, "application_id": "APsi2UkE1BgD1aq839yKrwRh", "currency": "USD", "failure_code": null, "failure_message": null, "funding_transfer_id": "TRmjGDHpt53BPhbx2vb5WAhn", "instrument_id": "PIfbd85QZnb4dAGHHBrLiTeh", "merchant_id": "MUa1CDgJL9vibs3BTFoL4DNa", "settlement_id": "STjRXh8DAJs7HsDgregrSuiK", "state": "SUCCEEDED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/settlements/STjRXh8DAJs7HsDgregrSuiK/funding_transfer_attempts" } } } ``` View the [Funding Transfer Attempt API Reference](/api/settlements/createsettlementfundingtransferattempt) for more information on using the API to send instant payouts. ## Enabling instant Payouts on a Merchant Work with your Customer Delivery Manager to identify any merchants you want to enable this feature on. --- # Network Tokens Source: https://docs.finix.com/guides/after-the-payment/network-tokens Leverage network tokenization to improve your authorization rates. ## What are Network tokens? Network tokens are digital payment credentials that can replace Primary Account Numbers (PANs) for online transactions. Finix integrates with Visa, Mastercard, and Discover to convert a user's stored PANs into network tokens. These tokens are managed by Finix to ensure they remain up-to-date, even if the original card details change. For instance, if a customer loses their card or if it expires, Finix receives a notification from the network and automatically updates the token. This allows the token to remain functional without requiring the customer to manually update their payment information. ## Why use Network tokens? - **Increased Authorization Rates:** Network tokens can increase authorization rates, leading to more approved payments and higher revenue for your business. - **Lower Interchange Fees:** Visa often charges lower interchange fees on transactions utilizing network tokens. - **Improved Customer Experience:** By automatically updating payment details, network tokens remove the need for customers to manually refresh their card details, ensuring a seamless, hassle-free experience for both customers and merchants. Rather than waiting for the cardholder to activate a new card, you can continue accepting the card on file without interruption — thanks to network tokens. There are two ways to enable Network Tokens: 1. **Enabling Network Tokens for All New Payment Instruments:** You can choose to enable Network Tokens for all new cards. 2. **Enabling Network Tokens for an Individual Payment Instrument:** You can enable Network Tokens at an individual Payment Instrument level. This can be particularly useful if you just want a subset of your payment instruments to be enabled for Network Tokens. ## Option 1: Enabling Network tokens for all new Payment Instruments To enable new Payment Instruments of type `PAYMENT_CARD` for Network Tokens, contact your Finix Representative or email [support@finix.com](mailto:support@finix.com). This is a setting that will make it so all new Card Payment Instruments are enabled for Network Tokens If you would like to include all previously created cards for Network Tokens, please let us know in your request. You can see if you are enabled for Network Tokens by: 1. Navigating to the Company Page on the Dashboard. 2. Clicking on **Company Settings** tab > **Payment Methods** tab. Account Update Application Payment Instrument ## Option 2: Enabling Network tokens for an individual Payment Instrument ### Finix Dashboard To enable a Payment Instrument of type `PAYMENT_CARD` for Network Tokens: 1. Navigate to a Payment Instrument detail page 2. Find the Settings section 3. Click on the Edit Button and enable Payment Instrument Details - Edit Settings ### Using the Finix API to enable an individual card You'll pass `network_token_enabled` is true to enable a specific card. If you already created the card, you can instead run a [PUT request](/api/payment-instruments/updatepaymentinstrument) to enable the card. Immediately upon enabling a specific card for network tokens, we'll return `PENDING` for `network_token_state` while we wait for the Issuing bank to generate a token and return it to us. This should take a couple of seconds, depending on how fast the Issuing bank returns the network token. If network_token_enabled is true and `network_token_state` is `ACTIVE`, we will not use the underlying PAN, and instead use the network token. Alternatively, if `network_token_state` is still in the `PENDING` state, we'll submit the transaction with the underlying PAN until `network_token_state` is `ACTIVE`. You can see below for all of the available enumerators. Once the card has a `network_token_state` of `ACTIVE`, you can use the Payment Instrument ID to create transactions. ```shell Network Token Payment Instrument curl -X POST \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ https://finix.sandbox-payments-api.com/payment_instruments \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "network_token_enabled": true, "token": "TKiMxe323RE5Dq3wLVtG8kSW", "type": "TOKEN", "identity": "IDpYDM7J9n57q849o9E9yNrG" }' ``` ### Network token state If you enable network tokens, `network_token_state` can return the following values. | Enumerator | Description | | --- | --- | | `ACTIVE` | The card and token are in good standing. | | `CLOSED` | The cardholder has closed their account. | | `FAILED` | The network token request failed to provision a token successfully, either because the card is not eligible or due to a system error. | | `NOT_ENABLED` | This is the initial state while the network token enabled is false. | | `PENDING` | The card is enabled for network tokens and is in the process of requesting a network token from the card brands. | | `SUSPENDED` | The Issuing bank has temporarily suspended the use card of the card, and it cannot be used for transactions. The merchant can contact the cardholder in advance to use a different card or have them contact their Issuing bank to reactivate their card. | ## How are Network tokens different from account updater? [Account updater](/guides/after-the-payment/account-updater) will ensure that you always have the up-to-date PAN, while with network tokens, you will not have access to the current PAN because it uses an underlying network token to process your transactions. The purpose of each is to increase authorization rates while improving the customer experience. --- # Your Payout Schedule Source: https://docs.finix.com/guides/after-the-payment/payouts Learn how you get paid from the payments you've processed. Card payouts are supported for cards issued in the United States only. Net Payouts As you process payments, Finix buckets the funds from transactions into Settlements. After Finix reviews and approves your settlement, you will receive a Funding Transfer with your payout. ## Payout schedule Finix processes payouts on a daily basis every business day. The timing of when funds from transactions are deposited into your merchant bank account depends on your payout configuration (T+1 or T+2) and the payment method used (card vs. ACH). Payout timing is based on business days (Monday-Friday), excluding [bank holidays](/guides/platform-payments/seller-payouts/approving-settlements#standard-federal-reserve-bank-holidays). Finix pays out to the bank account you provided in your `Onboarding Form`. Changing Payout Accounts You can change your payout account later, but it will require review by our risk team. ### Card transaction Settlements Finix offers two payout availability options for card transactions: #### T+1 availability Funds from card transactions are deposited into your bank account one business day after the transaction is processed. **Example**: > *A card transaction processed on Monday is batched Monday night. On Tuesday morning, Finix reviews and approves the settlement. The deposit is sent Tuesday early afternoon (EST) and typically appears in your bank account by Tuesday late afternoon.* #### T+2 availability Funds from card transactions are deposited into your bank account two business days after the transaction is processed. **Example**: > *A card transaction processed on Monday is batched Monday night. It is settled with the card networks on Tuesday (Day 1). Finix initiates an ACH transfer Tuesday evening. Funds are typically deposited into your bank account by Wednesday morning/afternoon (Day 2).* Caveats - In rare cases, some banks may have a delay in posting the deposit to your account. - Canadian card transactions have additional delays in funding. [Learn More](/guides/regional-considerations/canada#funding-schedule) ### ACH transaction Settlements ACH Direct Debits take longer than card transactions to settle due to different network protocols and the risk of returns. Finix holds ACH debits for a certain number of days to accommodate for any ACH returns (an ACH Settlement Delay). Finix's default delay is 5 business days for ACH Direct Debits. Refer to [ACH Direct Debit Timing](/guides/online-payments/bank-payments/ach-direct-debits#ach-direct-debit-timing) for more information. For information about faster payout options, see [Bank Payouts](/guides/payouts/bank-payouts#bank-payout-speeds). ## Payout type Finix offers two ways to configure payouts: **Net** and **Gross**. By default, payouts are calculated on a **Net** basis. To change your payouts schedule or payout type (net / gross), contact the [Finix Support team](mailto:support@finix.com). ### Net Fees get deducted from your payouts. In other words, deposits and fees are combined into one payout. br Net Payouts br br If you had $1000 in Payment and $30 in Fees, you'd receive a payout of $970 to your payout bank account. ### Gross Deposits and fees get distributed into two separate payouts. br Gross Payouts br br If you had a $1000 Payment and $30 in Fees, you would receive two payouts. The first would be a $1000 credit to your payout account. The second would be a debit of $30 to your other account. Using Finix, you can manage what accounts get used for your payouts. This includes which accounts you use for payouts and fees. ## Viewing Settlement details You can use the Finix Dashboard to find out: - When you'll be paid out - How much you will be paid - Why you're receiving a specific amount ### Accessing Settlement details After a payment succeeds, it is added to an accruing settlement. In most cases, the settlement closes automatically, and you become eligible for payout when the accrual window ends. Some merchants are set up to [release settlements manually](/guides/platform-payments/seller-payouts/releasing-transactions-manually), which requires a manual action to release the transaction. Follow these steps to view settlement details for a successful payment that was added to a settlement: 1. Go to **Transactions > Payments** in the Finix Dashboard. 2. Find and click the payment you wish to view the settlement details for. - A drawer opens from the right side showing a summary of the payment. 3. Locate the **"Transaction Flow"** section in the drawer. - Look for the entry labeled "Payment Added to Accruing Settlement". - Next to this entry, you'll see three vertical dots. 4. Click the three vertical dots and select **View Settlement**. Payment Summary View Settlement - The settlement details page displays with full information about the settlement. Settlement Details Page ### Understanding the Settlement details page The settlement details page is organized into several sections that help you understand your payout. #### Information header At the top of the Settlement Details page, you'll see key information about the settlement. Settlement Details Page Information Header The following information is displayed: - **Settlement State** - The current status of the settlement. - **Accruing** - The settlement is still open and collecting payments. More payments can be added to it. - **Awaiting Approval** - The settlement has closed but hasn't been approved yet. You're not eligible for payout until it's approved. - **Approved** - The settlement is closed and finalized. No more payments can be added. You're eligible for payout, and the payout has already been processed. - **Settlement Accrual Window** - *(Visible only when settlement state is Accruing or Awaiting Approval)* The timeframe during which the settlement collects payments. - Example: `12/20/25 9 PM - 12/21/25 9 PM` - Once this window closes at 9 PM, the settlement automatically moves to an approved state and you become eligible for payout. - **Funding Transfer Speed** - *(Visible only when settlement state is Accruing or Awaiting Approval)* When you'll receive your payout after the accrual window closes. - **Next-Day ACH** - Your payout will be transferred via ACH the next business day. - **Same-Day ACH** - Your payout will be transferred via ACH on the same day. - **Payout Profile** - How frequently you receive payouts and how fees are handled. - Example: `Daily - Net` - **Daily** means you receive payouts every business day (as opposed to weekly or monthly). - **Net** means fees are deducted from your payouts (deposits and fees are combined into one payout). - **Processor** - The payment processing entity responsible for handling transactions and fund movements. - Example: `DUMMY_V1` #### Settlement breakdown Below the information header, you'll see the **Settlement Breakdown** section. Settlement Details Page Amount Breakdown This section shows the following: - **Payments** - The total amount from all individual transactions included in this settlement. - **Fees** - Associated charges deducted from your payout. - **Net Amount (Total Payout Amount)** - The final amount you'll receive after fees are deducted. #### Merchant deposits *(Visible only when settlement state is Approved)* This section shows the status of funds transferred to your connected bank account. Settlement Details Page Merchant Deposits The following states are possible: - **Succeeded** - The payout was successfully deposited into your bank account. - **Failed** - The deposit did not go through, often due to incorrect bank information or a block by your bank. You may need to update your bank information or contact your bank. ## Payout delays Payouts may be delayed for several reasons: ### Risk review delays As a risk mitigation measure, Finix has the right to temporarily withhold the first payout while conducting a standard risk review. This review is a required step in our risk mitigation process and helps us verify the legitimacy of payments activity. During this time, Finix may request supporting documentation (such as invoices or service agreements) to validate transactions. Beyond the first large payout, Finix may also delay or hold subsequent payouts if we detect unusual activity. This may include large increases in settlement volume, high dispute rates, or elevated ACH return rates. These reviews are essential for fraud prevention and compliance with regulatory obligations. ### Bank processing delays Bank processing can be delayed by [weekends and holidays](/guides/platform-payments/seller-payouts/approving-settlements#standard-federal-reserve-bank-holidays). Once the bank has finished processing your payout, the funds will be deposited into your account automatically. Weekend and Holiday Processing If a payout is scheduled to be sent on a weekend or bank holiday, it will be processed on the next business day. For example, a payout scheduled for Saturday will be initiated on Monday morning. ## Negative Payouts In some cases, you can have a negative balance. For example, if you receive $200 but then process a refund for $300, your settlement amount would be -$100. If you don't process transactions to balance out the negative amount, Finix will eventually create a Funding Transfer that debits your payout bank account. ## Failed Payouts If a funding transfer fails, Finix **disables** the merchant's settlements and automatically retries the funding transfer according to the following schedule: - **First retry** - 1 business day after the initial failure - **Second retry** - 3 business days after the first retry fails If both retries fail, the merchant goes under review and Finix's Risk team will reach out for next steps. --- # Accepting Disputes Source: https://docs.finix.com/guides/after-the-payment/disputes/accepting-disputes Accepting a Dispute avoids a long and potentially expensive process. When you accept a Dispute, you concede that it isn't worth challenging or representing. After you accept a Dispute, Finix marks it as `LOST`. You may want to concede a Dispute if: - You agree with the buyer. - You don't have evidence. - The transaction amount is low and you don't want to invest time to respond and represent the Dispute. - You suspect fraud or an internal issue. You can accept a Dispute only when `Dispute#response_state` is `NEEDS_RESPONSE`. For more information on responding instead of accepting, see [Responding to disputes](/guides/after-the-payment/disputes/responding-to-disputes). ## Accept a Dispute on the Dashboard Use the Finix Dashboard to accept a Dispute: click **Disputes** in the left navigation. For more information, see [Manage Disputes on the Dashboard](/guides/after-the-payment/disputes/managing-disputes#manage-disputes-on-the-dashboard). ## Accept a Dispute with the API To accept a Dispute, make a request to the accept endpoint with the Dispute's `id`. Accepted Dispute ```json Accepted Dispute { "id": "DId6CWsFDuwbuH1xtcccJjmM", "created_at": "2026-02-26T18:38:51.10Z", "updated_at": "2026-02-26T20:22:22.62Z", "action": null, "amount": 888888, "application": "APnbAM5AUfqVWogdNAK1uBo", "dispute_details": { "arn": "123" }, "evidence_submitted": "NOT_SUPPORTED", "identity": "ID6FYTFyR4Bvcz8Nf5kxZjDB", "merchant": "MUpKQQ83zyTHrGvrFcM52tWj", "message": null, "occurred_at": "2026-02-26T18:38:50.65Z", "reason": "FRAUD", "respond_by": "2026-03-05T18:38:51.07Z", "response_state": "ACCEPTED", // [!code highlight] "state": "PENDING", // [!code highlight] "tags": { "test": "dispute-simulation-1772131129" }, "transfer": "TRdsziSzzCpmsn4856uyPEAh", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/disputes/DId6CWsFDuwbuH1xtcccJjmM" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APnbAM5AUfqVWogdNAK1uBo" }, "transfer": { "href": "https://finix.sandbox-payments-api.com/transfers/TRdsziSzzCpmsn4856uyPEAh" }, "evidence": { "href": "https://finix.sandbox-payments-api.com/disputes/DId6CWsFDuwbuH1xtcccJjmM/evidence" }, "adjustment_transfers": { "href": "https://finix.sandbox-payments-api.com/disputes/DId6CWsFDuwbuH1xtcccJjmM/adjustment_transfers" } } } ``` ## Next steps Responding to Disputes Upload evidence and submit a response to challenge a Dispute. Dispute states Look up Dispute states, response states, and reason codes. --- # Dispute states Source: https://docs.finix.com/guides/after-the-payment/disputes/dispute-states Look up what each Dispute state, response state, and reason code means so you know what step to take next. Whether you manage Disputes through the Finix Dashboard or the API, the `response_state` and `state` of the Dispute tell you what to do to move the Dispute forward. ## Dispute response states | `response_state` | Description | | --- | --- | | `NEEDS_RESPONSE` | The `Merchant` needs to respond to the `Dispute` by `Dispute#respond_by`. | | `RESPONDED` | The issuing bank has received the evidence and actively reviewing it. No action needed from the `Merchant`. | | `ACCEPTED` | The `Merchant` has accepted the `Dispute`. When a `Dispute` is accepted, you concede that the `Dispute` is not worth challenging or representing. For details on how to accept a `Dispute`, see [Accepting a Dispute](/guides/after-the-payment/disputes/accepting-disputes/). | | `NO_RESPONSE_ALLOWED` | The final `Dispute#response_state` when a `Dispute` is either `WON` or `LOST`. | | `UNKNOWN` | `Dispute` details couldn't be submitted to the processor. Comes up when testing `Disputes` in sandbox or on the `DUMMY_V1` processor. | ## Dispute states | `state` | Description | | --- | --- | | `INQUIRY` | The `Dispute` is being reviewed by the buyer's issuing bank. When `Dispute#state` is `INQUIRY` no changes can be made. | | `PENDING` | This `Dispute#state` change happens at a later time, after the `Dispute` accept request is submitted. When you accept a `Dispute` on a sale, the `Dispute#state` changes to `LOST`. When you accept a `Dispute` on a refund, the `Dispute#state` changes to `WON`. To catch this change, [manage Disputes with the API](/guides/after-the-payment/disputes/managing-disputes#manage-disputes-with-the-api): subscribe to Finix's [webhooks](/additional-resources/developers/webhooks) and listen for the [`Dispute` `updated` event](/additional-resources/developers/webhooks/webhook-events#dispute-updated). | | `LOST` | The `Dispute` is lost and no further changes can be made. | | `WON` | The `Dispute` is won and no further changes can be made. | ## Dispute reasons The `reason` of the `Dispute` provides additional details regarding why the dispute got filed. | `reason` | Description | | --- | --- | | `CLERICAL` | An error occurred while processing the sale, or the cardholder has an issue with the transaction and refuses the goods. | | `FRAUD` | The cardholder claims they didn't approve or authorize the transaction. `FRAUD` is the primary reason Disputes get created. | | `INQUIRY` | The `Merchant` didn't respond by the `respond_by` date, or the transaction got flagged for review due to the network's internal standards. | | `QUALITY` | The cardholder has issues with the quality of the goods or services received. Reasons can include receiving damaged goods or a service that doesn't match what's promised. | | `TECHNICAL` | A technical issue caused the transaction to process funds incorrectly. | A Dispute is created with a `PENDING` `state`. The `Dispute#state` updates with the issuing bank’s decision, but Disputes can be further escalated and the outcome may change. When the `Dispute#state` updates to `INQUIRY` or `PENDING`, the issuing bank is requesting additional information from the seller that shows the transaction was legitimate. For steps on how to upload evidence and respond to the issuing bank, see [Responding to disputes](/guides/after-the-payment/disputes/responding-to-disputes). ## Next steps Responding to Disputes Upload evidence and submit a response to challenge a Dispute. Accepting Disputes Concede a Dispute that is not worth challenging. --- # How disputes work Source: https://docs.finix.com/guides/after-the-payment/disputes/how-disputes-work Understand the dispute process end to end so you know what happens when a cardholder challenges a payment, what it costs, and how it resolves. ## Overview A dispute happens when a cardholder contacts their issuing bank to challenge a payment. The card networks manage the process, and each network follows its own rules. Finix represents each dispute as a Dispute resource and guides you through responding to it. When a card network creates a dispute, Finix: - Records a new Dispute on the Finix Dashboard. - Sends an email or webhook for every new Dispute, if you subscribe to notifications. - Provides the Dispute details, including the reason code, card network, and your opportunity to challenge the Dispute. To monitor and act on Disputes, see [Managing disputes](/guides/after-the-payment/disputes/managing-disputes). ## How the dispute process works A dispute follows the same general process across card networks, though the exact steps and timing vary by network. Flow of a dispute from cardholder protest through the issuing bank's decision This process may differ across card networks for some specific disputes. To receive notifications for disputes, subscribe to Finix's webhooks. ### Protested charges The process starts when a buyer believes they were charged incorrectly and disputes the transaction with their issuing bank. Disputes often happen when buyers see charges on their statements that they don't recognize. The issuing bank reverses the payment and notifies Finix, and Finix debits the disputed amount from the relevant Merchant account. Throughout the process, the issuing bank gives the merchant opportunities to provide evidence that the charge is legitimate. ### Chargebacks and money movement A chargeback is the formal network phase that involves the first movement of money. A dispute may start as a chargeback or escalate to one from an inquiry. When a dispute is a chargeback, Finix pulls funds from you if you are a direct merchant, or from your merchants if you are a platform. Finix creates a `MERCHANT_DEBIT` Transfer, places it into a Settlement, and reduces the amount that would have been paid out to the merchant. The funds are held for the duration of the dispute. The held amount may be the full transaction amount or a different amount, depending on the dispute details. Disputes and split transactions For information on how disputes work for split transactions, see [Split Transactions - Disputes](/guides/online-payments/payment-features/split-transactions#disputes). ### Inquiries Before a chargeback, some card networks add a preliminary stage that Finix refers to as an **Inquiry**. This stage is also known as a retrieval request or a request for information. Only American Express and Discover use inquiries; Visa and Mastercard have discontinued them. Respond to every inquiry to prevent it from escalating into a chargeback. | **Card Network** | **Inquiry Supported** | | --- | --- | | American Express | Yes | | Discover | Yes | | Visa | No | | Mastercard | No | If you don't respond to an American Express or Discover inquiry, it turns into a chargeback that can't be challenged. ## Dispute timing After a chargeback is created, you have a limited time to respond to the card issuer. This ranges from 7 to 21 days, depending on the card network. If you submit evidence, the issuer has a limited time to evaluate it and reach a decision. This ranges from 60 to 75 days, depending on the card network. From start to finish, the dispute process typically spans two to three months. The only way to shorten this timeline is to accept the Dispute through the Dashboard or API. In rare cases, the process may take up to six months. The date by which a dispute must be responded to is subject to change based on updates Finix receives from the card networks. ## Dispute fees Finix charges a fee for the creation of inquiries and chargebacks. Both events create Dispute resources, so a single dispute may incur two fees: one for the initial inquiry and one for the eventual escalation to a chargeback. If you are a platform, Finix generates Costs for these events. You can pass them on to your merchants as Fees using Merchant Fee Profiles. ## Outcomes At the end of the process, the issuing bank rules in favor of either the merchant or the buyer. ### Dispute ruled in favor of the merchant The issuing bank reviews the evidence and rules in favor of the merchant. The issuing bank returns the debited chargeback amount to Finix, and Finix returns the amount to the merchant. ### Dispute ruled in favor of the buyer The issuing bank reviews the evidence and rules in favor of the buyer. No extra money movement occurs when the buyer wins. The networks may signal a provisional credit granted to the merchant. If the dispute is ruled in favor of the buyer, Finix pulls funds again to settle the difference. ## Winning and losing disputes Finix tracks the outcome of a Dispute with a `WON` or `LOST` state. Because disputes are asynchronous, this state may take up to two months to update. These states are not final: the networks or the cardholder may overturn them on further escalation. - A `LOST` Dispute may flip to `WON` on further escalation from the cardholder, acquirer, issuer, or network. The merchant receives their funds back if this happens. - A `WON` Dispute may flip to `LOST` on further escalation from the cardholder, acquirer, issuer, or network. The merchant has funds pulled if this happens. For the full set of Dispute states, response states, and reason codes, see [Dispute states](/guides/after-the-payment/disputes/dispute-states). ## Next steps Managing Disputes Monitor and act on Disputes through the Finix Dashboard or API. Responding to Disputes Upload evidence and submit a response to challenge a Dispute. Preventing disputes Follow best practices to reduce the disputes you receive. --- # Disputes Source: https://docs.finix.com/guides/after-the-payment/disputes Disputes Hero Respond to Disputes on time, submit strong evidence, and reduce the chargebacks that cost you revenue. A dispute (also known as a chargeback) occurs when a cardholder protests a charge on their statement with their issuing bank. When a dispute is filed, Finix notifies you, holds the disputed funds, and gives you a window to respond. These guides explain how disputes work, how to manage and respond to them through the Finix Dashboard or API, and how to prevent them from happening. ## Learn more How disputes work Learn what disputes are, how the dispute process runs, and what fees and outcomes to expect. Managing Disputes Monitor and act on Disputes through the Finix Dashboard or API. Responding to Disputes Upload evidence and submit a response to challenge a Dispute. Dispute states Look up Dispute states, response states, and reason codes. Accepting Disputes Concede a Dispute that is not worth challenging. Preventing disputes Follow best practices to reduce the disputes you receive. --- # Managing Disputes Source: https://docs.finix.com/guides/after-the-payment/disputes/managing-disputes Monitor incoming Disputes and act on them before their deadlines, whether you work in the Finix Dashboard or integrate with the Finix API. ## Overview Finix represents each dispute and its lifecycle as a Dispute resource. You can monitor and act on Disputes through the Finix Dashboard or the Finix API. For every Dispute, you can review its details, upload evidence to challenge it, or accept it. Use the `state` of the Dispute to decide your next step. For more information, see [Dispute states](/guides/after-the-payment/disputes/dispute-states). To understand the dispute process, fees, and outcomes before you act, see [How disputes work](/guides/after-the-payment/disputes/how-disputes-work). Build a process to monitor Disputes daily for updates that require action. Once a buyer disputes a transaction, you can no longer refund it, and a high dispute ratio can lead the card networks to monitor or disable your payment processing. Platforms must notify their sellers when they receive Disputes. You can send this notification through a Dashboard notification, an email, or any method you choose. ### Refunding disputed payments Disputed transactions can't be refunded or reversed. Attempts to refund or reverse a disputed transaction fail with a `409` error. ```json Error message reversing a disputed Transfer { "total": 1, "_embedded": { "errors": [ { "logref": "180636a5364866d0", "message": "Reversals and refunds on transactions with disputes are not allowed.", "code": "CONFLICT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/transfers" } } } ] } } ``` ## Manage Disputes on the Dashboard To manage Disputes on the Finix Dashboard, navigate to the **Disputes** screen. This page lists every reported Dispute so you can track incoming Disputes and their deadlines in one place. From the Disputes list, you can: - Review the details of any Dispute, including its reason code, card network, and respond-by date. - Upload evidence to challenge a Dispute. For the full evidence workflow, see [Responding to disputes](/guides/after-the-payment/disputes/responding-to-disputes). - Accept a Dispute that isn't worth challenging. For more information, see [Accepting disputes](/guides/after-the-payment/disputes/accepting-disputes). To receive a notification whenever a Dispute is created or updated, [subscribe to Finix's webhooks](/additional-resources/developers/webhooks). ## Manage Disputes with the API You can manage Disputes programmatically using webhook events and the Finix API. Managing Disputes with the API starts with receiving the Dispute webhook. ### Receive the Dispute webhook When a Dispute is created, you receive a webhook event with `entity: dispute` and `type: created`. The webhook includes the Dispute resource. ```json Dispute webhook example { "type": "created", "entity": "dispute", "occurred_at": "2022-01-27T07:43:03.48Z", "_embedded": { "disputes": [ { "id": "DIs7yQRkHDdMYhurzYz72SFk", "application": "APgPDQrLD52TYvqazjHJJchM", "tags": { "order_number": "21DFASJSAKAS" }, "amount": 888888, "state": "PENDING", "transfer": "TRoTrJ3kqNTFh1P2FJ7A36Ky", "reason": "FRAUD", "message": null, "action": null, "identity": "IDpYDM7J9n57q849o9E9yNrG", "created_at": "2022-01-27T07:43:03.74Z", "updated_at": "2022-01-27T07:43:03.48Z", "occurred_at": "2022-01-27T07:42:48.56Z", "respond_by": "2022-02-03T07:43:03.73Z", "dispute_details": { "arn": "123" } } ] } } ``` ### Fetch the Dispute Use the returned `id` to [query the Dispute](/api/disputes/getdispute). Dispute ```json Dispute { "id": "DIoGJyoVQ4LBFkfuc8eVkgfL", "created_at": "2026-09-30T23:26:45.07Z", "updated_at": "2026-09-30T23:26:45.07Z", "action": null, "amount": 888888, "application": "AP3Jq9GNcnw1BzxHtbcCgcfL", "dispute_details": { "arn": "123" }, "evidence_submitted": "NOT_SUPPORTED", // [!code highlight] "identity": "IDjM61nerqKFpCH9gz9p2vXS", "merchant": "MU5nUdyGDxrsibubRh3hLyGU", "message": null, "occurred_at": "2026-09-30T23:26:44.73Z", "reason": "FRAUD", "respond_by": "2026-10-07T23:26:45.07Z", // [!code highlight] "response_state": "NEEDS_RESPONSE", // [!code highlight] "state": "PENDING", "tags": {}, "transfer": "TRdCtihoBec3qj6Pi991wACn", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/disputes/DIoGJyoVQ4LBFkfuc8eVkgfL" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/AP3Jq9GNcnw1BzxHtbcCgcfL" }, "transfer": { "href": "https://finix.sandbox-payments-api.com/transfers/TRdCtihoBec3qj6Pi991wACn" }, "evidence": { "href": "https://finix.sandbox-payments-api.com/disputes/DIoGJyoVQ4LBFkfuc8eVkgfL/evidence" }, "adjustment_transfers": { "href": "https://finix.sandbox-payments-api.com/disputes/DIoGJyoVQ4LBFkfuc8eVkgfL/adjustment_transfers" } } } ``` Use the `state` of the Dispute to determine your next step. For more information, see [Dispute states](/guides/after-the-payment/disputes/dispute-states). ## Next steps Responding to Disputes Upload evidence and submit a response to challenge a Dispute. Accepting Disputes Concede a Dispute that is not worth challenging. Dispute states Look up Dispute states, response states, and reason codes. --- # Preventing disputes Source: https://docs.finix.com/guides/after-the-payment/disputes/preventing-disputes Cut the disputes you receive by making charges easy to recognize, policies easy to find, and your business easy to reach. ## Why disputes happen A cardholder may file a dispute for many reasons: - They don't recognize the business name on their statement. - The goods were never received. - They are dissatisfied with the service or goods, or the product wasn't as described. - Friendly fraud, where the cardholder knowingly approved the transaction but reports it as unauthorized. Friendly fraud is often caused by confusion over a statement descriptor. ## Best practices to prevent disputes The following practices reduce the most common causes of disputes. ### Use a clear billing descriptor Use a short, accurate statement descriptor that names the business your cardholders will recognize. For example, if your business is "Bob's Bike Repair LLC", use "Bob's Bike Repair". - Make the descriptor distinct and accurate, such as your website domain name. - Make your Doing Business As (DBA) name as visible as possible on your website, since your legal business name may not be recognizable to cardholders. ### Publish straightforward policies and FAQs Give buyers an easy-to-follow returns policy that includes return-by timeframes, refund guidelines, and return shipping instructions. List this information on your website or a Frequently Asked Questions (FAQ) page. ### Describe products and services clearly Accurately describe your products and services on your website. Descriptions can include product details, specifications, photos, and, where available, customer reviews. ### Keep contact information up to date An easy-to-find contact page is a first-line defense against an incoming dispute. Cardholders want to reach you with questions about your products or services. Publish your business hours and phone support availability, such as Monday to Friday, 6 AM to 6 PM PT. ### Communicate well with buyers Many disputes can be resolved before they become chargebacks. If a buyer contacts your business, resolving the disagreement directly can prevent a formal chargeback. For example, a buyer who receives a damaged product might open a dispute. Giving them the chance to explain the situation may let you replace the item instead. Be available: if a buyer emails you, send an auto-reply that confirms you received their message, and offer live chat or a customer service number. Responding quickly minimizes the miscommunication that leads to disputes. ### Keep detailed transaction records Retain purchase information so you can respond to a possible dispute. Documentation requirements vary by card issuer and by transaction type, such as card-present or card-not-present. For online transactions, keep order confirmations, shipping details, and delivery confirmations. For card-present transactions, keep written return guidelines, shipping policies, and transaction receipts showing the cardholder's signature. For card-present transactions, submitting more evidence than necessary can help. ### Send order confirmations and follow-ups Send an automated order confirmation when a buyer places an order. Once the order ships, send the shipping information or confirmation of digital delivery. If there is a delay, keep the buyer informed. For example, if a product is out of stock, tell the buyer right away and offer options, such as shipping when it is back in stock or providing a refund. ## Next steps How disputes work Learn what disputes are, how the dispute process runs, and what fees and outcomes to expect. Responding to Disputes Upload evidence and submit a response to challenge a Dispute. --- # Responding to Disputes Source: https://docs.finix.com/guides/after-the-payment/disputes/responding-to-disputes Challenge a Dispute by uploading evidence and submitting your response before the respond-by deadline. You can respond through the Finix Dashboard or the Finix API. When a Dispute is created, respond as quickly as possible. ## View Disputes you can respond to By default, the Finix Dashboard shows all Disputes that need a response. This view shows how much time you have left to respond to each Dispute. List of Disputes with the time remaining to respond to each ## Respond on the Dashboard When you click into a Dispute, you can respond to the full amount or a partial amount of the Dispute. Dispute detail page with the respond-by date and amount options After you upload your evidence, you can add any additional information you want to provide to the issuing bank. Challenge Dispute form with the additional information field When all your evidence files are uploaded and your **Additional Information** is filled out, click **Submit Response**. Finix submits the information to the cardholder's bank for review. A final response may take two to three months. Submit Response confirmation for a Dispute After the evidence is submitted, you cannot submit additional evidence unless there is further escalation of the Dispute. ## Dispute evidence To challenge a Dispute, upload compelling evidence that shows the transaction was legitimate and that the goods or services were delivered. This evidence can include order receipts, shipping information, tracking numbers, communication records, or any other information that establishes the validity of the transaction. - Shipping details, tracking numbers, or delivery confirmation demonstrate that the product or service was delivered as agreed. - Communication records, such as emails or chat transcripts, provide valuable context. Clear, organized evidence that directly addresses the Dispute gives you the best chance of winning. Combining evidence files Evidence files aren't guaranteed to be read or presented in the order they're uploaded. If you upload multiple evidence files and order matters, combine them into a single PDF before uploading to Finix. Other examples of evidence you can upload include: - An email thread of conversations with the cardholder. - Screenshots of conversations with the cardholder. - Proof of consistent use of a service or software over a period of time. - Product photos. - E-signature contracts. - Your returns or refund policy. - Proof of shipping. You're responsible for making sure any documents you upload are accurate and complete. Finix converts files to meet card network format requirements, but Finix can't guarantee the conversion is perfect or that your original documents meet all requirements. That remains your responsibility. If you don't have enough evidence, or you believe the Dispute isn't worth fighting, you can accept liability and concede the Dispute. For more information, see [Accepting disputes](/guides/after-the-payment/disputes/accepting-disputes). ## Respond with the API ### When you can respond to a Dispute If a `Dispute#response_state` is `NEEDS_RESPONSE`, you can upload additional evidence to challenge the Dispute or chargeback. When a Dispute is filed, `Dispute#response_state` shows what actions are available to the seller. For more information, see [Dispute states](/guides/after-the-payment/disputes/dispute-states). To challenge a `NEEDS_RESPONSE` Dispute, upload evidence and submit it to the issuing bank. ### Step 1: Upload evidence [Create Dispute evidence to upload your defense material](/api/disputes/createdisputeevidence). Use the `id` of the Dispute to create the evidence. - The total size of the uploaded files combined can't exceed 10 MB. - Combined length of all Mastercard evidence files cannot exceed 17 pages. - Allowed file formats are JPG, PDF, and PNG. - Individual files can't exceed 1 MB. - Finix automatically converts PNG files and returns them as JPEG files. A successful upload returns a response with `PENDING` saved for `state`. If you run into any issues or get a different response, try uploading the file again or in another format. Dispute Evidence ```json Dispute Evidence { "id": "DFvJbk7HS3p1LEoQpViJJSCB", "created_at": "2024-12-17T07:35:17.32Z", "updated_at": "2024-12-17T07:35:17.32Z", "application": "APgPDQrLD52TYvqazjHJJchM", "dispute": "DIkigGVrJPjDyAXejvvKXv9e", "identity": "ID4sanuCPqjmkmP4Q3Shkvww", "merchant": "MUcvYR7tboSRejbVzHJSjXct", "state": "PENDING", // [!code highlight] "failure_code": null, "failure_message": null, "content_type": "image/jpeg", "extension": "jpg", "file_name": "evidence.jpg", "tags": { "file-extension": ".jpg", "content-type": "image/jpeg", "file-name": "evidence.jpg" }, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/disputes/DIkigGVrJPjDyAXejvvKXv9e/evidence/DFvJbk7HS3p1LEoQpViJJSCB" } } } ``` The `evidence#state` field has four values that describe the status of the evidence upload: - `PENDING` - The evidence file hasn't yet been submitted to the processor. No further action is required. - `SUCCEEDED` - The evidence file was successfully sent to the processor. No further action is required. - `CANCELED` - The uploader canceled the evidence file upload. - `FAILED` - An issue occurred. Any of the following could have happened: - There was a system error. Try uploading the evidence again. - There is an issue with the file. Retry with a different file. - There is another issue. Contact Finix Support. ### Step 2: Submit evidence To move quickly to a decision, submit your evidence to the issuing bank by making a `POST` request to the `/disputes/DISPUTE_ID/submit` endpoint. This tells the issuing bank you've finished submitting evidence and are ready to move the Dispute forward. After you submit: - Finix forwards the uploaded evidence to the issuing bank. - The issuing bank reviews the files and either requests more information or moves the Dispute forward and makes a decision. Once submitted, you can't upload additional evidence to the Dispute. Dispute ```json Dispute { "id": "DI36zCEULZSRobTdkVsddn9i", "created_at": "2024-10-30T22:39:24.75Z", "updated_at": "2025-09-03T22:28:29.97Z", "action": null, "amount": 2599, "application": "APjzRSvNgT6HYpp3frqnEZFX", "dispute_details": { "case_id": "qwerty321", "reason_code": "10.1" }, "evidence_submitted": "INQUIRY", // [!code highlight] "identity": "ID3kLJLRUWmpUUt3Hy1xGi2z", "merchant": "MUqTsyQpykNNiwPG36mUJKWz", "message": "The cardholder has a chip card, but the transaction either did not take place at a chip terminal, was not chip read, the chip information sent was incomplete or the transaction was completed with a counterfeit card in a card-present environment.", "occurred_at": "2024-10-30T22:38:33.28Z", "reason": "FRAUD", "respond_by": "2024-11-06T08:00:00.00Z", "response_state": "RESPONDED", // [!code highlight] "state": "INQUIRY", // [!code highlight] "tags": {}, "transfer": "TRnWtcA4qYWqZ14hkd6G1gst", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/disputes/DI36zCEULZSRobTdkVsddn9i" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APjzRSvNgT6HYpp3frqnEZFX" }, "transfer": { "href": "https://finix.sandbox-payments-api.com/transfers/TRnWtcA4qYWqZ14hkd6G1gst" }, "evidence": { "href": "https://finix.sandbox-payments-api.com/disputes/DI36zCEULZSRobTdkVsddn9i/evidence" }, "adjustment_transfers": { "href": "https://finix.sandbox-payments-api.com/disputes/DI36zCEULZSRobTdkVsddn9i/adjustment_transfers" } } } ``` When the Dispute moves forward, `Dispute#evidence_submitted` updates to: - `INQUIRY` if `Dispute#state` is `INQUIRY`. - `CHARGEBACK` if `Dispute#state` is `PENDING`. When the issuing bank makes a decision, Finix notifies you with a webhook and updates the `Dispute#state` with the decision. ## Next steps Dispute states Look up Dispute states, response states, and reason codes. Accepting Disputes Concede a Dispute that is not worth challenging. --- # Creating and Delivering Receipts Source: https://docs.finix.com/guides/after-the-payment/receipts/how-receipts-work Receipts provide merchants with documentation for bookkeeping, inventory tracking, and tax compliance. They serve as proof of transaction details. They can be especially useful in responding to disputes and customer questions. ## Supported flows Finix supports creating receipts on the following flows: - Payments - Authorizations - Refunds ## Creating a receipt on the Dashboard ### Using a Dashboard detail page When you click into one of the supported flows, you will see an option to create a Receipt. Click on the three-dot icon on the top right corner and select Create Receipt. Payment Detail - Create Receipt When creating a receipt, you can include an Amount Breakdown, which allows you to specify subtotals, discount amounts, shipping fees, taxes, tips, and any buyer fees that were applied. You can also choose to itemize the receipt by adding product names and descriptions for each item. You can also include details from tags of the transactions by adding labels and descriptions. Once all details are added, you can either automatically send the receipt upon creation or choose to send it in the following step. Receipt Details After a receipt is created, you can view it on the detail page of the resource. This page displays the receipt ID, a history of when the receipt was sent and to whom, and provides an option to send the receipt to additional recipients. All of this information is available in the Receipt History section. Receipt History ## Creating a receipt via API You can create and send receipts for online payments through the API. - Include the `entity_id`, which must correspond to an ID from one of the supported payment flows. - Set `send_receipt_to_buyer` to true to automatically send the receipt to the receiver. - Specify one or more delivery methods in the `requested_delivery_methods` object. The example below demonstrates how to create and send a receipt. Visit our [API Reference](/api/receipts/) to learn how to include additional details in your receipts. ```shell Create a Receipt curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/receipts \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "entity_id": "TRraKDGt53y1XeTbeCkXYMkn", "send_receipt_to_buyer": true, "requested_delivery_methods": [ { "type": "EMAIL", "destinations": [ "johndoe@gmail.com" ] }, { "type": "SMS", "destinations": [ "3346497818" ] }, { "type": "PRINT", "destinations": [ "DV12343234" ] } ] }' ``` ```shell Response { "id": "receipt_cdGdu7mHL2DaEHHYf8PPg", "created_at": "2024-07-30T00:26:55.87Z", "updated_at": "2024-07-30T00:26:55.87Z", "amount": 22300, "currency": "USD", "amount_breakdown": null, "send_receipt_to_buyer": true, "device_id": null, "entity_details": { "id": "TRraKDGt53y1XeTbeCkXYMkn", "created_at": "2024-07-30T00:22:25.28Z", "type": "TRANSFER" }, "type": "BUYER", "items": [], "merchant_details": { "id": "MUeDVrf2ahuKc9Eg5TeZugvs", "business_name": "Dunder Mifflin", "doing_business_as": "Dunder Mifflin", "business_address": { … } }, "payment_instrument_details": { "id": "PIe2YvpcjvoVJ6PzoRPBK137", "type": "PAYMENT_CARD", "billing_address": { … }, "bin": "489514", "brand": "VISA", "card_type": "UNKNOWN", "last_four": "0006", "name": "Amy White" }, "network_details": null, "requested_delivery_methods": [ { … }, { … }, { … } ], "receipt_url": "https://receipt.sandbox-payments-checkout.com/TYPQp7", "_links": { "self": { … } } } ``` ## Receipts for low-code / no-code products On Payment Links, Subscriptions, Subscription Links, and Virtual Terminal, you'll see options to create receipts. This saves you an extra step of having to go to the resource later to manually create a receipt. ## Sandbox testing In Sandbox, receipts can only be sent to email addresses. Attempts to send a receipt to a phone number will be ignored, and no text message will be delivered. We also have rate limiting in our sandbox to only 10 receipt delivery per day per Application. --- # Receipts Source: https://docs.finix.com/guides/after-the-payment/receipts Receipts Hero You can create Receipts using the Finix Dashboard or the API. Receipts serve as formal records of payment activities including transfers, authorizations, and refunds that have been successfully processed. Receipts contain the essential metadata for buyers to keep record of. These include transaction IDs, amount, timestamps and more. ## Learn more Creating and Delivering Receipts Learn how to create receipts for payments, refunds, and authorizations. Receipt API Reference Review the API reference for creating and managing receipts programmatically. --- # Refunding with the API Source: https://docs.finix.com/guides/after-the-payment/refunds/api You can refund transactions processed with Finix programmatically using the Finix API instead of a user interface. The API supports refunds for both online and in-person payments. ## Refunding online Payments To refund a `Transfer` via API, [create a reversal Transfer](/api/transfers/createtransferreversal). Pass the `id` query parameter set to the original `Transfer` you want to refund. Include an `amount` equal to or less than the payment to refund. Enter a value less than the payment amount for a partial refund. Example API Definition A successful request returns a `201 Created` status code, with the response body containing: - `parent_transfer` representing the `Transfer` that was reversed. - `state` - Initially set to `PENDING` to indicate that the refund is still processing. - Changes to `SUCCEEDED` when the refund is processed. - `type` set to `REVERSAL`. Example Transfer - Reversal ```json Transfer - Reversal { "id": "TRhop5SzZD5AbRGz6HC6qB5w", "created_at": "2026-09-25T20:36:25.76Z", "updated_at": "2026-09-25T20:36:25.79Z", "3d_secure_session": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 1000, "amount_requested": 1000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "USD", "destination": "PI6iQcTtJNCS8GZAVKYi5Ueb", "expires_at": "2026-11-09T20:36:25.76Z", // [!code highlight] "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj", "idempotency_id": null, "ip_address_details": null, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "messages": [], "network_details": null, "operation_key": "CARD_NOT_PRESENT_REFUND", "parent_transfer": "TRqvNLUdn3aPmdwLMSKs3Gxz", // [!code highlight] "parent_transfer_trace_id": null, "processed_at": null, "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": null, "split_transfers": [], "state": "PENDING", // [!code highlight] "statement_descriptor": "FLX*FINIX FLOWERS", "subtype": "API", "supplemental_fee": null, "tags": {}, "third_party_details": null, "tip_amount": null, "trace_id": "9fc0c015-0d97-49f1-93a6-b845d4e50c01", "type": "REVERSAL", // [!code highlight] "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhop5SzZD5AbRGz6HC6qB5w" }, "parent": { "href": "https://finix.sandbox-payments-api.com/transfers/TRqvNLUdn3aPmdwLMSKs3Gxz" }, "destination": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6iQcTtJNCS8GZAVKYi5Ueb" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhop5SzZD5AbRGz6HC6qB5w/payment_instruments" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj" } } } ``` API Definition The `state` will be `SUCCEEDED` when the refund finishes processing. Buyers will see the refund credited within 5-10 business days, depending on their bank. Refunds can't be canceled once processed. Held Refunds When refund holds are enabled, refunds stay in `state: PENDING` until the merchant's settlement balance covers them, and the response includes an `expires_at` date. A refund that cannot be covered in time fails with `failure_code: REFUND_EXPIRED`. For more information, see [Pending refunds](/guides/after-the-payment/refunds/pending-refunds). ## Refunding Card-Present Payments Which refund method to use for card-present payments depends on how much time has passed since the original transaction. For debit transactions, the determining factor is whether the batch is still open; for credit transactions, whether it's within 45 days. - [Referenced Refunds](#referenced-refunds) — Reverse the original `Transfer` directly using its ID. No card swipe required in most cases. - [Unreferenced Refunds](#unreferenced-refunds) — Create a new `Transfer` unlinked from the original. The cardholder must swipe their card to authorize the refund. Only available for physically swiped transactions. ### Referenced Refunds Use a referenced refund when: - The payment type was `credit` and the transaction is within 45 days (regardless of batch status). - The payment type was `debit` and the transaction is in the current open batch. To perform the refund, [reverse the original Transfer](/api/transfers/createtransferreversal): Example API Definition A successful request returns a `201 Created` status code, with the response body containing: - `state` - Initially set to `PENDING` to indicate that the refund is still processing. - Changes to `SUCCEEDED` when the refund is processed. - `type` is set to `REVERSAL`. - Under `_links.parent`, you can find the original `Transfer` that was reversed. Example Reversed Card-Present Transfer Referencing Parent ```json Reversed Card-Present Transfer Referencing Parent { "id": "TR7PYuTpCU3AtLSgvSobjmGg", "created_at": "2026-09-28T20:31:08.64Z", "updated_at": "2026-09-28T20:31:08.69Z", "3d_secure_session": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 150, "amount_requested": 150, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "USD", "destination": "PI2zjrcxkiPYEokwQPq2G58z", "device": "DVhCtTEMVHnDPFMh2KQLrFSi", "expires_at": "2026-11-12T20:31:08.64Z", "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPmtT4MYmiAs1qjLjneQmk4d", "idempotency_id": null, "ip_address_details": null, "merchant": "MUmFY9PWbqJPGtQEN7RXdFAb", "merchant_identity": "IDvEVPqD9rnfLCAGnLJphyGT", "messages": [], "network_details": null, "operation_key": "CARD_PRESENT_REFUND", "parent_transfer": "TRhBbRpGifWm9U8fCaKVVAZo", "parent_transfer_trace_id": null, "processed_at": null, "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": null, "split_transfers": [], "state": "PENDING", // [!code highlight] "statement_descriptor": "FLX*FINIX FLOWERS", "subtype": "API", "supplemental_fee": null, "tags": {}, "third_party_details": null, "tip_amount": null, "trace_id": "253a57c6-a449-427c-9732-33655040b819", "type": "REVERSAL", // [!code highlight] "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TR7PYuTpCU3AtLSgvSobjmGg" }, "parent": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhBbRpGifWm9U8fCaKVVAZo" }, "destination": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI2zjrcxkiPYEokwQPq2G58z" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDvEVPqD9rnfLCAGnLJphyGT" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TR7PYuTpCU3AtLSgvSobjmGg/payment_instruments" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d" } } } ``` API Definition ### Unreferenced Refunds Use an unreferenced refund when: - The payment type is `debit` and the transaction is no longer in the batch. - The payment type is `credit` and the transaction is no longer in the batch and older than 45 days. To perform the unreferenced refund, [create a Transfer](/api/transfers/createtransfer) with `operation_key: CARD_PRESENT_UNREFERENCED_REFUND`. The cardholder must swipe their card to authorize the refund. Card-not-present transactions (e.g., eCommerce) do not support unreferenced refunds. Example API Definition A successful request returns a `201 Created` status code, with the response body containing: - `operation_key` is set to `CARD_PRESENT_UNREFERENCED_REFUND`. - `state` - Initially set to `PENDING` to indicate that the refund is still processing. - Changes to `SUCCEEDED` when the refund is processed. - `type` is set to `CREDIT` or `DEBIT` based on the original transfer type, rather than `REVERSAL`. Unlike referenced refunds, there is no `_links.parent` property — a new `Transfer` was created instead of reversing an existing one. Example Card Present Transfer without Parent Reference ```json Card Present Transfer without Parent Reference { "id": "TRo5JpCqMY26ufvRdTJ8715j", "created_at": "2025-11-19T20:31:16.48Z", "updated_at": "2025-11-19T20:31:16.48Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 150, "amount_requested": 150, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "card_present_details": { "emv_data": { "application_identifier": "A0000000041010", "application_label": "Mastercard Debit", "application_preferred_name": null, "application_transaction_counter": "01D2", "cryptogram": "ARQC 579B6893AADF6245", "issuer_code_table_index": null, "network_emv_response": null, "pin_verified": false, "tags": null }, "masked_account_number": "523499******4130", "name": null, "brand": "UNKNOWN", "entry_mode": "CONTACTLESS", "payment_type": "CREDIT", "approval_code": "674313", "digital_signature_file_id": null }, "currency": "USD", "destination": "PInqirmUHFh1FmPNa8reirAb", "device": "DVoDo7F6yYCnX2d6Fj9hvsd", "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPmtT4MYmiAs1qjLjneQmk4d", "idempotency_id": null, "ip_address_details": null, "merchant": "MUsMvN47nRtdgUkE23SRHDC6", "merchant_identity": "IDgu8uaRpVnfSEcRcZFXqpjK", "messages": [], "network_details": null, "operation_key": "CARD_PRESENT_UNREFERENCED_REFUND", // [!code highlight] "parent_transfer": null, "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": "2025-11-20T20:32:38.76Z", "receipt_last_printed_at": null, "security_code_verification": null, "source": null, "split_transfers": [], "state": "SUCCEEDED", // [!code highlight] "statement_descriptor": "FLX*FINIX FLOWERS", "subtype": "API", "supplemental_fee": null, "tags": {}, "third_party_details": null, "tip_amount": null, "trace_id": "23f1fdf9-2783-4bbe-8de2-afd7a7502aad", "type": "CREDIT", // [!code highlight] "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRo5JpCqMY26ufvRdTJ8715j" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDgu8uaRpVnfSEcRcZFXqpjK" }, "device": { "href": "https://finix.sandbox-payments-api.com/devices/DVoDo7F6yYCnX2d6Fj9hvsd" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRo5JpCqMY26ufvRdTJ8715j/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRo5JpCqMY26ufvRdTJ8715j/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRo5JpCqMY26ufvRdTJ8715j" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRo5JpCqMY26ufvRdTJ8715j/disputes" }, "destination": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PInqirmUHFh1FmPNa8reirAb" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d" } } } ``` API Definition --- # Refunding with the D135 Checkout App Source: https://docs.finix.com/guides/after-the-payment/refunds/d135-checkout-app If you want to refund transactions processed with the D135 Finix Checkout App, you can do so directly from your iOS device without using the Finix Dashboard or API. To refund a payment using the D135 Finix Checkout App: 1. From the navigation bar at the bottom of the screen, tap **Transactions**. 2. Tap on the payment you wish to refund. D135 Checkout App - Transactions List 1. From the payment details page, tap **Refund**. D135 Checkout App - Payment Details Page - Refund 1. Enter an amount equal to or less than the payment to refund. Enter a value less than the payment amount for a partial refund. 2. Tap **Create Refund**. D135 Checkout App - Create Refund 1. On the payment details page, the refund status first shows "Pending" then changes to "Succeeded". D135 Checkout App - Transaction Details - Refund Pending 1. You can view refunds from the **Transactions** page > **Refunds** tab. D135 Checkout App - Transaction List - Refund Tab --- # Refunding with the Dashboard Source: https://docs.finix.com/guides/after-the-payment/refunds/dashboard You can refund transactions in Finix conveniently using the Finix Dashboard rather than the Finix API. The Finix Dashboard supports refunds for both online and in-person payments. To refund a payment using the Finix Dashboard: 1. In the Dashboard, expand **Transactions** in the left navigation. 2. Click **Payments**. 3. Click the payment in the list or search by payment ID. Payments list page - A payment summary drawer opens on the right side. 1. Click **View All Details**. Payments list page - payment summary drawer 1. On the payment details page, scroll down to the **Refunds** section. 2. Click **Issue Refund**. Payments details page - issue refund button 1. On the **Issue Refund** screen, you can keep the default amount, which is the same as the payment amount, or enter a refund amount less than the payment amount for a partial refund. 2. Click **Refund**. 3. Confirm the total refund amount. Issue refund screen - If successful, a "Refund has been successfully created" message briefly appears. - On the payment details page, "Refund Pending" is initially displayed, then it changes to "Refund Succeeded". - You can optionally view the refund from the **Transaction Activity** → **Refunds** page. --- # Refunds Source: https://docs.finix.com/guides/after-the-payment/refunds Use Finix to return funds to a customer after a payment has been processed. Refunds can be issued in full or in part, and can be initiated through the Finix Dashboard, the API, or directly on a payment terminal. - **Full refunds** return the entire transaction amount to the customer. - **Partial refunds** return a portion of the amount; you can issue multiple partial refunds against a single `Transfer` as long as the total doesn't exceed the original transaction amount. - Once a refund is initiated, it **cannot be canceled**. Refund processing depends on the merchant's `pending_refunds_strategy`. When refund holds are enabled, refunds follow a `PENDING` workflow to verify there are sufficient funds to cover the refund. For more information, see [Pending refunds](/guides/after-the-payment/refunds/pending-refunds). ## Fees When a payment is refunded, the original processing and platform fees are not returned. Depending on your Fee Profile, a fixed fee applies to each refund attempt, successful or failed. For more information, see [Available Fees](/guides/platform-payments/monetizing-payments/available-fees#transaction-attempt-fees). ## Timing Customers typically see refunds credited to their account within 5-10 business days, depending on their bank. When a refund is issued shortly after the original charge, it may appear as a reversal instead. A reversal removes the original charge from the statement rather than adding a separate credit. ## Settlements Refunds appear as debits in Settlements (see [Payouts](/guides/after-the-payment/payouts)), similar to `Transfers` and capture requests. If the merchant's settlement balance cannot cover a refund, Finix holds the refund in `state: PENDING` until the balance, or a debit on the merchant's bank account, covers it. For more information, see [Pending refunds](/guides/after-the-payment/refunds/pending-refunds). Refunds in Auth and Capture Flows If you are performing [separate Authorizations and captures](/guides/online-payments/payment-features/auth-and-captures), you'll need to refund the `Transfer` that was created as part of capturing the `Authorization`. If you haven't captured it yet, [void the Authorization](/guides/online-payments/payment-features/auth-and-captures#void-an-authorization) instead. ## Learn more Refunding with the Dashboard Refund payments using the Finix Dashboard. Refunding with the API Refund online and card-present payments programmatically using the Finix API. Refunding with a Standalone Terminal Refund in-person payments using a Standalone Terminal (e.g., Pax A800 or Pax A920Pro). Refunding with the D135 Checkout App Refund in-person payments using the D135 Finix Checkout App. Pending refunds Learn how Finix holds refunds when a merchant's settlement balance is insufficient, how pending refunds are funded, and what happens when a refund expires. --- # Pending refunds Source: https://docs.finix.com/guides/after-the-payment/refunds/pending-refunds By default, refunds are submitted immediately when created. A merchant may also be configured to have refunds withheld until the merchant's settlement balance can cover them. This guide explains the pending refund lifecycle, how Finix funds pending refunds, and what happens if a refund cannot be covered before it expires. ## Merchant pending refund strategies On the Merchant resource, the `pending_refunds_strategy` field controls how refunds are held. When a merchant's `pending_refunds_strategy` is set to `SEVEN_DAY_DELAYED_ADJUSTMENT` or `SAME_DAY_ADJUSTMENT`, refunds enter a `PENDING` state while Finix verifies that there are sufficient funds in the merchant's settlement to cover them. - `SEVEN_DAY_DELAYED_ADJUSTMENT`: Refunds are held in `state: PENDING` for up to 7 days to be covered by settlement funds. After 7 days, Finix debits the merchant's bank account to cover the refund. - `SAME_DAY_ADJUSTMENT`: Finix issues a debit adjustment near settlement close if the settlement can't cover the refund. Only users with `ROLE_PARTNER` credentials can set `pending_refunds_strategy`. ## Pending refund lifecycle ### 1. Refund created If a Merchant has a `pending_refunds_strategy` configured, refunds are not processed immediately. In the response, the Transfer reversal (i.e., refund) contains `state: PENDING` and an `expires_at` datetime 45 days after creation. Finix sets and enforces this expiration window. Refund - held ```json Refund - held { "id": "TRhop5SzZD5AbRGz6HC6qB5w", "created_at": "2026-09-25T20:36:25.76Z", "updated_at": "2026-09-25T20:36:25.79Z", "3d_secure_session": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 1000, "amount_requested": 1000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "USD", "destination": "PI6iQcTtJNCS8GZAVKYi5Ueb", "expires_at": "2026-11-09T20:36:25.76Z", // [!code highlight] "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj", "idempotency_id": null, "ip_address_details": null, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "messages": [], "network_details": null, "operation_key": "CARD_NOT_PRESENT_REFUND", "parent_transfer": "TRqvNLUdn3aPmdwLMSKs3Gxz", // [!code highlight] "parent_transfer_trace_id": null, "processed_at": null, "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": null, "split_transfers": [], "state": "PENDING", // [!code highlight] "statement_descriptor": "FLX*FINIX FLOWERS", "subtype": "API", "supplemental_fee": null, "tags": {}, "third_party_details": null, "tip_amount": null, "trace_id": "9fc0c015-0d97-49f1-93a6-b845d4e50c01", "type": "REVERSAL", // [!code highlight] "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhop5SzZD5AbRGz6HC6qB5w" }, "parent": { "href": "https://finix.sandbox-payments-api.com/transfers/TRqvNLUdn3aPmdwLMSKs3Gxz" }, "destination": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6iQcTtJNCS8GZAVKYi5Ueb" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhop5SzZD5AbRGz6HC6qB5w/payment_instruments" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj" } } } ``` If the refund is not funded by the expiration, it expires. ### 2. Daily funding check Before a Settlement belonging to a Merchant moves to `status: AWAITING_APPROVAL`: 1. Finix checks whether the Settlement balance covers each pending refund, starting with the oldest pending refund. 2. If it does, Finix submits the refund, moves the refund `state` to `SUCCEEDED`, and deducts it from the Settlement. 3. If the balance cannot cover a refund, the refund `state` stays `PENDING`. How long Finix waits before collecting via bank account debit depends on the merchant's [pending_refunds_strategy](#merchant-pending-refund-strategies). Pending refunds are processed in the order they were created. If the oldest pending refund cannot be covered, the refunds behind it wait, even if they are smaller. ### 3. Finix collects the refund If incoming sales cannot cover the refund and it reaches the maximum days allowed in `state: PENDING`, as set by the [pending_refunds_strategy](#merchant-pending-refund-strategies), Finix debits the Merchant's bank account for the refund amount. To collect the refund, Finix: 1. Creates a debit adjustment Transfer for the amount of the refund which will be deducted from the next Settlement. 2. Submits the refund 3 business days after the debit clears and creates an offsetting credit adjustment Transfer so the two adjustments net to zero for the Merchant. For more information, see [Refund Adjustments](#refund-adjustments). End customers do not need to take action The pending refund process is between Finix and the merchant. The refund is submitted to the cardholder's or bank account holder's financial institution only after it is funded; if funding is not secured by `expires_at`, the refund fails. ### 4. Refund expiration If the bank account debit fails and the refund still cannot be covered by the `expires_at` datetime, the refund's `state` is set to `FAILED` with a `failure_code` of `REFUND_EXPIRED`. ```json Refund - Expired { "id": "TR8fezr4xCMFJvH5rzCqrUkF", "created_at": "2026-10-24T17:38:19.09Z", "updated_at": "2026-12-08T17:38:19.09Z", ... "expires_at": "2026-12-08T17:38:19.09Z", "failure_code": "REFUND_EXPIRED", "failure_message": "The refund has expired.", "state": "FAILED", "type": "REVERSAL" } ``` ## Refund adjustments If necessary to collect funds, Finix may create adjustment Transfers with two possible `operation_key` values. These adjustments are system-generated and are always in `state: SUCCEEDED`. | Subtype | Type | Description | | --- | --- | --- | | `REFUND_MERCHANT_DEBIT_ADJUSTMENT` | `DEBIT` | Deducts the refund amount from the Merchant's Settlement. | | `REFUND_MERCHANT_CREDIT_ADJUSTMENT` | `CREDIT` | Offsets the refund amount when the refund is submitted, or returns pending funds if the refund expires. | ```json Refund adjustment { "id": "TRaB91xboyy8mfFxZNFWf1F", ... "parent_transfer": "TR8fezr4xCMFJvH5rzCqrUkF", "state": "SUCCEEDED", "operation_key": "REFUND_MERCHANT_DEBIT_ADJUSTMENT", "type": "DEBIT" } ``` Both adjustments reference the pending refund in the `parent_transfer` field. ```json Debit adjustment { "id": "TRaB91xboyy8mfFxZNFWf1F", ... "parent_transfer": "TR8fezr4xCMFJvH5rzCqrUkF", "state": "SUCCEEDED", "operation_key": "REFUND_MERCHANT_DEBIT_ADJUSTMENT", "type": "DEBIT" } ``` ```json Credit adjustment { "id": "TR4Lxcmkn1py9him81swz4FD", ... "parent_transfer": "TR8fezr4xCMFJvH5rzCqrUkF", "state": "SUCCEEDED", "operation_key": "REFUND_MERCHANT_CREDIT_ADJUSTMENT", "type": "CREDIT" } ``` On the Settlement Entry: - `subtype` matches the adjustment `operation_key`. - The `parent_entity_id` field matches the adjustment `parent_transfer`. ## Webhooks You may subscribe to [Transfer webhooks](/additional-resources/developers/webhooks/webhook-events#refund-debit) to receive a notification each time a pending refund changes state: - `PENDING` to `SUCCEEDED`: The refund was submitted. - `PENDING` to `FAILED`: The refund could not be funded. The webhook payload includes `failure_code: REFUND_EXPIRED` and the `expires_at` timestamp when this is due to expiration. --- # Refunding with a Standalone Terminal Source: https://docs.finix.com/guides/after-the-payment/refunds/standalone-terminal If you want to refund transactions processed on standalone terminals like the A800 or Pax A920Pro, you can do so directly from those terminals without using the Finix Dashboard or API. To refund a payment with a Standalone Terminal: 1. Open the Payment App. 2. From the navigation bar at the bottom of the screen, tap **Transactions**. 3. Tap on the payment you wish to refund. Standalone Terminal - Transactions List 1. From the payment details page, tap **Create Refund**. Standalone Terminal - Payment Details Page - Create Refund 1. Enter an amount equal to or less than the payment to refund. Enter a value less than the payment amount for a partial refund. 2. Tap **Create Refund**. Standalone Terminal - Refund Payment - Enter Amount 1. Go back to the **Transactions** page, then tap the same payment to refresh the payment details. - If the refund was successful, the status appears as "Succeeded" in the **Refunds** section. Standalone Terminal - Payment Details - Refund Succeeded 1. Tap the refund to view details including the refund state, the settlement it was placed into, the buyer, and the payment instrument. Standalone Terminal - Payment Details - Refund Details 1. To view all issued refunds, return to the **Transactions** screen and tap the **Refunds** tab. Standalone Terminal - Transactions List - Refund tab --- # Managing Your Payments with Finix Source: https://docs.finix.com/guides/managing-operations Learn about managing payments using Finix's products and services. Online Payments Hero Finix offers several tools and solutions to help you manage the operations part of processing payments and complying with regulations. Finix Dashboard Learn about the Finix Dashboard. ## Learn more Reports Learn about the reports that regularly get generated on the dashboard. Security and Compliance Learn how Finix handles your security and compliance obligations. Managing Team Members Learn how to add Team Members. --- # Managing Your Payments with Finix Source: https://docs.finix.com/guides/managing-operations/finix-dashboard Learn about managing payments using Finix's products and services. Online Payments Hero The Finix Dashboard is a powerful tool that helps you keep track of your payment processing activity, view graphical representations of payment trends, and perform any of the actions available through our API. Add your team to the Finix Dashboard to help your business get started managing payments through Finix. The Finix Dashboard supports Safari, Mozilla Firefox, Brave, and Edge. Customize Finix Dashboard Customize the look of the dashboard Manage Your Team Members Add the rest of your team to the Finix Dashboard --- # White-Labeling The Finix Dashboard Source: https://docs.finix.com/guides/managing-operations/finix-dashboard/white-labeling-finix-dashboard White Labeling the Finix Dashboard provides your sellers a branded experience that includes your colors, logos, and a subdomain of your choice. Behind the scenes, Finix continues powering the dashboard allowing your sellers to see their payment information. This guide shows you how to customize the Finix Dashboard with your logo, colors, subdomain, and emails. Finix Custom Dashboard ## Enabling custom Finix Dashboards To enable customization for your Finix Dashboard, reach out to your Finix point of contact or email [Finix Support](/guides/getting-started/support-at-finix/) with your request. Once enabled, you can change the different assets of your Finix Dashboard from the **Company** tab. Attributes of the Finix Dashboard you can change include: - [White-Labeling The Finix Dashboard](#white-labeling-the-finix-dashboard) - [Enabling Custom Finix Dashboards](#enabling-custom-finix-dashboards) - [Adding a Logo](#adding-a-logo) - [Dashboard Colors](#dashboard-colors) - [Onboarding Forms](#onboarding-forms) - [Email Invites](#email-invites) - [Branded Subdomain](#branded-subdomain) ### Adding a logo You can customize the Finix Dashboard, so a logo other than the Finix logo appears in the top left of the Finix Dashboard. - Allowed formats: JPEG, JPG, or PNG - Max file size: 2 MB ### Dashboard colors You can change the colors of the Finix Dashboard sidebar so it matches your brand and customer experience. You can also include the hex values of the colors you'd like to use and where in the Finix Dashboard you want them applied. Finix Sidebar Background Color The colors or the Finix Dashboard that can get changed include: - **Sidebar Background Color:** Customize the background color of the navigation menu. - **Sidebar Text Color:** Customize the color of the text in the navigation menu. - **Sidebar Text Highlight:** Customize the color of the highlight that gets used to mark the active tab in the navigation menu. ### Onboarding Forms You can customize the form sellers fill out to get onboarded and process payments. Parts of the form you can change include: - **Display Name:** The name of your business and who is onboarding the seller. - **Upload Logo:** The logo that appears in the onboarding form. - **Primary Color:** The main color of the form's design. ### Email invites You can brand the emails sent to your sellers when they get granted access to the Finix Dashboard. Attributes you can change include: - **Display Name:** The name of your business and who is inviting the user. - **Upload Logo:** The logo that appears in the invite email. ### Branded subdomain You can customize the URL of your Finix Dashboard so sellers login to a dashboard with a custom domain. For example, instead of `finix.payments-dashboard.com`, you can set the subdomain of your Finix Dashboard to be `yourcompany.payments-dashboard.com`. Other examples include: - `daphnescorner.payments-dashboard.com` - `customerfirstcommerce.payments-dashboard.com` - `finixflowers.payments-dashboard.com` To set up a custom subdomain, email [Finix Support](/guides/getting-started/support-at-finix/) with your request and the subdomain you'd like your Finix Dashboard to have. Currently, subdomains can only be configured for live environments. --- # Insights and Reports Source: https://docs.finix.com/guides/managing-operations/insights-reports In this guide, you can learn about the different reports and analytics that are available in the Finix Dashboard. Online Payments Hero It's important to understand the performance and profitability of your business and how you're processing payments. To help you gain valuable insights, Finix provides a range of downloadable CSV reports and analytic charts available within the Finix Dashboard. ## Exports In addition to the charts and pre-generated reports, several pages on the Finix Dashboard can also be filtered and exported as a CSV. Exports Click the **Export All** button in the top right to create a new export. Pages in the Finix Dashboard that can be filtered and exported includes: - Payments - Authorizations - Refunds - Payment Instruments - Settlements - Merchant Deposits - Disputes - ACH Returns - Identities - Merchant Accounts - Compliance - Onboarding Forms - Buyers Any exports created will be available to download as a CSV from the **Exports** page. ## Learn more Insights Learn about Insights and the different visual analytic tools available in the Finix Dashboard. Reports Learn about the different CSV reports available to download in the Finix Dashboard. --- # Insights Source: https://docs.finix.com/guides/managing-operations/insights-reports/insights Learn about Insights and the different visual and analytic tools available in the Finix Dashboard. The Finix Dashboard has several charts and visual tools available to help provide an at-a-glance overview of key performance metrics for platforms and sellers. - Use the date and column filters to breakdown your payment data. - The data visualized updates as you change the filtered dates and columns. ## Home The **Home** page is the first page you see when you [log in to the Finix Dashboard](https://finix.payments-dashboard.com/Login) and open your sandbox. Home Analytics available on the **Home** page includes the following: ### Summary A snapshot of the payments processed. | Analytic | Description | | --- | --- | | Total Transaction Volume | The total aggregate of all transactions, both `Transfers` and `Authorizations`. | | Authorization Rate | Percentage of `Transfers` and `Authorizations` attempted that were *successfully* processed (doesn't include refunds). | | Merchant Fees Collected | The total aggregate of all processing fees. | | Avg. Transaction Amount | The average amount of transactions (both `Transfers` and `Authorizations`) processed across all `Merchants`. | ### Transaction trends Detailed breakdown of the data provided in the Summary by Day, Month, or Year. | Analytic | Description | | --- | --- | | Total Transaction Volume and Count | The total aggregate and count of all transactions, both `Transfers` and `Authorizations`. | | Authorization Rate | Percentage of `Transfers` and `Authorizations` attempted that were *successfully* processed compared to the number attempted (doesn't include refunds). | | Merchant Fees Collected | The total aggregate of all processing fees. | | Average Transaction Amount | The average amount of transactions (both `Transfers` and `Authorizations`) processed across all `Merchants`. | ### Last month's Insights A breakdown of the payment data processed from the prior calendar month. | Analytic | Description | | --- | --- | | Total Residual Amount | Total returned to the platform. | | Avg. Interchange % | Average interchange charged per transaction. | | Avg. Dues and Assessments % | Average amount of transactions that get paid as fees. | | Card Payments | Total count of card payments processed. | ### Year-to-Date Insights Payment data for the current calendar year. | Analytic | Description | | --- | --- | | Active Merchants | Number of unique `Merchants` that are actively processing transactions. | | Disputes | Number of `Disputes` filed by buyers against `Merchants`. | | ACH Returns | Number of ACH transactions returned due to processing issues. | | Chargeback Rate | Total percentage of `Disputes` submitted compared to the number transactions processed. | ## Transactions The **Transactions Insights** page is available to help you dig deeper into the metrics of how your business processes payments. To open the Transactions Insights page, click **Insights** → **Transaction Insights**. Transaction Insights Analytics available on the **Transaction Insights** page includes the following: ### Payments A breakdown of the payments and transactions processed (both `Transfers` and `Authorizations`). #### Summary A snapshot of the payments processed. | Analytic | Description | | --- | --- | | Total Transaction Vol. | The total aggregate of all transactions, both `Transfers` and `Authorizations`, for all of your `Merchants`. | | Successful Sales | The total aggregate of all `Transfers` for all of your `Merchants`. | | Failed Sales | The total aggregate of failed `Transfers` for all of your `Merchants`. | | Avg. Transaction Amount | The average amount of transactions (both `Transfers` and `Authorizations`) processed across all `Merchants`. | #### Payment trends Break down payment method and card brand data by Day, Month, or Year. | Analytic | Description | | --- | --- | | Payment Volume by Payment Method | Break down transaction volume by the different payment methods used by buyers. | | Payment Count by Payment Method | Break down the number of transactions processed by the different payment methods used by buyers. | | Payment Volume by Card Brand | Filter transaction volume by the different card brands used by buyers. | | Payment Count by Card Brand | Filter the number of transactions processed by the different card brands used by buyers. | #### Payments per Merchant Transaction data broken down across all `Merchants`. Available for platforms only, for more details, see [Platform Payments.](/guides/platform-payments) #### Card payment data Filter the payment data you've processed by: - Card Brand - Card Type - Card Issuer Country - Payment Channel #### Failed transactions by failure code A detailed breakdown of failed transactions by the failure code that was returned. ### Authorizations A breakdown of the `Authorizations` processed. #### Summary A snapshot of the `Authorizations` processed. | Analytic | Description | | --- | --- | | Requests Received | The total aggregate of all transactions, both `Transfers` and `Authorizations`. | | Authorization Rate | Total percentage of successful `Authorizations` compared to the number attempted (doesn't include refunds). | | Voided Authorizations | The total aggregate of voided `Authorizations`. | | Captured Authorizations | The total aggregate of successfully captured `Authorizations`. | #### Authorization trends Break down approved `Authorizations` and card brand data by Day, Month, or Year. | Analytic | Description | | --- | --- | | Authorization Rate by Card Brand | Total percentage of successful `Authorizations` broken down by the card brand used by buyers. | | Authorization Count by Card Brand | Total count of successful `Authorizations` broken down by the card brand used by buyers. | #### Authorizations per Merchant `Authorization` data broken down across all `Merchants`. Available for platforms only, for more details, see [Platform Payments.](/guides/platform-payments) #### Card Authorization data `Authorization` data broken down across all `Merchants`. Available for platforms only, for more details, see [Platform Payments.](/guides/platform-payments) #### Failed Authorizations by failure code A detailed breakdown of failed `Authorizations` by the failure code that was returned. ### Refunds A breakdown of the refunds processed. #### Summary A snapshot of the refunds processed. | Analytic | Description | | --- | --- | | Gross Processing Vol. | The total aggregate of all transactions, both `Transfers` and `Authorizations` minus the total aggregate of refunds processed. | | Successful Refunds | The total aggregate of successfully processed refunds. | | Failed Refunds | The total aggregate of failed refunds. | | Total Transaction Vol. | The total aggregate of all transaction volume. | #### Refund trends Break down refund, payment method, and card brand data by Day, Month, or Year. | Analytic | Description | | --- | --- | | Refund Volume by Payment Method | Total aggregate of successful refunds broken down by the payment method used by buyers. | | Refund Count by Payment Method | Total count of refunds broken down by the payment method used by buyers. | | Refund Volume by Card Brand | Total aggregate of successful refunds broken down by the card brand used by buyers. | | Refund Count by Card Brand | Total count of refunds broken down by the card brand used by buyers. | #### Refunds per Merchant Data surrounding the refunds processed broken down across all `Merchants`. Available for platforms only, for more details, see [Platform Payments.](/guides/platform-payments) #### Card Refund data Data surrounding refunded card transactions broken down by the card brands used by buyers. ## Merchants The **Merchant Insights** page provides an overview of merchant onboarding activity, transaction performance, and geographic distribution. To open the Merchant Insights page, click **Insights** → **Merchant Insights**. Merchant Insights Analytics available on the **Merchant Insights** page includes the following: ### Summary A snapshot of merchant activity compared to the previous period. | Analytic | Description | | --- | --- | | Onboarded Merchants | The total number of new `Merchants` onboarded during the selected period. | | Rejected Merchants | The total number of `Merchants` rejected during the selected period. | | Active Merchants | The total number of `Merchants` actively processing transactions. | | Profitable Merchants | The total number of `Merchants` that were profitable during the selected period. | ### Merchant trends Break down merchant onboarding and activity data by Week. | Analytic | Description | | --- | --- | | Onboarding State | A breakdown of `Merchants` by their current onboarding state over the selected period. | | Active Merchants | The number of `Merchants` actively processing transactions over the selected period. | ### Total transaction volume by Merchant A detailed breakdown of transaction volume across all `Merchants`. | Column | Description | | --- | --- | | Merchant Name | The name of the `Merchant`. | | Transaction Volume | The total aggregate of all transactions processed by the `Merchant`. | | Card Transaction Volume | The total aggregate of card transactions processed by the `Merchant`. | | Card Transaction Count | The total number of card transactions processed by the `Merchant`. | | ACH Transaction Volume | The total aggregate of ACH transactions processed by the `Merchant`. | | ACH Transaction Count | The total number of ACH transactions processed by the `Merchant`. | ### Total transaction volume by MCC A breakdown of transaction volume grouped by Merchant Category Code (MCC). | Column | Description | | --- | --- | | MCC | The four-digit Merchant Category Code assigned to the `Merchant`. | | MCC Description | The category of goods or services associated with the MCC. | | Total Transaction Volume | The total aggregate of all transactions for `Merchants` under the MCC. | | Card Transaction Volume | The total aggregate of card transactions for `Merchants` under the MCC. | | Card Transaction Count | The total number of card transactions for `Merchants` under the MCC. | | ACH Transaction Volume | The total aggregate of ACH transactions for `Merchants` under the MCC. | | ACH Transaction Count | The total number of ACH transactions for `Merchants` under the MCC. | ### Merchants by location A breakdown of merchant activity and transaction volume by state or province. | Column | Description | | --- | --- | | State | The state or province where the `Merchant` is located. | | Active Merchants | The number of `Merchants` actively processing transactions in that location. | | Transaction Volume | The total aggregate of all transactions for `Merchants` in that location. | | Card Transaction Volume | The total aggregate of card transactions for `Merchants` in that location. | | Card Transaction Count | The total number of card transactions for `Merchants` in that location. | | ACH Transaction Volume | The total aggregate of ACH transactions for `Merchants` in that location. | | ACH Transaction Count | The total number of ACH transactions for `Merchants` in that location. | ## Insights availability At this time, Insights is available for: - Finix Flex customers - Customers using `FINIX_V1` as a processor If you have any questions about availability or using Insights, please reach out to the [Finix Support Team.](mailto:support@finix.com) --- # Reports Source: https://docs.finix.com/guides/managing-operations/insights-reports/reports Finix offers several pre-defined reports that detail the activity on your account. These reports get generated regularly and are available for review in the Finix Dashboard. To view these reports: 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login). 2. Click **Reports** on the left. The following reports are available on the Finix Dashboard: | Report Name | Description | | --- | --- | | [Net Profit Report](#net-profit-report) | Per-merchant margin and profitability including fee revenue collected, network and Finix costs, and revenue share. | | [Consolidated Fees Reports](#consolidated-fees-reports) | All fees collected, network fees passed through, and program fees charged. Used to audit revenue and cost details by merchant and by transaction, and to perform revenue and cost analysis, and business optimization. | | [Transaction Reports](#transaction-reports) | Transactions including gateway and payout status. Used for operations, customer service, reconciliation, and exceptions management. Includes interchange report by transaction. | | [Authorization Reports](#authorization-reports) | Authorizations including capture status and expiration. Used for operations, reconciliation, and exceptions management. | | [Transactions Settled](#transactions-settled) | All transactions that settled the previous day. Used for operations, customer service, reconciliation, and exceptions management. | | [Fee Profile - Merchant](#fee-profile---merchant) | Active fee profiles for all onboarded`merchants`. Used for operations and finance. | | [Settlement Merchant](#settlement-merchant) | All settlements generated the previous day, aggregated by the`Identity` of the `Merchant` . Used for daily reconciliation. | | [Settlement Application](#settlement-application) | All settlements generated the previous day, aggregated by`Application`. Used for daily reconciliation. | | [Settlement Processor](#settlement-processor) | All settlements generated the previous day, aggregated by`Application` and processor. Used for daily reconciliation. | | [Chargeback Merchant (Daily)](#disputes-daily-and-monthly) | All new chargebacks and any chargebacks with updates from the previous day. The report is blank if there's no new chargeback activity. Used for exceptions management and risk management. | | [Chargeback Merchant (Historical)](#disputes-historical) | Details all chargeback-related metrics for`merchants`. `Merchants` with higher disputes in the last 30 days get sorted to the top of the report. Used for exceptions management and risk management. | | [Failed Funding Instructions](#failed-funding-instructions) | Details all the Funding Transfers that got returned. For more information about Funding Transfers, see [Payouts](/guides/platform-payments/seller-payouts). | ## Net profit Report Net Profit Report deprecated on June 1st, 2025 As of June 1st, Finix is deprecating the Net Profit Report. Please reference [Platform Residuals](/guides/platform-payments/monetizing-payments/platform-residuals) to understand how residuals are calculated and paid out. Reach out to Finix Point of Contact if you have any questions. The **Net Profit** report provides an end-to-end view of all the fees you've collected. This report also breaks down how the collected fees get used for interchange & assessments, program fees, and revenue share. - All currencies are in the local currency (USD). - All timestamps are in UTC. - The report is generated monthly on the 10th day of the following month, unless that day falls on a weekend, bank holiday, or a Monday, in which case the report can be generated as late as the 15th of the month. - The report is only available for Flex customers. The different Net Profit reports that are available include: | File Name | Description | | --- | --- | | `net_profit_merchant` | Details the profit waterfall per `Merchant` . | | `net_profit_application` | Details the profit waterfall per `Application`. | | **Field** | **Description** | | --- | --- | | `merchant_id` | ID of the `Merchant` associated with the transaction.The unique `merchant_id` begins with **MU.** | | `merchant_name` | The legal name saved in the `Merchant` resource. | | `merchant_doing_business_as` | The "doing business as" name saved in the `Merchant` resource. | | `mid` | MID of the `Merchant`. | | `mcc` | The Merchant Category Code ([MCC](http://www.dm.usda.gov/procurement/card/card_x/mcc.pdf)) the `Merchant` is classified under. | | `card_sale_count` | Total count of card sales and capture transactions. | | `card_sale_amount` | Total amount of card sales and capture transactions. | | `echeck_sale_count` | Total count of eCheck (also called ACH payments) sale transactions. | | `echeck_sale_amount` | Total amount of eCheck sale transactions. | | `total_sale_count` | The total sum of`card_sale_count` and `echeck_sale_count` (in dollars, e.g. 1102 = $11.02). | | `total_sale_amount` | The total sum of`card_sale_amount` and `echeck_sale_amount`. | | `card_refund_count` | The number of card refunds performed (in dollars). | | `card_refund_amount` | The total sum of all card refunds (in dollars). | | `echeck_refund_count` | The number of eCheck refunds performed. | | `echeck_refund_amount` | The total sum of all eCheck refunds (in dollars). | | `echeck_return_count` | The number of returned eChecks. Returned eChecks are eCheck transactions that returned as unpaid. | | `echeck_return_amount` | The total sum of all returned eChecks. Returned eChecks are eCheck transactions that returned as unpaid. | | `dispute_count` | The number of card disputes such as chargebacks. Follow-up dispute activity such as re-presentment is not included here. | | `dispute_amount` | The total sum of all of card disputes such as chargebacks (in dollars). If a dispute has multiple movements of money such as if a merchant wins the dispute, those additional money movements don't get included. | | `card_bps_rate` | Card transactions only. The base variable fee that was applied to card transactions. This column might not reflect any older rates that applied to this `Merchant` or for specific transactions. | | `card_per_item_rate` | Card transactions only. The base per-item fee that was applied to card transactions. This column might not reflect any older rates that applied to this `Merchant` or for specific transactions. | | `card_fees_amount` | Total sum of card fees collected from the merchant. | | `echeck_bps_rate` | eCheck transactions only. The base variable fee that was applied to eCheck transactions. This column might not reflect any older rates that applied to this `Merchant` or for specific transactions. | | `echeck_per_item_rate` | eCheck transactions only. The base per-item fee that was applied to eCheck transactions. This column might not reflect any older rates that applied to this `Merchant` or for specific transactions. | | `echeck_fees_amount` | Total sum of eCheck fees collected from the `Merchant`. | | `subscription_fees_amount` | Total sum of subscription billing fees collected from the `Merchant`. | | `other_fees_amount` | Total sum of any additional fees collected from the `Merchant`, not in the other three categories of fees. | | `total_fees_amount` | Sum of `card_fees_amount`, `echeck_fees_amount`, `subscription_fees_amount`, and `other_fees_amount` | | `interchange_fees_amount` | All card interchange fees assessed. Note: This includes eCheck processing fees. | | `dues_and_assessments_fees_amount` | All dues and assessments fees assessed. Note: Due to the time it takes for our processor to deliver data, this column can be incomplete or blank until Finix receives and processes all data up to the 15th day of the following month. | | `total_network_fees_amount` | Sum of`interchange_fees_amount` and `dues_and_assessments_fees_amount`. | | `total_program_fees_amount` | All Finix per-transaction and additional fees assessed. | | `residual_amount` | Total amount of residual revenue. Represents`total_fees_amount` minus `total_network_fees_amount` and `total_program_fees_amount`. | | `application_id` | ID of the`Application` associated with the transaction. | | `application_business_name` | The registered name saved in the`Application` resource. | | `application_doing_business_as` | The "doing business as" name saved in the`Application` resource. | | `platform_id` | The ID of the`Platform`. | | `platform_name` | The name saved in the`Platform` resource. | | `report_created_at` | A timestamp of when the report was created (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `report_range_start` | A timestamp that details the beginning of the range covered by this report (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `report_range_end` | A timestamp that details the end of the range covered by this report (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | ## Consolidated fees Reports The Consolidated Fees reports provide detailed fee revenue, network cost, and program fee cost line items on a per-merchant, per-cost-occurrence with additional levels of aggregation. You can use these reports to examine specific details of any type of revenue or cost to audit what is happening and also to optimize your business at a merchant level. - All currencies are in the local currency (USD). - All timestamps are in UTC. - The report is generated monthly on the 10th day of the following month, unless that day falls on a weekend, bank holiday, or a Monday, in which case the report can be generated as late as the 15th of the month. - The report is only available for Flex customers. Fees that are detailed include: - Total fees revenue collected from merchants, on transactions or otherwise. This includes subscription fee revenue and custom fees. - Interchange rates and fees. - Dues and assessments from processors and card brands, and other passthrough fees. - Payment facilitator program fees charged by Finix. There are 3 aggregations of this report: - `consolidated_fees_by_occurrence` - Details each fee each time it occurs. In some cases, we report passthrough network assessments fees already aggregated per-merchant as they can not be further broken down per occurrence. - `consolidated_fees_by_description` - This aggregates the by-occurrence report by the fee description, per merchant, so you can examine each fee you're collecting or being charged by merchant, how often, and how much it affects your business economics. - `consolidated_fees_summary` - This is per-merchant, by fee category, so you can see the individual components of profitability. Categories are listed below. | Field | **Description** | | --- | --- | | `merchant_id` | ID of the `Merchant` associated with the transaction.The unique `merchant_id` begins with **MU.** | | `merchant_identity_id` | ID of the merchant's `Identity` associated with the transaction.The unique `merchant_identity_id` begins with **ID.** | | `merchant_name` | The legal name saved in the `Merchant` resource. | | `merchant_doing_business_as` | The "doing business as" name saved in the `Merchant` resource. | | `mid` | MID of the `Merchant`. | | `mcc` | The Merchant Category Code ([MCC](http://www.dm.usda.gov/procurement/card/card_x/mcc.pdf)) the `Merchant` is classified under. | | `transaction_id` | Finix's ID for the `Transfer` resource.The unique `transaction_id` begins with **TR** | | `transaction_state` | The status of the transaction. `SUCCEEDED`, `FAILED`, or `CANCELED`. | | `created_at` | Timestamp of when the transaction was received by the processor (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `item_type` | The type of the transaction. [See here for more information.](/guides/managing-operations/insights-reports/reports#transaction-types-for-reporting) | | `item_subtype` | The subtype of the transaction. Provides additional details for `item_type`. [See here for more information.](/guides/managing-operations/insights-reports/reports#transaction-types-for-reporting) | | `payment_type` | The type of payment method used for the transaction. [See here for more information.](/guides/managing-operations/insights-reports/reports#transaction-types-for-reporting) | | `payment_subtype` | If available, the subtype of the payment method used for the transaction. [See here for more information.](/guides/managing-operations/insights-reports/reports#transaction-types-for-reporting) | | `payment_channel` | For card transactions only. Details if a card was present for the transaction. Available values include:**CARD_PRESENT****CARD_NOT_PRESENT** [See here for more information.](/guides/managing-operations/insights-reports/reports#transaction-types-for-reporting) | | `card_brand` | Card transactions only. The brand of the card used. | | `last_4` | Last 4 digits of the payment card or bank account used in the transactions. | | `statement_descriptor` | The description of the transaction that appears on the buyer's bank or card statement. | | `fee_category` | The primary category of the fee. Choices are: `PLATFORM_FEE`: Revenue you collect.`PASSTHROUGH_FEE`: Interchange, assessments, and other fees from processors and card brands.`PROGRAM_FEE`: Fees collected by Finix. | | `fee_type` | Additional details on the fee, such as if it's a transaction fee (collected by you or billed to you), interchange, dues and assessments, and/or additional fees outlined on your Finix MSA. | | `fee_description` | A description of the specific revenue collected or fee assessed. Can include detail such as the specific interchange rate. | | `accrual_level` | How the fee is collected or assessed. Choices are: `PER_TRANSACTION`: Collected on each transaction.`PER_OCCURRENCE`: Collected each time the described event occurs. | | `fee_id` | If available, an industry-standard numerical identifier for interchange. | | `fee_transaction_id` | If available, the Finix identifier for the fee component of the transaction. | | `fixed_fee_rate` | If available, the per-item rate charged for this fee. | | `variable_fee_rate` | If available, the variable percentage rate charged for this fee. | | `fee_count` | The count of the number of occurrences of this fee. | | `fee_amount` | Total fee amount for this line item. | | `transaction_count` | If applicable, the count of transactions that this line item is related to. | | `transaction_amount` | If applicable, the total amount of transactions that this line item is related to. | | `application_id` | ID of the`Application` associated with the transaction. | | `application_business_name` | The registered name saved in the`Application` resource. | | `application_doing_business_as` | The "doing business as" name saved in the`Application` resource. | | `platform_id` | The ID of the`platform` that processed the transaction. | | `platform_name` | The name saved in the`platform` resource. | | `report_created_at` | A timestamp of when the report was created (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `report_range_start` | A timestamp that details the beginning of the range covered by this report (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `report_range_end` | A timestamp that details the end of the range covered by this report (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | ## Transaction Reports The **Transaction** reports detail all sales, captures, refunds, and reversals, along with fees and cost information, plus payout details. There are 7 variations of these reports: - `transactions` - this report shows you all transactions that succeeded since the previous business day, from midnight-to-midnight US Eastern time zone. This report is delivered to you early morning. - `transactions_failed` - this reports shows you all transactions that did not succeed since the previous business day, from midnight-to-midnight US Eastern time zone. This report is delivered to you early morning. - `transactions_settled_v3` - this report shows you which transactions since the previous business day were marked as eligible to be paid. This report is only available to Core Platform customers. - `transactions_unsettled` - this report shows you which transactions since the previous business day were not marked as eligible to be paid. Transactions in this report are repeated daily until they are eligible to be paid, usually the next business day. This report is only available to Core Platform customers. - `transactions_paid` - this report shows you all transactions that were paid out to the merchant since the previous business day. - `transactions_unpaid` - this report shows you all transactions that are still awaiting review and pay out. Transactions in this report are repeated daily until they are paid to the merchant, refunded back to the buyer, or otherwise canceled. - `transaction_interchange` - this report shows transactions for which Finix has full cost data including interchange amounts and rates. Note: some transactions do not have interchange cost data either because there was no interchange charged or refunded, or due to reporting limitations from third parties. Additional: - All timestamps are in UTC. - All currencies are in the local currency (USD). - The report is generated on bank workdays. | Field | **Description** | | --- | --- | | `merchant_id` | ID of the `Merchant` associated with the transaction.The unique `merchant_id` begins with **MU.** | | `merchant_identity_id` | ID of the merchant's `Identity` associated with the transaction.The unique `merchant_identity_id` begins with **ID.** | | `merchant_name` | The legal name saved in the `Merchant` resource. | | `merchant_doing_business_as` | The "doing business as" name saved in the `Merchant` resource. | | `mid` | MID of the `Merchant`. | | `mcc` | The Merchant Category Code ([MCC](http://www.dm.usda.gov/procurement/card/card_x/mcc.pdf)) the `Merchant` is classified under. | | `trace_id` | Trace ID of the `Transfer`. The processor sends back the `trace_id` so you can track the transaction end-to-end.The unique `trace_id` begins with **FNX**, but can change depending on the processor of the transaction. | | `transaction_id` | Finix's ID for the `Transfer` resource.The unique `transaction_id` begins with **TR** | | `transaction_state` | The status of the transaction. `SUCCEEDED`, `FAILED`, or `CANCELED`. | | `created_at` | Timestamp of when the transaction was received by the processor (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `updated_at` | Timestamp of when the transaction was last updated (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `instrument_id` | ID of the `Payment Instrument` associated with the transaction.The unique `instrument_id` begins with **PI.** | | `buyer_name` | Full name of the buyer associated with the transaction. | | `buyer_email` | E-mail of the buyer associated with the transaction. | | `buyer_zip` | Postal code of the buyer associated with the transaction. | | `bin` | BIN associated with the payment card used in the transaction. | | `last_4` | Last 4 digits of the payment card or bank account used in the transactions. | | `security_code_verification` | Security code verification status of payment card used in the transaction. [See here for more information.](https://finix.com/docs/guides/payments/risk/card-verification-checks/#card-verification-checks) | | `address_verification` | Address verification status of payment card used in the transaction. [See here for more information.](https://finix.com/docs/guides/payments/risk/card-verification-checks/#card-verification-checks) | | `bank_account_validation_check` | Bank account validation status of bank account used in the transaction. [See here for more information.](/api/payment-instruments/createpaymentinstrument) | | `statement_descriptor` | The description of the transaction that appears on the buyer's bank or card statement. | | `item_type` | The type of the transaction. [See here for more information.](/guides/managing-operations/insights-reports/reports#transaction-types-for-reporting) | | `item_subtype` | The subtype of the transaction. Provides additional details for`item_type`. [See here for more information.](/guides/managing-operations/insights-reports/reports#transaction-types-for-reporting) | | `payment_type` | The type of payment method used for the transaction. [See here for more information.](/guides/managing-operations/insights-reports/reports#transaction-types-for-reporting) | | `payment_subtype` | If available, the subtype of the payment method used for the transaction. [See here for more information.](/guides/managing-operations/insights-reports/reports#transaction-types-for-reporting) | | `payment_channel` | For card transactions only. Details if a card was present for the transaction. Available values include:**CARD_PRESENT****CARD_NOT_PRESENT** [See here for more information.](/guides/managing-operations/insights-reports/reports#transaction-types-for-reporting) | | `transaction_currency` | [3-letter ISO code](https://en.wikipedia.org/wiki/ISO_4217) designating the currency of the transaction. (e.g. USD) | | `transaction_amount` | The amount processed by the transaction (in dollars). | | `rent_surcharge_amount` | Amount of `transaction_amount` that is a rent surcharge amount. [See here for more information.](https://finix.com/docs/guides/payments/making-a-payment/buyer-charges/#overview) | | `convenience_amount` | Amount of `transaction_amount` that is a convenience amount. [See here for more information.](https://finix.com/docs/guides/payments/making-a-payment/buyer-charges/#overview) | | `fee_profile_id` | The ID of the `Fee Profile` associated with the transaction.The unique `fee_profile_id` begins with **FP.** | | `card_bps_rate` | Card transactions only. The base variable fee that was applied. Note: The `Fee Profile` can contain additional details or overrides that apply to this transaction. Use the linked `fee_profile_id` to find the details in the `fee_profile_merchant` report. | | `card_per_item_rate` | Card transactions only. The base per-item fee that was applied. Note: The `Fee Profile` can contain additional details or overrides that apply to this transaction. Use the linked `fee_profile_id` to find the details in the `fee_profile_merchant` report. | | `echeck_bps_rate` | eCheck transactions only. The base variable fee that was applied. Note: The `Fee Profile` can contain additional details or overrides that apply to this transaction. Use the linked `fee_profile_id` to find the details in the `fee_profile_merchant` report. | | `echeck_per_item_rate` | eCheck transactions only. The base per-item fee that was applied. Note: Th e`Fee Profile` can contain additional details or overrides that apply to this transaction. Use the linked `fee_profile_id` to find the details in the `fee_profile_merchant` report. | | `fee_amount` | The total amount of fee collected for this transaction. | | `program_fee_amount` | The per-transaction fee collected by Finix for this transaction. (Finix Flex only)This doesn't include any additional fees not directly tied to this transaction.This field is left blank for Finix Core customers. | | `card_type` | Card transactions only. The type of the card used. [See here for more information.](/api/payment-instruments/createpaymentinstrument) | | `card_brand` | Card capture/sale transactions only. Echecks and refunds do not show this information. The brand of the card used. | | `interchange_category` | A description of the interchange rates applied to this transaction. | | `interchange_category_id` | The category ID of the interchange rate for this transaction. | | `interchange_bps_rate` | In basis points, the interchange variable rate charged for this transaction. | | `interchange_per_item` | The interchange per-item rate charged for this transaction. | | `interchange_amount` | The total interchange amount charged for this transaction. | | `merchant_settled_amount` | The total amount of the transaction that's settled to the merchant. | | `additional_settled_amount` | The total amount of the transaction that's settled to split recipients. | | `original_trace_id` | Refunds and reversals only. The `trace_id` from the original transaction. | | `original_transaction_id` | Refunds and reversals only. The `transaction_id` from the original transaction. | | `original_transaction_method` | Refund and reversals only. Details the method used to process the original transaction. | | `original_transaction_currency` | Refunds and reversals only. The currency of the original transaction. | | `original_transaction_amount` | Refunds and reversals only. The amount, in dollars, processed in the original transaction. | | `authorization_id` | Captures only. The ID of the related`authorization`. | | `authorization_currency` | Captures only. The currency of the related`authorization`. | | `authorization_amount` | Captures only. The amount, in dollars, of the related`authorization`. | | `failure_code` | Code associated with a failed transaction. Only for transactions_failed report. [See here for more information.](https://finix.com/docs/guides/developers/errors/#failure-codes) | | `failure_message` | Message associated with a failed transaction. Only for transactions_failed report. [See here for more information.](https://finix.com/docs/guides/developers/errors/#failure-codes) | | `echeck_return_code` | Code associated with a returned echeck. | | `echeck_return_description` | Message associated with a returned echeck. | | `gateway` | Name of the gateway that processed this transaction. | | `processor` | Name of acquiring processor that settled the transaction. | | `settlement_id` | ID of the`Settlement`. | | `settlement_created_at` | A timestamp of when the merchant`Settlement` was created (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `settlement_updated_at` | A timestamp of when the`Settlement` was last updated (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `settlement_status` | The status of the`Settlement`. Available values include:**PENDING****STAGED****AWAITING_APPROVAL****APPROVED.** Merchants only receive payouts when `Settlements` are **APPROVED.** For more information, see [Payouts](/guides/payouts). | | `settlement_total_amount` | Total (gross) amount of the`Settlement`. | | `settlement_total_fees` | Total fee amount of the`Settlement`. | | `settlement_net_amount` | Amount of `Settlement` remitted to merchant. | | `settlement_additional_amount` | Amount of `Settlement` remitted to additional split recipients. | | `should_fund` | Indicates if this transaction was funded directly or via direct settlement from a card brand. Example: American Express Conveyed transactions. | | `latest_funding_transfer_id` | ID of the funding instruction sent to merchant. | | `latest_funding_transfer_trace_id` | Trace ID of the funding instruction. | | `funding_transfer_state` | Status of the funding instruction. | | `funding_transfer_created_at` | When the funding instruction was created. | | `application_id` | ID of the`Application` associated with the transaction. | | `application_business_name` | The registered name saved in the`Application` resource. | | `application_doing_business_as` | The "doing business as" name saved in the`Application` resource. | | `platform_id` | The ID of the`platform` that processed the transaction. | | `platform_name` | The name saved in the`platform` resource. | | `report_created_at` | A timestamp of when the report was created (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `report_range_start` | A timestamp that details the beginning of the range covered by this report (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `report_range_end` | A timestamp that details the end of the range covered by this report (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | ## Authorization Reports The **Authorization** report details authorizations, including success/failure, expiration, and capture. - All timestamps are in UTC. - All currencies are in the local currency (USD). - The report is generated on bank workdays. | Field | **Description** | | --- | --- | | `merchant_identity_id` | ID of the merchant's `Identity` associated with the transaction.The unique `merchant_identity_id` begins with **ID.** | | `merchant_name` | The legal name saved in the `Merchant` resource. | | `merchant_doing_business_as` | The "doing business as" name saved in the `Merchant` resource. | | `mid` | MID of the `Merchant`. | | `mcc` | The Merchant Category Code ([MCC](http://www.dm.usda.gov/procurement/card/card_x/mcc.pdf)) the `Merchant` is classified under. | | `authorization_id` | Finix's ID for the `Authorization` resource.The unique `authorization_id` begins with **AU** | | `authorization_state` | The status of the authorization. `SUCCEEDED`, `FAILED`, or `CANCELED`. | | `is_void` | If the authorization is now void. | | `created_at` | Timestamp of when the authorization was received by the processor (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `updated_at` | Timestamp of when the authorization was last updated (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `expires_at` | Timestamp of when the authorization expires. Can be a time in the past or the future. (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `instrument_id` | ID of the `Payment Instrument` associated with the authorization.The unique `instrument_id` begins with **PI.** | | `buyer_name` | Full name of the buyer associated with the authorization. | | `buyer_email` | E-mail of the buyer associated with the authorization. | | `buyer_zip` | Postal code of the buyer associated with the authorization. | | `bin` | BIN associated with the payment card used in the authorization. | | `last_4` | Last 4 digits of the payment card or bank account used in the authorization. | | `card_type` | Card transactions only. The type of the card used. [See here for more information.](/api/payment-instruments/createpaymentinstrument) | | `card_brand` | Card transactions only. The brand of the card used. | | `security_code_verification` | Security code verification status of payment card used in the authorization. [See here for more information.](https://finix.com/docs/guides/payments/risk/card-verification-checks/#card-verification-checks) | | `address_verification` | Address verification status of payment card used in the authorization. [See here for more information.](https://finix.com/docs/guides/payments/risk/card-verification-checks/#card-verification-checks) | | `statement_descriptor` | The description of the transaction that appears on the buyer's bank or card statement. | | `item_type` | The type of the transaction. For authorizations, this is `Authorization`. | | `payment_channel` | For card transactions only. Details if a card was present for the transaction. | | `authorization_currency` | [3-letter ISO code](https://en.wikipedia.org/wiki/ISO_4217) designating the currency of the authorization. (e.g. USD) | | `authorization_amount` | The amount processed by the authorization (in dollars). | | `transaction_id` | If this authorization has been captured, this field will be Finix's ID for the `Transfer` resource.The unique `transaction_id` begins with **TR** | | `transaction_amount` | If this authorization has been captured, this will be the amount of the capture. | | `application_id` | ID of the`Application` associated with the authorization. | | `application_business_name` | The registered name saved in the`Application` resource. | | `application_doing_business_as` | The "doing business as" name saved in the`Application` resource. | | `platform_id` | The ID of the`platform` that processed the authorization. | | `platform_name` | The name saved in the`platform` resource. | | `report_created_at` | A timestamp of when the report was created (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `report_range_start` | A timestamp that details the beginning of the range covered by this report (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `report_range_end` | A timestamp that details the end of the range covered by this report (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | ## Transactions settled The **Transactions Settled** report details all the transactions that have settled since the previous business day. The report also includes transactions that settled over the weekend or on bank holidays. Note the `Settlement` itself does not need to be approved or funded for the transaction to appear in this report. - All timestamps are in UTC. - All currencies are in the local currency (USD). - The report is generated on weekdays from Monday to Friday (excluding bank holidays). | **Field** | **Description** | | --- | --- | | `transfer_id` | ID of the `Transfer` resource.The unique `transfer_id` begins with **TR.** | | `trace_id` | Trace ID of the `Transfer`. The processor sends back the `trace_id` so you can track the transaction end-to-end.The unique `trace_id` begins with **FNX**, but can change depending on the processor of the transaction. | | `transfer_created_at` | Timestamp of when the transaction was created. | | `transfer_type` | Type of transaction. Valid values include:**DEBIT** (Sale and capture transactions)**CREDIT** (Refunds, reversals) | | `application_id` | ID of the `Application` associated with the transaction.The unique `application_id` begins with **AP.** | | `application_name` | Name of the `Application` associated with the transaction. | | `processor_id` | ID of the processor handling the transaction. | | `processor` | Name of the transaction processor. | | `merchant_id` | ID of the `Merchant` associated with the transaction.The unique `merchant_id` begins with **MU.** | | `merchant_identity_id` | ID of the `Identity` associated with the `Merchant`.The unique `merchant_identity_id` begins with **ID.** | | `processor_mid` | MID of the `Merchant` . | | `currency` | 3-letter [ISO code](https://www.iso.org/iso-4217-currency-codes.html) designating the currency of the `Transfers`. (e.g. USD) | | `amount` | The amount of the transaction (in dollars). | | `Fee` | The total fee that was withheld from the transaction (in dollars). | | `platform_fee` | If assessed, the platform fee that was applied to the transaction (in dollars). | | `application_fee` | If assessed, the application fee that was applied to the transaction (in dollars). | | `instrument_type` | The type of `Payment Instrument` used in the transaction. Possible values include: **BANK_ACCOUNT****PAYMENT_CARD****PAYMENT_CARD_PRESENT****APPLE_PAY****GOOGLE_PAY****VIRTUAL** (for credits and reversals) | | `settlement_id` | The ID of the `Settlement` associated with the transaction.The unique `settlement_id` begins with **ST.** | | `settlement_created_at` | A timestamp of when the `Settlement` was created (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `settlement_total_amount` | Total amount of the `Settlement` (in dollars). | | `settlement_total_fees` | The total sum of fees in the `Settlement` (in dollars). | | `settlement_net_amount` | Total amount sent to the `Merchant` (in dollars). | | `latest_funding_transfer_id` | The ID of the latest `Funding Transfer` associated with the `Settlement`. For more information about `Funding Transfers`, see [Payouts](/guides/platform-payments/seller-payouts).The unique `latest_funding_transfer_id` begins with **TR.** | | `latest_funding_transfer_trace_id` | The latest funding `trace_ID` associated with the transaction.The unique `latest_funding_transfer_trace_id` begins with **FNX**, but can change depending on the processor of the transaction. | | `funding_transfer_state` | The state of the `Funding Transfer`. Possible values include: **PENDING****SUBMITTED** | | `funding_transfer_created_at` | A timestamp of when the `Funding Transfer` was created. | | `fee_profile_id` | The ID of the `Fee Profile` associated with the transaction.The unique `fee_profile_id` begins with **FP.** | | `fee_profile_bps` | The Basis Point Fees on Credit Cards and Debit Cards. | | `fee_profile_fixed` | The Fixed Fee on Credit Cards and Debit Cards. | | `fee_profile_interchange_enabled` | If **TRUE** Interchange is enabled.If **FALSE** Interchange is not enabled. | | `fee_profile_ach_bps` | The Basis Point Fees on eCheck (ACH) transactions. | | `fee_profile_ach_fixed` | The Fixed Fee on eCheck (ACH) transactions. | ### Transaction types for reporting Transaction metadata is available to help you quickly filter, find, and manage transactions. The metadata details the transactions processed and the `Payment Instruments` used. Finix provides the following fields in the [Transactions Settled](#transactions-settled) and [Transaction Interchange Reports](#transaction-reports): - `item_type` - Type of transaction for the reported line. - `item_subtype` - Additional information describing the `item_type`. - `payment_type` - The type of `Payment Instrument`used in the transaction (or the original payment). - `payment_subtype` - Additional information describing the `payment_type`. - `payment_channel` - Details if the transaction was card-present (a debit card was used), or card-not-present (e.g. ecommerce transactions). The different values that can appear in the above fields include: | Field | Values | Description | | --- | --- | --- | | `item_type` | **ADJUSTMENT** | A manual transfer of funds between the For Benefit of (FBO) account and the users' accounts. | | `item_type` | **DISPUTE_TRANSFER** | A withdrawal or deposit to a merchant account following the outcome of a disputed charge. | | `item_type` | **FEE** | The fees (in dollars) charged to the sub-merchant or the client | | `item_type` | **P2C** | Real-time payments that use [Finix's Push to Card APIs](/guides/payouts/card-payouts). This includes P2P payments and disbursements. | | `item_type` | **PAYMENT** | Payments from cards, bank accounts, or other `Payment Instruments`, including captured charges. | | `item_type` | **RETURN** | Payments or reverses that get returned following a payment failure. | | `item_type` | **REVERSE** | Payments that got refunded to the buyer. | | `item_subtype` | **APPLICATION_FEE** | Any fee that exceeds the program fee that's defined for the `Merchant` and/or `Application`. | | `item_subtype` | **CAPTURE** | The clearing and transfer of funds from the buyer following the second part of a dual-message transaction. | | `item_subtype` | **CUSTOM_FEE** | The [subscription fee](/guides/billing/subscriptions/creating-subscriptions/). | | `item_subtype` | **MERCHANT_DEPOSIT** | A transfer of funds *to* a merchant account, for `item_type` **DISPUTE_TRANSFER** and **ADJUSTMENT** | | `item_subtype` | **MERCHANT_WITHDRAWAL** | A transfer of funds *from* a merchant account, for `item_type` **DISPUTE_TRANSFER** and **ADJUSTMENT** | | `item_subtype` | **PLATFORM_FEE** | The program fee. | | `item_subtype` | **PULL_FROM_CARD** | A transfer of funds *from* a payment card using [Finix's Push to Card APIs](/guides/payouts/card-payouts). | | `item_subtype` | **PUSH_TO_CARD** | A transfer of funds *to* a payment card using [Finix's Push to Card APIs](/guides/payouts/card-payouts). | | `item_subtype` | **REFUND** | A payment refunded to the buyer. | | `item_subtype` | **REFUND_RETURN** | A return of refunded funds to the `Merchant` , following a payment failure. | | `item_subtype` | **RETURN** | A return of funds following a payment failure. | | `item_subtype` | **SALE** | A transfer of funds from a buyer in a single-message transaction. | | `item_subtype` | **UNREFERENCED_REFUND** | A payment that has been refunded to the buyer, but does not reference the original transaction. | | `payment_type` | **CARD** | A payment card (e.g. A debit or credit card). | | `payment_type` | **ECHECK** | A bank account. | | `payment_type` | **VANTIV_OMNI_TOKEN** | A Worldpay-specific token that represents a `Payment Instrument`. | | `payment_subtype` | **APPLE_PAY** | Indicates that a `Payment Instrument` was used with Apple Pay in a **CARD_NOT_PRESENT** transaction. | | `payment_subtype` | **GOOGLE_PAY** | Indicates that a `Payment Instrument` was used with Google Pay in a **CARD_NOT_PRESENT** transaction. | | `payment_channel` | **CARD_PRESENT** | A physical card got used in-person to process the payment (e.g The card was swiped, dipped, tapped, etc.). | | `payment_channel` | **CARD_NOT_PRESENT** | The `Payment Instrument` used for the transaction got entered remotely. (e.g. online, phone, eCheck) | #### `Item_types` and available subtypes | `item_type` | `item_subtype` | | --- | --- | | **PAYMENT** | **CAPTURE****SALE** | | **P2C** | **PULL_FROM_CARD****PUSH_TO_CARD** | | **REVERSE** | **REFUND****UNREFERENCED_REFUND****RETURN****REFUND_RETURN** | | **DISPUTE_TRANSFER** | **MERCHANT_DEPOSIT****MERCHANT_WITHDRAWAL****PLATFORM_DEPOSIT****PLATFORM_WITHDRAWAL** | | **ADJUSTMENT** | **MERCHANT_DEPOSIT****MERCHANT_WITHDRAWAL****PLATFORM_DEPOSIT****PLATFORM_WITHDRAWAL** | | **FEE** | **APPLICATION_FEE****CUSTOM_FEE****PLATFORM_FEE** | #### `Payment_types` and available subtypes and channels | `payment_type` | `payment_subtype` | `payment_channel` | | --- | --- | --- | | **CARD** | **NULL** | **CARD_PRESENT**, **CARD_NOT_PRESENT** | | **APPLE_PAY**, **GOOGLE_PAY** | **CARD_NOT_PRESENT** | | | **ECHECK** | **NULL** | **CARD_NOT_PRESENT** | | **VANTIV_OMNI_TOKEN** | **NULL** | **CARD_NOT_PRESENT** | ## Fee Profile - Merchant The **Fee Profile - Merchant** report details all of your onboarded merchants and the fees applied to their transactions. If a fee profile isn't set up for a merchant, the application or platform level fee profile gets applied instead. - All timestamps are in UTC. - All currencies are in the local currency (USD). - The report is generated on weekdays Monday to Friday (excluding bank holidays). | **Field Name** | **Description** | | --- | --- | | `identity_id` | ID of the `Identity` resource associated with the `Merchant` .The unique `identity_id` begins with **ID.** | | `merchant_id` | ID of the `Merchant` resource associated with the transaction.The unique `merchant_id` begins with **MU.** | | `merchant_created_at` | A timestamp of when the `Merchant` was created. | | `application_id` | ID of the `Application` associated with the transaction.The unique `application_id` begins with **AP.** | | `business_name` | The full legal business name saved for the `Merchant` . | | `doing_business_as` | The "doing business as" name saved in the `Merchant` resource (if applicable). | | `processor` | Name of the transaction processor. | | `mcc` | The Merchant Category Code ([MCC](http://www.dm.usda.gov/procurement/card/card_x/mcc.pdf)) the `Merchant` is classified under. | | `fee_profile_id` | The ID of the `Fee Profile` associated with the transaction. | | `card_basis_points` | The fee, in [basis points](https://www.investopedia.com/terms/b/basispoint.asp), applied to credit and debit card transactions. | | `card_fixed_fee` | The fixed fee on credit and debit card transactions. | | `ach_debit_basis_points` | The fee, in basis points, on ACH `Transfers`. | | `ach_debit_fixed_fee` | The fixed fee on ACH `Transfers`. | | `charge_interchange_fees` | Set to **True** to incur interchange fees for card-based `transfers` | | `fee_profile_created_at` | A timestamp of the date the `Fee Profile` associated with the transaction was created. | | `line_1` | The first address line saved in the `Merchant` resource. | | `line_2` | The second address line saved in the `Merchant` resource. | | `city` | The city saved in the `Merchant` resource. | | `region` | The 2-letter State code saved in the `Merchant` resource. | | `postal_code` | The Postal code saved in the `Merchant` resource. | | `country` | The country saved in the `Merchant` resource. | | `processing_enabled` | Details if transaction processing is enabled for the `Merchant` . | | `settlement_enabled` | Details if settlement processing is enabled for the `Merchant` . | | `onboarding_state` | Details the state of the `Merchant's` Onboarding | | `application_name` | Application name | | `processor_submerchant_id` | Processor’s submerchant identification number | | `rounding_mode` | Details if a single `TRANSACTION` or a whole `SETTLEMENT` is rounded. | | `qualified tiers` | If specific functionality for qualified tiers are enabled or disabled. Usually `null`. | | `card_basis_points_decimal` | Version of `card_basis_points` that contains fractional values rounded to 1/10 of 1 basis point. | | `card_fixed_fee_decimal` | Version of `card_fixed_fee` that contains fractional values rounded to 1/10 of 1 cent. | | `ach_debit_basis_points_decimal` | Version of `ach_debit_basis_points` that contains fractional values rounded to 1/10 of 1 basis point. | | `ach_debit_fixed_fee_decimal` | Version of `ach_debit_fixed_fee` that contains fractional values rounded to 1/10 of 1 cent. | | `dispute_inquiry_fixed_fee` | The fee charged when a dispute is created with the `state` **INQUIRY.** | | `dispute_fixed_fee` | The fee charged when a dispute is created or moved to `state` **PENDING** . | | `ach_debit_return_fixed_fee` | Fee in cents of ACH debits (withdrawals) that are returned. | | `ach_credit_return_fixed_fee` | Fee in cents of ACH credits (deposits) that are returned. | | `visa_basis_points` | The percentage-based fee charged against the full amount of each Visa `transfer`. Calculated as one hundredth of one percent (1 basis point = .0001 or .01%). | | `visa_fixed_fee` | The fee (in cents) charged for each individual Visa `transfer`. | | `visa_charge_interchange` | Details if interchange fees are enabled for Visa `transfers`. | | `visa_assessments_basis_points` | The assessment fee charged to all Visa credit transactions | | `visa_acquirer_processing_fixed_fee` | The fee charged to all U.S.-based credit card authorizations acquired in the U.S. regardless of where the issuer/cardholder is located. If your business is based in the U.S., the acquirer processing fee will apply to all Visa credit card `Authorizations`. | | `visa_credit_voucher_fixed_fee` | The fee applied to refunds. | | `visa_kilobyte_access_fixed_fee` | The fee charged on each `Authorization` transaction submitted to Visa’s network for settlement. | | `discover_basis_points` | The percentage-based fee charged against the full amount of each Discover `transfer`. Calculated as one hundredth of one percent (1 basis point = .0001 or .01%). | | `discover_fixed_fee` | The fee (in cents) charged for each individual Discover `transfer`. | | `discover_charge_interchange` | Details if interchange fees are enabled for Discover `transfers`. | | `discover_assessments_basis_points` | The fee applied to the gross Discover card volume. | | `discover_data_usage_fixed_fee` | The Discover data usage fee that applies to all U.S.-based authorization transactions. | | `discover_network_authorization_fixed_fee` | This fee applies to all Discover network authorizations and replaces any previously assessed `discover_data_usage_fixed_fee`. | | `diners_club_basis_points` | The percentage-based fee charged against the full amount of each diners `transfer`. Calculated as one hundredth of one percent (1 basis point = .0001 or .01%). | | `diners_club_fixed_fee` | The fee (in cents) charged for each individual diners `transfer`. | | `diners_club_charge_interchange` | Details if interchange fees are enabled for diners `transfers`. | | `mastercard_basis_points` | The percentage-based fee charged against the full amount of each MasterCard `transfer`. Calculated as one hundredth of one percent (1 basis point = .0001 or .01%). | | `mastercard_fixed_fee` | The fee (in cents) charged for each individual MasterCard `transfer`. | | `mastercard_charge_interchange` | Details if interchange fees are enabled for MasterCard `transfers`. | | `mastercard_assessments_under1k_basis_points` | The assessment fee charged to Mastercard transactions less than or equal to $1,000. | | `mastercard_assessments_over1k_basis_points` | The assessment fee charged to Mastercard credit sale transactions greater than $1,000. | | `mastercard_acquirer_fees_basis_points` | This fee is assessed and based on a business’s gross MasterCard processing volume. This fee varies based on MasterCard’s assessed charge as it’s distributed across your portfolio of merchants. Generally, the ALF fee is a fraction of a basis point. For example, 0.0045%, 0.0075%, etc., are likely examples of a ALF fee. | | `jcb_basis_points` | The percentage-based fee charged against the full amount of each JCB `transfer`. Calculated as one hundredth of one percent (1 basis point = .0001 or .01%). | | `jcb_fixed_fee` | The fee (in cents) charged for each individual JCB `transfer`. | | `jcb_charge_interchange` | Details if interchange fees are enabled for JCB `transfers`. | | `american_express_basis_points` | The percentage-based fee charged against the full amount of each American Express `transfer`. Calculated as one hundredth of one percent (1 basis point = .0001 or .01%). | | `american_express_fixed_fee` | The fee (in cents) charged for each individual American Express `transfer`. | | `american_express_charge_interchange` | Details if interchange fees are enabled for American Express `transfers`. | | `american_express_assessment_basis_points` | The fee applied to the gross American Express card volume. | | `visa_base_II_system_file_transmission_fixed_fee` | The fee that's applied to all Visa transactions and is charged on top of other transaction-based fees. | | `visa_base_II_credit_voucher_fixed_fee` | The fee applied to all U.S.-based refunds | | `ancillary_fixed_fee_primary` | An additional fixed fee that can be charged per `Transfer` | | `ancillary_fixed_fee_secondary` | An additional fixed fee that can be charged per `Transfer` if the `ancillary_fixed_fee_primary` is passed | ## Settlement Merchant The Settled Merchant report shows you all the `Settlements` generated the day before and aggregated by `Merchant` . If a `Merchant` has multiple processing accounts, all accounts will be aggregated in the report. - All timestamps are in UTC. - All currencies are in the local currency (USD). - The report is generated on weekdays from Monday to Friday (excluding bank holidays). | Field | Description | | --- | --- | | `settlement_id` | The ID of the `Settlement` resource.The unique `settlement_id` begins with **ST.** | | `settlement_created_at` | A timestamp of when the merchant `Settlement` was created (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `identity_id` | ID of the `Identity` resource associated with the `Merchant`.The unique `identity_id` begins with **ID.** | | `merchant_id` | ID of the `Merchant` associated with the `Settlement`.The unique `merchant_id` begins with **MU.** | | `merchant_created_at` | A timestamp of when the `Merchant` was created. | | `application_id` | ID of the `Application` associated with the transaction.The unique `application_id` begins with **AP.** | | `business_name` | The full legal business name saved for the `Merchant` . | | `doing_business_as` | The "doing business as" name saved in the `Merchant` resource (if applicable). | | `processor` | Name of the `Settlement` processor. | | `total_amount` | Total sum of the `Settlement` (Fees+Net Settled). | | `total_fees` | Sum of the fees in the `Settlement`. | | `net_settled` | Details the amount paid to `Merchants` (`total_amount` - `total_Fees`). | | `currency` | 3-letter [ISO code](https://www.iso.org/iso-4217-currency-codes.html) designating the currency of the `Settlement`. (e.g. USD). | | `total_debit_amount` | The sum of all debit `Transfers` in the `Settlement`. | | `total_debit_count` | The total number of debit `Transfers` processed in the `Settlement`. | | `total_reversal_amount` | The sum of all reversal `Transfers` in the `Settlement`. | | `total_reversal_count` | The total number of reversal `Transfers` processed in the `Settlement`. | | `total_credit_amount` | The sum of all credit `Transfers` in the `Settlement`. | | `total_credit_count` | The total number of credit `Transfers` processed in the `Settlement`. | | `total_dispute_debit_adjustment_amount` | The sum of all debit dispute adjustment `Transfers` in the `Settlement`. | | `total_dispute_debit_adjustment_count` | The total number of debit dispute adjustment `Transfers` processed in the `Settlement`. | | `total_dispute_credit_adjustment_amount` | The sum of all credit dispute adjustment `Transfers` in the `Settlement`. | | `total_dispute_credit_adjustment_count` | The total number of credit dispute adjustment `Transfers` processed in the `Settlement`. | | `payment_instrument_id` | The ID of the `Payment Instrument` associated with the `Settlement`.The unique `payment_instrument_id` begins with **PI.** | | `latest_funding_transfer_id` | The ID of the latest `Funding Transfer` associated with the `Settlement`. For more information about `Funding Transfers`, see [Payouts](/guides/platform-payments/seller-payouts).The unique `transfer_id` begins with **TR.** | | `funding_transfer_created_at` | A timestamp of when the `Funding Transfer` was created. | | `latest_funding_transfer_trace_id` | The latest funding `trace_ID` associated with the `Funding Transfer`.The unique `trace_id` begins with **FN**, but can change depending on the processor of the transaction. | | `funding_transfer_state` | The state of the `Funding Transfer`. Possible values include: **PENDING****SUBMITTED** | | `payment_instrument_data` | Data associated with the `Payment Instrument`. | | `platform_settlement_id` | The `Settlement` ID associated with the platform.The unique `settlement_id` begins with **ST.** | | `platform_settlement_created_at` | A timestamp of when the `Settlement` for the platform was created (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `platform_latest_funding_transfer_id` | The ID of the latest `Funding Transfer` associated with the `Settlement`of the platform.The unique `transfer_id` begins with **TR.** | | `platform_funding_transfer_created_at` | A timestamp of when the `Funding Transfer` for the platform was created. | | `platform_latest_funding_transfer_trace_id` | The `trace_ID` of the latest `Funding Transfer` associated with the platform.The unique `trace_id` begins with **FN**, but can change depending on the processor of the transaction. | | `platform_funding_transfer_state` | The `state` of the `Funding Transfer` associated with the platform. | | `application_settlement_id` | The ID of the Settlement associated with the `Application`.The unique `settlement_id` begins with **ST.** | | `application_settlement_created_at` | A timestamp of when the `Settlement` for the `Application` was created (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `application_latest_funding_transfer_id` | The ID of the latest `Funding Transfer` associated with the `Settlement`of the `Application`.The unique `transfer_id` begins with **TR.** | | `application_funding_transfer_created_at` | A timestamp of when the `Funding Transfer` for the `Application` was created. | | `application_latest_funding_transfer_trace_id` | The `trace_ID` of the latest `Funding Transfer` associated with the `Application`.The unique `trace_id` begins with **FN**, but can change depending on the processor of the transaction. | | `application_funding_transfer_state` | The `state` of the `Funding Transfer` associated with the `Application`. | ## Settlement Application The **Settled Application** report shows you all the settlements generated the day before, aggregated by `Application`. If you are a Flex Client, this report shows only one line of data for the transactions processed with Finix. - All timestamps are in UTC. - All currencies are in the local currency (USD). - The report is generated on weekdays from Monday to Friday (excluding bank holidays). | Field | Description | | --- | --- | | `application_id` | ID of the `Application` associated with the transaction.The unique `application_id` begins with **AP.** | | `created_at` | Date the `Application` was created at | | `business_name` | The full legal business name saved for the `Application`. | | `doing_business_as` | The "doing business as" name saved in the `Application` resource. | | `currency` | 3-letter [ISO code](https://www.iso.org/iso-4217-currency-codes.html) designating the currency of the `Settlement`. (e.g. USD) | | `total_amount` | Total sum of the `Settlement` (Fees+Net Settled). | | `total_fees` | Sum of the fees in the `Settlement`. | | `net_settled` | Details the amount paid to `Merchants` (`total_amount` - `total_Fees`). | | `total_debit_amount` | The sum of all debit `Transfers` in the `Settlement`. | | `total_debit_count` | The total number of debit `Transfers` processed in the `Settlement`. | | `total_reversal_amount` | The sum of all reversal `Transfers` in the `Settlement`. | | `total_reversal_count` | The total number of reversal `Transfers` processed in the `Settlement`. | | `total_credit_amount` | The sum of all credit `Transfers` in the `Settlement`. | | `total_credit_count` | The total number of credit `Transfers` processed in the `Settlement`. | | `total_dispute_debit_adjustment_amount` | The sum of all debit dispute adjustment `Transfers` in the `Settlement`. | | `total_dispute_debit_adjustment_count` | The total number of debit dispute adjustment `Transfers` processed in the `Settlement`. | | `total_dispute_credit_adjustment_amount` | The sum of all credit dispute adjustment `Transfers` in the `Settlement`. | | `total_dispute_credit_adjustment_count` | The total number of credit dispute adjustment `Transfers` processed in the `Settlement`. | | `total_merchant_settlement_count` | The total number of `Settlements` that were created with `type` **MERCHANT.** | | `total_merchant_debit_settlement_amount` | The sum of `net_settled` for all `Settlements` with `type` **MERCHANT.** | | `total_merchant_debit_settlement_count` | The total number of `net_settled` `Settlements` with `type` **MERCHANT.** | ## Settlement processor The **Settled Processor** report shows you all the settlements generated the day before, aggregated by `Application` and by processor. If you are a Flex Client, this report shows only one line of data for your business with Finix. - All timestamps are in UTC. - All currencies are in the local currency (USD). - The report is generated on weekdays from Monday to Friday (excluding bank holidays). | **Field** | **Description** | | --- | --- | | `application_id` | ID of the `Application` associated with the transaction.The unique `application_id` begins with **AP.** | | `created_at` | When the `Application` was created | | `business_name` | The full legal business name saved for the `Application`. | | `doing_business_as` | The "doing business as" name saved in the `Application` resource. | | `processor` | Name of the settlement processor. | | `currency` | 3-letter [ISO code](https://www.iso.org/iso-4217-currency-codes.html) designating the currency of the `Settlement`. (e.g. USD). | | `total_amount` | Total sum of the `Settlement` (Fees+Net Settled). | | `total_fees` | Sum of the fees in the `Settlement`. | | `total_debit_amount` | The sum of all debit `Transfers` in the `Settlement`. | | `total_debit_count` | The total number of debit `Transfers` processed in the `Settlement`. | | `total_reversal_amount` | The sum of all reversal `Transfers` in the `Settlement`. | | `total_reversal_count` | The total number of reversal `Transfers` processed in the `Settlement`. | | `total_credit_amount` | The sum of all credit `Transfers` in the `Settlement`. | | `total_credit_count` | The total number of credit `Transfers` processed in the `Settlement`. | | `total_dispute_debit_adjustment_amount` | The sum of all debit dispute adjustment `Transfers` in the `Settlement`. | | `total_dispute_debit_adjustment_count` | The total number of debit dispute adjustment `Transfers` processed in the `Settlement`. | | `total_dispute_credit_adjustment_amount` | The sum of all credit dispute adjustment `Transfers` in the `Settlement`. | | `total_dispute_credit_adjustment_count` | The total number of credit dispute adjustment `Transfers` processed in the `Settlement`. | | `total_merchant_settlement_count` | The total number of `Settlements` that were created with `type` **MERCHANT.** | | `total_merchant_debit_settlement_amount` | The sum of `net_settled` for all `Settlements` with `type` **MERCHANT.** | | `total_merchant_debit_settlement_count` | The total number of `net_settled` `Settlements` with `type` **MERCHANT.** | ## Disputes (daily and monthly) The **Disputes** report shows all the chargebacks that got generated or updated the previous day. The CSV will be blank if no chargebacks are generated or updated on the previous day. - All timestamps are in UTC. - All currencies are in the local currency (USD). - The report is generated on weekdays from Monday to Friday (excluding bank holidays). | **Field** | **Description** | | --- | --- | | `dispute_id` | ID of the `Dispute`.The unique `dispute_id` begins with **DI.** | | `merchant_identity_id` | ID of the `Identity` resource associated with the `Merchant`.The unique `merchant_identity_id` begins with **ID.** | | `merchant_id` | ID of the `Merchant` associated with the `Dispute`.The unique `merchant_id` begins with **MU.** | | `merchant_created_at` | A timestamp of when the `Merchant` was created. | | `application_id` | ID of the `Application` associated with the `Dispute`.The unique `application_id` begins with **AP.** | | `business_name` | The full legal business name saved for the `Merchant` . | | `doing_business_as` | The "doing business as" name saved in the `Merchant` resource (if applicable). | | `processor` | Name of the `Dispute` processor. | | `dispute_created_at` | The date the `Dispute` was created | | `dispute_amount` | The total amount of the `Dispute` (in cents). | | `dispute_currency` | 3-letter [ISO code](https://www.iso.org/iso-4217-currency-codes.html) designating the currency of the `Dispute`. (e.g. USD). | | `reason` | The reason for the `Dispute`. | | `message` | The messages saved in the `Dispute`. | | `action` | The next `action` required to move forward with the `Dispute`. | | `respond_by` | The date the `Merchant` needs to submit evidence to supports their claim. | | `transfer_id` | The ID of the `Transfer` associated with the `Dispute`. | | `transfer_amount` | The total sum of the `Transfer` associated with the `Dispute`. | | `transfer_created_at` | A timestamp of when the `Transfer` was created. | | `adjustment_transfer_id` | ID of the `Transfer` created to adjust funds due to the `Dispute`.The unique `transfer_id` begins with **TR.** | | `adjustment_transfer_settlement_id` | ID of the `Settlement` created to adjust funds due to the `Dispute`.The unique `settlement_id` begins with **ST.** | | `adjustment_transfer_settlement_created_at` | A timestamp of when the `Transfer` was created to adjust funds. | | `settlement_funding_transfer_state` | The state of the `Funding Transfer` associated with the adjustment `Settlement`. Possible values include: **PENDING****SUBMITTED** | | `chargeback_settlement_exposure` | Exposure for a `Settlement` chargeback. | | `card_holder_name` | Name of the card holder saved in the `Payment Instrument`. | | `bin` | Bank Identification number for the `Payment Instrument`. | | `last_four` | Last four digits of the card or bank account number | | `brand` | The `brand` of the card saved in the `Payment Instrument`. | | `total_dispute_volume_past_30_days` | Total `Dispute` volume in the last 30 days. | | `total_dispute_volume_ratio_past_30_days` | Total `Dispute` volume / total processing volume in the last 30 days. | | `total_dispute_count_past_30_days` | The total number of `Disputes` processed over the last 30 days. | | `total_dispute_count_ratio_past_30_days` | The total number of `Disputes` that **SUCCEEDED** vs. **FAILED** over the last 30 days. | | `total_dispute_volume_past_year` | Total `Dispute` volume over the past year. | | `total_dispute_volume_ratio_past_year` | Total `Dispute` volume / total processing volume over the last year. | | `total_dispute_count_past_year` | Total number of `Disputes` processed over the last year. | | `total_dispute_count_ratio_past_year` | The total number of `Disputes` processed over the last year. | | `merchant_line_1` | The first address line saved in the `Merchant` resource. | | `merchant_line_2` | The second address line saved in the `Merchant` resource. | | `merchant_city` | The city saved in the `Merchant` resource. | | `merchant_region` | The 2-letter State code saved in the `Merchant` resource. | | `merchant_postal_code` | The Postal code saved in the `Merchant` resource. | | `merchant_country` | The country saved in the `Merchant` resource. | | `processing_enabled` | Details if transaction processing is enabled for the `Merchant` . | | `settlement_enabled` | Details if settlement processing is enabled for the `Merchant` . | | `merchant_onboarding_state` | Details the state of the `Merchant's` onboarding | | `dispute_updated_at` | A timestamp of the date the `Dispute` was last updated. | ## Disputes historical The **Disputes Historical** report gives you a view of your`Merchants` and how they're processing chargebacks and `Disputes`. `Merchants` with higher disputes in the last 30 days are shown at the top of the report. - All timestamps are in UTC. - All currencies are in the local currency (USD). - The report is generated on weekdays from Monday to Friday (excluding bank holidays). | Field | Description | | --- | --- | | `merchant_identity_id` | ID of the `Identity` resource associated with the `Merchant`.The unique `merchant_identity_id` begins with **ID.** | | `merchant_id` | ID of the `Merchant` associated with the `Dispute`.The unique `merchant_id` begins with **MU.** | | `created_at` | A timestamp of when the `Merchant` was created. | | `application_id` | ID of the `Application` associated with the `Dispute`The unique `application_id` begins with **AP.** | | `business_name` | The full legal business name saved for the `Merchant`. | | `doing_business_as` | The "doing business as" name saved in the `Merchant` resource (if applicable). | | `processor` | Name of the `Dispute` processor. | | `total_dispute_volume_past_30_days` | Total `Dispute` volume in the last 30 days. | | `total_dispute_volume_ratio_past_30_days` | Total `Dispute` volume / total processing volume in the last 30 days. | | `total_dispute_count_past_30_days` | The total number of `Disputes` processed over the last 30 days. | | `total_dispute_count_ratio_past_30_days` | The total number of `Disputes` that **SUCCEEDED** vs. **FAILED** over the last 30 days. | | `total_dispute_volume_past_year` | Total `Dispute` volume over the past year. | | `total_dispute_volume_ratio_past_year` | Total `Dispute` volume / total processing volume over the last year. | | `total_dispute_count_past_year` | Total number of `Disputes` processed over the last year. | | `total_dispute_count_ratio_past_year` | The total number of `Disputes` processed over the last year. | | `line_1` | The first address line saved in the `Merchant` resource. | | `line_2` | The second address line saved in the `Merchant` resource. | | `city` | The city saved in the `Merchant` resource. | | `region` | The 2-letter State code saved in the `Merchant` resource. | | `postal_code` | The Postal code saved in the `Merchant` resource. | | `country` | The country saved in the `Merchant` resource. | ## Failed funding instructions The **Failed Funding Instructions** report details every `Funding Instruction`, or [payout](/guides/payouts), that was returned. Reasons `Funding Instructions` can return include a closed bank account, an incorrect bank account number, etc. - All timestamps are in UTC. - All currencies are in the local currency (USD). - The report is generated on weekdays Monday to Friday (excluding bank holidays). | **Field Name** | **Description** | | --- | --- | | `Return Date` | A timestamp that details the when the `Funding Instructions` was returned (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `Original Date` | A timestamp that details the when the `Funding Instructions` was originally processed (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `Attempted Funds Transfer Date` | A timestamp that details when the attempt to push funds to the relevant `Payment Instrument` was made (in UTC using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) formatting). | | `Merchant Name` | The legal name saved in the `Merchant` resource. | | `Sub Merchant Business Name` | Merchant's full legal business name (If INDIVIDUAL_SOLE_PROPRIETORSHIP, use the control owner's first name, Full legal last name and middle initial; max 120 characters) | | `Funding Sub Merchant ID` | ID of the `Merchant` associated with the returned `Funding Instructions`. | | `Funds Transfer Request ID` | Trace ID of the `Funding Instructions`. | | `Vantiv Payment ID` | Unique identifier for transaction assigned by payment processor A Worldpay-specific ID that represents the `Funding Instructions`. | | `Txn Type` | The type of transaction. Possible values include: **FIPC:** Funding Instruction PayFac Credit**FIPD:** Funding Instruction PayFac Debit**FIRC:** Funding Instruction Reserve Credit**FIPD:** Funding Instruction Reserve Debit**FISC:** Funding Instruction Sub-merchant Credit**FISD:** Funding Instruction Sub-merchant Debit**FIVC:** Funding Instruction Vendor Credit**FIVD:** Funding Instruction Vendor Debit**FICC:** Funding Instruction Physical Check Credit**FICD:** Funding Instruction Physical Check Debit | | `Funds Transfer Amount` | The total sum of the `Transfer` associated with the `Funding Instructions`. | | `Reason Code` | The Reason Code details the reason why the `Funding Instructions` failed. | | `Reason Message` | The Reason Message provides more detail regarding why the `Funding Instructions` failed. | | `Routing Number` | The routing number for the bank account where `Funding Instructions` were sent. | | `Account Number` | The account number for the bank account where `Funding Instructions` were sent. | | `Account Name` | The name of the bank account owner. | For a list of the `Reason Codes` that can cause `Funding Instructions` to return and the next steps to take, see [Resolving Funding Instruction Failures](/guides/platform-payments/seller-payouts/managing-failed-payouts#resolving-funding-instruction-failures). --- # Managing Your Team Members Source: https://docs.finix.com/guides/managing-operations/managing-team-members Manage your team's members and permissions on the dashboard. After signing up, Finix assigns the **administrator** role to you or another team member. As an administrator, you can manage team members, change their roles, and view all resources on the dashboard. You can manage team members from the Finix dashboard by clicking the **Company** → **Team** tab > **Team Members** tab. Company team members We recommend limiting the number of administrators to three. ## Adding a Team Member To add a team member, from your [dashboard](https://dashboard.finix.com/Login) 1. Click **Company** → **Team** tab > **Team Members** tab. - On this page, you'll see all your team members. 2. Click the **Add New Team Member** button. Company - Add Team Member - The **Add New Team Member** page displays. Company - Add Team Member Form 1. Provide the following information about the team member: | Field | Description | | --- | --- | | Dashboard Account Name | This is the name team members will see when they log in to the dashboard. While Finix sets a default name, you can easily change it to fit your business needs. | | Email | The email of your team member. | | Role | The role of the team member. A role defines the level of access team members have on the Finix Dashboard. | For a complete list of roles, see [Roles and Permissions](/guides/managing-operations/managing-team-members/roles-permissions). 2. After providing the above, click the **Add Team Member** button to invite the team member to your team. - Your team member will receive an email invitation to join your dashboard. ## Manage Team Members To manage a team member: 1. Click **Company** → **Team** tab > **Team Members** tab. - On this page, you'll see all your team members. 2. Select the team member from the table to view their details. - The **Team Member** details screen displays. 3. Click the **...** icon in the top right to see available actions for the team member. Manage Teams The available actions are: - Resend Dashboard Invite Email - Edit Team Member Role - Deactivate Team Member - Reset Multi-Factor Authentication You can also perform actions on a team member by clicking the three dots next to their name on the **Company** screen > **Team** tab. ## Custom Roles Custom Roles are also available to accommodate your business needs. For more information, see [Roles and Permissions](/guides/managing-operations/managing-team-members/roles-permissions#custom-roles). --- # Multi-Factor Authentication Source: https://docs.finix.com/guides/managing-operations/managing-team-members/multi-factor-authentication Learn how to enable multi-factor authentication for you and your company. When you log onto the Dashboard, you have the ability to sign up for multi-factor authentication. Finix supports SMS and Mobile Authenticator options. Users can opt into either option. When an individual logs in with multi-factor authentication enabled, they'll be prompted to either enter a Code sent from Finix or enter a code from a mobile authenticator app such as Google Authenticator. ## Enabling multi-factor authentication for yourself Set up MFA To enable multi-factor authentication for yourself on the dashboard: 1. Navigate to the Company > User page 2. Click on the Set Up MFA Link A screen will appear asking whether to enable: - SMS Authentication - Mobile Authenticator SMS or Mobile Authenticator After choosing your selection, you can either: 1. Enter a phone number to receive an SMS text (carrier text message rates may apply) 2. Set up a mobile authenticator with Google Authenticator, Okta, or another provider. When you have successfully enabled multi-factor authentication, you'll be routed to the same user page. MFA enabled ## Enforcing multi-factor authentication for your company Administrators and User Management Admins can enforce multi-factor authentication for all users at the same access level. This would apply to anyone who appears in the `Team` page. To enforce multi-factor authentication: 1. Navigate to the Company > Team > Members Page 2. Click on the checkbox to enforce MFA 3. Confirm you want to enable MFA MFA enabled When logging into the Finix Dashboard, all `Team Members` will be prompted to choose to authenticate using SMS or a mobile authenticator. ## Resetting multi-factor authentication for a Team Member Administrators and User Management Admins can reset multi-factor authentication for an individual team member. To reset a team member's multi-factor: 1. Navigate to the Company > Team > Members 2. Click on the Team Member you want to reset 3. Click Reset Multi-Factor Authentication MFA Reset --- # Roles and Permissions Source: https://docs.finix.com/guides/managing-operations/managing-team-members/roles-permissions Finix provides built-in roles to control what team members can access in the Dashboard. You can also create [custom roles](#custom-roles) to fit your business needs. For security, we recommend assigning no more than three Administrators. For instructions on how to add and manage team members, refer to [Managing Your Team Members](/guides/managing-operations/managing-team-members). ## Built-in roles Finix includes seven built-in roles. Each matrix below shows the resources that role can view and manage. - **View**: Can see the resource in the Dashboard. - **Manage**: Can create, edit, delete, export, approve, or take action on the resource. ### Administrator Full control over the Dashboard, including team management, all resources, and all settings. | Resource | View | Manage | | --- | --- | --- | | Team members | ✓ | ✓ | | API keys | ✓ | ✓ | | Webhooks | ✓ | ✓ | | Transactions | ✓ | ✓ | | Payment instruments | ✓ | ✓ | | Payout settings | ✓ | ✓ | | Settlements | ✓ | ✓ | | Disputes | ✓ | ✓ | | Fee Profiles | ✓ | ✓ | | Platform Fee Profile | ✓ | ✓ | | Risk Profiles | ✓ | ✓ | | Identities and Merchants | ✓ | ✓ | | Applications | ✓ | ✓ | ### Payment Operations Manager Broad access to transactions, Merchants, and Settlements. No access to team management or developer tools. | Resource | View | Manage | | --- | --- | --- | | Team members | | | | API keys | | | | Webhooks | | | | Transactions | ✓ | ✓ | | Payment instruments | ✓ | ✓ | | Payout settings | ✓ | ✓ | | Settlements | ✓ | ✓ | | Disputes | ✓ | ✓ | | Fee Profiles | ✓ | ✓ | | Platform Fee Profile | | | | Risk Profiles | ✓ | ✓ | | Identities and Merchants | ✓ | ✓ | | Applications | ✓ | ✓ | ### Merchant Manager Can onboard, add, and update Merchants. Can manage Settlements and Fee Profiles. No access to Disputes or developer tools. | Resource | View | Manage | | --- | --- | --- | | Team members | | | | API keys | | | | Webhooks | | | | Transactions | ✓ | | | Payment instruments | ✓ | | | Payout settings | ✓ | ✓ | | Settlements | ✓ | ✓ | | Disputes | | | | Fee Profiles | ✓ | ✓ | | Platform Fee Profile | | | | Risk Profiles | ✓ | | | Identities and Merchants | ✓ | ✓ | | Applications | ✓ | ✓ | ### Settlement Specialist Can review and approve Settlements and export transactions. On **Finix Flex**, Settlement Specialists can view Settlements and export transactions. | Resource | View | Manage | | --- | --- | --- | | Team members | | | | API keys | | | | Webhooks | | | | Transactions | ✓ | | | Payment instruments | ✓ | | | Payout settings | ✓ | ✓ | | Settlements | ✓ | ✓ | | Disputes | | | | Fee Profiles | ✓ | ✓ | | Platform Fee Profile | | | | Risk Profiles | ✓ | | | Identities and Merchants | ✓ | ✓ | | Applications | ✓ | ✓ | ### Developer Full access to API keys, webhooks, transactions, and Disputes. Read-only access to payout settings and Settlements. | Resource | View | Manage | | --- | --- | --- | | Team members | | | | API keys | ✓ | ✓ | | Webhooks | ✓ | ✓ | | Transactions | ✓ | ✓ | | Payment instruments | ✓ | ✓ | | Payout settings | ✓ | | | Settlements | ✓ | | | Disputes | ✓ | ✓ | | Fee Profiles | ✓ | | | Platform Fee Profile | | | | Risk Profiles | ✓ | | | Identities and Merchants | ✓ | | | Applications | ✓ | | ### Viewer Read-only access to the Dashboard. Can view data but cannot make changes. | Resource | View | Manage | | --- | --- | --- | | Team members | | | | API keys | | | | Webhooks | | | | Transactions | ✓ | | | Payment instruments | ✓ | | | Payout settings | ✓ | | | Settlements | ✓ | | | Disputes | ✓ | | | Fee Profiles | ✓ | | | Platform Fee Profile | | | | Risk Profiles | ✓ | | | Identities and Merchants | ✓ | | | Applications | ✓ | | ### User Management Admin Can manage team members, create roles, and invite users. No access to any other Dashboard section. | Resource | View | Manage | | --- | --- | --- | | Team members | ✓ | ✓ | | API keys | | | | Webhooks | | | | Transactions | | | | Payment instruments | | | | Payout settings | | | | Settlements | | | | Disputes | | | | Fee Profiles | | | | Platform Fee Profile | | | | Risk Profiles | | | | Identities and Merchants | | | | Applications | | | ## Custom Roles You can create custom roles to match permissions to your business needs. To create a custom role: 1. In the [Finix Dashboard](https://dashboard.finix.com/Login), click **Company > Team > Roles**. 2. Click **Create Custom Role**. 3. Fill in the role name, description, and permissions. Custom roles can include any permission listed above except Team Management. Custom roles cannot add team members or change role assignments. --- # 1099-K Tax Forms Source: https://docs.finix.com/guides/managing-operations/security-compliance/1099k Learn how the 1099-K form works and how to keep your merchant information current for accurate IRS reporting. Every year, Finix's processor sends out a 1099-K form to *every* Finix account. The 1099-K form details the sales activity of your account to help you report your taxes. This form is sent to you, the IRS, and some US states. - For information about understanding your 1099-K form, see the following [IRS article](https://www.irs.gov/businesses/understanding-your-form-1099-k). - For your review, a blank example of the 1099-K form is available [on the IRS website](http://www.irs.gov/pub/irs-pdf/f1099k.pdf). The 1099-K form is generated based on the information saved in the `Identities` resource associated with the `Merchant` . Keep the `Identities` resource updated with any changes to ensure there aren't any issues with the 1099-K form. Changes that would require the `Identities` resource to be updated include: - Change in address or name. - Ownership changes. - Bank account changes. - Change in tax ID or other entity information. If you make changes to the `Identities` resource, you'll need to verify the updated information by submitting a **new** Merchant Verification Request and provisioning the merchant again. For details on how to re-provision a merchant, see [Re-Verifying Already Approved Merchants](/guides/platform-payments/onboarding-sellers/seller-onboarding-process). The total amount listed on the 1099-K form is the *gross total*. Refunds, credits, and fees are not included in the amount listed on the 1099-K form. --- # Approved MCCs Source: https://docs.finix.com/guides/managing-operations/security-compliance/approved-merchant-category-codes Learn about the sellers and MCCs that are approved to process payments on Finix. In the finance ecosystem, [Merchant Category Codes (MCCs)](https://en.wikipedia.org/wiki/Merchant_category_code) are used to classify businesses by the type of goods or services they provide. For example, grocery stores would use the MCC `5411`, whereas department stores would use the MCC `5311`. Beyond general record-keeping, MCCs are important because they contribute to interchange fee calculation, payment authorization rates, and fraud prevention. Finix assigns customers a list of MCCs their Seller Merchants can select during the onboarding process. Customers offering many products and services may have an expansive MCC lists, whereas customers offering a narrower range of products and services would have a smaller list. Below, you'll find the full list of MCCs that Finix currently supports. For information about prohibited and restricted businesses, see [Prohibited and Restricted Businesses & Activities](https://finix.com/terms-and-policies/prohibited-and-restricted-businesses). Should you have any questions about whether Finix can support your business, please reach out to your Finix point of contact or email [Finix Support](/guides/getting-started/support-at-finix). ## Approved Merchant category codes Below is a complete list of the Merchant Category Codes (MCCs) that Finix supports. table thead tr th div b MCC th div b Description tbody tr td 0742 td Veterinary Services tr td 0763 td Agricultural Cooperatives tr td 0780 td Horticultural Services / Landscaping Services tr td 1520 td General Contractors-Residential and Commercial tr td 1711 td Air Conditioning Contractors – Sales and Installation / Heating Contractors – Sales, Service, Installation tr td 1731 td Electrical Contractors tr td 1740 td Insulation – Contractors / Plastering Contractors / Masonry, Stonework Contractors / Stonework and Masonry Contractors / Tile Settings Contractors tr td 1750 td Carpentry Contractors tr td 1761 td Roofing - Contractors / Sheet Metal Work - Contractors / Siding - Contractors tr td 1771 td Contractors – Concrete Work tr td 1799 td Contractors – Special Trade, Not Elsewhere Classified tr td 2741 td Miscellaneous Publishing and Printing tr td 2842 td Specialty cleaning and sanitation services. tr td 4111 td Local/Suburban Commuter Passenger Transportation - Railroads, Ferries, Local Water Transportation tr td 4119 td Ambulance Services tr td 4121 td Taxicabs and Limousines tr td 4214 td Delivery Services – Local / Freight Carriers / Motor Freight Carriers / Moving and Storage Companies / Trucking - Local/Long Distance tr td 4225 td Storage / Warehousing, Public tr td 4457 td Boat Rentals and Leases tr td 4468 td Marinas, Marine Service, and Supplies tr td 4582 td Flying Fields tr td 4789 td Transportation Services, Not elsewhere classified) tr td 4812 td Telecommunications Equipment including telephone sales tr td 4899 td Cable and other pay television (previously Cable Services) tr td 4900 td Electric, Gas, Sanitary and Water Utilities tr td 5013 td Motor vehicle supplies and new parts tr td 5021 td Office and Commercial Furniture tr td 5039 td Construction Materials, Not Elsewhere Classified tr td 5044 td Office, Photographic, Photocopy, and Microfilm Equipment tr td 5045 td Computers, Computer Peripheral Equipment, Software tr td 5046 td Commercial Equipment, Not Elsewhere Classified tr td 5047 td Medical, Dental Ophthalmic, Hospital Equipment and Supplies tr td 5065 td Electrical Parts and Equipment tr td 5072 td Hardware Equipment and Supplies tr td 5074 td Plumbing and Heating Equipment and Supplies tr td 5085 td Industrial Supplies, Not Elsewhere Classified tr td 5094 td Precious Stones and Metals, Watches and Jewelry tr td 5099 td Durable Goods, Not Elsewhere Classified tr td 5111 td Stationery, Office Supplies, Printing, and Writing Paper tr td 5122 td Drugs, Drug Proprietors and Druggist's Sundries (Card-Present) tr td 5131 td Piece Goods, Notions, and other Dry Goods tr td 5137 td Men’s Women’s and Children’s Uniforms and Commercial Clothing tr td 5139 td Commercial Footwear tr td 5169 td Chemicals and Allied Products, Not Elsewhere Classified tr td 5172 td Petroleum and Petroleum Products tr td 5192 td Books, Periodicals, and Newspapers tr td 5193 td Florists’ Supplies, Nursery Stock and Flowers tr td 5198 td Paints, Varnishes, and Supplies tr td 5199 td Non-durable Goods, Not Elsewhere Classified tr td 5200 td Home Supply Warehouse Stores tr td 5211 td Lumber and Building Materials Stores tr td 5231 td Glass Stores / Paint and Wallpaper Stores / Wallpaper Stores tr td 5251 td Hardware Stores tr td 5261 td Nurseries – Lawn and Garden Supply Store tr td 5300 td Wholesale Clubs tr td 5309 td Duty Free Store tr td 5310 td Discount Stores tr td 5311 td Department Stores tr td 5331 td Variety Stores tr td 5399 td Misc. General Merchandise tr td 5411 td Grocery Stores / Supermarkets tr td 5422 td Freezer and Locker Meat Provisioners / Meat Provisioners - Freezer and Locker tr td 5441 td Candy Stores / Confectionary Stores / Nut Stores tr td 5451 td Dairy Products Stores tr td 5462 td Bakeries tr td 5499 td Misc. Food Stores – Convenience Stores and Specialty Markets (EXCLUDING: Personal Enhancement Products and/or Nutraceuticals) tr td 5511 td Car and Truck Dealers (New and Used) Sales, Service, Repairs, Parts and Leasing tr td 5521 td Automobile and Truck Dealers (Used Only) tr td 5532 td Automotive Tire Stores tr td 5533 td Automotive Parts, Accessories Stores tr td 5541 td Service Stations (with or without ancillary services) tr td 5551 td Boat Dealers tr td 5561 td Recreational and Utility Trailers, Camp Dealers tr td 5571 td Motorcycle Dealers tr td 5599 td Miscellaneous Auto Dealers tr td 5611 td Men’s and Boy’s Clothing and Accessories Stores tr td 5621 td Women’s Ready-to-Wear Stores tr td 5631 td Women’s Accessory and Specialty Shops tr td 5641 td Children’s and Infant’s Wear Stores tr td 5651 td Family Clothing Stores tr td 5655 td Sports Apparel, Riding Apparel Stores tr td 5661 td Shoe Stores tr td 5681 td Furriers and Fur Shops tr td 5690 td Direct Marketing – Insurance Services tr td 5691 td Men’s and Women’s Clothing Stores tr td 5697 td Tailors, Seamstress, Mending, and Alterations tr td 5698 td Wig and Toupee Stores tr td 5699 td Miscellaneous Apparel and Accessory Shops tr td 5712 td Furniture, Home Furnishings, and Equipment Stores, Except Appliances tr td 5713 td Floor Covering Stores tr td 5714 td Drapery, Window Covering and Upholstery Stores tr td 5718 td Fireplace, Fireplace Screens, and Accessories Stores tr td 5719 td Miscellaneous Home Furnishing Specialty Stores tr td 5722 td Household Appliance Stores tr td 5732 td Electronic Sales tr td 5733 td Music Stores, Musical Instruments, Piano Sheet Music tr td 5734 td Computer Software Stores tr td 5735 td Record Shops tr td 5811 td Caterers tr td 5812 td Eating places and Restaurants; includes food delivery tr td 5813 td Drinking Places (Alcoholic Beverages), Bars, Taverns, Cocktail lounges, Nightclubs and Discotheques tr td 5814 td Fast Food Restaurants; includes food delivery tr td 5817 td Digital Goods: Applications (Excludes Games) tr td 5832 td Antique Shops – Sales, Repairs, and Restoration Services tr td 5912 td Drug Stores and Pharmacies (Card-Present) tr td 5921 td Package Stores – Beer, Wine, and Liquor (in-person and online) tr td 5931 td Used Merchandise and Secondhand Stores tr td 5932 td Antique Shops tr td 5940 td Bicycle Shops – Sales and Service tr td 5941 td Sporting Goods Stores tr td 5942 td Book Stores tr td 5943 td Stationery Stores, Office and School Supply Stores tr td 5944 td Watch, Clock, Jewelry, and Silverware Stores tr td 5945 td Hobby, Toy, and Game Shops tr td 5946 td Camera and Photographic Supply Stores tr td 5947 td Card Shops, Gift, Novelty, and Souvenir Shops tr td 5948 td Luggage and Leather Goods Stores tr td 5949 td Sewing, Needle, Fabric, and Piece Goods Stores tr td 5950 td Glassware/Crystal Stores tr td 5964 td Direct Marketing - Catalog Merchant tr td 5970 td Artist’s Supply and Craft Shops tr td 5971 td Art Dealers and Galleries tr td 5973 td Religious Goods Stores tr td 5975 td Hearing Aids – Sales, Service, and Supply Stores tr td 5976 td Orthopedic Goods Prosthetic Devices tr td 5977 td Cosmetic Stores tr td 5983 td Fuel – Fuel Oil, Wood, Coal, Liquefied Petroleum tr td 5992 td Florists tr td 5995 td Pet Shops, Pet Foods, and Supplies Stores tr td 5996 td Swimming Pools – Sales, Service, and Supplies tr td 5997 td Electric Razor Stores – Sales and Service tr td 5998 td Tent and Awning Shops tr td 5999 td Miscellaneous and Specialty Retail Stores tr td 6300 td Insurance Sales, Underwriting, and Premiums tr td 6513 td Real Estate Agents & Managers tr td 7011 td Lodging – Hotels, Motels, Resorts, Central Reservation Services (not elsewhere classified) tr td 7032 td Sporting and Recreational Camps (EXCLUDING Nudist Camps) tr td 7033 td Trailer Parks and Camp Grounds tr td 7210 td Laundry, Cleaning, and Garment Services tr td 7211 td Laundries tr td 7216 td Dry Cleaners tr td 7217 td Carpet and Upholstery Cleaning tr td 7221 td Photographic Studios tr td 7230 td Barber and Beauty Shops tr td 7251 td Shoe Repair/Hat Cleaning tr td 7261 td Funeral Service and Crematories tr td 7276 td Tax Preparation Service tr td 7277 td Counseling Service - Marriage, Personal tr td 7298 td Health and Beauty Spas tr td 7299 td Miscellaneous General Services tr td 7311 td Advertising Services tr td 7332 td Blueprinting and Photocopying Services tr td 7333 td Commercial Photography, Art and Graphics tr td 7338 td Quick Copy, Repro, and Blueprint tr td 7342 td Exterminating & Disinfecting Services tr td 7349 td Cleaning and Maintenance, Janitorial Services tr td 7361 td Employment Agencies, Temporary Help Services tr td 7372 td Computer Programming, Integrated Systems Design and Data Processing Services tr td 7375 td Information Retrieval Services tr td 7379 td Computer Maintenance and Repair Services, Not Elsewhere Classified tr td 7392 td Management, Consulting, and Public Relations Services tr td 7393 td Detective Agencies, Protective and Security Services – Including Armored Cars and Guard Dogs tr td 7394 td Equipment Rental and Leasing Services, Tool Rental, Furniture Rental, and Appliance Rental tr td 7399 td Business Services, Not Elsewhere Classified; Event Planning and Management tr td 7519 td Recreational Vehicle Rentals tr td 7531 td Automotive Body Repair Shops tr td 7534 td Tire Re-treading and Repair Shops tr td 7538 td Automotive Service Shops (Non Dealer) tr td 7542 td Car Washes tr td 7549 td Towing Services tr td 7622 td Electronics Repair Shops tr td 7623 td Air Conditioning and Refrigeration Repair Shops tr td 7629 td Electrical And Small Appliance Repair Shops tr td 7631 td Watch/Jewelry Repair tr td 7641 td Furniture, Furniture Repair, and Furniture Refinishing tr td 7699 td Repair Shops and Related Services –Miscellaneous tr td 7829 td Motion Pictures and Video Tape Production and Distribution tr td 7832 td Motion Picture Theaters tr td 7911 td Dance Halls, Studios and Schools tr td 7922 td Theatrical Producers (Except Motion Pictures), Ticket Agencies tr td 7941 td Commercial Sports, Athletic Fields, Professional Sport Clubs, and Sport Promoters; Sports arena and Stadium Management tr td 7991 td Tourist Attractions and Exhibits tr td 7992 td Golf Courses - Public tr td 7993 td Video Amusement Game Supplies tr td 7994 td Video Game Arcades/Establishments tr td 7996 td Amusement Parks, Carnivals, Circuses, Fortune Tellers tr td 7997 td Membership Clubs (Sports, Recreation, Athletic), Country Clubs, and Private Golf Courses tr td 7999 td Recreation Services (Not Elsewhere Classified) (EXCLUDES Shooting Ranges) tr td 8011 td Doctors and Physicians (Not Elsewhere Classified) tr td 8021 td Dentists and Orthodontists tr td 8031 td Osteopaths tr td 8041 td Chiropractors tr td 8042 td Optometrists and Ophthalmologists tr td 8043 td Opticians, Opticians Goods and Eyeglasses tr td 8049 td Podiatrists and Chiropodists tr td 8050 td Nursing and Personal Care Facilities; Home Healthcare tr td 8062 td Hospitals tr td 8071 td Medical and Dental Laboratories tr td 8099 td Medical Services and Health Practitioners (Not Elsewhere Classified) tr td 8111 td Legal Services and Attorneys tr td 8211 td Elementary and Secondary Schools tr td 8220 td Colleges, Junior Colleges, Universities, and Professional Schools tr td 8241 td Correspondence Schools tr td 8244 td Business and Secretarial Schools tr td 8249 td Vocational Schools and Trade Schools tr td 8299 td Schools and Educational Services (Not Elsewhere Classified) tr td 8351 td Child Care Services tr td 8398 td Charitable and Social Service Organizations tr td 8641 td Civic, Fraternal, and Social Associations tr td 8661 td Religious Organizations tr td 8699 td Membership Organizations (Not Elsewhere Classified) tr td 8734 td Testing Laboratories tr td 8911 td Architectural – Engineering and Surveying Services tr td 8931 td Accounting, Auditing, and Bookkeeping Services tr td 8999 td Professional Services (Not Elsewhere Defined) tr td 9222 td Fines tr td 9311 td Tax Payments tr td 9399 td Government Services (Not Elsewhere Classified) ## Restricted MCCs by American Express (AMEX) American Express (AMEX) has a list of restricted MCCs that are not allowed to be processed by AMEX. Below is a list of restricted MCCs by AMEX. table thead tr th MCC th Description tbody tr td 6010 td Financial Institutions – Manual Cash Disbursements tr td 6011 td Financial Institutions – Automated Cash Disbursements tr td 6012 td Financial Institutions – Merchandise and Services tr td 6051 td Non-Financial Institutions – Foreign Currency, Cryptocurrency, Money Orders (not Wire Transfer), Scrip, and Travelers Checks --- # Avoiding Compliance Overdue Fees Source: https://docs.finix.com/guides/managing-operations/security-compliance/avoiding-compliance-overdue-fees To stay PCI compliant, all users who store, process, or transmit credit card data—whether onboarded directly or through an ISV—must complete and sign a PCI compliance form each year. These forms are generated automatically, pre-filled with business data, at onboarding and each subsequent year. For ISVs, a new form is generated annually for each sub-merchant onboarded through their applications. ISVs are charged for any overdue forms for their sub-merchants and may choose to pass those charges onward using merchant Fee Profiles. Merchants must review and validate the compliance form within 90 days of its generation. If a compliance form remains unsigned for more than 90 days, the system applies an overdue compliance fee. A daily automated process checks for overdue forms and, using a 30-day look-back, issues a charge if a form has not been signed within the previous 30 days. The fee is applied for each 30-day period the form remains unsigned. Direct merchants are charged through their own Fee Profiles (if configured). Overdue compliance charges are visible in the **Company** → **Company Financials** → **Cost Profile** tab. Applicable fees for merchants are displayed in their Fee Profiles (if configured). Notifications regarding overdue forms and potential upcoming fees are sent monthly. The system processes fee charges daily at midnight Eastern Time. All users should be aware of these fee mechanisms and the need to promptly complete PCI compliance forms to avoid recurring charges. Manual uploads of signed forms are not supported. Signing must be completed directly through the [Finix Dashboard](/guides/managing-operations/security-compliance/managing-pci-compliance#completing-compliance-forms-using-the-dashboard) or [API](/guides/managing-operations/security-compliance/managing-pci-compliance#completing-compliance-forms-using-the-api). Refer to our guide on [Managing PCI Compliance](/guides/managing-operations/security-compliance/managing-pci-compliance) to learn how to complete PCI compliance forms. ## How to stay compliant To maintain PCI compliance: 1. **Annually review and sign your PCI compliance form:** A new, pre-filled form is generated at onboarding and every year after. 2. **Complete the form within 90 days:** You must sign and attest to the form via the Finix dashboard or API—manual uploads are not allowed. 3. **Monitor notifications:** Watch for email or dashboard alerts about pending or overdue forms. 4. **Avoid overdue fees:** Unsigned forms after 90 days trigger monthly fees until signed. 5. **For ISVs:** Track your sub-merchants’ compliance and address any overdue forms promptly. ## Viewing the overdue fee amount The overdue fee is applied to the company's Cost Profile. *To view the overdue fee amount*: 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login). 2. In the left-navigation, click **Company**. - The **Company** page displays. 3. Click the **Company Financials** tab. 4. Click the **Cost Profile** tab. 5. Scroll down to the **PCI SAQ Compliance Forms** section. - You will see a **Per Overdue Compliance Form Fee**. ## Assigning fees to Merchants You can assign the Overdue PCI Compliance Form Fee to merchants using Fee Profiles. *To apply the overdue fee to a Fee Profile*: 1. From the left navigation, click **Merchants** to expand the menu. 2. Click **Merchants**. - The **Merchants** list page displays. 3. Click a merchant to open the merchant details page. 4. Click the **Account Settings** → **Fee Profiles** tab. - If a Fee Profile is already applied to the merchant, you can click **Edit** to edit the Fee Profile applied to the merchant (if permission is granted): - If the merchant is not assigned a Fee Profile, by default, the Fee Profile below has been inherited from the Fee Profile applied to the application. You have the option to **Apply Standard Fee Profile for Direct Merchants** or **Create a Custom Fee Profile**. 5. Select the desired option and click **Save and Continue** until you arrive at the **ACH & Additional** tab. 6. On the **ACH & Additional** tab, set an amount for the **Overdue PCI Compliance Form Fee**. 7. Click **Save and Continue** and submit the updated Fee Profile. - From the **Fee Profiles** tab, locate **Value Added Services**. The **Overdue PCI Compliance Form Fee** is displayed. All merchants that share the same Fee Profile are now subject to the fee. --- # Security and Compliance Source: https://docs.finix.com/guides/managing-operations/security-compliance Learn how Finix handles security and your compliance obligations. Finix is PCI Service Provider Level 1 certified and undergoes regular vulnerability scanning and penetration testing. All material findings are documented, reviewed, and remediated within 30 days of discovery. ## Learn more PCI DSS Compliance Learn how Finix helps you validate merchant compliance on an annual basis. Managing PCI Compliance Learn how to comply with the PCI DSS using Finix. Approved MCCs Learn about the sellers and MCCs that are approved to process payments on Finix. Website Requirements Find out what is required on your website to process payments. 1099-K Tax Forms Learn how Finix handles security and your compliance obligations. --- # Managing PCI Compliance Source: https://docs.finix.com/guides/managing-operations/security-compliance/managing-pci-compliance To process payments, users must attest to compliance with PCI DSS within 90 days of merchant approval, and annually thereafter. Users validate compliance by completing a Self-Assessment Questionnaire (SAQ). In this guide, you can learn how to comply with the PCI DSS using Finix. "Users" include any entity that stores, processes, or transmits credit card data. For more information about PCI compliance, see [PCI DSS Compliance](/guides/managing-operations/security-compliance/pci-dss-compliance). ## The PCI compliance lifecycle The PCI compliance lifecycle consists of the following steps: 1. The compliance form is generated and pre-populated with business data. 2. Users review the form to verify the business details. 3. Users provide additional details and submit the form, attesting to its accuracy. 4. After submission, the system marks the form as **signed** and makes a PDF available for download. 5. Compliance forms must be completed within 90 days of onboarding and renewed annually thereafter. Manual uploads of signed forms are not supported. Signing must be completed directly through the [Finix Dashboard](#completing-compliance-forms-using-the-dashboard) or [API](#completing-compliance-forms-using-the-api). ## Understanding compliance forms The following points outline key aspects of compliance forms: - Upon successful onboarding, Finix's API generates the required PCI compliance form pre-filled with your business information. Each Compliance Form is uniquely associated with your account. - Finix will generate a pre-filled SAQ Questionnaire with type `pci_saq_a`. For example, see the following sample [SAQ A form](https://www.pcisecuritystandards.org/documents/PCI-DSS-v3_2_1-SAQ-A.pdf) from the PCI Council. - You must validate PCI compliance by completing the Compliance Form within 90 days of onboarding. - The `due_at` field specifies the deadline for completing the Compliance Form. - Users must attest to a new Compliance Form annually. - A fee is assessed for each 30-day period that the Compliance Form remains overdue. For more information, see our [Avoiding Compliance Overdue Fees](/guides/managing-operations/security-compliance/avoiding-compliance-overdue-fees) guide. ## Completing compliance forms using the Dashboard When a compliance form is overdue, a banner appears on the **Home** page. Compliance Home Banner A [webhook notification](#1-webhook-notification) is sent when Finix creates a Compliance Form. *To complete a compliance form*: 1. In the left navigation, expand **Merchants** and click **Compliance Forms**. - The **Compliance Forms** page loads. The **Forms** tab displays each form's ID, creation date, due date, merchant, application, form type, and state. By default, **Incomplete** and **Overdue** forms are displayed. 2. Click a compliance form to view its details. The details page includes: - **Form Info** - Type, Created On, Due On, and Expires On. - **Business Info** - Business Name, Incorporation Date, Business Address, Business Phone, and Website. - **Attestation** - Attestor Name, Signed date, Unsigned PDF, Signed PDF, IP Address, and User Agent. The **Unsigned PDF** link provides access to the pre-filled form for review. 3. Click **Attest to Form** to complete the compliance form. - A popup appears requesting attestation details. - Complete the required fields and confirm. - The compliance form state updates to **Completed**. To invalidate a compliance form, click **Invalidate Form**: - A confirmation popup appears: *Invalidate Compliance Form? This action cannot be undone.* - Click **Invalidate** to confirm. The compliance form state changes to **Invalid**. ## Completing compliance forms using the API The following section describes the process of using the API to complete a PCI Compliance Form. Alternatively, users can review and complete the form using the [Finix dashboard](#completing-compliance-forms-using-the-dashboard). ### 1. Webhook notification A webhook notification is sent when Finix creates a Compliance Form. Take note of the compliance form ID in the webhook payload. ### 2. Retrieve the unsigned compliance form Using the compliance form ID from the webhook, retrieve the compliance form resource from the [GET /compliance_forms/{compliance_form_id}](/api/compliance-forms/getcomplianceform) endpoint. ```shell curl -i -X GET \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/compliance_forms/cf_uwErNm23TKYNEiqrEdJK59 ``` In the response object, the `files.unsigned_file` property contains the ID of the unsigned compliance form, which can be retrieved and displayed to the user for review. The `state` property indicates the form is `INCOMPLETE`. ```json { "id": "cf_uwErNm23TKYNEiqrEdJK59", "created_at": "2025-07-07T18:05:01.96471Z", "updated_at": "2025-10-16T22:34:05.217688Z", "linked_to": "MUwfZPNW3r4EqLMzwgr6txw4", "linked_type": "MERCHANT", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "type": "PCI_SAQ_A", "version": "2018.10", "valid_from": "2025-09-09T23:17:43.041004Z", "valid_until": "2026-09-09T23:17:43.041005Z", "tags": {}, "pci_saq_a": { "name": "John Smith", "signed_at": "2022-03-18T16:42:55Z", "user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)", "ip_address": "42.1.1.113", "is_accepted": true, "title": "CTO" }, "due_at": "2025-10-05T18:05:01.94105Z", "compliance_form_template": "cft_n6BfvWBVe4iK1HC4n9qN2t", "files": { "unsigned_file": "FILE_uyntoF5Y4LDrMDJtA9ujd6", "signed_file": null }, "state": "INCOMPLETE" } ``` ### 3. Obtaining compliance consent Obtain compliance consent as follows: 1. Provide the user with a link to the unsigned compliance form for review. 2. Verify that the user is the authorized representative of the company. 3. Show the user the required text to obtain consent: > *By submitting this Self-Assessment Questionnaire, I certify that I am an authorized representative of the company and that all the information submitted is true and correct.* 4. The user reviews the unsigned compliance form, submits the self-assessment questionnaire, and attests to its accuracy. Description of image ### 4. Completing the compliance form Once consent is obtained, send a request to the [PUT /compliance_forms/{compliance_form_id}](/api/compliance-forms/updatecomplianceform) endpoint to complete the compliance form, passing the compliance form ID as a path parameter. Include details about the signee's digital signature in the `pci_saq_a` object. Example ```shell curl -i -X PUT \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/compliance_forms/cf_uwErNm23TKYNEiqrEdJK59 \ -H 'Content-Type: application/json' \ -d '{ "pci_saq_a": { "ip_address": "42.1.1.113", "name": "John Smith", "signed_at": "2022-03-18T16:42:55Z", "title": "CTO", "user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)" } }' ``` API Definition In the response object, the `files.signed_file` property contains the ID of the signed compliance form available for download. The `state` property indicates the form is `COMPLETED`. Example ```json { "id": "cf_uwErNm23TKYNEiqrEdJK59", "created_at": "2025-07-07T18:05:01.96471Z", "updated_at": "2025-10-16T22:34:05.217688Z", "linked_to": "MUwfZPNW3r4EqLMzwgr6txw4", "linked_type": "MERCHANT", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "type": "PCI_SAQ_A", "version": "2018.10", "valid_from": "2025-09-09T23:17:43.041004Z", "valid_until": "2026-09-09T23:17:43.041005Z", "tags": {}, "pci_saq_a": { "name": "John Smith", "signed_at": "2022-03-18T16:42:55Z", "user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)", "ip_address": "42.1.1.113", "is_accepted": true, "title": "CTO" }, "due_at": "2025-10-05T18:05:01.94105Z", "compliance_form_template": "cft_n6BfvWBVe4iK1HC4n9qN2t", "files": { "unsigned_file": "FILE_uyntoF5Y4LDrMDJtA9ujd6", "signed_file": "FILE_6U26h97cpuKmxqdE27KZh7" }, "state": "COMPLETED" ``` API Definition ### 5. Downloading the signed compliance form With the ID of the signed compliance form specified in `files.signed_file`, download the signed compliance form by retrieving the file resource from the GET `/files/{file_id}` endpoint. ```shell curl "https://finix.sandbox-payments-api.com/files/FILE_6U26h97cpuKmxqdE27KZh7/download" \ -H "Finix-Version: 2022-02-01" \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda ``` The previous API request returns the binary PDF of the signed compliance form. To stream the file in the browser, add the query parameter `?stream=true` to the URL. This instructs the API to stream the file inline so the client, such as a web browser, can render it directly. To save the file to a local directory, use the `-o` Curl argument (for example, `-o compliance_form.pdf`). ## Avoiding compliance overdue fees To maintain PCI compliance, users must validate compliance annually by completing the SAQ questionnaire. When the `valid_until` date passes, Finix generates a new unsigned Compliance Form with updated `valid_from` and `valid_until` timestamps. See our [Avoiding Compliance Overdue Fees](/guides/managing-operations/security-compliance/avoiding-compliance-overdue-fees) guide for how to avoid overdue fees. --- # PCI DSS Compliance Source: https://docs.finix.com/guides/managing-operations/security-compliance/pci-dss-compliance This guide explains PCI DSS and the different PCI levels. You’ll also learn how Finix helps you validate merchant compliance on an annual basis. The Payment Card Industry Data Security Standards (PCI DSS) is a set of information security standards created and managed by the [Payment Card Industry Security Standards Council](https://www.pcisecuritystandards.org/) (PCI SSC) for organizations that store, process, or transmit credit card data. The major card brands (including Visa, Mastercard, Discover, and American Express) require PCI DSS compliance. Finix helps you and your users validate compliance with PCI DSS by providing the necessary forms and verifying the submitted information. Users can include any entity that stores, processes, or transmits credit card data. ## PCI Levels There are four levels of PCI compliance. If the requirements apply to you or a user, the entity will need to meet that level of PCI DSS compliance before it can process payments. | PCI Level | Applies to | | --- | --- | | PCI Level 1 | Users that process over 6 million *card* transactions annually through all channels and regions. (card-present, ecommerce, etc). | | PCI Level 2 | Users that process between 1 to 6 million *card* transactions annually through all channels and regions. (card-present, ecommerce, etc). | | PCI Level 3 | Users that process between 20,000 to 1 million *card* transactions annually online (ecommerce only). | | PCI Level 4 | Users that process less than 20,000 *card* transactions online (ecommerce only) annually.Users that process up to 1 million *card* transactions annually through all channels and regions. (card-present, ecommerce, etc). | Finix is certified as a Level 1 Payment Card Industry Data Security Standards (PCI DSS) compliant Service Provider. ## Validating PCI DSS compliance Every one of your sellers eligible to process payments is required to validate compliance with PCI DSS annually. Sellers can validate compliance by completing and attesting to a Self Assessment Questionnaire (SAQ). Self-Assessment Questionnaires (SAQs) are validation tools to aid entities in self-evaluating their compliance with PCI DSS. For PCI Levels 2-4, there are different [SAQ types](https://listings.pcisecuritystandards.org/documents/Understanding_SAQs_PCI_DSS_v3.pdf) based on the manner of your payment integration. | Self-Assessment Questionnaire (SAQ) | Applies to | | --- | --- | | A | Card-not-present merchants that have fully outsourced all cardholder data functions to PCI DSS validated third party service providers with no electronic storage, processing, or transmission of any cardholder data on the merchant’s systems or premises. | | A-EP | E-commerce merchants who outsource all payment processing to PCI DSS validated third parties, and who have a website(s) that doesn’t directly receive cardholder data but that can impact the security of the payment transaction.No electronic storage, processing, or transmission of any cardholder data on the merchant’s systems or premises. | | B | Sellers using only: Imprint machines with no electronic cardholder data storage; and/or.Standalone, dial-out terminals with no electronic cardholder data storage. | | B-IP | Sellers using only standalone, PTS-approved payment terminals with an IP connection | | C-VT | Merchants who manually enter a single transaction at a time via a keyboard into an Internet-based virtual terminal solution that is provided and hosted by a PCI DSS validated third-party service provider. | | C | Merchants with payment application systems connected to the Internet, no electronic cardholder data storage. | | P2PE | Merchants using only hardware payment terminals that are included in and managed via a validated, PCI SSC-listed P2PE solution. With no electronic cardholder data storage. | | D | SAQ D for Merchants: All merchants not included in descriptions for the above SAQ types.SAQ D for Service Providers: All service providers defined by a payment brand as eligible to complete a SAQ. | Each PCI DSS Self-Assessment Questionnaire comprises the following: - Questions associated with the PCI DSS requirements that are appropriate for your cardholder data environment (CDE). - Attestation of Compliance: The attestation contains your declaration of eligibility for completing the applicable SAQ and the results of a self-assessment requirements under PCI DSS. Finix will evaluate your method of payment integration to help alleviate some of the PCI compliance burden. Finix takes care of the heavy lifting and creates the SAQ compliance forms your sellers need to complete. Finix pre-fills some information based on the information collected from you as part of the implementation process. For many organizations, this helps save many hours of auditing and compliance checks. Finix also actively monitors PCI compliance on an ongoing basis and will notify you in advance of any compliance validation issues or changes. For information on how you and your sellers can validate compliance with PCI DSS, see [Managing PCI Compliance](/guides/managing-operations/security-compliance/managing-pci-compliance). ## Additional materials Additional articles and materials are also available to help you understand the Payment Card Industry Data Security Standards: - [Everything You Need to Know About PCI Compliance](https://finix.com/resources/blogs/everything-you-need-to-know-about-pci-compliance) - PCI Security Standards Council articles: - [Merchant Resources](https://www.pcisecuritystandards.org/merchants/) - [SAQ Instructions & Guidelines](https://docs-prv.pcisecuritystandards.org/SAQ%20(Assessment)/Instructions%20%26%20Guidance/SAQ-InstrGuidelines-v3-2-1-r1.pdf) - [Best Practice for Securing E-commerce](https://listings.pcisecuritystandards.org/pdfs/best_practices_securing_ecommerce.pdf?agreement=true&time=1565342137625) - [Common Payment Systems](https://listings.pcisecuritystandards.org/pdfs/Small_Merchant_Common_Payment_Systems.pdf) ### PCI SSC glossary and resources | Abbreviation | Name | Definition | | --- | --- | --- | | AOC | [Attestation of Compliance](https://www.pcisecuritystandards.org/document_library/?category=saqs&subcategory=saqs_saq_aoc) | A document to complete as a declaration of the results reflected in an associated Self-Assessment Questionnaire (SAQ). | | ASV | [Approved Scanning Vendor](https://listings.pcisecuritystandards.org/assessors_and_solutions/approved_scanning_vendors) | An organization with a scan solution that is tested and approved by the PCI SSC to conduct external vulnerability scanning adhering to PCI DSS Requirement 11.2.2. | | CDE | [Cardholder Data Environment](https://www.pcisecuritystandards.org/glossary/#glossary-c) | The people, processes and technology that store, process, or transmit cardholder data. | | CHD | [Cardholder Data](https://www.pcisecuritystandards.org/glossary/#glossary-c) | At minimum, cardholder data consists of the full PAN (Primary Account Number), and may also include: cardholder name, expiration date and/or service code. | | PAN | [Primary Account Number](https://www.pcisecuritystandards.org/glossary/#glossary-p) | Also referred to as the account number and is a unique payment card number that identifies the issuer and the particular cardholder account. | | PCI DSS | [Payment Card Industry Data Security Standards](https://www.pcisecuritystandards.org/document_library/?category=pcidss&document=pci_dss) | Document Library | | PCI SSC | [Payment Card Industry Security Standards Council](https://www.pcisecuritystandards.org/) | PCI DSS Help Site | | PTS | [PIN Transaction Security](https://listings.pcisecuritystandards.org/assessors_and_solutions/pin_transaction_devices?agree=true) | PTS is a set of modular evaluation requirements managed by the PCI SSC for PIN acceptance Point-of-Interaction terminals. | | QSA | [Qualified Security Assessor](https://listings.pcisecuritystandards.org/assessors_and_solutions/qualified_security_assessors) | An independent security organization that has been qualified by the PCI SSC to validate an entity’s adherence to PCI DSS. A QSA employee is an individual who is employed by a QSA company and has satisfied all QSA requirements. | | RoC | [Report on Compliance](https://docs-prv.pcisecuritystandards.org/PCI%20DSS/Reporting%20Template%20or%20Form/PCI-DSS-v4-0-ROC-Template-r1.pdf) | The ROC provides details about an entity’s environment and assessment methodology, and documents the entity’ compliance status for each PCI DSS requirement. | | SAD | [Sensitive Authentication Data](https://www.pcisecuritystandards.org/glossary/#glossary-s) | Security-related information used to authenticate cardholders and/or authorize card transactions (may include card validation codes/values - CVS/CVV, PINs, full track data from the magnetic stripe or equivalent on a chip). | | SAQ | [Self-Assessment Questionnaire](https://www.pcisecuritystandards.org/document_library/?category=saqs#results) | A validation tool intended to aid merchants and service providers in self-evaluating their compliance with PCI DSS. | | | Service Provider | Business entity that is not a payment brand, directly involved in the processing, storage, or transmission of cardholder data on behalf of another entity. | --- # Website Requirements Source: https://docs.finix.com/guides/managing-operations/security-compliance/website-requirements Find out what is required on your website to process payments. To process payments, Finix follows regulations set by Visa’s Global Brand Protection Program (GBPP) and Mastercard’s Business Risk Assessment and Mitigation (BRAM) program. The regulations for Mastercard’s BRAM and Visa’s GBPP are designed to protect the card brands and customers from illegal and brand-damaging activity. Under BRAM and GBPP, the card brands impose fines for processing any activity that's illegal, fraudulent, or poses a regulatory or reputational risk. Finix conducts regular scans of onboarded merchants and platforms to verify compliance with the BRAM and GBPP guidelines. Examples of activities that can incur fines include: - The illegal sale of prescription drugs or counterfeit merchandise. - Illegal gambling. - Banned pornography. This list includes examples of the role the card brands play in keeping the payments ecosystem safe under BRAM and GBPP. To enable processing payments with Finix, and comply with the BRAM and GBPP requirements, your website must follow these rules: ## Return, Refund, and cancellation policies Your return, refund, and cancellation policies are easily available and disclosed to customers. ## Customer service - Content is available for customers that details the support experience. This must include: - The different ways to contact customer support. (e.g email addresses, phone numbers, chat, etc.) - What kind of support is offered. (live person, automated, online support, etc.) - The following contact info displays during the checkout process: - Support email and/or telephone number. - Business address including country. ## Terms and conditions - Terms and conditions must be available for customers online. - Customers must agree to your terms and conditions before you can process any of their information. ## Promotions and trial periods - The conditions of any promotion, discount, or trial are displayed and easily available for customers. - Trial periods must include: - A cancellation policy that customers can easily find and follow. - A clear disclosure that tells customers they will be charged unless they cancel before the trial period ends. - The date or period of time after which charges will begin. - Steps the customer can take to cancel the transaction before the end of the trial period. - Clear instructions explaining the steps for returning products and obtaining refunds. - Email notifications to customers, shortly before the trial period ends, explaining their card will be charged unless they cancel the trial. ## Required policies Content is available for customers that helps them understand your different policies. This includes your: | Policy | Description | | --- | --- | | Cancellation policy | Explain how customers can cancel subscriptions or reservations. | | Consumer data privacy policy | Explain how you protect the data of your customers. | | Delivery policy | Detail how and where products are shipped and under what timeline. | | Privacy policy | Detail your website’s privacy policy and how the data of your customers is protected, used, or disclosed. | | Refund policy | Explain how customers can receive a refund. | | Return policy | Explain how customers can return purchased goods. | | Security capabilities and policy on transmitting payment details | Detail when you transmit payment info and how you protect that data. | ## Additional website requirements - Descriptions of all the goods or services offered. - An explanation of legal restrictions. (if known) - The transaction currency. (e.g., U.S. dollars, Canadian dollars) - An explanation of any restrictions on exporting data. (if known) - Visa's logo in full color to let customers know Visa is accepted. - Details on how to display Visa's logo can be found in the Visa Product Brand Standards and [Visa's POS guidelines](https://usa.visa.com/run-your-business/accept-visa-payments/posguidelines.html). --- # Platform Payments Source: https://docs.finix.com/guides/platform-payments Learn how to accept payments for your buyers and sellers. Seller Payouts Hero Platforms facilitate payments between sellers and buyers. For example, software companies manage transactions on behalf of their merchants and end-customers. With Finix, you can easily onboard your sellers to start processing their payments and payouts. Use Finix's online and in-person payment solutions to let your sellers accept payments from their buyers. Whether you are a software company or marketplace, Finix can manage your end-to-end payments solution. Platform Quickstart Get started with the Platform Quickstart ## Platform models Finix supports multiple types of platforms. Your integration will depend on which type of platform you are. | Features | Software Companies | Payment Facilitators | Marketplaces | | --- | --- | --- | --- | | Buyer interaction | With your sellers | With your sellers | Directly with you | | Online payments | | | | | In-person payments | | | | | Sub-merchant payouts | | | | ## Learn more Onboarding Sellers Onboard your sellers to start processing their payments Processing Payments Learn the basics about using Finix for your platform's payments Paying Sellers Manage your sellers' payouts using Finix's variety of payout options --- # Managing White-Labeled Seller Dashboards Source: https://docs.finix.com/guides/platform-payments/managing-seller-dashboards White-labeled seller dashboards give your sellers a scoped view of their own account — letting them track payments, manage transactions, and handle day-to-day operations independently, without access to platform-level data or other merchants. ## Customizing the Dashboard You can customize the seller dashboard with your logo, brand colors, onboarding forms, email invites, and a branded subdomain. For full configuration details, see [White-Labeling The Finix Dashboard](/guides/managing-operations/finix-dashboard/white-labeling-finix-dashboard). You can pair seller dashboards with our [white-labeled no-code/low-code products](/low-code-no-code/manage-low-code-no-code/low-code-branding) to deliver a fully white-labeled payment experience. ## Adding Sellers to the Dashboard You can invite sellers to access their white-labeled dashboard directly from your Dashboard. For step-by-step instructions on navigating to the merchant account, accessing team settings, and adding team members, see [Managing Team Members](/guides/managing-operations/managing-team-members/). ### Merchant Dashboard experience After accepting the invitation, the merchant will have access to their own Finix Dashboard. - The layout and navigation are similar to the platform's dashboard - Data and functionality are limited to the seller merchant’s own account - Seller merchants cannot view or access other merchants or platform level settings Merchant Dashboard --- # Platform Checklist Source: https://docs.finix.com/guides/platform-payments/platform-checklist Use this checklist to ensure a smooth transition when taking your platform live with Finix. The following are the key aspects platforms need to integrate with to go live with Finix. Completing this checklist ensures your platform is complete and transactions will be processed successfully. Platforms include the [following experiences](/guides/getting-started/finix-sign-up/#step-2-build-your-finix-integration): - Finix for Software Platforms - Finix for Marketplaces - Finix for PayFacs Taking your platform live largely depends on the payment experience you plan to build and the engineering resources you have available. Finix for Business users can refer to our [Integration Checklist](/additional-resources/developers/implementation-and-testing/integration-checklist) for details on how to build an integration with Finix. We recommend reviewing our documentation and defining your payment experience before going live. (e.g. will you accept Apple Pay, how will you be alerted about disputes, when will sellers receive payouts, etc.) When you're ready to go live, [let us know](mailto:support@finix.com) and our team will review your platform for live payment processing. ## Account and login - [Create your sandbox account with Finix.](/guides/getting-started) - Log in and gain access to the Finix Dashboard. - [Understand Finix's account structure and find your `Application#id`.](/additional-resources/developers/resources-and-payment-flows/key-resources#applications) Once you've gained access to the Finix Dashboard, it's ***essential*** to [create API Keys](/additional-resources/developers/authentication-and-api-basics/api-keys) for your developers so they can begin integrating your platform with Finix. ### Migration If you're actively processing payments or have done so in the past, you can migrate data over to Finix to ensure no gaps in availability or billing comes up. For more details, see [Migrating Data with Finix](/additional-resources/developers/migrating-data-to-finix). ## Onboarding You need to be able to [onboard](/guides/platform-payments/onboarding-sellers) the sellers and service providers you sign onto Finix. This includes handling failure flows and [onboarding rejections](/guides/platform-payments/onboarding-sellers/seller-rejections): - Learn how to [onboard sellers](/guides/platform-payments/onboarding-sellers/seller-onboarding-process) - Depending on the onboarding experience you want to build, you need to follow either our: - [Onboarding Forms - Checklist](#onboarding-forms) - [Onboarding With the Finix API - Checklist](#onboarding-with-the-finix-api) ### Onboarding Forms **[Onboarding Forms](/guides/platform-payments/onboarding-sellers/seller-onboarding-forms/)** manages the collection of seller information and the creation of API resources that get manipulated to move funds. Your platform needs to be able to onboard sellers using the form Finix provides and handle any onboarding rejections that come up. - [Create an `Onboarding Form`.](/guides/platform-payments/onboarding-sellers/seller-onboarding-forms#creating-onboarding-forms) - [Redirect users to the onboarding form.](/guides/platform-payments/onboarding-sellers/seller-onboarding-forms/#step-2-redirecting-sellers) - [Retrieve the created `Identity`, `Merchant` , `Payment Instrument`.](/guides/platform-payments/onboarding-sellers/seller-onboarding-forms/#step-3-retrieve-the-created-resources) - [Handle any onboarding rejections.](/guides/platform-payments/onboarding-sellers/seller-rejections) - [Upload files](/guides/platform-payments/onboarding-sellers/seller-onboarding-uploading-files) as needed to appeal any onboarding rejections. ### Onboarding with the Finix API [Onboarding with the Finix API](/guides/platform-payments/onboarding-sellers/seller-onboarding-via-api) means your platform handles every aspect of onboarding sellers. - [Create an `Identity` for your seller.](/guides/platform-payments/onboarding-sellers/seller-onboarding-via-api#step-2-create-an-identity) - [Create associated `Identities` as needed for additional owners or control persons.](/guides/platform-payments/onboarding-sellers/seller-onboarding-via-api/#step-3-add-associated-identities) - [Tokenize the seller's bank account](/guides/platform-payments/onboarding-sellers/seller-onboarding-via-api#step-4-add-a-bank-account) - [Onboard the seller by creating a `Merchant` .](/guides/platform-payments/onboarding-sellers/seller-onboarding-via-api#step-5-verify-the-seller) - [Handle any onboarding rejections.](/guides/platform-payments/onboarding-sellers/seller-rejections) - [Upload files](/guides/platform-payments/onboarding-sellers/seller-onboarding-uploading-files) as needed to appeal any onboarding rejections. ## Process Payments Any platform that goes live needs to be able to [process payments](/guides/getting-started/developer-quickstart). Depending on the payment methods you want to accept, your platform will need to handle these different flows: - [Card](#card-payments) - [Apple Pay](#apple-pay-payments) - [Google Pay](#google-pay-payments) - [ACH (eCheck)](#ach-echeck-payments) All platforms also need to handle the following: - [Refunding a payment.](/guides/after-the-payment/refunds) - [Manage Disputes.](/guides/after-the-payment/disputes/) ### Card Payments Your platform needs to handle the following to process transactions where the buyer pays with a card: - [Create an `Identity` for the buyer.](/guides/getting-started/developer-quickstart#step-1-create-an-identity-for-your-buyer) - [Tokenize the buyer's card details using our Tokenization Forms.](/guides/online-payments/payment-tokenization/tokenization-forms) - Process the payment by [creating a `Transfer`.](/guides/getting-started/developer-quickstart#step-3-make-a-payment) - Alternatively, [create and capture an `Authorization`.](/guides/online-payments/payment-features/auth-and-captures/) - [Handle payments that fail and their related `failure_code`.](/additional-resources/developers/implementation-and-testing/error-codes/#transfer-and-authorization-errors) #### Raw card Payments If you're fully [PCI DSS compliant](/guides/managing-operations/security-compliance/pci-dss-compliance) and want to handle raw card data: - [Tokenize card details using Raw Card data.](/guides/online-payments/payment-tokenization/handling-raw-card-data) ### Apple Pay Payments To support Apple Pay, your platform needs to process an [Apple Pay transaction](/guides/online-payments/digital-wallets/apple-pay/) with either: - [Apple Pay on iOS](/guides/online-payments/digital-wallets/apple-pay/apple-pay-on-ios) - [Apple Pay on Web](/guides/online-payments/digital-wallets/apple-pay/apple-pay-on-web) ### Google Pay Payments To support Google Pay, your platform needs to process a [Google Pay transaction](/guides/online-payments/digital-wallets/google-pay) with either: - [Google Pay on Android](/guides/online-payments/digital-wallets/google-pay/google-pay-on-android) - [Google Pay on Web](/guides/online-payments/digital-wallets/google-pay/google-pay-on-web) ### ACH (eCheck) Payments Successfully process an [ACH (eCheck) Payment](/guides/online-payments/bank-payments/ach-direct-debits/) where the buyer pays with their bank account details. ## Payout and fee collection Your platform needs to be able to [payout sellers](/guides/platform-payments/seller-payouts) and [collect fees](/guides/platform-payments/monetizing-payments/collecting-seller-fees): - [Understand how `Settlements` and payouts work in Finix.](/guides/payouts) - [Display the history of `Settlements` and payouts to sellers.](/guides/payouts) ## Technical considerations A complete technical integration includes the following: - [Set up Webhooks](/additional-resources/developers/webhooks) to receive updates about changes in your payment activity. - [Authenticate Webhooks](/additional-resources/developers/webhooks/integrating-into-webhooks#creating-authenticated-webhooks) - [Manage Webhooks using the Webhook Log](/additional-resources/developers/webhooks/integrating-into-webhooks#managing-webhooks-via-dashboard) --- # Platform Quickstart Source: https://docs.finix.com/guides/platform-payments/platform-quickstart ## Before you start To start, create your Finix sandbox account to access the Finix Dashboard and create an API Key. You can use your sandbox account to build and test your integration into Finix's APIs, as well as use the Finix Dashboard to manage payments, sellers, and more. To create an API Key in the Dashboard, navigate to **Developer > Create API Key**. Save your username and password on your computer; you won't be able to access the same credentials after closing the window. ## Step 1: Onboard your Seller ### Create an Identity - The first step to processing your sellers' payments is creating an Identity with your seller's information - You will create 1 Identity your seller, and 1 Identity for each beneficial owner with more than 25% ownership (if applicable) USA Seller Seller (USA) ```json Seller (USA) { "id": "IDfC3Z9xVrniLsE6Hk4Zqhjv", "created_at": "2026-09-30T00:02:15.54Z", "updated_at": "2026-09-30T00:02:15.54Z", "additional_underwriting_data": { // [!code highlight] "refund_policy": "MERCHANDISE_EXCHANGE_ONLY", "credit_check_ip_address": "42.1.1.112", "card_volume_distribution": { "card_present_percentage": 30, "ecommerce_percentage": 60, "mail_order_telephone_order_percentage": 10 }, "average_ach_transfer_amount": 200000, "average_card_transfer_amount": 200000, "merchant_agreement_accepted": true, "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)", "annual_card_volume": 12000000, "merchant_agreement_ip_address": "42.1.1.113", "annual_ach_volume": 200000, "credit_check_allowed": true, "business_description": "SB3 vegan cafe", "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10_14_6)", "volume_distribution_by_business_type": { "business_to_business_volume_percentage": 100, "business_to_consumer_volume_percentage": 0, "consumer_to_consumer_volume_percentage": 0, "other_volume_percentage": 0, "person_to_person_volume_percentage": 0 }, "credit_check_timestamp": "2021-04-28T16:42:55Z", "merchant_agreement_timestamp": "2021-04-28T16:42:55Z" }, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "entity": { "ach_max_transaction_amount": 1000000, "amex_mid": null, "annual_card_volume": 12000000, "business_address": { "line1": "741 Douglass St", "line2": "Apartment 8", "city": "San Mateo", "region": "CA", "postal_code": "94114", "country": "USA" }, "business_name": "Finix Flowers", "business_phone": "+1 (408) 756-4497", "business_tax_id_fingerprint": "business_tax_fpr_tukGF2uSeRPcXqS2B1ngPQ", "business_tax_id_provided": true, "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP", "default_statement_descriptor": "Finix Flowers", "discover_mid": null, "dob": { "day": 27, "month": 6, "year": 1978 }, "doing_business_as": "Finix Flowers", "email": "user@example.org", "first_name": "John", "has_accepted_credit_cards_previously": true, "incorporation_date": { "day": 27, "month": 6, "year": 1978 }, "last_name": "Smith", "max_transaction_amount": 1000000, "mcc": "4900", "ownership_type": "PRIVATE", "personal_address": { "line1": "741 Douglass St", "line2": "Apartment 7", "city": "San Mateo", "region": "CA", "postal_code": "94114", "country": "USA" }, "phone": "14158885080", "principal_percentage_ownership": 50, "short_business_name": null, "tax_authority": null, "tax_id_fingerprint": "tax_fpr_tukGF2uSeRPcXqS2B1ngPQ", "tax_id_provided": true, "title": "CEO", "url": "https://www.finix.com" }, "identity_roles": [ "SELLER" ], "tags": { "Studio Rating": "4.7" }, "type": "BUSINESS", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDfC3Z9xVrniLsE6Hk4Zqhjv" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDfC3Z9xVrniLsE6Hk4Zqhjv/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDfC3Z9xVrniLsE6Hk4Zqhjv/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDfC3Z9xVrniLsE6Hk4Zqhjv/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDfC3Z9xVrniLsE6Hk4Zqhjv/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDfC3Z9xVrniLsE6Hk4Zqhjv/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDfC3Z9xVrniLsE6Hk4Zqhjv/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDfC3Z9xVrniLsE6Hk4Zqhjv/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDfC3Z9xVrniLsE6Hk4Zqhjv/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ``` Canadian Seller Seller (CAN) ```json Seller (CAN) { "id": "IDheUNDYiYUNnR2CMCjYJdyK", "created_at": "2026-09-25T20:05:12.11Z", "updated_at": "2026-09-25T20:05:12.11Z", "additional_underwriting_data": { "refund_policy": "MERCHANDISE_EXCHANGE_ONLY", "credit_check_ip_address": "42.1.1.112", "card_volume_distribution": { "card_present_percentage": 30, "ecommerce_percentage": 60, "mail_order_telephone_order_percentage": 10 }, "average_card_transfer_amount": 200000, "merchant_agreement_accepted": true, "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)", "annual_card_volume": 12000000, "merchant_agreement_ip_address": "42.1.1.113", "credit_check_allowed": true, "business_description": "Business offering video editing services.", "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10_14_6)", "volume_distribution_by_business_type": { "business_to_business_volume_percentage": 100, "business_to_consumer_volume_percentage": 0, "consumer_to_consumer_volume_percentage": 0, "other_volume_percentage": 0, "person_to_person_volume_percentage": 0 }, "credit_check_timestamp": "2021-04-28T16:42:55Z", "merchant_agreement_timestamp": "2021-04-28T16:42:55Z" }, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "entity": { "ach_max_transaction_amount": 1000000, "amex_mid": null, "annual_card_volume": 12000000, "business_address": { "line1": "456 Elm Avenue", "line2": null, "city": "Vancouver", "region": "BC", "postal_code": "V6B 2L2", "country": "CAN" // [!code highlight] }, "business_name": "Video Editing Services", "business_phone": "+1 (416) 555-7890", "business_tax_id_fingerprint": "business_tax_fpr_tukGF2uSeRPcXqS2B1ngPQ", "business_tax_id_provided": true, "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP", "default_statement_descriptor": "Video Services", "discover_mid": null, "dob": { "day": 27, "month": 6, "year": 1978 }, "doing_business_as": "Video Editing Services", "email": "info@video-editing-services.com", "first_name": "Jerry", "has_accepted_credit_cards_previously": true, "incorporation_date": { "day": 27, "month": 6, "year": 1978 }, "last_name": "Dunhill", "max_transaction_amount": 1000000, "mcc": "4900", "ownership_type": "PRIVATE", "personal_address": { "line1": "987 Milo Street", "line2": null, "city": "Vancouver", "region": "BC", "postal_code": "V5K 1Z5", "country": "CAN" }, "phone": "14158885080", "principal_percentage_ownership": 50, "short_business_name": null, "tax_authority": null, "tax_id_fingerprint": "tax_fpr_tukGF2uSeRPcXqS2B1ngPQ", "tax_id_provided": true, "title": "CEO", "url": "https://www.video-editing-services.com" }, "identity_roles": [ "SELLER" ], "tags": { "Studio Rating": "4.7" }, "type": "BUSINESS", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDheUNDYiYUNnR2CMCjYJdyK" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDheUNDYiYUNnR2CMCjYJdyK/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDheUNDYiYUNnR2CMCjYJdyK/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDheUNDYiYUNnR2CMCjYJdyK/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDheUNDYiYUNnR2CMCjYJdyK/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDheUNDYiYUNnR2CMCjYJdyK/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDheUNDYiYUNnR2CMCjYJdyK/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDheUNDYiYUNnR2CMCjYJdyK/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDheUNDYiYUNnR2CMCjYJdyK/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ``` ### Create a Payment Instrument - Next, you will link the bank account to which your seller will receive their settlement payouts - To do this, you will create a Payment Instrument linked to the Identity ID from the previous step Note on Payment Instruments Payment Instrument resources represent the payment details of cards or bank accounts. Tokenizing the same card or bank account multiple times will create multiple unique Payment Instruments, each with the same `fingerprint`. Each Payment Instrument is associated with one single Identity; once a Payment Instrument is created, the Identity it is associated with cannot be changed. USA Bank Account Payment Instrument - Bank Account ```json Payment Instrument - Bank Account { "id": "PI68E8eKh1v4P2eY2PoLrzzT", "created_at": "2026-09-25T20:05:25.37Z", "updated_at": "2026-09-25T20:05:25.37Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRxpMNPZbZqVQfcHzRUJnzkR", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "BANK_ACCOUNT", // [!code highlight] "microdeposit": "microdeposit_g92m9YHXhhndZcmFAUW7Ki", "microdeposit_verification_url": "https://link.sandbox-payment-form.com/DKDrmq", "account_type": "BUSINESS_CHECKING", "bank_account_validation_check": "NOT_ATTEMPTED", "bank_code": "122105278", "country": "USA", "institution_number": null, "masked_account_number": "XXXXXX0019", "name": "Smith & Associates Consulting", "transit_number": null, "tags": {}, "third_party": null, "third_party_token": null, "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` Canadian Bank Account Payment Instrument - Canadian Bank Account ```json Payment Instrument - Canadian Bank Account { "id": "PIeHxmfnj5PzqF4JGtbf2Y2m", "created_at": "2026-09-25T20:05:27.04Z", "updated_at": "2026-09-25T20:05:27.04Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "CAD", // [!code highlight] "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPR8RAHfXm1BMYYVJyHWHhw4J", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "BANK_ACCOUNT", "account_type": "PERSONAL_CHECKING", "bank_account_validation_check": "NOT_ATTEMPTED", "bank_code": null, "country": "CAN", // [!code highlight] "institution_number": "123", "masked_account_number": "XXXXX3123", "name": "John Doe", "transit_number": "12345", "tags": {}, "third_party": null, "third_party_token": null, "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIeHxmfnj5PzqF4JGtbf2Y2m" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIeHxmfnj5PzqF4JGtbf2Y2m/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIeHxmfnj5PzqF4JGtbf2Y2m/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIeHxmfnj5PzqF4JGtbf2Y2m/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` ### Create a Merchant - Finally, you will create your seller's Merchant account - This is the resource you will use to process your seller's payments - The Merchant account will be ready to process payments once `APPROVED` Merchant States Your Merchant's `onboarding_state` can be `PROVISIONING`, `APPROVED`, `REJECTED`, or `UPDATE_REQUESTED`. We recommend integrating into our webhooks to listen for any Merchant state changes. Example API Definition Example Merchant ```json Merchant { "id": "MU9hcmnx5cWZUmRFKRqHnKc8", "created_at": "2026-09-30T00:02:18.62Z", "updated_at": "2026-09-30T00:02:18.62Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "card_cvv_required": false, "card_expiration_date_required": true, "card_network_details": null, "convenience_charges_enabled": false, "country": "USA", "creating_transfer_from_report_enabled": false, "currencies": [ "USD" ], "default_partial_authorization_enabled": false, "disbursements_ach_pull_enabled": true, "disbursements_ach_push_enabled": true, "disbursements_card_pull_enabled": true, "disbursements_card_push_enabled": true, "disbursements_same_day_ach_pull_enabled": false, "disbursements_same_day_ach_push_enabled": false, "fee_ready_to_settle_upon": "PROCESSOR_WINDOW", "first_approved_at": null, "gateway": null, "gross_settlement_enabled": false, "identity": "IDxmXmkWTmyipx5DdwbYFWP2", "instant_payouts_card_push_enabled": false, "is_terminated": false, "level_two_level_three_data_enabled": false, "loan_repayment": null, "mcc": "4900", "merchant_name": "Finix Flowers", "merchant_profile": "MPtAYYmX7of1MYkqKH9GBYAm", "microdeposit_verification_required_buyer": true, "microdeposit_verification_required_sender": false, "mid": null, "onboarding_state": "PROVISIONING", "pending_refunds_strategy": "SAME_DAY_ADJUSTMENT", "processing_enabled": false, "processor": "DUMMY_V1", "processor_details": {}, "ready_to_settle_upon": "PROCESSOR_WINDOW", "ready_to_settle_upon_delay_alignment": "NONE", "refunds_disabled": false, "rent_surcharges_enabled": false, "settlement_enabled": false, "settlement_funding_identifier": "UNSET", "settlement_queue_mode": "UNSET", "surcharges_enabled": false, "tags": { "order_id": "ORD-123" }, "termination_details": null, "unreferenced_refund_card_present_enabled": true, "unreferenced_refund_manual_entry_enabled": false, "verification": "VIpfHm3CLqD77hCUqCKeiF", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/merchants/MU9hcmnx5cWZUmRFKRqHnKc8" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDxmXmkWTmyipx5DdwbYFWP2" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/merchants/MU9hcmnx5cWZUmRFKRqHnKc8/verifications" }, "merchant_profile": { "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPtAYYmX7of1MYkqKH9GBYAm" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "verification": { "href": "https://finix.sandbox-payments-api.com/verifications/VIpfHm3CLqD77hCUqCKeiF" } } } ``` API Definition ## Step 2: Create your Buyer ### Create an Identity - The next step is creating an Identity for your buyer - This resource represents the customer to which your seller makes a sale - All buyer Identity fields are optional, but Finix recommends passing in the name and email to help with accounting, reconciliation, and disputes Example API Definition Example Buyer ```json Buyer { "id": "IDm1QmqySG8YQUth47dj2sV5", "created_at": "2026-09-25T20:05:10.29Z", "updated_at": "2026-09-25T20:05:10.29Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "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_fingerprint": null, "business_tax_id_provided": false, "business_type": null, "default_statement_descriptor": null, "discover_mid": null, "dob": null, "doing_business_as": null, "email": "johnsmithbuyer@gmail.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": "7147148784", "principal_percentage_ownership": null, "short_business_name": null, "tax_authority": null, "tax_id_fingerprint": null, "tax_id_provided": false, "title": null, "url": null }, "identity_roles": [ // [!code highlight] "BUYER" ], "tags": {}, "type": "PERSONAL", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDm1QmqySG8YQUth47dj2sV5/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ``` API Definition ### Create a Payment Instrument - Next, create a Payment Instrument to represent the payment card or bank account your buyer will use for the sale - PCI Level 1-compliant organizations can collect and pass in sensitive payment data directly - Organizations that are *not* PCI Level 1-compliant *must* use Finix's Tokenization Forms or Mobile Tokenization to collect and pass in sensitive payment data PCI Level 1 Compliance Please reach out to your Finix point-of-contact should you have any questions about PCI Level 1 Compliance. Payment Card Payment Instrument - Card ```json Payment Instrument - Card { "id": "PImZV8WukUEgB8iFqoSouLt1", "created_at": "2026-09-25T20:05:27.37Z", "updated_at": "2026-09-25T20:05:27.37Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "PAYMENT_CARD", // [!code highlight] "account_updater_enabled": false, "address": { "line1": "900 Metro Center Blv", "line2": null, "city": "San Francisco", "region": "CA", "postal_code": "94404", "country": "USA" }, "address_verification": "UNKNOWN", "bin": "520082", "brand": "MASTERCARD", "card_type": "DEBIT", "expiration_month": 12, "expiration_year": 2029, "issuer_country": "NON_USA", "last_four": "8210", "name": "John Doe", "network_token_enabled": false, "network_token_state": "NOT_ENABLED", "security_code_verification": "UNKNOWN", "tags": {}, "third_party": null, "third_party_token": null, "type": "PAYMENT_CARD", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" }, "updates": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/updates" } } } ``` Bank Account Payment Instrument - Bank Account ```json Payment Instrument - Bank Account { "id": "PI68E8eKh1v4P2eY2PoLrzzT", "created_at": "2026-09-25T20:05:25.37Z", "updated_at": "2026-09-25T20:05:25.37Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRxpMNPZbZqVQfcHzRUJnzkR", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "BANK_ACCOUNT", // [!code highlight] "microdeposit": "microdeposit_g92m9YHXhhndZcmFAUW7Ki", "microdeposit_verification_url": "https://link.sandbox-payment-form.com/DKDrmq", "account_type": "BUSINESS_CHECKING", "bank_account_validation_check": "NOT_ATTEMPTED", "bank_code": "122105278", "country": "USA", "institution_number": null, "masked_account_number": "XXXXXX0019", "name": "Smith & Associates Consulting", "transit_number": null, "tags": {}, "third_party": null, "third_party_token": null, "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` Token Payment Instrument - Token - Card ```json Payment Instrument - Token - Card { "id": "PImmCg3Po7oNi7jaZcXhfkEu", "created_at": "2022-10-10T05:32:17.78Z", "updated_at": "2022-10-10T05:32:17.78Z", "account_updater_enabled": false, "application": "APgPDQrLD52TYvqazjHJJchM", "created_via": "API", "currency": "USD", "enabled": true, "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY", "identity": "IDjvxGeXBLKH1V9YnWm1CS4n", "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": "520082", "brand": "MASTERCARD", "card_type": "DEBIT", "expiration_month": 12, "expiration_year": 2029, "issuer_country": "USA", "last_four": "8210", "name": "Amy White", "network_token_enabled": false, "network_token_state": "NOT_ENABLED", "security_code_verification": "UNKNOWN", "tags": { "card_name": "Business Card" }, "type": "PAYMENT_CARD", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDjvxGeXBLKH1V9YnWm1CS4n" }, "updates": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/updates" } } } ``` ## Step 3: Make a Sale ### Create a Transfer - With your seller and buyer created, you are ready to make a sale - To do this, create a Transfer with your Buyer's Payment Instrument as the `source` and your Seller's Merchant ID as the `merchant` - Alternatively, you can use an authorization-and-capture flow by creating and capturing an Authorization Transfer Amount Note that the Transfer's `amount` is represented in cents. Transfer - USA Transfer - USA ```json Transfer - USA { "id": "TRgQBFEUahEyLZ6zvu3hrqNJ", "created_at": "2026-09-25T20:05:48.72Z", "updated_at": "2026-09-25T20:05:48.72Z", "3d_secure_session": null, "additional_buyer_charges": { "convenience_amount": 150, "surcharge_amount": 0, "rent_surcharge_amount": 0 }, "additional_healthcare_data": null, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": { "customer_reference_number": "321xyz", "customs_duty_amount": 10, "destination_country_code": null, "destination_postal_code": null, "discount_amount": 100, "invoice_reference_number": null, "order_date": null, "sales_tax": null, "sales_tax_finix_generated": 200, "ship_from_postal_code": null, "shipping_amount": 100, "tax_exempt": false, "item_data": [ { "cost_per_unit": 500, "item_description": "printing paper", "item_discount_amount": 100, "merchant_product_code": "1149611", "quantity": 1, "amount_excluding_sales_tax": 400, "amount_including_sales_tax": 500, "unit_of_measure": "BX", "commodity_code": "175-62-20", "sales_tax_amount": 100, "sales_tax_rate": 0.25 }, { "cost_per_unit": 500, "item_description": "printing ink", "item_discount_amount": 0, "merchant_product_code": "2149612", "quantity": 1, "amount_excluding_sales_tax": 400, "amount_including_sales_tax": 500, "unit_of_measure": "CTN", "commodity_code": "207-72-54", "sales_tax_amount": 100, "sales_tax_rate": 0.25 } ] }, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 1000, "amount_requested": 1000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "USD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FP9F2KEnY4wt1XjFvhLBJVjb", "idempotency_id": null, "ip_address_details": null, "merchant": "MUe17jKSrfPetoeiJQzzjmA2", "merchant_identity": "ID6NvZy42D7PChZL8GKKD87F", "messages": [], "network_details": { "brand": "VISA", "authorization_code": "824912", "acquirer_reference_number": null }, "operation_key": "CARD_NOT_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "processed_at": "2026-09-25T20:05:49.20Z", "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": "MATCHED", "source": "PI6iQcTtJNCS8GZAVKYi5Ueb", "split_transfers": [ "split_transfer_gQSpMGjxZRQ452uTarEZZ4", "split_transfer_gQSr5EaDoRwr4A7E8EBPzH" ], "state": "SUCCEEDED", // [!code highlight] "statement_descriptor": "FLX*FLEX GYM", "subtype": "API", "supplemental_fee": null, "tags": { "tip": "50" }, "third_party_details": null, "tip_amount": null, "trace_id": "2c32aa3f-cd7a-4b44-9b53-56af75957d85", "type": "DEBIT", // [!code highlight] "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRgQBFEUahEyLZ6zvu3hrqNJ" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6NvZy42D7PChZL8GKKD87F" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRgQBFEUahEyLZ6zvu3hrqNJ/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRgQBFEUahEyLZ6zvu3hrqNJ/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRgQBFEUahEyLZ6zvu3hrqNJ" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRgQBFEUahEyLZ6zvu3hrqNJ/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6iQcTtJNCS8GZAVKYi5Ueb" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FP9F2KEnY4wt1XjFvhLBJVjb" } } } ``` Transfer - Canada Transfer - EFT ```json Transfer - EFT { "id": "TRp6LDrhdXaXNvnksSeTrrGw", "created_at": "2026-09-11T23:30:10.49Z", "updated_at": "2026-09-11T23:30:10.49Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_lodging_data": null, "additional_motor_vehicle_rental_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 662154, "amount_requested": 662154, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "UNKNOWN", "currency": "CAD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPmtT4MYmiAs1qjLjneQmk4d", "idempotency_id": null, "ip_address_details": null, "merchant": "MUaxXcUAU93JCJutWZVy6KJ5", "merchant_identity": "ID6V2Fppq1oUsEd9pzWUbrw6", "messages": [], "network_details": null, "operation_key": "CARD_NOT_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "processed_at": "2026-09-11T23:30:10.85Z", "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": "PIaRNMmrH4WtiBVhaZach99g", "split_transfers": [], "state": "PENDING", "statement_descriptor": "FLX*VIDEO SERVICES", "subtype": "API", "supplemental_fee": null, "tags": {}, "third_party_details": null, "tip_amount": null, "trace_id": "c9b6d473-d4bc-4c7d-9d18-ab444de10e4b", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRp6LDrhdXaXNvnksSeTrrGw" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6V2Fppq1oUsEd9pzWUbrw6" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRp6LDrhdXaXNvnksSeTrrGw/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRp6LDrhdXaXNvnksSeTrrGw/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRp6LDrhdXaXNvnksSeTrrGw" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRp6LDrhdXaXNvnksSeTrrGw/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIaRNMmrH4WtiBVhaZach99g" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d" } } } ``` ## Next steps Your seller has successfully charged their buyer, and is ready to collect their payout. Finix will create a Settlement resource to map transactions and fees to calculate and track your seller's payout. Continue reading to learn the details of onboarding your sellers, processing their payments, and managing their payouts. --- # Onboarding Sellers Source: https://docs.finix.com/guides/platform-payments/onboarding-sellers Learn how to onboard your sellers. Seller Payouts Hero Finix lets you easily onboard sellers and start accepting payments for your sellers. Onboard your sellers with Finix's low-code / no-code Onboarding Forms, or directly with Finix's onboarding APIs. ## Learn more Onboarding Process Learn about the process for onboarding your sellers. Onboarding Forms Use Finix's low-code / no-code Onboarding Forms to onboard your sellers in just minutes. Onboarding APIs Use Finix's APIs to build your own custom onboarding experience for your sellers. --- # Onboarding Data Source: https://docs.finix.com/guides/platform-payments/onboarding-sellers/seller-onboarding-data Learn about the data Finix collects and reviews during the seller onboarding process. For expected data formats by country and business type, see the Identity API Ref. | Required | Optional | Not Collected | | --- | --- | --- | | | | | ## Business information United States (USA) | Field | Default | Tax Exempt Organization | Government Agency | Individual Sole Proprietorship | | --- | --- | --- | --- | --- | | Business Address `business_address` | | | | | | Business Description `business_description` | | | | | | Business Name `business_name` | | | | | | Business Phone `business_phone` | | | | | | Business Tax ID `business_tax_id` | | | | | | Business Website `url` | | | | | | Doing Business As `doing_business_as` | | | | | | Incorporation Date `incorporation_date` | | | | | | Ownership Type `ownership_type` | | | | | Canada (CAN) | Field | Default | Tax Exempt Organization | Government Agency | Individual Sole Proprietorship | | --- | --- | --- | --- | --- | | Business Address `business_address` | | | | | | Business Description `business_description` | | | | | | Business Name `business_name` | | | | | | Business Phone `business_phone` | | | | | | Business Tax ID `business_tax_id` | | | | | | Business Website `url` | | | | | | Doing Business As `doing_business_as` | | | | | | Incorporation Date `incorporation_date` | | | | | | Ownership Type `ownership_type` | | | | | ## Owner information United States (USA) | Field | Default | Tax Exempt Organization | Government Agency | Individual Sole Proprietorship | | --- | --- | --- | --- | --- | | Control Owner `identity` | | | | | | Beneficial Owner(s) `associated_identity` | | | | | | Birthdate `dob` | | | | | | First Name `first_name` | | | | | | Job Title `title` | | | | | | Last Name `last_name` | | | | | | Ownership Percent `principal_ownership_percent` | | | | | | Personal Address `address` | | | | | | Personal Phone `phone_number` | | | | | | Personal Tax ID `tax_id` | | | | | | Work Email `email` | | | | | Canada (CAN) | Field | Default | Tax Exempt Organization | Government Agency | Individual Sole Proprietorship | | --- | --- | --- | --- | --- | | Control Owner `identity` | | | | | | Beneficial Owner(s) `associated_identity` | | | | | | Birthdate `dob` | | | | | | First Name `first_name` | | | | | | Job Title `title` | | | | | | Last Name `last_name` | | | | | | Ownership Percent `principal_ownership_percent` | | | | | | Personal Address `address` | | | | | | Personal Phone `phone_number` | | | | | | Personal Tax ID `tax_id` | | | | | | Work Email `email` | | | | | ## Bank account information United States (USA) | Field | Default | Tax Exempt Organization | Government Agency | Individual Sole Proprietorship | | --- | --- | --- | --- | --- | | Account Number `account_number` | | | | | | Account Type `account_type` | | | | | | Accountholder Name `name` | | | | | | Routing Number `bank_code` | | | | | | Plaid Token `third_party_token` | | | | | Canada (CAN) | Field | Default | Tax Exempt Organization | Government Agency | Individual Sole Proprietorship | | --- | --- | --- | --- | --- | | Account Number `account_number` | | | | | | Account Type `account_type` | | | | | | Accountholder Name `name` | | | | | | Institution Number `institution_number` | | | | | | Transit Number `transit_number` | | | | | | Plaid Token `third_party_token` | | | | | Additional documentation required for Canadian sellers Canadian sellers must provide **one** of the following as part of credit risk underwriting: - A signed Credit Authorization Form (allows a soft credit pull) - 3 months of recent bank statements - 3 months of recent processing statements For restricted or high-risk Canadian merchants, **all** of the following are required: - A signed Credit Authorization Form - 3 months of recent bank statements - 3 months of recent processing statements (or compiled financials covering 2+ years with interim) ## Processing information | Field | Default | Tax Exempt Organization | Government Agency | Individual Sole Proprietorship | | --- | --- | --- | --- | --- | | Annual Volume, ACH `annual_ach_volume` | | | | | | Annual Volume, Card `annual_volume` | | | | | | Avg. Transfer Amount, ACH `average_ach_transfer_amount` | | | | | | Avg. Transfer Amount, Card `average_card_transfer_amount` | | | | | | Card Volume Distribution `card_volume_distribution` | | | | | | Default Statement Descriptor `default_statement_descriptor` | | | | | | Max Transaction Amount, ACH `ach_max_transaction_amount` | | | | | | Max Transaction Amount, Card `max_transaction_amount` | | | | | | Merchant Agreement `merchant_agreement` | | | | | | Merchant Category Code `mcc` | | | | | | Previous Card Acceptance `has_accepted_...` | | | | | | Refund Policy `refund_policy` | | | | | | Volume Distribution `volume_distribution_...` | | | | | --- # Seller Onboarding Forms Source: https://docs.finix.com/guides/platform-payments/onboarding-sellers/seller-onboarding-forms Seller Onboarding Forms Hero Save time onboarding sellers by using our Onboarding Forms. Finix's low-code / no-code Onboarding Forms are a fast and flexible way to onboard your sellers. Creating and filling out the form takes just minutes, helping your sellers start processing payments as fast as possible. You can create an Onboarding Form directly from Finix's dashboard, as well as with our APIs. Deleting Onboarding Forms is unavailable Our product does not support deleting onboarding forms. You can create a new one if you would like the merchant to start again. Finix's Onboarding Forms are purpose-built to make onboarding your sellers as easy as possible: - **Low-code / no-code:** send an Onboarding Form to your seller immediately, with no technical integrations. - **White-labeled experience:** customize our Onboarding Form with your company's name, logo, and colors. - **Prefill information:** prefill as much information as you want, saving your sellers time. - **Multi-country support:** our Onboarding Forms support boarding both American and Canadian sellers. - **Save progress:** our Onboarding Forms save your sellers' progress, should they need more time. - **Updating information:** our Onboarding Forms are editable, should we request updates during onboarding. br Seller Onboarding Forms Diagram ## Onboarding Form data Our Onboarding Forms collect 5 key pieces of data from your sellers: 1. **Seller consent:** Finix collects your sellers' consent to both Finix's terms as well as your own terms. 2. **Business information:** Finix collects data about your seller's business, such as their business name. 3. **Owner information:** Finix collects data about your seller's control person, such as their personal name. 4. **Processing information:** Finix collects data about your seller's processing information, such as volumes. 5. **Bank account information:** Finix collects details about your seller's bank account for their payouts. ## Managing Onboarding Forms with Finix's Dashboard ### Branding Onboarding Forms Finix lets you brand your Onboarding Forms with your company's name, logo, and colors. To apply your branding, visit **Settings > Company > Branding > Onboarding Forms** on your Finix dashboard. From there, you can set your business name, the logo to use on the form's header, and the color to use for the form's header. You can preview your branding by creating an Onboarding Form in your Sandbox account, or refreshing an existing Onboarding Form. Dashboard Settings Onboarding Forms By default, our Onboarding Form is branded dark blue with no logo. For more information, see White Labeling and Customizing Finix Dashboards. ### Creating Onboarding Forms To create an Onboarding Form with Finix's dashboard, visit **Merchants > Onboarding Forms** and select **Create New Form**. From there, we will collect these details to create the form: | Field | Description | | --- | --- | | Country | Your merchant's business country | | Merchant Name | Your merchant's business name | | Link Expiration Time (Days) | Time until your Onboarding Form expires | | Fee URL | Link to webpage explaining your payment processing fees | | Return URL | Link to webpage for your merchants to route after completing their Onboarding Form | | Terms of Service URL | Link to webpage with your Terms of Service | | Expired Session URL | Link to webpage for your merchants to route should the Onboarding Form expire | | Max Transaction Amount (Card) | Maximum transaction amount for your merchant's card payment processing | | Max Transaction Amount (ACH) | Maximum transaction amount for your merchant's ACH payment processing | | Payment Processor | Payment processor for your merchant's processing | After creating the Onboarding Form, copy the link to send to your merchant. That's it – your merchant is ready to apply to Finix, with no additional action from your team. Once your merchant submits their Onboarding Form, Finix will create their Merchant account and review their information. ### Viewing Onboarding Forms View all your Onboarding Forms in your Finix dashboard under **Merchants > Onboarding Forms**. You can view and filter by form status. Dashboard Settings Onboarding Forms Select an Onboarding Form to re-copy the form's link under **Actions**, as well as view all the information your Merchant has saved to the form while filling it out. You can generate a new URL link if the Onboarding Form's **Status** is **In Progress**. Dashboard Settings Onboarding Forms ### Submitted Onboarding Forms After your seller submits their Onboarding Form, Finix will mark it Completed and automatically create your seller's Merchant account. After the review process, your seller's Merchant account will be Approved and ready to accept payments. This process often takes just minutes. Should Finix require more information from your sellers during our review, their Merchant account and Onboarding Form will both move to an Update Requested state. To make the update process as easy as possible, your sellers can use their original Onboarding Form to provide the requested information. After resending your sellers their Onboarding Form link, no additional action is required from your team – Finix will automatically re-review your seller after they submit the requested updates. | Lifecycle event | Onboarding Form | Merchant Account | | --- | --- | --- | | Onboarding Form Created | `In Progress` | — | | Onboarding Form Submitted | `Completed` | `Provisioning` | | Merchant Approved | `Completed` | `Approved` | | Merchant Rejected | `Completed` | `Rejected` | | Updates Requested | `Update Requested` | `Update Requested` | | Updates Submitted | `Completed` | `Provisioning` | To learn more about update requests, see Handling Update Requests. ### Lifecycle notifications Finix offers notifications through both email and the Finix dashboard, making it easy for your team to receive updates as your sellers progress through onboarding. For example, your team can subscribe to receive notifications when your sellers submit their Onboarding Forms and are approved. To learn more about notifications, see Notifications and Webhooks. ## Managing Onboarding Forms with Finix's API Should you wish to create Onboarding Forms in bulk or directly from your application, you can use the Onboarding Forms API. Finix lets you prefill as many or as few fields as you'd like, and provides a link your seller can use to access the form. ### Creating Onboarding Forms #### Required data Finix requires these fields to create an Onboarding Form: | Field | Type | Description | | --- | --- | --- | | `expired_session_url` | String | Link to webpage for your merchants to route should the Onboarding Form expire | | `fee_details_url` | String | Link to webpage explaining your payment processing fees | | `max_transaction_amount` | Integer | Maximum transaction amount for your merchant's card payment processing | | `processor` | Enum | Payment processor for your merchant's processing | | `return_url` | String | Link to webpage for your merchants to route after completing their Onboarding Form | | `terms_of_service_url` | String | Link to webpage with your Terms of Service | #### Prefilling fields Beyond setting the required fields, you may prefill as many other fields as you'd like on the Onboarding Form. This includes the country, as well as all the fields under entity, additional_underwriting_data, associated_entities, and payment_instruments. See an example below of an Onboarding Form request with all fields prefilled, as well as the full list of fields and definitions on the Onboarding Forms API Reference. #### Form link In the response, Finix provides a link for your seller to access and complete the Onboarding Form (link_url). Should the form's link expire, use the Onboarding Forms Link API to create a new one. Link expiration Use `expiration_in_minutes` to control how long the link is valid. The value sets `onboarding_link.expires_at` in the response. If omitted, the link expires 60 minutes from creation. The pre-filled examples below use `10080` (7 days). Adjust the expiration to fit your needs. #### Request examples - USA Pre-filled form Response ```json Response { "id": "obf_eWjEqM1TnUG7Vr5Za9nU2P", "onboarding_data": { "entity": { "title": "CEO", "first_name": "John", "last_name": "Smith", "email": "john.smith@finix.com", "business_name": "Finix Flowers", "business_type": "CORPORATION", "doing_business_as": "Finix Flowers", "phone": "14158885080", "business_phone": "14158885080", "mcc": "4900", "url": "https://www.finix.com", "ownership_type": "PRIVATE", "default_statement_descriptor": "DEMOCOMPANY", "annual_card_volume": "1000000", "principal_percentage_ownership": "75", "tax_id": "*****6789", "business_tax_id": "*****6789", "has_accepted_credit_cards_previously": false, "personal_address": { "line1": "123 Boren Ave", "city": "Seattle", "region": "WA", "postal_code": "98040", "country": "USA" }, "business_address": { "line1": "123 Bellevue Way", "city": "Bellevue", "region": "WA", "postal_code": "98039", "country": "USA" }, "dob": { "day": 13, "month": 4, "year": 1982 }, "incorporation_date": { "day": 9, "month": 3, "year": 2018 } }, "associated_entities": [ { "title": "CFO", "first_name": "Alex", "last_name": "Smith", "email": "alex.smith@finix.com", "phone": "14158885080", "personal_address": { "line1": "4848 84th St", "city": "Bellevue", "region": "WA", "postal_code": "98032", "country": "USA" }, "dob": { "day": 13, "month": 4, "year": 1985 }, "principal_percentage_ownership": 25, "tax_id": "*****6789" } ], "payment_instruments": { "name": "SARAH BANKER", "bank_code": "123456789", "account_number": "*****6789", "account_type": "CHECKING", "type": "BANK_ACCOUNT", "country": "USA", "currency": "USD" }, "additional_underwriting_data": { "refund_policy": "NO_REFUNDS", "average_ach_transfer_amount": 200000, "average_card_transfer_amount": 20000, "merchant_agreement_ip_address": "42.1.1.113", "merchant_agreement_accepted": true, "merchant_agreement_timestamp": "2021-04-28T16:42:55Z", "merchant_agreement_user_agent": "Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)", "credit_check_timestamp": null, "credit_check_user_agent": null, "annual_ach_volume": 2000000, "business_description": "CONSUMER", "volume_distribution_by_business_type": { "other_volume_percentage": 0, "person_to_person_volume_percentage": 0, "business_to_business_volume_percentage": 90, "business_to_consumer_volume_percentage": 10, "consumer_to_consumer_volume_percentage": 0 }, "card_volume_distribution": { "ecommerce_percentage": 100, "card_present_percentage": 0, "mail_order_telephone_order_percentage": 0 }, "amex_marketing_consent": { "accepted": false, "ip_address": "42.1.1.113", "user_agent": "Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)", "timestamp": "2021-04-28T16:42:55Z" } }, "max_transaction_amount": 100000, "ach_max_transaction_amount": 100000, "country": "USA", "associated_files": [] }, "merchant_processors": [ { "processor": "DUMMY_V1" } ], "onboarding_link_details": { "return_url": "https://www.finixflowers.com/home", "expired_session_url": "https://www.finixflowers.com/login", "fee_details_url": "https://www.finixflowers.com/fee_details", "merchant_max_transaction_amount": 100000, "merchant_ach_max_transaction_amount": 100000, "terms_of_service_url": "https://www.finixflowers.com/ToS", "expiration_in_minutes": 10080 }, "onboarding_link": { "expires_at": "2026-10-02T20:05:22.899Z", "link_url": "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=REDACTED&applicationId=APc9vhYcPsRuTSpKD9KpMtPe&bearerToken=REDACTED" }, "status": "IN_PROGRESS", "identity_id": null, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "created_at": "2026-09-25T20:05:22.8913Z", "updated_at": "2026-09-25T20:05:22.8913Z", "tags": {} } ``` Empty form Response ```json Response { "id": "obf_eXN4HNVf8oAfcAQQVw95e3", "onboarding_data": { "max_transaction_amount": 500000, "country": "USA", // [!code highlight] "associated_files": [] }, "merchant_processors": [ { "processor": "DUMMY_V1" } ], "onboarding_link_details": { "return_url": "https://www.finixflowers.com/home", "expired_session_url": "https://www.finixflowers.com/login", "fee_details_url": "https://www.finixflowers.com/fee_details", "terms_of_service_url": "https://www.finixflowers.com/ToS" }, "onboarding_link": { "expires_at": "2026-09-25T21:05:23.241Z", "link_url": "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=REDACTED&applicationId=APc9vhYcPsRuTSpKD9KpMtPe&bearerToken=REDACTED" }, "status": "IN_PROGRESS", "identity_id": null, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "created_at": "2026-09-25T20:05:23.235792Z", "updated_at": "2026-09-25T20:05:23.235792Z", "tags": {} } ``` #### Request examples - CAN Additional documentation required for Canadian sellers Canadian sellers must provide **one** of the following as part of credit risk underwriting: - A signed Credit Authorization Form (allows a soft credit pull) - 3 months of recent bank statements - 3 months of recent processing statements For restricted or high-risk Canadian merchants, **all** of the following are required: - A signed Credit Authorization Form - 3 months of recent bank statements - 3 months of recent processing statements (or compiled financials covering 2+ years with interim) Pre-filled form Response ```json Response { "id": "obf_eRLCSSUd8Hu5MNsgEyuCcE", "onboarding_data": { "entity": { "title": "CEO", "first_name": "John", "last_name": "Smith", "email": "john.smith@finix.com", "business_name": "Finix Flowers", "business_type": "CORPORATION", "doing_business_as": "Finix Flowers", "phone": "16138885080", "business_phone": "16138885080", "mcc": "4900", "url": "https://www.finix.com", "ownership_type": "PRIVATE", "default_statement_descriptor": "DEMOCOMPANY", "annual_card_volume": "1000000", "principal_percentage_ownership": "75", "tax_id": "*****6789", "business_tax_id": "*****6789", "has_accepted_credit_cards_previously": false, "personal_address": { "line1": "123 Queen St W", "city": "Toronto", "region": "ON", "postal_code": "M5H 2M9", "country": "CAN" }, "business_address": { "line1": "456 King St W", "city": "Toronto", "region": "ON", "postal_code": "M5V 1K4", "country": "CAN" }, "dob": { "day": 13, "month": 4, "year": 1982 }, "incorporation_date": { "day": 9, "month": 3, "year": 2018 } }, "associated_entities": [ { "title": "CFO", "first_name": "Alex", "last_name": "Smith", "email": "alex.smith@finix.com", "phone": "16138885080", "personal_address": { "line1": "789 Rideau St", "city": "Ottawa", "region": "ON", "postal_code": "K1N 5Y3", "country": "CAN" }, "dob": { "day": 13, "month": 4, "year": 1985 }, "principal_percentage_ownership": 25, "tax_id": "*****6789" } ], "payment_instruments": { "name": "SARAH BANKER", "bank_code": "123456789", "account_number": "*****6789", "account_type": "CHECKING", "type": "BANK_ACCOUNT", "country": "CAN", "currency": "CAD" }, "additional_underwriting_data": { "refund_policy": "NO_REFUNDS", "average_ach_transfer_amount": 200000, "average_card_transfer_amount": 20000, "merchant_agreement_ip_address": "42.1.1.113", "merchant_agreement_accepted": true, "merchant_agreement_timestamp": "2021-04-28T16:42:55Z", "merchant_agreement_user_agent": "Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)", "credit_check_timestamp": null, "credit_check_user_agent": null, "annual_ach_volume": 2000000, "business_description": "CONSUMER", "volume_distribution_by_business_type": { "other_volume_percentage": 0, "person_to_person_volume_percentage": 0, "business_to_business_volume_percentage": 90, "business_to_consumer_volume_percentage": 10, "consumer_to_consumer_volume_percentage": 0 }, "card_volume_distribution": { "ecommerce_percentage": 100, "card_present_percentage": 0, "mail_order_telephone_order_percentage": 0 }, "amex_marketing_consent": { "accepted": false, "ip_address": "42.1.1.113", "user_agent": "Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)", "timestamp": "2021-04-28T16:42:55Z" } }, "max_transaction_amount": 100000, "country": "CAN", "associated_files": [] }, "merchant_processors": [ { "processor": "DUMMY_V1" } ], "onboarding_link_details": { "return_url": "https://www.finixflowers.com/home", "expired_session_url": "https://www.finixflowers.com/login", "fee_details_url": "https://www.finixflowers.com/fee_details", "merchant_max_transaction_amount": 100000, "merchant_ach_max_transaction_amount": 100000, "terms_of_service_url": "https://www.finixflowers.com/ToS", "expiration_in_minutes": 10080 }, "onboarding_link": { "expires_at": "2026-10-02T20:05:21.838Z", "link_url": "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=REDACTED&applicationId=APc9vhYcPsRuTSpKD9KpMtPe&bearerToken=REDACTED" }, "status": "IN_PROGRESS", "identity_id": null, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "created_at": "2026-09-25T20:05:21.824498Z", "updated_at": "2026-09-25T20:05:21.824498Z", "tags": {} } ``` Empty form Response ```json Response { "id": "obf_eUJJthJa997AqcdF63XdnN", "onboarding_data": { "max_transaction_amount": 100000, "country": "CAN", // [!code highlight] "associated_files": [] }, "merchant_processors": [ { "processor": "DUMMY_V1" } ], "onboarding_link_details": { "return_url": "https://www.finixflowers.com/home", "expired_session_url": "https://www.finixflowers.com/login", "fee_details_url": "https://www.finixflowers.com/fee_details", "terms_of_service_url": "https://www.finixflowers.com/ToS" }, "onboarding_link": { "expires_at": "2026-09-25T21:05:22.528Z", "link_url": "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=REDACTED&applicationId=APc9vhYcPsRuTSpKD9KpMtPe&bearerToken=REDACTED" }, "status": "IN_PROGRESS", "identity_id": null, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "created_at": "2026-09-25T20:05:22.519561Z", "updated_at": "2026-09-25T20:05:22.519561Z", "tags": {} } ``` #### Fetching an Onboarding Form Link Should your seller need to re-access their Onboarding Form (for example, if the form expires or your seller needs to update their form), you can create a new link for an existing form. Finix saves your seller's progress as they complete each form step, letting them pick up wherever they left off. ```shell Request curl "https://finix.sandbox-payments-api.com/onboarding_forms/obf_n4J6QuG6XHoUbZ54Z88v5h/links" \ -H "Content-Type: application/json" \ -H "Finix-Version: 2022-02-01" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -d '{ "return_url": "https://www.democompany.com/home", "expired_session_url": "https://www.democompany.com/login", "fee_details_url": "https://www.democompany.com/fee_details", "terms_of_service_url": "https://www.democompany.com/ToS", "expiration_in_minutes": 10080 }' ``` ```json Response { "expires_at": "2024-11-15T05:39:20.864Z", "link_url": "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_n4J6QuG6XHoUbZ54Z88v5h&applicationId=APgPDQrLD52TYvqazjHJJchM&bearerToken=eyJhbGciOiJIUzUxMiJ9.eyJvbmJvYXJkaW5nX2Zvcm1faWQiOiJvYmZfbjRKNlF1RzZYSG9VYlo1NFo4OHY1aCIsImZlZV9kZXRhaWxzX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9mZWVfZGV0YWlscyIsImV4cGlyZWRfc2Vzc2lvbl91cmwiOiJodHRwczovL3d3dy5kZW1vY29tcGFueS5jb20vbG9naW4iLCJtZXJjaGFudF9hY2hfbWF4X3RyYW5zYWN0aW9uX2Ftb3VudCI6MTAwMDAwMDAwLCJpc3MiOiJodHRwczovL3d3dy5maW5peC5jb20iLCJyZXR1cm5fdXJsIjoiaHR0cHM6Ly93d3cuZGVtb2NvbXBhbnkuY29tL2hvbWUiLCJleHAiOjE3MzE2NDkxNjAsImFwcGxpY2F0aW9uX2lkIjoiQVBnUERRckxENTJUWXZxYXpqSEpKY2hNIiwiaWF0IjoxNzMxMDQ0MzYwLCJtZXJjaGFudF9tYXhfdHJhbnNhY3Rpb25fYW1vdW50IjoxMDAwMDAwMDAsInRlcm1zX29mX3NlcnZpY2VfdXJsIjoiaHR0cHM6Ly93d3cuZGVtb2NvbXBhbnkuY29tL1RvUyJ9.9h1NIqGe6_VlBzXK7KeC3t9F3cWBA4qrnrq-H_t0R3W2pdXq8_d7-mVFxxqQMaVYRcjgOZmL1e-P01-hgUY0EQ" } ``` ### Submitted Onboarding Forms #### Created resources After your seller completes their Onboarding Form, Finix automatically creates these API resources for them: 1. Merchant: your seller will use their Merchant Account to accept payments once it is approved 2. Verification: this resource puts the Merchant Account into Finix's underwriting system 3. Identity: this resource contains the data your seller submitted through their Onboarding Form 4. Payment Instrument: this resource represents the bank account for your seller's payouts Your seller's Merchant account will transition from PROVISIONING to APPROVED after the underwriting process, letting them accept payments. Should Finix require additional information during the underwriting process, your Merchant's account and the Onboarding Form will both transition into an UPDATE_REQUESTED state. In the event that Finix cannot onboard your seller, their Merchant account will transition to the REJECTED state. | Lifecycle event | Merchant | Verification | Onboarding Form | | --- | --- | --- | --- | | Onboarding Form Submitted | `PROVISIONING` | `PENDING` | `COMPLETED` | | Merchant Approved | `APPROVED` | `SUCCEEDED` | `COMPLETED` | | Merchant Rejected | `REJECTED` | `FAILED` | `COMPLETED` | | Updates Requested | `UPDATE_REQUESTED` | `FAILED` | `UPDATE_REQUESTED` | | Updates Submitted | `PROVISIONING` | `PENDING` | `COMPLETED` | #### Fetching resources Your seller's completed Onboarding Form will have an identity_id, which you can also find appended to the return_url your seller is redirected to: Return URL ```txt https://www.demo-company.com/return_url?identityId=IDeoSwE888omd6pn73hzLA5a ``` Completed Onboarding Form ```json { "id": "obf_osQEKPNUrVT6BFf9ucUH7z", "onboarding_data": { "entity": { "title": "CEO", "first_name": "John", "last_name": "Smith", "email": "owner@democompany.com", "business_name": "Demo Company, LLC", "business_type": "CORPORATION", "doing_business_as": "Demo Company", "phone": "1234567890", "business_phone": "1234567890", "mcc": "4900", "url": "www.democompany.com", "ownership_type": "PRIVATE", "default_statement_descriptor": "DEMOCOMPANY", "annual_card_volume": "1000000", "principal_percentage_ownership": "75", "tax_id": "*****6789", "business_tax_id": "*****6789", "has_accepted_credit_cards_previously": false, "personal_address": { "line1": "123 Boren Ave", "city": "Seattle", "region": "WA", "postal_code": "98040", "country": "USA" }, "business_address": { "line1": "123 Bellevue Way", "city": "Bellevue", "region": "WA", "postal_code": "98039", "country": "USA" }, "dob": { "day": 13, "month": 4, "year": 1982 }, "incorporation_date": { "day": 9, "month": 3, "year": 2018 } }, "associated_entities": [ { "title": "CFO", "first_name": "Numbers", "last_name": "McGee", "email": "numbers@democompany.com", "phone": "123456789", "personal_address": { "line1": "4848 84th St", "city": "Bellevue", "region": "WA", "postal_code": "98032", "country": "USA" }, "dob": { "day": 13, "month": 4, "year": 1985 }, "principal_percentage_ownership": 25, "tax_id": "*****6789" } ], "payment_instruments": { "name": "JOE BANKER", "bank_code": "123456789", "account_number": "*****6789", "account_type": "CHECKING", "type": "BANK_ACCOUNT", "country": "USA", "currency": "USD" }, "additional_underwriting_data": { "refund_policy": "NO_REFUNDS", "average_ach_transfer_amount": 20000000, "average_card_transfer_amount": 20000, "merchant_agreement_ip_address": null, "merchant_agreement_accepted": null, "merchant_agreement_timestamp": null, "merchant_agreement_user_agent": null, "credit_check_timestamp": null, "credit_check_user_agent": null, "annual_ach_volume": 20000000, "business_description": "CONSUMER", "volume_distribution_by_business_type": { "other_volume_percentage": 0, "person_to_person_volume_percentage": 0, "business_to_business_volume_percentage": 90, "business_to_consumer_volume_percentage": 10, "consumer_to_consumer_volume_percentage": 0 }, "card_volume_distribution": { "ecommerce_percentage": 100, "card_present_percentage": 0, "mail_order_telephone_order_percentage": 0 }, "amex_marketing_consent": null }, "max_transaction_amount": 100000, "country": "USA", "associated_files": [] }, "merchant_processors": [ { "processor": "LITLE_V1" } ], "onboarding_link_details": { "return_url": "https://www.democompany.com/home", "expired_session_url": "https://www.democompany.com/login", "fee_details_url": "https://www.democompany.com/fee_details", "terms_of_service_url": "https://www.democompany.com/ToS", "expiration_in_minutes": 10080 }, "onboarding_link": { "expires_at": "2024-08-22T03:01:47.445Z", "link_url": "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_osQEKPNUrVT6BFf9ucUH7z&applicationId=APgPDQrLD52TYvqazjHJJchM&bearerToken=eyJhbGciOiJIUzUxMiJ9.eyJvbmJvYXJkaW5nX2Zvcm1faWQiOiJvYmZfb3NRRUtQTlVyVlQ2QkZmOXVjVUg3eiIsImZlZV9kZXRhaWxzX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9mZWVfZGV0YWlscyIsImV4cGlyZWRfc2Vzc2lvbl91cmwiOiJodHRwczovL3d3dy5kZW1vY29tcGFueS5jb20vbG9naW4iLCJtZXJjaGFudF9hY2hfbWF4X3RyYW5zYWN0aW9uX2Ftb3VudCI6bnVsbCwiaXNzIjoiaHR0cHM6Ly93d3cuZmluaXguY29tIiwicmV0dXJuX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9ob21lIiwiZXhwIjoxNzI0Mjk1NzA3LCJhcHBsaWNhdGlvbl9pZCI6IkFQZ1BEUXJMRDUyVFl2cWF6akhKSmNoTSIsImlhdCI6MTcyMzY5MDkwNywibWVyY2hhbnRfbWF4X3RyYW5zYWN0aW9uX2Ftb3VudCI6MTAwMDAwLCJ0ZXJtc19vZl9zZXJ2aWNlX3VybCI6Imh0dHBzOi8vd3d3LmRlbW9jb21wYW55LmNvbS9Ub1MifQ.1ePWjKXSSvHF5FJdfMn5dQFgKKnM91ig2urX6kDxiYQD940hKoi4EJVSlQFvcHHTDPeS1Fz84_GGwh7aZC6qLQ" }, "status": "COMPLETED", "identity_id": "IDXX", "application_id": "APgPDQrLD52TYvqazjHJJchM", "created_at": "2024-08-15T03:01:47.43517Z", "updated_at": "2024-08-15T03:01:47.43517Z", "tags": {} } ``` You can use the `identity_id` to fetch your seller's Merchant resource: An Identity's Merchant ```json An Identity's Merchant { "_embedded": { "merchants": [ { "id": "MU28NZ49FWpXPM4UkMEWATEF", "created_at": "2026-09-25T20:06:54.59Z", "updated_at": "2026-09-25T20:07:03.19Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "card_cvv_required": false, "card_expiration_date_required": true, "card_network_details": null, "convenience_charges_enabled": false, "country": "USA", "creating_transfer_from_report_enabled": false, "currencies": [ "USD" ], "default_partial_authorization_enabled": false, "disbursements_ach_pull_enabled": true, "disbursements_ach_push_enabled": true, "disbursements_card_pull_enabled": true, "disbursements_card_push_enabled": true, "disbursements_same_day_ach_pull_enabled": false, "disbursements_same_day_ach_push_enabled": false, "fee_ready_to_settle_upon": "PROCESSOR_WINDOW", "first_approved_at": "2026-09-25T20:07:03.21Z", "gateway": null, "gross_settlement_enabled": false, "identity": "IDm7cEEr5stCd7vUYRHKDsqs", "instant_payouts_card_push_enabled": false, "is_terminated": false, "level_two_level_three_data_enabled": false, "loan_repayment": null, "mcc": "4900", "merchant_name": "Finix Flowers", "merchant_profile": "MPbywVLQovHYvrMmvAE9NotL", "microdeposit_verification_required_buyer": true, "microdeposit_verification_required_sender": false, "mid": "FNX8bUT5k3N76YvsxEdDvP4tM", "onboarding_state": "APPROVED", "pending_refunds_strategy": "SAME_DAY_ADJUSTMENT", "processing_enabled": true, "processor": "DUMMY_V1", "processor_details": { "mid": "FNX8bUT5k3N76YvsxEdDvP4tM", "api_key": "secretValue" }, "ready_to_settle_upon": "PROCESSOR_WINDOW", "ready_to_settle_upon_delay_alignment": "NONE", "refunds_disabled": false, "rent_surcharges_enabled": false, "settlement_enabled": true, "settlement_funding_identifier": "UNSET", "settlement_queue_mode": "UNSET", "surcharges_enabled": false, "tags": { "order_id": "ORD-123" }, "termination_details": null, "unreferenced_refund_card_present_enabled": true, "unreferenced_refund_manual_entry_enabled": false, "verification": "VIhNG3yx7gNN8ikjCp9huTVs", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/merchants/MU28NZ49FWpXPM4UkMEWATEF" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDm7cEEr5stCd7vUYRHKDsqs" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/merchants/MU28NZ49FWpXPM4UkMEWATEF/verifications" }, "merchant_profile": { "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPbywVLQovHYvrMmvAE9NotL" }, "verification": { "href": "https://finix.sandbox-payments-api.com/verifications/VIhNG3yx7gNN8ikjCp9huTVs" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } }, { "id": "MUeGAgVmwcHD4jNHFmAxHTrm", "created_at": "2026-09-25T20:06:52.84Z", "updated_at": "2026-09-25T20:07:02.93Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "card_cvv_required": false, "card_expiration_date_required": true, "card_network_details": null, "convenience_charges_enabled": false, "country": "USA", "creating_transfer_from_report_enabled": false, "currencies": [ "USD" ], "default_partial_authorization_enabled": false, "disbursements_ach_pull_enabled": true, "disbursements_ach_push_enabled": true, "disbursements_card_pull_enabled": true, "disbursements_card_push_enabled": true, "disbursements_same_day_ach_pull_enabled": false, "disbursements_same_day_ach_push_enabled": false, "fee_ready_to_settle_upon": "PROCESSOR_WINDOW", "first_approved_at": "2026-09-25T20:07:02.95Z", "gateway": null, "gross_settlement_enabled": false, "identity": "IDpxyDdo9RgJpsmfM45vVPJ6", "instant_payouts_card_push_enabled": false, "is_terminated": false, "level_two_level_three_data_enabled": false, "loan_repayment": null, "mcc": "4900", "merchant_name": "Finix Flowers", "merchant_profile": "MPrwPrsqCNJhJX9L57zhiWiX", "microdeposit_verification_required_buyer": true, "microdeposit_verification_required_sender": false, "mid": "FNXuhxYrydhUj95XtZ2wxNfrV", "onboarding_state": "APPROVED", "pending_refunds_strategy": "SAME_DAY_ADJUSTMENT", "processing_enabled": true, "processor": "DUMMY_V1", "processor_details": { "mid": "FNXuhxYrydhUj95XtZ2wxNfrV", "api_key": "secretValue" }, "ready_to_settle_upon": "PROCESSOR_WINDOW", "ready_to_settle_upon_delay_alignment": "NONE", "refunds_disabled": false, "rent_surcharges_enabled": false, "settlement_enabled": true, "settlement_funding_identifier": "UNSET", "settlement_queue_mode": "UNSET", "surcharges_enabled": false, "tags": {}, "termination_details": null, "unreferenced_refund_card_present_enabled": true, "unreferenced_refund_manual_entry_enabled": false, "verification": "VIkbyj4r6ZvE5nGWfBNgUnuC", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/merchants/MUeGAgVmwcHD4jNHFmAxHTrm" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDpxyDdo9RgJpsmfM45vVPJ6" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/merchants/MUeGAgVmwcHD4jNHFmAxHTrm/verifications" }, "merchant_profile": { "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPrwPrsqCNJhJX9L57zhiWiX" }, "verification": { "href": "https://finix.sandbox-payments-api.com/verifications/VIkbyj4r6ZvE5nGWfBNgUnuC" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } }, { "id": "MU4YKW5VuamZriGSCBKj9cyZ", "created_at": "2026-09-25T19:47:40.47Z", "updated_at": "2026-09-25T19:48:03.36Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "card_cvv_required": false, "card_expiration_date_required": true, "card_network_details": null, "convenience_charges_enabled": false, "country": "USA", "creating_transfer_from_report_enabled": false, "currencies": [ "USD" ], "default_partial_authorization_enabled": false, "disbursements_ach_pull_enabled": true, "disbursements_ach_push_enabled": true, "disbursements_card_pull_enabled": true, "disbursements_card_push_enabled": true, "disbursements_same_day_ach_pull_enabled": false, "disbursements_same_day_ach_push_enabled": false, "fee_ready_to_settle_upon": "PROCESSOR_WINDOW", "first_approved_at": "2026-09-25T19:48:03.39Z", "gateway": null, "gross_settlement_enabled": false, "identity": "IDdgLJPevfKoHk4KP3Yg2XsD", "instant_payouts_card_push_enabled": false, "is_terminated": false, "level_two_level_three_data_enabled": false, "loan_repayment": true, "mcc": "6012", "merchant_name": "Finix Flowers", "merchant_profile": "MPhYuYKuEpejyZ6kacdv61PB", "microdeposit_verification_required_buyer": true, "microdeposit_verification_required_sender": false, "mid": "FNX8TW96Cd576zdZuLidxpMfL", "onboarding_state": "APPROVED", "pending_refunds_strategy": "SAME_DAY_ADJUSTMENT", "processing_enabled": true, "processor": "DUMMY_V1", "processor_details": { "mid": "FNX8TW96Cd576zdZuLidxpMfL", "api_key": "secretValue" }, "ready_to_settle_upon": "PROCESSOR_WINDOW", "ready_to_settle_upon_delay_alignment": "NONE", "refunds_disabled": false, "rent_surcharges_enabled": false, "settlement_enabled": true, "settlement_funding_identifier": "UNSET", "settlement_queue_mode": "UNSET", "surcharges_enabled": false, "tags": {}, "termination_details": null, "unreferenced_refund_card_present_enabled": true, "unreferenced_refund_manual_entry_enabled": false, "verification": "VIu8nxwAz91tt9cFJ7wDVz5x", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/merchants/MU4YKW5VuamZriGSCBKj9cyZ" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDdgLJPevfKoHk4KP3Yg2XsD" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/merchants/MU4YKW5VuamZriGSCBKj9cyZ/verifications" }, "merchant_profile": { "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPhYuYKuEpejyZ6kacdv61PB" }, "verification": { "href": "https://finix.sandbox-payments-api.com/verifications/VIu8nxwAz91tt9cFJ7wDVz5x" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ] }, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/merchants?limit=3" }, "next": { "href": "https://finix.sandbox-payments-api.com/merchants?limit=3&after_cursor=MU4YKW5VuamZriGSCBKj9cyZ" } }, "page": { "limit": 3, "next_cursor": "MU4YKW5VuamZriGSCBKj9cyZ" } } ``` #### Receiving Webhooks Finix sends webhooks to update you about your seller's progress throughout the onboarding process. For example, the Merchant Created webhook lets you know when your seller has submitted their Onboarding Form, and the Merchant Updated webhook lets you know when their Merchant account transitions between state. To learn more about webhooks, see Notifications and Webhooks. #### Handling update requests Should Finix request additional information from your seller during the underwriting process, they can use their original Onboarding Form to provide the requested information. Use the Dashboard or API to fetch and send your seller's Onboarding Form link. No additional action is required from your team – Finix will update your seller's API resources and place them back in the underwriting process after they re-submit their Onboarding Form. To learn more about update requests, see Handling Update Requests. ## Onboarding Form Identity Verification To mitigate fraud and identity theft, Finix requires government IDs and selfie photos from merchants submitting Onboarding Forms. This verification step ensures that the actual control owner of a merchant’s business is submitting the form, preventing unauthorized access. Collecting government IDs and selfies is an effective tool for mitigating fraud and identity theft. If you have concerns about Finix collecting and verifying this information, please contact your Finix representative. Finix integrates [Persona](https://withpersona.com/product/verifications/government-id) to securely collect government IDs and selfies within the Onboarding Form. The control owner must complete this step before submitting the form. The verification process works on any device with a camera, and merchants can switch to another device if needed. Persona Onboarding Form Persona Frames ## Next steps Next, learn how to [handle update requests](/guides/platform-payments/onboarding-sellers/seller-onboarding-update-requests) and [subscribe to lifecycle notifications](/guides/platform-payments/onboarding-sellers/seller-onboarding-notifications-and-webhooks) to move your sellers through the onboarding process. --- # Seller Onboarding Notifications and Webhooks Source: https://docs.finix.com/guides/platform-payments/onboarding-sellers/seller-onboarding-notifications-and-webhooks Learn how to get notified about updates throughout the seller onboarding process Sellers go through several steps during onboarding – for example, from submitting an onboarding form to getting approved. To keep your team in-the-loop about your sellers' progress during onboarding, Finix offers notifications in multiple formats: dashboard and email, as well as developer webhooks. ## Notifications Finix offers notifications for these onboarding lifecycle events: 1. Onboarding Form Submitted 2. Merchant Approved 3. Merchant Rejected 4. Merchant Updates Requested 5. Merchant Updates Submitted ### Subscribing to notifications You can subscribe to notifications by visiting **Settings > User > Notification Settings**. You can subscribe to Dashboard or email notifications for each lifecycle event individually. Seller Onboarding Notifications ### Viewing notifications When one of your Merchants moves through any of those lifecycle events, Finix will notify you via Dashboard and/or email. On the Dashboard, you will see notifications under the **bell icon**, as well as floating on the righthand side of your page. Seller Onboarding Notifications ## Webhooks | Lifecycle event | `entity` | `type` | `_embedded` | | --- | --- | --- | --- | | Merchant Created | `merchant` | `created` | `merchants[0].onboarding_state: PROVISIONING` | | `verification` | `created` | `verifications[0].state: PENDING` | | Merchant Approved | `merchant` | `underwritten` | `merchants[0].onboarding_state: APPROVED` | | `merchant` | `updated` | `merchants[0].onboarding_state: APPROVED` | | `verification` | `updated` | `verifications[0].state: SUCCEEDED` | | Merchant Rejected | `merchant` | `updated` | `merchants[0].onboarding_state: REJECTED` | | `verification` | `updated` | `verifications[0].state: FAILED` | | Updates Requested | `merchant` | `updated` | `merchants[0].onboarding_state: UPDATE_REQUESTED` | | `verification` | `updated` | `verifications[0].state: FAILED` | | Updates Submitted | `verification` | `created` | `verifications[0].state: PENDING` | See our webhooks guide for information on how to integrate into our webhooks. --- # Seller Onboarding Process Source: https://docs.finix.com/guides/platform-payments/onboarding-sellers/seller-onboarding-process Learn how to onboard your sellers. Whether you onboard your sellers with Finix's low-code / no-code Onboarding Forms, or use Finix's APIs directly, our onboarding process follows these steps: br Seller Onboarding Diagram ## Seller consent Finix requires that sellers are presented with and agree to your Terms of Service and payment processing fees, as well as Finix's Terms of Service and Privacy Policy. Finix's Onboarding Forms present and collect consent to these materials seamlessly, making the process hands-off. If you onboard your sellers with Finix's APIs directly, you will need to build the process for presenting and collecting consent to these materials, as well as send the e-signature details to Finix. ## Collected information Finix collects business, ownership, processing, and bank account information from your sellers. The exact required fields and data formats vary by sellers' business types and country. For more information, see Onboarding Data. ### Business information Finix collects details about your sellers' business, and verifies these details as part of the customer identification process to help protect you and your sellers. - Business address - Business description - Business incorporation date - Business name - Business phone number - Business tax ID - Business website - Doing business as (DBA) - Ownership type ### Ownership information Finix collects details about your sellers' control owner, as well as any beneficial owners with at least 25% ownership of the business. Finix verifies these details as part of the customer identification process, helping protect both you and your sellers. Finix does not conduct hard credit checks on your sellers. - Birthdate - Business email - Full legal name - Home address - Job title - Ownership percentage - Personal phone number - Personal tax ID - Identity verification Collecting government IDs and selfies is an effective tool for mitigating fraud and identity theft. If you have concerns about Finix collecting and verifying this information, please contact your Finix representative. Finix requires all entities to have at least one Control Person or Beneficial Owner who resides in the same country where the business is located and operates in. ### Processing information Finix collects information about your sellers' processing activity to help configure their merchant account, including setting the maximum transaction amounts and Merchant Category Code (MCC) for processing payments. - Card volume distribution - Merchant Category Code (MCC) - Processing volume - Refund policy - Statement descriptor - Transaction sizes ### Bank account information Finix collects information about the bank account to send your seller's payouts. Finix verifies the bank account details and adds it to your seller's merchant account. Optionally, Finix supports providing these details through Plaid. - Account name - Account number - Account type - Routing number Additional documentation required for Canadian sellers Canadian sellers must provide **one** of the following as part of credit risk underwriting: - A signed Credit Authorization Form (allows a soft credit pull) - 3 months of recent bank statements - 3 months of recent processing statements For restricted or high-risk Canadian merchants, **all** of the following are required: - A signed Credit Authorization Form - 3 months of recent bank statements - 3 months of recent processing statements (or compiled financials covering 2+ years with interim) ## Review process Finix reviews seller information before approving payment processing, using both automated and manual underwriting. Occasionally, additional information or documents may be requested to complete the review. The Finix dashboard, Onboarding Forms, and APIs simplify and expedite this process, allowing sellers to start processing payments quickly. ## Merchant account Finix creates a Merchant account for your sellers during the onboarding process. The account transitions from `PROVISIONING` to `APPROVED` after the review process completes, at which point your seller is ready to accept payments. In the event Finix requests additional information from your seller, their account will move to an `UPDATE_REQUESTED` state that includes details about the information requested. Should Finix be unable to onboard your seller due to our risk decision, your seller's account will move to the `REJECTED` state. ## What's next? Continue reading to learn how to onboard your sellers with Finix's Onboarding Forms or APIs. --- # Handling Update Requests Source: https://docs.finix.com/guides/platform-payments/onboarding-sellers/seller-onboarding-update-requests Learn how to handle update requests when onboarding sellers. In some cases, Finix requests documents or data updates during the seller onboarding process. Finix requests these updates when we need additional information to verify your sellers (for example, if we cannot identify the bank account's owner), or when your seller's data is invalid (for example, if the bank account's routing number does not belong to a financial institution). When this happens, Finix will move the Merchant to the Update Requested state and re-review their application after receiving the requested updates. This guide explains how to handle update requests with our Dashboard and APIs. ## Handling Update Requests with the Dashboard ### Viewing update requests On the **Merchants > Merchant Accounts** page, you can see all Merchants in your system. The **Update Requested tab** shows all Merchants with outstanding update requests. To see the updates Finix has requested, you can check the **Onboarding State column**, or click on the Merchant to navigate to their account page. Merchant Accounts list with Update Requested tab selected On the Merchant page, you will find details about the documents and data updates Finix has requested. You may also see notes providing additional context about the requested updates (for example, we may include a note explaining that the bank account routing number is invalid). Merchant detail page showing requested document and data updates ### Making updates with Onboarding Forms If you boarded your Merchant with an Onboarding Form, your Merchant can make the requested updates using their original Onboarding Form. To do this, use the **Share Onboarding Form Link button**. Merchant detail page with Get Onboarding Form Link button Copy your Merchant's Onboarding Form link. You can send the link to your Merchant however you like (for example, over email). Dashboard modal showing merchant onboarding form link to copy Once your Merchant is back inside their Onboarding Form, they will see exactly which documents and data updates Finix has requested. They will have file uploaders for each document, and we will highlight each field they need to update in red [3]. Onboarding form with highlighted fields and file uploaders for requested updates After your Merchant completes the requested updates and re-submits their Onboarding Form, Finix will update their Onboarding State state back to Provisioning and re-review their application. No action is needed from your team at this point (Finix will automatically create a new verification on their account). ### Making updates with the Dashboard Alternatively, your team can make updates to your Merchants directly inside the Finix Dashboard. You might do this if you already have the requested documents or correct data on-hand, and prefer to handle the update request on behalf of your Merchant. You can upload documents on the Merchant page, as well as navigate to and edit their Identity to make data updates. Your Merchant can upload files through their own Dashboard as well. Merchant detail page showing file upload option for requested documents After uploading files or updating the Identity, your team must create a new verification on the Merchant to put the Merchant back in the underwriting process for further review. Merchant detail page showing option to create a new verification Finix advises making updates with Onboarding Forms to streamline this process, but offers the option to make updates through the Dashboard to give your team the most flexibility. ### Notifications Finix offers notifications through both email and the Finix dashboard, making it easy for your team to receive updates as your sellers progress through onboarding. For example, your team can subscribe to receive notifications when your sellers submit their Onboarding Forms and are approved. To learn more about notifications, see Notifications and Webhooks. ## Handling Update Requests with the API ### Merchant resource When Finix requests updates from your Merchant, your Merchant's `onboarding_state` will be `UPDATE_REQUESTED`. ```json Merchant { "id": "MUno35MtzSMr61mUvY7qCayR", "created_at": "2022-01-27T07:36:58.19Z", "updated_at": "2022-10-06T20:25:24.06Z", "application": "APgPDQrLD52TYvqazjHJJchM", "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": "IDpYDM7J9n57q849o9E9yNrG", "level_two_level_three_data_enabled": false, "mcc": "4900", "merchant_name": "Bobs Burgers", "merchant_profile": "MPzW2oRPtkLxK3fymcMACFi", "mid": "FNXh6htoPnfwmgGdvaG4L67Q1", "onboarding_state": "UPDATE_REQUESTED", "processing_enabled": true, "processor": "DUMMY_V1", "processor_details": {}, "ready_to_settle_upon": "RECONCILIATION", "rent_surcharges_enabled": false, "settlement_enabled": true, "settlement_funding_identifier": "UNSET", "surcharges_enabled": false, "tags": {}, "verification": "VIxfDrRKZZzkCDDbeCT15oDN", "_links": {} } ``` ### Verification resource When Finix requests updates from your Merchant, the Verification will have `state: FAILED`, as well as an `outcomes` array listing each `outcome_code` assigned to your Merchant. Use the Merchant's Verification ID (`verification`) to get the Verification. The Verification also includes two summary fields: - `outcome_summary` — An overall message from the Finix underwriting team providing context about the requested updates. This field is intended for your team, not your end users. - `outcome_message` — An optional per-outcome message from the underwriter providing additional context about a specific outcome code (for example, a note explaining exactly which format of bank statement is required). This field is only visible to Applications and should not be displayed to submerchants. Verification ```json Verification { "id": "VI5pMpAg6e5bRaMREhrYjwQW", "created_at": "2024-12-04T07:56:00.03Z", "updated_at": "2024-12-04T07:57:01.95Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "identity": null, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "messages": [], "outcome_summary": null, "outcomes": null, "payment_instrument": null, "payment_instrument_verification_details": { "billing_currency": null, "card_type": null, "issuer_country": null, "pull_from_card_cross_border": null, "pull_from_card_domestic": null, "push_to_card_cross_border": null, "push_to_card_domestic": null }, "processor": "DUMMY_V1", "raw": "RawDummyMerchantUnderwriteResult", "reverification_reason": { "review_type": null, "initiated_by": null, "reason_description": null }, "state": "SUCCEEDED", // [!code highlight] "sub_type": null, "tags": {}, "trace_id": "26577eee-2db9-4707-85f6-5b8f9c1e5376", "type": "MERCHANT", // [!code highlight] "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/verifications/VI5pMpAg6e5bRaMREhrYjwQW" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MUmfEGv5bMpSJ9k5TFRUjkmm" } } } ``` #### Outcomes array Each object in `outcomes` has the following properties, including `remediation_details` that describe how to resolve the outcome codes to get your Merchant boarded. | Field | Description | Example | | --- | --- | --- | | `outcome_code` | Outcome code | `BANK_STATEMENT_ONE_MONTH_REQUESTED` | | `outcome_message` | An optional message from the Finix underwriting team providing additional context about the specific outcome code. Only visible to Applications, not submerchants. | `Please provide a signed bank letter for this account.` | | `remediation_details.type` | Update type requested | `FILE_UPLOAD`, `FIELD_UPDATE` | | `remediation_details.file_type` | File to upload | `BANK_STATEMENT_ONE_MONTH` | | `remediation_details.field_name` | Field to update | `entity.business_tax_id` | | `remediation_details.entity_type` | Type of resource to update | `IDENTITY` | | `remediation_details.entity_id` | ID of resource to update | `ID5ZbV3hkc7eLxNhmFjfrrYA` | ### Onboarding Form resource If you boarded your Merchant with an Onboarding Form, their Onboarding Form will have `status: UPDATE_REQUESTED` when Finix requests updates from them. When your Merchant resubmits their Onboarding Form, it will move back to `status: COMPLETED`. ```json Onboarding Form { "id": "obf_cJUfiz97L8de54EwkC3Hiu", "onboarding_data": { "entity": {...}, "associated_entities": [...], "payment_instruments": {...}, "additional_underwriting_data": {...}, "max_transaction_amount": 100000 }, "merchant_processors": [...], "onboarding_link_details": {...}, "onboarding_link": {...}, "status": "UPDATE_REQUESTED", "identity_id": null, "application_id": "APgPDQrLD52TYvqazjHJJchM", "created_at": "2023-03-30T19:16:28.377022Z", "updated_at": "2023-03-30T19:16:28.377022Z", "tags": {} } ``` ### Updating fields If the Verification has any outcomes with `remediation_details.type: FIELD_UPDATE`, you will need to update the specified Identity based on the `field_name` and `entity_id`. In the example below, you would need to update `business_tax_id` for `ID5ZbV3hkc7eLxNhmFjfrrYA`. ```json Field Update Outcome Code { "outcome_code": "INVALID_BUSINESS_TAX_ID", "remediation_details": { "type": "FIELD_UPDATE", "field_name": "entity.business_tax_id", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } } ``` To perform these updates, Finix recommends asking your Merchants to review and update the specified fields within your application or onboarding flow. You can update the Identity with a `PUT` request. If you board a Merchant with any `associated_identities`, be sure to update the correct Identity when making the `PUT` request. ```shell Identity PUT Request curl "https://finix.sandbox-payments-api.com/identities/IDf6gK2XnWxriikmhQAeisoP" \ -H "Content-Type: application/json" \ -H "Finix-Version: 2022-02-01" \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ -X PUT \ -d '{ "entity": { "business_tax_id": "112222222" } }' ``` Finix does not include additional context in `remediation_details` that describe why the existing field is incorrect or the update was requested. However, Finix assigns these codes when we believe the fields have incorrect data. We recommend asking the Merchant to review and update the field as-needed. Finix may provide additional context on the requested updates through the `outcome_summary` field, but we do not recommend displaying this to your Merchant as it comes directly from the Finix underwriting team and is not meant for your end users. #### Updating bank accounts In some cases, Finix will assign outcome codes indicating that your Merchant's bank account details are incorrect (for example, Finix will assign `INVALID_PAYMENT_INSTRUMENT_BANK_CODE` if the bank account's routing number is invalid). To handle these outcome codes, you should collect the correct bank account details from your Merchant and create a new Payment Instrument: Example API Definition Example Payment Instrument - Bank Account ```json Payment Instrument - Bank Account { "id": "PI68E8eKh1v4P2eY2PoLrzzT", "created_at": "2026-09-25T20:05:25.37Z", "updated_at": "2026-09-25T20:05:25.37Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRxpMNPZbZqVQfcHzRUJnzkR", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "BANK_ACCOUNT", // [!code highlight] "microdeposit": "microdeposit_g92m9YHXhhndZcmFAUW7Ki", "microdeposit_verification_url": "https://link.sandbox-payment-form.com/DKDrmq", "account_type": "BUSINESS_CHECKING", "bank_account_validation_check": "NOT_ATTEMPTED", "bank_code": "122105278", "country": "USA", "institution_number": null, "masked_account_number": "XXXXXX0019", "name": "Smith & Associates Consulting", "transit_number": null, "tags": {}, "third_party": null, "third_party_token": null, "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` API Definition Finix does not support editing Payment Instruments' account and routing numbers, so we recommend always creating a new Payment Instrument when handling outcome codes for invalid bank account data. Jump to Outcome Codes to see the outcome codes for invalid bank account data. ### Uploading Files If the Verification has any outcomes with `remediation_details.type: FILE_UPLOAD`, you will need to upload Files linked to the specified Identity based on the `file_type` and `entity_id`. In the example below, you would need to upload a `BANK_STATEMENT_ONE_MONTH` File linked to `ID5ZbV3hkc7eLxNhmFjfrrYA`. ```json File Upload Outcome Code { "outcome_code": "BANK_STATEMENT_ONE_MONTH_REQUESTED", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "BANK_STATEMENT_ONE_MONTH", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } } ``` Jump to File Types to see the new File types Finix supports, and see Uploading Files to Finix for instructions on uploading Files to Finix via API or Dashboard. ### Merchant Verification After resolving all outcome codes by updating fields or uploading files, you are ready put your Merchant back into underwriting process for further review. To do this, create another verification on the Merchant. ### Webhooks Finix sends webhooks to update you about your seller's progress throughout the onboarding process. For example, you can listen to the Merchant Updated and Merchant Underwritten events to know when your Merchant transitions from PROVISIONING to another state. To learn more about webhooks, see Notifications and Webhooks. ## Outcome Codes ### Business outcome codes Finix assigns these outcome codes when there are issues related to your Merchant's business data. Use the `remediation_details` to know how to correct the issues and get the Merchant boarded. In these cases, the Merchant's `onboarding_state` is set to `UPDATE_REQUESTED`. File Uploads ```json Business File Upload Requests [ { "outcome_code": "BUSINESS_INCORPORATION_DOCUMENT_REQUESTED", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "BUSINESS_INCORPORATION_DOCUMENT", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BUSINESS_INCORPORATION_DOCUMENT", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "BUSINESS_INCORPORATION_DOCUMENT", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "BUSINESS_REGISTRATION_DOCUMENT_REQUESTED", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "BUSINESS_REGISTRATION_DOCUMENT", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BUSINESS_REGISTRATION_DOCUMENT", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "BUSINESS_REGISTRATION_DOCUMENT", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "BUSINESS_TAX_ID_DOCUMENT_REQUESTED", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "BUSINESS_TAX_ID_DOCUMENT", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BUSINESS_TAX_ID_DOCUMENT", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "BUSINESS_TAX_ID_DOCUMENT", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "BUSINESS_TAX_EXEMPTION_STATUS_DOCUMENT_REQUESTED", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "BUSINESS_TAX_EXEMPTION_STATUS_DOCUMENT", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BUSINESS_TAX_EXEMPTION_STATUS_DOCUMENT", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "BUSINESS_TAX_EXEMPTION_STATUS_DOCUMENT", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "BUSINESS_ADDRESS_DOCUMENT_REQUESTED", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "BUSINESS_ADDRESS_DOCUMENT", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BUSINESS_ADDRESS_DOCUMENT", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "BUSINESS_ADDRESS_DOCUMENT", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } } ] ``` Field Updates ```json Business Field Update Requests [ { "outcome_code": "INVALID_BUSINESS_ADDRESS", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.business_address", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BUSINESS_DBA", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.doing_business_as", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BUSINESS_DESCRIPTION", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.business_description", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BUSINESS_INCORPORATION_DATE", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.incorporation_date", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BUSINESS_MCC", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.mcc", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BUSINESS_NAME", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.business_name", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BUSINESS_OWNERSHIP_TYPE", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.ownership_type", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BUSINESS_PHONE", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.business_phone", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BUSINESS_TAX_ID", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.business_tax_id", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BUSINESS_TYPE", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.business_type", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BUSINESS_WEBSITE", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.url", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } } ] ``` ### Owner outcome codes Finix assigns these outcome codes when there are issues related to one or more of your Merchant's owners. Use the `remediation_details` to know how to correct the issues and get the Merchant boarded. In these cases, the Merchant's `onboarding_state` is set to `UPDATE_REQUESTED`. File Uploads ```json Owner File Upload Requests [ { "outcome_code": "OWNER_GOVERNMENT_ISSUED_PHOTO_ID_REQUESTED", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "OWNER_GOVERNMENT_ISSUED_PHOTO_ID", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_OWNER_GOVERNMENT_ISSUED_PHOTO_ID", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "OWNER_GOVERNMENT_ISSUED_PHOTO_ID", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "OWNER_TAX_ID_DOCUMENT_REQUESTED", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "OWNER_TAX_ID_DOCUMENT", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_OWNER_TAX_ID_DOCUMENT", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "OWNER_TAX_ID_DOCUMENT", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } } ] ``` Field Updates ```json Owner Field Update Requests [ { "outcome_code": "INVALID_OWNER_ADDRESS", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.personal_address", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_OWNER_BIRTHDATE", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.dob", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_OWNER_EMAIL", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.email", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_OWNER_FIRST_NAME", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.first_name", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_OWNER_LAST_NAME", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.last_name", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_OWNER_PHONE", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.phone", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_OWNER_TAX_ID", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.tax_id", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_OWNER_TITLE", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "entity.title", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } } ] ``` ### Bank account outcome codes Finix assigns these outcome codes when there are issues related to one or more of your Merchant's owners. Use the `remediation_details` to know how to correct the issues and get the Merchant boarded. In these cases, the Merchant's `onboarding_state` is set to `UPDATE_REQUESTED`. File Uploads ```json Owner File Upload Requests [ { "outcome_code": "BANK_STATEMENT_ONE_MONTH_REQUESTED", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "BANK_STATEMENT_ONE_MONTH", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BANK_STATEMENT_ONE_MONTH", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "BANK_STATEMENT_ONE_MONTH", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "BANK_STATEMENT_THREE_MONTHS_REQUESTED", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "BANK_STATEMENT_THREE_MONTHS", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_BANK_STATEMENT_THREE_MONTHS", "remediation_details": { "type": "FILE_UPLOAD", "file_type": "BANK_STATEMENT_THREE_MONTHS", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } } ] ``` Field Updates ```json Owner Field Update Requests [ { "outcome_code": "INVALID_PAYMENT_INSTRUMENT_NAME", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "name", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_PAYMENT_INSTRUMENT_BANK_CODE", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "bank_code", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } }, { "outcome_code": "INVALID_PAYMENT_INSTRUMENT_ACCOUNT_NUMBER", "remediation_details": { "type": "FIELD_UPDATE", "file_type": "account_number", "entity_type": "IDENTITY", "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA" } } ] ``` --- # Uploading Files Source: https://docs.finix.com/guides/platform-payments/onboarding-sellers/seller-onboarding-uploading-files Learn how to upload files to Finix. ## Uploading Files with the Dashboard To upload files from Finix's dashboard: 1. Inside your dashboard, navigate to your Seller's **Identity page** 2. On their Identity page, navigate to their **Files tab** 3. Use the **Upload File** button to upload their file You will see a green banner after the file uploads successfully. ## Uploading Files with the API To upload files with Finix's File API: 1. Create a `File` resource 2. Upload your file to the `File` resource Seller Onboarding File Upload Diagram ### Step 1: Create a File resource Create a File resource with the document's type, display name, and Merchant the file belongs to. ```shell Request curl "https://finix.sandbox-payments-api.com/files" \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X POST \ -d '{ "display_name": "Bank Statement (January 2024)", "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk", "type": "DRIVERS_LICENSE_FRONT" }' ``` ```json Response { "id": "FILE_aw97EbTRshpyiCjdHXhd3t", "status": "REQUIRES_UPLOAD", "created_at": "2025-12-05T16:27:32.899574Z", "updated_at": "2025-12-05T16:27:32.917596Z", "linked_type": "MERCHANT", "linked_to": "MUtaVJ3X6DFXfEox6fUSyqxt", "extension": null, "display_name": "Bank Statement (January 2024)", "type": "BANK_STATEMENT", "platform_id": "PLoMxXWbqwEMT5N1upSaNUbJ", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "tags": {}, "identity_id": "ID47veZZgBXfRGv9ZkFdgCLt", "entity_id": null, "entity_type": null, "size_in_bytes": null, "file_name": null } ``` ### Step 2: Upload your file to the File resource To upload your file to the `File` resource, you can either: 1. Upload the file directly (for example, if the file is stored on your own servers). 2. Use an `external_link` to let your seller upload the file directly from their browser. ### Option 1: Upload the file directly Use the `/upload` endpoint to upload the file directly to the `File` resource: ```shell Request curl "https://finix.sandbox-payments-api.com/files/FILE_qBwNnDHrpHv6xc1yQwLjNx/upload" \ -H 'Content-Type: multipart/form-data' \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -F "file=@{{file_path}}" ``` This request is asynchronous. Finix will respond with a `File` object with `status: PENDING`, and afterward the `status` to `UPLOADED` after the file finishes uploading (typically, this takes about 60 seconds). Uploading ```json File Resource { "id": "FILE_qBwNnDHrpHv6xc1yQwLjNx", "status": "PENDING", "created_at": "2025-12-05T16:45:16.953723Z", "updated_at": "2025-12-05T16:46:06.017533Z", "linked_type": "MERCHANT", "linked_to": "MUvWVhLpLj9w7kV1EXA7yvzc", "extension": "csv", "display_name": "bank_statement", "type": "BANK_STATEMENT_ONE_MONTH", "platform_id": "PLoMxXWbqwEMT5N1upSaNUbJ", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "tags": {}, "identity_id": "IDnT3ff71VShf6dB2ShcPozq", "entity_id": null, "entity_type": null, "size_in_bytes": 312, "file_name": "bank_statement_11052025.csv" } ``` Uploaded ```json File Resource { "id": "FILE_qBwNnDHrpHv6xc1yQwLjNx", "status": "UPLOADED", "created_at": "2025-12-05T16:45:16.953723Z", "updated_at": "2025-12-05T16:46:06.017533Z", "linked_type": "MERCHANT", "linked_to": "MUvWVhLpLj9w7kV1EXA7yvzc", "extension": "csv", "display_name": "bank_statement", "type": "BANK_STATEMENT_ONE_MONTH", "platform_id": "PLoMxXWbqwEMT5N1upSaNUbJ", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "tags": {}, "identity_id": "IDnT3ff71VShf6dB2ShcPozq", "entity_id": null, "entity_type": null, "size_in_bytes": 312, "file_name": "bank_statement_11052025.csv" } ``` ### Option 2: Upload the file with an `external_link` Alternatively, you can create an `external_link` that your user can use to upload the file directly from their browser. This lets your users upload documents without the files ever touching your own servers. To do this, start by creating an `external_link` with `type: UPLOAD`. ```shell External Link Request curl "https://finix.sandbox-payments-api.com/files/FILE_jyLRzpcLcvUh8yCuTdRJE8/external_links" \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -d '{ "duration": 15, "type": "UPLOAD" }' ``` ```json External Link Response { "id": "EL_3zJ3B4UYMWrLPyYSdL65hX", "created_at": "2024-08-27T22:09:51.396334Z", "url": "https://finix-file-quarantine-sb.s3.us-east-2.amazonaws.com/MERCHANT/MU2n7BSovtwYsWYZF6rBnnzk/DRIVERS_LICENSE_FRONT/FILE_vhbDpyGKGUAUtBZnBv67AQ/file?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEAYaCXVzLWVhc3QtMiJHMEUCIQDqZMMyXnwQkuWLRrOOyLoQnqaOZKpz8UDTq07CDgdDrgIgL1XJpGqc9nJPAJ6vHOgxG%2F8XRsxD4idH7dQ%2BrdnKlG4q%2BQQIHxACGgwzNzU2MzU1NzAwNzAiDHZtIXMx1embf%2BSOMirWBB77UW%2FTQu19mMt7ERQjJ5IYVR%2BykbtVYVQXFYrVLg6Hla5Qv8ncxm3%2BiWnN9%2BcWlnz1d0g1lX7indpff8tjHbnZRrLVNbfJbKQISRgb5qIxcHKXfUuvZvBYKhlqZe%2BEJ3x%2BbD1A4EdLf35wRFq%2FZscST24XGIQkB99GaJeaEH0pL%2BrWdhgE%2FpJHxuTfCVVR6sia7tLltC3CSwd8DJZCrqIEZjaFa69I%2FXvcwnz3VRvofEcgUcbEGTrUCmWS3cK1IpcvBZg1dQj4KC6Ds8%2FSK7DaWDfEtYpwyKfRVGDE6PzbHsNHkn7GEtM7%2FQcZ18mReMOzb0kjd5apPvbrLJiduxOAJC3q7lRRn3NN24mhc844PLrZAKgD4XqDuRUzh1IQrCByWAE%2Boq8pnRwGMfMzVHkr%2FXCiJrQzt7rGh1okNxFx8WR5You4xN1uHLeZuN9AHa37wMB%2FMAIS12NwmHwSy9WO5c60rnS8sof0qCEiN4Qx3uLr8LLc%2F3JeEEni1Tb2Og3kcnY0qZmSXKHZe7r3dSvet6RVT33Cxt8YIzwKWdCMy%2FT7ACE%2Br5mJWMynmLXfs%2B2nceYYWoabSTAoMte%2BRz%2BgsCqmTRg9eXns8ITFH7nxakDhf3zLDqByWHIkBRlv0SVAKb%2F31tGzeAdGheAF1zaltbVEnAwz7U0zFPeDtKpRXxiBcXivUpHHHEkXHJeIHjdfM1r%2FH6E7ASY4CSvbw3eMEw9j1EB0eLxej8xquTRpW6%2F5adT0bcfM0ZGEt3EjD7YFKtGvs4wuzmhG4imJS7c%2BoAnFXIww1pm5tgY6mgFXwaweuRLsT4LlKvxRBw1Kj0%2BeyMjTwgWnINHAVGzrmt4XHfHrZxEyY0CCF%2Fw%2B1yjxxRFwMT83zzgI4YzLF%2FX6nK989O9Lv%2F6QrIO%2Fx5am9ksDCybEkth5u1hkSuaUV4pZP4fZjSqTzM1j%2B3JMVSPsVdnCVPW8UFTKuuFk1y62ImovKuAcET1Pq4JRUc2AZkjNPRUkC6HewLSk&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240827T220951Z&X-Amz-SignedHeaders=host&X-Amz-Expires=899&X-Amz-Credential=ASIAVO5M75WLGULA5QPJ%2F20240827%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Signature=5e973b4aa7a7f6ac4026b88bf1470efa334bde06adb51837e559b74c7df06ae6", "type": "UPLOAD", "expires_at": "2024-08-27T22:24:51.380464Z", "user_id": "USsRhsHYZGBPnQw8CByJyEQW", "file_id": "FILE_vhbDpyGKGUAUtBZnBv67AQ", "duration": null, "tags": {}, "expired": false } ``` See below for an example of how to embed the `external_link` into an HTML form, including making a `PUT` request to the `url` to upload the file. ```html Embedded External Link Snippet File Upload
``` ## File types ### Bank statement (one month) - Type: `BANK_STATEMENT_ONE_MONTH` - Accepted documents: 1 month bank statements, signed bank verification letter, and voided checks - Expected format: Account number, routing number, and account owner name must be clearly visible ### Bank statement (three months) - Type: `BANK_STATEMENT_THREE_MONTHS` - Accepted documents: 3 month bank statements - Expected format: Account number, routing number, and account owner name must be clearly visible ### Business incorporation document - Type: `BUSINESS_INCORPORATION_DOCUMENT` - Accepted documents: Articles of Incorporation - Expected format: Must be original business registration document ### Business registration document - Type: `BUSINESS_REGISTRATION_DOCUMENT` - Accepted documents: Secretary of State filing - Expected format: Must be active state filing ### Business tax ID document - Type: `BUSINESS_TAX_ID_DOCUMENT` - Accepted documents: Form CP-575, Form 147C - Expected format: Must not be EIN Application form ### Business tax exemption status document - Type: `BUSINESS_TAX_EXEMPTION_STATUS_DOCUMENT` - Accepted documents: Form 1023-EZ, Form T3010 (CAN) - Expected format: Must prove business tax exemption status ### Business address document - Type: `BUSINESS_ADDRESS_DOCUMENT` - Accepted documents: Utility bill, lease - Expected format: Must display active business address ### Business ownership structure - Type: `BUSINESS_OWNERSHIP_STRUCTURE` - Accepted documents: Diagram, cap table - Expected format: Must illustrate business ownership structure ### Owner government-issued photo ID - Type: `OWNER_GOVERNMENT_ISSUED_PHOTO_ID` - Accepted documents: Driver's License, passport, residence card - Expected format: Must clearly show owner's name and face and not be expired ### Owner tax ID document - Type: `OWNER_TAX_ID_DOCUMENT` - Accepted documents: SSN Card, TIN Card, SIN Card (CAN) - Expected format: Must clearly show owner's name and tax ID and not be expired --- # Seller Onboarding via API Source: https://docs.finix.com/guides/platform-payments/onboarding-sellers/seller-onboarding-via-api Learn how to onboard your sellers with Finix APIs. Finix offers APIs to onboard your sellers directly to Finix. The process follows the same steps as our Onboarding Forms, while giving you the most control over your seller's onboarding experience. For example, you might build your own hosted onboarding solution on top of Finix's APIs if you board a high volume of merchants or want full control over the user experience. Onboarding sellers via API involves 5 steps: 1. Collect your sellers' information and consent to the onboarding process 2. Create an Identity with your seller's business and personal information 3. Create a Payment Instrument with your seller's bank account information 4. Create a Merchant that your seller will use to process payments 5. Listen for updates to the Merchant account as Finix reviews your seller Seller Onboarding Forms Diagram ## Step 1: Collect information and consent To board sellers directly via API, Finix requires that you: - Collect your sellers' business, ownership, processing, and bank account information - Present language to your sellers that their information will be verified - Present both Finix's and your own terms of service to your sellers - Present your payment processing fees to your sellers ### Collecting information Finix requires you collect the following information about your sellers: 1. **Business information:** Finix collects data about your seller's business, such as their business name 2. **Owner information:** Finix collects data about your seller's control person, such as their personal name 3. **Processing information:** Finix collects data about your seller's processing information, such as volumes 4. **Bank account information:** Finix collects details about your seller's bank account for their payouts See Onboarding Data and Identities for the full list of required fields and data formats. #### Collecting bank account information When collecting bank account information, you must use the following language to communicate to your sellers that the bank account provided should only be used for business purposes: ```text You agree to use this bank account for legitimate business purposes, and not for personal, family, or household purposes. ``` ### Verification consent You must present your sellers with language informing them that they are applying for payment processing services, and that their identity will be verified. Please add the following text at the beginning of your onboarding process: ```text The information you provide will be used to verify your identity. Additional information may be requested. ``` ### Terms of service You must present both Finix's and your own terms of service to your sellers, which your sellers must explicitly consent to via click-through agreement. Please add the following text to your onboarding process, which should hyperlink to both Finix's and your own terms of service: ```text By continuing, you agree to our Terms of Service and the Finix Terms of Service. ``` The Finix Terms of Service version you link to varies by your seller's business country and payment processor: | Country | Processor | ToS Version | | --- | --- | --- | | United States (USA) | `FINIX_V1` | [Finix Terms of Service (USA - FINIX_V1)](https://finix-hosted-content.s3.amazonaws.com/flex/v3/finix-terms-of-service.html) | | United States (USA) | `LITLE_V1` | [Finix Terms of Service (USA - LITLE_V1/VANTIV_V1)](https://finix-hosted-content.s3.amazonaws.com/flex/v2/finix-terms-of-service.html) | | United States (USA) | `VANTIV_V1` | [Finix Terms of Service (USA - LITLE_V1/VANTIV_V1)](https://finix-hosted-content.s3.amazonaws.com/flex/v2/finix-terms-of-service.html) | | Canada (CAN) | `FINIX_V1` | [Finix Terms of Service (Canada)](https://finix-hosted-content.s3.amazonaws.com/flex/v3/finix-terms-of-service-canada.html) | Finix will collect information about your seller's consent on the `Identity` resource in the next step. ### Presenting fees You must present your payment processing fees to your sellers clearly and prominently in your onboarding process. You must also communicate fee changes to your sellers with prior notice. ## Step 2: Create an Identity After the previous step is complete, you are ready to create an `Identity` for your seller. The `Identity` holds the business, personal, processing, and consent information from your seller, which Finix underwrites during the review process. Each `Identity` can hold one person's information; should your seller's business have one or more beneficial owners with 25% or more ownership, you must create an `Associated Identity` for each beneficial owner. See Onboarding Data and Identities for the full list of required fields and data formats. USA ```shell Request curl -X POST \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ https://finix.sandbox-payments-api.com/identities \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "additional_underwriting_data": { "annual_ach_volume": 200000, "average_ach_transfer_amount": 200000, "average_card_transfer_amount": 200000, "business_description": "SB3 vegan cafe", "card_volume_distribution": { "card_present_percentage": 30, "mail_order_telephone_order_percentage": 10, "ecommerce_percentage": 60 }, "credit_check_allowed": true, "credit_check_ip_address": "42.1.1.112", "credit_check_timestamp": "2021-04-28T16:42:55Z", "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)", "merchant_agreement_accepted": true, "merchant_agreement_ip_address": "42.1.1.113", "merchant_agreement_timestamp": "2021-04-28T16:42:55Z", "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)", "refund_policy": "MERCHANDISE_EXCHANGE_ONLY", "volume_distribution_by_business_type": { "other_volume_percentage": 0, "consumer_to_consumer_volume_percentage": 0, "business_to_consumer_volume_percentage": 0, "business_to_business_volume_percentage": 100, "person_to_person_volume_percentage": 0 } }, "entity": { "annual_card_volume": 12000000, "business_address": { "city": "San Mateo", "country": "USA", "region": "CA", "line2": "Apartment 8", "line1": "741 Douglass St", "postal_code": "94114" }, "business_name": "Finix Flowers", "business_phone": "+1 (408) 756-4497", "business_tax_id": "123456789", "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP", "default_statement_descriptor": "Finix Flowers", "dob": { "year": 1978, "day": 27, "month": 6 }, "doing_business_as": "Finix Flowers", "email": "user@example.org", "first_name": "John", "has_accepted_credit_cards_previously": true, "incorporation_date": { "year": 1978, "day": 27, "month": 6 }, "last_name": "Smith", "max_transaction_amount": 1200000, "ach_max_transaction_amount": 1000000, "mcc": "4900", "ownership_type": "PRIVATE", "personal_address": { "city": "San Mateo", "country": "USA", "region": "CA", "line2": "Apartment 7", "line1": "741 Douglass St", "postal_code": "94114" }, "phone": "14158885080", "principal_percentage_ownership": 50, "tax_id": "123456789", "title": "CEO", "url": "https://www.finix.com" }, "identity_roles": ["SELLER"], "tags": { "Studio Rating": "4.7" }, "type": "BUSINESS" }' ``` ```json Response { "id": "IDfbYwPeMVE2dVWbGuuZxMyD", "created_at": "2024-08-15T21:25:53.55Z", "updated_at": "2024-08-15T21:25:53.55Z", "additional_underwriting_data": { "refund_policy": "MERCHANDISE_EXCHANGE_ONLY", "credit_check_ip_address": "42.1.1.112", "card_volume_distribution": { "card_present_percentage": 30, "mail_order_telephone_order_percentage": 10, "ecommerce_percentage": 60 }, "average_ach_transfer_amount": 200000, "average_card_transfer_amount": 200000, "merchant_agreement_accepted": true, "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)", "merchant_agreement_ip_address": "42.1.1.113", "annual_ach_volume": 200000, "credit_check_allowed": true, "business_description": "SB3 vegan cafe", "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)", "volume_distribution_by_business_type": { "other_volume_percentage": 0, "consumer_to_consumer_volume_percentage": 0, "business_to_consumer_volume_percentage": 0, "business_to_business_volume_percentage": 100, "person_to_person_volume_percentage": 0 }, "credit_check_timestamp": "2021-04-28T16:42:55Z", "merchant_agreement_timestamp": "2021-04-28T16:42:55Z" }, "application": "APgPDQrLD52TYvqazjHJJchM", "entity": { "ach_max_transaction_amount": 1000000, "amex_mid": null, "annual_card_volume": 12000000, "business_address": { "line1": "741 Douglass St", "line2": "Apartment 8", "city": "San Mateo", "region": "CA", "postal_code": "94114", "country": "USA" }, "business_name": "Finix Flowers", "business_phone": "+1 (408) 756-4497", "business_tax_id_provided": true, "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP", "default_statement_descriptor": "Finix Flowers", "discover_mid": null, "dob": { "day": 27, "month": 6, "year": 1978 }, "doing_business_as": "Finix Flowers", "email": "user@example.org", "first_name": "John", "has_accepted_credit_cards_previously": true, "incorporation_date": { "day": 27, "month": 6, "year": 1978 }, "last_name": "Smith", "max_transaction_amount": 1200000, "mcc": "4900", "ownership_type": "PRIVATE", "personal_address": { "line1": "741 Douglass St", "line2": "Apartment 7", "city": "San Mateo", "region": "CA", "postal_code": "94114", "country": "USA" }, "phone": "14158885080", "principal_percentage_ownership": 50, "short_business_name": null, "tax_authority": null, "tax_id_provided": true, "title": "CEO", "url": "https://www.finix.com" }, "identity_roles": ["SELLER"], "tags": { "Studio Rating": "4.7" }, "type": "BUSINESS", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" } } } ``` Canada ```shell Request curl -X POST \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ https://finix.sandbox-payments-api.com/identities \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "additional_underwriting_data": { "annual_ach_volume": 200000, "average_ach_transfer_amount": 200000, "average_card_transfer_amount": 200000, "business_description": "Business offering video editing services.", "card_volume_distribution": { "card_present_percentage": 30, "mail_order_telephone_order_percentage": 10, "ecommerce_percentage": 60 }, "credit_check_allowed": true, "credit_check_ip_address": "42.1.1.112", "credit_check_timestamp": "2021-04-28T16:42:55Z", "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)", "merchant_agreement_accepted": true, "merchant_agreement_ip_address": "42.1.1.113", "merchant_agreement_timestamp": "2021-04-28T16:42:55Z", "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)", "refund_policy": "MERCHANDISE_EXCHANGE_ONLY", "volume_distribution_by_business_type": { "other_volume_percentage": 0, "consumer_to_consumer_volume_percentage": 0, "business_to_consumer_volume_percentage": 0, "business_to_business_volume_percentage": 100, "person_to_person_volume_percentage": 0 } }, "entity": { "annual_card_volume": 12000000, "business_address": { "city": "Vancouver", "country": "CAN", "region": "BC", "line2": null, "line1": "456 Elm Avenue", "postal_code": "V6B 2L2" }, "business_name": "Video Editing Services", "business_phone": "+1 (416) 555-7890", "business_tax_id": "123456789", "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP", "default_statement_descriptor": "Video Services", "dob": { "year": 1978, "day": 27, "month": 6 }, "doing_business_as": "Video Editing Services", "email": "info@video-editing-services.com", "first_name": "Jerry", "has_accepted_credit_cards_previously": true, "incorporation_date": { "year": 1978, "day": 27, "month": 6 }, "last_name": "Dunhill", "max_transaction_amount": 1200000, "ach_max_transaction_amount": 1000000, "mcc": "4900", "ownership_type": "PRIVATE", "personal_address": { "city": "Vancouver", "country": "CAN", "region": "BC", "line2": null, "line1": "987 Milo Street", "postal_code": "V5K 1Z5" }, "phone": "14158885080", "principal_percentage_ownership": 50, "tax_id": "123456789", "title": "CEO", "url": "https://www.video-editing-services.com" }, "identity_roles": ["SELLER"], "tags": { "Studio Rating": "4.7" }, "type": "BUSINESS" }' ``` ```json Response { "id": "IDpNvpkgXiBMArDrGWJ3JRG9", "created_at": "2024-08-15T21:26:54.36Z", "updated_at": "2024-08-15T21:26:54.36Z", "additional_underwriting_data": { "refund_policy": "MERCHANDISE_EXCHANGE_ONLY", "credit_check_ip_address": "42.1.1.112", "card_volume_distribution": { "card_present_percentage": 30, "mail_order_telephone_order_percentage": 10, "ecommerce_percentage": 60 }, "average_ach_transfer_amount": 200000, "average_card_transfer_amount": 200000, "merchant_agreement_accepted": true, "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)", "merchant_agreement_ip_address": "42.1.1.113", "annual_ach_volume": 200000, "credit_check_allowed": true, "business_description": "Business offering video editing services.", "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)", "volume_distribution_by_business_type": { "other_volume_percentage": 0, "consumer_to_consumer_volume_percentage": 0, "business_to_consumer_volume_percentage": 0, "business_to_business_volume_percentage": 100, "person_to_person_volume_percentage": 0 }, "credit_check_timestamp": "2021-04-28T16:42:55Z", "merchant_agreement_timestamp": "2021-04-28T16:42:55Z" }, "application": "APgPDQrLD52TYvqazjHJJchM", "entity": { "ach_max_transaction_amount": 1000000, "amex_mid": null, "annual_card_volume": 12000000, "business_address": { "line1": "456 Elm Avenue", "line2": null, "city": "Vancouver", "region": "BC", "postal_code": "V6B 2L2", "country": "CAN" }, "business_name": "Video Editing Services", "business_phone": "+1 (416) 555-7890", "business_tax_id_provided": true, "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP", "default_statement_descriptor": "Video Services", "discover_mid": null, "dob": { "day": 27, "month": 6, "year": 1978 }, "doing_business_as": "Video Editing Services", "email": "info@video-editing-services.com", "first_name": "Jerry", "has_accepted_credit_cards_previously": true, "incorporation_date": { "day": 27, "month": 6, "year": 1978 }, "last_name": "Dunhill", "max_transaction_amount": 1200000, "mcc": "4900", "ownership_type": "PRIVATE", "personal_address": { "line1": "987 Milo Street", "line2": null, "city": "Vancouver", "region": "BC", "postal_code": "V5K 1Z5", "country": "CAN" }, "phone": "14158885080", "principal_percentage_ownership": 50, "short_business_name": null, "tax_authority": null, "tax_id_provided": true, "title": "CEO", "url": "https://www.video-editing-services.com" }, "identity_roles": ["SELLER"], "tags": { "Studio Rating": "4.7" }, "type": "BUSINESS", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" } } } ``` Associated Identity ```shell Request curl -X POST \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/associated_identities \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "entity": { "first_name": "John", "last_name": "Smith", "title": "Founder", "dob": { "month": 1, "day": 1, "year": 2013 }, "principal_percentage_ownership": 25, "phone": "14158885080", "personal_address": { "city": "San Francisco", "region": "CA", "postal_code": "90650", "line1": "123 Main Street", "country": "USA" }, "email": "john.smith@company1.com", "tax_id": "123456789" } }' ``` ```json Response { "id": "IDmqEnFc9DQDAEraGkAZr9Ss", "created_at": "2024-08-15T21:33:07.73Z", "updated_at": "2024-08-15T21:33:07.73Z", "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": { "day": 1, "month": 1, "year": 2013 }, "doing_business_as": null, "email": "john.smith@company1.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": "123 Main Street", "line2": null, "city": "San Francisco", "region": "CA", "postal_code": "90650", "country": "USA" }, "phone": "14158885080", "principal_percentage_ownership": 25, "short_business_name": null, "tax_authority": null, "tax_id_provided": true, "title": "Founder", "url": null }, "identity_roles": ["BENEFICIAL_OWNER"], "tags": {}, "type": "PERSONAL", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" } } } ``` ## Step 3: Add a bank account Next, you're ready to link your seller's bank account to their Identity with the Payment Instruments API. This is the bank account to which your seller will receive payouts, and is reviewed during Finix's seller underwriting process. Note that step is required for the next step's request (creating your seller's Merchant) to succeed. You can create the Payment Instrument with your seller's bank account information directly. Alternatively, you can create the Payment Instrument using a Plaid Processor Token (see our Plaid guide for additional context). USA ```shell Request curl -X POST \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ https://finix.sandbox-payments-api.com/payment_instruments \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "account_number": "0000000019", "account_type": "BUSINESS_CHECKING", "bank_code": "122105278", "identity": "IDfbYwPeMVE2dVWbGuuZxMyD", "name": "Smith & Associates Consulting", "type": "BANK_ACCOUNT" }' ``` ```json Response { "id": "PI3dGTEWFHC8XHZrqpHBHpHc", "created_at": "2024-08-16T12:23:02.94Z", "updated_at": "2024-08-16T12:23:02.94Z", "application": "APgPDQrLD52TYvqazjHJJchM", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRxpMNPZbZqVQfcHzRUJnzkR", "identity": "IDfbYwPeMVE2dVWbGuuZxMyD", "instrument_type": "BANK_ACCOUNT", "account_type": "BUSINESS_CHECKING", "bank_account_validation_check": "NOT_ATTEMPTED", "bank_code": "122105278", "country": "USA", "institution_number": null, "masked_account_number": "XXXXXX0019", "name": "Smith & Associates Consulting", "transit_number": null, "tags": {}, "third_party": null, "third_party_token": null, "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI3dGTEWFHC8XHZrqpHBHpHc" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI3dGTEWFHC8XHZrqpHBHpHc/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI3dGTEWFHC8XHZrqpHBHpHc/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI3dGTEWFHC8XHZrqpHBHpHc/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD" } } } ``` Canada ```shell Request curl -X POST \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ https://finix.sandbox-payments-api.com/payment_instruments \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "account_number": "123123123", "account_type": "PERSONAL_CHECKING", "country": "CAN", "currency": "CAD", "identity": "IDpNvpkgXiBMArDrGWJ3JRG9", "institution_number": "123", "name": "John Smith", "transit_number": "12345", "type": "BANK_ACCOUNT" }' ``` ```json Response { "id": "PIwTCBS1DaTQZA93VSnSRFUL", "created_at": "2024-08-16T12:24:50.07Z", "updated_at": "2024-08-16T12:24:50.07Z", "application": "APgPDQrLD52TYvqazjHJJchM", "created_via": "API", "currency": "CAD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPR8RAHfXm1BMYYVJyHWHhw4J", "identity": "IDpNvpkgXiBMArDrGWJ3JRG9", "instrument_type": "BANK_ACCOUNT", "account_type": "PERSONAL_CHECKING", "bank_account_validation_check": "NOT_ATTEMPTED", "bank_code": null, "country": "CAN", "institution_number": "123", "masked_account_number": "XXXXX3123", "name": "John Smith", "transit_number": "12345", "tags": {}, "third_party": null, "third_party_token": null, "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwTCBS1DaTQZA93VSnSRFUL" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwTCBS1DaTQZA93VSnSRFUL/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwTCBS1DaTQZA93VSnSRFUL/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwTCBS1DaTQZA93VSnSRFUL/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9" } } } ``` Plaid ```shell Request curl -X POST \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ https://finix.sandbox-payments-api.com/payment_instruments \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "third_party": "PLAID", "third_party_token": "processor-sandbox-4855f0a2-c6f4-440c-9e6b-1d0ad9ca0010", "type": "BANK_ACCOUNT", "identity": "IDfbYwPeMVE2dVWbGuuZxMyD" }' ``` ```json Response { "id": "IDmqEnFc9DQDAEraGkAZr9Ss", "created_at": "2024-08-15T21:33:07.73Z", "updated_at": "2024-08-15T21:33:07.73Z", "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": { "day": 1, "month": 1, "year": 2013 }, "doing_business_as": null, "email": "john.smith@company1.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": "123 Main Street", "line2": null, "city": "San Francisco", "region": "CA", "postal_code": "90650", "country": "USA" }, "phone": "14158885080", "principal_percentage_ownership": 25, "short_business_name": null, "tax_authority": null, "tax_id_provided": true, "title": "Founder", "url": null }, "identity_roles": ["BENEFICIAL_OWNER"], "tags": {}, "type": "PERSONAL", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" } } } ``` ## Step 4: Create a Merchant With your seller's Identity and Payment Instrument created, you are ready to create your seller's Merchant. This step creates the Merchant account that your seller will use to process payments once approved. When you create the Merchant account, Finix automatically creates a Verification on the Merchant, which puts the Merchant into Finix's underwriting process. Each Merchant can use one payments processor; should your seller need multiple processors, you may create one Merchant per processor. USA ```shell Request curl -X POST \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/merchants \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "processor": "DUMMY_V1" }' ``` ```json Response { "id": "MUa2uYEkaRBzP8EEDeKweE5h", "created_at": "2024-08-16T12:23:30.79Z", "updated_at": "2024-08-16T12:23:30.79Z", "application": "APgPDQrLD52TYvqazjHJJchM", "card_cvv_required": false, "card_expiration_date_required": true, "card_network_details": null, "convenience_charges_enabled": false, "country": "USA", "creating_transfer_from_report_enabled": true, "currencies": ["USD"], "default_partial_authorization_enabled": false, "disbursements_ach_pull_enabled": false, "disbursements_ach_push_enabled": false, "disbursements_card_pull_enabled": false, "disbursements_card_push_enabled": false, "disbursements_same_day_ach_pull_enabled": false, "disbursements_same_day_ach_push_enabled": false, "fee_ready_to_settle_upon": "RECONCILIATION", "gateway": null, "gross_settlement_enabled": false, "identity": "IDfbYwPeMVE2dVWbGuuZxMyD", "level_two_level_three_data_enabled": false, "loan_repayment": null, "mcc": "4900", "merchant_name": "Finix Flowers", "merchant_profile": "MP7vh4DGaBW9eCKq1kFiJaP4", "mid": null, "onboarding_state": "PROVISIONING", "processing_enabled": false, "processor": "DUMMY_V1", "processor_details": {}, "ready_to_settle_upon": "RECONCILIATION", "ready_to_settle_upon_delay_alignment": "NONE", "rent_surcharges_enabled": false, "settlement_enabled": false, "settlement_funding_identifier": "UNSET", "surcharges_enabled": false, "tags": {}, "verification": "VIrnen8yHQZTQnc4EYA8NL8W", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/merchants/MUa2uYEkaRBzP8EEDeKweE5h" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/merchants/MUa2uYEkaRBzP8EEDeKweE5h/verifications" }, "merchant_profile": { "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MP7vh4DGaBW9eCKq1kFiJaP4" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "verification": { "href": "https://finix.sandbox-payments-api.com/verifications/VIrnen8yHQZTQnc4EYA8NL8W" } } } ``` Canada ```shell Request curl -X POST \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/merchants \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "processor": "DUMMY_V1" }' ``` ```json Response { "id": "MUu6un1HH6ghMtwak9FbaJX", "created_at": "2024-08-16T12:25:45.46Z", "updated_at": "2024-08-16T12:25:45.46Z", "application": "APgPDQrLD52TYvqazjHJJchM", "card_cvv_required": false, "card_expiration_date_required": true, "card_network_details": null, "convenience_charges_enabled": false, "country": "CAN", "creating_transfer_from_report_enabled": true, "currencies": ["CAD"], "default_partial_authorization_enabled": false, "disbursements_ach_pull_enabled": false, "disbursements_ach_push_enabled": false, "disbursements_card_pull_enabled": false, "disbursements_card_push_enabled": false, "disbursements_same_day_ach_pull_enabled": false, "disbursements_same_day_ach_push_enabled": false, "fee_ready_to_settle_upon": "RECONCILIATION", "gateway": null, "gross_settlement_enabled": false, "identity": "IDpNvpkgXiBMArDrGWJ3JRG9", "level_two_level_three_data_enabled": false, "loan_repayment": null, "mcc": "4900", "merchant_name": "Video Editing Services", "merchant_profile": "MPjso886FW3AHS7qC7yZ5UfE", "mid": null, "onboarding_state": "PROVISIONING", "processing_enabled": false, "processor": "DUMMY_V1", "processor_details": {}, "ready_to_settle_upon": "RECONCILIATION", "ready_to_settle_upon_delay_alignment": "NONE", "rent_surcharges_enabled": false, "settlement_enabled": false, "settlement_funding_identifier": "UNSET", "surcharges_enabled": false, "tags": {}, "verification": "VItdfqW6Hyu9n5ak2eWr2SUS", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/merchants/MUu6un1HH6ghMtwak9FbaJX" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/merchants/MUu6un1HH6ghMtwak9FbaJX/verifications" }, "merchant_profile": { "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPjso886FW3AHS7qC7yZ5UfE" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "verification": { "href": "https://finix.sandbox-payments-api.com/verifications/VItdfqW6Hyu9n5ak2eWr2SUS" } } } ``` ## Step 5: Review process Your seller will be ready to process payments once their Merchant account is `APPROVED`. Finix will update the Merchant's `onboarding_state` after the review process, which often takes just minutes but can take longer if manual intervention is required. ### Receiving Webhooks Finix sends webhooks to update you about your seller's progress throughout the onboarding process. For example, you can listen to the `Merchant Updated` and `Merchant Underwritten` events to know when your Merchant transitions from `PROVISIONING` to another state. To learn more about webhooks, see [Notifications and Webhooks](/guides/platform-payments/onboarding-sellers/seller-onboarding-notifications-and-webhooks). ### Handling update requests Should Finix require additional information to board your seller, we will move their Merchant to an `UPDATE_REQUESTED` state and explain what additional information is required. Finix provides codes for each information request type, making it easy to build your own experience to manage update requests. To learn more about handling update requests, see [Handling Update Requests](/guides/platform-payments/onboarding-sellers/seller-onboarding-update-requests). ## Next steps Next, learn how to handle update requests and listen to webhooks to move your sellers through onboarding. --- # Seller Rejections Source: https://docs.finix.com/guides/platform-payments/onboarding-sellers/seller-rejections In some cases, Finix will reject your sellers if we cannot support them due to financial risk, fraud risk, or other reasons. When this happens, Finix will move your seller's Merchant account to the Rejected state with outcome codes explaining we rejected them. Should you believe this was done in error or need more information, please reach out to your Finix point of contact. ## Handling rejections with the Dashboard On the **Merchants > Merchant Accounts** page, you can see all Merchants in your system. The **Rejected tab** shows all rejected Merchants. To see details about the rejection, you can check the **Onboarding State column**, or click on the Merchant to navigate to their account page. Rejected Merchant List Page On the Merchant page, you will see the outcome codes Finix assigned when rejecting the Merchant. You may also see notes providing additional context about the rejection (for example, we may include a note explaining that the Merchant was rejected due to being on the MATCH list for excessive chargebacks). Rejected Merchant Detail Page ## Handling rejections with the API ### Merchant resource When Finix rejects your Merchant, your Merchant's `onboarding_state` will be `REJECTED`. ```json Rejected Merchant { "id": "MUno35MtzSMr61mUvY7qCayR", "created_at": "2022-01-27T07:36:58.19Z", "updated_at": "2022-10-06T20:25:24.06Z", "application": "APgPDQrLD52TYvqazjHJJchM", "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": "IDpYDM7J9n57q849o9E9yNrG", "level_two_level_three_data_enabled": false, "mcc": "4900", "merchant_name": "Bobs Burgers", "merchant_profile": "MPzW2oRPtkLxK3fymcMACFi", "mid": "FNXh6htoPnfwmgGdvaG4L67Q1", "onboarding_state": "REJECTED", "processing_enabled": true, "processor": "DUMMY_V1", "processor_details": {}, "ready_to_settle_upon": "RECONCILIATION", "rent_surcharges_enabled": false, "settlement_enabled": true, "settlement_funding_identifier": "UNSET", "surcharges_enabled": false, "tags": {}, "verification": "VIxfDrRKZZzkCDDbeCT15oDN", "_links": {} } ``` ### Verification resource When Finix requests updates from your Merchant, the Verification will have `state: FAILED`, as well as an `outcomes` array listing each `outcome_code` assigned to your Merchant. Your Merchant will also have an `outcome_summary` providing additional context about the requested updates (for example, we may include a note explaining the bank account routing number is invalid). Use the Merchant's Verification ID (`verification`) to get the Verification. Rejection outcome codes do not include any `remediation_details`. ```json Rejected Verification { "id": "VIvyMuSk9EdyVUrCw2JcXq4r", "created_at": "2023-09-12T16:08:17.03Z", "updated_at": "2023-09-12T16:08:17.10Z", "application": "AP7sqs8G9eTwcLPpjEHLgfUq", "identity": null, "merchant": "MUno35MtzSMr61mUvY7qCayR", "merchant_identity": "IDbM99DS8MaYXyqynqB7z1mR", "messages": [], "outcomes": [ { "outcome_code": "FINANCIAL_HISTORY", "remediation_details": null }, { "outcome_code": "HIGH_RISK", "remediation_details": null } ], "outcome_summary": "Rejected due to risk.", "payment_instrument": null, "payment_instrument_verification_details": {}, "processor": "LITLE_V1", "raw": [], "state": "FAILED", "tags": {}, "trace_id": "FNXboZb9r4P8TRKXluF2udGEv", "type": "MERCHANT", "_links": {} } ``` ## Rejection codes | `outcome_code` | `remediation_details` | | --- | --- | | `FINANCIAL_HISTORY` | `null` | | `HIGH_RISK` | `null` | | `INCOMPLETE_APPLICATION` | `null` | | `INSUFFICIENT_BUSINESS_HISTORY` | `null` | | `MATCH_LIST_DECLINE` | `null` | | `OFAC_DECLINE` | `null` | | `POTENTIAL_FRAUD` | `null` | | `UNSUPPORTED_BUSINESS` | `null` | | `OTHER` | `null` | --- # Seller Terminations Source: https://docs.finix.com/guides/platform-payments/onboarding-sellers/seller-terminations You can terminate seller accounts through the Finix Dashboard or via our APIs. There are several reasons to terminate a seller merchant account after approval, including suspected fraud, compliance violations, excessive chargebacks, or merchant churn. The seller's merchant account state will immediately update to **Terminated**. Terminating a seller merchant account will: - Disable payment processing (`processing_enabled: false`) - Disable settlements (`settlement_enabled: false`) - Disable refunds (`refunds_disabled: true`) If a merchant is terminated by mistake, please [contact the Finix Support Team](mailto:support@finix.com). ## Terminating Merchants in the Dashboard On the **Merchants** page, you can see all Merchants in your system. Click on the Merchant to navigate to their account page. Merchant Account List Page On the Merchant page, click the three-dot icon in the top-right corner, then select **Terminate Merchant Account** from the dropdown menu. Merchant Detail Page Choose a reason for terminating the merchant account from the dropdown menu. Then, enter a description explaining the reason (maximum 1,000 characters). Terminate Merchant Page Terminating the merchant account will disable processing, settlements and refunds. The action cannot be reverted. ## Terminating Merchants with the API ### Terminate Merchant account Example API Definition --- # Available Fees Source: https://docs.finix.com/guides/platform-payments/monetizing-payments/available-fees ## Card fees | Field | Description | | --- | --- | | `basis_points` | Percentage-based fee incurred against the full amount of each card-based `Transfer`. Calculated as one hundredth of one percent (1 basis point = .0001 or .01%). | | `fixed_fee` | Fee in cents incurred for each individual card-based `Transfer`. | | `charge_interchange` | Set to True to incur interchange fees for card-based `Transfers`. | | `cross_border_fixed_fee` | Fee in cents incurred for each individual card-based `Transfer` that is deemed to be cross-border (Non-US). | | `cross_border_basis_points` | Percentage-based fee incurred against the full amount of each card-based `Transfer` that is deemed to be cross-border (Non-US). Calculated as one hundredth of one percent (1 basis point = .0001 or .01%). | | `ancillary_fixed_fee_primary` | Fee in cents incurred for each individual `Transfer`. | | `ancillary_fixed_fee_secondary` | Fee in cents incurred for each individual `Transfer`. | ## Card brand specific fees ## Visa | Field | Description | | --- | --- | | `visa_basis_points` | Percentage-based fee incurred against the full amount of each Visa `Transfer`. Calculated as one hundredth of one percent (1 basis point = .0001 or .01%). | | `visa_fixed_fee` | Fee in cents incurred for each individual Visa `Transfer`. | | `visa_charge_interchange` | Set to True to incur interchange fees for Visa `Transfers`. | | `visa_assessments_basis_points` | Applies to all Visa credit transactions. | | `visa_acquirer_processing_fixed_fee` | All U.S.-based credit card authorizations acquired in the U.S. regardless of where the issuer/cardholder is located. If your business is based in the U.S., the acquirer processing fee will apply to all Visa credit card authorizations. | | `visa_credit_voucher_fixed_fee` | Applies to refunds. | | `visa_kilobyte_access_fixed_fee` | Charged on each authorization transaction submitted to Visa's network for settlement. | | `visa_base_II_system_file_transmission_fixed_fee` | Applies to all Visa transactions and is charged in addition to other transaction-based assessments. | | `visa_base_II_credit_voucher_fixed_fee` | Applies to all U.S.-based refunds. | ## Mastercard | Field | Description | | --- | --- | | `mastercard_basis_points` | Percentage-based fee incurred against the full amount of each MasterCard `Transfer`. Calculated as one hundredth of one percent (1 basis point = .0001 or .01%). | | `mastercard_fixed_fee` | Fee in cents incurred for each individual MasterCard `Transfer`. | | `mastercard_charge_interchange` | Set to True to incur interchange fees for MasterCard `Transfers`. | | `mastercard_assessments_under1k_basis_points` | Assessment applies to Mastercard transactions less than or equal to $1,000. | | `mastercard_assessments_over1k_basis_points` | Assessment applies to Mastercard credit sale transactions greater than $1,000. | | `mastercard_acquirer_fees_basis_points` | Fee is assessed on a business's gross MasterCard processing volume. This fee varies per acquirer based on MasterCard's assessed charge as it's distributed across the acquirer's portfolio of merchants. Generally, the ALF fee is a fraction of a basis point. For example, 0.0045%, 0.0075%, etc. are examples of a likely ALF fee. | ## American Express | Field | Description | | --- | --- | | `american_express_basis_points` | Percentage-based fee incurred against the full amount of each American Express `Transfer`. Calculated as one hundredth of one percent (1 basis point = .0001 or .01%). | | `american_express_fixed_fee` | Fee in cents incurred for each individual American Express `Transfer`. | | `american_express_charge_interchange` | Set to True to incur interchange fees for American Express `Transfers`. | | `american_express_assessment_basis_points` | Applies to gross American Express card volume. | ## JCB | Field | Description | | --- | --- | | `jcb_basis_points` | Percentage-based fee incurred against the full amount of each JCB `Transfer`. Calculated as one hundredth of one percent (1 basis point = .0001 or .01%). | | `jcb_fixed_fee` | Fee in cents incurred for each individual JCB `Transfer`. | | `jcb_charge_interchange` | Set to True to incur interchange fees for JCB `Transfers`. | ## Discover | Field | Description | | --- | --- | | `discover_basis_points` | Percentage-based fee incurred against the full amount of each Discover `Transfer`. Calculated as one hundredth of one percent (1 basis point = .0001 or .01%). | | `discover_fixed_fee` | Fee in cents incurred for each individual Discover `Transfer`. | | `discover_charge_interchange` | Set to True to incur interchange fees for Discover `Transfers`. | | `discover_assessments_basis_points` | Assessment applies to gross Discover card transaction volume. | | `discover_data_usage_fixed_fee` | Applies to all U.S.-based authorization transactions. | | `discover_network_authorization_fixed_fee` | This fee will apply to all Discover network authorizations and will replace the previously assessed Data Transmission. | ## Diner's Club | Field | Description | | --- | --- | | `diners_club_basis_points` | Percentage-based fee incurred against the full amount of each Diners `Transfer`. Calculated as one hundredth of one percent (1 basis point = .0001 or .01%). | | `diners_club_fixed_fee` | Fee in cents incurred for each individual Diners `Transfer`. | | `diners_club_charge_interchange` | Set to True to incur interchange fees for Diners `Transfers`. | ## ACH fees | Field | Description | | --- | --- | | `ach_fixed_fee` | Fee in cents incurred for each individual `Transfer`. | | `ach_basis_points` | Percentage-based fee incurred against the full amount of an ACH Direct Debit. Calculated as one hundredth of one percent (1 basis point = .0001 or .01%). | | `ach_basis_points_fee_limit` | Maximum `ach_basis_points` fee (in cents) incurred for each individual `Transfer`. | ## ACH return fees | Field | Description | | --- | --- | | `ach_debit_return_fixed_fee` | A fixed amount (in cents) that will be charged to the seller for receiving an ACH *Debit* Return. | | `ach_credit_return_fixed_fee` | A fixed amount (in cents) that will be charged to the seller for receiving an ACH *Credit* Return. | ## Dispute specific fees | Field | Description | | --- | --- | | `dispute_inquiry_fixed_fee` | Applied when a dispute is created in state INQUIRY. | | `dispute_fixed_fee` | Applied when a dispute is created or moved to state PENDING. | --- # Calculating Fees Dynamically Source: https://docs.finix.com/guides/platform-payments/monetizing-payments/calculating-fees-dynamically Some platforms have variable pricing strategies that depend on a number of factors such as promotions, concessions, and other criteria. ## Using supplemental fee Finix allows you to use our `supplemental_fee` on our /Transfers API. This `supplemental_fee` works with our Merchant Fee Profiles to unlock several pricing strategies. In all of these strategies below, you will need to supply this field using logic you control into our API. ## Common implementation strategies ### Passing fees to Buyers Many platforms choose to offer a pricing strategy where the buyer pays for processing fees. These are usually considered Buyer Fees. You should consult your own legal counsel if what you are doing is considered a Buyer Fee. Goal: Merchant does not pay for fees. This means they pass through the fees to the buyer. Example: - $100.00 Item - $4.00 Buyer Fee passed onto buyer (Displayed as "Processing Fee" to Buyer or "Platform Fee") - $4.00 Fee charged to merchant To accomplish this example, we will need to: 1. Set the Merchant Fee Profile for the merchant to be $0.00 for Card and ACH transactions 2. Run a Sale or Capture with a `supplemental_fee` of $4.00 and the amount to be passed to be the buyer to be $104.00 ```API curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/transfers \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "amount": 10400, "supplemental_fee": 400, "currency": "USD", "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "source": "PI6iQcTtJNCS8GZAVKYi5Ueb", "tags": { "test": "Sale" } }' ``` ### Charging an additional fee on top of interchange plus or blended pricing This pricing strategy requires the use of Merchant Fee Profiles along with calculating the fees at transaction time. Let's take a simplified example where we charge a flat rate of $1.00 on top of interchange plus pricing strategy for transactions less than $150.00. For transactions more than $150.00, we charge $1.50. Goal: Charge $1.00 fee on top of fees calculated by the fee profile To accomplish this example we will need to: 1. Set the merchant fee profile to the desired setting & rates 2. Supply a `supplemental_fee` of $1.00 for transactions less than $150.00 and $1.50 for a transactions over $150.00 ```API curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/transfers \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "amount": 10000, "supplemental_fee":100, "currency": "USD", "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "source": "PI6iQcTtJNCS8GZAVKYi5Ueb", "tags": { "test": "Sale" } }' ``` A `Fee` of $1.00 will be created on top of the additional fees created by the Fee Profile. --- # Collecting Seller Fees Source: https://docs.finix.com/guides/platform-payments/monetizing-payments/collecting-seller-fees Seller Payouts Hero Finix allows you to monetize your payments by charging `Fees` to your sellers. Fees are the revenue you make for processing transactions. You can also charge Fees for specific events like disputes and ACH returns. Finix offers a number of ways to charge Fees to your sellers. ## 1.) Calculating fees with Merchant Fee Profiles Billing Settlements ### Available pricing strategies Finix's Merchant Fee Profiles take care of the heavy lifting and supports many different pricing strategies and fees. #### Interchange plus Your sellers pay the interchange rate set by the issuing banks plus a markup you can charge on top. #### Interchange plus and dues & assessments Your sellers pay the interchange rate as well as separate pass-through of card network fees (dues and assessments). Finix provides many of these Dues and Assessments at a Transaction level. #### Blended pricing Transactions are charged a single flat rate (e.g. 2.90%+ 30 cents). There are additional features to charge different card brands (e.g. Visa, MasterCard, Discover, and Amex) and payment methods a different rate. ### All available fees Finix has 60+ fee options to monetize your payments. To see all available fees, see our [Fee Profile guide](/guides/platform-payments/monetizing-payments/merchant-fee-profiles). ## 2.) Calculating fees per transaction Seller Payouts Hero Some platforms have variable pricing strategies that depend on a number of factors such as promotions, concessions, and other criteria. In this case, Finix makes it easy to be able to support these use cases. You can use our /transfers API to pass in a `supplemental_fee` that can be varied on each transaction. For additional information, see our [Dynamically Calculating Fees Guide](/guides/platform-payments/monetizing-payments/calculating-fees-dynamically). ## 3.) Splitting a transaction to collect a portion of revenue Split transactions Some platforms choose to take a small portion of every payment. Finix supports this using our Split Transactions functionality. To learn more about Split Transactions, see the [Split Transactions guide](/guides/online-payments/payment-features/split-transactions). --- # Monetizing Payments Source: https://docs.finix.com/guides/platform-payments/monetizing-payments Learn how to monetize payments with Finix. Seller Payouts Hero Finix allows you to easily monetize your payments. We offer out of the box customizability, efficiency, and revenue growth tools. ## Learn more Platform Residuals Learn about how to receive residuals with Finix. Collecting Seller Fees Learn how to collect Fees from your sellers. Merchant Fee Profiles Learn how to use Finix's out of the box Merchant Fee Profiles. --- # Instrument Specific Fees Source: https://docs.finix.com/guides/platform-payments/monetizing-payments/instrument-specific-fees In Finix, `Payment Instruments` are tied to the owner of that account. For example, `Payment Instruments` tied to buyer will be the cards used for purchases while `Payment Instruments` tied to a `Merchant` are the bank accounts where they receive settlements. When billing events occur that are tied to a buyer's `Payment Instrument` (e.g. enrolling in account updater, using Plaid for tokenization, etc) Finix cannot automatically map those fees to a specific `Merchant`. By default, these costs are instead charged to your `Application` (e.g. the Platform, Marketplace, Vertical Saas owner's account) and will be deducted from your residual. If you wish to monetize these offerings or pass the fees on to your `Merchant` you must explicitly link the buyers `Payment Instrument` to a `Merchant` resource using the `Payment Instrument Association` [resource](/api/payment-instrument-associations). To accomplish this example, we will need to: 1. Make sure the Merchant `Fee Profile` is configured with a fee (i.e. has a value >0) for these relevant instrument fees 2. Create a `Payment Instrument Association` resource after the `Payment Instrument` is tokenized. ```API curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/payment_instrument_associations \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "merchant_id": "MUcgYZswyRfqSSbvMsxuaHxZ", "payment_instrument_id": "PInQ4yKVvyJxB6dJtQkXLMWt" }' ``` --- # Merchant Fee Profiles Source: https://docs.finix.com/guides/platform-payments/monetizing-payments/merchant-fee-profiles Finix lets you monetize payments with our easy-to-use Fee Profiles. We offer tools for customization, efficiency, and revenue growth. Finix provides over 60 fee options. Finix offers the following pricing strategies: | **Pricing Strategy** | **Description** | | --- | --- | | Interchange Plus | Your sellers pay the interchange rate set by the issuing banks plus a markup you can charge on top. | | Interchange Plus and Dues & Assessments | Your sellers pay the interchange rate and a separate pass-through of card network fees, called dues and assessments. Finix provides many of these dues and assessments at the transaction level. | | Blended Pricing | Transactions are charged a single flat rate, such as 2.90% plus 30 cents. Additional features let you charge different rates for card brands like Visa, MasterCard, Discover, and American Express, as well as for different payment methods. | ## Creating Fee Profiles using the Finix Dashboard *To create a Fee Profile using the Finix Dashboard*: 1. From the left navigation, expand **Merchants** and click **Merchant Accounts**. Merchant Accounts list in Finix Dashboard for selecting a merchant to apply a fee profile 1. Click a merchant to open their merchant details page. 2. Click the **Account Settings** → **Fee Profile** tab and click **Create Custom Fee Profile**. - If the merchant is not assigned a Fee Profile, a default Fee Profile is created for the merchant that inherits the application's Fee Profile. Create a Custom Fee Profile - The next screens let you edit the fees for the Fee Profile. 1. Apply card-not-present fees to the merchant. - This lets you set processing fees for online card payments. - By default, a **Blended** pricing strategy is selected, letting you set a percentage rate and fixed fee that covers the markup, interchange, and other card fees the application plans to charge. You can also select **Interchange Plus** or **Interchange Plus and Dues & Assessments** pricing strategies. - You can also select **Card Brand Overrides**, which allow you to select a percentage rate and fixed fee based on the card brand. Card-Not-Present Fees 1. Click **Save and Continue**. 2. Apply card-present fees to the merchant. - This lets you set processing fees for in-person card payments. - By default, the same fees as online payments are applied. - To use different fees for in-person payments, untick the **Apply Card-Not-Present Fee Profile** checkbox. - When using a different set of fees, the pricing strategy is set to **Blended**, as with the default for card-not-present fees. Card-Present Fees 1. Click **Save and Continue**. 2. Next, set processing fees for ACH payments. You may apply additional charges for value-added services to all card and ACH payments. ACH Transfer Fees 1. Click **Save and Continue**. 2. Review the fees and click **Submit**. Submit Fee Profile You return to the merchant's details page with the ability to **Edit** the Fee Profile. ## Viewing / editing the Fee Profile You can view a Fee Profile's fees from the merchant's details page > **Account Settings** → **Fee Profiles** tab. For example, in the screenshot below, the **Card Brand Overrides** (interchange) section shows fees for Visa, Mastercard, American Express, and more. You can also click **Edit** to update the Fee Profile. Merchant Fee Profile - Edit ## Viewing transaction fees You can view a specific transaction's fees in the Finix Dashboard or via the API. ### Using the Finix Dashboard *To view a transaction's fees using the Finix Dashboard*: 1. From the left navigation, expand **Transactions** and click **Payments**. 2. Click a transaction. 3. A drawer opens that provides a high-level overview of the transaction. Click **View All Details**. 4. Scroll down to the **Associated Fees** section. - You will see the list of fees applied to the transaction. Payment Details - Associated Fees 1. You can view the corresponding fees on the Fee Profile by navigating to the merchant's details page > **Account Settings** → **Fee Profiles** tab. Merchant Fee Profile - Fees ### Using the API View transaction fees using the API by sending a request to the [GET /fees](/api/fees/listfees) endpoint with the ID of the `Transfer` or `Authorization`. The response lists all fees applied to the transaction. In the response, `fee_type: VISA_ACQUIRER_PROCESSING_FIXED` corresponds to the `visa_acquirer_processing_fixed_fee` field on the Fee Profile. ```json { "_embedded": { "fees": [ { "id": "FEuYERkdmeFjHbtzCotpCY87", "created_at": "2025-11-12T16:57:31.04Z", "updated_at": "2025-11-12T16:57:31.04Z", "amount": 2, "category": "PROCESSOR", "currency": "USD", "display_name": null, "fee_subtype": "PLATFORM_FEE", "fee_type": "VISA_ACQUIRER_PROCESSING_FIXED", "label": null, "linked_id": "TRnnQUqBwegR7dqJdXJ9KthJ", "linked_to": "TRnnQUqBwegR7dqJdXJ9KthJ", "linked_type": "TRANSFER", "merchant": "MUcCFbB9XJGE3fJcMu2egRJY", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/fees/FEuYERkdmeFjHbtzCotpCY87" }, "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MUcCFbB9XJGE3fJcMu2egRJY" }, "transfer": { "href": "https://finix.sandbox-payments-api.com/transfers/TRnnQUqBwegR7dqJdXJ9KthJ" } } } ] } } ``` You can view the corresponding fee on the Fee Profile by navigating to the merchant's details page > **Merchant Fee Profile** tab. ## Creating Fee Profiles via API Creating a `Fee Profile` is a three-step process: 1. Create a `Fee Profile`. 2. Update the `Merchant` to use the new `Fee Profile` for new transactions. Certification Recommended To integrate these API calls, contact our support team to certify them. ### Step 1: Create a Fee Profile You can create a `Fee Profile` with the following API request: Example API Definition Record the `id` of the new `Fee Profile` from the response: Example Fee Profile ```json Fee Profile { "id": "FPmH8SgwcrgpV595sojbKXNB", "created_at": "2026-09-25T20:05:06.83Z", "updated_at": "2026-09-25T20:05:06.83Z", "ach_basis_points": 30, "ach_basis_points_fee_limit": 50, "ach_credit_return_fixed_fee": 25, "ach_debit_return_fixed_fee": 30, "ach_fixed_fee": 40, "ach_notice_of_change_credit_fixed_fee": 12, "ach_notice_of_change_debit_fixed_fee": 25, "ach_validation_plaid_fixed_fee": null, "afterpay_basis_points": null, "afterpay_fixed_fee": null, "american_express_assessment_basis_points": null, "american_express_basis_points": 10, "american_express_charge_dues_assessments": null, "american_express_charge_interchange": true, "american_express_externally_funded_basis_points": null, "american_express_externally_funded_fixed_fee": null, "american_express_fixed_fee": 15, "ancillary_fixed_fee_primary": 32, "ancillary_fixed_fee_secondary": 80, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "basis_points": 20, "card_account_updater_fixed_fee": null, "card_cross_border_basis_points": 15, "card_cross_border_fixed_fee": 30, "card_name_verification_fixed_fee": null, "card_network_token_fixed_fee": null, "cash_app_pay_basis_points": null, "cash_app_pay_fixed_fee": null, "charge_all_authorization_requests": true, "charge_all_reversal_requests": true, "charge_all_transfer_requests": true, "charge_dues_assessments": true, "charge_interchange": false, "compliance_forms_overdue_fixed_fee": 20, "diners_club_basis_points": 90, "diners_club_charge_interchange": true, "diners_club_fixed_fee": 25, "discover_assessments_basis_points": null, "discover_basis_points": 12, "discover_charge_dues_assessments": null, "discover_charge_interchange": true, "discover_data_usage_fixed_fee": null, "discover_externally_funded_basis_points": null, "discover_externally_funded_fixed_fee": null, "discover_fixed_fee": 35, "discover_network_authorization_fixed_fee": null, "dispute_fixed_fee": 1500, "dispute_inquiry_fixed_fee": 1500, "eft_basis_points": 25, "eft_basis_points_fee_limit": 20, "eft_credit_return_fixed_fee": 35, "eft_debit_return_fixed_fee": 30, "eft_fixed_fee": 15, "eft_validation_plaid_fixed_fee": null, "externally_funded_basis_points": 15, "externally_funded_fixed_fee": 20, "fixed_fee": 20, "gross_monthly_fees_ach_basis_points": null, "gross_monthly_fees_ach_fixed_fee": null, "gross_monthly_fees_card_basis_points": null, "gross_monthly_fees_card_fixed_fee": null, "gross_monthly_fees_eft_basis_points": null, "gross_monthly_fees_eft_fixed_fee": null, "interac_basis_points": 20, "interac_fixed_fee": 25, "invoice_ach_basis_points": null, "invoice_ach_basis_points_fee_limit": null, "invoice_ach_fixed_fee": null, "invoice_card_basis_points": null, "invoice_card_fixed_fee": null, "invoice_eft_basis_points": null, "invoice_eft_basis_points_fee_limit": null, "invoice_eft_fixed_fee": null, "jcb_basis_points": 11, "jcb_charge_interchange": true, "jcb_fixed_fee": 20, "mastercard_acquirer_fees_basis_points": null, "mastercard_assessments_over1k_basis_points": null, "mastercard_assessments_under1k_basis_points": null, "mastercard_basis_points": 30, "mastercard_charge_dues_assessments": null, "mastercard_charge_interchange": true, "mastercard_fixed_fee": 18, "payment_instrument_tokenization_fixed_fee": null, "qualified_tiers": null, "rounding_mode": "AGGREGATE", "settlement_funding_transfer_ach_basis_points": null, "settlement_funding_transfer_ach_basis_points_fee_limit": null, "settlement_funding_transfer_ach_credit_return_fixed_fee": null, "settlement_funding_transfer_ach_debit_return_fixed_fee": null, "settlement_funding_transfer_ach_fixed_fee": null, "settlement_funding_transfer_eft_basis_points": null, "settlement_funding_transfer_eft_basis_points_fee_limit": null, "settlement_funding_transfer_eft_credit_return_fixed_fee": null, "settlement_funding_transfer_eft_debit_return_fixed_fee": null, "settlement_funding_transfer_eft_fixed_fee": null, "settlement_funding_transfer_instant_payout_card_basis_points": null, "settlement_funding_transfer_instant_payout_card_basis_points_fee_limit": null, "settlement_funding_transfer_instant_payout_card_fixed_fee": null, "settlement_funding_transfer_noc_credit_fixed_fee": null, "settlement_funding_transfer_noc_debit_fixed_fee": null, "settlement_funding_transfer_same_day_ach_basis_points": null, "settlement_funding_transfer_same_day_ach_basis_points_fee_limit": null, "settlement_funding_transfer_same_day_ach_fixed_fee": null, "subscription_ach_basis_points": null, "subscription_ach_basis_points_fee_limit": null, "subscription_ach_fixed_fee": null, "subscription_card_basis_points": null, "subscription_card_fixed_fee": null, "subscription_eft_basis_points": null, "subscription_eft_basis_points_fee_limit": null, "subscription_eft_fixed_fee": null, "tags": {}, "third_party_gateway_cybersource_basis_points": null, "third_party_gateway_cybersource_fixed_fee": null, "visa_acquirer_processing_fixed_fee": null, "visa_assessments_basis_points": null, "visa_base_II_credit_voucher_fixed_fee": null, "visa_base_II_system_file_transmission_fixed_fee": null, "visa_basis_points": 10, "visa_charge_dues_assessments": null, "visa_charge_interchange": true, "visa_credit_voucher_fixed_fee": null, "visa_fixed_fee": 20, "visa_kilobyte_access_fixed_fee": null, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmH8SgwcrgpV595sojbKXNB" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ``` API Definition You can apply this `Fee Profile` to as many merchants as you want. Changes to the `Fee Profile` affect to all merchants that profile is applied to. You can also create a new `Fee Profile` for each merchant or reuse one you created earlier. ### Step 2: Retrieve the Merchant profile To update your merchant's `Fee Profile`, you need the `Merchant Profile` of the `Merchant`. You can get the `Merchant Profile` by sending a request to the [GET /merchants](/api/merchants/getmerchant) endpoint with the `Merchant` ID. The response includes the `merchant_profile` field. Record the `merchant_profile` returned in the response: Merchant ```json Merchant { "id": "MUwfZPNW3r4EqLMzwgr6txw4", "created_at": "2025-07-07T18:04:14.14Z", "updated_at": "2026-09-04T14:16:01.76Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "card_cvv_required": false, "card_expiration_date_required": true, "card_network_details": null, "convenience_charges_enabled": true, "country": "USA", "creating_transfer_from_report_enabled": false, "currencies": [ "USD" ], "default_partial_authorization_enabled": false, "disbursements_ach_pull_enabled": true, "disbursements_ach_push_enabled": true, "disbursements_card_pull_enabled": true, "disbursements_card_push_enabled": true, "disbursements_same_day_ach_pull_enabled": false, "disbursements_same_day_ach_push_enabled": false, "fee_ready_to_settle_upon": "CONFIGURABLE_WINDOW", "first_approved_at": "2025-07-07T18:05:01.34Z", "gateway": null, "gross_settlement_enabled": false, "identity": "IDhC29dXMAkbmr1aBpS91Hpx", "instant_payouts_card_push_enabled": false, "is_terminated": true, "level_two_level_three_data_enabled": true, "loan_repayment": null, "mcc": "9399", "merchant_name": "Finix Flowers", "merchant_profile": "MPpxQZAuHheULikbLYhJCNUd", // [!code highlight] "microdeposit_verification_required_buyer": false, "microdeposit_verification_required_sender": false, "mid": "FNX6cVPYBbfvtnR8G41pjVMQz", "onboarding_state": "APPROVED", "pending_refunds_strategy": "NONE", "processing_enabled": true, "processor": "DUMMY_V1", "processor_details": { "mid": "FNX6cVPYBbfvtnR8G41pjVMQz", "api_key": "secretValue" }, "ready_to_settle_upon": "CONFIGURABLE_WINDOW", "ready_to_settle_upon_delay_alignment": "NONE", "refunds_disabled": true, "rent_surcharges_enabled": true, "settlement_enabled": false, "settlement_funding_identifier": "UNSET", "settlement_queue_mode": "UNSET", "surcharges_enabled": true, "tags": { "key_2": "value_2" }, "termination_details": { "terminated_at": "2025-10-03T22:51:03.78Z", "reason": "CHURNED", "description": "Customer canceled", "terminated_by": "PARTNER_USER", "terminated_by_user_id": "USfdccsr1Z5iVbXDyYt7hjZZ" }, "unreferenced_refund_card_present_enabled": false, "unreferenced_refund_manual_entry_enabled": false, "verification": "VIsmg3o9ZZhTJuQfsg4JkPgv", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/merchants/MUwfZPNW3r4EqLMzwgr6txw4" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDhC29dXMAkbmr1aBpS91Hpx" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/merchants/MUwfZPNW3r4EqLMzwgr6txw4/verifications" }, "merchant_profile": { "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPpxQZAuHheULikbLYhJCNUd" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "verification": { "href": "https://finix.sandbox-payments-api.com/verifications/VIsmg3o9ZZhTJuQfsg4JkPgv" } } } ``` ### Step 3: Updating the Merchant to use the Fee Profile After you have the `merchant_profile` ID and the `fee_profile` ID from previous requests, send a request to the PUT `/merchant_profiles` endpoint to update the `Merchant Profile` with the `Fee Profile`. Only the `fee_profile` field is required in the request. - If you do not supply a `card_present_fee_profile`, the `fee_profile` will be applied to both card-not-present and card-present transactions. - If a `card_present_fee_profile` field is provided, the `card_present_fee_profile` will be used only for card-present transactions. ```shell Updating a Merchant Profile to use the Fee Profile curl "https://finix.sandbox-payments-api.com/merchant_profiles/MPrqHHN5y5Up4AGYENnEGvah" \ -H "Content-Type: application/json" \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ -X PUT \ -d '{ "fee_profile": "FPryaDMUDq9Tcc5epVpro1Jj", "card_present_fee_profile" : "FPryaDMUDq9Tcc5epVpro1Jj" }' ``` After you update the `Merchant Profile`, all new transactions will have this `Fee Profile` applied. Transactions created before the change will use the previous `Fee Profile`. ```json Updated Merchant Profile { "id": "MPrqHHN5y5Up4AGYENnEGvah", "created_at": "2025-03-13T07:00:02.44Z", "updated_at": "2025-11-18T17:29:46.87Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "card_present_fee_profile": "FPryaDMUDq9Tcc5epVpro1Jj", "fee_profile": "FPryaDMUDq9Tcc5epVpro1Jj", "payout_profile": null, "risk_profile": "RPfZMXNRVi6wqueZwwNN1xuh", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPrqHHN5y5Up4AGYENnEGvah" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "risk_profile": { "href": "https://finix.sandbox-payments-api.com/risk_profiles/RPfZMXNRVi6wqueZwwNN1xuh" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPryaDMUDq9Tcc5epVpro1Jj" } } } ``` --- # Platform Residuals Source: https://docs.finix.com/guides/platform-payments/monetizing-payments/platform-residuals As a Platform, Finix allows you to easily monetize payments and collect a residual from your merchants. ## Residuals overview Finix has two types of billing: - **Merchant Fees** - Fees used to bill your `merchants` for transaction costs on Finix. These can be set using the Fee Profile or passed in per transaction via API. - **Finix Costs** - Costs for using the Finix system for Acquiring. These are associated with your legal agreement with Finix. ## Residuals Finix calculates residuals with a simple equation: ```txt Residuals Calculation Merchant Fees - Finix Costs = Residuals ``` Depending on your agreement with Finix, there may be a Revenue Share. If that's the case, you will only keep the portion of the Residuals specified in your agreement. ## Viewing your residuals Finix generates Residuals monthly. These residuals appear on the dashboard as `billing_settlements`. Billing Settlements Additional Notes: - Residuals may be negative if your Merchant `Fees` are not high enough to cover the Finix `Costs`. - Certain contracts with Finix have a Rev Share split that needs to be taken into account ### Income Statement When you click into a Billing Settlement, you'll be able to see an aggregate of both `Fees` and `Costs`. You can expand and collapse the different sections to view the aggregations for both Fees and Costs. Cost Income Statement ### Downloading Reports At the bottom of the Billing Settlement, there will be a section to download reports related to this Billing Settlement. We offer the following report: - **Residual by Merchant:** This report provides a breakdown of residuals by merchants. ## Receiving your residual Residuals are normally paid out within 30 days of the billing settlement being created. Residuals will be paid out using `Billing Transfers` which will be viewable in your `Billing Settlement`. There may be situations where a residual is not paid out if money is owed or if losses occur due to an inability to collect fees from a merchant in your portfolio. ## Viewing your costs profile Platforms on Finix are assigned a Cost Profile that detail the rates assigned to them. To View your Cost Profile: 1. Log into the Finix Dashboard. 2. Navigate to Settings > Company 3. Navigate to the Company Financials Tab 4. Select Cost Profile Your Cost Profile will match the rates entered in your Finix Master Service Agreement (MSA) and Order Form. Cost Profile ## Viewing costs Similar to Fees, you will be able to view `Costs` on different resources. When viewing a payment, you will be able to view `Fees` and `Costs` to give you a better perspective on different payments. Viewing Costs ## Changing your billing settings If you need to update your bank account on file, please reach out to your Customer Delivery Manager. We will want to validate the new bank account with a bank verification letter or bank statement. --- # Accruing Settlements Source: https://docs.finix.com/guides/platform-payments/seller-payouts/accruing-settlements As sellers process payments on Finix, they have open Settlements that accrue transactions. This ensures that each payout is the result of an explicit set of transactions. As long as a Merchant is processing transactions, they'll have an accruing Settlement. This accruing Settlement has running totals that can almost be seen as the current balance for the seller. These totals constantly change while the seller is processing transactions and can continue to change in value until the settlement closes. You can find these accruing Settlements in the dashboard or programmatically through the API and Webhooks. ## Accruing Settlements in the Dashboard In the dashboard, you can see the currently accruing Settlements under **Merchants > Merchant Payouts**. Filter the **State** to **Accruing**. Accruing Settlements List Page From this page, select an individual accruing Settlement to see its current totals. Accruing Settlements Detail Page Manage Accruing Settlements on Mobile You can also view and stop accruing Settlements from the Finix iOS app. Open **More > Merchant Payouts**, find the Settlement with a status of **Accruing**, and select **Stop Accruing** from its ellipsis menu. For more, see [Merchant Payouts on Mobile](/guides/platform-payments/seller-payouts/merchant-payouts-mobile). ## Accruing Settlements in the API You can use the API to interact with accruing Settlements. When a settlement starts accruing we'll send a webhook event with an entity of settlement and a event type of `accruing_started`. The `PENDING` status means the Settlement is actively accruing transactions. Use the `id` to query the Settlement at any moment for its current totals. ```json Accruing Started Webhook { "type": "accruing_started", "entity": "settlement", "occurred_at": "2018-03-06T20:41:34.277", "_embedded": { "settlements": [ { "id": "STc4qcqYJn4tKaD6bkHzkzMG", "application": "APcL6gyMzeFqDf6RHJid3SEq", "tags": {}, "identity": "ID57iuPnKwuopPn93YsGmvkP", "currency": "USD", "merchant_id": "MUgRjRrRwDyMbzS6CVQYPECC", "created_at": "2022-08-18T19:00:00.93Z", "updated_at": "2022-08-18T19:00:00.93Z", "processor": "DUMMY_V1", "type": "MERCHANT_REVENUE", "funds_flow": null, "payment_type": null, "total_amount": 662154, "total_fees": 19232, "total_fee": 19232, "net_amount": 642922, "destination": null, "status": "PENDING" } ] } } ``` ## Closing an accruing Settlement Once the settlement closes, you'll see its status update in the dashboard. You'll also receive another webhook event with `entity: settlement` and `type: created` for that original accruing Settlement. You can confirm the Settlement is closed by matching the settlement `id` with the `id` in the `accruing_started` webhook event. Once closed, the Settlement goes through the normal settlement approval and payout process. --- # Approving Settlements Source: https://docs.finix.com/guides/platform-payments/seller-payouts/approving-settlements Learn how to approve Settlements to payout your sellers. When `Settlements` with day-to-day payments and transactions are approved, a Funding `Transfer` gets created that credits the seller's bank account with their payout. The grouping of Settlements and when they're available for approval depends on the payout schedule you've configured. `Settlements`, Entries, and Funding `Transfers` are available for review and approval via [Finix's API](/api/settlements) and your [Finix Dashboard](https://finix.payments-dashboard.com/Login). - For Finix Flex customers, Finix manages and approves Settlements. - For Finix Core customers, you’ll need to approve and manage your user's Settlements. Your sellers receive funds (or get paid out) when their Settlements are approved. For example, say one of your sellers has a Settlement that only contains refunds. Once the Settlement is approved, the Funding Transfer will debit funds from the user's bank account. ## Settlement approval checklist It's important to exercise vigilance and carefully review each Settlement before approving it. Reviewing Settlements ensures funding `Transfers` are created accurately and securely and protects your organization from potential risks and fraudulent activities. Use the following list to understand what key aspects you should keep an eye out for when approving Settlements: - **Inflated Settlements** - Watch out for Settlements that appear abnormally large compared to the usual processing activity of the seller. These inflated Settlements can indicate errors, discrepancies, or even potential attempts to manipulate the system. Take the time to investigate the underlying reasons for such high amounts to ensure they align with the seller's legitimate transactions. - **Large Discrepancies** - Pay close attention to Settlements that exhibit large discrepancies in comparison to the seller's usual processing activity. Such variances can arise due to unexpected changes in sales volume, sudden spikes in refunds, or other anomalies. By scrutinizing these discrepancies, you can identify potential issues, such as erroneous entries, fraudulent transactions, or operational errors, which may require further investigation. - **Odd Money Movements** - Keep an eye out for any unusual money movements within the Settlements. This includes transactions that seem out of place, such as funds being transferred to unfamiliar accounts or routed through unverified channels. Such irregularities can be indicative of fraudulent activities or unauthorized transfers. Take immediate action to investigate and rectify these instances to safeguard your sellers and maintain compliance. - **Discrepancies in Total Amount and Transaction Count** - Verify the accuracy of the total amount and the number of transactions included in each Settlement. Large discrepancies in either of these areas should raise a red flag, as they could indicate miscalculations, missing transactions, or even intentional manipulations. Thoroughly review the Settlement details, cross-checking them against the corresponding transaction records to ensure all amounts and counts are consistent and accurate. - **Large Negative Settlements** - Negative Settlements can occur when the refund amount exceeds the initial transaction value, resulting in a net negative balance. While negative Settlements are not inherently problematic, they should still be closely examined. Unusually large negative Settlements may warrant further investigation to confirm their legitimacy. This scrutiny helps prevent potential losses, chargebacks, or disputes arising from excessive refunds or unauthorized refunds initiated by bad actors. Additional best practices you can take include: - Monitoring the [Failed Funding Report](/guides/managing-operations/insights-reports/reports#failed-funding-instructions) and reaching out to sellers with closed accounts. - Reaching out to sellers with insufficient funds. Regularly monitoring and investigating Settlements for abnormalities or inconsistencies allows you to take preventive measures, ensuring smooth and secure transactions within your payments experience. ## Creating Settlements On a daily schedule, Finix will automatically create Settlements: - Monday through Friday on our `LITLE_V1` processor. - Every day using the `VANTIV_V1` processor. ### Payment Facilitators (Finix core) timelines If you are a payment facilitator, you will need to approve your user's Settlements by 3:30 PM PST. If a Settlement gets approved after 4:00 PM PST, the Funding Transfer is sent to the merchant the following business day. ### Managed Settlement flow (Finix flex) If you are on Flex, Finix will automatically review all Settlements and approve them. Settlements can get delayed if Entries or transactions get flagged for review. Settlements that require further review get held for risk review. Finix's team will reach out to you via a support ticket if further investigation is needed. ## Settlement schedules Settlements for `Merchants` using the `LITLE_V1` and `VANTIV_V1` processors get completed Monday-Friday with the exception of federal banking holidays. Finix Core customers must approve Settlements before 7:00 PM Eastern Time (4:00 PM Pacific Time) for sellers to receive next day funding. We recommend approving settlements no later than 6:00 PM Eastern Time to allow time for additional adjustments or review. ### Weekly Settlement schedule Weekly `LITLE_V1` Schedule | Day of the Week | Settlement Approval Day | Reconciliation Day | | --- | --- | --- | | Monday | Approve Monday | Monday | | Tuesday | Approve Tuesday | Tuesday | | Wednesday | Approve Wednesday | Wednesday | | Thursday | Approve Thursday | Thursday | | Friday | Approve Friday | Friday | Weekly `VANTIV_V1` Schedule | Day of the Week | Settlement Approval Day | Reconciliation Day | | --- | --- | --- | | Monday | Approve previous Saturday | Saturday, Sunday, Monday | | Tuesday | Approve Sunday - Tuesday | Tuesday | | Wednesday | Approve Wednesday | Wednesday | | Thursday | Approve Thursday | Thursday | | Friday | Approve Friday | Friday | ### Federal banking holidays Settlements don't process on federal banking holidays, so approvals and funding shift to the next business day. For holidays falling on Saturday, Federal Reserve Banks are open the preceding Friday. For holidays falling on Sunday, they're closed the following Monday. For the current schedule of federal banking holidays, see the [Federal Reserve's holiday schedule](https://www.federalreserve.gov/aboutthefed/k8.htm). ### Holiday Settlement schedules No Settlements are funded or approved on the holiday itself. Transaction activity from the holiday accumulates and gets settled on the following business days: - For `Merchants` using `VANTIV_V1`, the accumulated Settlements get approved on each of the business days following the holiday. - For `Merchants` using `LITLE_V1`, all accumulated Settlements get approved on the first business day after the holiday. --- # Seller Payouts Source: https://docs.finix.com/guides/platform-payments/seller-payouts Learn how to pay out sellers for the payments they've processed. Seller Payouts Hero Finix makes it easy to payout sellers. You can manage how sellers get paid out using the Finix Dashboard or our API. ## Learn more Managing Seller Payouts Learn to manage how your sellers get paid. Tracking Seller Payouts Learn how to track your sellers' payouts. Accruing Settlements Learn how payments get collected into Settlements. --- # Managing Failed Payouts Source: https://docs.finix.com/guides/platform-payments/seller-payouts/managing-failed-payouts Learn how to manage payouts that get returned. ## Failed Payouts overview There are several reasons why payouts (also known as Funding Transfers) can fail and return to you. The most common reason is that the Seller's payout bank account information is incorrect. When Funding Transfers fail, Finix will mark them as `failed` and tagged with the ACH Return Reason Code. You may need to reach out to your seller to update bank account information. ## Resending a failed funding Transfer using the Dashboard If a payout to a merchant's bank account does not go through, you can resend the failed funding transfer using the Finix dashboard after the `Merchant` has updated their bank account information. To resend a failed funding transfer using the dashboard: 1. From the **Merchant Account** page, click **Payouts**, then **Settlements**. 2. Click a settlement from the list of settlements to view its details. 3. Scroll down to **Settlement Deposits** to see a list of all settlement funding transfers. 4. A failed settlement funding transfer is in a `Failed` state. 5. You can resend the transfer by clicking the **Re-send Transfer** button. - A **Resend Funding Transfer Instructions** modal displays. 6. From the modal, select a **Payment Instrument**. - If successful, a new settlement funding transfer displays in the list with a state of `SUCCEEDED`. ## Resending a failed funding Transfer using the API To resend a failed settlement funding transfer, send a request to the PUT `/settlements/{settlement_id}`, including the `destination` (merchant's bank account) and `rail` (always `ACH`) in the request body: Example ```shell curl -i -X PUT \ -u USrsBRw5q8f8ZcuWvrWsZro1:c00462f6-251c-47a7-aa12-31d7e7b4fa8c \ https://finix.sandbox-payments-api.com/settlements/STcuLDR3uAhut6DBAnDSB2a \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "destination": "PIeuV9AEb5hFxSzVLDqiGdne", "rail": "ACH" }' ``` API Definition To confirm if the retry was successful, [list the settlement funding transfers](/api/settlements/listsettlementfundingtransfers) and look for a new `Transfer` marked as `CREDIT` with the same details and amount as the failed transfer. ## Automatically retrying failed funding Transfers If a funding transfer fails, Finix disables the merchant's settlements and automatically retries the funding transfer according to the following schedule: - **First retry** - 1 business day after the initial failure - **Second retry** - 3 business days after the first retry fails - If both retries fail, Finix debits the platform bank account on file If the platform debit also fails, the outstanding balance is applied as a deduction to platform's next residual payout. To identify which merchant accounts are driving failed debits, navigate to **Merchants** → **Merchant Payouts** → **Merchant Deposits** in the Dashboard and filter by **Failed**. ## Funding Transfer resource You can fetch Funding Transfers from the `/transfers` endpoint. Funding Transfers get processed on the ACH rails and behave like ACH payments (also known as eChecks). ```json Failed Funding Transfer { "id": "TRxxxxxx", "amount": 500, "tags": {}, "state": "FAILED", "trace_id": "FNXxxxxxx", "currency": "USD", "application": "APxxxxxx", "source": null, "destination": "PIxxxxx", "ready_to_settle_at": null, "fee": 0, "statement_descriptor": null, "type": "CREDIT", "messages": [ "ReasonCode: R03", "ReasonDescription: No Account/Unable to Locate Account", "Declined because there is a record in FAILED_FUNDS for 'FNXxxxxxxx' transfer" ], "raw": { "Return Date": "xx/xx/2019", "Original Date": "xx/xx/2019", "Attempted Funds Transfer Date": "xx/xx/2019", "Merchant Name": "xxx xxxx xxxx xxx", "Sub Merchant Business Name": "xxx xxx xxx", "Funding Sub Merchant ID": "0xxxxxx", "Funds Transfer Request ID": "FNXxxxxx", "Vantiv Payment ID": "xxxxx", "Txn Type": "FISC", "Funds Transfer Amount": 500.0, "Reason Code": "R03", "Reason Message": "No Account/Unable to Locate Account", "Routing Number": "xxxxx", "Account Number": "XXxxxxx", "Account Name": "xxx xxx xxx" }, "created_at": "xxxx", "updated_at": "xxxx", "idempotency_id": null, "merchant": "MUxxxxx", "merchant_identity": "IDxxxxx", "subtype": "SETTLEMENT_MERCHANT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APxxxxxx" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRxxxxxx" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDxxxxx" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRxxxxxx/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRxxxxxx/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TRxxxxxx/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRxxxxxx/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIxxxxx" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8" } } } ``` ## Resolving funding instruction failures Failed funding transfers will receive these ACH Return Reason Codes in the Transfer's `messages` array. | Code | Failure Message | Description | Next Steps | | --- | --- | --- | --- | | R01 | Insufficient Funds | The bank account doesn't have enough funds to cover the transaction. | - Reach out to your user and confirm the bank account information entered is correct. | | R02 | Account Closed | A previously active account has been closed by an action of the customer or the RDFI. | - Contact your user for another form of payment or a different bank account. - If you haven't shipped the goods or provided the services covered by the payment, we recommend waiting to do so until you have confirmed the funding instructions transfer has settled. | | R03 | No Account / Unable to Locate Account | The account number structure is valid, and it passes the check digit validation, but the account number does not correspond to the individual identified in the entry, or the account number designated is not an open account. | - Reach out to your user and confirm the Routing Number, Bank Account Number, and the exact name on the bank account. You can request a copy of a voided check to use for verification. - If this information does not exactly match what you initially entered, create a new Payment Instrument with the needed changes and submit the Funding Instructions again. | | R04 | Invalid Account Number | The account number structure is not valid. The account number may have failed the check digit validation or has the wrong number of digits. | - Reach out to the user and request the correct bank account number. Request a copy of a voided check to verify the bank account number provided. - Create a new Payment Instrument with the correct bank account number and submit the Funding Instructions again. | | R05 | Unauthorized Debit Entry | The account number structure isn't valid. The account number may have failed the check digit validation or has the wrong number of digits. | - Don't re-submit the funding instruction to the same Payment Instrument. Any additional attempts will get returned unless your customer explicitly instructs their bank to accept them. - Reach out to the user and resolve any issues that caused the transaction to get disputed. - You can ask the user for another form of payment or a different bank account. - If you need to debit the same bank account, ask the user to call their bank and remove the block on transactions. - Unfortunately, there is no dispute resolution available within the ACH Network. If your customer continues to claim the transaction was not authorized, but you have proof that it was authorized correctly, please reach out to your Finix point of contact. | | R06 | Returned per ODFI’s Request | The ODFI (Originating Depository Financial Institution) has requested that the RDFI (Receiving Depository Financial Institution) return the ACH entry. If the RDFI agrees to return the entry, the ODFI must indemnify the RDFI according to Article Five (Return, Adjustment, Correction, and Acknowledgment of Entries and Entry Information) of the ACH Rules. | - Reach out to your Finix point of contact. | | R07 | Authorization Revoked by Customer (adjustment entries) | Authorization Revoked by Customer – Consumer, who previously authorized ACH payment, has revoked authorization from the Originator (must be returned no later than 60 days from the settlement date, and the customer must sign an affidavit). | - Immediately suspend any recurring payments entered for this bank account/Payment Instrument. This prevents additional transactions from being returned while you address the issue with the user. - Reach out to your user and resolve any issues that caused the funding instructions to get disputed. - You can ask the user for another form of payment or a different bank account. - If you need to debit the same bank account, instruct the user to call their bank and remove the block on transactions. - Unfortunately, there is no dispute resolution available within the ACH Network. If your customer continues to claim the transaction was not authorized, but you have proof that it was authorized correctly, please reach out to you | | R08 | Payment Stopped or Stop Payment on Item | The Receiver of a recurring debit transaction has the right to stop payment on any specific ACH debit. The RDFI should verify the Receiver’s intent when a request to stop payment gets made to verify the request isn't intended to be a revocation of the authorization. | - Reach out to your user and resolve any issues that caused the funding instructions to stop. - You can try re-submitting the funding instructions again once you have proper authorization from the user. Alternatively, you can request another or different form of payment. | | R09 | Uncollected Funds | A sufficient book or ledger balance exists to satisfy the dollar value of the transaction, but the dollar value of transactions in the process of collection (i.e., uncollected checks) brings the available and/or cash reserve balance below the dollar value of the debit entry. | - Try submitting the funding instructions again. You can try up to two more times within 30 days of the original authorization date. | | R10 | Customer Advises Not Authorized; Item Is Ineligible, Notice Not Provided, Signatures Not Genuine, or Item Altered (adjustment entries) | For entries to Consumer Accounts that are not PPD debit entries constituting notice of presentment or PPD Accounts Receivable Truncated Check Debit Entries in accordance with Article Two, subsection 2.1.4(2), the RDFI has been notified by its customer, the Receiver, that the Originator of a given transaction has not been authorized to debit his account.[For entries to Consumer Accounts that are not PPD Accounts Receivable Truncated Check Debit Entries in accordance with Article Two, subsection 2.1.4(2) (Authorization/Notification for PPD Accounts Receivable Truncated Check Debit Entries), the RDFI has been notified by its customer, the Receiver, that the Originator of a given transaction has not been authorized to debit his account. | - Immediately suspend any recurring payments for this bank account/Payment Instrument. This prevents additional transactions from being returned while you address the issue with the user. - Reach out to your user and resolve any issues that caused the funding instructions to get disputed or canceled. - You can ask the user for another form of payment or a different bank account. - If you need to debit the same bank account, instruct your user to call their bank and remove the block on transactions. - Unfortunately, there is no dispute resolution available within the ACH Network. If your customer continues to claim the transaction was not authorized, but you have proof that it was authorized correctly, please reach out to your Finix point of contact. | | R11 | Customer Advises Entry Not in Accordance with the Terms of the Authorization | Used by the RDFI to return an entry for which the Originator and Receiver have a relationship, and an authorization to debit exists, but there is an error or defect in the payment such that the entry does not conform to the terms of the authorization. (i.e., “an incorrect amount,” “payment was debited earlier than authorized” ) For ARC, BOC, or POP errors with the original source document and errors may exist. (i.e., “document is ineligible”, “notice was not provided to Receiver”, “amount was not accurate per the source document”). | - Reach out to your user and resolve any issues that caused the funding instructions to get disputed or canceled. You’ll need to submit the funding instructions again. | | R12 | Branch Sold to Another DFI | A financial institution may continue to receive entries destined for an account at a branch that has been sold to another financial institution. Because the RDFI no longer maintains the account and is unable to post the entry, it should return the entry to the ODFI. | - Reach out to the user and obtain a new Routing Number and Bank Account Number. Create a new Payment Instrument with the information and submit the funding instructions again to this new instrument. | | R13 | RDFI not qualified to participate | Financial institutions are not qualified to participate in ACH, or the routing number is incorrect. | - Verify the Routing Number is correct. If necessary, reach out to the user to verify bank information. You’ll need to submit the funding instructions again. | | R14 | Representative Payee Deceased or Unable to Continue in that Capacity | The representative payee is a person or institution authorized to accept entries on behalf of one or more other persons, such as legally incapacitated adults or minor children. The representative payee is either deceased or unable to continue in that capacity. The beneficiary is not deceased. | - Reach out to the user and request another form of payment. | | R15 | Beneficiary or Account Holder (Other Than a Representative Payee) Deceased | (1) The beneficiary is the person entitled to the benefits and is deceased. The beneficiary may or may not be the account holder; or(2) The account holder (acting in a non-representative payee capacity) is an owner of the account and is deceased. | - Reach out to the user and obtain a new Routing Number and Bank Account Number. Create a new Payment Instrument and submit the funding instructions again to this new instrument. | | R16 | Account Frozen | The funds in the account are unavailable due to specific action taken by the RDFI or by legal action. | - Reach out to the user and request a different form of payment. You won't be able to process any transactions using this bank account until it is un-frozen. | | R17 | File Record Edit Criteria (Specify) | Some fields that are not edited by the ACH Operator are edited by the RDFI. If the entry cannot be processed by the RDFI, the field(s) causing the processing error must be identified in the addenda record information field of the return. | - Verify the Routing and Account Number are correct. If necessary, reach out to the user to verify bank information. If the information is correct, request a different form of payment. You’ll need to submit the funding instructions again. | | R20 | Non-Transaction Account | The ACH entry is destined for a non-transaction account. This would include either an account against which transactions are prohibited or limited. | - Contact your user for another form of payment or a different bank account. | | R23 | Credit Entry Refused by Receiver | The Receiver may return a credit entry because one of the following conditions exists: (1) a minimum amount required by the Receiver has not been remitted; (2) the exact amount required has not been remitted; (3) the account is subject to litigation and the Receiver will not accept the transaction; (4) acceptance of the transaction results in an overpayment; (5) the Originator is not known by the Receiver; or (6) the Receiver has not authorized this credit entry to this account. | - Reach out to the user and resolve any issues that could have caused the transaction to be stopped or refused. - Alternatively, you can send your customer a paper check for the refund amount. | | R29 | Corporate Customer Advises Not Authorized | The RDFI has been notified by the Receiver (non-consumer) that the Originator of a given transaction has not been authorized to debit the Receiver’s account. | - Immediately suspend any recurring payments scheduled for this bank account/Payment Instrument. This prevents additional transactions from being returned while you address the issue with the user. - Contact your user for another form of payment or a different bank account. - If you need to debit the same bank account, instruct your customer to call the bank and remove the block on transactions. - Unfortunately, there is no dispute resolution available within the ACH Network. If your customer continues to claim the transaction was not authorized, but you have proof that it was authorized correctly, please reach out to your Finix point of contact. | ## Notification of change (NOC) A Notification of Change (NOC) is a notice sent from a customer’s bank detailing the information that changed in a transaction to allow it to be successful. For example, if you paid out one of your merchants, and they accidentally put the wrong routing number or bank account number. Instead of the transaction failing, a NOC gets generated as the bank successfully delivers the payout to the merchant. The NOC informs the Payment Facilitator of what occurred and provides the necessary information to rectify the issue. When a NOC of change happens, depending on the changes made, you may receive a Payment Instrument updated webhook event as Finix complies with NOC laws from NACHA. | Code | Description | Next Steps | | --- | --- | --- | | C01 | Incorrect account number | Update the Payment Instrument with the correct account number | | C02 | Incorrect routing/transit number | Update the Payment Instrument with the correct routing number | | C03 | Incorrect routing/transit number and incorrect account number | Update the Payment Instrument with the correct routing and account number | | C04 | Incorrect account name | Update the Payment Instrument with the correct account name | --- # Managing Seller Payouts Source: https://docs.finix.com/guides/platform-payments/seller-payouts/managing-seller-payouts Settlements contain the transactions and money movements that sellers process. Settlements include payments, refunds, adjustments, and fees. When Finix approves Settlements, Finix creates Funding Transfers to deliver your seller's payouts. For additional details on Settlements and payouts, see Collecting Payouts. ## Payout schedules Your seller receives payouts depending on their payout schedule. Finix offers several different schedules to manage payouts. | Type | Description | | --- | --- | | Daily | Settlements become ready for approval every business day. | | Monthly | Settlements become ready for approval on a monthly basis. | | Manual | Settlements become ready for approval manually on an on-demand basis (PayFacs only). | For any additional questions, please contact the Finix Support team. Payout Preferences ## Payout types | Type | Description | | --- | --- | | Net | Finix deducts fees from the payouts to your sellers. Finix combines deposits and fees into one combined Funding Transfer. | | Gross | Finix distributes deposits and fees into two separate Funding Transfers. | ### Net Net Payout Diagram If you had $1,000 in Payment and $30 in Fees, your seller would receive a payout of $970 to their payout bank account. ### Gross Net Payout Diagram If you had a $1,000 Payment and $30 in Fees, your seller would receive two payouts. The first would be a $1,000 credit to the seller's bank account. The second would be a debit of $30 to the seller's other bank account. Using Finix, you can manage what bank accounts get used for your sellers' payouts. This includes which bank accounts you use for payouts and fees. ## Payout speed Finix uses Next Day ACH to payout your sellers. Next Day ACH is offered by default to Finix Flex customers. Through Next Day ACH, funds from payouts are available in sellers bank accounts the business day after the settlement is approved. If you have any questions about the delivery of payouts, please reach out to your Finix point of contact or the Finix Support team. ## Reconciliation Three options are available to control when Transfers appear in Settlements and are ready to settle: | Option | Description | | --- | --- | | Reconciliation | Transfers appear in Settlements only when Finix receives the Confirmation Settlement file from the processor detailing that the Transfer has been settled. | | Processor Window | Transfers are added to Settlements based on the estimated settlement window provided by the processor. | | Successful Capture | Finix places Transfers in Settlements immediately when the state becomes Succeeded. | ## Negative Payouts In some cases, your sellers can have a negative balance. For example, if the seller receives $200 but refunds $300, their account balance would be -$100. If the seller doesn't receive further payments or process transactions to balance out the negative amount, Finix creates a Funding Transfer that debits the seller's bank account. ## Managing Payouts with the Dashboard To manage the Payout Settings of a seller: 1. Open the Merchant Account of the seller. 2. Click the **Account Settings** → **Payout Settings** tab. 3. To change Payout Settings, click **Edit**. View Payout Settings Edit Payout Settings If you run into any issues changing payout settings, contact the Finix Support team. --- # Merchant Payouts on Mobile Source: https://docs.finix.com/guides/platform-payments/seller-payouts/merchant-payouts-mobile You can follow a settlement from accrual through payout without leaving your phone. The **Merchant Payouts** section of the Finix iOS app shows your open and approved settlements, explains how each net amount was calculated, and handles the actions you'd otherwise go to the web dashboard for. ## Getting Started Open the iOS app and tap **More** in the bottom navigation bar. Select **Merchant Payouts** from the menu. The Merchant Payouts screen has two segments at the top: **Settlements** and **Merchant Deposits**. Tap either segment to switch between them. ## Settlements The Settlements segment lists your settlements grouped by date. Each row shows a status icon, the net amount, and the time and current status. If your dashboard covers more than one merchant, the merchant name appears as well. Pull down to refresh the list. More settlements load automatically as you scroll toward the end. Merchant Payouts settlements list grouped by date ### Filtering Settlements Tap the filter button in the navigation bar to open the filter sheet. Once filters are active, the button shows a badge with how many you've applied. You can combine any of the following filters: | Filter | Description | | --- | --- | | Amount | Total amount condition (equals, greater than, or less than) | | Date Range | Start and end date | | Funding Transfer Speed | `NEXT_DAY_ACH` or `SAME_DAY_ACH` | | Merchant Account ID | Exact match on merchant ID | | Net Amount | Net amount condition | | Settlement Entry ID | Exact match on entry ID | | Split Transfer ID | Exact match on split transfer ID | | Transfer ID | Exact match on transfer ID | | State | Accruing, Approved, or Awaiting Approval | Settlement filter sheet ## Settlement Detail Tap any settlement row to open its detail screen. The detail screen has two tabs: **Overview** and **Settlement Entries**. ### Overview Tab The Overview tab opens with three summary rows: **Transactions**, **Fees**, and **Net Amount**. Tap **Show Breakdown** for the full [Financial Breakdown](#financial-breakdown). Below the summary, the Details section lists the settlement ID, schedule type, accrual window, and key dates. Once a settlement is **Approved**, a **Merchant Deposits** section appears with the payout transfers that moved funds to the merchant's bank account. Partner and platform dashboards also get a **Platform Deposits** section. Direct (single-merchant) dashboards show only Merchant Deposits. Settlement detail screen showing the Overview tab with summary rows and Show Breakdown button ### Settlement Entries Tab The Settlement Entries tab lists the line items included in the settlement. Entries load the first time you tap the tab, and more load as you scroll. Each row shows an icon for the entry type, the amount, a type label, the linked instrument, and the entry's status. Settlement Entries tab showing settlement line items ## Financial Breakdown Tap **Show Breakdown** on the Overview tab to see how the net amount was calculated. The breakdown is read-only, and it walks through each part of the total: | Section | Description | | --- | --- | | Payments | Total captured payment volume | | Refunds | Refund amounts deducted from the total | | Disputes | Dispute deductions | | Adjustments | Any manual adjustments | | Fees | Platform and processing fees | As in the web dashboard, deductions appear in parentheses, like `($5.00)`. The **Net Amount** row sits at the bottom in bold. Settlement breakdown screen showing Payments, Refunds, Disputes, Adjustments, Fees, and Net Amount ## Merchant Deposits The Merchant Deposits segment lists payout transfers, with the amount, subtype, and linked payment instrument on each row. Tap a row for the full deposit detail, including the source and destination payment instruments. Merchant Deposits list showing payout transfers with amount, subtype, and payment instrument ## Actions ### Stop Accruing You can stop any settlement that's still **Accruing** (`PENDING`). Open the settlement detail, tap the ellipsis `...` menu in the top-right corner, and select **Stop Accruing**. The settlement closes right away and goes through the normal approval and payout process. For the web dashboard equivalent, see [Accruing Settlements](/guides/platform-payments/seller-payouts/accruing-settlements). ### Remove from Settlement You can remove an entry from any settlement that isn't **Approved** yet. Open the entry, either from the Settlement Entries tab or from a Transaction detail screen, tap the ellipsis `...` menu, and select **Remove from Settlement**. The app takes you back to the settlement detail and refreshes the list. Removed entries move to an Exception Settlement. Contact Finix support to make sure the Exception Settlement is rejected before the daily settlement review. For the web dashboard equivalent, see [Removing Entries from Settlements](/guides/platform-payments/seller-payouts/removing-entries-from-settlements). ### Open in Web Dashboard The settlement detail ellipsis menu always includes this option, which opens the matching page of the Finix web dashboard in your browser. On entry details, it's limited to fee entries, the ones with an `FE...` ID. --- # Releasing Transactions Manually Source: https://docs.finix.com/guides/platform-payments/seller-payouts/releasing-transactions-manually Use Finix's Settlement Queue to control when to release transactions to Settlements. For Platforms such as marketplaces or specialized ISVs, there might be a need to control when to release funds to Settlements. For example, you may not release a transaction until the sellers ship goods to buyers or enough trust has been obtained before releasing funds. Finix offers an easy and streamlined way via API to manage holding onto and releasing funds. ## Settlement queue overview If a Merchant's `settlement_queue_mode` is set to `MANUAL`, Finix will automatically place all transactions (Sales, Fees, Refunds, and ACH Returns) into a Settlement Queue that you can manage. Each transaction will have a `Settlement Queue Entry`. When a `Settlement Queue Entry` is created, it will not be placed into `Settlement` until the `Settlement Queue Entry` is explicitly released. ## Settlement queue entry Auto-release Finix requires all Settlement Queue Entries to be released within 30 days of creation. When an ACH return or refund is received, Finix automatically handles releasing the related entries: - If the original transaction has **not yet been released**, Finix automatically releases both the original transaction and the ACH return or refund. - If the original transaction has **already been released**, Finix automatically releases the ACH return or refund. This same behavior applies to ACH credit returns on an ACH refund. ## Enabling your account to release transactions manually To enable your account to use our Settlement Queue, contact our support team. We can enable this feature at an Application level for all your merchant or only for select merchants. ## Releasing a Settlement queue entry Release Timing Settlement Queue Entries can only be released on or after their `ready_to_settle_at` date. Attempting to release an entry before that date returns the following error: `Unable to Release Entries.` ### Step 1: Fetching a Settlement entry queue To release a `Settlement Queue Entry`, you first need to find the entry you are looking for. We offer an `entity_id` filter where you can pass in the resource you are looking for or you can instead query all Settlement Queue Entries. For more information, you can view our Settlement Queue API Reference. ```shell Fetch Settlement Queue Entries curl -i -X GET \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ 'https://finix.sandbox-payments-api.com/settlement_queue_entries?entity_id=TRdhp3DszqDKbNvwtn7DDcUi' \ -H 'Finix-Version: 2022-02-01' ``` ### Step 2: Release Settlement entry queue After finding the settlement_queue you are interested, you then can release the funds based on your business logic. For example, you may want to wait until someone provides a shipping label before releasing a `Transfer` or a `split_transfer`. Some customers choose to release items in bulk which our API also supports. ```json Release Settlement Queue Entries curl "https://finix.sandbox-payments-api.com/settlement_queue_entries" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -X PUT \ -d '{ "ids": [ "settlement_queue_entry_3z2B57VFx6tatMwyf5VbZz", "settlement_queue_entry_3zrNVXpNkq87ae9by5dMWd" ], "action": "RELEASE" }' ``` After a Settlement Queue Entry is released, the transaction will be placed into a Settlement. Each settlement will be paid out depending on the Merchant's Payout Settings. ## Enabling a Merchant to use Settlement queue To enable a `Merchant` to use the Settlement Queue, set `settlement_queue_mode: MANUAL` for the desired `Merchant`. By default, `settlement_queue_mode` is set to `UNSET`. Example API Definition To stop a `Merchant` from using the Settlement Queue, set `settlement_queue_mode: UNSET` for that `Merchant`. --- # Removing Entries from Settlements Source: https://docs.finix.com/guides/platform-payments/seller-payouts/removing-entries-from-settlements Learn how you can remove entries from a Seller's Settlement to minimize risk exposure An `entry` can correspond to a Sale, Capture, Refund, or Fee. All `entries` are viewable in a Settlement on the Dashboard or via API. There are many scenarios in which you might want to remove an `entry` from a Settlement. For example, you may be unsure whether a specific sale is fraudulent or not and would rather have Finix's risk team reject the Settlement. ## How to remove entries from Settlements To remove an entry from a Settlement using the Dashboard: 1. Navigate to the Settlement. 2. Click the **Settlement Entries** tab. 3. Click the entry you want to remove. 4. Click the three horizontal dots `...` and select **Remove from Settlement**. Remove Entries on Mobile You can also remove entries from a Settlement in the Finix iOS app. Open the Settlement, go to the **Settlement Entries** tab, tap the entry you want to remove, and select **Remove from Settlement** from the ellipsis menu. For more, see [Merchant Payouts on Mobile](/guides/platform-payments/seller-payouts/merchant-payouts-mobile). Settlement details page with an entry selected for removal 1. Click **Remove**. Confirmation modal for removing an entry from a Settlement - Removing an entry moves it to an [Exception Settlement](#exception-settlements). After removing entries, contact Finix to ensure the Exception Settlement is rejected before the daily settlement review: 1. Locate the Exception Settlement generated for the removed entries (see [Exception Settlements](#exception-settlements) below) and copy its ID. 2. Email support@finix.com with the Exception Settlement ID. Emailing Finix Support When emailing Finix Support, include the Exception Settlement ID (STxx) you'd like to reject. ## Exception Settlements When an entry is removed from a Settlement, it moves to an Exception Settlement. You can locate Exception Settlements for a merchant by: - Going to **Merchant Payouts** → **Settlements** tab. A new Exception Settlement appears as soon as entries are removed. - Finding the original Sale, Capture, or Fee. The top nav bar shows the new Settlement it belongs to. --- # Tracking Seller Payouts Source: https://docs.finix.com/guides/platform-payments/seller-payouts/tracking-payouts Learn how to track your sellers' payouts. When Finix approves settlements, Finix will notify you with webhooks. Each approved settlement contains a Funding Transfer that corresponds to a deposit in the your seller's bank account. The webhook you receive details the `state` change in the Funding Transfer. ## Estimated funds timing When a Funding Transfer gets sent, your seller will receive the deposit one business day after it is approved. The cutoff is 4 PM PST on business days. | Day Funding Transfer is created | Day funds will deposit in Merchant's bank account | | --- | --- | | Monday | Tuesday | | Tuesday | Wednesday | | Wednesday | Thursday | | Thursday | Friday | | Friday | Monday | | Saturday | Tuesday | | Sunday | Tuesday | | Monday | Tuesday | ## Unsuccessful funds If the Funding Transfer isn't successful, the state of the transfer will become `failed`. For more information, see Managing Failed Payouts. ## Funding Transfer ```json Funding Transfer Resource { "_embedded": { "transfers": [ { "id": "TR34zjBBxXnT1mNDWvTq8usW", "amount": 54919, "tags": {}, "state": "SUCCEEDED", "trace_id": "ea085f9d-2b9a-4388-8ff9-e4f5112a26f1", "currency": "USD", "application": "APiwqrQ7wxQQ6AgJtKz8ibC7", "source": "PI66ubeZmbbV93ES6DXCqfsC", "destination": null, "ready_to_settle_at": "2020-05-27T04:00:00.00Z", "externally_funded": "UNKNOWN", "fee": 0, "statement_descriptor": null, "type": "DEBIT", "messages": [], "raw": null, "created_at": "2020-02-18T22:35:06.42Z", "updated_at": "2020-02-18T22:36:12.09Z", "idempotency_id": null, "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDrE9ezGKCZhFN7NCigZ3TbC", "subtype": "SETTLEMENT_MERCHANT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APiwqrQ7wxQQ6AgJtKz8ibC7" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TR34zjBBxXnT1mNDWvTq8usW" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDrE9ezGKCZhFN7NCigZ3TbC" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TR34zjBBxXnT1mNDWvTq8usW/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TR34zjBBxXnT1mNDWvTq8usW/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TR34zjBBxXnT1mNDWvTq8usW/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TR34zjBBxXnT1mNDWvTq8usW/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI66ubeZmbbV93ES6DXCqfsC" } } } ] }, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/settlements/STsBXhy8shZtyif935DL2s2q/funding_transfers/?offset=0&limit=20&sort=created_at,desc&sort=id,desc" } }, "page": { "offset": 0, "limit": 20, "count": 2 } } ``` --- # Adding Funds to your Finix Balance Source: https://docs.finix.com/guides/payouts/adding-funds Finix makes it easy to use ACH to add funds to your Finix balance (i.e., create a "Top-Up"). By default, there is a **3-day hold** for ACH Top-Ups before your account balance increases. This accounts for risk and possible returns. Adding Funds Using a Wire We offer support for sending wires to quickly top up your bank account. To learn more, contact your Finix Representative. You can top up your account using the Finix Dashboard or API. Dashboard ## Topping up your account using the Dashboard With the Dashboard, you can create a Top-Up to add funds to your account balance. *To Top-Up your account*: 1. From the dashboard, expand **Payouts** and select **Balance Adjustments**. 2. From the **Balance Adjustments** page, click the **Top Up Balance** button. Payouts Balance Adjustments Top Up 1. Enter the amount you want to top up. 2. Select the bank account to use for the Top-Up. 3. Add a note about the Top-Up. 4. Click **Review**. Top Up Your Account 1. Review the **Transaction Details**. 2. If the information is correct, click **Submit**. - A message appears indicating that your balance adjustment is being processed. - You are presented with the option to **Add More Funds** and **View Balance Adjustments**. 3. Click **View Balance Adjustments** to return to the **Balance Adjustments** screen. - Your Top-Up is displayed in the list of balance adjustments. API ## Topping up your account using the Finix API To create a Top-Up using the API, you will need to create a `Balance Adjustment` resource that will track the Top-Up. To do so, send a request to the [POST /balance_adjustments](/api/balance-adjustments/createbalanceadjustment) endpoint to create a `Balance Adjustment`. ```shell Balance Adjustment Request curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/balance_adjustments \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "amount": 19, "currency": "USD", "description": "Sample balance adjustment", "instrument_id": "PI4Ppf8rxWYapuEqQr3u6efi", "processor": "DUMMY_V1", "rail": "ACH", "type": "TOP_UP", "tags": { "name": "Sample balance adjustment" } }' ``` ```json Balance Adjustment Response { "id": "balance_adjustment_kkYD8Hen6Ri8bkPErceifY", "created_at": "2025-11-14T17:30:28.172363Z", "updated_at": "2025-11-14T17:30:28.545956Z", "amount": 19, "balance_entry_id": "balance_entry_kno3XJ9vbymJCw15eCdSpJ", "currency": "USD", "description": "Sample balance adjustment", "failure_code": null, "failure_message": null, "instrument_id": "PI4Ppf8rxWYapuEqQr3u6efi", "rail": "ACH", "state": "SUCCEEDED", "tags": { "name": "Sample balance adjustment" }, "top_up_config_id": null, "trace_id": "9ce69925-8dfa-431a-8c7f-f846d4d33340", "type": "TOP_UP", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/balance_adjustments/balance_adjustment_kkYD8Hen6Ri8bkPErceifY" } } } ``` ## Setting up Auto Top-Up using the Dashboard Set up **Auto-Top-Up** to add funds from a selected bank account to your account balance when it falls below a set threshold. *To set up an Auto Top-Up rule*: 1. From the dashboard, expand **Payouts** and select **Balance Adjustments**. 2. From the **Balance Adjustments** page, click the **Set up Auto Top-Up** button. - The **Set up Auto Top-Up** wizard displays. 3. Select a bank account to draw funds for the Top-Up. 4. Enter a **Minimum Balance Threshold**, the lowest balance you want to maintain. 5. Enter a **Maximum Daily Top-Up**, the most the system can top up from your bank account each day. 6. Enter a name for the Auto Top-Up rule. Set up Auto Top Up Wizard 1. Click **Review**. 2. Review the Auto Top-Up details. 3. Click **Confirm** if the information is accurate. Review Auto Top Up Rule - A message appears indicating the Auto Top-Up rule was created successfully. - The **Company** page > **Company Settings** tab > **Auto Top-Up Rules** page shows the Auto Top-Up rule you created. You can only edit this rule from the **Balance Adjustments** page. --- # Bank Payouts Source: https://docs.finix.com/guides/payouts/bank-payouts Send funds to your recipient's bank account using Payouts. If you have any questions about sending payouts, reach out to your Finix Point of Contact or [Finix Support](mailto:support@finix.com). ## Bank Payout speeds Finix supports two types of bank payout options: - **Next Day ACH:** Funds sent via Next Day ACH will be available in a customer's bank account by 9 AM in their local bank time. - **Same Day ACH:** Funds sent via Same Day ACH are available Same Day if sent by the cutoff times below. ### Cutoff times The table below outlines cutoff times for Next Day ACH and Same Day ACH. | Bank Payout | Speed Finix Cutoff time | Funds in Recipient's bank account | | --- | --- | --- | | Next Day ACH | 9:30 PM ET | By 9 AM the next business day Local Time. (Can vary by bank) | | Same Day ACH | 11:30 AM ET | 5 PM Local Time of bank | | Same Day ACH | 2:30 PM ET | End of processing day | ## Step 1: Create a Recipient Identity The first step for making a payout is creating a [`RECIPIENT` Identity](/api/identities/createidentity) to represent whom you'll send funds to. The Identity resource helps manage bank accounts, cards, payout history, and the details of your customers. You can create either `PERSONAL` or `BUSINESS` Recipients. ### Required data | Required | Optional | Invalid | | --- | --- | --- | | | | | | Field | `type: PERSONAL` | `type: BUSINESS` | | --- | --- | --- | | Type `type` | | | | First Name `first_name` | | | | Last Name `last_name` | | | | Personal Address `personal_address` | | | | Business Name `business_name` | | | | Doing Business As `doing_business_as` | | | | Business Address `business_address` | | | | Business Phone `business_phone` | | | | Personal Email `email` | | | | Personal Phone `phone` | | | ### API request Personal Recipient Recipient (Personal) ```json Recipient (Personal) { "id": "IDwg9vTS2bNi12SxhScaUTui", "created_at": "2026-09-25T20:05:11.66Z", "updated_at": "2026-09-25T20:05:11.66Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "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_fingerprint": null, "business_tax_id_provided": false, "business_type": null, "default_statement_descriptor": null, "discover_mid": null, "dob": null, "doing_business_as": null, "email": null, "first_name": "John", "has_accepted_credit_cards_previously": false, "incorporation_date": null, "last_name": "Jeremy", "max_transaction_amount": 0, "mcc": null, "ownership_type": null, "personal_address": { "line1": "789 Oak Drive", "line2": null, "city": "Springfield", "region": "IL", "postal_code": "62704", "country": "USA" }, "phone": null, "principal_percentage_ownership": null, "short_business_name": null, "tax_authority": null, "tax_id_fingerprint": null, "tax_id_provided": false, "title": null, "url": null }, "identity_roles": [ // [!code highlight] "RECIPIENT" ], "tags": {}, "type": "PERSONAL", // [!code highlight] "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ``` Business Recipient Recipient (Business) ```json Recipient (Business) { "id": "IDo2fLkwALWQoMbFntPB2iMi", "created_at": "2026-09-25T20:05:11.22Z", "updated_at": "2026-09-25T20:05:11.22Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "entity": { "ach_max_transaction_amount": 0, "amex_mid": null, "annual_card_volume": 0, "business_address": { "line1": "7890 Oak Drive", "line2": "Suite 101", "city": "Smalltown", "region": "TX", "postal_code": "75432", "country": "USA" }, "business_name": "Blue Horizon Technologies", "business_phone": null, "business_tax_id_fingerprint": null, "business_tax_id_provided": false, "business_type": null, "default_statement_descriptor": null, "discover_mid": null, "dob": null, "doing_business_as": "B.H. Technologies", "email": null, "first_name": "John", "has_accepted_credit_cards_previously": false, "incorporation_date": null, "last_name": "Jeremy", "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": null, "principal_percentage_ownership": null, "short_business_name": null, "tax_authority": null, "tax_id_fingerprint": null, "tax_id_provided": false, "title": null, "url": null }, "identity_roles": [ // [!code highlight] "RECIPIENT" ], "tags": {}, "type": "BUSINESS", // [!code highlight] "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ``` ## Step 2: Create a Payment Instrument for the Recipient PCI Level 1 Compliance Creating `Payment Instruments` and passing payment details (account number, card number, etc.) directly via the API should only be done for testing purposes and by PCI Level 1 compliant entities. If you aren't a Level 1 PCI-compliant entity, you must use our [Tokenization Forms](/guides/online-payments/payment-tokenization/tokenization-forms), [Mobile Tokenization](/guides/online-payments/payment-tokenization), or [Plaid](/guides/online-payments/bank-payments/plaid-integration) to accept payment details and comply with PCI regulations. Now that we've created an `Identity` for our recipient, we'll need to create a `Payment Instrument` using the recipient's bank account. A `Payment Instrument` represents the recipient's payment method that will receive funds. When creating `Payment Instruments` for Payouts, `attempt_bank_account_validation_check` must be set to `true`. If you have any questions about creating `Payment Instruments`, reach out to your Finix Point of Contact or [Finix Support](mailto:support@finix.com). Bank Account Payment Instrument - Bank Account ```json Payment Instrument - Bank Account { "id": "PI68E8eKh1v4P2eY2PoLrzzT", "created_at": "2026-09-25T20:05:25.37Z", "updated_at": "2026-09-25T20:05:25.37Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRxpMNPZbZqVQfcHzRUJnzkR", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "BANK_ACCOUNT", // [!code highlight] "microdeposit": "microdeposit_g92m9YHXhhndZcmFAUW7Ki", "microdeposit_verification_url": "https://link.sandbox-payment-form.com/DKDrmq", "account_type": "BUSINESS_CHECKING", "bank_account_validation_check": "NOT_ATTEMPTED", "bank_code": "122105278", "country": "USA", "institution_number": null, "masked_account_number": "XXXXXX0019", "name": "Smith & Associates Consulting", "transit_number": null, "tags": {}, "third_party": null, "third_party_token": null, "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` Plaid Bank Account Payment Instrument - Plaid Bank Account ```json Payment Instrument - Plaid Bank Account { "id": "PI9RvCXMLzSHkQpUWxX7dgY4", "created_at": "2026-09-25T20:36:43.89Z", "updated_at": "2026-09-25T20:36:43.89Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRxAutj19xH1AH6ykGx2dwa7", "identity": "ID3YZagNmW2bXhJkA6RdUkdS", "instrument_type": "BANK_ACCOUNT", "account_type": "CHECKING", "bank_account_validation_check": "VALID", "bank_code": "011401533", "country": "USA", "institution_number": null, "masked_account_number": "XXXXXXXXXXX0000", "name": "John Smith", "transit_number": null, "tags": {}, "third_party": "PLAID", // [!code highlight] "third_party_token": "processor-sandbox-ab3cff03-8948-1291-f2fe-05634be2c38c", "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI9RvCXMLzSHkQpUWxX7dgY4" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI9RvCXMLzSHkQpUWxX7dgY4/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI9RvCXMLzSHkQpUWxX7dgY4/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI9RvCXMLzSHkQpUWxX7dgY4/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID3YZagNmW2bXhJkA6RdUkdS" } } } ``` ## Step 3: Verify and onboard the Recipient Now that we've associated a `Payment Instrument` with our recipient's `Identity` we're ready to provision a recipient account. This is the last step before you can begin paying out a recipient `Identity`. Luckily you've already done most of the heavy lifting - make one final POST request, and a `Merchant` resource will get returned. Example API Definition Example Merchant ```json Merchant { "id": "MU3CTeJT1MMhwaGZabCo2xwK", "created_at": "2026-09-30T00:02:16.89Z", "updated_at": "2026-09-30T00:02:16.89Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "card_cvv_required": false, "card_expiration_date_required": true, "card_network_details": null, "convenience_charges_enabled": false, "country": "USA", "creating_transfer_from_report_enabled": false, "currencies": [ "USD" ], "default_partial_authorization_enabled": false, "disbursements_ach_pull_enabled": true, "disbursements_ach_push_enabled": true, "disbursements_card_pull_enabled": true, "disbursements_card_push_enabled": true, "disbursements_same_day_ach_pull_enabled": false, "disbursements_same_day_ach_push_enabled": false, "fee_ready_to_settle_upon": "PROCESSOR_WINDOW", "first_approved_at": null, "gateway": null, "gross_settlement_enabled": false, "identity": "IDfC3Z9xVrniLsE6Hk4Zqhjv", "instant_payouts_card_push_enabled": false, "is_terminated": false, "level_two_level_three_data_enabled": false, "loan_repayment": null, "mcc": "4900", "merchant_name": "Finix Flowers", "merchant_profile": "MPh7HkSopbp5wFnTgWNQujDx", "microdeposit_verification_required_buyer": true, "microdeposit_verification_required_sender": false, "mid": null, "onboarding_state": "PROVISIONING", "pending_refunds_strategy": "SAME_DAY_ADJUSTMENT", "processing_enabled": false, "processor": "DUMMY_V1", "processor_details": {}, "ready_to_settle_upon": "PROCESSOR_WINDOW", "ready_to_settle_upon_delay_alignment": "NONE", "refunds_disabled": false, "rent_surcharges_enabled": false, "settlement_enabled": false, "settlement_funding_identifier": "UNSET", "settlement_queue_mode": "UNSET", "surcharges_enabled": false, "tags": {}, "termination_details": null, "unreferenced_refund_card_present_enabled": true, "unreferenced_refund_manual_entry_enabled": false, "verification": "VIw6VyyzVBjdoabt98e4Nrj2", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/merchants/MU3CTeJT1MMhwaGZabCo2xwK" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDfC3Z9xVrniLsE6Hk4Zqhjv" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/merchants/MU3CTeJT1MMhwaGZabCo2xwK/verifications" }, "merchant_profile": { "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPh7HkSopbp5wFnTgWNQujDx" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "verification": { "href": "https://finix.sandbox-payments-api.com/verifications/VIw6VyyzVBjdoabt98e4Nrj2" } } } ``` API Definition ## Step 4: Create a bank Payout Create a `Transfer` to send funds to the bank account. A `Transfer` represents any flow of funds to or from a `Payment Instrument`. To create a `Transfer`: 1. Choose the [bank payout speed](#choosing-your-payout-speed). 2. Set `destination` to the ID of the `Payment Instrument` for the tokenized bank account. 3. Set `amount` to the funds in cents. 4. Include an `idempotency_id`. See [Idempotent Requests](/additional-resources/developers/authentication-and-api-basics/idempotent-request) for details. ### Choosing your Payout speed #### Next day ACH For Next Day ACH, set the `operation_key` to `PUSH_TO_ACH`. Example API Definition #### Same day ACH For Same Day ACH, set the `operation_key` to `PUSH_TO_SAME_DAY_ACH`. Default Same Day ACH is not enabled by default. If you are interested in Same Day ACH, please contact your Finix representative to enable `disbursements_same_day_ach_push_enabled` for your `Application`. Example API Definition --- # Card Payouts Source: https://docs.finix.com/guides/payouts/card-payouts Send funds to your recipient's debit or credit card using Payouts. Please note card payouts are only available to Visa and Mastercard cards. Card payouts are supported for cards issued in the United States only. If you have any questions about creating payouts, reach out to your Finix Point of Contact or [Finix Support](mailto:support@finix.com). ## Step 1: Create a Recipient Identity The first step for making a payout is creating a [`RECIPIENT` Identity](/api/identities/createidentity) to represent whom you'll send funds to. The Identity resource helps manage bank accounts, cards, payout history, and the details of your customers. You can create either `PERSONAL` or `BUSINESS` Recipients. ### Required data | Required | Optional | Invalid | | --- | --- | --- | | | | | | Field | `type: PERSONAL` | `type: BUSINESS` | | --- | --- | --- | | Type `type` | | | | First Name `first_name` | | | | Last Name `last_name` | | | | Personal Address `personal_address` | | | | Business Name `business_name` | | | | Doing Business As `doing_business_as` | | | | Business Address `business_address` | | | | Business Phone `business_phone` | | | | Personal Email `email` | | | | Personal Phone `phone` | | | ### API request Personal Recipient Recipient (Personal) ```json Recipient (Personal) { "id": "IDwg9vTS2bNi12SxhScaUTui", "created_at": "2026-09-25T20:05:11.66Z", "updated_at": "2026-09-25T20:05:11.66Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "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_fingerprint": null, "business_tax_id_provided": false, "business_type": null, "default_statement_descriptor": null, "discover_mid": null, "dob": null, "doing_business_as": null, "email": null, "first_name": "John", "has_accepted_credit_cards_previously": false, "incorporation_date": null, "last_name": "Jeremy", "max_transaction_amount": 0, "mcc": null, "ownership_type": null, "personal_address": { "line1": "789 Oak Drive", "line2": null, "city": "Springfield", "region": "IL", "postal_code": "62704", "country": "USA" }, "phone": null, "principal_percentage_ownership": null, "short_business_name": null, "tax_authority": null, "tax_id_fingerprint": null, "tax_id_provided": false, "title": null, "url": null }, "identity_roles": [ // [!code highlight] "RECIPIENT" ], "tags": {}, "type": "PERSONAL", // [!code highlight] "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDwg9vTS2bNi12SxhScaUTui/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ``` Business Recipient Recipient (Business) ```json Recipient (Business) { "id": "IDo2fLkwALWQoMbFntPB2iMi", "created_at": "2026-09-25T20:05:11.22Z", "updated_at": "2026-09-25T20:05:11.22Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "entity": { "ach_max_transaction_amount": 0, "amex_mid": null, "annual_card_volume": 0, "business_address": { "line1": "7890 Oak Drive", "line2": "Suite 101", "city": "Smalltown", "region": "TX", "postal_code": "75432", "country": "USA" }, "business_name": "Blue Horizon Technologies", "business_phone": null, "business_tax_id_fingerprint": null, "business_tax_id_provided": false, "business_type": null, "default_statement_descriptor": null, "discover_mid": null, "dob": null, "doing_business_as": "B.H. Technologies", "email": null, "first_name": "John", "has_accepted_credit_cards_previously": false, "incorporation_date": null, "last_name": "Jeremy", "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": null, "principal_percentage_ownership": null, "short_business_name": null, "tax_authority": null, "tax_id_fingerprint": null, "tax_id_provided": false, "title": null, "url": null }, "identity_roles": [ // [!code highlight] "RECIPIENT" ], "tags": {}, "type": "BUSINESS", // [!code highlight] "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDo2fLkwALWQoMbFntPB2iMi/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ``` ## Step 2: Add a Payment Instrument for the Recipient PCI Level 1 Compliance Creating `Payment Instruments` and passing payment details (account number, card number, etc.) directly via the API should only be done for testing purposes and by PCI Level 1 compliant entities. If you aren't a Level 1 PCI-compliant entity, you must use our [Tokenization Forms](/guides/online-payments/payment-tokenization/tokenization-forms) or [Mobile Tokenization](/guides/online-payments/payment-tokenization) to accept payment details and comply with PCI regulations. If you have any questions, please don't hesitate to reach out to your Finix point of contact or email the [Finix Support team](/guides/getting-started/support-at-finix/). Now that we've created an `Identity` for our recipient, we'll need to create a `Payment Instrument` using the recipient's card details. A `Payment Instrument` represents the recipient's payment method that will receive funds. When creating `Payment Instruments` for Payouts, `attempt_bank_account_validation_check` must be set to `true`. If you have any questions about creating `Payment Instruments`, reach out to your Finix Point of Contact or [Finix Support](mailto:support@finix.com). Example API Definition Example Payment Instrument - Card ```json Payment Instrument - Card { "id": "PImZV8WukUEgB8iFqoSouLt1", "created_at": "2026-09-25T20:05:27.37Z", "updated_at": "2026-09-25T20:05:27.37Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "PAYMENT_CARD", // [!code highlight] "account_updater_enabled": false, "address": { "line1": "900 Metro Center Blv", "line2": null, "city": "San Francisco", "region": "CA", "postal_code": "94404", "country": "USA" }, "address_verification": "UNKNOWN", "bin": "520082", "brand": "MASTERCARD", "card_type": "DEBIT", "expiration_month": 12, "expiration_year": 2029, "issuer_country": "NON_USA", "last_four": "8210", "name": "John Doe", "network_token_enabled": false, "network_token_state": "NOT_ENABLED", "security_code_verification": "UNKNOWN", "tags": {}, "third_party": null, "third_party_token": null, "type": "PAYMENT_CARD", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" }, "updates": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/updates" } } } ``` API Definition ## Step 3: Verify the Payment Instrument After associating a payment instrument with a recipient, you must verify the card's eligibility for push-to-card by submitting the following request. The resulting `Verification` resource provides general attributes and specific card details, including card type and issuer information. Example API Definition Example Card is eligible for push-to-card ```json Card is eligible for push-to-card { "id": "VIbv4zMJ9i6VE1TnfA76g4bi", "created_at": "2026-09-25T20:05:28.48Z", "updated_at": "2026-09-25T20:05:28.54Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "identity": null, "merchant": null, "merchant_identity": null, "messages": [], "outcome_summary": null, "outcomes": null, "payment_instrument": "PIhWqjo3DU13WmFzWZFLngfa", "payment_instrument_verification_details": { // [!code highlight] "billing_currency": null, "card_type": null, "issuer_country": "UNKNOWN", "name_verification_results": { "first_name_verification": "UNKNOWN", "last_name_verification": "UNKNOWN", "middle_name_verification": "UNKNOWN", "name_verification": "UNKNOWN" }, "pull_from_card_cross_border": null, "pull_from_card_domestic": null, "push_to_card_cross_border": null, "push_to_card_domestic": null }, "processor": "DUMMY_V1", "raw": "RawDummyInstrumentVerificationResult", "reverification_reason": { "review_type": null, "initiated_by": null, "reason_description": null }, "state": "SUCCEEDED", "sub_type": null, "tags": {}, "trace_id": "e95f0e68-dab6-4b19-b8a3-3d53cdb250d2", "type": "PAYMENT_INSTRUMENT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/verifications/VIbv4zMJ9i6VE1TnfA76g4bi" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "payment_instrument": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIhWqjo3DU13WmFzWZFLngfa" } } } ``` API Definition ### Payment Instrument Verification result codes #### Card type (`card_type`) This code indicates whether the card is credit, debit, or prepaid. | `CODE` | Description | | --- | --- | | `CREDIT` | Credit or Charge Card | | `DEBIT` | Debit or Deferred Debit Card | | `HSA_FSA` | HSA or FSA Card | | `RELOADABLE_PREPAID` | Reloadable Prepaid Card | | `UNRELOADABLE_PREPAID` | Unreloadable Prepaid Card | | `UNKNOWN` | Unknown | #### Pull from card cross border (`pull_from_card_cross_border`) This field indicates whether pull-from-card functionality is supported cross-border for this instrument. | `CODE` | Description | | --- | --- | | `FAST_FUNDS` | Indicates fast fund movement is supported for this instrument | | `NON_FAST_FUNDS` | Indicates movement is supported for this instrument | | `NOT_SUPPORTED` | Indicates this instrument is not supported | | `UNKNOWN` | Unexpected verification result | #### Pull from card domestic (`pull_from_card_domestic`) This field indicates whether pull-from-card functionality is supported domestically for this instrument. | `CODE` | Description | | --- | --- | | `FAST_FUNDS` | Indicates fast fund movement is supported for this instrument | | `NON_FAST_FUNDS` | Indicates movement is supported for this instrument | | `NOT_SUPPORTED` | Indicates this instrument is not supported | | `UNKNOWN` | Unexpected verification result | #### Push to card domestic (`push_to_card_domestic`) This field is used to indicate push to card functionality is supported domestically for this instrument. | `CODE` | Description | | --- | --- | | `FAST_FUNDS` | Indicates fast fund movement is supported for this instrument | | `NON_FAST_FUNDS` | Indicates movement is supported for this instrument | | `NOT_SUPPORTED` | Indicates this instrument is not supported | | `UNKNOWN` | Unexpected verification result | #### Push to card cross border (`push_to_card_cross_border`) This field is used to indicate push to card functionality is supported cross border for this instrument. | `CODE` | Description | | --- | --- | | `FAST_FUNDS` | Indicates fast fund movement is supported for this instrument | | `NON_FAST_FUNDS` | Indicates movement is supported for this instrument | | `NOT_SUPPORTED` | Indicates this instrument is not supported | | `UNKNOWN` | Unexpected verification result | details summary Raw Message Response Arguments #### 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: Verify and onboard the Recipient account Now that we've associated a `Payment Instrument` with our recipient's `Identity` we're ready to provision a recipient account. This is the last step before you can begin paying out a recipient `Identity`. Luckily you've already done most of the heavy lifting - make one final POST request, a `Merchant` resource will get returned. Example API Definition Example Merchant ```json Merchant { "id": "MU3CTeJT1MMhwaGZabCo2xwK", "created_at": "2026-09-30T00:02:16.89Z", "updated_at": "2026-09-30T00:02:16.89Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "card_cvv_required": false, "card_expiration_date_required": true, "card_network_details": null, "convenience_charges_enabled": false, "country": "USA", "creating_transfer_from_report_enabled": false, "currencies": [ "USD" ], "default_partial_authorization_enabled": false, "disbursements_ach_pull_enabled": true, "disbursements_ach_push_enabled": true, "disbursements_card_pull_enabled": true, "disbursements_card_push_enabled": true, "disbursements_same_day_ach_pull_enabled": false, "disbursements_same_day_ach_push_enabled": false, "fee_ready_to_settle_upon": "PROCESSOR_WINDOW", "first_approved_at": null, "gateway": null, "gross_settlement_enabled": false, "identity": "IDfC3Z9xVrniLsE6Hk4Zqhjv", "instant_payouts_card_push_enabled": false, "is_terminated": false, "level_two_level_three_data_enabled": false, "loan_repayment": null, "mcc": "4900", "merchant_name": "Finix Flowers", "merchant_profile": "MPh7HkSopbp5wFnTgWNQujDx", "microdeposit_verification_required_buyer": true, "microdeposit_verification_required_sender": false, "mid": null, "onboarding_state": "PROVISIONING", "pending_refunds_strategy": "SAME_DAY_ADJUSTMENT", "processing_enabled": false, "processor": "DUMMY_V1", "processor_details": {}, "ready_to_settle_upon": "PROCESSOR_WINDOW", "ready_to_settle_upon_delay_alignment": "NONE", "refunds_disabled": false, "rent_surcharges_enabled": false, "settlement_enabled": false, "settlement_funding_identifier": "UNSET", "settlement_queue_mode": "UNSET", "surcharges_enabled": false, "tags": {}, "termination_details": null, "unreferenced_refund_card_present_enabled": true, "unreferenced_refund_manual_entry_enabled": false, "verification": "VIw6VyyzVBjdoabt98e4Nrj2", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/merchants/MU3CTeJT1MMhwaGZabCo2xwK" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDfC3Z9xVrniLsE6Hk4Zqhjv" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/merchants/MU3CTeJT1MMhwaGZabCo2xwK/verifications" }, "merchant_profile": { "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPh7HkSopbp5wFnTgWNQujDx" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "verification": { "href": "https://finix.sandbox-payments-api.com/verifications/VIw6VyyzVBjdoabt98e4Nrj2" } } } ``` API Definition ## Step 5: Send Payout Next you'll need to create a `Transfer`. A `Transfer` represents any flow of funds either to or from a `Payment Instrument`. In this case a payout to a debit or credit card. To create a `Transfer`: - Include the ID of the `Payment Instrument` of the previously tokenized card as the `destination`. - In `amount`, set the funds to send in cents. In the below example, $150.00 is getting paid out. - Recommended to include an `idempotency_id` field in the payload. For more information, see [Idempotent Requests](/additional-resources/developers/authentication-and-api-basics/idempotent-request). The recipient of the card payout must be: - an `Identity` whose `identity_roles` includes `RECIPIENT` - an approved `Merchant` Example API Definition --- # Handling Payout Failures Source: https://docs.finix.com/guides/payouts/handling-payout-failures Payouts may fail for a number of reasons. Payout failures fall into three major categories: - **Velocity Rule Failures:** Failures for exceeding Velocity Rules. - **Balance Amount Failures:** Failures for attempting to exceed the available balance in your account. - **Third-Party Network Failures:** Failures from the card networks (e.g. Visa, Mastercard) or ACH network. ## Velocity rule failures Velocity Rule failures can be the most common reasons why a payout fails. If you require a higher velocity limit, please email your Finix Point of Contact. We may follow up with additional documentation requests. ### Velocity rule failure example ```json Payout Transfer failed due to velocity rule { "id": "TRfb1QBrJVWY3UYpsX4qscDr", "created_at": "2024-07-23T18:21:58.51Z", "updated_at": "2024-07-23T18:21:58.51Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 987650, "amount_requested": 987650, "application": "AP9oVc9EjXbupwTqXJ9BRR2N", "currency": "USD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": "VELOCITY_LIMIT_EXCEEDED", "failure_message": "Daily volume limit exceeded for APPLICATION; Monthly volume limit exceeded for APPLICATION; Daily volume limit exceeded for SENDER; Monthly volume limit exceeded for SENDER", "fee": 0, "idempotency_id": null, "merchant": "MUvYobRWG33L5XKiDZmArTGu", "merchant_identity": "ID2wWmoMhhhLZxveU2qCJ4mp", "messages": [], "operation_key": "PULL_FROM_CARD", "parent_transfer": null, "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": "PIt7H487HYBZTHXNLjuHESp8", "split_transfers": [], "state": "FAILED", "statement_descriptor": null, "subtype": "API", "tags": { "test": "Velocity Limit Exceeded" }, "tip_amount": null, "trace_id": "f339e82c-39eb-42bc-85c6-a9515ea9419a", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/AP9oVc9EjXbupwTqXJ9BRR2N" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRfb1QBrJVWY3UYpsX4qscDr" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID2wWmoMhhhLZxveU2qCJ4mp" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRfb1QBrJVWY3UYpsX4qscDr/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRfb1QBrJVWY3UYpsX4qscDr/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TRfb1QBrJVWY3UYpsX4qscDr/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRfb1QBrJVWY3UYpsX4qscDr/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIt7H487HYBZTHXNLjuHESp8" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPoiqRAzS2Yo33RqqS5995db" } } } ``` ### Velocity rule error codes | Transfer `failure_code` | Description | | --- | --- | | `VELOCITY_RULE_NOT_FOUND` | Velocity rule not found. Please contact support if you have any questions. | | `VELOCITY_VALIDATION_FAILED` | Velocity validation failed. Please contact support if you have any questions. | | `VELOCITY_LIMIT_EXCEEDED` | See below for Velocity Limit Exceeded possible values. | ### Velocity limit exceeded possible values When exceeding the velocity rules, Finix will return a list of values that exceeded the velocity rules. These are the possible values: - `Monthly count limit exceeded for APPLICATION` - `Monthly count limit exceeded for RECIPIENT` - `Monthly count limit exceeded for SENDER` - `Daily count limit exceeded for APPLICATION` - `Daily count limit exceeded for RECIPIENT` - `Daily count limit exceeded for SENDER` - `Monthly volume limit exceeded for APPLICATION` - `Monthly volume limit exceeded for RECIPIENT` - `Monthly volume limit exceeded for SENDER` - `Daily volume limit exceeded for APPLICATION` - `Daily volume limit exceeded for RECIPIENT` - `Daily volume limit exceeded for SENDER` - `Maximum amount exceeded for APPLICATION` - `Maximum amount exceeded for RECIPIENT` - `Maximum amount exceeded for SENDER` ## Balance amount failures Each payout customer has a Balance that they can use to send payouts to recipients. When sending a payout, your Balance is decremented. Finix returns the following error when you attempt to send more than your available balance. ### Balance amount failure example ```json Payout Transfer failed due to balance amount { "id": "TRfjvCVjrwwVSHRxukXFVRJr", "created_at": "2024-07-23T18:22:00.50Z", "updated_at": "2024-07-23T18:22:00.50Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 8, "amount_requested": 8, "application": "AP9oVc9EjXbupwTqXJ9BRR2N", "currency": "USD", "destination": "PItQHHw4ooFYgSFAcvoLKbX9", "externally_funded": "UNKNOWN", "failure_code": "INSUFFICIENT_BALANCE", "failure_message": "Your account balance is insufficient for this operation. Please contact support if you have any questions.", "fee": 0, "idempotency_id": null, "merchant": "MUf8sYLSLqKzN1FaPZjLRrhW", "merchant_identity": "IDvHPSftftx9RjUKnibnhHN5", "messages": [], "operation_key": "PUSH_TO_CARD", "parent_transfer": null, "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": null, "split_transfers": [], "state": "FAILED", "statement_descriptor": null, "subtype": "API", "tags": { "test": "Disbursements P2C" }, "tip_amount": null, "trace_id": "82087d5e-fe69-4253-9773-13c3917fcab4", "type": "CREDIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/AP9oVc9EjXbupwTqXJ9BRR2N" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRfjvCVjrwwVSHRxukXFVRJr" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDvHPSftftx9RjUKnibnhHN5" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRfjvCVjrwwVSHRxukXFVRJr/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRfjvCVjrwwVSHRxukXFVRJr/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TRfjvCVjrwwVSHRxukXFVRJr/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRfjvCVjrwwVSHRxukXFVRJr/disputes" }, "destination": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PItQHHw4ooFYgSFAcvoLKbX9" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPoiqRAzS2Yo33RqqS5995db" } } } ``` ### Balance amount error codes | Transfer `failure_code` | Description | | --- | --- | | `INSUFFICIENT_BALANCE` | Your account balance is insufficient for this operation. Please contact support if you have any questions. | | `BALANCE_ACCOUNT_NOT_FOUND` | Balance Account not found. Please contact support if you have questions. | | `BALANCE_VALIDATION_FAILED` | Balance Validation failed. Please try again. | ## Third-Party Network failures Third-party networks occasionally return an error to Finix for a Payout. A common example could include attempting a payout to an unsupported card. Finix will return a Failed `Transfer`. In these scenarios, we recommend viewing the `Transfer#messages` object for additional details. --- # Payouts Source: https://docs.finix.com/guides/payouts Send money directly to recipients via API or the Finix dashboard. To manage seller payouts, see [Platform Payments](/guides/platform-payments/seller-payouts). Card payouts are supported for cards issued in the United States only. Payouts Hero Use Payouts to send funds directly to a recipient's bank account or card in real-time. Payouts provide a simple way to send funds to any recipient. Examples where Payouts can help you out include payouts to gig employees, loan disbursements, insurance claims, tip payouts, rebates, and other accounts payable scenarios. Signing Up Learn how to get started with Payouts. ## Learn more Managing Payouts Learn how to manage your payout activity using the Payouts Dashboard. Card Payouts Learn how to send money to recipients' credit or debit cards. Bank Payouts Learn how to send money to recipients' bank accounts. Payout Links Send one-time links so recipients can enter their own details to claim funds. Me to Me Payouts Move funds between a recipient's own bank accounts and cards. Adding Funds Top up your Finix balance with ACH or wire transfers before sending payouts. Recipient Verification Process Understand the sanctions checks Finix runs when you onboard payout recipients. Handling Payout Failures Diagnose and resolve payouts that fail before funds reach the recipient. --- # Managing Payouts Source: https://docs.finix.com/guides/payouts/managing-payouts Learn how to manage payouts, including limits you can send. When you sign up for payouts, you'll also be granted access to a Payouts Dashboard. Note, for those who already use Finix Payments, this dashboard is separate from the Finix Payments Dashboard and is dedicated entirely to helping you manage your payouts activity. Details you can manage and review includes your: - Payout history and activity - Recipients - Account balance - Payout limits For details on how to create a payout to a bank account, see [Bank Payouts](/guides/payouts/bank-payouts). For details on how to create a payout to a debit or credit card, see [Card Payouts](/guides/payouts/card-payouts). If you have any questions about creating payouts, reach out to your Finix point of contact or email the [Finix Support](/guides/getting-started/support-at-finix/) team. ## Payouts Dashboard The Payouts Dashboard is a handy tool that helps you keep track of your payout activity all in one user-friendly place. Use the Payouts Dashboard to review your payouts, manage recipients, review limits, and add funds. Add your team to the Payouts Dashboard to help your business get started creating and managing payouts through Finix. Home Page Payouts On the **Home** page, you can view: - **Daily Card Payout Volume:** The volume processed for the day compared to the maximum daily volume allowed for card transactions. - **Daily Card Payout Count:** The number of payouts processed for the day compared to the maximum number of card transactions you can process in a single day. - **Daily ACH Payout Volume:** The ACH volume processed for the day compared to the maximum daily volume allowed for ACH transactions. - **Daily ACH Payout Count:** The number of ACH payouts processed for the day compared to the maximum number of ACH transactions you can process in a single day. You can also click into an individual entry to review the payout in detail. ## Company page You can view all your payout limits on the **Company** page in one aggregated view. Company Page Payout ## Recipients page Use the **Recipients** page to review a recipient in detail. You can see the current limits set for the recipient and their current totals. Recipients Page Payouts ## Balance adjustments page Use the **Balance Adjustments** page to review your account's current balance and financial activity. Balance Adjustments Page To send payouts in a live environment, you must [top up your balance](/guides/payouts/adding-funds#topping-up-your-account-using-the-dashboard). Balance Adjustments Page ### Account Balance entry When you add funds to your account or send a payout, a `balance_entry` gets created that you can view in the Payouts Dashboard. Each `balance_entry` corresponds to either: - An incoming wire - **ACH** and **Card**: These will correspond to bank or card payouts you have processed. ### Usage fees Fees for payouts get calculated outside your account balance. As a result, your Account Balance should only reflect the addition and debit of funds due to payouts. ## Payout limits Finix incorporates limits on the volume and number of transactions you can do on a daily, weekly, and monthly rolling basis for both ACH and Card transactions. These rules help safeguard you against fraud and comply with card brand rules. On the Finix Dashboard, you can view your limits from the [Company page](#company-page). ### Types of limits Finix has limits in place that apply to both: - **Card Transactions:** Card payouts sent to recipients. - **ACH Transactions:** Bank payouts sent to recipients. These limits occur at the: - **Application Level:** Limits set at the `Application` level apply across all recipients. These limits get aggregated on a rolling basis. - An `Application` represents your account in Finix. - **Recipient Merchant Level:** Limits applied at the individual recipient level. These limits get aggregated on a rolling basis. Company Page - Payouts These limits are applied a rolling basis: | Limit | Description | | --- | --- | | Application Card Velocity Limits | Limits applied to card transactions at the `Application` level across all recipients. | | Application ACH Velocity Limits | Limits applied to bank or ACH transactions at the `Application` level across all recipients. | | Recipient Card Velocity Limits | Limits applied to card transactions for each individual recipient. | | Recipient ACH Velocity Limits | Limits applied to bank or ACH transactions for each individual recipient. | Finix can also set different time zones and start dates for each cadence (e.g., Daily, Weekly, etc.). By default, the cadence set is: - **Daily:** We default to Eastern Standard Time (New York) and 12:00 AM ET (New York). - **Weekly:** We default to starting the week on Monday at 12:00 AM ET (New York). - **Monthly:** We default to starting the calendar month on the 1st at 12:00 AM ET (New York). If you would like a different start time, please email your Finix point of contact or [Finix Support](mailto:support@finix.com). --- # Me to Me Payouts Source: https://docs.finix.com/guides/payouts/me-to-me-payouts Me to Me payouts allow you to move funds between a customer's own payment instruments — pulling from a card or bank account and pushing to a bank account, debit card or credit card. The flow consists of two `Transfer` operations: 1. A **pull Transfer** that pulls funds from the customer's source card (`PULL_FROM_CARD`) or bank account (`PULL_FROM_ACH`, or `PULL_FROM_SAME_DAY_ACH`). 2. A **payout transfer** that pushes funds to the customer's destination card (`PUSH_TO_CARD`) or bank account (`PUSH_TO_ACH`, `PUSH_TO_SAME_DAY_ACH`), linked to the completed pull transfer via `pull_transfer_id`. Both transfers must use `funds_flow_type: ME_TO_ME` and be associated with the same `Identity`. The pull and payout transfer must be for the same amount. If you have any questions about Me to Me payouts, reach out to your Finix Point of Contact or [Finix Support](mailto:support@finix.com). ## Step 1: Create an Identity The first step is creating an [Identity `with Sender & Recipient roles`](/api/identities/createidentity) to represent the customer. The Identity resource helps manage payment instruments, payout history, and customer details. You can create either `PERSONAL` or `BUSINESS` Identities. ### Required data | Required | Optional | Invalid | | --- | --- | --- | | | | | | Field | `type: PERSONAL` | `type: BUSINESS` | | --- | --- | --- | | Identity Roles `identity_roles` | | | | Type `type` | | | | First Name `first_name` | | | | Last Name `last_name` | | | | Personal Address `personal_address` | | | | Business Name `business_name` | | | | Doing Business As `doing_business_as` | | | | Business Address `business_address` | | | | Business Phone `business_phone` | | | | Personal Email `email` | | | | Personal Phone `phone` | | | ### API request Personal Sender & Recipient (Personal) ```json Sender & Recipient (Personal) { "id": "ID6GEE71G68hL1aQA3qyDkDv", "created_at": "2026-09-25T20:05:13.82Z", "updated_at": "2026-09-25T20:05:13.82Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "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_fingerprint": null, "business_tax_id_provided": false, "business_type": null, "default_statement_descriptor": null, "discover_mid": null, "dob": null, "doing_business_as": null, "email": null, "first_name": "Michael", "has_accepted_credit_cards_previously": false, "incorporation_date": null, "last_name": "Johnson", "max_transaction_amount": 0, "mcc": null, "ownership_type": null, "personal_address": { "line1": "789 Oak Drive", "line2": null, "city": "Springfield", "region": "IL", "postal_code": "62704", "country": "USA" }, "phone": null, "principal_percentage_ownership": null, "short_business_name": null, "tax_authority": null, "tax_id_fingerprint": null, "tax_id_provided": false, "title": null, "url": null }, "identity_roles": [ // [!code highlight] "RECIPIENT", "SENDER" ], "tags": {}, "type": "PERSONAL", // [!code highlight] "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/ID6GEE71G68hL1aQA3qyDkDv" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/ID6GEE71G68hL1aQA3qyDkDv/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/ID6GEE71G68hL1aQA3qyDkDv/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/ID6GEE71G68hL1aQA3qyDkDv/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/ID6GEE71G68hL1aQA3qyDkDv/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/ID6GEE71G68hL1aQA3qyDkDv/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/ID6GEE71G68hL1aQA3qyDkDv/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/ID6GEE71G68hL1aQA3qyDkDv/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/ID6GEE71G68hL1aQA3qyDkDv/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ``` Business Sender & Recipient (Business) ```json Sender & Recipient (Business) { "id": "IDsNLvbDXJmsBoZ1X5VtbA48", "created_at": "2026-09-25T20:05:13.35Z", "updated_at": "2026-09-25T20:05:13.35Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "entity": { "ach_max_transaction_amount": 0, "amex_mid": null, "annual_card_volume": 0, "business_address": { "line1": "7890 Oak Drive", "line2": "Suite 101", "city": "Smalltown", "region": "TX", "postal_code": "75432", "country": "USA" }, "business_name": "Blue Horizon Technologies", "business_phone": null, "business_tax_id_fingerprint": null, "business_tax_id_provided": false, "business_type": null, "default_statement_descriptor": null, "discover_mid": null, "dob": null, "doing_business_as": "B.H. Technologies", "email": null, "first_name": "John", "has_accepted_credit_cards_previously": false, "incorporation_date": null, "last_name": "Jeremy", "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": null, "principal_percentage_ownership": null, "short_business_name": null, "tax_authority": null, "tax_id_fingerprint": null, "tax_id_provided": false, "title": null, "url": null }, "identity_roles": [ // [!code highlight] "RECIPIENT", "SENDER" ], "tags": {}, "type": "BUSINESS", // [!code highlight] "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDsNLvbDXJmsBoZ1X5VtbA48" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDsNLvbDXJmsBoZ1X5VtbA48/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDsNLvbDXJmsBoZ1X5VtbA48/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDsNLvbDXJmsBoZ1X5VtbA48/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDsNLvbDXJmsBoZ1X5VtbA48/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDsNLvbDXJmsBoZ1X5VtbA48/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDsNLvbDXJmsBoZ1X5VtbA48/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDsNLvbDXJmsBoZ1X5VtbA48/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDsNLvbDXJmsBoZ1X5VtbA48/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ``` ## Step 2: Add a source Payment Instrument PCI Level 1 Compliance Creating `Payment Instruments` and passing payment details (account number, card number, etc.) directly via the API should only be done for testing purposes and by PCI Level 1 compliant entities. If you aren't a Level 1 PCI-compliant entity, you must use our [Tokenization Forms](/guides/online-payments/payment-tokenization/tokenization-forms) or [Mobile Tokenization](/guides/online-payments/payment-tokenization) to accept payment details and comply with PCI regulations. If you have any questions, please don't hesitate to reach out to your Finix point of contact or email the [Finix Support team](/guides/getting-started/support-at-finix/). Add a `Payment Instrument` for the source instrument that funds will be pulled from. This can be a card or a bank account. Card Payment Instrument - Card ```json Payment Instrument - Card { "id": "PImZV8WukUEgB8iFqoSouLt1", "created_at": "2026-09-25T20:05:27.37Z", "updated_at": "2026-09-25T20:05:27.37Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "PAYMENT_CARD", // [!code highlight] "account_updater_enabled": false, "address": { "line1": "900 Metro Center Blv", "line2": null, "city": "San Francisco", "region": "CA", "postal_code": "94404", "country": "USA" }, "address_verification": "UNKNOWN", "bin": "520082", "brand": "MASTERCARD", "card_type": "DEBIT", "expiration_month": 12, "expiration_year": 2029, "issuer_country": "NON_USA", "last_four": "8210", "name": "John Doe", "network_token_enabled": false, "network_token_state": "NOT_ENABLED", "security_code_verification": "UNKNOWN", "tags": {}, "third_party": null, "third_party_token": null, "type": "PAYMENT_CARD", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" }, "updates": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/updates" } } } ``` Bank Account Payment Instrument - Bank Account ```json Payment Instrument - Bank Account { "id": "PI68E8eKh1v4P2eY2PoLrzzT", "created_at": "2026-09-25T20:05:25.37Z", "updated_at": "2026-09-25T20:05:25.37Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRxpMNPZbZqVQfcHzRUJnzkR", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "BANK_ACCOUNT", // [!code highlight] "microdeposit": "microdeposit_g92m9YHXhhndZcmFAUW7Ki", "microdeposit_verification_url": "https://link.sandbox-payment-form.com/DKDrmq", "account_type": "BUSINESS_CHECKING", "bank_account_validation_check": "NOT_ATTEMPTED", "bank_code": "122105278", "country": "USA", "institution_number": null, "masked_account_number": "XXXXXX0019", "name": "Smith & Associates Consulting", "transit_number": null, "tags": {}, "third_party": null, "third_party_token": null, "type": "BANK_ACCOUNT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI68E8eKh1v4P2eY2PoLrzzT/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" } } } ``` ## Step 3: (Optional) verify the source Payment Instrument If the source is a card, verify its eligibility for pull-from-card before proceeding. The resulting `Verification` resource provides card details including card type and issuer information. Example API Definition Example Card is eligible for push-to-card ```json Card is eligible for push-to-card { "id": "VIbv4zMJ9i6VE1TnfA76g4bi", "created_at": "2026-09-25T20:05:28.48Z", "updated_at": "2026-09-25T20:05:28.54Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "identity": null, "merchant": null, "merchant_identity": null, "messages": [], "outcome_summary": null, "outcomes": null, "payment_instrument": "PIhWqjo3DU13WmFzWZFLngfa", "payment_instrument_verification_details": { // [!code highlight] "billing_currency": null, "card_type": null, "issuer_country": "UNKNOWN", "name_verification_results": { "first_name_verification": "UNKNOWN", "last_name_verification": "UNKNOWN", "middle_name_verification": "UNKNOWN", "name_verification": "UNKNOWN" }, "pull_from_card_cross_border": null, "pull_from_card_domestic": null, "push_to_card_cross_border": null, "push_to_card_domestic": null }, "processor": "DUMMY_V1", "raw": "RawDummyInstrumentVerificationResult", "reverification_reason": { "review_type": null, "initiated_by": null, "reason_description": null }, "state": "SUCCEEDED", "sub_type": null, "tags": {}, "trace_id": "e95f0e68-dab6-4b19-b8a3-3d53cdb250d2", "type": "PAYMENT_INSTRUMENT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/verifications/VIbv4zMJ9i6VE1TnfA76g4bi" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "payment_instrument": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIhWqjo3DU13WmFzWZFLngfa" } } } ``` API Definition ## Step 4: Add a destination Payment Instrument Add a `Payment Instrument` for the destination instrument that will receive the funds. Me to Me payouts are only available for bank accounts or Visa and Mastercard cards. Example API Definition Example Payment Instrument - Card ```json Payment Instrument - Card { "id": "PImZV8WukUEgB8iFqoSouLt1", "created_at": "2026-09-25T20:05:27.37Z", "updated_at": "2026-09-25T20:05:27.37Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY", "identity": "IDmj1yA97RS4rMjiQgvK3Vio", "instrument_type": "PAYMENT_CARD", // [!code highlight] "account_updater_enabled": false, "address": { "line1": "900 Metro Center Blv", "line2": null, "city": "San Francisco", "region": "CA", "postal_code": "94404", "country": "USA" }, "address_verification": "UNKNOWN", "bin": "520082", "brand": "MASTERCARD", "card_type": "DEBIT", "expiration_month": 12, "expiration_year": 2029, "issuer_country": "NON_USA", "last_four": "8210", "name": "John Doe", "network_token_enabled": false, "network_token_state": "NOT_ENABLED", "security_code_verification": "UNKNOWN", "tags": {}, "third_party": null, "third_party_token": null, "type": "PAYMENT_CARD", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDmj1yA97RS4rMjiQgvK3Vio" }, "updates": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImZV8WukUEgB8iFqoSouLt1/updates" } } } ``` API Definition ## Step 5: (Optional) verify the destination Payment Instrument If pushing to a card you can verify the destination card's eligibility for push-to-card before sending funds. Example API Definition Example Card is eligible for push-to-card ```json Card is eligible for push-to-card { "id": "VIbv4zMJ9i6VE1TnfA76g4bi", "created_at": "2026-09-25T20:05:28.48Z", "updated_at": "2026-09-25T20:05:28.54Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "identity": null, "merchant": null, "merchant_identity": null, "messages": [], "outcome_summary": null, "outcomes": null, "payment_instrument": "PIhWqjo3DU13WmFzWZFLngfa", "payment_instrument_verification_details": { // [!code highlight] "billing_currency": null, "card_type": null, "issuer_country": "UNKNOWN", "name_verification_results": { "first_name_verification": "UNKNOWN", "last_name_verification": "UNKNOWN", "middle_name_verification": "UNKNOWN", "name_verification": "UNKNOWN" }, "pull_from_card_cross_border": null, "pull_from_card_domestic": null, "push_to_card_cross_border": null, "push_to_card_domestic": null }, "processor": "DUMMY_V1", "raw": "RawDummyInstrumentVerificationResult", "reverification_reason": { "review_type": null, "initiated_by": null, "reason_description": null }, "state": "SUCCEEDED", "sub_type": null, "tags": {}, "trace_id": "e95f0e68-dab6-4b19-b8a3-3d53cdb250d2", "type": "PAYMENT_INSTRUMENT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/verifications/VIbv4zMJ9i6VE1TnfA76g4bi" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "payment_instrument": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIhWqjo3DU13WmFzWZFLngfa" } } } ``` API Definition ## Step 6: Verify and onboard the account Provision a recipient account by making a POST request to create a `Merchant` resource. This is the last step before you can begin sending Me to Me payouts. Once the merchant is `Approved` you can create a transfer to pull funds. For more information, see [Recipient Verifications](/guides/payouts/recipient-verification-process) Example API Definition Example Merchant ```json Merchant { "id": "MU3CTeJT1MMhwaGZabCo2xwK", "created_at": "2026-09-30T00:02:16.89Z", "updated_at": "2026-09-30T00:02:16.89Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "card_cvv_required": false, "card_expiration_date_required": true, "card_network_details": null, "convenience_charges_enabled": false, "country": "USA", "creating_transfer_from_report_enabled": false, "currencies": [ "USD" ], "default_partial_authorization_enabled": false, "disbursements_ach_pull_enabled": true, "disbursements_ach_push_enabled": true, "disbursements_card_pull_enabled": true, "disbursements_card_push_enabled": true, "disbursements_same_day_ach_pull_enabled": false, "disbursements_same_day_ach_push_enabled": false, "fee_ready_to_settle_upon": "PROCESSOR_WINDOW", "first_approved_at": null, "gateway": null, "gross_settlement_enabled": false, "identity": "IDfC3Z9xVrniLsE6Hk4Zqhjv", "instant_payouts_card_push_enabled": false, "is_terminated": false, "level_two_level_three_data_enabled": false, "loan_repayment": null, "mcc": "4900", "merchant_name": "Finix Flowers", "merchant_profile": "MPh7HkSopbp5wFnTgWNQujDx", "microdeposit_verification_required_buyer": true, "microdeposit_verification_required_sender": false, "mid": null, "onboarding_state": "PROVISIONING", "pending_refunds_strategy": "SAME_DAY_ADJUSTMENT", "processing_enabled": false, "processor": "DUMMY_V1", "processor_details": {}, "ready_to_settle_upon": "PROCESSOR_WINDOW", "ready_to_settle_upon_delay_alignment": "NONE", "refunds_disabled": false, "rent_surcharges_enabled": false, "settlement_enabled": false, "settlement_funding_identifier": "UNSET", "settlement_queue_mode": "UNSET", "surcharges_enabled": false, "tags": {}, "termination_details": null, "unreferenced_refund_card_present_enabled": true, "unreferenced_refund_manual_entry_enabled": false, "verification": "VIw6VyyzVBjdoabt98e4Nrj2", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/merchants/MU3CTeJT1MMhwaGZabCo2xwK" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDfC3Z9xVrniLsE6Hk4Zqhjv" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/merchants/MU3CTeJT1MMhwaGZabCo2xwK/verifications" }, "merchant_profile": { "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPh7HkSopbp5wFnTgWNQujDx" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "verification": { "href": "https://finix.sandbox-payments-api.com/verifications/VIw6VyyzVBjdoabt98e4Nrj2" } } } ``` API Definition ## Step 7: Create a Transfer to pull funds Create a `Transfer` to pull funds from the customer's source payment instrument. Set `funds_flow_type` to `ME_TO_ME` and include the `Payment Instrument` ID as `source`. The pull transfer must reach a `state` of `SUCCEEDED` before you can create the payout transfer. It is recommended to include an `idempotency_id` field in the payload. For more information, see [Idempotent Requests](/additional-resources/developers/authentication-and-api-basics/idempotent-request). Pull from Card Transfer - Me to Me Pull - Card ```json Transfer - Me to Me Pull - Card { "id": "TR3vKfwCuXmLqPsDYbGYn4NUm", "created_at": "2025-08-14T21:45:12.98Z", "updated_at": "2025-08-14T21:45:12.98Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 15000, "amount_requested": 15000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPmtT4MYmiAs1qjLjneQmk4d", "funds_flow_type": "ME_TO_ME", "idempotency_id": null, "merchant": "MUuNdhs7uVYcjocWugeBbpRo", "merchant_identity": "IDbPrApp2adDVqG4QQzoo58E", "messages": [], "network_details": {}, "operation_key": "PULL_FROM_CARD", "parent_transfer": null, "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": "PIveyqg2bVkKo6SHsstxBSDc", "split_transfers": [], "state": "SUCCEEDED", "statement_descriptor": null, "subtype": "API", "supplemental_fee": null, "tags": {}, "tip_amount": null, "trace_id": "84749ef6-2018-5105-b4gg-g684e8g4f458", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TR3vKfwCuXmLqPsDYbGYn4NUm" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDbPrApp2adDVqG4QQzoo58E" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TR3vKfwCuXmLqPsDYbGYn4NUm/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TR3vKfwCuXmLqPsDYbGYn4NUm/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TR3vKfwCuXmLqPsDYbGYn4NUm/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TR3vKfwCuXmLqPsDYbGYn4NUm/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIveyqg2bVkKo6SHsstxBSDc" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d" } } } ``` Pull from Bank (Next Day ACH) Transfer - Me to Me Pull - Bank ```json Transfer - Me to Me Pull - Bank { "id": "TR4mNhCuXkAqRsDYbJYnBCDe", "created_at": "2025-08-14T20:59:09.39Z", "updated_at": "2025-08-14T20:59:09.39Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 15000, "amount_requested": 15000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPmtT4MYmiAs1qjLjneQmk4d", "funds_flow_type": "ME_TO_ME", "idempotency_id": null, "merchant": "MU2bESfmfedhA2SjcymNvSAX", "merchant_identity": "IDA3M8ueFuXaJex7N6jcAR9", "messages": [], "network_details": {}, "operation_key": "PULL_FROM_ACH", "parent_transfer": null, "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": "PI95jTbyzcdjhWsgFEK6vqSU", "split_transfers": [], "state": "PENDING", "statement_descriptor": null, "subtype": "API", "supplemental_fee": null, "tags": {}, "tip_amount": null, "trace_id": "451d044c-410d-54ge-c3b5-ef7c8g4e3358", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TR4mNhCuXkAqRsDYbJYnBCDe" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDA3M8ueFuXaJex7N6jcAR9" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TR4mNhCuXkAqRsDYbJYnBCDe/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TR4mNhCuXkAqRsDYbJYnBCDe/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TR4mNhCuXkAqRsDYbJYnBCDe/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TR4mNhCuXkAqRsDYbJYnBCDe/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI95jTbyzcdjhWsgFEK6vqSU" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d" } } } ``` Pull from Bank (Same Day ACH) Transfer - Me to Me Pull - Bank - Same Day ```json Transfer - Me to Me Pull - Bank - Same Day { "id": "TR5sDhCuXkAqRsEYbJYnSDFg", "created_at": "2025-08-15T13:37:30.38Z", "updated_at": "2025-08-15T13:37:30.38Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 15000, "amount_requested": 15000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPmtT4MYmiAs1qjLjneQmk4d", "funds_flow_type": "ME_TO_ME", "idempotency_id": null, "merchant": "MU2bESfmfedhA2SjcymNvSAX", "merchant_identity": "IDA3M8ueFuXaJex7N6jcAR9", "messages": [], "network_details": null, "operation_key": "PULL_FROM_SAME_DAY_ACH", "parent_transfer": null, "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": "PI95jTbyzcdjhWsgFEK6vqSU", "split_transfers": [], "state": "PENDING", "statement_descriptor": null, "subtype": "API", "supplemental_fee": null, "tags": {}, "tip_amount": null, "trace_id": "e8g0515f-49fb-5d99-9012-919ge3dg8bbe", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TR5sDhCuXkAqRsEYbJYnSDFg" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDA3M8ueFuXaJex7N6jcAR9" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TR5sDhCuXkAqRsEYbJYnSDFg/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TR5sDhCuXkAqRsEYbJYnSDFg/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TR5sDhCuXkAqRsEYbJYnSDFg/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TR5sDhCuXkAqRsEYbJYnSDFg/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI95jTbyzcdjhWsgFEK6vqSU" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d" } } } ``` ## Step 8: Create a Payout Transfer Once the pull transfer has `SUCCEEDED`, create the payout `Transfer` to push funds to the customer's destination instrument. To create the payout `Transfer`: - Include the `Payment Instrument` ID as `destination`. - Set `funds_flow_type` to `ME_TO_ME`. - In `amount`, set the funds to send in cents. - Set `pull_transfer_id` to the ID of the completed transfer used to pull funds from Step 6. The linked `Transfer` must: - Have an `operation_key` of `PULL_FROM_CARD`, `PULL_FROM_ACH`, or `PULL_FROM_SAME_DAY_ACH` - Have a `state` of `SUCCEEDED` - Be associated with the same `Identity` tied to the `Payment Instrument` provided in `destination`. - Have the same amount being requested for the Payout transfer - It is recommended to include an `idempotency_id` field in the payload. For more information, see [Idempotent Requests](/additional-resources/developers/authentication-and-api-basics/idempotent-request). Payout to Card Transfer - Me to Me Payout - Card ```json Transfer - Me to Me Payout - Card { "id": "TRhJdBnKpQsRmXvWyLzGcFUm", "created_at": "2025-08-14T21:45:12.98Z", "updated_at": "2025-08-14T21:45:12.98Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 15000, "amount_requested": 15000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "destination": "PIveyqg2bVkKo6SHsstxBSDc", "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPmtT4MYmiAs1qjLjneQmk4d", "funds_flow_type": "ME_TO_ME", "idempotency_id": null, "merchant": "MUuNdhs7uVYcjocWugeBbpRo", "merchant_identity": "IDbPrApp2adDVqG4QQzoo58E", "messages": [], "network_details": {}, "operation_key": "PUSH_TO_CARD", "parent_transfer": null, "parent_transfer_trace_id": null, "pull_transfer_id": "TR3vKfwCuXmLqPsDYbGYn4NUm", "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": null, "split_transfers": [], "state": "SUCCEEDED", "statement_descriptor": null, "subtype": "API", "supplemental_fee": null, "tags": {}, "tip_amount": null, "trace_id": "91850fg7-3129-6216-c5hh-h795f9h5g569", "type": "CREDIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhJdBnKpQsRmXvWyLzGcFUm" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDbPrApp2adDVqG4QQzoo58E" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhJdBnKpQsRmXvWyLzGcFUm/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhJdBnKpQsRmXvWyLzGcFUm/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRhJdBnKpQsRmXvWyLzGcFUm" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRhJdBnKpQsRmXvWyLzGcFUm/disputes" }, "destination": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIveyqg2bVkKo6SHsstxBSDc" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d" } } } ``` Payout to Bank (Next Day ACH) Transfer - Me to Me Payout - Bank ```json Transfer - Me to Me Payout - Bank { "id": "TRkPvQmNxBsHdWyCjLzGaFRp", "created_at": "2025-08-14T20:59:09.39Z", "updated_at": "2025-08-14T20:59:09.39Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 15000, "amount_requested": 15000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "destination": "PI95jTbyzcdjhWsgFEK6vqSU", "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPmtT4MYmiAs1qjLjneQmk4d", "funds_flow_type": "ME_TO_ME", "idempotency_id": null, "merchant": "MU2bESfmfedhA2SjcymNvSAX", "merchant_identity": "IDA3M8ueFuXaJex7N6jcAR9", "messages": [], "network_details": {}, "operation_key": "PUSH_TO_ACH", "parent_transfer": null, "parent_transfer_trace_id": null, "pull_transfer_id": "TR4mNhCuXkAqRsDYbJYnBCDe", "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": null, "split_transfers": [], "state": "PENDING", "statement_descriptor": null, "subtype": "API", "supplemental_fee": null, "tags": {}, "tip_amount": null, "trace_id": "562e155d-521e-65hf-d4c6-fg8d9h5f4469", "type": "CREDIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRkPvQmNxBsHdWyCjLzGaFRp" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDA3M8ueFuXaJex7N6jcAR9" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRkPvQmNxBsHdWyCjLzGaFRp/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRkPvQmNxBsHdWyCjLzGaFRp/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRkPvQmNxBsHdWyCjLzGaFRp" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRkPvQmNxBsHdWyCjLzGaFRp/disputes" }, "destination": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI95jTbyzcdjhWsgFEK6vqSU" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d" } } } ``` Payout to Bank (Same Day ACH) Transfer - Me to Me Payout - Bank - Same Day ```json Transfer - Me to Me Payout - Bank - Same Day { "id": "TRnRtQmNxBsHdWyCjLzGaFSd", "created_at": "2025-08-15T13:37:30.38Z", "updated_at": "2025-08-15T13:37:30.38Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 15000, "amount_requested": 15000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "destination": "PI95jTbyzcdjhWsgFEK6vqSU", "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPmtT4MYmiAs1qjLjneQmk4d", "funds_flow_type": "ME_TO_ME", "idempotency_id": null, "merchant": "MU2bESfmfedhA2SjcymNvSAX", "merchant_identity": "IDA3M8ueFuXaJex7N6jcAR9", "messages": [], "network_details": null, "operation_key": "PUSH_TO_SAME_DAY_ACH", "parent_transfer": null, "parent_transfer_trace_id": null, "pull_transfer_id": "TR5sDhCuXkAqRsEYbJYnSDFg", "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": null, "split_transfers": [], "state": "PENDING", "statement_descriptor": null, "subtype": "API", "supplemental_fee": null, "tags": {}, "tip_amount": null, "trace_id": "f9h1626g-60gc-6e00-0123-020hf4eh9ccf", "type": "CREDIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRnRtQmNxBsHdWyCjLzGaFSd" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDA3M8ueFuXaJex7N6jcAR9" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRnRtQmNxBsHdWyCjLzGaFSd/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRnRtQmNxBsHdWyCjLzGaFSd/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRnRtQmNxBsHdWyCjLzGaFSd" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRnRtQmNxBsHdWyCjLzGaFSd/disputes" }, "destination": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI95jTbyzcdjhWsgFEK6vqSU" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d" } } } ``` --- # Payout Links Source: https://docs.finix.com/guides/payouts/payout-links Payout Links are one-time use links to send a payout to a recipient. You can email or text the link to your recipient. If conducting a card payout, funds are usually available in minutes. You can use payout links to send insurance payouts, sales commissions, and more. You can customize the payout link with your brand name and logo. In this guide, you will learn how to create payout links on the Finix Dashboard and via API ## Recipient experience When a recipient clicks on the link, they'll see where they can enter their card or bank information to receive their payout. This experience can be white-labeled to have your brand colors and logo. Payout Link Recipient Experience - **Personal Recipients:** For personal recipients, `first_name`, `last_name`, and `personal_address` are required along with the payment instrument. - **Business Recipient:** For business recipients, `business_name`,`doing_business_as`, and `business_address` are required. We also require a control owner with `first_name`, `last_name`, and `personal_address`. Once they enter their information, Finix will review and conduct standard underwriting checks. If the recipients are approved, a card or bank payout will be sent. Recipients can re-visit the link to check the status of their payout. If the payout fails, they'll be asked to re-enter their information. If the recipient is under Manual Review, we may need additional documentation to clear the recipient. Please see our [verification process guide](/guides/payouts/recipient-verification-process) for more details. ## Create a Payout Link using the Finix Dashboard You can create a payout link in the Finix Dashboard without any development work. Using the Finix Dashboard, you can: - Create and send payout links to recipients to receive funds - Track the status of payout links. ### Step 1: Create a Payout Link To create a payout link in the Finix Dashboard: 1. Log into the Finix Dashboard. 2. Click Payout Links on the left navigation bar. 3. Click Create Payout Link 4. Fill out the form with the requested details. Be sure to include a link to your Terms of Service. Payout Link Creation Form Payout Link Confirmation Screen ### Step 2: Send Payout Link to Recipient On the **Payout Link Details** page, you can copy the payout link URL to send to buyers. When the recipient clicks on the link, they will be redirected to Finix's payout form to complete their payout. ```url Example Payout Link URL https://link.sandbox-payments-checkout.com/Mx4yvg ``` ### Step 3: Track your Payout Link After you create a payout link, you can track the payout link status on the Finix Dashboard. You can review the information again on the Finix Dashboard. On the detail page, you can copy the URL again or deactivate a payout link. Payout Link Detail Page If you click on **Payout Attempts**, you can view `payout attempts` in a `PENDING`, `SUCCEEDED`, or `FAILED` state. A `payout attempt` that is `PENDING` is actively being underwritten. ## Successful Payouts When a recipient successfully receives their payout, the `status` of the payout link updates to `COMPLETED`. --- # Recipient Verification Process Source: https://docs.finix.com/guides/payouts/recipient-verification-process Learn how to onboard Recipients to receive payouts. When you onboard a Recipient, Finix runs global sanctions checks to comply with regulatory requirements for bank and card payouts. Use Finix's APIs, webhooks, or dashboard to listen and respond to updates during the onboarding process. Recipient Onboarding Process ## Onboarding States When you first create your Recipient's Merchant account, their information will be sent to Finix's underwriting systems. Their Merchant account will start in the `PROVISIONING` state, and transition to either `APPROVED` or `REJECTED` after underwriting. Typically, this happens within seconds of the Merchant account. | State | Description | | --- | --- | | `PROVISIONING` | The request is pending and being processed by Finix's system. | | `APPROVED` | The Merchant was successfully onboarded. The Recipient is ready to receive payouts. | | `REJECTED` | The Merchant was rejected and you need to [handle the rejection](#rejected-recipients). | When these events happen, you'll receive `Merchant Created` and `Merchant Updated` [webhook events](#onboarding-states). Use the webhook's `onboarding_state` to understand the results and determine next steps. ### Approved Recipients When your `Merchant` is `APPROVED`, you will receive a `Merchant Underwritten` webhook. An approved `Merchant` means your seller is ready to receive [bank payouts](/guides/payouts/bank-payouts/) and [card payouts](/guides/payouts/card-payouts). ```json { "id": "MUoBGzwPdFxb397BKM3bHUvf", "created_at": "2021-11-14T19:20:29.15Z", "updated_at": "2021-11-14T19:20:29.48Z", "application": "APcVnXxyWotD6TGRWV2bRWuD", "card_cvv_required": false, "card_expiration_date_required": true, "creating_transfer_from_report_enabled": false, "fee_ready_to_settle_upon": "RECONCILIATION", "gross_settlement_enabled": false, "identity": "IDgXNAaoy5d4TLkp5ze6gScA", "level_two_level_three_data_enabled": false, "mcc": "4900", "merchant_name": "Finix Flowers", "merchant_profile": "MP9e916zYUTTqHUDe4F9ZQvp", "mid": "FNXqtgiZAvNPz44hT67Ai632W", "onboarding_state": "APPROVED", "processing_enabled": true, "processor": "DUMMY_V1", "ready_to_settle_upon": null, "settlement_enabled": true, "settlement_funding_identifier": "UNSET", "surcharges_enabled": false, "verification": "VItYKnaucfcaRNdb48y1kr3F" } ``` ### Rejected Recipients Should your `Merchant` get `REJECTED`, you will receive a `Merchant Updated` webhook with `onboarding_state: REJECTED`. Rejections happen in rare cases when Finix isn't able to approve your Merchant as-is. Typically, this means that your Merchant has invalid data (for example, an incorrect address), or is missing data. ```json { "id": "MUoBGzwPdFxb397BKM3bHUvf", "created_at": "2021-11-14T19:20:29.15Z", "updated_at": "2021-11-14T19:20:29.48Z", "application": "APcVnXxyWotD6TGRWV2bRWuD", "card_cvv_required": false, "card_expiration_date_required": true, "creating_transfer_from_report_enabled": false, "fee_ready_to_settle_upon": "RECONCILIATION", "gross_settlement_enabled": false, "identity": "IDgXNAaoy5d4TLkp5ze6gScA", "level_two_level_three_data_enabled": false, "mcc": "4900", "merchant_name": "Finix Flowers", "merchant_profile": "MP9e916zYUTTqHUDe4F9ZQvp", "mid": "FNXqtgiZAvNPz44hT67Ai632W", "onboarding_state": "REJECTED", "processing_enabled": true, "processor": "DUMMY_V1", "ready_to_settle_upon": null, "settlement_enabled": true, "settlement_funding_identifier": "UNSET", "surcharges_enabled": false, "verification": "VItYKnaucfcaRNdb48y1kr3F" } ``` To learn why Finix rejected your Merchant, and how you can resolve the issue, use the Merchant's `verification` ID to fetch the [`Verification`](/api/verifications/getverification). ```shell curl https://finix.sandbox-payments-api.com/verifications/VItYKnaucfcaRNdb48y1kr3F \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u "USxxxxx:xyz-123" ``` The Verification's `messages` and `raw` fields will have codes explaining the rejection: ```json { "id": "VItYKnaucfcaRNdb48y1kr3F", "created_at": "2024-09-13T19:25:31.60Z", "updated_at": "2024-09-13T19:25:31.68Z", "application": "APrMqXwT4CE9sRjtGaHcYJN7", "identity": null, "merchant": "MU9KBbc3MWNwcDgF78PAh92b", "merchant_identity": "ID5kBwNdEVcdaFcksHSEVfJu", "messages": ["INVALID_OWNER_DATA"], "outcome_summary": null, "outcomes": null, "payment_instrument": null, "payment_instrument_verification_details": { "push_to_card_domestic": null, "push_to_card_cross_border": null, "card_type": null, "billing_currency": null, "issuer_country": null, "name_verification_results": { "first_name_verification": "UNKNOWN", "last_name_verification": "UNKNOWN", "middle_name_verification": "UNKNOWN", "name_verification": "UNKNOWN" } }, "processor": "LITLE_V1", "raw": [ { "outcome_code": "INVALID_OWNER_DATA", "description": "Business Tax ID Number could not be verified.", "remediation_item": "Ensure a valid EIN or Tax ID is supplied by updating Identity and submitting a new Merchant Verification." } ], "state": "FAILED", "tags": {}, "trace_id": "FNXjmWCgqrQ23hFDfRhEyC4Nr", "type": "MERCHANT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/verifications/VItYKnaucfcaRNdb48y1kr3F" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APrMqXwT4CE9sRjtGaHcYJN7" }, "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MU9KBbc3MWNwcDgF78PAh92b" } } } ``` #### Soft rejections In most cases, Finix will send "soft rejections" that do not block onboarding. When you receive these codes, you can re-submit your Merchant to Finix's underwriting system after resolving the issue. Typically, the most common soft rejection `outcome_code` is `INVALID_OWNER_DATA`, which happens when your Recipient has invalid or missing data. Most steps to resolve rejections involve updating the information of the recipient's `Identity`. After updating the `Identity`, create a new `Verification` to send the Merchant back to Finix's underwriting systems: Example Merchant Verification ```json Merchant Verification { "id": "VItpnRDSS7eMXEgbPFMKEmD3", "created_at": "2024-09-20T20:46:18.84Z", "updated_at": "2024-09-20T20:46:18.91Z", "application": "APgFebyumW1TVZK9sbZwAvbx", "identity": null, "merchant": "MU7F6JcADa47CT1cwoZAgLFM", "merchant_identity": "IDfqVY8AcjQCSdyZSFL4thMn", "messages": [], "outcome_summary": null, "outcomes": null, "payment_instrument": null, "payment_instrument_verification_details": { "push_to_card_domestic": null, "push_to_card_cross_border": null, "card_type": null, "billing_currency": null, "issuer_country": null }, "processor": "LITLE_V1", "raw": null, "state": "PENDING", "tags": {}, "trace_id": "FNXmjmpf1PXHa52KDwFVEEPDy", "type": "MERCHANT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/verifications/VItpnRDSS7eMXEgbPFMKEmD3" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgFebyumW1TVZK9sbZwAvbx" }, "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MU7F6JcADa47CT1cwoZAgLFM" } } } ``` API Definition This will place your Merchant back in the `onboarding_state: PROVISIONING`, at which point they will go through the underwriting process again. Merchant - Provisioning ```json Merchant - Provisioning { "id": "MU9hcmnx5cWZUmRFKRqHnKc8", "created_at": "2026-09-30T00:02:18.62Z", "updated_at": "2026-09-30T00:02:18.62Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "card_cvv_required": false, "card_expiration_date_required": true, "card_network_details": null, "convenience_charges_enabled": false, "country": "USA", "creating_transfer_from_report_enabled": false, "currencies": [ "USD" ], "default_partial_authorization_enabled": false, "disbursements_ach_pull_enabled": true, "disbursements_ach_push_enabled": true, "disbursements_card_pull_enabled": true, "disbursements_card_push_enabled": true, "disbursements_same_day_ach_pull_enabled": false, "disbursements_same_day_ach_push_enabled": false, "fee_ready_to_settle_upon": "PROCESSOR_WINDOW", "first_approved_at": null, "gateway": null, "gross_settlement_enabled": false, "identity": "IDxmXmkWTmyipx5DdwbYFWP2", "instant_payouts_card_push_enabled": false, "is_terminated": false, "level_two_level_three_data_enabled": false, "loan_repayment": null, "mcc": "4900", "merchant_name": "Finix Flowers", "merchant_profile": "MPtAYYmX7of1MYkqKH9GBYAm", "microdeposit_verification_required_buyer": true, "microdeposit_verification_required_sender": false, "mid": null, "onboarding_state": "PROVISIONING", "pending_refunds_strategy": "SAME_DAY_ADJUSTMENT", "processing_enabled": false, "processor": "DUMMY_V1", "processor_details": {}, "ready_to_settle_upon": "PROCESSOR_WINDOW", "ready_to_settle_upon_delay_alignment": "NONE", "refunds_disabled": false, "rent_surcharges_enabled": false, "settlement_enabled": false, "settlement_funding_identifier": "UNSET", "settlement_queue_mode": "UNSET", "surcharges_enabled": false, "tags": { "order_id": "ORD-123" }, "termination_details": null, "unreferenced_refund_card_present_enabled": true, "unreferenced_refund_manual_entry_enabled": false, "verification": "VIpfHm3CLqD77hCUqCKeiF", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/merchants/MU9hcmnx5cWZUmRFKRqHnKc8" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDxmXmkWTmyipx5DdwbYFWP2" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/merchants/MU9hcmnx5cWZUmRFKRqHnKc8/verifications" }, "merchant_profile": { "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPtAYYmX7of1MYkqKH9GBYAm" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "verification": { "href": "https://finix.sandbox-payments-api.com/verifications/VIpfHm3CLqD77hCUqCKeiF" } } } ``` #### Hard rejections In some cases, Finix will assign hard rejection codes when we cannot board your Merchant. If you have any questions, please reach out to your Finix point of contact or the [Finix Support team](mailto:support@finix.com). --- # Signing Up for Payouts Source: https://docs.finix.com/guides/payouts/signing-up Learn how to get started with Payouts. ## Step 1: Contact Finix Reach out to your Finix point-of-contact or the [Finix Sales](https://finix.com/contact-us) team with: - A link to your website. - A brief explanation of how you plan to use Payouts. - The countries you plan to use Payouts in. ## Step 2: Login to your Payouts Sandbox Finix will work with you to set up your Payouts Sandbox. A Payouts Sandbox includes: - A Payouts Dashboard - API Credentials ## Step 3: Build your Payouts integration Build out your integration and begin testing Payouts. See [Card Payouts](/guides/payouts/card-payouts) for details on how to process a Card Payout. ## Step 4: Apply for a Live account When you're ready to apply for a live environment, reach out to your Finix point-of-contact or the [Finix Support](mailto:support@finix.com) team. Before we can grant access to a live environment, Finix must evaluate your business and integration. Access to a live environment enables you to process live payouts and initiate real money movements. ## Step 5: Approval Finix will evaluate your integration and, if approved, set up your live environment. ## Next steps Once you have access to your live environment, you can proceed with sending payouts to cards or bank accounts. Managing Payouts Learn how to manage your payout activity using the Payouts Dashboard. Card Payouts Learn how to send money to recipients' credit or debit cards. Bank Payouts Learn how to send money to recipients' bank accounts. --- # Low-Code / No-Code Source: https://docs.finix.com/low-code-no-code Customers that want to get started accepting payments right away can use Finix's suite of No-Code / Low-Code solutions. Use our Checkout Pages, Payment Links, Invoices, and Virtual Terminal to start processing payments on day one. ## Learn more Payment Links Create and send Payment Links to help buyers easily complete transactions. Invoices Create and send itemized invoices with support for partial payments. Virtual Terminal Learn how to create and process payments with Finix's Virtual Terminal. Subscriptions Create subscriptions in the Finix Dashboard without any development work. --- # Accepting Partial Payments Source: https://docs.finix.com/low-code-no-code/invoices/accepting-partial-payments During [invoice creation](/low-code-no-code/invoices/invoices-quickstart), you can allow buyers to pay in full or in partial payments. When creating the invoice, under the **Payment Options** section, select the **Partial Payments** checkbox. Payment Options - Partial Payments ## What the Buyer sees When a buyer clicks the invoice link, the payment page will display with the ability to add a payment amount that is less than or equal to the invoice total. After entering the amount, the remaining balance on the invoice will be shown. Invoice Payment Page - Partial Payment --- # Bank Payments with Invoices Source: https://docs.finix.com/low-code-no-code/invoices/bank-payments-with-invoices Finix Invoices support bank account payments, including ACH (US) and EFT (Canada). To accept bank payments on an invoice, select **Bank account** under **Allowed Payment Methods** when [creating the invoice](/low-code-no-code/invoices/invoices-quickstart). You can combine the bank account payment method with other payment methods like card, Apple Pay, and Google Pay to give buyers multiple options. ## How bank payments differ from card payments Unlike card payments, which are applied to an invoice immediately after a successful submission, bank transfers are not final at the time of submission. A bank payment can appear successful but later be returned by the bank. This affects how invoice state and totals are tracked. When a buyer pays an invoice with a bank account: 1. The payment amount is added to `total_amount_processing` on the invoice. 2. Finix groups the payment into a [Settlement](/guides/platform-payments/seller-payouts/accruing-settlements). When that Settlement is approved, the amount moves from `total_amount_processing` to `total_amount_paid` and the invoice updates to **Paid** (or **Partially Paid**). 3. If the bank returns the transfer, the amount is removed from `total_amount_processing` if it is still processing, or from `total_amount_paid` if it was already applied. The invoice is then recalculated as **Open** or **Partially Paid**. Paid is not always final with bank payments When an invoice includes a bank account payment, **Paid** is not a terminal state. A return can revert a **Paid** invoice back to **Open** or **Partially Paid**. Returns typically arrive within 1-7 days but can occur months later. ## When bank payments are applied A bank payment is applied to an invoice when the Settlement containing the payment is approved. Finix groups transactions into Settlements on a daily or configured schedule. Once a Settlement is finalized and [approved](/guides/platform-payments/seller-payouts/approving-settlements), the bank payment amount moves from `total_amount_processing` to `total_amount_paid`. If no settlement event is received within 7 days of the payment. For example, if the merchant is on a monthly settlement plan, Finix automatically applies the payment to the invoice. When a bank payment is applied, the following statuses are updated: | Resource | Status | Description | | --- | --- | --- | | Transfer | `SUCCEEDED` | The bank transfer has been submitted successfully. | | Transfer Attempt | `SUCCEEDED` | The Transfer Attempt on the invoice is created with a status of `SUCCEEDED`. The payment amount is reflected in `total_amount_processing` until the Settlement is approved, at which point it moves to `total_amount_paid`. | | Invoice | `PAID` or `PARTIALLY_PAID` | If the full invoice amount has been collected, the invoice moves to **Paid**. If the settled amount only covers part of the balance, the invoice moves to **Partially Paid**. | ## Returns If the bank returns a transfer, Finix removes the returned amount from `total_amount_processing` if it is still processing. If it was already applied, Finix removes it from `total_amount_paid` and adds it back to `total_amount_payable`. The invoice state is recalculated. Returns typically arrive within 1-7 days but can occur months later. When a return happens, the following statuses are updated: | Resource | Status | Description | | --- | --- | --- | | Transfer | `RETURNED` | The bank has returned the transfer. | | Transfer Attempt | `RETURNED` | The Transfer Attempt on the invoice is updated from `SUCCEEDED` to `RETURNED`. | | Invoice | `OPEN` or `PARTIALLY_PAID` | If no other settled payments remain, the invoice reverts to **Open**. If other settled payments still cover part of the balance, the invoice moves to **Partially Paid**. | Subscribe to invoice and transfer [webhooks](/additional-resources/developers/webhooks/integrating-into-webhooks) to be notified when a return occurs. ## Partial payments If [partial payments](/low-code-no-code/invoices/accepting-partial-payments) are enabled on the invoice, buyers can make multiple bank payments. The total of all in-flight bank payments cannot exceed `total_amount_payable`, which prevents overpayment while payments are processing. If a partial bank payment is returned after another payment has already settled, `total_amount_paid` is decremented by the returned amount. The invoice moves to **Partially Paid** if settled payments remain, or back to **Open** if no settled payments remain. ## Best practices - **Wait for the invoice to reach Paid before fulfilling orders.** Don't release goods or services based solely on a bank payment submission. Wait until the Settlement is approved and the invoice state reflects **Paid** or **Partially Paid**. - **Monitor for returns.** Subscribe to invoice and transfer webhooks to be notified when a bank payment is returned and the invoice state changes. - **Plan for late returns.** Returns typically arrive within 1-7 days but can occur months later. Build your workflows to handle invoice state reversals even after a payment appears settled. --- # Customize Invoice Branding Source: https://docs.finix.com/low-code-no-code/invoices/customize-branding During [invoice creation](/low-code-no-code/invoices/invoices-quickstart), you can personalize both the invoice and payment page. The invoice will only show your logo, while the payment page will display your logo and any other brand settings you choose. To customize the branding for your invoices, you can configure the following settings: - **Logo URL** - Provide a link to your company logo. - **Brand Color** - Customize the header background color. - **Accent Color** - Customize the payment button background color. - **Button Text Color** - Customize the payment button text color. - **Redirect URLs** - Specify where buyers are sent after successful payment, failed payment, or session expiration. Custom Branding ## What the Buyer sees ### Invoice The invoice contains your logo. Invoice PDF Logo ### Payment page The payment page displays your logo and custom branding. Invoice Payment Page - Branding --- # How Invoices Work Source: https://docs.finix.com/low-code-no-code/invoices/how-invoicing-works Invoices let you request payment from buyers for goods or services. Each invoice includes a unique invoice number, itemized details, a due date, and a hosted payment page where buyers can complete payment. You can create, send, and manage invoices directly from the Finix Dashboard. ## Invoices vs. Payment Links Both Invoices and Payment Links are low-code/no-code solutions for accepting payments. However, there are some key differences between the two: - **Invoices** are tied to a specific buyer and include a unique invoice number, itemized details, and a due date. They are formal documents suitable for business transactions and tax records. Invoices can be paid in full or in partial payments. - [Payment Links](/low-code-no-code/payment-links) are accessible to anyone with the link and do not support partial payments. ## Invoice lifecycle When you create an invoice, Finix generates: - A unique invoice number for tracking and reference. - A link that directs buyers to a hosted payment page. - A PDF of the invoice that can be downloaded or sent to buyers. The typical invoice lifecycle follows these steps: 1. **Create**: You create an invoice on the Dashboard with buyer details, line items, and a due date. 2. **Send**: You send the invoice to the buyer via email or share the payment page link directly. 3. **Pay**: The buyer clicks the link and completes the payment on the hosted payment page. 4. **Complete**: The invoice is marked as **Paid** and a receipt can be sent to the buyer. ## Invoice States Invoices transition through different states based on payment activity. You can view and filter invoices by state on the Dashboard. | State | Description | | --- | --- | | **Open** | The invoice has been created and is awaiting payment. No payments have been received yet. | | **Partially Paid** | A payment has been made, but the full amount has not been collected. Only available when partial payments are enabled. | | **Paid** | The invoice has been paid in full. No further action is required. | | **Void** | The invoice has been canceled and is no longer payable. Use this when an invoice was created in error or is no longer needed. | | **Uncollectible** | The invoice is unlikely to be paid (e.g., past due and unrecoverable). | ### Open An invoice starts in the **Open** state after it's created. The buyer can access the payment page and pay the invoice at any time before the due date. If the due date passes without payment, the invoice is marked as past due but remains in the **Open** state. ### Partially paid When [partial payments are enabled](/low-code-no-code/invoices/accepting-partial-payments), buyers can pay a portion of the invoice amount. The invoice moves to **Partially Paid** and displays the remaining balance. The buyer can continue making payments until the invoice is fully paid. ### Paid An invoice moves to **Paid** when the full amount has been collected. This can happen in a single payment or through multiple partial payments. Once paid, the invoice is complete and no further payments are accepted. ### Void You can void an invoice that was created in error or is no longer needed. Voiding an invoice cancels it and prevents any future payments. Voided invoices remain visible on the Dashboard for record-keeping but are clearly marked as canceled. To mark an invoice as void: 1. From the Finix Dashboard, click **Payment Tools** → **Invoices**. 2. Click the invoice you want to mark as uncollectible. 3. Click the **...** icon and select **Void**. - A banner appears at the top of the invoice page confirming the action. Voided Invoice Voiding Invoices You cannot void an invoice that has already received a payment. If partial payments have been made, you'll need to process refunds separately. ### Uncollectible Mark an invoice as **Uncollectible** when you've determined it won't be paid. This is typically used for invoices that are well past due and all collection attempts have failed. Marking an invoice as uncollectible is a bookkeeping action that helps you track invoices that are unlikely to be paid. To mark an invoice as uncollectible, 1. From the Finix Dashboard, click **Payment Tools** → **Invoices**. 2. Click the invoice you want to mark as uncollectible. 3. Click the **...** icon and select **Uncollectible**. - A banner appears at the top of the invoice page confirming the action. Uncollectible Invoice ## State transitions ### Payment flow Invoices move through these states as payments are received. ```mermaid stateDiagram-v2 direction TB [*] --> Open: Create Invoice Open --> PartiallyPaid Open --> Paid PartiallyPaid --> Paid Paid --> Open: Bank payment returned Paid --> PartiallyPaid: Bank payment returned (partial) ``` ### Cancellation flow with no partial Payments You can [void](#void) or [mark an invoice as uncollectible](#uncollectible) to close it without full payment. ```mermaid stateDiagram-v2 direction TB [*] --> Open: Create Invoice %% Main flows from Open Open --> Void: Cancel Open --> Uncollectible %% End states Void --> [*] Uncollectible --> [*] ``` ### Cancellation flow with partial Payments If an invoice has received partial payments, you can still void it or mark it as uncollectible. Any payments already collected must be refunded separately. ```mermaid stateDiagram-v2 direction TB [*] --> Open Open : Create Invoice %% Main flows from Open Open --> PartiallyPaid %% From Partially Paid, two possible outcomes PartiallyPaid --> Void PartiallyPaid --> Uncollectible %% Refund separately as transition text before closing Void --> [*] : Refund Separately Uncollectible --> [*] : Refund Separately ``` ## Payment methods You can allow buyers to pay with credit/debit cards, Apple Pay, and Google Pay. For more information, see [Payment Methods for Invoices](/low-code-no-code/invoices/payment-methods-for-invoices). ## Due dates and expiration ### Due date The **due date** is when payment is expected from the buyer. You set the due date when creating an invoice. After the due date passes: - The invoice remains **Open** and payable. - The invoice is flagged as **past due** on the Dashboard. - Buyers can still access the payment page and complete payment. ### Link expiration The payment page link has a separate expiration date from the due date. By default, payment page links expire 3 years after the invoice is created. After the link expires: - Buyers can no longer access the hosted payment page. - The invoice remains on the Dashboard but cannot be paid through the original link. ## Key Invoice settings When creating an invoice on the Dashboard, you can configure the following settings: | Setting | Description | | --- | --- | | **Invoice Number** | A unique identifier for the invoice. Finix auto-generates this, but you can customize it. | | **Due Date** | The date by which payment is expected from the buyer. | | **Buyer** | The identity associated with the invoice. Required for tracking and communication. | | **Line Items** | Individual items or services being billed, including descriptions, quantities, and amounts. | | **Partial Payments** | When enabled, buyers can pay a portion of the invoice amount. See [Accepting Partial Payments](/low-code-no-code/invoices/accepting-partial-payments). | | **Branding** | Customize the invoice and payment page with your logo and brand colors. See [Customize Branding](/low-code-no-code/invoices/customize-branding). | | **Receipt** | When enabled, a receipt is automatically sent to the buyer after payment. | ## Related guides - [Invoices Quickstart](/low-code-no-code/invoices/invoices-quickstart) - Create your first invoice. - [Accepting Partial Payments](/low-code-no-code/invoices/accepting-partial-payments) - Enable installment payments. - [Sharing Invoices](/low-code-no-code/invoices/sharing-invoices) - Share - [Customize Branding](/low-code-no-code/invoices/customize-branding) - Add your logo and brand colors. --- # Invoices Source: https://docs.finix.com/low-code-no-code/invoices Invoices Invoices are a way to request payment for goods or services provided. You can create invoices on the Finix Dashboard. ## Learn more Invoices Quickstart Learn how to get started with invoices. How Invoicing Works Learn how invoicing works. Sharing Invoices Learn how to share invoices. Accepting Partial Payments Learn how to accept partial payments on your invoices. Payment Methods for Invoices Learn about the payment methods available for invoices. Customize Branding Learn how to customize the branding for your invoices. --- # Invoices Quickstart Source: https://docs.finix.com/low-code-no-code/invoices/invoices-quickstart Learn how to quickly create invoices with the Finix Dashboard. ## Step 1: Create an Invoice ### Navigate to Invoices 1. In the Dashboard, expand **Payment Tools** in the left navigation. 2. Click **Invoices**. 3. Click **Create Invoice**. Create Invoice The creation form displays with a live preview that updates as you fill out each section. Invoice Creation Form #### Basic information Basic Invoice Information | Field | Description | | --- | --- | | **Invoice Name** | Internal label to identify the invoice in your records. Not visible to buyers. | | **Invoice Date** | The date the invoice was issued. Defaults to today but can be customized. | | **Due Date** | When payment is expected. Select a preset number of days or enter a custom date. | #### Buyer information | Field | Description | | --- | --- | | **Select or Create Buyer** | Choose an existing buyer from your records or add a new one. | | **Buyer Details** | Name, email, phone, and billing address. | | **Buyer Type** | Individual or business. | Click the Pencil icon to edit buyer information after selection. #### Delivery options | Option | Description | | --- | --- | | **Email Invoice** | Automatically send the invoice to the buyer's email address when created. | | **Additional Recipients** | Send to multiple email addresses (separate with enter, space, or tab). | | **Manual Delivery** | Skip automatic sending and [share the link manually](/low-code-no-code/invoices/sharing-invoices#sharing-an-invoice-after-its-created) later. | #### Line items Add one or more items you're invoicing for. Line Items | Field | Description | | --- | --- | | **Product/Service Name** | What you're charging for. | | **Unit Price** | Cost per unit. | | **Quantity** (optional) | Number of units. | | **Description** (optional) | Additional details about the item. | | **Per-Unit Discount** (optional) | Discount applied to this line item. | | **Item Code** (optional) | Internal reference code for your records. | Click **Add another item** to include additional line items. #### Transaction options Transaction Options | Field | Description | | --- | --- | | **Additional Discount** | Discount applied to the entire invoice total. | | **Shipping Amount** | Delivery costs. | | **Sales Tax** | Tax amount for the transaction. | | **Terms of Service URL** | Link to your terms displayed on the payment page. | #### Payment options | Option | Description | | --- | --- | | **Allowed Payment Methods** | Select which [payment methods](/low-code-no-code/invoices/payment-methods-for-invoices) buyers can use. | | **Partial Payments** | Allow buyers to pay in installments. See [Accepting Partial Payments](/low-code-no-code/invoices/accepting-partial-payments). | #### Additional Invoice details Additional Invoice Details | Field | Description | | --- | --- | | **Shipping Address** | Where physical goods should be delivered, if applicable. | | **Custom Fields** | Add fields like account number or project ID that appear on the invoice. | | **Footer/Memo** | Personal message, payment terms, or additional instructions at the bottom of the invoice. | #### Notification options | Option | Description | | --- | --- | | **Payment Confirmation Email** | Automatically send the buyer a receipt after each payment. | | **Copy Recipients** | Send receipt copies to yourself or additional recipients. | #### Custom branding Customize colors, logos, and styles. For details, see [Customize Branding](/low-code-no-code/invoices/customize-branding). ### Create the Invoice Click **Create and Send Invoice** to finalize. The invoice will be created and delivered according to your delivery options. Create and Send Invoice ### Invoice details page From the invoice details page, you can: - [Share the invoice](#step-2-share-the-invoice). - Edit the invoice. - Void the invoice. - Download the invoice as a PDF. To access additional options, click the **...** menu. Invoice Details Page Options Menu ## Step 2: Share the Invoice After creating your invoice, share it with buyers. Options include: - **Automatic email** - If you selected "Email Invoice" during creation, it's already sent. - **Manual sharing** - Copy the payment link, send via email, or generate a QR code. - **Download PDF** - Send the invoice as a PDF attachment. For detailed instructions, see [Sharing Invoices](/low-code-no-code/invoices/sharing-invoices). ## Step 3: Track the Invoice Monitor invoice status and view payment activity from the Dashboard. After a buyer makes a payment, you can: - View payment confirmation - Track partial payments - Access transaction details - Download receipts Invoice Details Page ### Payment attempts tab The Payment Attempts tab shows all payment activity on the invoice: - Filter by status (Succeeded, Failed, Pending, Canceled) - View payment amount, method, and timestamp - See masked card number and card type Invoice Details Page Payment Attempts Tab ## Real-Time updates with Webhooks Integrate [webhooks](/additional-resources/developers/webhooks/webhook-events) to receive real-time notifications when: - An invoice is paid. - A payment fails. - A partial payment is received. --- # Payment Methods for Invoices Source: https://docs.finix.com/low-code-no-code/invoices/payment-methods-for-invoices During [invoice creation](/low-code-no-code/invoices/invoices-quickstart), you can determine how your buyer can pay. You can configure the following settings: - **Allowed Payment Methods** - Select which payment options to accept (credit/debit card, bank account, Apple Pay, Google Pay). - **Partial Payments** - Allow buyers to make partial payments instead of the full amount at once. For more information, see [Accepting Partial Payments](/low-code-no-code/invoices/accepting-partial-payments). Invoice creation form showing payment method options including card, Apple Pay, and Google Pay ## Supported Payment Methods The following payment methods can be configured on an invoice: - `PAYMENT_CARD` - `APPLE_PAY` - `GOOGLE_PAY` - `BANK_ACCOUNT` - `CASH_APP_PAY` - `AFTERPAY` ## What the Buyer sees When a buyer clicks the invoice link, the payment page will display the available payment options. Invoice Payment Page - Apple Pay --- # Sharing Invoices Source: https://docs.finix.com/low-code-no-code/invoices/sharing-invoices Finix allows you to share an Invoice via email or share it directly. ## Delivery options During [invoice creation](/low-code-no-code/invoices/invoices-quickstart), you may select delivery options to determine how you want to share the invoice with the buyer. There are two options: 1. Automatically send the invoice to the buyer's email address. 2. [Share an invoice link manually](#sharing-an-invoice-after-its-created). ### Sharing an Invoice upon creation When creating the invoice: 1. Select a buyer or click **+ Add a Buyer** if they are not in the system. - The buyer's email address will appear in the **Send Invoice To** field. 2. For **Delivery Options**, leave **Email Invoice** selected. 3. Optional: You can add more recipients by separating email addresses with a semicolon. 4. Optional: You can also add yourself as a recipient. Delivery Options - Email Invoice Upon creation, the invoice will be sent to the buyer's email address. ### Sharing an Invoice after it's created After creating an invoice, you can manually share the invoice link by following these steps: 1. Navigate to the **Invoices** list page and select the desired invoice you want to share. 2. From the invoice details page, click **Share Link** to access multiple sharing options: #### Via email Send the invoice link via email. #### Via text message Share via SMS or messaging apps. #### Via QR code Generate a scannable QR code. #### Copy Link To share an invoice through Slack or another messaging app, copy the invoice URL. Your buyer can then use the link to pay. Invoice Sharing Options - Copy Link ## What the Buyer sees When a buyer clicks the invoice link, they're taken to the payment page where they can: - Review the invoice details and itemized breakdown - Enter their billing information - Select a [payment method](/low-code-no-code/invoices/payment-methods-for-invoices) - Pay the full amount or a [partial payment](/low-code-no-code/invoices/accepting-partial-payments) (if enabled) Invoice Payment Page Buyers will see a confirmation message upon successful payment. ## Link sharing history You can view a record of all invoice shares from the invoice details page. To do so: 1. On the dashboard, expand **Payment Tools** in the left navigation and click **Invoices**. 2. From the **Invoices** list page, select the desired invoice. 3. From the invoice details page, click the **Link Sharing History** tab to view a record of all invoice shares. The Link Sharing History displays: - **Recipient** - Who the invoice was sent to. - **Delivery Method** - How it was sent (email, link, etc.). - **Shared On** - Date and time of the share. - **Status** - Whether the delivery succeeded or failed. Invoice Details Page Link Sharing History Tab --- # Low-Code / No-Code Branding Source: https://docs.finix.com/low-code-no-code/manage-low-code-no-code/low-code-branding Finix allows you to customize branding in several ways across our No-Code / Low-Code features. Here's a table of the customizable branding available on our No-Code / Low-Code features: | Field | Description | Payment Links | Checkout Forms | Subscription Links | Payout Links | | --- | --- | --- | --- | --- | --- | | Icon | URL of the logo | ✓ | ✓ | ✓ | ✓ | | Logo | URL for the logo | ✓ | ✓ | ✓ | ✓ | | Brand Color | Hex code of branding color. | ✓ | ✓ | ✓ | ✓ | | Accent Color | Hex code of accent color. | ✓ | ✓ | ✓ | ✓ | | Button Color | Hex code of button color. | ✓ | ✓ | ✓ | ✓ | | Branded Subdomain | Subdomain (e.g. acme.payment-form.com) | ✓ | ✓ | ✓ | ✓ | | Button Text | You can customize the text that appears. | | | ✓ | | | Custom success return URL | A URL to redirect buyers to if the operation was successful. | ✓ | ✓ | ✓ | ✓ | | Custom failure return URL | A URL to redirect buyers to if the operation was unsuccessful. | ✓ | ✓ | ✓ | ✓ | | Custom expired session URL | A URL to redirect buyers to if their session expires before completing the operation. | ✓ | ✓ | ✓ | ✓ | ## Branded subdomains Using the Finix Dashboard, you can configure how your urls appear for Finix's Low-Code / No-Code products (e.g. Payment Links). Finix will generate a short link with the following structure: ```json {your-subdomain}.payments-form.com ``` In your live environment, you'll be able to see the subdomain configured. To request a branded subdomain (e.g., `yourbrand.payments-form.com`), email [support@finixpayments.com](mailto:support@finixpayments.com) with your custom subdomain. ### Payment Links Using Payment Links, you can configure the branding that appears by default. To configure, head to your Company > Branding > Payment Links Tab. Buyer Page ### Subscription Links Using Subscription Links, you can configure the branding that appears by default. To configure, head to your Company > Branding > Subscription Links Tab. Subscriptions Settings Subscription Links follow a similar branding to Payment Links. To learn more about Subscription Links, see our [guide](/guides/subscriptions/subscription-links). ### Payout Links Using Payout Links, you can configure the branding that appears by default. To configure, head to your Company > Branding > Payout Links Tab. Create a Payout on Dashboard Payout Links follow a similar branding to Payment Links. To learn more about Payout Links, see our [guide](/guides/payouts/payout-links). --- # Configuring Custom Domains Source: https://docs.finix.com/low-code-no-code/manage-low-code-no-code/registering-domains Adding a custom domain can help build customer confidence by showing your company name in the short links. Custom domains can be used on Finix's low-code solutions, including checkout forms, payment links, and subscription links. ## Add a custom domain If your domain is `example.com`, we recommend using `payments.example.com` or `pay.example.com` as your custom subdomain. You must use a subdomain (like `payments.example.com`) rather than a path (like `example.com/checkout`). Note Custom Domains can only be enabled in our Production (Live) environment. 1. On the Finix Dashboard, navigate to **Manage** → **Company** → **Branding** → **Domains**. 2. Click **Add** next to **Domain (Advanced)**. 3. Enter your desired subdomain (for example, `payments` if your domain is `example.com`): - `payments.example.com` 4. Click **Add Domain**. 1. A popup displays the DNS records you need to add to your domain provider. Copy these details. 2. Click **Done** to close the popup. You can view the DNS record details again by clicking **View Verification Instructions** next to your custom domain. Domains settings page showing custom domain with unverified status ## Add DNS records to your domain provider ### Find your DNS provider Your DNS provider is usually the company where you registered your domain. If you're not sure, check your domain registration email or contact the company where you purchased your domain. ### Add the DNS records 1. Sign in to your DNS provider's control panel. 2. Find the page to manage DNS records for your domain. 3. Add the two DNS records from the Finix Dashboard popup: - **CNAME record** - This connects your subdomain to Finix 4. Enter the values exactly as shown in the [Domain Verification popup](#domain-verification-popup) and save the records. If you need help, contact your DNS provider's support team. Share the DNS record details provided by Finix with them, and they can help you add the records. ## Domain verification and activation ### Domain Verification After you add the DNS records to your provider, it may take up to 72 hours for them to propagate and be verified. Once Finix verifies the DNS records, your domain will show a **Verified** indicator in the Finix Dashboard, confirming it's ready to activate. Domains settings page showing custom domain with green verified status indicator ### Domain activation The last step you will need to do is to **Activate** your domain. This happens after your domain is verified. If your domain is not yet verified, you can click [View Verification Instructions](#view-verification-instructions) next to your domain to see the DNS record details again. ## Test your custom domain We recommend creating a test payment link to verify your DNS and Finix are configured correctly. 1. On the Finix Dashboard, navigate to **Manage** → **Company** → **Branding** → **Domains**. 2. Verify you have an **Active** indicator next to your custom domain. 3. [Create a Payment Link](/low-code-no-code/payment-links/quickstart-dashboard) You'll see your new custom domain in the details page of your newly created payment link. ## Remove your custom domain If you need to remove your custom domain: 1. On the Finix Dashboard, navigate to **Manage** → **Company** → **Branding** → **Domains**. 2. Click the three dots (`...`) next to the domain you want to remove, and select **Remove**. 3. Read the popup confirmation, and click **Remove** to confirm the removal. 4. Log in to your DNS provider and delete the two DNS records you created for your custom subdomain. Note After you remove your custom domain, previous payment link URLs using your custom domain may contain errors. We recommend de-activating payment links and subscription links before proceeding. --- # Transfer Attempts Source: https://docs.finix.com/low-code-no-code/manage-low-code-no-code/transfer-attempts When a user attempts to make a payment using a Checkout Form or [Payment Link](/low-code-no-code/payment-links), or a recipient submitting details with a [Payout Link](/guides/payouts/payout-links)—a Transfer Attempt is created. Using transfer attempts, you can track the lifecycle of a payment or a series of payments if you are using a multi-use Payment Link. A Transfer Attempt records the original `entity_id` and the resulting `transfer_id` (or `authorization_id` for payment links that authorize a payment). You cannot create transfer attempts directly. They are created automatically when a user submits a form using one of these methods. ## Key details - **Relationship to Transfers** - Each payment using a `Checkout Form` or `Payment Link` creates a `Transfer` with a corresponding `Transfer Attempt` to track it. Multiple transfers can occur when buyers retry failed payments or when multiple buyers use a multi-use payment link. Payout links create a `Transfer` for each payout, with a corresponding `Transfer Attempt` to track it. - **Relationship to Authorizations** - Payment links configured to authorize a payment reference the resulting `Authorization` instead of a `Transfer`. - **Every Transfer Attempt contains two main identifiers** - `transfer_id` (points to the `Transfer`) and `entity_id` that references the entity that initiated the payment. An `authorization_id` is present for payment links that authorize a payment. ## How Checkout Form, Payment Link, or Payout Links relate to Transfer attempts and Transfers Here's how checkout forms, payment Links, and payout links relate to transfer attempts and transfers: 1. **Checkout Form, Payment Link, or Payout Link:** These entities allow users enter payment details. Multi-use payment links allow multiple submissions, each creating a new `Transfer Attempt` and `Transfer`. Checkout forms and payout links are single-use, creating only one `Transfer Attempt` and `Transfer`. 2. **Transfer Attempt:** Each payment attempt creates a `Transfer Attempt` resource that contains: - The originating entity (via the `entity_id` field) - The resulting `Transfer` (via the `transfer_id` field) This structure lets you trace each `Transfer` back to its originating entity. You can see every attempt, whether it succeeded or not, for that entity. 3. **Transfer:** This is the final payment resource created if a transfer attempt is successful. Transfer Attempts ## Transfer attempt States When a user submits a form, the system creates a `Transfer Attempt` in `PENDING` state. If the payment is accepted, the state changes to `SUCCEEDED`. If it fails, it changes to `FAILED`. ## Transfer attempt Webhooks Users often want to track the relationships between entities and the resulting transfers. The best approach is to subscribe to the [Transfer Attempt - Created](/additional-resources/developers/webhooks/webhook-events#transfer-attempt-created) and [Transfer Attempt - Updated](/additional-resources/developers/webhooks/webhook-events#transfer-attempt-updated) webhooks. These webhooks provide both `entity_id` and `transfer_id`, allowing you to associate a `Transfer` with the original entity. For example, when listening to the `Transfer Attempt - Created` webhook, the payload will show the `transfer_id` and `entity_id`. The `entity_type` field indicates whether the entity is a `Checkout Form`, `Payment Link`, or `Payout Link`. ```json { "type": "created", "entity": "transfer_attempt", "occurred_at": "2020-04-29T20:31:32.348", "_embedded": { "transfer_attempts": [ { "id": "transfer_attempt_ciACBK59kDhfx2Mi4Vy81", "created_at": "2024-12-27T05:52:07.44Z", "updated_at": "2024-12-27T05:52:07.44Z", "merchant_id": "MUmfEGv5bMpSJ9k5TFRUjkmm", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "amount": 200, "currency": "USD", "state": "SUCCEEDED", "payment_frequency": "ONE_TIME", "transfer_id": "TRodANv8j3CVRUQz4sgZa8sK", "payment_instrument_id": "PI7AS61AmsnJQ5Y7sL7dM1Ux", "entity_id": "checkout_form_ciADaDNMFAHdyNbDPuByS", "entity_type": "CHECKOUT_FORM", "buyer_details": { "first_name": "", "last_name": "", "email": "test@gmail.com", "identity_id": "IDew6Bkcj1AwEP2aWhjjfdqS", "phone": null, "billing_address": null, "shipping_address": { "city": null, "country": "USA", "line1": null, "line2": null, "postal_code": null, "region": null } }, "failure_code": null, "failure_message": null, "tags": {}, "recipient_details": null, "operation_key": "SALE", "type": "DEBIT", "recipient_merchant_id": null, "receipt_requested_delivery_methods": [ { "type": "EMAIL", "destinations": ["test@gmail.com"] } ], "additional_buyer_charges": null, "amount_requested": 200 } ] } } ``` --- # Customize Payment Link Branding Source: https://docs.finix.com/low-code-no-code/payment-links/customize-branding Personalize the payment page that buyers see when they click your payment link. Add your logo, brand colors, and redirect URLs to create a consistent checkout experience. You can add branding when you [create a payment link](/low-code-no-code/payment-links/quickstart-dashboard) or by [editing an active payment](/low-code-no-code/payment-links/quickstart-dashboard#payment-link-details-page). ## Branding settings Configure the following branding options in the **Custom Branding** section: | Setting | Description | | --- | --- | | **Logo URL** | A link to your company logo image. Displayed in the payment page header. | | **Header Color** | The background color for the payment page header. | | **Button Background Color** | The background color for the payment button. | | **Button Text Color** | The text color for the payment button. | Custom Branding Settings ## Redirect URLs You can also configure where buyers are sent after interacting with the payment page: - **Success URL** - Where buyers go after a successful payment. - **Failure URL** - Where buyers go if the payment fails. - **Session Expired URL** - Where buyers go if their session times out. ## Payment page preview As you configure branding settings, the live preview shows how the payment page will appear to buyers. Payment Page Preview --- # How Payment Links Work Source: https://docs.finix.com/low-code-no-code/payment-links/how-payment-links-work Payment links create individual links you can send to buyers to complete a transaction. You can share these links on web pages, email, text, or QR codes. Payment links can be either "single-use" or "multiple-use". Single-use payment links are personalized for a specific customer's purchase, while multiple-use links can be used any number of times. With payment links, instead of logging in to a computer or meeting the seller in person, the buyer can click a link and complete the transaction on their phone or preferred device. Example use cases for payment links: - Including a payment link with an invoice for your buyer to pay - Asking a buyer to pay after they visit your store - Allowing buyers to pay through chat, email, or social media The payment link buyer page is supported on desktop and mobile. You can also customize the checkout page with your brand name and logo. Level 2 / Level 3 processing is supported for Payment Links. For more information, see our guide on [Level 2 / Level 3 Processing](/guides/online-payments/payment-features/level-2-level-3-processing#create-a-payment-link-with-level-2level-3-processing). ## Buyer experience Payment links are generated by entering transaction details in the Finix Dashboard. After creating the payment link, you can share it with your buyer via a hyperlink, QR code, email, or chat. When the buyer clicks the link, they will be directed to a payment page where they can enter their card or bank information to complete the transaction. Buyer Page ## Supported payment methods Finix's payment links support: - Card payments ($USD and $CAD) - Bank account payments (ACH Direct Debits in the USA and EFTs in Canada) - Google Pay - Apple Pay ## Payment Link types ### Single-Use Payment Links Single-use payment links can only be used once. After a buyer completes payment, the link transitions to **Completed** and cannot accept additional payments. Use single-use links when: - Sending a payment request for a specific transaction. - You want to ensure the link is only valid for one payment. - Tracking individual purchases tied to specific buyers. Single-use Link After payment, the buyer sees a confirmation with the items and total amount paid: Single-use Link - Completed If a buyer clicks the link again, they see a message confirming the payment was already processed: Single-use Link - Already Processed ### Multiple-Use Payment Links Multiple-use payment links can accept unlimited payments. The link remains **Active** until it expires or is manually deactivated. Use multiple-use links when: - Accepting recurring payments from multiple buyers. - Embedding a payment link on a website or in marketing materials. - You don't need to track individual buyers per transaction. Multiple-use links do not support L2/L3 [Level 2 / Level 3 processing](/guides/online-payments/payment-features/level-2-level-3-processing) is not supported for multiple-use payment links. Multiple-use Link Each successful payment creates a new [Transfer](/api/transfers) resource. You can [view all transactions](/low-code-no-code/payment-links/tracking-payment-links#view-payment-attempts) associated with a payment link on the dashboard. ## Amount types Payment links support two amount types: **Fixed** and **Variable**. ### Fixed amount Fixed amount payment links have a predetermined total that buyers cannot change. Use fixed amounts when you know the exact payment amount upfront. - The `amount_type` is set to `FIXED`. - The `total_amount` specifies the payment amount in cents. ### Variable amount Variable amount payment links let buyers enter their own payment amount within optional min/max limits. Use variable amounts for donations, tips, or when the final amount isn't known at link creation. - The `amount_type` is set to `VARIABLE`. - Optionally set `min_amount` and `max_amount` to control the allowed range. ## Payment Link lifecycle The typical payment link lifecycle follows these steps: 1. **Create**: Create a payment link in the [Dashboard](/low-code-no-code/payment-links/quickstart-dashboard) with product details, amount, and settings. 2. **Share**: [Share the link](/low-code-no-code/payment-links/sharing-payment-links) with buyers via email, text, QR code, or embed it on your website. 3. **Pay**: The buyer clicks the link and completes payment on the hosted payment page. 4. **Complete**: For single-use links, the state changes to **Completed**. For multiple-use links, the state remains **Active**. ## Payment Link States Payment Links transition through different states based on payment activity. You can view and filter payment links by state on the dashboard. | Status | Description | | --- | --- | | **Active** | The payment link is available for buyers to use. | | **Completed** | A payment has been successfully made (single-use links only). | | **Expired** | The link validity period has passed and the link can no longer be used. | | **Deactivated** | The payment link was manually deactivated and can no longer be used. | ### Active A payment link starts in the **Active** state after it's created. - For a single-use payment link, when a payment is made the state changes to **Completed**. - For multiple-use payment links, the state remains **Active** until it expires or is deactivated. ### Completed A single-use payment link moves to **Completed** when a payment is made. This state does not apply to multiple-use payment links. ### Expired A payment link moves to **Expired** when the link validity period has passed. Buyers can no longer use the link to make payments. ### Deactivated For multiple-use payment links, you can deactivate the link at any time while its state is **Active**. Once deactivated, the link cannot be used for payments. To deactivate payment link: 1. From the Finix Dashboard, click **Payment Tools** → **Payment Links**. 2. Click the payment link you want to deactivate. - The payment link details page opens. 3. Click the **...** icon and select **Deactivate**. - A banner appears at the top of the payment link page confirming the action. Payment Links - Deactivate ## State transitions ### Single-Use Payment Links Single-use payment links follow this flow: ```mermaid %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e9f0fd', 'primaryTextColor': '#0d121a', 'primaryBorderColor': '#0052e5', 'lineColor': '#0052e5', 'secondaryColor': '#e9f7fe', 'secondaryTextColor': '#0d121a', 'secondaryBorderColor': '#0052e5', 'tertiaryColor': '#e0faf9', 'tertiaryTextColor': '#0d121a', 'tertiaryBorderColor': '#00d6cc' }}}%% stateDiagram-v2 direction LR [*] --> Active: Create Active --> Completed: Payment Made Active --> Expired: Validity Period Ends Active --> Deactivated: Manual Deactivation Completed --> [*] Expired --> [*] Deactivated --> [*] ``` ### Multiple-Use Payment Links Multiple-use payment links remain Active through multiple payments: ```mermaid %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e9f0fd', 'primaryTextColor': '#0d121a', 'primaryBorderColor': '#0052e5', 'lineColor': '#0052e5', 'secondaryColor': '#e9f7fe', 'secondaryTextColor': '#0d121a', 'secondaryBorderColor': '#0052e5', 'tertiaryColor': '#e0faf9', 'tertiaryTextColor': '#0d121a', 'tertiaryBorderColor': '#00d6cc' }}}%% stateDiagram-v2 direction LR [*] --> Active: Create Active --> Active: Payment Made Active --> Expired: Validity Period Ends Active --> Deactivated: Manual Deactivation Expired --> [*] Deactivated --> [*] ``` Multiple-use links do not transition to **Completed** state. They remain **Active** until they expire or are manually deactivated. ## Payment methods You can allow buyers to pay with credit/debit cards, Apple Pay, and Google Pay. For more information, see [Payment Methods for Payment Links](/low-code-no-code/payment-links/payment-methods). ## Key Payment Link fields | Field | Description | | --- | --- | | `is_multiple_use` | When `true`, the payment link can be used for multiple transactions. When `false`, the link can only be used once. | | `amount_type` | Determines whether the payment amount is `FIXED` (set by you) or `VARIABLE` (buyer enters an amount within min/max limits). | | `allowed_payment_methods` | The payment methods buyers can use: `PAYMENT_CARD`, `BANK_ACCOUNT`, `APPLE_PAY`, or `GOOGLE_PAY`. | | `link_expires_at` | The timestamp when the payment link expires and can no longer be used by buyers. | | `state` | The current state of the payment link: `ACTIVE`, `COMPLETED`, `EXPIRED`, or `DEACTIVATED`. | ## Refunds Refunds on payments made through Payment Links are handled the same way as other payments. For more information, see [Refunds](/guides/after-the-payment/refunds). ## Terms of service You must include your terms and services with every payment link you create. Your terms and conditions should contain the following information. You must include a URL to your terms of service when creating a payment link. ### General terms - A description of the product or service that you are selling or offering. - Any third parties involved in the product you are selling or offering. - Reference to which governing law applies to you and your buyers. ### Privacy policy - Any data you are storing. - Any data you are sharing with third parties. - Your cookie policy. ### Shipping and delivery information - Expected delivery and shipping timelines - Any restrictions on where you can ship or deliver your goods or services ### Refunds and cancellations - Your general refund policies (e.g., 10 days, 30 days, no refunds allowed). - Directions on submitting a refund request or canceling a subscription. ### Contact information You should include general contact information such as: - Business name - Doing Business as - Support Email address - Support Phone number --- # Payment Links Source: https://docs.finix.com/low-code-no-code/payment-links Payment Links Payment links let you request payment from buyers for your goods or services. You can set up these links using the Finix Dashboard. ## Learn more Payment Links Quickstart Learn how to get started with payment links. How Payment Links Work Learn how payment links work. Sharing Payment Links Learn how to share payment links. Tracking Payment Links Learn how to track payment links. Payment Methods Learn about the payment methods available for payment links. Customize Branding Learn how to customize the branding for your payment links. --- # Payment Methods for Payment Links Source: https://docs.finix.com/low-code-no-code/payment-links/payment-methods Finix payment links support credit/debit cards, ACH bank transfers, Apple Pay, and Google Pay. Configure which methods are enabled at link creation. Payment link creation form showing available payment method options including card and digital wallets ## Supported payment methods | Payment Method | Description | | --- | --- | | **Credit/Debit Card** | Accept Visa, Mastercard, American Express, and Discover cards. Supports USD and CAD. | | **Bank Account (ACH)** | Accept ACH Direct Debits (USA). | | **Apple Pay** | Fast, secure checkout with tokenized payments and biometric authentication. Appears on supported Apple devices. | | **Google Pay** | Fast, secure checkout with tokenized payments. Appears on supported Android devices and Chrome browsers. | ## Configuring payment methods Select which payment methods to accept in the **Allowed Payment Methods** section when creating a payment link: - **Credit/Debit** - Accept card payments. - **Bank Account** - Accept ACH (USA) payments. Buyers connect their bank account with [Plaid](/guides/online-payments/bank-payments/plaid-integration), which verifies the account instantly. - **Apple Pay** - Enable Apple Pay for supported devices. - **Google Pay** - Enable Google Pay for supported devices. You can enable multiple payment methods. Buyers will see all enabled options on the payment page. ## What the Buyer sees When a buyer clicks the payment link, the payment page displays the available payment options based on your configuration and the buyer's device. Payment Page ### Google Pay Google Pay speeds up checkout and reduces abandonment by letting buyers pay with saved cards. It offers enhanced security through tokenization, which hides card numbers and requires biometric or PIN authentication. Google Pay on Payment Link ### Apple Pay Apple Pay offers similar benefits to Google Pay with tokenized, biometric-authenticated payments. It appears automatically for buyers on supported Apple devices. --- # Creating Payment Links using the Dashboard Source: https://docs.finix.com/low-code-no-code/payment-links/quickstart-dashboard Learn how to quickly create payment links with the Finix Dashboard. ## Step 1: Create a Payment Link ### Navigate to Payment Links 1. In the Dashboard, navigate to **Tools** in the left navigation. 2. Click **Payment Links**. 3. Click **Create Payment Link**. Create Payment Link The creation form displays with a live preview that updates as you fill out each section. Payment link Creation Form ### Fill out the form Complete each section of the form as described below. #### Basic information Basic Payment link Information | Field | Description | | --- | --- | | **Payment Link Name** | Internal label to identify the link in your records. Not visible to buyers. | | **Transaction Type** | Choose **Sale** or **Authorization**. If Authorization, you must select Credit/Debit, Apple Pay, or Google Pay as the [payment method](/low-code-no-code/payment-links/payment-methods). | | **Amount Type** | [Fixed](/low-code-no-code/payment-links/how-payment-links-work#fixed-payment-links): Set a specific amount for each item.[Variable](/low-code-no-code/payment-links/how-payment-links-work#variable-payment-links): Let buyers enter an amount within min/max limits you define. | | **Link Type** | [Single Use](/low-code-no-code/payment-links/how-payment-links-work#single-use-payment-links): Link works once. [Multiple Use](/low-code-no-code/payment-links/how-payment-links-work#multiple-use-payment-links): Link can be reused. | | **Link Validity** | How long the link remains active before expiring. | | **Allowed Payment Methods** | Select which [payment options](/low-code-no-code/payment-links/payment-methods) to accept. | #### Product or service information Add one or more products or services you're charging for. Fixed Amount Product or Service Information - Fixed Amount | Field | Description | | --- | --- | | **Product/Service Name** | What you're charging for. | | **Unit Price** | Price per unit. | | **Quantity** (optional) | Number of units. | | **Description** (optional) | Additional details about the item. | | **Image** (optional) | Product image displayed on the payment page. | Variable Amount Product or Service Information - Variable Amount | Field | Description | | --- | --- | | **Product/Service Name** | What you're charging for. | | **Control what buyers can enter** | Enable to set minimum and maximum amounts buyers can enter. | Click **Add another product** to include additional items. #### Transaction options Fixed Amount Transaction Options - Fixed Amount | Field | Description | | --- | --- | | **Terms of Service URL** | Link to your [terms of service](/low-code-no-code/payment-links/how-payment-links-work#terms-of-service) displayed on the payment page. Required for all links. | | **Additional Discount** | Discount applied to the total. | | **Shipping Amount** | Delivery costs. | | **Tip Amount** | Tip added to the total. | | **Split Transaction Across Multiple Merchants** | Used to [split transactions](/guides/online-payments/payment-features/split-transactions). | Variable Amount Transaction Options - Variable Amount | Field | Description | | --- | --- | | **Terms of Service URL** | Link to your [terms of service](/low-code-no-code/payment-links/how-payment-links-work#terms-of-service) displayed on the payment page. Required for all links. | #### Advanced settings Advanced Settings - Additional Buyer Details | Setting | Options | | --- | --- | | **Additional Buyer Details** | Name, Phone Number, Shipping Address, Billing Address, Custom Fields (e.g., account number, project ID). | | **Receipt Options** | Email a receipt to the buyer, email a copy to yourself or additional recipients. | | **Custom Card Statement Descriptor** | The description of the merchant that appears on the buyer's bank or card statement. | #### Custom branding Customize colors, logos, and button styles. For details, see [Customize Branding](/low-code-no-code/payment-links/customize-branding). ### Create the Link Click **Create Payment Link** to finalize. You'll see a confirmation and can view the payment link details page. ### Payment Link details page From the payment link details page, you can - [Share the payment link](#step-2-share-the-payment-link) - Edit the payment link - Deactivate the payment link To edit or deactivate the payment link, click the **...** to reveal the additional options. Payment Link Details - Additional Options ## Step 2: Share the Payment Link After creating your link, share it with buyers. Options include: - Copy the link URL directly - Send via email - Embed in your website or app For detailed instructions, see [Sharing Payment Links](/low-code-no-code/payment-links/sharing-payment-links). ## Step 3: Track your Payment Link Monitor payment state and view transaction details from the Dashboard. After a buyer completes payment, you can: - View payment confirmation - Access transaction details - Download receipts For more information, see [Tracking Payment Links](/low-code-no-code/payment-links/tracking-payment-links). ## Real-Time updates with Webhooks Integrate [webhooks](/additional-resources/developers/webhooks/webhook-events#payment-link-created) to receive real-time notifications when: - A payment is completed - A payment fails - An authorization is created --- # Sharing Payment Links Source: https://docs.finix.com/low-code-no-code/payment-links/sharing-payment-links Share payment links with buyers via email, text message, QR code, or by copying the link directly. ## How to share a Payment Link 1. In the Dashboard, navigate to **Tools** in the left navigation and click **Payment Links**. 2. Select the payment link you want to share. 3. From the payment link details page, click **Share Link**. 4. Choose a sharing method: ### Sharing methods | Method | Description | | --- | --- | | **Email** | Send the payment link directly via email. Enter the recipient's email address and an optional message. | | **Text Message** | Share via SMS or messaging apps. Enter the recipient's phone number. | | **QR Code** | Generate a scannable QR code. Useful for in-person transactions or printed materials. | | **Copy Link** | Copy the payment link URL to share through apps, social media, or any other channel. The buyer can use the link to complete payment. | For example, you can share the payment link through Slack: Payment Link Sharing Options - Copy Link ## What the Buyer sees When a buyer clicks the payment link, they're taken to the payment page where they can enter their payment details and view an itemized breakdown of the products/services. The fields present depend on the payment link settings and configuration. Payment Links Payment Page Buyers see a confirmation message upon successful payment. For single-use payment links, clicking the link again shows that the payment was successful and does not allow another payment. ## Link sharing history View a record of all shares for a payment link from the details page: 1. In the Dashboard, navigate to **Tools** in the left navigation and click **Payment Links**. 2. Select the desired payment link. 3. Click the **Link Sharing History** tab. The Link Sharing History displays: | Field | Description | | --- | --- | | **Recipient** | Who the payment link was sent to. | | **Delivery Method** | How it was sent (email, text, link copy, etc.). | | **Shared On** | Date and time of the share. | | **State** | Whether the delivery succeeded or failed. | --- # Tracking Payment Links Source: https://docs.finix.com/low-code-no-code/payment-links/tracking-payment-links Monitor your payment links to see their state, view payment attempts, and track completed transactions. Refunds Refunds on payments made through payment links are handled the same way as other payments. For more information, see [Refunds](/guides/after-the-payment/refunds). ## Payment Link States Payment links move through different states as buyers interact with them. Filter the payment links list by state to quickly find what you're looking for. | Status | Description | | --- | --- | | **Active** | The payment link is available for buyers to use. | | **Completed** | A payment has been successfully made (single-use links only). | | **Expired** | The link validity period has passed and the link can no longer be used. | | **Deactivated** | The payment link was manually deactivated and can no longer be used. | ## View Payment Link States To check the state of your payment links: 1. In the Dashboard, navigate to **Tools** in the left navigation. 2. Click **Payment Links**. Payment Links List Page The list shows each payment link's state, amount, and creation date. Use the state filter to narrow down the list. ## View payment attempts To see all payment attempts for a specific payment link: 1. Select a payment link from the list to open its details page. 2. Click the **Payment Attempts** tab. Payment Link Details Page Payment Attempts Tab Each payment attempt shows: - Buyer information - Amount - State (Succeeded, Failed, Pending) - Payment instrument and type - Created timestamp Click any attempt to view the full payment attempt details page. ## View payment details From a payment attempt, you can navigate to the associated payment: 1. Open a payment attempt from the **Payment Attempts** tab. 2. Click the **Payment** link to open the payment details page. Payment Attempt Details Page The payment details page shows complete transaction information, including the payment link that generated it. ## Real-Time updates with Webhooks For automated tracking, integrate [webhooks](/additional-resources/developers/webhooks/webhook-events#payment-link-created) to receive real-time notifications when: - A payment is completed - A payment fails - An authorization is created --- # How the Virtual Terminal Works Source: https://docs.finix.com/low-code-no-code/virtual-terminal/how-the-virtual-terminal-works Use the Virtual Terminal to accept credit and debit card payments directly from the Finix Dashboard, without sending buyers to an external payment page. ## Virtual Terminal vs. other low-code / no-code solutions Unlike Finix's other low-code/no-code solutions, the Virtual Terminal is designed for real-time payment collection with no prior setup required. There is no buyer-facing page where customers enter their own payment details. Instead, the merchant enters the buyer's card information directly or collects payment through a connected physical device. ## The Virtual Terminal form The Virtual Terminal form allows you to configure the payment as a sale or authorization, enter transaction and payment details, and add buyer fees. You can process the payment manually by entering card details or send it to a connected device. Virtual Terminal - Manually Enter Payment Details ## Sample use case Imagine you are a merchant that does custom embroidery. When a customer comes to the store to pick up their order, you type in the total amount due on the Virtual Terminal in the Finix Dashboard. You can manually enter the customer's payment method, or — if you have a payment device provisioned for [in-person payments](/guides/in-person-payments) — push the transaction to the device so the customer can pay by tapping, swiping, or dipping their credit or debit card. In this case, the Virtual Terminal means you do not need an external payment page. Everything is handled directly from the Finix Dashboard. ## Transaction types When creating a payment in the Virtual Terminal, you choose between two transaction types: - **Sale** - A one-step transaction that immediately charges the buyer's card. - **Authorization** - A two-step transaction that first places a hold on the buyer's funds. You can later capture the authorization to complete the charge, or void it to release the hold. ## Supported features The Virtual Terminal supports the following: - **Process a sale or authorization** - Immediately charge a buyer or place a hold on funds to capture or void later. - **Add buyer fees** - Pass processing costs to the buyer using a [surcharge fee](/low-code-no-code/virtual-terminal/buyer-fees/surcharge-fees) (up to 3% on credit cards) or a flat-rate [convenience fee](/low-code-no-code/virtual-terminal/buyer-fees/convenience-fees). - **Custom statement descriptor** - Add a descriptor (1–20 characters) that appears on the buyer's card statement. Available on sales only. - **Split transactions** - Split a transaction across two or more merchants. For more information, see [Split Transactions](/guides/online-payments/payment-features/split-transactions). - **Level 2 / Level 3 processing** - Submit additional order data to qualify for lower interchange rates. For more information, see [Level 2 and Level 3 Processing](/guides/online-payments/payment-features/level-2-level-3-processing). ## Supported payment methods The Virtual Terminal supports card payments ($USD and $CAD). ## Ways to collect payment When filling out the Virtual Terminal form, you can collect the buyer's payment in two ways: ### 1. Manually enter payment method Manually enter the buyer's credit/debit card information into the Virtual Terminal. Virtual Terminal - Manually Enter Payment Details ### 2. Send to a payment device You can process the payment [using a payment device](/low-code-no-code/virtual-terminal/using-payment-devices). The device must be provisioned and have an open connection. See our [in-person payments guides](/guides/in-person-payments) to learn how to set up a device. Virtual Terminal - Send to a Payment Device ## Refunds Refunds on payments made through the Virtual Terminal are handled the same way as other payments. View our guide on [managing transactions](/low-code-no-code/virtual-terminal/managing-transactions), or to learn about refunds more broadly, refer to our [Refunds](/guides/after-the-payment/refunds) guide. --- # Virtual Terminal Source: https://docs.finix.com/low-code-no-code/virtual-terminal Virtual Terminal The Virtual Terminal lets you charge any credit or debit card directly from the Finix Dashboard — no external payment page required. ## Learn more Virtual Terminal Quickstart Learn how to quickly create payments with the Virtual Terminal. How the Virtual Terminal Works Learn how the Finix Virtual Terminal works — process payments directly from the Dashboard. Using Payment Devices Learn how to use a payment device to collect payment instead of manually entering card details in the Virtual Terminal. Buyer Fees Learn how to add buyer fees to Virtual Terminal transactions. Managing Transactions Learn how to manage transactions processed with the Virtual Terminal. --- # Managing Transactions Source: https://docs.finix.com/low-code-no-code/virtual-terminal/managing-transactions After processing a payment or authorization through the Virtual Terminal, you can manage it from the Finix Dashboard. ## View and manage a transaction Sale After [using the Virtual Terminal to process a sale](/low-code-no-code/virtual-terminal/quickstart), a **Payment ID** is returned. Click the **Payment ID** to open the payment details page. From the payment details page, you can: - Review the payment details. - Create a receipt. - Issue a [refund](/guides/after-the-payment/refunds). Managing Payments Authorization After [using the Virtual Terminal to process an authorization](/low-code-no-code/virtual-terminal/quickstart), an **Authorization ID** is returned. Click the **Authorization ID** to open the authorization details page. From the authorization details page, the following actions are available: - **Capture Authorization** the authorization to complete the charge. - **Void Authorization** the authorization to release the hold on the buyer's funds. - **Create Receipt** for the authorization. Managing Authorizations --- # Virtual Terminal Quickstart Source: https://docs.finix.com/low-code-no-code/virtual-terminal/quickstart Learn how to create a payment using the Virtual Terminal in the Finix Dashboard. ## Step 1: Open the Virtual Terminal ### Option 1: From the Payments List Page 1. From the left navigation, click **Transactions** > **Payments**. 2. Click **Take a Payment**. Payments List Page - Take a Payment ### Option 2: From the Virtual Terminal Page From the left navigation, click **Tools** > **Virtual Terminal**. Virtual Terminal Page ## Step 2: Enter payment details From the **Virtual Terminal**, you have the option to create a sale or authorization. - **Sale** - A one-step transaction that immediately charges the buyer. - **Authorization** - A two-step transaction that places a hold on funds, which you can later capture or void. Sale ### Sale transaction details | Field | Description | | --- | --- | | **Total Purchase Amount** | The total amount charged to the buyer's debit or credit card, including taxes, tips, or other fees. | | **Description** | Add any helpful details, such as order numbers or invoice information. | #### Sale buyer fees (optional) Click **+Add Buyer Fee** to add a buyer fee to the transaction. You can choose from: - **Surcharge Fee** - Enter a percentage up to 3%. Surcharge fees are only applied to credit cards. For more information, see [Surcharge Fees](/low-code-no-code/virtual-terminal/buyer-fees/surcharge-fees). - **Convenience Fee** - Enter a flat rate amount. For more information, see [Convenience Fees](/low-code-no-code/virtual-terminal/buyer-fees/convenience-fees). Click **Remove** to remove the buyer fee. #### Statement Descriptor (optional) Click **+Custom Card Statement Descriptor** to add a custom descriptor that appears on the buyer's card statement. The statement descriptor must be 1–20 characters long. Click **Remove** to remove the statement descriptor. ### Sale payment details Select how to collect the buyer's payment method: | Option | Description | | --- | --- | | **Manually Enter Payment Method** | Select the buyer. If the buyer isn't listed, click **Add New Buyer** to enter their details. Then select the payment method to charge. You'll only see the first six and last four digits of the card number. If the buyer's card isn't shown, click **Add a new payment method** to add it. | | **Send to a Payment Device** | Process the payment [using a payment device](/low-code-no-code/virtual-terminal/using-payment-devices). The device must be provisioned and have an open connection. See our [in-person payments guides](/guides/in-person-payments) to learn how to set up a device. | ### Sale processing data (optional) After selecting a payment method, you can add additional data to qualify for lower interchange rates. Select **Level 1** (default), **Level 2**, or **Level 3** processing. For more information, see [Level 2 and Level 3 Processing](/guides/online-payments/payment-features/level-2-level-3-processing). ### Additional options - **Split this transaction across multiple merchants** (Optional): Tick this checkbox to split the transaction across multiple merchants. For more information, see [Split Transactions](/guides/online-payments/payment-features/split-transactions). Click **Review Transaction** when ready. Virtual Terminal - Form Authorization We recommend filling out every field to make the authorization easier to search for later. ### Authorization details | Field | Description | | --- | --- | | **Total Purchase Amount** | The total amount that will be held on the buyer's debit or credit card, including taxes, tips, or other fees. | | **Description** | Add any helpful details, such as order numbers or invoice information. | #### Authorization buyer fees (optional) Click **+Add Buyer Fee** to add a buyer fee to the transaction. You can choose from: - **Surcharge Fee** - Enter a percentage up to 3%. Surcharge fees are only applied to credit cards. For more information, see [Surcharge Fees](/low-code-no-code/virtual-terminal/buyer-fees/surcharge-fees). - **Convenience Fee** - Enter a flat rate amount. For more information, see [Convenience Fees](/low-code-no-code/virtual-terminal/buyer-fees/convenience-fees). Click **Remove** to remove the buyer fee. ### Authorization payment details Select how to collect the buyer's payment method: | Option | Description | | --- | --- | | **Manually Enter Payment Method** | Select the buyer. If the buyer isn't listed, click **Add New Buyer** to enter their details. Then select the payment method to charge. You'll only see the first six and last four digits of the card number. If the buyer's card isn't shown, click **Add a new payment method** to add it. | | **Send to a Payment Device** | Collect payment method details using a payment device. The device must be provisioned and show a **Connected** status. For more information, see [Using Payment Devices](/low-code-no-code/virtual-terminal/using-payment-devices). | ### Authorization processing data (optional) After selecting a payment method, you can add additional data to qualify for lower interchange rates. Select **Level 1** or **Level 3** processing. For more information, see [Level 2 and Level 3 Processing](/guides/online-payments/payment-features/level-2-level-3-processing). Click **Review Transaction** when ready. Virtual Terminal - Form ## Step 3: Review and submit This applies if you selected "Manually enter the payment method" in Payment Details. If you selected "Send to a Payment Device", see the [Using Payment Methods with the Virtual Terminal](/low-code-no-code/virtual-terminal/using-payment-devices#3-send-to-a-payment-device) guide. Sale 1. Review the **Purchase Details** and **Billing Details** to confirm the transaction is correct. 2. Choose to send a receipt to the buyer, to yourself, or both. 3. Click **Process Payment** to complete the transaction. Virtual Terminal - Review Payment Authorization 1. Review the **Purchase Details** and **Billing Details** to confirm the authorization is correct. 2. Choose to send a receipt to the buyer, to yourself, or both. 3. Click **Process Authorization** to submit. Review Authorization ## Step 4: Confirmation Sale After submitting, a confirmation message appears. - Use the **Payment ID** to [manage the payment](/low-code-no-code/virtual-terminal/managing-transactions). The **Payment ID** is taken from the [Transfer](/api/transfers) created to debit funds from the buyer. - Click **View Receipt** to view and print payment details and to provide your buyer with a receipt. - Click **Create Another Transaction** to take another payment. - Click **View All Payments** to view all your payments. Virtual Terminal - Confirmation Sale Authorization After submitting, a confirmation message appears. - Use the **Authorization ID** to [manage the authorization](/low-code-no-code/virtual-terminal/managing-transactions). The **Authorization ID** is taken from the [Authorization](/api/authorizations) created to hold funds from the buyer. - Click **View Receipt** to view and print payment details and to provide your buyer with a receipt. - Click **Create Another Transaction** to take a payment or create an authorization. - Click **View All Authorizations** to view all your authorizations. Virtual Terminal - Confirmation Authorization ## Step 5: Manage the transaction You can [manage the transaction](/low-code-no-code/virtual-terminal/managing-transactions) from the Finix Dashboard. - For sales, this helps view payment status and issue refunds. - For authorizations, you can capture and void authorizations. --- # Using Payment Devices with the Virtual Terminal Source: https://docs.finix.com/low-code-no-code/virtual-terminal/using-payment-devices When processing a transaction using the Virtual terminal, you can process the payment by collecting the payment using a payment device rather than manually entering the payment method on the dashboard. ## 1. Navigate to the Virtual Terminal ### Option 1: From the Payments List Page 1. From the left navigation, click **Transactions** > **Payments**. 2. Click **Take a Payment**. Payments List Page - Take a Payment ### Option 2: From the Virtual Terminal Page From the left navigation, click **Tools** > **Virtual Terminal**. Virtual Terminal Page ## 2. Fill out basic form information 1. Select whether to process a **Sale** or **Authorization** using the Virtual Terminal. 2. Under **Transaction Details**, enter a **Total Purchase Amount** and a **Description**. ## 3. Send to a payment device 1. Under **Transaction Details**, select **Send to a payment device**. 2. Click **Review Transaction**. - A **Ready for payment** message displays on the dashboard indicating that the device is ready for a card tap, swipe, or dip. ## 4. Buyer makes the payment On the payment device, a prompt displays asking the buyer to tap, insert, or swipe their card. If approved, a **Payment Approved** screen displays on the device, prompting the buyer to choose a receipt option: **Print**, **Email**, **Text**, or **No Receipt**. Payment App - Confirm Pay If the payment fails, the dashboard displays an error: Payment App - Payment Failed ## 5. Review the payment confirmation On the dashboard, a confirmation page displays a **Payment ID** you can use to [manage the transaction](/low-code-no-code/virtual-terminal/managing-transactions) as well as payment device details. Virtual Terminal - Confirmation for Device Payment --- # Getting Started with Finix Checkout Source: https://docs.finix.com/low-code-no-code/mobile-apps/finix-checkout/getting-started Device Compatibility Finix Checkout requires iOS version 18.1 or later. ## Prerequisites To use Finix Checkout, you must have an existing Finix account. If you don't have one yet: 1. [Sign up for a Finix account](/guides/getting-started/finix-sign-up) 2. Once your account is set up, [sign in](#signing-in) to Finix Checkout using the same credentials. ## Signing in 1. Tap the **Finix Checkout** app icon on your Home screen. 2. When the following dialogs appear, respond as follows: - **Notifications** - Tap **Allow** or **Don't Allow**. Notifications are not required to use the app. - **"Finix Checkout wants to use auth0.com to Sign In"** - Tap **Continue**. 3. On the login screen, enter your Finix Dashboard username and password and sign in. Finix Checkout iOS app login screen After signing in, the [Checkout screen](#checkout-screen) displays. ## App navigation The app includes a navigation bar at the bottom of the screen with four sections: | Section | Description | | --- | --- | | **Checkout** | The home screen. [Process sales or authorizations](/low-code-no-code/mobile-apps/finix-checkout/taking-a-payment) using a card reader, manual entry, or a payment link. | | **Transactions** | View and filter your payment history. See [Transactions](#transactions). | | **Buyers** | Add, search, and manage buyers. See [Buyers](#buyers). | | **More** | Access device management, payment links, app info, and logout. | ## Checkout screen The Checkout screen is the app's home screen and displays after signing in. From here, you can select a **Sale** or **Authorization** transaction type and start taking a payment. For step-by-step instructions, see [Take a Payment](/low-code-no-code/mobile-apps/finix-checkout/taking-a-payment). Finix Checkout iOS app Checkout screen showing Sale and Authorization options ## More screen Tap **...** (More) in the navigation bar to access the following options: | Option | Description | | --- | --- | | **Manage Devices** | Set up and manage your Pax D135 card reader. For more information, see [Set Up the D135](/low-code-no-code/mobile-apps/finix-checkout/set-up-d135). | | **Payment Links** | Create and manage your payment links. For more information, see [Payment Links](/low-code-no-code/mobile-apps/finix-checkout/payment-links). | | **App Info** | View app version and your Finix account details, including your Application ID, Identity ID, and User ID. | | **Logout** | [Sign out](#logging-out) of the app. | Finix Checkout iOS app More screen showing Manage Devices, Payment Links, App Info, and Logout options ## Transactions Tap **Transactions** in the navigation bar to view a history of all transactions. Finix Checkout iOS app Transactions screen Tap one of the tabs at the top of the screen to filter by transaction type: | Tab | Description | | --- | --- | | **Payments** | Displays completed sales. | | **Authorizations** | Displays authorized holds on buyer funds. | | **Refunds** | Displays refunds issued on previous transactions. | Tap the filter icon to access additional filters, including **Amount**, **Buyer**, **Date Range**, **Description**, **State**, and **Payment Instrument**. Tap **Apply** to apply your filters. Finix Checkout iOS app Transactions advanced filter panel ## Buyers Tap **Buyers** in the navigation bar to add and manage the buyers associated with your Finix account. Finix Checkout iOS app Buyers screen showing a list of buyers ### Add a Buyer 1. Tap **+** in the top-right corner. 2. Fill out the buyer's details. 3. Tap **Add Buyer**. Finix Checkout iOS app Add Buyer form The buyer appears in your buyer list. When taking a payment from the Checkout screen, you can select this buyer to associate them with the transaction. ### Search for a Buyer Use the search bar at the top of the Buyers screen to search by first name, last name, or email address. ### Buyer details Tap a buyer from the list to open their **Buyer Details** page. From there, you can view the buyer's contact information, payment history, and saved payment instruments. The following actions are available: | Action | Description | | --- | --- | | **Edit** | Tap the pencil icon to update the buyer's details. | | **Take a Payment** | Tap **Take a Payment** to go to the Checkout screen with the buyer already associated with the transaction. | | **View in Dashboard** | Tap **...** to open the buyer's record in the Finix Dashboard. | Finix Checkout iOS app Buyer Details page showing contact information, payments, and payment instruments ## Logging out 1. Tap **...** (More) in the navigation bar. Finix Checkout iOS app More screen showing Manage Devices, Payment Links, App Info, and Logout options 1. Tap **Logout**. The next time you sign in, your credentials will be available to select so you don't have to re-enter them manually. Finix Checkout iOS app login screen showing previously saved credentials ## Next steps | Next Step | Description | | --- | --- | | [Set Up the D135](/low-code-no-code/mobile-apps/finix-checkout/set-up-d135) | Pair and connect a Pax D135 card reader to accept in-person payments by tapping, swiping, or dipping a card. | | [Take a Payment](/low-code-no-code/mobile-apps/finix-checkout/taking-a-payment) | Process a sale or authorization using the card reader, manual card entry, or a payment link. | | [Payment Links](/low-code-no-code/mobile-apps/finix-checkout/payment-links) | Create and share payment links so buyers can pay remotely from their own device. | --- # Finix Checkout App Source: https://docs.finix.com/low-code-no-code/mobile-apps/finix-checkout Finix Checkout App The Finix Checkout app lets you accept payments on the go. Using your iPhone or Android device, you can charge buyers through a connected [Pax D135](/guides/in-person-payments/select-your-device/pax-d135) card reader, enter card details manually, or create and share payment links. | Android | iOS | | --- | --- | | [Google Play](https://play.google.com/store/apps/details?id=com.finix.finixcheckout) | [App Store](https://apps.apple.com/us/app/finix-checkout/id6746730500) | ## Learn more Getting Started Learn how to sign in and navigate the Finix Checkout app. Set Up the D135 Learn how to pair and connect the Pax D135 card reader to the app. Take a Payment Learn how to process a sale or authorization using the card reader, manual entry, or a payment link. Payment Links Learn how to view, share, and manage payment links from the app. --- # Payment Links in Finix Checkout Source: https://docs.finix.com/low-code-no-code/mobile-apps/finix-checkout/payment-links You can manage payment links directly from Finix Checkout. This includes viewing existing payment links, reviewing transaction attempts, and sharing links with buyers. To create a payment link as part of taking a payment, see [Take a Payment — Payment Link](/low-code-no-code/mobile-apps/finix-checkout/taking-a-payment#payment-link). ## Access Payment Links 1. Tap **...** (More) in the navigation bar. Finix Checkout iOS app More screen showing Manage Devices, Payment Links, App Info, and Logout options 1. Tap **Payment Links**. - The **Payment Links** screen displays. ## Payment Links screen The Payment Links screen has two tabs: | Tab | Description | | --- | --- | | **Payment Links** | Lists all payment links you have created. Tap a payment link to view its details. | | **Transaction Attempts** | Lists all transaction attempts made using your payment links. Tap a transaction attempt to view its details. | Tap the **+** icon to [create a new payment link](#create-a-payment-link). Finix Checkout iOS app Payment Links screen showing the list of payment links and Transaction Attempts tab ## Create a Payment Link 1. From the **Payment Links** screen, tap **+**. 2. Fill out the form fields described below. 3. Tap **Create Link** to generate the link. Finix Checkout iOS app Create Payment Link form ### Payment Link form fields #### Name An internal label for the payment link. Not visible to buyers. #### Amount type | Type | Description | | --- | --- | | **Fixed** | The payment amount is predetermined and cannot be changed by the buyer. Use fixed amounts when you know the exact payment amount upfront. | | **Variable** | The buyer enters their own payment amount within optional minimum and maximum limits. Use variable amounts for donations, tips, or when the final amount isn't known at link creation. | #### Amount The transaction amount. Only available when **Amount Type** is set to **Fixed**. #### Link type | Type | Description | When to Use | | --- | --- | --- | | **One Time** | Single-use payment links can only be used once. After a buyer completes payment, the link is marked as completed and cannot accept additional payments. | Sending a payment request for a specific transaction; ensuring the link is only valid for one payment; tracking individual purchases tied to specific buyers. | | **Multi-Use** | Multiple-use payment links can accept unlimited payments. The link remains active until it expires or is manually deactivated. | Accepting recurring payments from multiple buyers; when you don't need to track individual buyers per transaction. | #### Transaction options A URL to your terms of service displayed on the payment page. Required for all payment links. #### Payment methods Select which payment methods buyers can use to complete payment: | Payment Method | Description | | --- | --- | | **Credit/Debit Card** | Accept Visa, Mastercard, American Express, and Discover cards. Supports USD and CAD. | | **Bank Account (ACH/EFT)** | Accept ACH Direct Debits (USA) and EFT payments (Canada). | | **Apple Pay** | Fast, secure checkout with tokenized payments and biometric authentication. Appears on supported Apple devices. | | **Google Pay** | Fast, secure checkout with tokenized payments. Appears on supported Android devices and Chrome browsers. | #### Customization options Configure branding options for the buyer-facing payment page: | Setting | Description | | --- | --- | | **Logo URL** | A link to your company logo image. Displayed in the payment page header. | | **Header Color** | The background color for the payment page header. | | **Button Background Color** | The background color for the payment button. | | **Button Text Color** | The text color for the payment button. | ## Payment Link details Tap a payment link from the **Payment Links** tab to open its details page. The details page shows information about the payment link, including any transaction attempts made using it. From the details page, you can share the link with your buyer using one of the following options: | Option | Description | | --- | --- | | **Share Link** | Tap to open the share sheet. From there, you can copy the payment link URL or share it through any app on your device (for example, Messages, Mail, or WhatsApp). | | **Share QR Code** | Tap to display a QR code the buyer can scan with their phone camera to access the payment page. You can also download the QR code image and share it through any app of your choice. | Finix Checkout iOS app Payment Link Details page Finix Checkout iOS app iOS share sheet for sharing a payment link Finix Checkout iOS app QR code display for sharing a payment link --- # Setting Up the D135 for Finix Checkout Source: https://docs.finix.com/low-code-no-code/mobile-apps/finix-checkout/set-up-d135 The [Pax D135](/guides/in-person-payments/select-your-device/pax-d135) is a card reader that works with the Finix Checkout iOS app to accept in-person payments. Buyers can pay by tapping, swiping, or dipping their card using the device's: - Contactless card reader - Magnetic stripe reader - IC/smart card (chip) reader To order a D135, contact your Finix point of contact. For an in-depth overview of the D135's features and hardware, refer to the [Pax D135 Quick Setup Guide](https://www.pax.us/support/documents/d135-quick-setup-guide/). ## Prerequisites Before pairing the D135 with your iPhone: - **Charge the device** - Connect the charging cable to the D135. The charging indicator flashes slowly while charging. When you unplug the cable and the indicator is solid green, the device is fully charged. - **Turn on the device** - Press and hold the button on the side of the D135 until it beeps and powers on. - **Enable Bluetooth on your device** - Finix Checkout connects to the D135 over Bluetooth. USB is not supported. ## Add the D135 1. Open the **Finix Checkout** app and tap **...** (More) in the navigation bar. Finix Checkout iOS app More screen showing Manage Devices, Payment Links, App Info, and Logout options 1. Tap **Manage Devices**. Finix Checkout iOS app Manage Devices screen 1. Tap the **+** icon in the top-right corner. - The **Add a Device** screen displays. Finix Checkout iOS app Add a Device screen with setup instructions 1. Follow the on-screen instructions to make sure the device is on, then tap **Next**. - A **Searching for Nearby Devices** screen displays listing nearby Bluetooth devices. Finix Checkout iOS app Searching for Nearby Devices screen listing available Bluetooth devices 1. Tap the device that matches the serial number (S/N) shown on your D135 or its packaging. 2. On the **Add a Device** screen, optionally update the device name and add a description, then tap **Add Device**. - A **Registering Device** message appears, followed by an **Activating Device** message. Finix Checkout iOS app Add a Device form with name and description fields Finix Checkout iOS app showing Activating Device message 1. When prompted with a Bluetooth pairing request on your iPhone, tap **Pair**. - A **Connecting to Device** message displays, followed by a **Setting up your device** screen. - You only need to complete this setup once. Finix Checkout iOS app Setting Up Your Device screen showing firmware update progress Finix Checkout iOS app Setting Up Your Device screen showing parameters update progress 1. When the device beeps, setup is complete and you are returned to the **Manage Devices** screen. Finix Checkout iOS app Manage Devices screen after successfully adding a device ## Connect the D135 After adding the D135, you need to connect it before taking payments. 1. From the **Manage Devices** screen, tap the device that matches your D135's S/N. - The **Device Details** screen displays. Finix Checkout iOS app Device Details screen showing device information and Connect button 1. Tap **Connect**. - A **Setting up your device** screen displays with a progress bar. 2. When complete, you are returned to the **Manage Devices** screen. The device displays a **Connected** status when the connection is successful. Finix Checkout iOS app Device Details screen showing a connected device Finix Checkout iOS app Manage Devices list showing device with Connected status You are now ready to [process payments using the D135](/low-code-no-code/mobile-apps/finix-checkout/taking-a-payment). ## Managing the D135 Tap a device from the **Manage Devices** screen to open its **Device Details** page. From there, you can: | Action | Description | | --- | --- | | **Connect / Disconnect** | If the device is disconnected, tap **Connect** to reconnect. If the device is connected, tap **Disconnect** to disconnect it. | | **Edit Details** | Tap **Edit Details** to update the device name or description. | | **Reset Device** | Tap **Reset Device** to factory reset the D135. After resetting, you will need to [add and connect the device](#add-the-d135) again. | | **View in Dashboard** | Tap **...** in the top-right corner to open the device's details page in the Finix Dashboard. | Finix Checkout iOS app Edit Device Details screen Finix Checkout iOS app Device Details screen showing option to open device in Finix Dashboard The **Device Details** page also shows the device name, type (PAX D135), serial number, connection status, creation date, and description. ## Next steps | Next Step | Description | | --- | --- | | [Take a Payment](/low-code-no-code/mobile-apps/finix-checkout/taking-a-payment) | Process a sale or authorization using the D135. | --- # Taking a Payment with Finix Checkout Source: https://docs.finix.com/low-code-no-code/mobile-apps/finix-checkout/taking-a-payment From the Checkout screen, you can process a **Sale** or **Authorization**. Sale is selected by default. - **Sale** - A one-step transaction that immediately charges the buyer. - **Authorization** - A two-step transaction that places a hold on funds, which you can later capture or void. Finix Checkout supports three ways to collect payment: | Method | Description | | --- | --- | | **Card Reader** | Collect payment using a paired [Pax D135](/low-code-no-code/mobile-apps/finix-checkout/set-up-d135) card reader. The buyer taps, swipes, or dips their card on the device. | | **Enter Card Manually** | Type the buyer's card details directly into the app. No device required. | | **Payment Link** | [Create a payment link and share it](/low-code-no-code/mobile-apps/finix-checkout/payment-links) with the buyer to pay from their own device. | ## Step 1: Enter transaction details 1. Tap **Checkout** in the navigation bar if you are not already on that screen. 2. Select the **Sale** or **Authorization** tab. 3. Enter the payment amount using the keypad. Finix Checkout iOS app Checkout screen with keypad for entering a payment amount 1. Tap **Next**. - The transaction details screen displays. 2. Optionally, tap **Add Description** to add a description for the transaction. 3. Optionally, tap **Add Buyer** to associate a buyer with the transaction. - Search for an existing buyer or tap **+** to create a new one. - Tap **Add Buyer** when done. Finix Checkout iOS app transaction details screen showing the Add Buyer option Finix Checkout iOS app buyer selection list when adding a buyer to a transaction Finix Checkout iOS app new buyer form Finix Checkout iOS app transaction details screen with a buyer added 1. Tap **Confirm and Pay**. - A screen displays asking how you would like to collect payment. Finix Checkout iOS app payment method selection screen showing Card Reader, Enter Card Manually, and Payment Link options ## Step 2: Collect payment Select the payment method that applies to your situation. Card Reader ### Prerequisites - The D135 is [set up and connected](/low-code-no-code/mobile-apps/finix-checkout/set-up-d135). ### Card Reader Steps 1. Tap **Use Card Reader**. - The app displays **Tap or Insert Card on Reader**, indicating the device is ready. - You can optionally connect to a different device. Finix Checkout iOS app showing Tap or Insert Card on Reader prompt 1. Have the buyer tap, insert, or swipe their card on the D135. - A processing screen displays while the transaction is being submitted. Finix Checkout iOS app processing screen while the D135 transaction is being submitted Enter Card Manually ### Manual Entry Steps 1. Tap **Enter Card Manually**. 2. Enter the buyer's card details. 3. Tap **Charge $X.XX**. - A processing screen displays while the transaction is being submitted. Payment Link ### Payment Link Steps 1. Tap **Create a Payment Link**. 2. If prompted, select a merchant from the list. - The **Create Payment Link** form displays. 3. Fill out the form fields. For field descriptions, see [Payment Link Form Fields](/low-code-no-code/mobile-apps/finix-checkout/payment-links#payment-link-form-fields). 4. Tap **Create** to generate the link. 5. Share the link with your buyer. For sharing options, see [Payment Links](/low-code-no-code/mobile-apps/finix-checkout/payment-links). ## Step 3: Transaction result After the transaction is submitted: - **Approved** - A **Sale Approved** or **Authorization Approved** screen displays. Choose to send a receipt by email, by text, or select **No Receipt**. Finix Checkout iOS app Sale Approved screen with receipt options - **Failed** - A **Failed Transaction** screen displays with the reason for the failure (for example, the buyer did not complete payment in time, or there was an issue with the card). Finix Checkout iOS app Failed Transaction screen showing the reason for failure Tap **Done** to return to the Checkout screen. --- # Accept payments with Tap to Pay on iPhone Source: https://docs.finix.com/low-code-no-code/mobile-apps/finix-checkout/tap-to-pay-on-iphone Tap to Pay on iPhone Tap to Pay on iPhone lets you accept in-person contactless payments using only your iPhone. No card reader or additional hardware is required. Buyers can pay with: - Contactless credit and debit cards. - Apple Pay, Google Pay, and other NFC-based digital wallets. Device compatibility Tap to Pay on iPhone is only supported on: - **OS** - iOS 18.1 or later. - **Phone** - iPhone XS or newer. - **Passcode** - Having passcode setup on iPhone is a requirement for Tap to Pay. Tap to Pay on iPhone is not available on iPad or Android devices. In the Finix Checkout app, Tap to Pay on iPhone is only available in the Production environment. Developers integrating the [Finix Tap to Pay on iPhone SDK](/ios/tap-to-pay) into their own app can test in Sandbox. ## Prerequisites Before taking a Tap to Pay on iPhone payment: - **Sign in to the Finix Checkout app** - For instructions, see [Getting Started](/low-code-no-code/mobile-apps/finix-checkout/getting-started). - **Use a compatible iPhone** - See the device compatibility requirements above. - **Have a stable internet connection** - Offline payments are not supported. If your phone case holds physical cards, remove them before taking a Tap to Pay payment to avoid accidentally charging your own card. ## Take a payment with Tap to Pay There is no setup required for Tap to Pay. You select it as the payment method when taking a payment. 1. From the **Checkout** screen, enter the transaction details and tap **Confirm and Pay**. - A screen displays asking how you would like to collect payment. Finix Checkout iOS app payment method selection screen showing the Tap to Pay option 1. Select **Tap to Pay on iPhone**. - The Tap to Pay on iPhone screen displays, indicating your iPhone is ready to accept a payment. - If it is your first time using Tap to Pay on iPhone, you are prompted to enable it. Finix Checkout iOS app Tap to Pay screen ready to accept a contactless payment 1. Have the buyer hold their contactless card or device near the top of your iPhone, next to the contactless symbol on screen. - A processing screen displays while the transaction is being submitted. Finix Checkout iOS app processing screen while the Tap to Pay transaction is being submitted ## Transaction result After the transaction is submitted: - **Approved** - A **Sale Approved** or **Authorization Approved** screen displays. Choose to send a receipt by email, by text, or select **No Receipt**. Finix Checkout iOS app Sale Approved screen with receipt options - **Failed** - A **Failed Transaction** screen displays with the reason for the failure (for example, the buyer did not complete payment in time, or there was an issue with the card). Finix Checkout iOS app Failed Transaction screen showing the reason for failure ## Security best practices To make sure Tap to Pay payments are processed securely: - **Keep control of your iPhone** - Do not hand your iPhone to the buyer. Have them hold out their card or NFC device, or hand it to you, so you can tap it on your phone. - **Wait for confirmation** - The payment is not complete until the approved screen displays. If the transaction fails, ask the buyer to tap their card or device again. --- # Convenience Fees for Payment Links Source: https://docs.finix.com/low-code-no-code/payment-links/buyer-fees/convenience-fees Convenience fees are buyer charges for providing an alternative payment channel (e.g., online or by phone). They are only supported for **fixed** payment links. Convenience fees must be a **flat amount** (not a percentage) and cannot be applied when bank account (ACH) is the only permitted payment method. For more details on requirements, see [Convenience Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/convenience-fees). ## 1. Navigate to Payment Links 1. In the Dashboard, navigate to **Tools** in the left navigation. 2. Click **Payment Links**. 3. Click **Create Payment Link**. Create Payment Link The creation form displays with a live preview that updates as you fill out each section. Payment link Creation Form ## 2. Fill out basic form information 1. Fill out the [Basic Information](/low-code-no-code/payment-links/quickstart-dashboard#basic-information) section of the form. 2. Fill out the [Product or Service Information](/low-code-no-code/payment-links/quickstart-dashboard#product-or-service-information) section of the form. ## 3. Add a convenience fee in transaction options 1. Under **Transaction Options**, enter a **Terms of Service URL** (required for all payment links). 2. Expand **Additional Transaction Options**. 3. Under **Buyer Fee**, select **Convenience Fee**. 4. Enter a flat dollar amount. - The convenience fee amount must be the same across all transactions. - The convenience fee amount displays in the buyer preview. View other [Transaction Options](/low-code-no-code/payment-links/quickstart-dashboard#transaction-options) available. ## 4. Create and share the Payment Link Complete the remaining sections of the form: - [Advanced Settings](/low-code-no-code/payment-links/quickstart-dashboard#advanced-settings) - [Customize Branding](/low-code-no-code/payment-links/customize-branding) When done, click **Create Payment Link** to finalize. You'll see a confirmation and can view the payment link details page. From the payment link details page, you can [share the payment link](/low-code-no-code/payment-links/sharing-payment-links) with buyers. ## What Buyers see Buyers will see the convenience fee amount added to their total. Payment Link Buyer Page - Convenience Fee --- # Buyer Fees for Payment Links Source: https://docs.finix.com/low-code-no-code/payment-links/buyer-fees You can add buyer fees to payment links to cover the cost of processing payments or accepting cards. ## Supported Buyer Fees Payment Links support two types of buyer fees. Only one can be applied per transaction. | Fee Type | `FIXED` Links | `VARIABLE` Links | | --- | --- | --- | | Surcharge | Yes | Yes | | Convenience | Yes | No | Only one buyer fee can be applied per transaction. - **Surcharge Fees**: A fee to offset credit card processing costs. Surcharges apply only to credit cards, not debit or prepaid, cannot exceed 3% for USA merchants or 2.5% for Canadian merchants, and are not allowed in all states. Merchants must be enabled by Finix to process surcharges. - **Convenience Fees**: A fee for providing an alternative payment channel (e.g., online or by phone). Must be a flat amount. Note Surcharges are not supported for ACH transactions. For more details on buyer fees and requirements, see [Buyer Charges](/guides/online-payments/payment-features/buyer-charges). ## Learn more Surcharge Fees Add surcharge fees to payment links to cover payment processing costs. Convenience Fees Add flat-rate convenience fees to payment links. --- # Surcharge Fees for Payment Links Source: https://docs.finix.com/low-code-no-code/payment-links/buyer-fees/surcharge-fees Surcharge fees are available to sellers to help cover the cost of processing payments in any environment. Surcharge fees must be a **percentage** (not a flat amount) less than 3% for USA merchants and 2.5% for Canadian merchants. Surcharges cannot be applied when bank account (ACH) is the only permitted payment method. For more details on requirements, see [Surcharge Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/surcharge-fees). ## 1. Navigate to Payment Links 1. In the Dashboard, navigate to **Tools** in the left navigation. 2. Click **Payment Links**. 3. Click **Create Payment Link**. Create Payment Link The creation form displays with a live preview that updates as you fill out each section. Payment link Creation Form ## 2. Fill out basic form information 1. Fill out the [Basic Information](/low-code-no-code/payment-links/quickstart-dashboard#basic-information) section of the form. 2. Fill out the [Product or Service Information](/low-code-no-code/payment-links/quickstart-dashboard#product-or-service-information) section of the form. ## 3. Add a surcharge fee in transaction options 1. Under **Transaction Options**, enter a **Terms of Service URL** (required for all payment links). 2. Expand **Additional Transaction Options**. 3. Under **Buyer Fee**, select **Surcharge Fee Percentage**. 4. Enter a value up to 3% for USA merchants or 2.5% for Canadian merchants. - In the buyer preview, a notice will state that a surcharge applies and show the exact amount. This amount will also appear on the buyer payment page. View other [Transaction Options](/low-code-no-code/payment-links/quickstart-dashboard#transaction-options) available. ## 4. Create and share the Payment Link Complete the remaining sections of the form: - [Advanced Settings](/low-code-no-code/payment-links/quickstart-dashboard#advanced-settings) - [Customize Branding](/low-code-no-code/payment-links/customize-branding) When done, click **Create Payment Link** to finalize. You'll see a confirmation and can view the payment link details page. From the payment link details page, you can [share the payment link](/low-code-no-code/payment-links/sharing-payment-links) with buyers. ## What Buyers see Buyers will see a notice that the payment will be surcharged and the exact amount. Payment Link Buyer Page - Surcharge --- # Convenience Fees for Virtual Terminal Transactions Source: https://docs.finix.com/low-code-no-code/virtual-terminal/buyer-fees/convenience-fees Convenience fees are buyer charges for providing a more convenient payment channel. They can only be charged when the seller provides a payment method (usually online or phone) different from their standard channel (historically mail or in-person). Convenience fees must be a **flat amount** (not a percentage). For more details on requirements, see [Convenience Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/convenience-fees). ## 1. Navigate to the Virtual Terminal ### Option 1: From the Payments List Page 1. From the left navigation, click **Transactions** > **Payments**. 2. Click **Take a Payment**. Payments List Page - Take a Payment ### Option 2: From the Virtual Terminal Page From the left navigation, click **Tools** > **Virtual Terminal**. Virtual Terminal Page ## 2. Fill out basic form information 1. Select whether to process a **Sale** or **Authorization** using the Virtual Terminal. 2. Under **Transaction Details**, enter a **Total Purchase Amount** and a **Description**. ## 3. Add a convenience fee in transaction details 1. Under **Transaction Details**, click +Add Buyer Fee to add a buyer fee to the transaction. 2. Select **Convenience Fee Amount**. 3. Enter a flat dollar amount. View other [Transaction Options](/low-code-no-code/virtual-terminal/quickstart#transaction-details) available. ## 4. Process the transaction 1. Complete the remaining sections of the form. 2. Click **Review Transaction** if the payment details look correct. 3. Click **Process Payment** to complete the transaction. - After submitting, a confirmation message appears with a **Payment ID**. ## 5. Review the payment confirmation 1. In the confirmation message after processing the payment, click the **Payment ID** to view its details. - The payment or authorization details page displays. 2. The **Convenience Fee** is displayed under the **Payment Details** section. --- # Buyer Fees for Virtual Terminal Transactions Source: https://docs.finix.com/low-code-no-code/virtual-terminal/buyer-fees You can add buyer fees to transactions processed through the Virtual Terminal to cover the cost of processing payments or accepting cards. ## Supported Buyer Fees The Virtual Terminal supports two types of buyer fees: Only one buyer fee can be applied per transaction. - **Surcharge Fees**: A fee to offset credit card processing costs. Surcharges apply only to credit cards, not debit or prepaid, cannot exceed 3% for USA merchants or 2.5% for Canadian merchants, and are not allowed in all states. Merchants must be enabled by Finix to process surcharges. - **Convenience Fees**: A fee for providing an alternative payment channel (e.g., online or by phone). Must be a flat amount. Note Surcharges are not supported for ACH transactions. For more details on buyer fees and requirements, see [Buyer Charges](/guides/online-payments/payment-features/buyer-charges). ## Learn more Surcharge Fees Add surcharge fees to Virtual Terminal transactions to cover payment processing costs. Convenience Fees Add flat-rate convenience fees to Virtual Terminal transactions. --- # Surcharge Fees for Virtual Terminal Transactions Source: https://docs.finix.com/low-code-no-code/virtual-terminal/buyer-fees/surcharge-fees Surcharge fees are available to sellers to help cover the cost of processing payments in any environment. Surcharge fees must be a **percentage** (not a flat amount) less than 3%. For more details on requirements, see [Surcharge Fees](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/surcharge-fees). ## 1. Navigate to the Virtual Terminal ### Option 1: From the Payments List Page 1. From the left navigation, click **Transactions** > **Payments**. 2. Click **Take a Payment**. Payments List Page - Take a Payment ### Option 2: From the Virtual Terminal Page From the left navigation, click **Tools** > **Virtual Terminal**. Virtual Terminal Page ## 2. Fill out basic form information 1. Select whether to process a **Sale** or **Authorization** using the Virtual Terminal. 2. Under **Transaction Details**, enter a **Total Purchase Amount** and a **Description**. ## 3. Add a surcharge fee in transaction details 1. Under **Transaction Details**, click **+Add Buyer Fee** to add a buyer fee to the transaction. 2. Select **Surcharge Fee Amount**. 3. Enter a value up to 3%. View other [Transaction Options](/low-code-no-code/virtual-terminal/quickstart#transaction-details) available. ## 4. Process the transaction 1. Complete the remaining sections of the form. 2. Click **Review Transaction** if the payment details look correct. 3. Click **Process Payment** to complete the transaction. - After submitting, a confirmation message appears with a Payment ID. ## 5. Review the payment confirmation 1. In the confirmation message after processing the payment, click the **Payment ID** to view its details. - The payment or authorization details page displays. 2. The **Surcharge Fee** is displayed under the **Payment Details** section. --- # Developers Source: https://docs.finix.com/additional-resources/developers Learn about the additional resources Finix has available to help Developers build integrations with Finix. Seller Payouts Hero Finix offers many features and tools to help developers integrate into Finix's platform. We encourage you to review every article to ensure you take advantage of every resource that is available to developers. ## Learn more Webhooks Integrate into Finix's webhooks to get notified when resources change Testing your Integration Test your integration for specific errors and responses. Errors Learn about the different errors that can get returned and how to handle them. --- # API Keys Source: https://docs.finix.com/additional-resources/developers/authentication-and-api-basics/api-keys Learn how to manage your Finix API keys and submit an authenticated request. Finix API requests are authenticated with API Keys. Finix uses HTTP Basic Authentication with a `username:password` combination. You can get API Keys for the Sandbox and Live environments from the Finix Dashboard. ## Creating API keys To create an API Key: 1. Navigate to **Developers > API Keys** in the Finix dashboard. 2. Click **Create API Key** and enter a **Display Name** (can be anything). 3. Save the credentials somewhere secure. Store API Keys Securely Save your password somewhere secure. You **cannot** re-copy the password, but you can always create another API Key. API Keys are sensitive data and must be treated like passwords. Store them securely and only share them on an as-needed basis. Developers API Keys Developers API Keys API Environments API Keys are specific to either the Sandbox or Live environments, depending on whether you get them from the Sandbox or Live Dashboard. Sandbox Keys cannot be used in the Live Environment and vice-versa. [Learn more here](/api/section/environments). ## API authentication Finix authenticates requests with [HTTP Basic Authentication (RFC7617)](https://datatracker.ietf.org/doc/html/rfc7617). ### Create authentication header All your requests will need to include the Base64-encoded Authentication header, which you can generate using your API Key `username` and `password`. Basic Authentication look like `Authorization: Basic `. To create the Authentication header: 1. Combine the `username` and `password` with a colon (e.g., `USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e`) 2. Base64-encode the string (e.g., `VVNzUmhzSFlaR0JQblF3OENCeUp5RVFXOjhhMTRjMmY5LWQ5NGItNGM3Mi04ZjVjLWE2MjkwOGU1YjMwZQ==`) 3. Add the value to the Authorization Header with the Basic scheme (e.g, `Authorization: Basic` `VVNzUmhzSFlaR0JQblF3OENCeUp5RVFXOjhhMTRjMmY5LWQ5NGItNGM3Mi04ZjVjLWE2MjkwOGU1YjMwZQ==`) ## API key permission Levels When you sign up for Finix, you get a pair of credentials that you use to set up your Finix Dashboard and/or create requests with Finix's API. Due to the sensitive nature of these credentials, access is tightly controlled. Users have three potential roles in Finix, which provide different levels of access: | Role | Access | | --- | --- | | `ROLE_PLATFORM` | - Access all Applications and Merchant data (Finix Core only). - Gain access to every permission for any Application created with the `ROLE_PLATFORM` credentials (e.g., creating Transfers or Payment Instruments). - Users can create Applications, Merchants, and assign `ROLE_PARTNER` and `ROLE_MERCHANT` credentials. - `ROLE_PLATFORM` credentials provide Finix's highest level of access, allowing users to see and manage almost everything. | | `ROLE_PARTNER` | - Access data for one Application and its Merchant data (e.g., Merchants created under the Application). - Gain access to `ROLE_MERCHANT` permissions for any Merchant created under the Application (e.g., creating Transfers or Payment Instruments). - Users can create Merchants and assign `ROLE_MERCHANT` credentials. - `ROLE_PARTNER` credentials offer the highest level of access available to Finix Flex customers, enabling users to investigate issues that may arise when processing payments for Merchants. | | `ROLE_MERCHANT` | - Access data for one Merchant. - Use Finix's API freely for a single Merchant (e.g., creating Transfers or Payment Instruments). - `ROLE_MERCHANT` credentials are intended for your sellers—Merchants who use your platform to connect with buyers. | Finix `ROLE_PLATFORM` credentials have the highest levels of access and offer the most customization. However, more developer work is involved, and `ROLE_PLATFORM` users are held liable for more responsibilities like approving Settlements. - Finix Core customers receive `ROLE_PLATFORM` credentials. - Finix Flex customers receive `ROLE_PARTNER` credentials. Should you have any questions about the credentials you receive, reach out to your Finix point of contact or Finix Support. --- # API Logs Source: https://docs.finix.com/additional-resources/developers/authentication-and-api-basics/api-logs When you send an API request, Finix logs the request and displays it in the Finix Dashboard. This helps your team review the request for debugging, integration checks, and request tracking. The API Logs capture historical request data for easy access. ## Viewing API logs To view API Logs in the Finix Dashboard, navigate to **Developer > API Logs**. Click on an individual log entry to see detailed information, including: - ID of the `User` who created the request - Timestamp of when the request was sent - Request and response headers - Body of the request and response API Logs Overview API Logs Entry ## Filtering API logs You can filter API Logs in the Dashboard using the fields below: | Field | Definition | Example(s) | | --- | --- | --- | | Entity ID | Finix ID of the resource the API request was performed on (e.g., Identity fetched) | `IDfgaAfZqQL4BWq4YyYj32mo`, `TR8dfiTB9PGfQBGNABnzsfFL` | | HTTP Method | HTTP Method used for the request | `POST`, `PUT`, `GET`, `DELETE` | | HTTP Status | HTTP Status Code of the response | `200`, `201`, `401`, `500` | | Request ID | X-Request-ID response header | `85894eaece9fe1b8abbc3193674dc11` | | Requesting User | Finix User ID from requesting user | `US8JtpvGARqs1ikkoWPnTYfx` | | Time range | Dates to return API Logs from | December 01 to 05 2025 | API Logs Filters API Logs Filters Used ## Sensitive data Sensitive fields in requests and responses are masked. This includes: - Authorization headers - Tax IDs - Sensitive payment data Masking is performed before the data is stored and cannot be reversed or recovered. ## Log availability Keep in mind the following about API Logs: - Only direct API requests are logged. Actions from within the Dashboard are not recorded in the logs. - Logs are only retained for 40 days. - In the Live Environment, **successful** `GET` request responses may be shown as null or empty. - Logs do not include data for file uploads/downloads, such as disputes. While there's no strict guarantee on log timing, under normal conditions, logs should appear in near real-time (within a few seconds). --- # Idempotent Request Source: https://docs.finix.com/additional-resources/developers/authentication-and-api-basics/idempotent-request Finix recommends including an `idempotency_id` field on specific API resources to ensure that each request is processed only once. This is especially useful in scenarios where a checkout page hangs and users may retry the request. You can generate a unique ID and include it in your request payload. Each `idempotency_id` must be unique per request. If the same `idempotency_id` is submitted again, Finix returns a `422 Unprocessable Entity` error. Using `idempotency_id` protects against duplicate authorizations or transfers. ## Implementing idempotent requests Follow the steps below to generate, include, and process an `idempotency_id` in your API requests. ### Step 1: Generate a unique identifier You should generate a unique string to use as the `idempotency_id`. Finix recommends using a UUID (Universally Unique Identifier), a 128-bit value represented as a 36-character string that uniquely identifies information across systems. Each API request should include its own distinct `idempotency_id`. ### Step 2: Include the ID in the request body Pass the generated `idempotency_id` as part of your request payload. ```json Sample Request Payload { "amount": 1000, "currency": "USD", "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "source": "PI6iQcTtJNCS8GZAVKYi5Ueb", "idempotency_id": "7f1b4c82-9e3a-4e5b-93b0-2ad1c6c47a11" } ``` ### Step 3: Finix processes the request The first time the `idempotency_id` is received for the given endpoint, the request is processed. If the same `idempotency_id` is submitted again, Finix returns a `422 Unprocessable Entity` error. ## Example idempotent requests The following examples show how to use `idempotency_id` in Finix API requests and responses. Sample IDs are for Demonstration The `idempotency_id` values shown in these examples are for demonstration purposes. In your environment, each request must include a new, unique `idempotency_id`, as API calls with the example IDs will not be valid or testable. ### Endpoints supporting idempotency | Endpoint | Description | | --- | --- | | `POST /transfers` | Create a new transfer. | | `POST /authorizations` | Create a new authorization. | | `POST /transfers/{id}/reversals` | Create a reversal for a specific transfer. | ### Online Sale Include an `idempotency_id` when creating an online sale. ```shell Example Transfer Request curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/transfers \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "amount": 1000000, "currency": "USD", "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "source": "PI6iQcTtJNCS8GZAVKYi5Ueb", "idempotency_id": "0e2e97c0-8b4c-4c52-90c5-c13a3c69f6e0", <--- sample value "tags": { "test": "Sale" } }' ``` ```json Example Transfer Response { "id": "TRjiQJ5gRfuVtccFmtn2HYuT", "created_at": "2025-09-26T16:05:10.85Z", "updated_at": "2025-09-26T16:05:10.85Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 1000000, "amount_requested": 1000000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPmtT4MYmiAs1qjLjneQmk4d", "idempotency_id": "0e2e97c0-8b4c-4c52-90c5-c13a3c69f6e0", "merchant": "MUwfZPNW3r4EqLMzwgr6txw4", "merchant_identity": "IDhC29dXMAkbmr1aBpS91Hpx", "messages": [], "network_details": { "brand": "VISA", "authorization_code": "840735", "acquirer_reference_number": null }, "operation_key": "CARD_NOT_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": "2025-09-27T16:05:11.42Z", "receipt_last_printed_at": null, "security_code_verification": "MATCHED", "source": "PI6iQcTtJNCS8GZAVKYi5Ueb", "split_transfers": [], "state": "SUCCEEDED", "statement_descriptor": "FLX*FINIX FLOWERS", "subtype": "API", "supplemental_fee": null, "tags": { "test": "Sale" }, "tip_amount": null, "trace_id": "a6c5835b-d855-4961-8070-caeaa8e89cbb", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRjiQJ5gRfuVtccFmtn2HYuT" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDhC29dXMAkbmr1aBpS91Hpx" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRjiQJ5gRfuVtccFmtn2HYuT/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRjiQJ5gRfuVtccFmtn2HYuT/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TRjiQJ5gRfuVtccFmtn2HYuT/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRjiQJ5gRfuVtccFmtn2HYuT/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6iQcTtJNCS8GZAVKYi5Ueb" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d" } } } ``` ### In-Person Sale Include an `idempotency_id` when creating an in-person sale. ```shell Example Transfer Request curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/transfers \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "amount": 1500, "currency": "USD", "device": "DVhXqP9onzhA7sxheKXoBc3J", "idempotency_id": "7f1b4c82-9e3a-4e5b-93b0-2ad1c6c47a11", <--- sample value "operation_key": "CARD_PRESENT_SALE" }' ``` ```json Example Transfer Response { "id": "TRuuwYpzXQsxNRY77CVvcJJp", "created_at": "2025-07-25T18:19:28.11Z", "updated_at": "2025-07-25T18:19:28.11Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 1500, "amount_requested": 1500, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "card_present_details": { "emv_data": { "application_identifier": null, "application_label": null, "application_preferred_name": null, "application_transaction_counter": null, "cryptogram": null, "issuer_code_table_index": null, "network_emv_response": null, "pin_verified": false, "tags": null }, "masked_account_number": null, "name": null, "brand": null, "entry_mode": "UNKNOWN", "payment_type": null, "approval_code": null, "digital_signature_file_id": null }, "currency": "USD", "destination": null, "device": "DVhXqP9onzhA7sxheKXoBc3J", "externally_funded": "UNKNOWN", "failure_code": "DEVICE_UNREACHABLE", "failure_message": "The API request could not communicate with the device. Please try again.", "fee": 0, "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj", "idempotency_id": "7f1b4c82-9e3a-4e5b-93b0-2ad1c6c47a11", "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "messages": ["RAW MESSAGE"], "operation_key": "CARD_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": "PI9hTsZF8ms387bxNv5FmPyU", "split_transfers": [], "state": "FAILED", "statement_descriptor": "FLX*FINIX FLOWERS", "subtype": "API", "supplemental_fee": null, "tags": {}, "tip_amount": null, "trace_id": "70bbc88e-83db-4efe-a4ab-eb54cd6da5fe", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRuuwYpzXQsxNRY77CVvcJJp" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/transfers/ID6UfSm1d4WPiWgLYmbyeo3H" }, "device": { "href": "https://finix.sandbox-payments-api.com/devices/DVhXqP9onzhA7sxheKXoBc3J" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRuuwYpzXQsxNRY77CVvcJJp/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRuuwYpzXQsxNRY77CVvcJJp/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TRuuwYpzXQsxNRY77CVvcJJp/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRuuwYpzXQsxNRY77CVvcJJp/disputes" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj" } } } ``` ### Authorization Include an `idempotency_id` when creating an authorization. ```shell Example Authorization Request curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/authorizations \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "amount": 12000, "currency": "USD", "merchant": "MUsVtN9pH65nGw61H7Nv8Apo", "source": "PIkxmtueemLD6dN9ZoWGHT44", "idempotency_id": "d4a2f1e7-63b8-4c90-8b5e-7b91c2c3e215", <--- sample value "tags": { "order_number": "21DFASJSAKAS" } }' ``` ```json Example Authorization Response { "id": "AUsJgTPyNKUKbkTk4mzq2aoM", "created_at": "2025-10-27T15:55:36.29Z", "updated_at": "2025-10-27T15:55:36.29Z", "3ds_redirect_url": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 12000, "amount_requested": 12000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "expires_at": "2025-11-03T15:55:36.29Z", "failure_code": null, "failure_message": null, "idempotency_id": "d4a2f1e7-63b8-4c90-8b5e-7b91c2c3e215", "ip_address_details": null, "is_void": false, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "messages": [], "raw": null, "receipt_last_printed_at": null, "security_code_verification": "MATCHED", "source": "PIkxmtueemLD6dN9ZoWGHT44", "state": "SUCCEEDED", "supplemental_fee": null, "tags": { "order_number": "21DFASJSAKAS" }, "trace_id": "0504c0cc-7665-4555-90c3-c460330acf2e", "transfer": null, "void_state": "UNATTEMPTED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUsJgTPyNKUKbkTk4mzq2aoM" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" } } } ``` ### Refund Include an `idempotency_id` when creating a reversal transfer. ```shell Example Refund Request curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/transfers/TRnErBfrHLgdAi3BqAkWLN27/reversals \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "refund_amount": 1000000, "idempotency_id": "3f9c8a41-b0e7-4e27-9f6c-0d2f3a9e52b8", <--- sample value "tags": { "test": "Refund" } }' ``` ```json Example Refund Response { "id": "TRi87Kgx6NdZFXkQtLXQ9NMJ", "created_at": "2025-08-05T17:22:50.40Z", "updated_at": "2025-08-05T17:22:50.44Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 1000000, "amount_requested": 1000000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "destination": "PImXAVgkKVshKWWHUk4xXbve", "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPmtT4MYmiAs1qjLjneQmk4d", "idempotency_id": "3f9c8a41-b0e7-4e27-9f6c-0d2f3a9e52b8", "merchant": "MUcgYZswyRfqSSbvMsxuaHxZ", "merchant_identity": "IDgCoio3FfaMSKPNM35atXPU", "messages": [], "operation_key": "CARD_NOT_PRESENT_REFUND", "parent_transfer": "TRjAnCNNSxDCW8GDsxYobHHe", "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": null, "split_transfers": [], "state": "PENDING", "statement_descriptor": "FLX*FINIX FLOWERS", "subtype": "API", "supplemental_fee": null, "tags": { "test": "Refund" }, "tip_amount": null, "trace_id": "d1cb23da-3368-473d-bf8e-68d8e093839b", "type": "REVERSAL", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRi87Kgx6NdZFXkQtLXQ9NMJ" }, "parent": { "href": "https://finix.sandbox-payments-api.com/transfers/TRjAnCNNSxDCW8GDsxYobHHe" }, "destination": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImXAVgkKVshKWWHUk4xXbve" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDgCoio3FfaMSKPNM35atXPU" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRi87Kgx6NdZFXkQtLXQ9NMJ/payment_instruments" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d" } } } ``` --- # Authentication & API Basics Source: https://docs.finix.com/additional-resources/developers/authentication-and-api-basics Integrating into Finix's API is easy. Use the guides below to learn about key API topics such as credentials, logs, and rate limits. ## Learn more API Keys Learn how to manage your Finix API keys and submit an authenticated request. API Logs Learn about reviewing API Logs on the Finix Dashboard. Pagination Learn how to page through lists and other API responses. Rate Limits Learn about the Finix API's rate limits and how to work with them. Versioning Learn how Finix applies versioning to our API. --- # Pagination Source: https://docs.finix.com/additional-resources/developers/authentication-and-api-basics/pagination Learn how to paginate through Finix's APIs. ## Overview Finix's API supports cursor based pagination for listing resources. All api requests should include the `Finix-Version: 2022-02-01` header. All API responses are limited to 100 results per page. ## Cursor-Based pagination ### Basic usage To use cursor-based pagination: 1. Include the version header: `Finix-Version: 2022-02-01` 2. Specify the number of items using the `limit` parameter 3. Use the returned `next_cursor` for subsequent requests ```shell Cursor Pagination Request curl "https://finix.sandbox-payments-api.com/transfers?limit=10" \ -H "Finix-Version: 2022-02-01" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e ``` In the response, you will see the `limit` defined in the request, as well as the `next_cursor`. ```json Cursor Pagination Response { "_embedded": { "transfers": [...] }, "_links": {...}, "page": { "limit": 10, "next_cursor": "TRnasXQ5AmjsLnPMwnme7TL4" } } ``` ### Navigation #### Forward navigation To get results ***after*** `next_cursor`, pass in `after_cursor: {{next_cursor}}`: ```shell Cursor Pagination Forward Navigation curl "https://finix.sandbox-payments-api.com/transfers?limit=10&after_cursor=TRnasXQ5AmjsLnPMwnme7TL4" \ -H "Finix-Version: 2022-02-01" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e ``` #### Backward navigation To get results **_before _** `next_cursor`, pass in `before_cursor: {{next_cursor}}`: ```shell Cursor Pagination Backward Navigation curl "https://finix.sandbox-payments-api.com/transfers?limit=10&before_cursor=TRnasXQ5AmjsLnPMwnme7TL4" \ -H "Finix-Version: 2022-02-01" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e ``` ### End of results When `next_cursor` is `null`, there are no more results available. ### Example: Listing Transfers Here's a complete example showing how to fetch and page through transfers: ```shell Fetching first three Transfers curl "https://finix.sandbox-payments-api.com/transfers?limit=3" \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e ``` ```json First three Transfers { "_embedded": { "transfers": [ { "id": "TRtLhSEAHak7isKjZu9x7Gjh", ... } }, { "id": "TR2fXt8wHuHxjVPZ1MvrnSU8", ... }, { "id": "TRuzk139AayVqe1K9eyz18q9", ... } ] }, "_links": {...}, "page": { "limit": 3, "next_cursor": "TRuzk139AayVqe1K9eyz18q9" } } ``` To get the next page: ```shell Next three Transfers curl "https://finix.sandbox-payments-api.com/transfers?limit=3&after_cursor=TRuzk139AayVqe1K9eyz18q9" \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e ``` To get the previous page: ```shell Previous three Transfers curl "https://finix.sandbox-payments-api.com/transfers?limit=3&before_cursor=TRuzk139AayVqe1K9eyz18q9" \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e ``` ## Filter support For available filters, consult the [API documentation](/api) for each endpoint's specific supported filters. --- # Rate Limits Source: https://docs.finix.com/additional-resources/developers/authentication-and-api-basics/rate-limits As you develop your integration, it's important to understand Finix API's rate limits and ensure your systems don't programmatically create excessive requests. In simplest terms, rate limits are the maximum number of API requests you can make in a given time period. Rate limits help ensure the stability and performance of an API. By controlling the number of requests your application makes, you can avoid hitting these limits and keep the performance of your application consistent and stable. Custom Rate Limits Finix can customize limits to enable high-traffic applications (or prevent abuse). If your requests are being rate-limited, reach out to your Finix point-of-contact or [email Finix Support](mailto:support@finix.com). ## Rate limits ### Live environment These rate limits apply to our Live Environment (i.e., production). | Operation | Limit | | --- | --- | | Writes | 100 per second | | Reads | 100 per second | ### Sandbox environment We also have Sandbox Rate Limits that apply for Writes and Reads. These rate limits are subject to change and are not publicly documented at this time. ## Exceeding rate limits Rate-limited requests return `429` HTTP Errors. If you receive a `429`, your application will be unable to get the data it needs from responses to process transactions. See [Handling Rate Limits](#handling-rate-limits) for tips on how to develop your application to work within these limits and handle 429 HTTP Errors. If you suddenly see a rising number of requests get rate limited, please reach out to [Finix Support](mailto:support@finix.com). ## Handling rate limits To avoid running into rate limits, optimize your application so it makes the least amount of requests needed. By optimizing your code and monitoring usage, you can develop an application that's both efficient and effective. Here are some strategies you can use to avoid hitting rate limits. ### Exponential backoff To handle `429` errors, retry requests using an ***exponential backoff strategy***. Exponential backoff gradually increases the time between retries until your requests are no longer being rate limited. ### Cache response Caching responses can reduce the number of requests your application needs to make to process transactions. ### Error handling If your application exceeds rate limits, make sure you have error handling in place to catch the 429 HTTP Error and handle it appropriately. Error handling can include retrying the request later or displaying an error message to the user. ### Webhooks Instead of using `GET` requests to retrieve data, [integrate into webhooks](/additional-resources/developers/webhooks) to be programmatically alerted of responses and changes to resources you manage. --- # Versioning Source: https://docs.finix.com/additional-resources/developers/authentication-and-api-basics/versioning Learn how Finix applies versioning to our API. As Finix improves our products and features, we'll make changes to our APIs. When breaking changes are made to Finix's API, a new dated version is released. A breaking change is a change in Finix's API that makes your current integration with Finix incompatible. More commonly, we make [non-breaking changes](#non-breaking-changes) that don't result in a new released version. The API version your requests use controls how API responses and webhooks behave (for example, the values you see in responses, the parameters you're sending in requests, etc.). When a breaking change is introduced to Finix's API, a new version is released to put the changes behind. To avoid compatibility issues and take advantage of all the improvements Finix introduces, we recommend always using the latest version of the Finix API. To use the latest version of Finix's API, you need to include the following versioning header, including the date, with **every request.** The header needs to include the **exact** versioning date. If there are any changes or mistakes in the date, requests will default to the base version of Finix's API. ```json curl "https://finix.sandbox-payments-api.com/transfers?limit=3&after_cursor=TRt2F1j2ST3ijbsmPVXB6Ztf" \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ ``` ## API changelog Here are the changes and updates in the different versions of Finix's API. Include the specified header in your requests, to use that version of Finix's API. ### 2022-02-01 - We've improved the performance of querying endpoints by introducing cursor-based pagination to Finix's API. For details on how to migrate your requests to cursor-based navigation, see [Migrating to Cursor Pagination](/additional-resources/developers/authentication-and-api-basics/pagination#migration-guide). ### 2018-01-01 - If you don't include a version header and date, your requests will default to this base version of Finix's API. ## Non-breaking changes A non-breaking change is a backward-compatible change in Finix's API that allows your integration to continue using Finix's API without any changes on your end. Non-breaking changes include: - Adding new resources. - Adding new enum values. - Adding optional fields to requests. - Adding new fields to responses. - Changing the length and format of ID fields. - Finix's ID fields will never exceed 255 characters. --- # Error Codes Source: https://docs.finix.com/additional-resources/developers/implementation-and-testing/error-codes This guide explains the error codes Finix's API can return. ## Error code overview Finix uses standard HTTP status codes to indicate the outcome of API requests: - **`2xx` (Successful):** Indicates the request was processed successfully. - **`4xx` / `5xx` (Failed):** Indicates the request failed due to client-side or server-side errors. ### Testing responses You can simulate specific responses and errors for `Transfers` and `Authorizations` by following [this guide](/additional-resources/developers/implementation-and-testing/testing-your-integration/). ### Response times API responses are typically returned in under one second. However, factors such as communication delays with card networks and processors can increase response times. Card-Present Transaction Latency For card-present transactions, response times may be further delayed based on how quickly buyers complete actions on the payment terminal. ### Timeout limit To accommodate potential delays, API requests have a maximum timeout **5 minutes**. ## List of error codes These are the HTTP status codes Finix uses for errors. | HTTP Code | `error.code` | Description | | --- | --- | --- | | `400` | `BAD_REQUEST` | You provided a request that can not be successfully parsed. Verify you are providing valid JSON. | | `401` | `UNKNOWN` | We could not authenticate your request. You used an incorrect API Key. | | `402` | `UPSTREAM_PROCESSOR_ERROR` | Errors caused by 3rd-party services. | | `DECLINED` | The authorization was declined. See the [`failure_code` and `failure_message`](/additional-resources/developers/implementation-and-testing/error-codes/#transfer-and-authorization-errors) for more details. | | `403` | `FORBIDDEN` | Your credentials do not have the right permissions to submit the request. | | `404` | `NOT_FOUND` | The specified resource could not be found. | | `405` | `METHOD_NOT_ALLOWED` | The HTTP request method used to submit the request is not supported by the specified resource. | | `406` | `NOT_ACCEPTABLE` | The server cannot accept the submitted request. Confirm how the request was formatted and submitted. | | `409` | `CONFLICT` | The submitted request conflicts with the current state of the server. | | `422` | `UNPROCESSABLE_ENTITY` | The parameters were valid but the request failed. The error is usually some misunderstanding of various steps that have to be executed in order (e.g. attempting to initiate a transfer on behalf of a merchant that has not yet been approved). | | `INVALID_FIELD` | A provided field has an invalid value. | | `429` | `TOO_MANY_REQUESTS` | A rate limit has been reached. Please wait and try again after the rate limit has reset. [See our rate limit guide here](/additional-resources/developers/authentication-and-api-basics/rate-limits). | | `500` | `SERVER_ERROR` | We had a problem with our server. Try again later. | ## Error response body Requests with errors will return an array of `errors`. Below is an example of one error that can be returned from any resource (except `Transfers` and `Authorizations`). For `Transfer` and `Authorization` errors, see [Transfer and Authorization Errors](#transfer-and-authorization-errors). ```json Error Response Example { "total": 1, "_embedded": { "errors": [ { "logref": "d4ee0b6cdb67686f0c1ec0780e5b4296", "message": "Malformed request. ", "code": "BAD_REQUEST", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/merchants" } } } ] } } ``` ### Response format | Field | Description | | --- | --- | | `error.code` | A code to programmatically handle the error. | | `error.logref` | A unique identifier for this specific API request and response. | | `error.message` | A human-readable description of the error. Not to be coded/programmed to. | ## Transfer and Authorization errors When a card is declined, Finix creates a `Transfer` or `Authorization` resource with a `state` of `FAILED` and returns a `201 Created` response. The resource includes a `failure_code` and `failure_message` that describe the decline reason. Invalid requests (missing required fields, unsupported parameters, etc.) return a 400-level response with an `errors` object describing what went wrong. The `errors` object may also include the ID of any resource Finix created before the error occurred. ```json Authorization Request Error Response { "total": 1, "_embedded": { "errors": [ { "logref": "3fe8e6ab1e8cf44f", "message": "Authorization AUst6ZdywPwe4fbYWrH1zTNJ was declined Cause: Authorization AUst6ZdywPwe4fbYWrH1zTNJ could not be submitted. Cause: Generic Decline", "code": "DECLINED", "authorization": "AUst6ZdywPwe4fbYWrH1zTNJ", "failure_code": "GENERIC_DECLINE", "failure_message": "The card was declined for an unknown reason. The cardholder needs to contact their issuer for more information.", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations" }, "authorization": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUst6ZdywPwe4fbYWrH1zTNJ" } } } ] } } ``` ### Response format | Field | Description | | --- | --- | | `error.authorization` | The `Authorization` ID of the declined authorization. This is only populated for authorization errors that result in a created `Authorization`. | | `error.code` | A code to programmatically handle the error. For `Authorizations` and `Transfers` this field is now deprecated in favor of `failure_code`. | | `error.failure_code` | The code of the failure so the decline can be handled programmatically. | | `error.failure_message` | A human-readable description of why the transaction was declined. This will also include a suggestion on how to complete the payment. | | `error.logref` | A unique identifier for this specific API request and response. | | `error.message` | A human-readable description of the error. For `Authorizations` and `Transfers` this field is now deprecated in favor of `failure_message`. | | `error.transfer` | The `Transfer` ID of the declined authorization. This is only populated for transfer errors that result in a created `Transfer`. | --- # Failure Codes Source: https://docs.finix.com/additional-resources/developers/implementation-and-testing/failure-codes When a transaction gets declined, Finix lets you know by returning a `failure_code` and `failure_message`. The `failure_message` in the response explains the steps you need to take to complete the payment. This guide explains what each of the failure codes Finix uses means. Failure Code Changes `failure_codes` will never change without advanced notice. However, `failure_messages` are subject to change and improvements. ## Payment failure codes Note that failure codes with asterisks will **disable the Payment Instrument**. | Failure Code | Failure Message | | --- | --- | | `ADDRESS_VERIFICATION_FAILED_RISK_RULES` | The Risk Rules associated to the `Merchant` declined the transaction. The cardholder needs to create a card with the correct address. | | `ALLOWABLE_NUMBER_OF_PIN_ENTRY_TRIES_EXCEEDED` | The maximum permitted number of PIN entry attempts has been exceeded. Please use another payment method. | | `AUTHORIZATION_EXPIRED_OR_ALREADY_CAPTURED` | The authorization is either expired or has already been captured. The cardholder needs to create a new authorization. | | `BANK_ACCOUNT_CLOSED` | The bank account has been closed. Contact the account owner and get another method of payment that's active. | | `BANK_ACCOUNT_FROZEN` | The bank account is frozen. Contact the account owner and get another method of payment. | | `CALL_ISSUER` | The card was declined for an unknown reason. The cardholder needs to contact their card issuer for more information. | | `CANCELLATION_VIA_API` | The transaction was canceled via API before the transaction was completed. The cardholder needs to attempt the transaction again. | | `CANCELLATION_VIA_DEVICE` | The cancel button was pressed on the device before the transaction was completed. The cardholder needs to attempt the transaction again. | | *`CARD_ACCOUNT_CLOSED` | The card account has been closed. The cardholder should use an active card. | | `CARD_NETWORK_ERROR` | There is a problem with the card network. Contact the network for more information. | | `CARD_NOT_ACTIVATED_OR_BLOCKED` | The card was declined because it has not been activated or has been temporarily blocked. Please ask the cardholder to activate their card or contact their issuing bank for additional information. | | `CARD_NOT_SUPPORTED` | The card does not support this type of purchase. The cardholder needs to contact their issuing bank to make sure their card can be used to make this type of purchase. | | `CARDHOLDER_PREVENTED_RECURRING_TRANSACTION` | Cardholder requested that recurring or installment transaction to be stopped. | | `COMMUNICATION_ERROR` | There was a network communication error with the host. Check your network connection and retry the transaction. | | `CVV_FAILED_RISK_RULES` | The Risk Rules associated with the `Merchant` declined the transaction. The cardholder needs to create a card with the correct CVV. | | `DEVICE_IN_USE` | The device is currently processing a request. Attempt a request again once the request is complete, or within 6 minutes. | | `DEVICE_NOT_CONNECTED` | The payment terminal isn't connected to a network. Connect the payment terminal to a network and reattempt the transaction. | | `DEVICE_UNREACHABLE` | The API request could not communicate with the device. Please try again. | | `DO_NOT_HONOR` | The card was declined for an unknown reason. The cardholder needs to contact their issuing bank for more information. | | `DUPLICATE_TRANSACTION` | A transaction with the same amount and card was approved recently and marked as a duplicate. If this duplicate transaction was intentional, set `check_for_duplicate_transactions` to `false`. | | `EXCEEDED_CARDHOLDER_INPUT_TIME_LIMIT` | The cardholder failed to swipe, tap, or dip the card in the expected time window. The cardholder needs to attempt the transaction again. | | `EXCEEDS_APPROVAL_LIMIT` | The transaction was declined because it exceeded the daily approval limit for the card. The cardholder needs to use a different card. | | `EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT` | The card has exceeded its withdrawal frequency limit. The cardholder needs to use a different card. | | `EXPIRED_CARD` | The card has expired. The cardholder needs to use another card that's not expired. | | `FRAUD_DETECTED` | The card was declined for fraud by the processor. The customer should contact their card issuer for more information. | | `FRAUD_DETECTED_BY_FINIX` | The card was declined because of suspected fraud by Finix. Please contact Finix for additional information. | | `FRAUD_DETECTED_BY_ISSUER` | The card was declined because of suspected fraud by the issuing bank. Please have the cardholder contact their issuing bank for additional information. | | `GENERIC_DECLINE` | The transaction was declined for an unknown reason. The account owner needs to contact their issuer for more information. | | `INACTIVE_CARD` | The card is inactive. The cardholder needs to activate the card or use an active card. | | `INCOMPLETE_TRANSACTION` | The transaction was not completed by the cardholder. The cardholder needs to reattempt the transaction. | | `INSUFFICIENT_FUNDS` | The account has insufficient funds for the transaction. The account holder needs to use another method of payment. | | *`INVALID_ACCOUNT_NUMBER` | The card number is not valid. The cardholder needs to contact their issuing bank for more information or use another card. | | `INVALID_AMOUNT` | The amount exceeds the amount that is allowed on the card. The cardholder needs to check with their issuing bank to see if they can make purchases of that amount. | | `INVALID_BANK_ACCOUNT_NUMBER` | The bank account number is not valid. The account holder needs to use a valid account number. | | `INVALID_BANK_ACCOUNT_VALIDATION_CHECK` | The provided bank account cannot be used because the routing number is no longer valid. Please check that the account holder's routing number and account are correct or attempt with another bank account. | | `INVALID_CARD` | The card is invalid. The cardholder needs to use another card that is not invalid. | | `INVALID_CARD_NUMBER_OR_EXPIRED_CARD` | The card was declined because the issuing bank indicated that the card number is not valid, closed, or the expiration date is invalid. | | `INVALID_CVV` | The CVV number is invalid. The cardholder needs to attempt the transaction again using the correct CVV. | | `INVALID_ISSUER` | The card number is not associated to a valid card issuing bank. The cardholder needs to contact their issuing bank. | | `INVALID_ROUTING_NUMBER` | The bank routing number provided is invalid. The bank account holder needs to provide a valid routing number. | | `INVALID_TRANSACTION` | The transaction is not permitted by the issuing bank. The cardholder needs to contact their issuing bank for more information. | | `ISSUER_POLICY_VIOLATION` | The card was declined because the issuing bank has an internal rule that prevents the transaction from being permitted. The rule can prohibit certain MCCs, merchant accounts, issuer country codes or other restrictions. Please have the cardholder contact their issuing bank for additional information. | | *`LOST_OR_STOLEN_CARD` | The transaction was declined because the card is reported lost or stolen. Do not return the `LOST_OR_STOLEN_CARD` `failure_code` and `failure_message` to cardholders. Instead, return a generic decline. | | `MAX_TRANSACTION_AMOUNT_EXCEEDED` | The transaction was declined because it exceeded the max transaction amount that's associated with the `Merchant` . The cardholder needs to reprovision the `Merchant` with a higher max transaction amount or create a transaction with a lower amount. | | `NO_BANK_ACCOUNT_FOUND` | The account number is valid; however, the number doesn't correspond to the account holder or it's not an open account. The account holder needs to reenter their information with the correct details. | | `NON_TRANSACTION_ACCOUNT` | This is a non-transaction account that limits or prevents transactions Contact your customer and request permission to charge a different bank account. | | `PAYMENT_STOPPED` | The customer has stopped the payment with their bank. Contact the customer for details and to arrange payment. | | *`PICK_UP_CARD` | The card has been reported as lost or stolen by the cardholder. The cardholder needs to contact their issuing bank. | | `REFUND_EXPIRED` | The refund has expired. | | `RESTRICTED_CARD` | The card has a restriction preventing approval for this transaction. Please contact the issuing bank for a specific reason. | | `RESUBMIT_TRANSACTION` | The transaction couldn’t be processed by the issuer for an unknown reason. The cardholder needs to attempt the transaction again. If the transaction is declined again, the cardholder should contact their issuing bank. | | `TRANSACTION_NOT_PERMITTED` | The transaction was declined because the card or transaction type is not permitted. The cardholder needs to use a different type of card or attempt a different transaction method. | ## Push-to-Card errors Below are the different error values that the `messages` attribute can return for Push to Card. | Error Code | Messages | | --- | --- | | `ALLOWABLE_NUMBER_OF_PIN_ENTRY_TRIES_EXCEEDED` | The maximum permitted number of PIN entry attempts has been exceeded. Please use another payment method. | | `CANNOT_VERIFY_PIN` | The PIN is invalid or missing. Please try again with the correct PIN. | | `CARD_AUTHENTICATION_FAILED` | Please contact card issuer for more information. | | `CRYPTOGRAPHIC_ERROR_FOUND_IN_PIN` | The supplied PIN is invalid. | | `DO_NOT_HONOR` | Please contact card issuer for more information. | | `ERROR` | Please attempt transaction again but if it still cannot be processed try again at a later time. | | `EXCEEDS_APPROVAL_AMOUNT_LIMIT` | Transaction violates issuer amount limit. Please contact card issuer for more information or try with another card. | | `EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT` | Please attempt with another card or contact card issuer for more information. | | `EXPIRED_CARD` | The expiration date is expired or missing. Please correct and try again. | | `FILE_TEMPORARILY_NOT_AVAILABLE` | Please contact card issuer for more information. | | `FINANCIAL_INSTITUTION_NOT_FOUND` | The issuer can not be found. Please check card number to ensure it is valid. | | `INCORRECT_PIN` | The PIN is invalid or missing. Please try again with the correct PIN. | | `INVALID_ACCOUNT_NUMBER` | The account number does not exist. Please make sure the account number is correct or contact your issuer. | | `INVALID_AMOUNT_OR_CURRENCY` | Transaction violates network amount limit. | | `INVALID_MERCHANT` | Merchant not permitted for this transaction type. | | `INVALID_TRANSACTION` | Issuing bank does not support this transaction type on this card. Please contact card issuer for more information. | | `ISSUER_INOPERATIVE` | Please attempt transaction again and contact card issuer if it still cannot be processed. | | `LOST_CARD_PICK_UP_FRAUD_ACCOUNT` | Please contact card issuer for more information. | | `NEGATIVE_RESULTS` | Invalid security code. | | `NO_ACTION_TAKEN` | Please contact card issuer for more information. | | `NO_CHECKING_ACCOUNT` | The card is not tied to a checking account and thus cannot be processed. Please try another card. | | `NO_CREDIT_ACCOUNT` | Issuer has declined the transaction because the card is not a credit account. Please try another card. | | `NO_SAVINGS_ACCOUNT` | The card is not tied to a savings account and thus cannot be processed. Please try another card. | | `NO_SUCH_ISSUER` | The issuer can not be found. Please check card number to ensure it is valid. | | `NOT_SUFFICIENT_FUNDS` | Card issuer has declined the transaction as it does not have sufficient funds. | | `PICK_UP_CARD_FRAUD_ACCOUNT` | Please contact card issuer for more information. | | `PICK_UP_CARD_NO_FRAUD` | Please contact card issuer for more information. | | `RE_ENTER_TRANSACTION` | Please attempt transaction again and contact card issuer if it still cannot be processed. | | `REFER_TO_CARD_ISSUER` | Please contact card issuer for more information. | | `RESTRICTED_CARD` | Card not supported in this region or country. Please contact card issuer for more information. | | `STOLEN_CARD_PICK_UP_FRAUD_ACCOUNT` | Please contact card issuer for more information. | | `STOP_PAYMENT_ORDER` | Please contact card issuer for more information. | | `SURCHARGE_AMOUNT_NOT_SUPPORTED` | The supplied surcharge amount is not supported by the issuer. | | `SUSPECTED_FRAUD` | Please contact card issuer for more information. | | `TRANSACTION_AMOUNT_EXCEEDS_PREAUTHORIZED_APPROVAL_AMOUNT` | Transaction violates amount limit. | | `TRANSACTION_DOES_NOT_FULFILL_AML_REQUIREMENT` | This transaction does not fulfill compliance requirements and cannot be processed. | | `TRANSACTION_NOT_COMPLETED_LAW_VIOLATION` | The transaction cannot be completed because it violates a law. | | `TRANSACTION_NOT_PERMITTED` | Transaction not permitted to cardholder. Please contact card issuer for more information. | | `UNABLE_TO_LOCATE_RECORD` | The account number does not exist. Please make sure the account number is correct or contact your issuer. | --- # Implementation and Testing Source: https://docs.finix.com/additional-resources/developers/implementation-and-testing Learn how to implement and test your integration into Finix's APIs. If you're planning to use Finix's APIs, implementing and testing your integration is critical before going live and accepting payments on behalf of customers. Finix recommends reading through our guides here before starting your implementation. ## Learn more Error Codes Learn about the HTTP error codes the Finix API returns and how to resolve them. Failure Codes Learn what each failure code means when a transaction gets declined. Integration Checklist Use this checklist to ensure a smooth transition when going live with Finix. Testing Your Integration Learn how to test your integration in Sandbox before going live. --- # Integration Checklist Source: https://docs.finix.com/additional-resources/developers/implementation-and-testing/integration-checklist Use this checklist to ensure a smooth transition when going live with Finix. This guide explains the key details that [Finix-for-Businesses](https://finix.com/who-we-serve/customers/businesses) need to consider before going live. Reviewing and completing this checklist helps ensure your payment experience is complete and transactions process successfully. Who this checklist is for This checklist is specifically for [Finix-for-Businesses](https://finix.com/who-we-serve/customers/businesses). [All other customers](https://finix.com/who-we-serve/customers) should integrate with Finix as Platforms. See [Platform Checklist](/guides/platform-payments/platform-checklist) for integration details. ## Before you start How you build your integration may depend on your team's payment experience and engineering resources. We recommend reviewing our documentation and defining your payment experience before going live. For example: - Will you accept Apple Pay? - How will you receive notifications about disputes? - What refund window will you offer? The Finix-for-Businesses Integration Checklist covers: 1. [Account](#account-and-login) 2. [Process Payments](#process-payments) 3. [Collecting Payouts](#collect-payouts) 4. [Technical Considerations](#technical-considerations) When you're ready to go live, [message our Support Team](mailto:support@finix.com). We will review your integration to confirm if your Sandbox and Live Environments are ready. ## Account and login Start your integration with the following steps: - [Create your Sandbox Account](/guides/getting-started/finix-sign-up) - [Log into the Finix Dashboard](https://finix.payments-dashboard.com/Login) - [Create API Keys for your developers](/additional-resources/developers/authentication-and-api-basics/api-keys) ### Data migration You may optionally migrate existing payments or customer data to Finix to minimize gaps in availability or billing. For more info, see [Migrating Data with Finix](/additional-resources/developers/migrating-data-to-finix). ## Process Payments All Finix integrations must be able to [process payments](/guides/getting-started/developer-quickstart) before going live. Depending on the payment methods, you may need to support: - [Card](#card-payments) - [Apple Pay](#apple-pay-payments) - [Google Pay](#google-pay-payments) - [ACH (eCheck)](#ach-echeck-payments) Every integration must also include: - [Refunding a payment](/guides/after-the-payment/refunds/) - [Managing disputes](/guides/after-the-payment/disputes/) ### Card Payments Your integration must handle the following for card transactions: - [Create an `Identity` for your buyer](/guides/getting-started/developer-quickstart#step-1-create-an-identity-for-your-buyer) - [Tokenize card details with our Tokenization Forms](/guides/online-payments/payment-tokenization/tokenization-forms) - [Process payment via `Transfer` for Sale flows](/guides/getting-started/developer-quickstart#step-3-make-a-payment) - [Create and capture an `Authorization` for Auth and Capture flows](/guides/online-payments/payment-features/auth-and-captures) - [Handle failed payments and `failure_codes`](/additional-resources/developers/implementation-and-testing/error-codes/#transfer-and-authorization-errors) Handling Raw Card Data If you're fully [PCI DSS-compliant](/guides/managing-operations/security-compliance/pci-dss-compliance) and want to handle raw card data, see our guide on [handling raw card data](/guides/online-payments/payment-tokenization/handling-raw-card-data). ### Apple Pay Payments To support Apple Pay, process an [Apple Pay transaction](/guides/online-payments/digital-wallets/apple-pay) using: - [Apple Pay on iOS](/guides/online-payments/digital-wallets/apple-pay/apple-pay-on-ios) - [Apple Pay on Web](/guides/online-payments/digital-wallets/apple-pay/apple-pay-on-web) ### Google Pay Payments To support Google Pay, process a [Google Pay transaction](/guides/online-payments/digital-wallets/google-pay) using: - [Google Pay on Android](/guides/online-payments/digital-wallets/google-pay/google-pay-on-android) - [Google Pay on Web](/guides/online-payments/digital-wallets/google-pay/google-pay-on-web) ### ACH (eCheck) Payments Successfully process an [ACH (eCheck) transaction](/guides/online-payments/bank-payments) using the buyer's bank account details. ## Collect Payouts [Collect payouts](/guides/platform-payments/seller-payouts/) from your processed payments. Ensure payouts are sent to the correct account and align with your processed payment activity. ## Technical considerations Your complete integration should also include: - [Set up Webhooks to receive updates](/additional-resources/developers/webhooks) - [Authenticate Webhooks](/additional-resources/developers/webhooks/integrating-into-webhooks#creating-authenticated-webhooks) - [Manage Webhooks using the Webhook Log](/additional-resources/developers/webhooks/integrating-into-webhooks#managing-webhooks-via-dashboard) --- # Testing Your Integration Source: https://docs.finix.com/additional-resources/developers/implementation-and-testing/testing-your-integration Finix offers several ways to test your Sandbox integration. Use the values below to test your integration. We encourage you to test these scenarios before running transactions in your Live environment. ## Testing transactions The testing scenarios below are for testing payment transactions. These include `Transfers`, `Authorizations`, `Payment Instrument` responses, and more. ### Testing card type Use the following card numbers to trigger the respective `card_type`. Provide the `amount` in cents. | Card Type | Card Number | Brand | | --- | --- | --- | | `CREDIT` | `6011000000004675` | Discover | | `DEBIT` | `5200820000007201` | Mastercard | | `HSA_FSA` | `4393420000002680` | Visa | | `NON_RELOADABLE_PREPAID` | `5223100000008423` | Mastercard | | `RELOADABLE_PREPAID` | `379032000006086` | American Express | | `UNKNOWN` | `386214000009097` | Discover | ### Testing transaction failures and Disputes Pass one of the following `amount` values to trigger the respective payment failure. Once a `Payment Instrument` is flagged with an AVS or CVV failure, it will continue to return that error. Provide the `amount` in cents. | Amount | Description | | --- | --- | | `102` | Declined amount | | `103` | Canceled amount | | `888888` | Disputed amount | | `193` | Insufficient funds amount | | `194` | Invalid card number amount | | `889986` | AVS total failure amount | | `889987` | CVC failure amount | For more details about address and CVV verification, see the [Risk Rules and Card Checks](https://docs.finix.com/guides/online-payments/fraud-and-risk/risk-rules-card-checks) guide. ### Testing name Verification Use the following sentinel values to simulate name verification results on `DUMMY_V1`. If none are provided, all fields in `name_verification_results` return `UNKNOWN`. Sentinel values are not case-sensitive. #### Direct name Verification You can perform name verification using the [PUT /payment_instruments/{payment_instrument_id_verify}](/api/payment-instruments/createpaymentinstrumentverification) endpoint. Select the "Name Verification" example. Use the `first_name` and `last_name` fields in `name_verification_details` to trigger a specific result. All four fields in `name_verification_results` return the same value. | `first_name` | `last_name` | `name_verification_results` | | --- | --- | --- | | `Billy` | `NameVerification` | `MATCH` | | `Joey` | `NameVerification` | `NO_MATCH` | | `Sarah` | `NameVerification` | `PARTIAL_MATCH` | | `Amanda` | `NameVerification` | `NOT_SUPPORTED` | #### Name Verification via Push-to-Card eligibility check [Verifying Push-to-Card eligibility](/api/payment-instruments/createpaymentinstrumentverificationpushtocard) returns name verification results. All four fields in `name_verification_results` (`first_name`, `last_name`, `middle_name`, and `name`) return the same value. | `Payment Instrument` › `name` | `name_verification_results` | | --- | --- | | `Billy NameVerification` | `MATCH` | | `Joey NameVerification` | `NO_MATCH` | | `Sarah NameVerification` | `PARTIAL_MATCH` | | `Amanda NameVerification` | `NOT_SUPPORTED` | ### Testing failure codes Use the following card numbers to test failure codes. Provide the `amount` in cents. After [creating a Transfer](/api/transfers/createtransfer) with one of the card numbers below, you can see the `failure_code` and `failure_message` in the `Transfer` details. You can also [retrieve a Transfer](/api/transfers/gettransfer) to check these fields. For testing ACH return codes, refer to [Testing ACH returns](#testing-ach-returns). | Failure Code | Card Number | Brand | | --- | --- | --- | | `GENERIC_DECLINE` | `4000000000009979` | Visa | | `GENERIC_DECLINE` | `378282246310005` | American Express | | `GENERIC_DECLINE` | `5555555555554444` | Mastercard | | `GENERIC_DECLINE` | `6011111111111117` | Discover | | `CALL_ISSUER` | `4012888888881881` | Visa | | `CARD_NOT_ACTIVATED_OR_BLOCKED` | `4539148803436467` | Visa | | `DO_NOT_HONOR` | `4000000000000002` | Visa | | `EXCEEDS_APPROVAL_LIMIT` | `4000000000009995` | Visa | | `EXPIRED_CARD` | `4000000000009987` | Visa | | `FRAUD_DETECTED_BY_FINIX` | `4129054449449482` | Visa | | `FRAUD_DETECTED_BY_ISSUER` | `4783512839773883` | Visa | | `INSUFFICIENT_FUNDS` | `4000000000000069` | Visa | | `INVALID_CARD_NUMBER_OR_EXPIRED_CARD` | `4544206329536898` | Visa | | `INVALID_CVV` | `4000056655665556` | Visa | | `ISSUER_POLICY_VIOLATION` | `4709247730212712` | Visa | | `LOST_OR_STOLEN_CARD` | `4000000000000127` | Visa | | `PICK_UP_CARD` | `4000000000000119` | Visa | | `RESTRICTED_CARD` | `4242424242424242` | Visa | ### Testing Network tokens Use the following card numbers to set a specific `network_token_state`. By default, any valid card number enabled for network tokens returns an `ACTIVE` state. Provide the `amount` in cents. | `Payment Instrument` › `network_token_state` | Card Number | | --- | --- | | `CLOSED` | `4181126552690790` | | `FAILED` | `4281168227567010` | | `SUSPENDED` | `4220706972789265` | To learn more about Network Tokens, see the [Network Tokens](https://docs.finix.com/guides/after-the-payment/network-tokens) guide. ### Testing account updater Use the following card numbers to test account updater responses. Provide the `amount` in cents. | Account Update Type | Brand | Initial card number | Initial expiration (M/Y) | New number | New expiration (M/Y) | | --- | --- | --- | --- | --- | --- | | `CLOSED_CARD` | Visa | `4402087389579601` | `1/2030` | - | - | | `CONTACT_CARDHOLDER` | Visa | `4349990631704016` | `1/2030` | - | - | | `EXPIRATION_UPDATED` | Visa | `4208862673740549` | `1/2030` | `4307730606824385` | `1/2040` | | `FRAUD_REPORTED` | American Express | `340452801563455` | `1/2030` | - | - | | `INACTIVE_MERCHANT` | American Express | `3403470175812488` | `1/2030` | - | - | | `NO_TRANSACTIONAL_ACTIVITY` | American Express | `3019542985188444` | `1/2030` | - | - | | `NOT_FOUND` | Visa | `4543267787982264` | `1/2030` | - | - | | `NUMBER_AND_EXPIRATION_UPDATED` | Visa | `4496772882855767` | `1/2030` | `4887005601746919` | `3/2040` | | `NUMBER_AND_EXPIRATION_UPDATED` | Mastercard | `5103504002919260` | `1/2030` | `5213076676875406` | `11/2040` | | `NUMBER_AND_EXPIRATION_UPDATED` | American Express | `3883494643244974` | `1/2030` | `3969967933006770` | `08/2040` | | `NUMBER_AND_EXPIRATION_UPDATED` | Discover | `6588849539088200` | `1/2030` | `6011174500160749` | `12/2040` | | `NUMBER_AND_EXPIRATION_UPDATED` | Visa | `4496772882855767` | `1/2030` | `4887005601746919` | `3/2040` | | `NUMBER_UPDATED` | Visa | `4036161292637501` | `1/2030` | `4649777215746100` | `4/2040` | To find out how Account Updater works, see the [Account Updater](/guides/after-the-payment/account-updater) guide. ### Testing Refunds Use the following card numbers to test refunds. Provide the `amount` in cents. | State | Card Number | Brand | | --- | --- | --- | | `FAILED` | `4000000000000135` | Visa | To learn more about refunding payments, refer to our [Refunding Payments](/guides/after-the-payment/refunds) guide. ### Testing bank account validations Use these specific bank codes and account numbers to test bank account validations. Provide the `amount` in cents. | Bank Account Validation Check | Bank Code | Account Number | | --- | --- | --- | | `VALID` | `122105278` | `0000000016` | | `INVALID` | `122105278` | `0000000005` | | `INCONCLUSIVE` | `121000358` | `123123128` | ### Testing Microdeposit verifications #### Creating a bank account Payment Instrument Use the following account numbers when [creating a bank account Payment Instrument](/api/payment-instruments/createpaymentinstrument) (`POST /payment_instruments`) to trigger different Microdeposit outcomes. | Scenario | Account Number | | --- | --- | | Any valid account number not listed below creates a [Microdeposit](/api/microdeposits) with `state: PENDING`. | Any valid value | | The bank account is permanently blocked (`TOTAL_MICRODEPOSIT_ATTEMPTS_EXCEEDED_ACCOUNT_LOCKED`). | `374920581` | | Forces Microdeposit verification even when the application flag is off (`MICRODEPOSIT_VERIFICATION_REQUIRED`). | `846135702` | | Bypasses verification even when the application flag is on; the `Payment Instrument` is enabled at creation. | `528193746` | #### Verifying the Microdeposit Use the following verification codes when [verifying the Microdeposit](/guides/online-payments/bank-payments/microdeposit-verification#verifying-a-bank-account-using-the-api) (`PUT /payment_instruments/{id}`) to trigger different outcomes. | Scenario | Verification Code | | --- | --- | | The verification succeeds and the `Payment Instrument` is enabled. | `FNX0000` | | The verification has expired (`MICRODEPOSIT_VERIFICATION_EXPIRED`). | `FNX4444` | | The submission is incorrect and uses one try. After 3 incorrect submissions, the verification fails with `MICRODEPOSIT_VERIFICATION_ATTEMPTS_EXCEEDED`. | Any other value | To learn more about verifying bank accounts with Microdeposits, refer to our [Microdeposit Verification](/guides/online-payments/bank-payments/microdeposit-verification) guide. ### Testing ACH returns Use the following bank details to trigger the respective ACH Return Code. Provide the `amount` in cents. For more information about the different ACH Return Codes, see [ACH Direct Debit](/guides/online-payments/bank-payments/ach-direct-debits). | ACH Return Code | Failure Code | Failure Message | Bank Details | | --- | --- | --- | --- | | R01: Insufficient Funds | `INSUFFICIENT_FUNDS` | The account has insufficient funds for the transaction. The account holder needs to use another method of payment. | Bank Code: `122105278`Account Number: `123120006` | | R02: Account is Closed | `BANK_ACCOUNT_CLOSED` | The bank account has been closed. Contact the account owner and get another method of payment that's active. | Bank Code: `122105278`Account Number: `123120007` | | R03: No account on file | `NO_BANK_ACCOUNT_FOUND` | The account number is valid; however, the number doesn't correspond to the account holder or it's not an open account. The account holder needs to reenter their information with the correct details. | Bank Code: `122105278`Account Number: `123120008` | | R04: Invalid Account Number | `INVALID_BANK_ACCOUNT_NUMBER` | The bank account number is not valid. The account holder needs to use a valid account number. | Bank Code: `122105278`Account Number: `123120009` | - The `Merchant` › `ready_to_settle_upon` field must be `PROCESSOR_WINDOW` or `RECONCILIATION`. Currently, `SUCCESSFUL_CAPTURE` is not supported. - The `failure_code` and `failure_message` are populated on the original `Transfer` resource. - The `tags` of the new return `Transfer` that's created include the ACH Return Code and `failure_message` associated with the return. ### Testing 3D Secure Use the following card numbers to test 3D Secure sessions on `DUMMY_V1` in Sandbox. Challenges are rendered by Evervault's Sandbox environment, which Finix does not host. The flow for challenge, frictionless, and attempted authentication cards: 1. Create a Payment Instrument using one of the card numbers below. Call POST /3d_secure_sessions with its `payment_instrument_id`, plus `amount`, `currency`, `merchant_id`, and an HTTPS `redirect_url`. 2. Open the `3d_secure_authentication_url` returned in the session to complete the challenge. 3. GET /3d_secure_sessions/{id} to confirm the result. Allow 1-2 seconds for results to update asynchronously after the challenge completes. For **Card not enrolled** cards, the session fails immediately on creation. No redirect or challenge step occurs. | Scenario | Network | Card Number | `authentication_type` | `state` | `failure_code` | | --- | --- | --- | --- | --- | --- | | 3D Secure challenge | Visa | `4829866387038313` | `CHALLENGE` | `SUCCEEDED` | | | 3D Secure challenge | Mastercard | `5587767065796470` | `CHALLENGE` | `SUCCEEDED` | | | Successful frictionless | Visa | `4111110116638870` | `FRICTIONLESS` | `SUCCEEDED` | | | Successful frictionless | Mastercard | `5555550130659057` | `FRICTIONLESS` | `SUCCEEDED` | | | Failed frictionless | Visa | `4111111738973695` | `FRICTIONLESS` | `FAILED` | `SUSPECTED_FRAUD` | | Failed frictionless | Mastercard | `5555550487847545` | `FRICTIONLESS` | `FAILED` | `SUSPECTED_FRAUD` | | Attempted authentication | Visa | `4111110148486405` | `ATTEMPT` | `SUCCEEDED` | | | Attempted authentication | Mastercard | `5555558824815604` | `ATTEMPT` | `SUCCEEDED` | | | Card not enrolled | Visa | `4111110148486413` | | `FAILED` | `CARD_NOT_ENROLLED` | | Card not enrolled | Mastercard | `5555558824815612` | | `FAILED` | `CARD_NOT_ENROLLED` | Only these 10 cards are supported for 3D Secure sessions in Sandbox. Using any other card number may return an undocumented failure code. To learn more about integrating 3D Secure, see the [3D Secure Authentication](/guides/online-payments/fraud-and-risk/3d-secure) guide. ## Testing Payouts ### Testing Push-to-Card Use the following card numbers to test Push-to-Card payout responses. Provide the `amount` in cents. | Scenario | Card number | Brand | Region | Country | Code | | --- | --- | --- | --- | --- | --- | | Successful push to a Visa (debit card) | `4895142232120006` | Visa | CA | USA | N/A | | Successful push to a Visa (credit card) | `4957030420210454` | Visa | CA | USA | N/A | | Successful push to a Mastercard (debit card) | `5123280115058611` | Mastercard | CA | USA | N/A | | Invalid account number | `4957030420210504` | Visa | CA | USA | `INVALID_INSTRUMENT` | | Exceeds approval amount limit | `4957030420210488` | Visa | CA | USA | `EXCEEDS_ISSUER_AMOUNT_LIMIT` | | Exceeds withdrawal frequency limit | `4957030420210496` | Visa | CA | USA | `EXCEEDS_ISSUER_COUNT_LIMIT` | | Refer to card issuer | `4895070000007685` | Visa | CA | USA | `CALL_ISSUER` | | Do not honor | `4895070000006687` | Visa | CA | USA | `DECLINE` | | Lost card, pick up (fraud account) | `4895070000005671` | Visa | CA | USA | `LOST_OR_STOLEN_CARD` | | Suspected fraud | `4895070000004674` | Visa | CA | USA | `SUSPECTED_FRAUD` | | Transaction does not fulfill AML requirement | `4895070000003551` | Visa | CA | USA | `COMPLIANCE_VIOLATION` | ### Testing Push-to-Card Verifications Use the following card numbers to test Push-to-Card Verification responses. Provide the `amount` in cents. | Scenario | Card number | Brand | fast_funds_indicator | push_funds_block_indicator | card_type_code | card_issuer_country_code | | --- | --- | --- | --- | --- | --- | --- | | Issuer does participate in fast funds for only domestic transactions | `4815070000000018` | Visa | `D` | `C` | `D` | `840` | | Issuer does participate in fast funds for all transactions | `4835070000000014` | Visa | `B` | `C` | `D` | `840` | | Issuer does not participate in fast funds | `4855070000000035` | Visa | `N` | `C` | `D` | `840` | | Issuer does participate in fast funds and Push-to-Card | `4895047700003297` | Visa | `B` | `B` | `C` | `840` | --- # Finix MCP Server for AI Agents Source: https://docs.finix.com/additional-resources/developers/mcp-server MCP Server The Finix MCP Server allows AI agents like Claude to search and retrieve information from Finix's documentation. Ask an AI agent questions about the Finix API to get accurate, current answers. Before exploring setup, let’s clarify what MCP offers and why it’s essential for AI integration. ## What is MCP? Model Context Protocol (MCP) is an open standard enabling AI agents to connect to external data sources and tools. MCP lets AI models query live documentation, APIs, and databases in real time—instead of relying only on training data. ## Why use MCP? Large language models have knowledge cutoffs and lack access to proprietary documentation. When you ask an AI agent about Finix APIs, it provides general guidance based on its training data. MCP provides a standardized interface between AI agents and documentation servers. The Finix MCP server reveals all documentation—including guides, API references, and code examples—enabling AI agents to deliver accurate, up-to-date information on demand. | Without MCP | With MCP | | --- | --- | | Responses based on training data | Responses based on live documentation | | May be outdated or generic | Always reflects current API state | | No access to Finix-specific examples | Full access to code samples and guides | ## Quick setup Add the Finix MCP server to Claude Code with a single command: ```bash Add Finix MCP Server claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http ``` That's it. Claude Code can now access Finix documentation. Detailed Setup Guide For step-by-step instructions, configuration options, and troubleshooting, see the [Claude Code Setup Guide](/additional-resources/developers/mcp-server/mcp-claude-setup). ## Other ways for agents to read the docs If your tool does not support MCP, or you want to load the documentation into a knowledge base, Finix publishes the same content as plain text: - [llms.txt](https://docs.finix.com/llms.txt) - An index of every guide with a one-line summary, following the [llms.txt convention](https://llmstxt.org/). - [llms-full.txt](https://docs.finix.com/llms-full.txt) - The full text of every guide in one file, in the same order as the index. Load it into Cursor, Claude Projects, a custom GPT, or your own retrieval pipeline. - Append `.md` to any page URL, such as `https://docs.finix.com/guides/getting-started/developer-quickstart.md`, to get that page as Markdown. Both files regenerate on every docs deploy, so they always match the published pages. ## What you can do Once connected, your AI agent can help you with: ### Search documentation Ask questions in plain English and get answers from Finix documentation: - "How do I process a refund with Finix?" - "What parameters does the create payment endpoint accept?" - "Show me an example of tokenizing a card." ### Explore the API Access details about Finix API endpoints: list all endpoints, view request and response schemas, check authentication requirements, and see code examples. ### Understand concepts Explore Finix features and best practices, including the payment lifecycle and states, seller onboarding, fee collection options, and webhook integration. ## Available tools The MCP server offers your AI agent these tools: | MCP Tool | Tool Description | | --- | --- | | `search` | Search across all Finix documentation using keywords or phrases. | | `list-apis` | List available APIs with their context and purpose. | | `get-endpoints` | Get all endpoints for a specific API. | | `get-endpoint-info` | Get comprehensive details about a specific endpoint including parameters, security requirements, and examples. | | `get-security-schemes` | Get authentication and security information for an API. | | `get-full-spec-document` | Retrieve the complete OpenAPI specification. | ## Example usage Here are some example prompts you can use with your AI agent after connecting the Finix MCP server: ### Getting started > *"I'm new to Finix. What's the basic flow for accepting an online payment?"* ### API reference > *"What fields are required when creating a Transfer resource?"* ### Integration help > *"How do I set up webhooks to track payment status changes?"* ### Troubleshooting > *"What does the RETURNED state mean for a Transfer?"* ## Requirements - **Claude Code** (or another MCP-compatible AI agent). - Internet connection to reach [docs.finix.com](https://docs.finix.com/). ## How it works 1. Ask a question about Finix in your AI agent. 2. The AI detects the need for Finix-specific info. 3. It queries the MCP server at `https://docs.finix.com/mcp`. 4. The server searches Finix documentation. 5. Results are returned to the AI. 6. You receive an accurate, up-to-date response. The process takes just seconds and keeps you in your development environment. ## Learn more Connect ChatGPT to Finix MCP Connect ChatGPT to the Finix MCP server and ask questions about Finix to get accurate, up-to-date answers sourced directly from the documentation. Connect Claude to Finix MCP Use Claude Code with Finix MCP to ask questions about Finix APIs and get documentation-based answers. Connect Gemini to Finix MCP Connect the Gemini CLI to the Finix MCP server and ask questions about Finix to get answers from the documentation. Connect Cursor to Finix MCP Connect Cursor to the Finix MCP server and ask questions about Finix to get accurate answers from the documentation inside your editor. Model Context Protocol Learn more about the open MCP standard and specification. --- # Connect ChatGPT to Finix MCP Source: https://docs.finix.com/additional-resources/developers/mcp-server/mcp-chatgpt-setup OpenAI Logo This guide walks you through connecting ChatGPT to the Finix MCP server. After setup, you can ask ChatGPT questions about Finix and get accurate, up-to-date answers sourced directly from our documentation. ## Prerequisites Before you begin, make sure you have: - **ChatGPT Pro, Team, Enterprise, or Edu plan:** MCP (via the Connectors feature) requires one of these paid plans - **Developer Mode enabled:** Required to add custom MCP connectors - **Internet connection:** Required to reach [docs.finix.com](https://docs.finix.com/) ## Enable developer mode MCP connector support in ChatGPT requires enabling Developer Mode first. 1. Open [ChatGPT](https://chatgpt.com) and click your **profile icon** in the top-left corner. 2. Click **Settings**. 3. Navigate to **Apps & Connectors**. 4. Scroll to **Advanced Settings**. 5. Toggle **Developer Mode** to **On**. ## Add the Finix MCP connector After enabling Developer Mode, add the Finix MCP server as a connector. 1. In **Settings**, go to **Connectors**. 2. Click **Create**. 3. Fill in the connector details: - **Connector name** - `Finix API Docs` - **Description** - `Access Finix API reference and documentation. Use this connector when answering questions about Finix APIs, endpoints, authentication, payments, or integrations.` - **Connector URL** - `https://docs.finix.com/mcp` - **Authentication** - None 4. Click **Create**. If the connection succeeds, ChatGPT shows the list of tools provided by the Finix MCP server (such as `search`, `get-endpoints`, `get-endpoint-info`). Your ChatGPT workspace must have access to the **Connectors** feature. If you don't see **Connectors** in your **Settings**, your plan may not support it yet. ## Use the connector in a chat After creating the connector, activate it in your chat: 1. Open a new ChatGPT conversation. 2. Click the **+** button next to the message composer, then select **More**. 3. Find and select **Finix API Docs** from the list of available connectors. 4. Ask your question - ChatGPT will use the MCP tools to search Finix documentation. The Finix MCP server's `search` tool finds results in both the API Reference and Guides. Detailed retrieval tools (`get-endpoint-info`, `get-endpoints`, `get-full-spec-document`) are only available in the API Reference. See [Enhancing Guide Access](#enhancing-guide-access) to configure the agent for full access to the Finix documentation. ## Enhancing guide Access To get the most from both API documentation and guides, add the following to your ChatGPT system prompt or at the start of your conversation: ```markdown When answering questions about Finix: 1. Use the Finix MCP connector tools (`search`, `get-endpoint-info`, `get-endpoints`) to find relevant API reference content. 2. For guide/tutorial content: after using the MCP search tool to find relevant guide pages, fetch the full content by appending .md to the guide URL. For example: - https://docs.finix.com/guides/getting-started/developer-quickstart.md - https://docs.finix.com/guides/online-payments/payment-tokenization/tokenization-forms.md - https://docs.finix.com/guides/payouts/adding-funds.md 3. Always check both the API Reference and Guides for a complete answer. ``` This lets ChatGPT access Markdown guides and API references via MCP, ensuring complete access to Finix docs. ## Check the connection Try these prompts after activating the connector to confirm it works. ### API reference test > *"What authentication method does the Finix API use?"* If ChatGPT responds with precise information about Finix API authentication (Basic Auth with API credentials), the connection is working. ### Guide Access test > *"How do I onboard a seller on Finix?"* If ChatGPT responds with details from the seller onboarding guide (not just API endpoint info), guide access is working correctly. ## Example prompts Once configured, use the connector by asking Finix-related questions naturally in chat conversations. **API Questions:** > *"What fields are required to create a Transfer?"* *"How do I tokenize a card with Finix.js?"* *"What's the difference between a Transfer and an Authorization?"* **Integration Help:** > *"Show me an example of processing a refund."* *"How do I set up webhooks for payment status updates?"* *"What are the steps to onboard a seller?"* **Troubleshooting:** > *"What does error code 402 mean?"* *"What does the RETURNED state mean for a Transfer?"* *"How do I handle declined payments?"* ### Best practices For best results, follow these tips: 1. **Be specific** - "How do I create a card Authorization?" is better than "How do payments work?". 2. **Reference API resources** - Utilize terms like "Transfer", "Authorization", "Identity", "Merchant" when relevant. 3. **Ask for examples** - "Show me an example of..." prompts ChatGPT to pull code samples from documentation. 4. **Mention the environment** - Specify "Sandbox" or "Production" if it matters for your question. 5. **Activate the connector each session** - Select the Finix connector each time you start a new conversation. ## Troubleshooting tips ### Connector creation fails If ChatGPT reports an error when creating the connector: 1. Verify you can reach [docs.finix.com](https://docs.finix.com/) in a browser. 2. Check that Developer Mode is enabled in **Settings → Apps & Connectors → Advanced Settings**. 3. Confirm your plan supports Connectors (Pro, Team, Enterprise, or Edu required). ### Connector not listed in chat If the Finix connector does not appear after clicking **+** in the chat composer: 1. Ensure the connector was created successfully in **Settings → Connectors**. 2. Try clicking **+** → **More** to see the full list of available connectors. 3. Reload the page and try again. ### ChatGPT not using Finix documentation If ChatGPT answers from general knowledge instead of searching Finix documentation: 1. **Be explicit** - Try "Search the Finix documentation for..." in the prompt. 2. **Check the connector is active** - Click **+** → **More** to confirm the Finix connector is selected for this chat. 3. **Start a new conversation** - Activate the connector before asking your first question. ### Only seeing API reference without guide content If ChatGPT answers with only API endpoint details and misses relevant guide content: 1. **Add the system prompt** - See [Enhancing Guide Access](#enhancing-guide-access) above to instruct ChatGPT to fetch guide Markdown pages. 2. **Ask explicitly** - Try "Check the Finix guides for how to..." to direct ChatGPT toward guide content. ### Outdated information The MCP server uses Finix's published documentation. If you find any outdated information: - Check [docs.finix.com](https://docs.finix.com) for the latest published documentation. - If you notice a discrepancy, contact the [Finix Support Team](mailto:support@finix.com) or your Finix representative for a definitive answer. The MCP server always shows the latest information from [docs.finix.com](https://docs.finix.com), which is updated regularly. ## Set up on other platforms Connect Claude to Finix MCP Use Claude Code with Finix MCP for documentation-based answers. Connect Gemini to Finix MCP Connect the Gemini CLI to the Finix MCP server for documentation-based answers. Connect Cursor to Finix MCP Connect Cursor to the Finix MCP server for answers inside your editor. --- # Connect Claude to Finix MCP Source: https://docs.finix.com/additional-resources/developers/mcp-server/mcp-claude-setup Claude Logo This guide shows you how to use Claude Code with Finix MCP to ask questions about Finix APIs and get documentation-based answers. ## Prerequisites Before you begin, make sure you have: - **Claude Code installed** - Anthropic's CLI tool for AI-assisted development. - **Internet connection** - Required to reach [docs.finix.com](https://docs.finix.com/). ### Installing Claude code If you don't have Claude Code installed yet: ```bash Install Claude Code npm install -g @anthropic-ai/claude-code ``` Or with Homebrew on macOS: ```bash Install with Homebrew brew install claude-code ``` For detailed installation instructions, see [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code). ## Quick setup Run this command to add the Finix MCP server: ```bash claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http ``` Claude Code can now access Finix documentation. The Finix MCP server's `search` tool finds results in both the API Reference and Guides. Detailed retrieval tools (`get-endpoint-info`, `get-endpoints`, `get-full-spec-document`) are only available in the API Reference. See [Enhancing Guide Access](#enhancing-guide-access) to configure the agent for full access to the Finix documentation. ## Enhancing guide Access The MCP server can search guides, but doesn't have a dedicated tool to retrieve their full content. To give Claude full access to both API docs and guides, add the following to your project's `CLAUDE.md` file or system prompt: ```markdown ## Finix Documentation Access When answering Finix questions: 1. Use the Finix MCP server tools (like `search`, `get-endpoint-info`, `get-endpoints`) to find API details. 2. To access the full content of a guide or tutorial: after using the MCP `search` tool to identify relevant guide pages, copy the guide URL from the search result and add `.md` to the end of the URL before opening it. For example: - `https://docs.finix.com/guides/getting-started/developer-quickstart.md` - `https://docs.finix.com/guides/online-payments/payment-tokenization/tokenization-forms.md` - `https://docs.finix.com/guides/payouts/adding-funds.md` 3. Always check both API Reference and Guides for a complete answer. ``` This lets Claude access Markdown guides and API references via MCP, ensuring full access to Finix docs. ## Verify the connection After adding the MCP server, verify it works: ### Check MCP status ```bash List MCP Servers claude mcp list ``` You should see `finix-redocly-mcp` in the list of configured servers. ### Test a query Run this command to start a Claude Code session: ```bash Start Claude Code claude ``` #### API reference test Then try a test prompt: > *"What authentication method does the Finix API use?"* If Claude responds with exact details about Finix API authentication, such as Basic Auth with API credentials, the connection is working. #### Guide Access test > *"How do I onboard a seller on Finix?"* If Claude responds with details from the seller onboarding guide, not just API endpoint info, guide access is working correctly. ## Configuration options ### Project-Level configuration Navigate to your project directory (e.g., `cd /path/to/your/project`) and run: ```bash Project-Level Setup claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http --scope project ``` This creates a `.claude/mcp.json` file so the server is available only in this directory. ### Global configuration Run this command for global configuration: ```bash Global Setup claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http --scope user ``` ### Manual configuration You can also manually edit your Claude configuration file. **Location**: - macOS/Linux: `~/.claude.json` - Windows: `%USERPROFILE%\.claude.json` Add the Finix MCP server to the `mcpServers` section: ```json ~/.claude.json { "mcpServers": { "finix-redocly-mcp": { "type": "http", "url": "https://docs.finix.com/mcp" } } } ``` After editing, restart Claude Code to apply the changes. ## Using the Finix MCP server Once configured, Claude uses the MCP server automatically when you ask Finix-related questions. ### Example prompts **API Questions**: > *"What fields are required to create a Transfer?"* *"How do I tokenize a card with Finix.js?"* *"What's the difference between a Transfer and an Authorization?"* **Integration Help**: > *"Show me an example of processing a refund."* *"How do I set up webhooks for payment status updates?"* *"What are the steps to onboard a seller?"* **Troubleshooting**: > *"What does error code 402 mean?"* *"What does the RETURNED state mean for a Transfer?"* *"How do I handle declined payments?"* ### Best practices For best results: 1. **Be specific** - "How do I create a card Authorization?" is better than "How do payments work?" 2. **Reference API resources** - Utilize terms like "Transfer", "Authorization", "Identity", "Merchant" when relevant. 3. **Ask for examples** - "Show me an example of..." prompts Claude to pull code samples from documentation. 4. **Mention the environment** - Specify "Sandbox" or "Production" if it matters for your question. ## Troubleshooting ### MCP server not found If `claude mcp list` doesn't show `finix-redocly-mcp`: 1. Re-run the add command: ```bash claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http ``` 2. Check that your configuration file exists and is valid JSON. ### Connection errors If Claude reports connection issues: 1. **Check internet connection** - Verify you can access [docs.finix.com](https://docs.finix.com/) in a browser. 2. **Look for firewall/proxy issues** - Corporate networks may block MCP connections. 3. **Try removing and re-adding**: ```bash Reset Connection claude mcp remove finix-redocly-mcp claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http ``` ### Claude not using Finix documentation If Claude seems to guess instead of searching the documentation: 1. **Be explicit** - Try "Search the Finix documentation for..." in the prompt. 2. **Check MCP is enabled** - Run `claude mcp list` to verify the server is configured. 3. **Restart Claude Code** - A fresh session can help. ### Claude only returning API reference (no guide content) If Claude answers with only API endpoint details and misses relevant guide content, 1. **Add the `CLAUDE.md` instructions** - See the [Enhancing Guide Access](#enhancing-guide-access) section above to instruct Claude to fetch guide Markdown pages. 2. **Ask explicitly** - Try "Check the Finix guides for how to..." to prompt Claude to search for guide content. ### Outdated information The MCP server uses Finix's published documentation. If you find any outdated information: - Check [docs.finix.com](https://docs.finix.com) for the latest published documentation. - If you notice a discrepancy, contact the [Finix Support Team](mailto:support@finix.com) or your Finix representative for a definitive answer. The MCP server always shows the latest information from [docs.finix.com](https://docs.finix.com), which is updated regularly. ## Removing the Finix MCP server To disconnect Claude Code from Finix documentation: ```bash Remove Finix MCP Server claude mcp remove finix-redocly-mcp ``` ## Set up on other platforms Connect ChatGPT to Finix MCP Connect ChatGPT to the Finix MCP server for documentation-based answers. Connect Gemini to Finix MCP Connect the Gemini CLI to the Finix MCP server for documentation-based answers. Connect Cursor to Finix MCP Connect Cursor to the Finix MCP server for answers inside your editor. --- # Connect Cursor to Finix MCP Source: https://docs.finix.com/additional-resources/developers/mcp-server/mcp-cursor-setup Cursor Logo This guide walks you through connecting Cursor to the Finix MCP server. After setup, you can ask Cursor questions about Finix and get accurate answers from our documentation inside your editor. ## Prerequisites Before you begin, make sure you have: - **Cursor Pro plan or above** - MCP is not available on the free Hobby plan. - **Internet connection** - Required to reach [docs.finix.com](https://docs.finix.com/). ### Installing Cursor If you don't have Cursor installed yet, download it from the [official Cursor website](https://www.cursor.com) and follow the installation instructions for your platform. ## Quick setup Add the Finix MCP server using the Cursor user interface or by editing the MCP configuration file. ### Option A: Cursor user interface 1. Open Cursor Settings (**Cmd / Ctrl + Shift + J** on Mac, or click the gear icon). 2. Navigate to **Tools & MCP**. 3. Click **+ Add new MCP server**. 4. Enter the following details: - **Name** - `finix-redocly-mcp` - **URL** - `https://docs.finix.com/mcp` 5. The server appears in the MCP list with a green status indicator when connected. ### Option B: MCP configuration file Create or edit `.cursor/mcp.json` in your project root: ```json .cursor/mcp.json { "mcpServers": { "finix-redocly-mcp": { "url": "https://docs.finix.com/mcp" } } } ``` Cursor has detected the configuration update. No restart is required. The Finix MCP server's `search` tool finds results in both the API Reference and Guides. Detailed retrieval tools (`get-endpoint-info`, `get-endpoints`, `get-full-spec-document`) are only available in the API Reference. See [Enhancing Guide Access](#enhancing-guide-access) to configure the agent for full access to the Finix documentation. ## Enhancing guide Access The MCP server can search guides but lacks a tool to retrieve their full content. To give Cursor full access to both API docs and guides, add the following to your project's Cursor rules (`.cursor/rules` file) or system prompt: ```markdown ## Finix Documentation Access When answering questions about Finix: 1. Use the Finix MCP server tools (`search`, `get-endpoint-info`, `get-endpoints`) to find relevant API reference content. 2. For guide/tutorial content: after using the MCP `search` tool to find relevant guide pages, fetch the full content by appending `.md` to the guide URL. For example: - `https://docs.finix.com/guides/getting-started/developer-quickstart.md` - `https://docs.finix.com/guides/online-payments/payment-tokenization/tokenization-forms.md` - `https://docs.finix.com/guides/payouts/adding-funds.md` 3. Always check both API Reference and Guides for a complete answer. ``` This lets Cursor access Markdown guides and API references via MCP, ensuring full access to Finix docs. ## Verify the connection After adding the MCP server, verify it is working: ### Check MCP status 1. Open Cursor Settings (**Cmd / Ctrl + Shift + J**). 2. Navigate to **Tools & MCP**. 3. Confirm `finix-redocly-mcp` shows a green status indicator. ### Test a query Open a Cursor chat session and ask a question about Finix. #### API reference test > *"What authentication method does the Finix API use?"* If Cursor responds with specific details about Finix API authentication (Basic Auth with API credentials), the connection is working. #### Guide Access test > *"How do I onboard a seller on Finix?"* If Cursor responds with details from the seller onboarding guide (not just API endpoint info), guide access is working correctly. ## Configuration options ### Project-Level configuration To share the Finix MCP server with your team, add the following MCP configuration to your project and commit it to your repo: ```json .cursor/mcp.json (project root) { "mcpServers": { "finix-redocly-mcp": { "url": "https://docs.finix.com/mcp" } } } ``` This makes the MCP server available to anyone who opens the project in Cursor. ### Global configuration Make the Finix MCP server available across all your projects by adding the MCP configuration to your home directory: ```json ~/.cursor/mcp.json { "mcpServers": { "finix-redocly-mcp": { "url": "https://docs.finix.com/mcp" } } } ``` ### Toggle without removing Enable or disable the Finix MCP server from **Settings > Tools & MCP** without deleting the configuration. This lets you disable the server temporarily without losing your setup. ## Using Finix MCP Once configured, Cursor uses the MCP server when you ask Finix-related questions in chat or via the agent. ### Example prompts **API Questions:** > *"What fields are required to create a Transfer?"* *"How do I tokenize a card with Finix.js?"* *"What's the difference between a Transfer and an Authorization?"* **Integration Help:** > *"Show me an example of processing a refund."* *"How do I set up webhooks for payment status updates?"* *"What are the steps to onboard a seller?"* **Troubleshooting:** > *"What does error code 402 mean?"* *"What does the RETURNED state mean for a Transfer?"* *"How do I handle declined payments?"* ### Best practices For best results: 1. **Be specific** - "How do I create a card Authorization?" is better than "How do payments work?" 2. **Reference API resources** - Use terms like "Transfer", "Authorization", "Identity", "Merchant" when relevant. 3. **Ask for examples** - "Show me an example of..." prompts Cursor to pull code samples from documentation. 4. **Mention the environment** - Specify "Sandbox" or "Production" if it matters for your question. ## Troubleshooting ### Server not connecting If the Finix MCP server does not show a green status indicator: 1. **Check the URL** - Verify the URL is exactly `https://docs.finix.com/mcp`. 2. **Check internet connection** - Verify you can access [docs.finix.com](https://docs.finix.com/) in a browser. 3. **Check your plan** - MCP requires a Cursor Pro plan or above. ### Connection errors If Cursor reports connection issues: 1. **Check for firewall or proxy issues** - Corporate networks may block MCP connections 2. **Check MCP logs** - Open the Output panel (**Cmd / Ctrl + Shift + U**) and select **MCP Logs** from the dropdown to see detailed error messages 3. **Try the mcp-remote bridge** - If you experience transport negotiation issues, use the `stdio` bridge as a workaround: ```json .cursor/mcp.json { "mcpServers": { "finix-redocly-mcp": { "command": "npx", "args": ["-y", "mcp-remote", "https://docs.finix.com/mcp"] } } } ``` ### Cursor not using Finix documentation If Cursor seems to guess instead of searching the documentation: 1. **Be explicit** - Try "Search the Finix documentation for..." in your prompt. 2. **Check MCP is enabled** - Go to **Settings > Tools & MCP** and verify the server is enabled. 3. **Start a new chat** - Sometimes a fresh chat session helps. ### Cursor only returning API reference (no guide content) If Cursor answers with only API endpoint details and misses relevant guide content, 1. **Add Cursor rules** - See the [Enhancing Guide Access](#enhancing-guide-access) section above to instruct Cursor to fetch guide Markdown files. 2. **Ask explicitly** - Try "Check the Finix guides for how to..." to prompt Cursor to search for guide content. ### Outdated information The MCP server uses Finix's published documentation. If you find any outdated information: - Check [docs.finix.com](https://docs.finix.com) for the latest published documentation. - If you notice a discrepancy, contact the [Finix Support Team](mailto:support@finix.com) or your Finix representative for a definitive answer. The MCP server always shows the latest information from [docs.finix.com](https://docs.finix.com), which is updated regularly. ## Removing the MCP server To disconnect Cursor from Finix documentation: 1. Open Cursor Settings (**Cmd / Ctrl + Shift + J**). 2. Navigate to **Tools & MCP**. 3. Remove `finix-redocly-mcp` from the list. Or delete the `finix-redocly-mcp` entry from your `.cursor/mcp.json` file. ## Set up on other platforms Connect ChatGPT to Finix MCP Connect ChatGPT to the Finix MCP server for documentation-based answers. Connect Claude to Finix MCP Use Claude Code with Finix MCP for documentation-based answers. Connect Gemini to Finix MCP Connect the Gemini CLI to the Finix MCP server for documentation-based answers. --- # Connect Gemini to Finix MCP Source: https://docs.finix.com/additional-resources/developers/mcp-server/mcp-gemini-setup Gemini Logo This guide walks you through connecting the Gemini CLI to the Finix MCP server. After setup, you can ask Gemini questions about Finix and get answers from our documentation. ## Prerequisites Before you begin, make sure you have: - **Node.js 20.0.0 or later**. - **A Google account** - The free tier (Gemini Code Assist for individuals) works; no Google Cloud project needed. - **Internet connection** - Required to reach [docs.finix.com](https://docs.finix.com). ### Installing the gemini CLI If you do not have the Gemini CLI installed yet: ```bash Install Gemini CLI npm install -g @google/gemini-cli ``` After installing, run `gemini` and select **Sign in with Google** to authenticate via your browser. Alternatively, set a `GEMINI_API_KEY` environment variable from [Google AI Studio](https://aistudio.google.com) to avoid browser-based authentication. Refer to the [Gemini CLI documentation](https://github.com/google-gemini/gemini-cli) for detailed installation instructions. ## Quick setup Add the Finix MCP server with a single command: ```bash Add Finix MCP Server gemini mcp add --transport http finix-redocly-mcp https://docs.finix.com/mcp ``` The Gemini CLI now accesses Finix documentation. The Finix MCP server's `search` tool finds results in both the API Reference and Guides. Detailed retrieval tools (`get-endpoint-info`, `get-endpoints`, `get-full-spec-document`) are only available in the API Reference. See [Enhancing Guide Access](#enhancing-guide-access) to configure the agent for full access to the Finix documentation. ## Enhancing guide Access The MCP server can search guides but lacks a tool to retrieve their full content. To give Gemini full access to both API docs and guides, add the following to your project's `GEMINI.md` file or system prompt: ```markdown ## Finix Documentation Access When answering questions about Finix: 1. Use the Finix MCP server tools (`search`, `get-endpoint-info`, `get-endpoints`) to find relevant API reference content. 2. For guide/tutorial content: after using the MCP `search` tool to find relevant guide pages, fetch the full content by appending `.md` to the guide URL. For example: - `https://docs.finix.com/guides/getting-started/developer-quickstart.md` - `https://docs.finix.com/guides/online-payments/payment-tokenization/tokenization-forms.md` - `https://docs.finix.com/guides/payouts/adding-funds.md` 3. Always check both API Reference and Guides for a complete answer. ``` This lets Gemini access Markdown guides and API references via MCP, ensuring full access to Finix docs. ## Verify the connection After adding the MCP server, verify it is working: ### Check MCP status ```bash List MCP Servers gemini mcp list ``` You should see `finix-redocly-mcp` listed among configured servers. ### Test a query Start a Gemini CLI session and ask a question about Finix: ```bash Start Gemini CLI gemini ``` #### API reference test Then try a test prompt: > *"What authentication method does the Finix API use?"* If Gemini responds with exact details about Finix API authentication (Basic Auth with API credentials), the connection is working. #### Guide Access test > *"How do I onboard a seller on Finix?"* If Gemini responds with details from the seller onboarding guide (not just API endpoint info), guide access is working correctly. ## Configuration options ### Project-Level configuration To add the Finix MCP server only to a specific project, navigate to your project directory and run the `gemini mcp add` command: ```bash Project-Level Setup cd /path/to/your/project gemini mcp add --transport http finix-redocly-mcp https://docs.finix.com/mcp -s project ``` This creates a `.gemini/settings.json` file in your project, making the MCP server available only in that directory. ### Global configuration To make the Finix MCP server available in all your projects: ```bash Global Setup gemini mcp add --transport http finix-redocly-mcp https://docs.finix.com/mcp -s user ``` ### Manual configuration You can manually edit your Gemini configuration file. - **Global location** - `~/.gemini/settings.json` - **Project location** - `.gemini/settings.json` Add the Finix MCP server to the `mcpServers` section: ```json settings.json { "mcpServers": { "finix-redocly-mcp": { "httpUrl": "https://docs.finix.com/mcp" } } } ``` After editing, restart Gemini CLI to apply the changes. ## Using Finix MCP Once configured, Gemini automatically uses the MCP server when you ask Finix-related questions. ### Example prompts **API Questions:** > *"What fields are required to create a Transfer?"* *"How do I tokenize a card with Finix.js?"* *"What's the difference between a Transfer and an Authorization?"* **Integration Help:** > *"Show me an example of processing a refund."* *"How do I set up webhooks for payment status updates?"* *"What are the steps to onboard a seller?"* **Troubleshooting:** > *"What does error code 402 mean?"* *"What does the RETURNED state mean for a Transfer?"* *"How do I handle declined payments?"* ### Best practices For best results: 1. **Be specific** - "How do I create a card Authorization?" works better than "How payments work?" 2. **Reference API resources** - Utilize terms like "Transfer", "Authorization", "Identity", "Merchant" when relevant. 3. **Ask for examples** - "Show me an example of..." prompts Gemini to pull code samples from documentation. 4. **Mention the environment** - Specify "Sandbox" or "Production" if it matters for your question. ## Troubleshooting ### MCP server not found If `gemini mcp list` doesn't show `finix-redocly-mcp`: 1. Re-run the `gemini mcp add` command: ```bash gemini mcp add --transport http finix-redocly-mcp https://docs.finix.com/mcp ``` 2. Check that your configuration file exists and has valid JSON. ### Connection errors If Gemini reports connection issues: 1. **Check internet connection** - Verify you can access [docs.finix.com](https://docs.finix.com/) from a browser. 2. **Check firewall/proxy issues** - Corporate networks may block MCP connections. 3. **Try removing and adding again**: ```bash Reset Connection gemini mcp remove finix-redocly-mcp gemini mcp add --transport http finix-redocly-mcp https://docs.finix.com/mcp ``` ### MCP issues detected at startup When starting a session, if Gemini shows: > *"MCP issues detected. Run /mcp list for status."* Perform the following: 1. Run `/mcp list` inside the session to see detailed diagnostics. 2. Verify the MCP server URL is correct in your configuration. 3. Check that [docs.finix.com](https://docs.finix.com/) is reachable from your network. ### Gemini not using Finix documentation If Gemini guesses instead of searching the documentation: 1. **Be explicit** - Try "Search the Finix documentation for..." in the prompt. 2. **Check MCP is enabled** - Run `gemini mcp list` to verify the server is configured. 3. **Restart Gemini CLI** - A fresh session can help. ### Gemini only returning API reference (no guide content) If Gemini answers with only API endpoint details and misses guide content: 1. **Add the `GEMINI.md` instructions** - See the [Enhancing Guide Access](#enhancing-guide-access) section above to have Gemini fetch full Markdown files. 2. **Ask explicitly** - Try "Check the Finix guides for how to..." to prompt Gemini to search for guide content. ### Outdated information The MCP server uses Finix's published documentation. If you find any outdated information: - Check [docs.finix.com](https://docs.finix.com) for the latest published documentation. - If you notice a discrepancy, contact the [Finix Support Team](mailto:support@finix.com) or your Finix representative for a definitive answer. The MCP server always shows the latest information from [docs.finix.com](https://docs.finix.com), which is updated regularly. ## Removing the MCP server To disconnect Gemini CLI from the Finix MCP server: ```bash Remove Finix MCP Server gemini mcp remove finix-redocly-mcp ``` ## Set up on other platforms Connect ChatGPT to Finix MCP Connect ChatGPT to the Finix MCP server for documentation-based answers. Connect Claude to Finix MCP Use Claude Code with Finix MCP for documentation-based answers. Connect Cursor to Finix MCP Connect Cursor to the Finix MCP server for answers inside your editor. --- # Migrating Data to Finix Source: https://docs.finix.com/additional-resources/developers/migrating-data-to-finix Learn how to migrate your existing data into Finix without any disruptions. If you’ve used another payment provider, Finix makes it easy to import your customers’ data and tokenized payment details into your account. By migrating this data, you can continue charging customers without disruptions or asking them to re-enter their payment information. ## Learn more Migrating Customer Data Learn how to migrate your existing customer data into Finix. Migrating Payment Data Learn how to migrate your existing payment data into Finix. PGP Key Learn how to securely encrypt and migrate sensitive payment data with Finix's PGP Key. --- # Migrating Customer Data Source: https://docs.finix.com/additional-resources/developers/migrating-data-to-finix/migrating-customer-data Learn what's required to migrate your customer data from another payment provider over to Finix. Along with [migrating payment data](/additional-resources/developers/migrating-data-to-finix/migrating-payment-data), you can migrate your merchants' data to Finix (e.g., name, address). Migrating your merchants' data can minimize payment processing disruptions by getting your merchants onboarded to Finix as fast as possible. ## Required data To migrate and underwrite sellers, Finix requires the info listed under [Required Onboarding Data](#required-onboarding-data). - If you have the onboarding data listed saved for your sellers, see [Migrating Customers using the Finix API](#migrating-customers-using-the-finix-api). - If you don’t have the required information, or it’s incomplete, see [Migrating Customers using Onboarding Forms](#migrating-customers-using-onboarding-forms). ## Migrating customers using the Finix API If you have all the [required data](#required-onboarding-data) listed available in your database, you can programmatically onboard sellers and create the `Merchant` accounts they will use to process payments with Finix. ### Step 1: Confirm required data availability Confirm that you have all the information listed under [Required Onboarding Data](#required-onboarding-data) available for the sellers you want to migrate. ### Step 2: Build a modal on your platform Build a modal on your platform to inform sellers about the upcoming changes with Finix. - The modal should also present any of the platform's updated Terms of Service or Privacy Policies. - Make sure the modal can also record the seller's consent to the changes on your platform. ### Step 3: Create an Identity request Using Python or your preferred programming language, create a script to programmatically submit [Create Identity requests](/api/identities/createidentity) each time a seller consents to the changes on your platform. Use the information you have on file to complete `entity` and the information collected by the modal to complete `additional_underwriting_data`. ### Step 4: Create a Merchant request As seller `Identities` get created, programmatically create a `Merchant` record using the new `Identity` resource to submit the seller for underwriting. - If a seller is `APPROVED`, and you can use the `Merchant` to create payments and process transactions on behalf of the seller. - If a seller is `UPDATE_REQUESTED`, fetch the `Verification` listed on the `Merchant` to handle next steps. See [Seller Onboarding Update Requests](/guides/platform-payments/onboarding-sellers/seller-onboarding-update-requests) for more information. - If a seller is `REJECTED`, it is possible that Finix will be unable to approve and process payments on behalf of the Merchant. See [Seller Rejections](/guides/platform-payments/onboarding-sellers/seller-rejections) for more information. ### Example migration with the Finix API For example, consider a music equipment reseller that signs up to process payments with Finix. The platform offers sellers a dashboard where they can log in to manage their account. To migrate their customer's data, the platform creates a three-screen modal that pops up for every seller when they login to their dashboard for the first time after the change. The screens of the modal are as follows: 1. **Explanation:** The first screen explains that the platform is changing payment processors. 2. **Platform Terms of Service and Privacy Policy:** The second screen presents the platform's updated Terms of Service and Privacy Policy. 3. **Finix's Terms of Service:** The third screen presents Finix's Terms of Service to sellers. To close the modal, the seller marks their consent to the presented terms, via their signature, a checkbox, or any other method. When the seller marks their consent, the platform programmatically submits a [Create an `Identity`](/api/identities/createidentity) request to Finix. The platform uses the information on file to complete the `entity` and utilizes information collected by the modal and anything else on file to complete `additional_underwriting_data`. When the platform receives the response with the `Identity` resource, it programmatically creates and submits a [Create a `Merchant`](/api/merchants/createmerchant) request to Finix. - If the seller is `APPROVED`, the platform can use it to create and process payments for the seller. - If the seller is `UPDATE_REQUESTED`, the platform programmatically sends an automated email to the seller requesting the missing information. - If the seller is `REJECTED`, the platform reviews the Verification and reaches out to Finix for more information as needed. ## Migrating customers using Onboarding Forms If you don't have the required information for your sellers or it's incomplete, you can migrate customers and collect the missing information using Finix Onboarding Forms. ### Step 1: Export Seller data For existing sellers, export their data into a CSV file. Make sure that in the CSV: - The required data is separated by commas. - The order of the data fields is the same and consistent for all sellers. ### Step 2: Send CSV data to Finix Send the CSV file to the [Finix support team](mailto:support@finix.com). The Finix support team will use internal tools and scripts to migrate the data and create onboarding forms for each individual seller. Also, ensure that Finix has the latest version of the following information: - **Fee URL:** A web page that describes your platform/customer's fee structure to the seller. - **Return URL:** The web page the seller is taken to after they submit the onboarding form. - **Terms of Service URL:** A link to your platform's terms of service. - **Expired Session URL:** The web page the seller is taken to if the form link expires. ### Step 3: Receive Onboarding Form information Finix support will send you a new CSV file with two new columns: - Column 1: Onboarding Form ID - Column 2: Onboarding Form link ### Step 4: Send Onboarding Form Link to Merchants/Sellers Send the pre-filled onboarding form link to your merchants/sellers. They will use the onboarding form to confirm the pre-filled information, fill out any missing information, and consent to your platform's terms of service and privacy policy, Finix's terms of service and privacy policy, and your platform's pricing terms. ### Step 5: Seller submits form The seller fills out any missing information, marks their consent, and submits the onboarding form. ### Step 6: Finix underwriting Finix will then proceed with the underwriting process for the migrated merchants/sellers. - If a seller is `APPROVED`, and you can use the `Merchant` to create payments and process transactions on behalf of the seller. - If a seller is `UPDATE_REQUESTED`, fetch the `Verification` listed on the `Merchant` to handle next steps. See [Seller Onboarding Update Requests](/guides/platform-payments/onboarding-sellers/seller-onboarding-update-requests) for more information. - If a seller is `REJECTED`, it is possible that Finix will be unable to approve and process payments on behalf of the Merchant. See [Seller Rejections](/guides/platform-payments/onboarding-sellers/seller-rejections) for more information. ### Example migration with the Finix API 1. Finix Customer uses SQL to pull required fields from their database and places those required fields into a CSV file. 2. The Finix Customer sends the CSV file to Finix Support. 3. Finix Support uses the information provided to programmatically create Onboarding Forms unique to each seller. 4. Finix Support updates the CSV with two new columns; one with a link to the seller's onboarding form and the ID of the `onboarding_form` that was created. 5. When the customer receives the updated CSV, they run a Python script (or the language of their choice) to create and send individual emails to each seller that includes the link to their unique onboarding form. The Finix customer uses the Finix dashboard to track approved, provisioned, and rejected sellers. The Finix customer also uses the dashboard to resend links and track onboarding forms not yet submitted. ## Required Onboarding data To see the data Finix requires for onboarding merchants, see [Onboarding Data](/guides/platform-payments/onboarding-sellers/seller-onboarding-data). --- # Migrating from Stripe Source: https://docs.finix.com/additional-resources/developers/migrating-data-to-finix/migrating-from-stripe In this article, we'll guide you through migrating your payment and customer data from Stripe and importing it to Finix, ensuring a smooth transition that minimizes disruptions to your customers and business operations. ## Migration overview To migrate your platform's tokenized payment data to Finix, you'll need to: 1. [Integrate with Finix](#step-1-integrate-with-finix) and prepare your account. 2. [Prepare your data](#step-2-prepare-your-data) and verify the information is accurate. 3. [Contact Finix](#step-3-contact-finix) and let us know you want to migrate tokens and payment data from Stripe. 4. [Reach out and notify Stripe](#step-4-notify-stripe) that you want to migrate your tokens and payment data to Finix. 5. [Finix will work with you and Stripe](#step-5-finix-imports-data) to receive the encrypted Primary Account Numbers (PANs) and other payment details. Once received, Finix will work with you to import the tokens and other payment details into your Finix account. 6. [When the import process is complete](#step-6-verify-migrated-data), Finix will follow up with a file that contains the new Finix payment tokens and how they map to Stripe's tokens. ## Step 1: Integrate with Finix To integrate with Finix and set up your account, check out our [Developer Quickstart](/guides/getting-started/developer-quickstart). For platforms and marketplaces, see the [Platform Quickstart](/guides/platforms/platform-qsg/) to get started. ### Tokenizing cards and bank accounts Similar to Stripe, Finix has a Javascript library available to help you collect payment data without letting the sensitive data touch your servers. - See [Tokenization Forms](/guides/online-payments/payment-tokenization/tokenization-forms) for details on how to securely accept payments on the web. - See [iOS](/guides/online-payments/payment-tokenization/mobile-tokenization-ios) or [Android](/guides/online-payments/payment-tokenization/mobile-tokenization-android) Mobile Tokenization articles for details on how to securely accept payments in your mobile app. - See [Raw Card Data](/guides/online-payments/payment-tokenization/handling-raw-card-data) if you have a Level 1 PCI-compliant card data environment (CDE). Establishing how you'll accept payment details with Finix early is helpful in case you need to request payment details from a buyer or seller again. ### Low code products Finix has a number of low code products to make it easy to transition from Stripe. - **[Payment Links](/low-code-no-code/payment-links):** Payment links create individual links you can send to buyers to complete a transaction. You can share these links on web pages, email, text, or QR codes. - **[Subscriptions](/guides/subscriptions/subscriptions-quickstart):** Set up recurring payments using no-code tools, manage changes at scale with bulk updates, customize plans by applying one-off pricing changes, and more. ### Stripe field mappings To help you build out your payments integration, here's a short summary of the fields of Finix's API and how they map to Stripe. See [Finix's API reference](/api) for a detailed breakdown of our API. #### Finix's Payment Instrument stores card and bank data A `Payment Instrument` represents your buyer's or seller's payment method. To implement this in your integration, see our guide on [Create a Payment Instrument](/api/payment-instruments/createpaymentinstrument). The Finix `Payment Instrument` resource corresponds to the following Stripe resources: - [Stripe's `payment_methods`](https://docs.stripe.com/api/payment_methods/object) - [Stripe's `bank_accounts`](https://docs.stripe.com/api/payment_methods/object) - [Stripe's `cards`](https://docs.stripe.com/api/cards) #### Finix's Identity stores data for buyers and sellers An `Identity` is required for either processing payments or onboarding sellers. The Finix `Identities` resource corresponds to: - [Stripe's `customer`](https://docs.stripe.com/api/customers): This object represents a customer of your business. Use it to create recurring charges, save payment and contact information, and track payments that belong to the same customer. - [Stripe's `account`](https://docs.stripe.com/api/accounts): This is an object representing a Stripe account. You can retrieve it to see properties on the account like its current requirements or if the account is enabled to make live charges or receive payouts. #### Merchant resources The Finix `Merchant` resource corresponds to [Stripe's `account` resource](https://docs.stripe.com/api/v2/core/accounts?api-version=2025-04-30.preview). A `Merchant` resource is essential for sellers to process payments. For implementation details, see our guide on [onboarding sellers](/guides/platform-payments/onboarding-sellers). ## Step 2: Prepare your data When migrating from Stripe to Finix, you should focus on aggregating and exporting your payment data to send to Finix. Payment data is the secured payment details of your customers, also called Primary Account Number data (or PAN data for short). PAN data includes secured credit and debit card details, bank account numbers, expiration dates, CVV, security codes, and other payment details saved for your customers on Stripe. To prepare your data for migration, start by reviewing the details of your customers in Stripe's dashboard and verify all their information is accurate. ### Platforms and marketplaces Platforms and marketplaces will also need to export their customer profile data. Use the **Connected Accounts** page in Stripe's Dashboard or the [accounts API](https://docs.stripe.com/api/accounts) resource to export the details of your sellers. Customer profile data includes the details of your sellers, like the name(s), email address, physical address, and merchant category code (MCC). If you run into any issues migrating your seller data, please reach out to [Finix Support Team](mailto:support@finix.com) or your Finix point of contact. Migrating this data will help ensure there are no issues migrating sellers. If you have any questions about sellers or what information to export, reach out to the [Finix Support team](/guides/getting-started/support-at-finix/) or your Finix point of contact. ## Step 3: Contact Finix When you're ready to begin migrating your customer and payment data from Stripe, contact your Finix point of contact or the [Finix Support Team](mailto:support@finix.com) to notify us. Once we receive your migration request, Finix will begin making the needed technical preparations. ## Step 4: Notify Stripe Reach out to [Stripe support](https://support.stripe.com/contact/login?email=true&subject=Migration+away+from+Stripe) with your account details and let them know you'd like to migrate all your payment data to Finix. Be sure to: - Explicitly state you're seeking to export payment data with the intention of migrating off of Stripe and over to Finix. - Include your Finix point of contact or Finix support on your request. Including Finix on the request to keep us in the loop will help give our team permission to start working on the migration with Stripe. Reach out to your Finix point of contact or the [Finix support team](mailto:support@finix.com) with any information your original processor provided, and we'll work on developing a solution to prepare for your migration. ## Step 5: Finix imports data Once you've submitted the migration request to Stripe, Finix will work with Stripe to ingest the necessary payment data and create `Payment Instruments` and `Identities` from the PAN data for your buyers. ## Step 6: Verify migrated data When the import is complete, Finix will reach out with a CSV that contains the new Finix payment tokens and how they map to the tokens of the original processor. If there's any reason any data can't be used, we'll outline what's wrong and work with you and the original processor to resolve the issue. The import process maps the original processor's token IDs to new Finix `Payment Instruments`, `Identities`, and custom fields. You can then use the newly created `Payment Instruments` and other data in your Finix integration to begin processing payments and building your integration. ### CSV output When the import is complete, Finix will reach out with a CSV that contains the new Finix payment tokens and how they map to the tokens of the original processor. The import process maps the original processor’s token IDs to new Finix token IDs, identities, and custom fields. You can then use the newly created `Payment Instruments` and other data in your Finix integration. #### CSV fields | Field | Description | Example | | --- | --- | --- | | `card_brand` | Brand of the payment card. | `Visa` | | `customer_email` | Customer's email address saved with the original payment provider. | `customer@example.com` | | `error_msg` | Returned when there’s an issue locating an account. Use the details in `error_msg` to reach out to the cardholder and confirm their payment information. After confirming, [create a `Payment Instrument`](/api/payment-instruments/createpaymentinstrument) with the updated details. | `null`, `Account not found` | | `expiration_month` | Payment card's expiration month. | `12` | | `expiration_year` | Payment card's 4-digit expiration year. | `2026` | | `external_customer_id` | Unique ID (from your original provider) to reference a specific customer and their saved payment details. | `cus_abc123def456` | | `external_token_id` | Token ID from your original provider that identifies the customer’s tokenized payment details. | `token-abc123` | | `finix_application_id` | ID of the `Application` linked to the Finix `Payment Instrument`. | `APdoThHn4jjYUSxQf76txAgg` | | `finix_identity_id` | ID of the `Identity` linked to the Finix `Payment Instrument`. | `IDcV3F1FzHB5cT9DoGZLJ39Q` | | `finix_instrument_id` | ID of the Finix `Payment Instrument` created from the tokenized payment data. | `PI8uU6wfi6hqBoWmzm9L4F2b` | | `import_reference_number` | Unique ID generated by Finix to reference a specific import. | `221014_TESTIMPORTHERE007` | | `instrument_last_four` | Last four digits of the payment card. | `4242` | | `is_expired` | Indicates whether the payment card is expired. When `true`, it means the card is expired and cannot be used. Use the [Account Updater](/guides/after-the-payment/account-updater) to get updated information. | `true`, `false` | | `successful` | Indicates if a Finix `Payment Instrument` was created successfully using the tokenized payment data. When `false`, it indicates Finix couldn’t create a `Payment Instrument`. Review the details in `external_customer_id` and try creating a [`Payment Instrument`](/api/payment-instruments/createpaymentinstrument) directly using Finix's API. | `true`, `false` | #### CSV example The CSV will look like this: ```csv Example Payment Migration CSV import_reference_number,finix_instrument_id,finix_identity_id,finix_application_id,successful,external_customer_id,external_token_id,customer_email,instrument_last_four,card_brand,expiration_month,expiration_year,error_msg,is_expired 221014_TESTIMPORTHERE007,PImch9imuQDLamPY1LCRmpsG,IDouBD8vwBFEjV5HvmyWsw2A,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def456,expiredTokenID,jenny.rosen@example.com,4242,UNKNOWN,1,2020,,true 221014_TESTIMPORTHERE007,PIm1QR8aF2a3NH8cmPgQ5x2o,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_edf214abc789,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,PIwi2m5TRh26ZVBXA4DLmSZM,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_123,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,PI85kuV5ySHF4GUDLC9wden7,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_456,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,PI6mfsXjJfHK9z89NNmoZWS1,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_edf214abd789,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,PIrmDHqhYuW1gQXSVV3CxB8H,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_edf214abc789,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,PI4UNNgggfwqZ4eqpHCZHqat,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_nodatafound,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,,IDouBD8vwBFEjV5HvmyWsw2A,APaPLggMvZ6bYCLhbr65MUZ9,False,cus_abc123def456,badTokenID,jenny.rosen@example.com,,,1,2024,Not a valid card number,false ``` With the CSV, you can make the necessary changes to get customers started processing payments on Finix. [Finix’s support team](/guides/getting-started/support-at-finix/) is also available to help guide you through the migration process and help make the changes that need to get made to your platform. ## API mappings ### Payment flow Replace Stripe API calls with equivalent Finix API endpoints: | Feature | Stripe API Endpoint | Finix API Endpoint | | --- | --- | --- | | Create a customer | `POST /v1/customers` | [`POST /identities`](/api/identities/createidentity) | | Save a card | `POST /v1/payment_methods` | [`POST /payment_instruments`](/api/payment-instruments/createpaymentinstrument) | | Attach card to customer | `POST /v1/payment_methods` + attach to customer | [`POST /payment_instruments`](/api/payment-instruments/createpaymentinstrument) + attach to a buyer [`Identity`](/api/identities/createidentity) | | Create a Payment Intent | `POST /v1/payment_intents` | [`POST /authorizations`](/api/authorizations/createauthorization) or [`POST /Transfers`](/api/transfers/createtransfer) | | Capture an authorized payment | `POST /v1/payment_intents/{id}/capture` | [`POST /authorizations/{id}/captures`](/api/authorizations/captureauthorization) | | Void an authorization | `POST /v1/payment_intents/{id}/cancel` | [`POST /authorizations/{id}/void`](/api/authorizations/voidauthorization) | | Create a charge (auto-capture) | `POST /v1/charges` | [`POST /transfers`](/api/transfers/createtransfer) | | Refund a charge | `POST /v1/refunds` | [`POST /transfers/{id}/refunds`](/api/transfers/createtransferreversal) | | Create a connected account | `POST /v1/accounts` | [`POST /identities`](/api/identities/createidentity) + [`POST /merchants`](/api/merchants/createmerchant) | | Webhooks | [Stripe Webhooks](https://docs.stripe.com/webhooks) | [Finix Webhooks](/additional-resources/developers/webhooks/integrating-into-webhooks) | ### Buyer data mappings | Finix Field `Identity` | Stripe Equivalent `Customer` | Description | | --- | --- | --- | | `city` | `customer#address.city` | Optional, the city listed on the buyer's billing address | | `country` | `customer#address.country` | Optional, the country listed on the buyer's billing address | | `email` | `customer#email` | Optional, the buyer's email address | | `first_name` | `customer#name` | Optional, the buyer's first name | | `last_name` | `customer#name` | Optional, the buyer's last name | | `line1` | `customer#address.line1` | Optional, line one of the buyer's billing address | | `line2` | `customer#address.line2` | Optional, line two of the buyer's billing address | | `phone` | `customer#phone` | Optional, buyer's phone number | | `postal_code` | `customer#address.postal_code` | Optional, the zip or postal code listed on the buyer's billing address | | `region` | `customer#address.region` | Optional, the state listed on the buyer's billing address | ### Seller data mappings | Finix Field [`Identity`](https://docs.finix.com/api/identities/createidentity) | Stripe `account` | Description | | --- | --- | --- | | `business_address` | `account#company.address` | Primary address for the legal entity | | `business_name` | `account#company.name` | The seller's legal business name | | `business_phone` | `account#company.phone` | Seller's customer service phone number | | `business_tax_id` | `account#company.tax_id` | Seller's Tax Identification Number (TIN/EIN) | | `business_type` | `account#business_type` | Type of entity: `individual`, `company` | | `default_statement_descriptor` | `account#settings.payments.statement_descriptor` | Description shown on buyer’s bank/card statement | | `dob` | `account#individual.dob` | Control owner's date of birth | | `doing_business_as` | `account#business_profile.name` | Alternate/DBA name of the business | | `email` | `account#individual.email` or `account#email` | Email address of the principal control owner | | `first_name` | `account#individual.first_name` | Legal first name of the control owner | | `incorporation_date` | `account#company.verification.document.issue_date` (approx.) | Date of incorporation – Stripe does not expose directly | | `last_name` | `account#individual.last_name` | Legal last name of the control owner | | `max_transaction_amount` | — | Max transaction size in cents | | `ach_max_transaction_amount` | — | Max ACH transaction size | | `mcc` | `account#business_profile.mcc` | Merchant Category Code (MCC) | | `ownership_type` | `account#company.structure` | Ownership type, e.g., `single_member_llc`, `corporation` | | `personal_address` | `account#individual.address` | Billing address of control owner | | `phone` | `account#individual.phone` | Control owner’s phone number | | `principal_percentage_ownership` | `account#company.owners[].ownership_percent` | Ownership percentage by control person | | `tax_id` | `account#company.tax_id` | TIN/SSN of the business (EIN) | | `title` | | Job title of the control owner | | `url` | `account#business_profile.url` | Public website of the business | --- # Migrating from WePay Source: https://docs.finix.com/additional-resources/developers/migrating-data-to-finix/migrating-from-wepay Learn how to migrate your data from WePay to Finix. In this article, we'll guide you through migrating your payment and customer data from WePay and importing it to Finix, ensuring a smooth transition that minimizes disruptions to your customers and business operations. ## Migration overview To migrate your platform's tokenized payment data to Finix, you'll need to: 1. [Integrate with Finix](#step-1-integration-overview) and prepare your account. 2. [Prepare your data](#step-2-prepare-your-data) and verify the information is accurate. 3. [Contact Finix](#step-3-contact-finix) and let us know you want to migrate tokens and payment data from WePay. 4. [Reach out and notify WePay](#step-4-notify-wepay) that you want to migrate your tokens and payment data to Finix. 5. [Finix will work with you and WePay](#step-5-finix-imports-data) to receive the encrypted Primary Account Numbers (PANs) and other payment details. Once received, Finix will work with you to import the tokens and other payment details into your Finix account. 6. [When the import process is complete](#step-6-verify-migrated-data), Finix will follow up with a file that contains the new Finix payment tokens and how they map to WePay's tokens. ## Step 1: Integration overview See our [Developer Quickstart](/guides/getting-started/developer-quickstart) for details on integrating with Finix and setting up your account. Platforms and marketplaces: See our [Platform Quickstart](/guides/platform-payments/platform-quickstart) for details on how to get your platform started. ### Accepting payment details Similar to WePay's Tokenization JavaScript Library, Finix has a library available to help you collect payment data without letting the sensitive data touch your servers. For more details, see [Accepting Payment Details](/guides/online-payments/payment-tokenization). - See [Tokenization Forms](/guides/online-payments/payment-tokenization/tokenization-forms) for details on how to securely accept payments on the web. - See [Payment Tokenization](/guides/online-payments/payment-tokenization) for details on how to securely accept payments in your mobile app. - See [Raw Card Data](/guides/online-payments/payment-tokenization/handling-raw-card-data) if you have a Level 1 PCI-compliant card data environment (CDE). Establishing how you'll accept payment details with Finix early is helpful in case you need to request payment details from a buyer or seller again. ### WePay field mappings To help you build out your payments integration, here's a detailed breakdown of the fields in WePay's API and how they map to Finix's API. See [Finix's API reference](/api) for a detailed breakdown of our API. #### Payment methods The Finix `Payment Instrument` resource corresponds to two WePay resources: - [WePay's `credit_card`](https://developer.wepay.com/api/api-calls/credit_card) - [WePay's `payment_bank`](https://developer.wepay.com/api/api-calls/payment_bank) A `Payment Instrument` represents your buyer's or seller's payment method. To implement this in your integration, see our guide on [Create a Payment Instrument](/api/payment-instruments/createpaymentinstrument). #### Identity resources The Finix `Identities` resource corresponds to [WePay's `legal_entities` resource](https://dev.wepay.com/api/latest/operation/POST_legal_entities/). This resource represents the personal details of your buyers and sellers. An `Identity` is required for processing payments with both buyers and sellers. To implement identity management, refer to our documentation on [Create an Identity](/api/identities/createidentity). #### Merchant resources The Finix `Merchant` resource corresponds to [WePay's `account` resource](https://dev.wepay.com/api/latest/operation/POST_accounts/). A `Merchant` resource is essential for sellers to process payments. For implementation details, see our guide on [Create a Merchant](/api/merchants/createmerchant). ## Step 2: Prepare your data When migrating from WePay to Finix, you should focus on aggregating and exporting your payment data to send to Finix. Payment data is the secured payment details of your customers, also called Primary Account Number data (or PAN data for short). PAN data includes secured credit and debit card details, bank account numbers, expiration dates, CVV, security codes, and other payment details saved for your customers on WePay. To prepare your data for migration, start by reviewing the details of your customers in WePay's dashboard and verify all their information is accurate. ### Platforms and marketplaces Platforms and marketplaces will also need to export their customer profile data. Customer profile data includes the details of your sellers, like the name(s), email address(es), physical address, and merchant category code (MCC). Migrating this data will help ensure there are no issues migrating sellers. If you have any questions about sellers or what information to export, reach out to the [Finix Support team](/guides/getting-started/support-at-finix/) or your Finix point of contact. ## Step 3: Contact Finix When you're ready to begin migrating your customer and payment data from WePay, contact your Finix point of contact or the [Finix Support Team](mailto:support@finix.com) to notify us. Once we receive your migration request, Finix will begin making the needed technical preparations. ## Step 4: Notify WePay Reach out to [WePay support](https://support.wepay.com/hc/en-us/requests/new) with your account details and let them know you'd like to migrate all your payment data to Finix. You can also submit an export request using WePay's [export form](https://developer.wepay.com/docs/faq/credit-card-migrations#does-wepay-participate-in-credit-card-data-migrations). Be sure to: - Explicitly state you're seeking to export payment data with the intention of migrating off of WePay and over to Finix. - Include your Finix point of contact or Finix support on your request. Including Finix on the request to keep us in the loop will help give our team permission to start working on the migration with WePay. Reach out to your Finix point of contact or the [Finix support team](mailto:support@finix.com) with any information your original processor provided, and we'll work on developing a solution to prepare for your migration. ### Platforms and marketplaces Use the **Customers** page in WePay's Dashboard or the Customer Profile API resource to export the details of your sellers. - [WePay's dashboard](#wepay-dashboard) - [WePay's `account` API resource](#wepay-account-api-resource) If you run into any issues migrating your seller data, please reach out to [Finix Support Team](mailto:support@finix.com) or your Finix point of contact, and they'll help you migrate customer data into your Finix account. #### WePay dashboard Use the **Customers** page of the WePay dashboard to export your seller's data. - For details on how to export your seller data from WePay's dashboard, reach out to [WePay support](https://support.wepay.com/hc/en-us/requests/new). #### WePay account API resource Use the `legal_entities` resource to export your seller's data from WePay's API. More details on the `legal_entities` can be found in WePay's API Reference: [Create a legal entity.](https://dev.wepay.com/api/latest/operation/POST_legal_entities/) ## Step 5: Finix imports data Once you've submitted the migration request to WePay, Finix will work with WePay to ingest the necessary payment data and create `Payment Instruments` and `Identities` from the PAN data for your buyers. The original processor will need to use a PGP key provided by Finix to encrypt data before transmitting it to Finix. See [Finix PGP Key](/additional-resources/developers/migrating-data-to-finix/pgp-key) for Finix's PGP key. If requested, Finix's most recent PCI DSS Attestation of Compliance (AoC) [is available](/guides/managing-operations/security-compliance) by request under a signed non-disclosure agreement with Finix. When Finix receives the PAN data from WePay: - We'll begin decrypting the sensitive payment data in a PCI-compliant environment. - Once decrypted, the team will begin working with you to import the sensitive payment data into your Finix account and help you create `Payment Instruments` and `Identity` accounts for your buyers. It can take anywhere from a few days to several weeks for your original processor to transfer your payment data to Finix, so be sure to accommodate this transition time in your migration plan. ## Step 6: Verify migrated data When the import is complete, Finix will reach out with a CSV that contains the new Finix payment tokens and how they map to the tokens of the original processor. If there's any reason any data can't be used, we'll outline what's wrong and work with you and the original processor to resolve the issue. The import process maps the original processor's token IDs to new Finix `Payment Instruments`, `Identities`, and custom fields. You can then use the newly created `Payment Instruments` and other data in your Finix integration to begin processing payments and building your integration. ### CSV output When the import is complete, Finix will reach out with a CSV that contains the new Finix payment tokens and how they map to the tokens of the original processor. The import process maps the original processor’s token IDs to new Finix token IDs, identities, and custom fields. You can then use the newly created `Payment Instruments` and other data in your Finix integration. #### CSV fields | Field | Description | Example | | --- | --- | --- | | `card_brand` | Brand of the payment card. | `Visa` | | `customer_email` | Customer's email address saved with the original payment provider. | `customer@example.com` | | `error_msg` | Returned when there’s an issue locating an account. Use the details in `error_msg` to reach out to the cardholder and confirm their payment information. After confirming, [create a `Payment Instrument`](/api/payment-instruments/createpaymentinstrument) with the updated details. | `null`, `Account not found` | | `expiration_month` | Payment card's expiration month. | `12` | | `expiration_year` | Payment card's 4-digit expiration year. | `2026` | | `external_customer_id` | Unique ID (from your original provider) to reference a specific customer and their saved payment details. | `cus_abc123def456` | | `external_token_id` | Token ID from your original provider that identifies the customer’s tokenized payment details. | `token-abc123` | | `finix_application_id` | ID of the `Application` linked to the Finix `Payment Instrument`. | `APdoThHn4jjYUSxQf76txAgg` | | `finix_identity_id` | ID of the `Identity` linked to the Finix `Payment Instrument`. | `IDcV3F1FzHB5cT9DoGZLJ39Q` | | `finix_instrument_id` | ID of the Finix `Payment Instrument` created from the tokenized payment data. | `PI8uU6wfi6hqBoWmzm9L4F2b` | | `import_reference_number` | Unique ID generated by Finix to reference a specific import. | `221014_TESTIMPORTHERE007` | | `instrument_last_four` | Last four digits of the payment card. | `4242` | | `is_expired` | Indicates whether the payment card is expired. When `true`, it means the card is expired and cannot be used. Use the [Account Updater](/guides/after-the-payment/account-updater) to get updated information. | `true`, `false` | | `successful` | Indicates if a Finix `Payment Instrument` was created successfully using the tokenized payment data. When `false`, it indicates Finix couldn’t create a `Payment Instrument`. Review the details in `external_customer_id` and try creating a [`Payment Instrument`](/api/payment-instruments/createpaymentinstrument) directly using Finix's API. | `true`, `false` | #### CSV example The CSV will look like this: ```csv Example Payment Migration CSV import_reference_number,finix_instrument_id,finix_identity_id,finix_application_id,successful,external_customer_id,external_token_id,customer_email,instrument_last_four,card_brand,expiration_month,expiration_year,error_msg,is_expired 221014_TESTIMPORTHERE007,PImch9imuQDLamPY1LCRmpsG,IDouBD8vwBFEjV5HvmyWsw2A,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def456,expiredTokenID,jenny.rosen@example.com,4242,UNKNOWN,1,2020,,true 221014_TESTIMPORTHERE007,PIm1QR8aF2a3NH8cmPgQ5x2o,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_edf214abc789,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,PIwi2m5TRh26ZVBXA4DLmSZM,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_123,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,PI85kuV5ySHF4GUDLC9wden7,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_456,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,PI6mfsXjJfHK9z89NNmoZWS1,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_edf214abd789,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,PIrmDHqhYuW1gQXSVV3CxB8H,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_edf214abc789,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,PI4UNNgggfwqZ4eqpHCZHqat,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_nodatafound,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,,IDouBD8vwBFEjV5HvmyWsw2A,APaPLggMvZ6bYCLhbr65MUZ9,False,cus_abc123def456,badTokenID,jenny.rosen@example.com,,,1,2024,Not a valid card number,false ``` With the CSV, you can make the necessary changes to get customers started processing payments on Finix. [Finix’s support team](/guides/getting-started/support-at-finix/) is also available to help guide you through the migration process and help make the changes that need to get made to your platform. ## Appendix ### Buyer data mappings | Finix Field | WePay Equivalent | Description | Finix API Ref | | --- | --- | --- | --- | | `city` | `payments#payment_method.credit_card.card_holder.address.city` | Optional, the city listed on the buyer's billing address | [Create an Identity](/api/identities/createidentity) | | `country` | `payments#payment_method.credit_card.card_holder.address.country` | Optional, the country listed on the buyer's billing address | [Create an Identity](/api/identities/createidentity) | | `email` | `payments#payment_method.credit_card.card_holder.email` | Optional, the buyer's email address | [Create Identity](/api/identities/createidentity) | | `first_name` | `payments#payment_method.credit_card.card_holder.holder_name` | Optional, the buyer's first name | [Create Identity](/api/identities/createidentity) | | `last_name` | `payments#payment_method.credit_card.card_holder.holder_name` | Optional, the buyer's last name | [Create Identity](/api/identities/createidentity) | | `line1` | `payments#payment_method.credit_card.card_holder.address.line1` | Optional, line one of the buyer's billing address | [Create Identity](/api/identities/createidentity) | | `line2` | `payments#payment_method.credit_card.card_holder.address.line2` | Optional, line two of the buyer's billing address | [Create Identity](/api/identities/createidentity) | | `phone` | `payments#payment_method.credit_card.card_holder.phone` | Optional, buyer's phone number | [Create Identity](/api/identities/createidentity) | | `postal_code` | `payments#payment_method.credit_card.card_holder.address.postal_code` | Optional, the zip or postal code listed on the buyer's billing address | [Create Identity](/api/identities/createidentity) | | `region` | `payments#payment_method.credit_card.card_holder.address.region` | Optional, the state listed on the buyer's billing address | [Create Identity](/api/identities/createidentity) | ### Seller data mappings | Finix Field | WePay Equivalent | Description | Finix API Ref | | --- | --- | --- | --- | | `business_address` | `legal_entity#address` | Primary address for the legal entity | [Create Identity](/api/identities/createidentity) | | `business_name` | `legal_entity#legal_entity_name` | The seller's legal business name | [Create Identity](/api/identities/createidentity) | | `business_phone` | `legal_entity#phone` | Seller's customer service phone number | [Create Identity](/api/identities/createidentity) | | `business_tax_id` | `legal_entity#entity_country_info.US.employer_identification_number` | Seller's Nine digit Tax Identification Number (TIN) or Employer Identification Number (EIN) | [Create Identity](/api/identities/createidentity) | | `business_type` | — | The entity type of the seller. Use the respective enum | [Create Identity](/api/identities/createidentity) | | `default_statement_descriptor` | `account#statement_description` | A description of the seller that appears on the buyer's bank or card statement | [Create Identity](/api/identities/createidentity) | | `dob` | `legal_entity#date_of_birth` | The control owner's date of birth | [Create Identity](/api/identities/createidentity) | | `doing_business_as` | `account#name` | Alternate names of the business | [Create Identity](/api/identities/createidentity) | | `email` | `legal_entity#email` | The email address of the principal control owner | [Create Identity](/api/identities/createidentity) | | `first_name` | `legal_entity#name.first` | The legal first name of the control owner | [Create Identity](/api/identities/createidentity) | | `incorporation_date` | `legal_entity#year_of_formation` | The date the company was founded and registered | [Create Identity](/api/identities/createidentity) | | `last_name` | `legal_entity#name.last` | The legal last name of the control owner | [Create Identity](/api/identities/createidentity) | | `max_transaction_amount` | — | The maximum amount (in cents) that can be charged for a single transaction | [Create Identity](/api/identities/createidentity) | | `ach_max_transaction_amount` | — | The maximum amount (in cents) that can be charged for a single ACH transaction | [Create Identity](/api/identities/createidentity) | | `mcc` | `account#industry_code.code` | The Merchant Category Code (MCC) that this merchant will be classified under | [Create Identity](/api/identities/createidentity) | | `ownership_type` | `legal_entity#entity_country_info.US.legal_form` | The legal entities ownership type. Use the respective enum | [Create Identity](/api/identities/createidentity) | | `personal_address` | `legal_entities#controller.address` | The billing address of the control owner | [Create Identity](/api/identities/createidentity) | | `phone` | `legal_entities#controller.phone` | The principal control owner's phone number | [Create Identity](/api/identities/createidentity) | | `principal_percentage_ownership` | — | Percentage of the company owned by the principal control owner | [Create Identity](/api/identities/createidentity) | | `tax_id` | `legal_entities#entity_country_info.US.employer_identification_number` | Pass either the TIN, ITIN, or control owner's SSN | [Create Identity](/api/identities/createidentity) | | `title` | `legal_entities#controller.job_title` | The corporate title of the control owner | [Create Identity](/api/identities/createidentity) | | `url` | `legal_entities#primary_url` | The URL of the seller's public website | [Create Identity](/api/identities/createidentity) | ### Credit card data mappings | Finix Field | WePay Equivalent | Description | Finix API Ref | | --- | --- | --- | --- | | `address` | `payments#payment_method.credit_card.card_holder.address` | The address of the card owner | [Create Payment Instrument](/api/payment-instruments/createpaymentinstrument) | | `expiration_month` | `payments#payment_method.credit_card.expiration_month` | The expiration month of the card | [Create Payment Instrument](/api/payment-instruments/createpaymentinstrument) | | `expiration_year` | `payments#payment_method.credit_card.expiration_year` | The 4-digit expiration year of the card | [Create Payment Instrument](/api/payment-instruments/createpaymentinstrument) | | `identity` | — | The ID of the `Identity` that the payment method should be associated with | [Create Payment Instrument](/api/payment-instruments/createpaymentinstrument) | | `name` | `payments#payment_method.credit_card.card_holder.holder_name` | The name of the card owner | [Create Payment Instrument](/api/payment-instruments/createpaymentinstrument) | | `number` | `payments#payment_method.credit_card.card_number` | The card number (no dashes in between numbers) | [Create Payment Instrument](/api/payment-instruments/createpaymentinstrument) | | `security_code` | `payments#payment_method.credit_card.cvv` | The 3-4 digit security code for the card (i.e. CVV code) | [Create Payment Instrument](/api/payment-instruments/createpaymentinstrument) | | `type` | — | Type of `Payment Instrument` - for cards use **PAYMENT_CARD** | [Create Payment Instrument](/api/payment-instruments/createpaymentinstrument) | ### Bank account data mappings | Finix Field | WePay Equivalent | Description | Finix API Ref | | --- | --- | --- | --- | | `account_number` | `payments#payment_method.payment_bank_us.account_number` | Bank account number | [Create Payment Instrument](/api/payment-instruments/createpaymentinstrument) | | `account_type` | `payments#payment_method.payment_bank_us.account_type` | Bank account type | [Create Payment Instrument](/api/payment-instruments/createpaymentinstrument) | | `bank_code` | `payments#payment_method.payment_bank_us.routing_number` | Bank account routing number | [Create Payment Instrument](/api/payment-instruments/createpaymentinstrument) | | `identity` | — | The ID of the `Identity` that the payment method should be associated with. | [Create Payment Instrument](/api/payment-instruments/createpaymentinstrument) | | `name` | `payments#payment_method.payment_bank_us.account_holder.holder_name` | Name of accountholder or cardholder | [Create Payment Instrument](/api/payment-instruments/createpaymentinstrument) | | `type` | — | Type of `Payment Instrument` | [Create Payment Instrument](/api/payment-instruments/createpaymentinstrument) | --- # Migrating Payments Data Source: https://docs.finix.com/additional-resources/developers/migrating-data-to-finix/migrating-payment-data Learn what's required to migrate your data from another payment provider over to Finix. Transmitting payment details of any kind requires extra PCI considerations. Finix has several resources available to take on those PCI considerations and help platforms bring their customer’s payment details over to Finix from any payment provider. ## Migration overview To migrate your platform’s tokenized payment data to Finix, you’ll need to: 1. [Reach out to Finix](#step-1-reach-out-to-finix) and let us know you’d like to migrate tokens and payment data from your original payment provider. 2. [Reach out and notify the original processor](#step-2-notify-your-original-processor) that you’d like to migrate your tokens and payment data to Finix. 3. [Finix will work with you and the original processor](#step-3-finix-receives-encrypted-pans) to receive the encrypted Primary Account Numbers (PANs) and other payment details. Once received, Finix will work with you to import the tokens and other payment details into your Finix account. 4. [When the import process is complete](#step-4-finix-completes-importing-your-tokens), Finix will follow up with a file that contains the new Finix payment tokens and how they map to the tokens of the original processor. ## Step 1: Reach out to Finix Reach out to Finix and let us know you’d like to migrate payment data from your original provider into Finix. You can reach out to your Finix point of contact or the [Finix support team](mailto:support@finix.com). Once the migration request is made, Finix will begin making the needed technical preparations. ## Step 2: Notify your original processor Reach out to the original processor and let them know you’d like to migrate your tokens to Finix. These requests can often be submitted through your original provider's support channels. Include Finix on the request to keep us in the loop. Reaching out helps give the processor permission to begin working on the migration with Finix. In your request, ask the original processor to provide the encrypted tokens and other payment details in the following file format: | Token Provider | Input Format | | --- | --- | | Adyen | CSV | | Auth.net | CSV | | BBMS (Blackbaud Merchant Services) | TXT (tab separated) | | Bluepay | CSV | | Braintree | CSV | | Celero | CSV | | CSG Forte | CSV | | Cybersource | CSV | | Elavon | CSV | | GoDaddy | CSV | | Heartland | CSV | | MindBody | CSV | | NMI | CSV | | Payrix | CSV | | Payabli | CSV | | Qualpay | CSV | | Spreedly | CSV | | Square | CSV | | Stripe | JSON, CSV | | TSYS | CSV | | VGS | CSV | | WePay | CSV | If your processor isn’t listed, ask them for a sample file or supported formats. Then share that information with your Finix contact or the Finix Support Team, and we’ll work with you to import your tokens. ## Step 3: Finix receives encrypted PANs Finix will work with you and the original processor to receive the encrypted Primary Account Numbers (PANs) and other payment details. The original processor will need to use a PGP key provided by Finix to encrypt data before transmitting it to Finix. See [Finix PGP Key](/guides/business/security-and-compliance/pgp-key/) for Finix's PGP key. - Some processors have policies that limit where they can transmit tokenized data. In these cases, you may need to communicate with the processor directly to ensure Finix receives the required data. - If requested, Finix's most recent PCI DSS Attestation of Compliance (AoC) [is available](/guides/managing-operations/security-compliance) by request under a signed non-disclosure agreement with Finix. It can take anywhere from a few days to several weeks for your original processor to transfer your payment data to Finix, so be sure to accommodate this transition time in your migration plan. ## Step 4: Finix completes importing your tokens When Finix receives the file from the original processor, we’ll begin decrypting the data in a PCI-compliant environment and importing the tokens. If there's any reason the data can't be used, we'll outline what's wrong and work with you and the original processor to resolve the issue. Account Updater enabled by default on imported tokens To ensure a smooth customer experience, Finix will automatically enable [Account Updater](/guides/after-the-payment/account-updater) on imported tokens. ## CSV output When the import is complete, Finix will reach out with a CSV that contains the new Finix payment tokens and how they map to the tokens of the original processor. The import process maps the original processor’s token IDs to new Finix token IDs, identities, and custom fields. You can then use the newly created `Payment Instruments` and other data in your Finix integration. ### CSV fields | Field | Description | Example | | --- | --- | --- | | `card_brand` | Brand of the payment card. | `Visa` | | `customer_email` | Customer's email address saved with the original payment provider. | `customer@example.com` | | `error_msg` | Returned when there’s an issue locating an account. Use the details in `error_msg` to reach out to the cardholder and confirm their payment information. After confirming, [create a `Payment Instrument`](/api/payment-instruments/createpaymentinstrument) with the updated details. | `null`, `Account not found` | | `expiration_month` | Payment card's expiration month. | `12` | | `expiration_year` | Payment card's 4-digit expiration year. | `2026` | | `external_customer_id` | Unique ID (from your original provider) to reference a specific customer and their saved payment details. | `cus_abc123def456` | | `external_token_id` | Token ID from your original provider that identifies the customer’s tokenized payment details. | `token-abc123` | | `finix_application_id` | ID of the `Application` linked to the Finix `Payment Instrument`. | `APdoThHn4jjYUSxQf76txAgg` | | `finix_identity_id` | ID of the `Identity` linked to the Finix `Payment Instrument`. | `IDcV3F1FzHB5cT9DoGZLJ39Q` | | `finix_instrument_id` | ID of the Finix `Payment Instrument` created from the tokenized payment data. | `PI8uU6wfi6hqBoWmzm9L4F2b` | | `import_reference_number` | Unique ID generated by Finix to reference a specific import. | `221014_TESTIMPORTHERE007` | | `instrument_last_four` | Last four digits of the payment card. | `4242` | | `is_expired` | Indicates whether the payment card is expired. When `true`, it means the card is expired and cannot be used. Use the [Account Updater](/guides/after-the-payment/account-updater) to get updated information. | `true`, `false` | | `successful` | Indicates if a Finix `Payment Instrument` was created successfully using the tokenized payment data. When `false`, it indicates Finix couldn’t create a `Payment Instrument`. Review the details in `external_customer_id` and try creating a [`Payment Instrument`](/api/payment-instruments/createpaymentinstrument) directly using Finix's API. | `true`, `false` | ### CSV example The CSV will look like this: ```csv Example Payment Migration CSV import_reference_number,finix_instrument_id,finix_identity_id,finix_application_id,successful,external_customer_id,external_token_id,customer_email,instrument_last_four,card_brand,expiration_month,expiration_year,error_msg,is_expired 221014_TESTIMPORTHERE007,PImch9imuQDLamPY1LCRmpsG,IDouBD8vwBFEjV5HvmyWsw2A,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def456,expiredTokenID,jenny.rosen@example.com,4242,UNKNOWN,1,2020,,true 221014_TESTIMPORTHERE007,PIm1QR8aF2a3NH8cmPgQ5x2o,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_edf214abc789,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,PIwi2m5TRh26ZVBXA4DLmSZM,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_123,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,PI85kuV5ySHF4GUDLC9wden7,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_456,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,PI6mfsXjJfHK9z89NNmoZWS1,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_edf214abd789,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,PIrmDHqhYuW1gQXSVV3CxB8H,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_edf214abc789,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,PI4UNNgggfwqZ4eqpHCZHqat,IDrHeCSZ4ss4f2HjuKFaGqiM,APaPLggMvZ6bYCLhbr65MUZ9,True,cus_abc123def459,card_nodatafound,johnny.rosen@example.com,4242,UNKNOWN,1,2024,,false 221014_TESTIMPORTHERE007,,IDouBD8vwBFEjV5HvmyWsw2A,APaPLggMvZ6bYCLhbr65MUZ9,False,cus_abc123def456,badTokenID,jenny.rosen@example.com,,,1,2024,Not a valid card number,false ``` With the CSV, you can make the necessary changes to get customers started processing payments on Finix. [Finix’s support team](/guides/getting-started/support-at-finix/) is also available to help guide you through the migration process and help make the changes that need to get made to your platform. --- # PGP Key Source: https://docs.finix.com/additional-resources/developers/migrating-data-to-finix/pgp-key Securely encrypt and migrate sensitive payment data. To migrate sensitive data (such as credit card information) to Finix, the data needs to be encrypted with Finix's PGP Key. Encrypting sensitive information with Finix's PGP Key is required for PCI Compliance purposes. After importing our key, you can encrypt files that need to be sent by running `gpg --encrypt --recipient {{key_id}} FILENAME`. If you have any questions, or encounter any issues, please contact the [Finix support team](mailto:support@finix.com). ## PGP key process ### File encryption Use this command to encrypt files. ```shell PGP Encrypt gpg --encrypt --recipient {{key_id}} FILENAME ``` ### PGP values | Field | Value | | --- | --- | | Key ID | `70113824182ECDC4` | | Key Type | RSA | | Key Size | 4096 Bits | | Fingerprint | `F022 952A 8C7C 1155 2E28 968B 7011 3824 182E CDC4` | | User ID | `Finix PGP Key (PCI) ` | ### Finix PGP key ```txt PGP Encrypt -----BEGIN PGP PUBLIC KEY BLOCK----- mQINBGSe5AEBEADdZ1Xn2A/vuLYVPoiZKfqOT3eNCeI3ERJm7PIfYcQhkCK7IERG fVt+uIoLf/jUNJq2anyLhs9wd3ct3xxl0xRXatLXSzTWJXYwF7a4tr0YR+BpNBH9 PskF9E7lX1FlvamOa6SFdG8tgiwiOSdXtFOQqP2PtL4rhhcFSY6XWuPAppDgjsed 4wWEN2cSvbD6VhHFT/9kzZvZcCNaUBk1fRrTXkqyiJ8QW5A9kmh0hXre3gMJMDYM swWb74Cdd3JZoPhCMPKJXeT2RM89Sg0GDpWUmjmkxnsbOSUaATJb2BBQ63jaCfOc H6J4BCkRXxdENKbqZTS5wR4gzD0DywYYsiudfFRF0Pks577GThs1dwPSyJV5wJ79 JOCkmeQ9EHRUMK12LCF9NVJU6qIIvoAiOLWUjUjFmbMBLXCpbkHBajDYP3pjKk52 ZLT9FLvG297KF2bG8pOqmcclVb4mmcYgdzfQYojK6nQQY+MSiYFLLIdqYpzk6f7r iAGzDfxu/e0/9i0B635TOeFoYzB96VxAeltq/WmKVNJ08idqsJMdxelNwD/e6G9V e0IfRNoO3/hpPLA5sYvGSKwPrZWMd8WkU4yF4wxbo5lNCMhCy9ptXjVkjApZOCj1 qhEdIK+dsq4XxPhMs1zQ+/BZiufE4KaR8x/7MBnExGV9DAlKZvWp99hvVQARAQAB tC9GaW5peCBQR1AgS2V5IChQQ0kpIDxzdXBwb3J0QGZpbml4cGF5bWVudHMuY29t PokCVwQTAQgAQQIbAwULCQgHAgIiAgYVCgkICwIEFgIDAQIeBwIXgBYhBPAilSqM fBFVLiiWi3AROCQYLs3EBQJodrnIBQkHmjzHAAoJEHAROCQYLs3EzKMP/3jMi3c1 hfQ1rQTSOL4iY7oY5/DBTUD6BoaSFcREsGuRr+p7y5U7bk1MMPu9iwdA7u9q9aCA 6P2Wqm2858ukktX/nGQFwIvNZDIpXVAbYh3GP6MsGWcwsj+hu6wyWU1pbaIsX4Uk zRzEP+z4aU3fykDkEl4ym98PuIawzSXjO4Ox+ckYfio4uXThH4+eR0kc5Evuh3wY TuIWCD8B72IBcAKTdz0k1DLTp6tYKdWjYsnzBo6/zv+pRG/Oan92QXDWt4xACiXr pxuh1RIIo/KtgGlqgIHgEnQ0uLgGwFqx9Oy1+v8Ha9rBtnPpUSLoVrLUvtFi2eTV VVR7zugRBSwjNx0O/LLYygDEssg8jKpqX3mQjhGdJ0Uqj2XZtGbzAp/O+Dq8djd+ CWvGY15x3GKzL2Y4MLqtG0P4s8NAgrsVquH4JTtDWszjBEqi4c6ApBmYiiibi2J9 qn1yuWGjwFsdn0KTgwzREiomYrLyRvRuKKnOLUBmimy7vbtrI2lj6bsop9Uurfid j5s83nkj1HxO9Ypa/NkNZKqlbkcLpwPgEnlGLTH2+BELmKdfSyMMzU0s4xfUWINW jLyZRF/mtRCtjvkHiaZhjDX6tyVamlnqTQEkWee+r+r4MuN4jX8JinvPIym/4xnm 8jTXMMBrbrY7fFLZt03z3E7P/MiI62wWhW28uQINBGSe5AEBEADqcIE01fBYU3Pl pwnpDMfi4/0aq4zYQuN4jiC3CsjhKPe/XJx0AVxxo7aGAMYBmrBy/SoEwp49hPux 9//g/onFtDc7M8RpEgbpUSCYfs0NliRmP/d3aEuYjmOJ5cfyhEpQ0Bi6q0ZIlgHD 5bQOFZCsquib7jOOD66VJTtlM8TgC6Je/QdrS3gF9oqdvn1bqkjApqIRK17sYDNo NNuMw2Hbr5AC9rqGUpQEU8Ppb5TCkH10uA42iv5bC7L5Hb32BWef1ekkDdnNsu9Q Mv+ze2eV+kffNt7BVy4j5QtI4fZC03lfMxMbKuDLuspKxmDWIfYZUyF29aBxJIiR 9X09vl8BXW3u6r0bredW2nM6sTKOEfgyKbUHRo5ma/5r99NtV0S15BX7QZGsATb1 IWHllfIZqQuM4vC1aLRM7Ze+k6QWjqtZx/LoDDCiSnoAmlsLJW+jnsCMnJkFoh6X 95InFwB9CCPLxELl9vge/l4uApA882vnmklkILZX2CpqGatjGbpYZp+3Ka/9hVle qf4pDjc1fNJc6MN4/JfS5BMT2y/Y5lvPTztqdZ+p+AQYQRtvbKFDF5qsYO3Fkx17 jTMMq9l+i6aDwlpYzkhUT2Cd2ma5u6ntpL2+uSi5lpIKdv1Nf0kZ+6FguK1fQ3XC RzNiLjUtL9wQcCzrTzXKQWMFz1eeLwARAQABiQI8BBgBCAAmAhsMFiEE8CKVKox8 EVUuKJaLcBE4JBguzcQFAmic3kgFCQfAYUcACgkQcBE4JBguzcQpcxAAwoy1G5hC Nct05986qWaFIf9e0wJ9wfnppIfegfgna0rsuknYOQuyiobz4gIRR1qEQnwgDRPh H4XiCQO47p5i4W4kMoAVPyM2jfOF1agJZ/VsaLCPqHkkdMgcHxkHDIvz9Y6nAK1K eHqZNSsHlTXH0D6euK3xrc82mcq/wlFG8uQ3PEqyFVVNdodcxRvKJWWYCcnbx/V/ zLH/zKNhNf5ru7IwzYBgYJ+kEVcd8qnTqvRYspo4fvkyWxzXVsIQPsZrgRtHeoAM TpzRl9SodahyfQS0MwV17wn2WFovc05VmVKhE++Pq0cIA1sb6vsISj6HJ8AUo8gX yqK9xoWGNAtGl+/8AlSpf7rOd4O9JyGVplvAzLwjutkSqgW0qD70Z8Gde3u+xEa2 /TX8q7XbRUdqvQIL5+Zg5sh9S+Ze+aSk51lCDZ0GAmGdTUcfYoyDsbshusOL9jDq VFUF7hkQhZogHQHXZFf0rYTMVrLPCN9uGOSDtwafd6lfVmf5Or+QWDoJfwI0nXpD 6ZXB9UKCAecg5dPypl/r5UFlcsiuSMnM3vZ2ppXNMOTarFJt1jtFmxtEP40csyDB AzjYsa8K72+QBYLXFWI9GT2Amr18idE2ONKTvezC8Qu9ZWE6v3DgEbRNnjuoYV9q UplI0igOfwA2Q7nHGPofmz45AU4K77LkCbY= =+Log -----END PGP PUBLIC KEY BLOCK----- ``` --- # Data Formats by Country Source: https://docs.finix.com/additional-resources/developers/resources-and-payment-flows/data-formats-by-country Learn how to pass in data for each country. ## United States | Field | Description | Format | Example(s) | | --- | --- | --- | --- | | Address Country `country` | Business's or owner's address country | 3 chars (ISO 3166) | `USA` | | Address Postal Code `postal_code` | Business's or owner's address postal code | 5 or 9 digits | `94105`, `94105-3907` | | Address Region `region` | Business's or owner's address state | 2 chars | `CA` | | Bank Account Number `account_number` | Bank account number | 5-17 digits | `1001001234` | | Bank Routing Number `bank_code` | Bank routing number | 9 digits | `026009593` | | Business Phone `business_phone` | Business's phone number | E.164 format | `+12124567890` | | Business Tax ID `business_tax_id` | Employer Identification Number (EIN) | 9 digits | `283748298` | | Business Type `business_type` | Sellers' incorporated business type | Enum | `CORPORATION` | | Owner Email `email` | Owner's email address | Valid email address | `doe@finix.com` | | Owner Phone `phone` | Owner's phone number | E.164 format | `+12124567890` | | Owner Tax ID `tax_id` | Social Security Number (SSN) Individual Taxpayer Identification Number (ITIN) | 9 digits | `283748298` | ## Canada | Field | Description | Format | Example(s) | | --- | --- | --- | --- | | Address Country `country` | Business's or owner's address country | 3 chars (ISO 3166) | `CAN` | | Address Postal Code `postal_code` | Business's or owner's address postal code | 6 chars (plus space) | `A1A 2B2` | | Address Region `region` | Business's or owner's address province / territory | 2 chars | `ON` | | Bank Account Number `account_number` | Bank account number | 5-17 digits | `1001001234` | | Bank Institution Number `institution_number` | Bank institution number | 3 digits | `177` | | Bank Transit Number `transit_number` | Bank transit number | 5 digits | `00006` | | Business Phone `business_phone` | Business's phone number | E.164 format | `+12124567890` | | Business Tax ID `business_tax_id` | Business Number (BN) | 9 digits | `283748298` | | Business Type `business_type` | Sellers' incorporated business type | Enum | `CORPORATION` | | Owner Email `email` | Owner's email address | Valid email address | `doe@finix.com` | | Owner Phone `phone` | Owner's phone number | E.164 format | `+12124567890` | | Owner Tax ID `tax_id` | (**Optional**) Social Insurance Number (SIN) | 9 digits | `283748298` `null` | --- # Resources and Payment Flows Source: https://docs.finix.com/additional-resources/developers/resources-and-payment-flows Learn about Finix's key API Resources and associated payment flows. Finix offers many different API resources, including `Identities` (which cover buyers and sellers) and `Transfers` (which cover any money movements). ## Learn more Data Formats by Country Learn how to pass in data for each country. Key Resources Learn about Finix's different API resources and how they relate to one another. Payment Lifecycle Learn how a payment flows through Finix from Authorization to Settlement. --- # Key Resources Source: https://docs.finix.com/additional-resources/developers/resources-and-payment-flows/key-resources The Finix platform comprises many different resources that fit together. This guide describes Finix's Key Resources are and how they relate to one another. ## Applications Application Resource Chart The `Application` resource represents your own business or platform within the Finix system. As this represents you, it is your root entity in Finix and most resources will include an `application.id` that points back to you. Several resources are direct children of `Applications`, including [`Users`](#users), [`Identities`](#identities), [`Webhooks`](/additional-resources/developers/webhooks), and your [`Application Profile`](#application-profile). We cover these resources in detail below. ## Identities Identities chart The `Identity` resource represents either an individual or business, and stores their information. You will create `Identities` for both the sellers and service providers you board to process payments, as well as their buyers: - For users you board to accept payments (e.g., sellers, service providers, merchants): the `Identity` resource includes Personally Identifying Information (PII) required for compliance and underwriting purposes, and they will go through the [onboarding process](/guides/platform-payments/onboarding-sellers) before they can accept payments. - For their buyers: the `Identity` resource can store [any information you choose to include](/guides/getting-started/developer-quickstart#step-1-create-an-identity-for-your-buyer), such as their names, emails, addresses, or phone numbers. `Identities` are central resources that link many other resources together: - Payments (called `Transfers`) and payment methods (called `Payment Instruments`) get created under and linked with an `Identity`. - The `Identity` resource helps manage payments, payment methods, bank accounts, transaction history, identity verification, and payouts between buyers and sellers. ## Merchants Merchants Chart [The `Merchant` resource](/guides/platform-payments/onboarding-sellers/seller-onboarding-process/) represents the ability for an `Identity` to process payments. An `Identity` can only have one merchant resource. ## Payment Instruments Payment Instruments Chart The `Payment Instrument` object represents a payment method (e.g., credit cards, bank accounts, tokens). When `Payment Instruments` are created, the payment method details get tokenized and stored securely (e.g., the card or bank account number). Each `Payment Instrument` has a unique `id` that represents the payment method in Finix moving forward. Each `Payment Instrument` is [created under an `Identity`](/guides/getting-started/developer-quickstart#step-2-tokenize-payment-details) and can only be linked to that one single `Identity`. Once created, a `Payment Instrument` cannot be disconnected from the `Identity` it was created under, or linked to another `Identity`. ## Transfers Transfers Chart The [`Transfer` resource](/api/transfers) represents ***any*** money movement from one `Payment Instrument` to another. For example, a `Transfer` can be a credit to a bank account, or a refund to a card. `Transfers` appear on the Finix Dashboard under **Transactions**. [`Authorizations` always create `Transfers` when captured](/guides/online-payments/payment-features/auth-and-captures#capturing-an-authorization); however, `Transfers` can get created for other reasons, including processing refunds, reversals, and paying out merchants. `Transfers` can have one of three types, each indicating a different funds flow: 1. `DEBIT`: These are created after [capturing Authorizations](/guides/online-payments/payment-features/auth-and-captures) or [creating ACH (eCheck) payments](/guides/online-payments/bank-payments) where funds are pulled from the issuer into the settlement account. 2. `REVERSAL`: represent [refunds or chargebacks](/guides/after-the-payment/refunds) where funds are returned to customers. 3. `CREDIT`: are created when funds are transferred to a merchant's bank account when [funding / payout out settlements](/guides/platform-payments/seller-payouts). `Transfers` can have six possible states: 1. `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. 2. `SUCCEEDED`: The Transfer was successful, and the funds will soon be available for [Payout](/guides/payouts). The `ready_to_settle_at` field indicates when the `Transfer` will be included and batched into a `Settlement`. 3. `FAILED`: The Payment was declined. Refer to the `failure_code` and `failure_message` for [details on why the transaction was declined](/additional-resources/developers/implementation-and-testing/error-codes/#transfer-and-authorization-errors). 4. `CANCELED`: There was an issue with the processor, please reach out to support. 5. `UNKNOWN`: A connection or timeout issue occurred while the `Transfer` got created or updated. Reattempt the `Transfer`. 6. `RETURNED`: The `Transfer` was returned by the bank, which can happen for ACH transactions (e.g., insufficient funds, invalid account). When a `Transfer` is in this state, the `bank_return_details` object is populated with the `reason_code`, `reason_title`, and `reason_message` explaining why the return occurred. ## Authorizations Authorizations Resource Chart The `Authorization` resource represents a charge or card hold made by a `Merchant` to verify the buyer's payment method has the necessary funds. When an `Authorization` is created, a specific amount gets reserved on the `Payment Instrument` associated with the `Identity` that represents the buyer. That amount is ***captured*** (i.e., debited) at a later date, usually within 7 days. When an `Authorization` gets captured, a `Transfer` resource gets created to process the movement of funds. ## Settlements Settlements chart The `Settlement` resource represents a batch of `Transfers` that will get paid out to a `Merchant`. `Merchants` (i.e., sellers) are paid out when Finix approves them. For more information, see [Payouts](/guides/platform-payments/seller-payouts). ## Users Users Chart A `User` represents: - Dashboard User - API User To Create a dashboard user, reach out to Finix support. ## Files Files Chart The `File` resource represents a [file that is or will be uploaded to Finix](/guides/platform-payments/onboarding-sellers/seller-onboarding-uploading-files). Files can be uploaded for any resource, though this is most often used during onboarding where documents may be required for an `Identity` or a `Merchant`. ## Profiles Profiles Chart Finix uses a concept called "profiles" that enable you to define a root configuration for charging fees, risk settings, and payout schedules. ### Application profile An `Application Profile` stores a base set of profiles: `Fee Profile` and `risk_profile`. Whenever you create a `Merchant`, a new `Merchant Profile` is created with a `Fee Profile` and `risk_profile` that are a copy of the profiles in the `Application Profile`. ### Merchant profile Each `Merchant` will have its own, unique, `Merchant Profile`. Merchant profiles are not shared between merchants. The merchant profile points to the `Fee Profile` and `risk_profile` that applies to the merchant ### Fee Profile A `Fee Profile` specified how you will [charge fees to your seller](/guides/platform-payments/monetizing-payments/collecting-seller-fees) for their specific `Merchant`'s payment processing. The fee profile contains a list of each fee type and the amount you want to charge the merchant. ### Risk profile A `Risk Profile` specifies the risk configuration for a `Merchant`. ### Per-Merchant customization You can change the profiles on a `Merchant Profile` and it will only affect the `Merchant` the `Merchant Profile` is associated to. ## Account structure account structure Finix enables many payment flows but the key account relationships start with your [`Application`](#applications) which is your main account. Your Application will have many [`Identities`](#identities) for your buyers and sellers or service providers. For buyers, their `Identities` will have one or more [`Payment Instruments`](#payment-instruments) for each payment method they save with you. For sellers or service providers, their `Identities` will have one or more [`Payment Instruments`](#payment-instruments) for the bank account their funds are paid out to. They will also have one or more `Merchants` for each payment capability you enable for them, such as enabling both online and in-store payments with one `Identity`. --- # Payment Lifecycle Source: https://docs.finix.com/additional-resources/developers/resources-and-payment-flows/payment-lifecycle Most transactions in Finix follow a similar pattern and lifecycle. The diagram below models out the Payment Lifecycle for Finix: Payments Lifecycle 1. Buyer requests to make a payment with seller. 2. The platform collects the buyers information and creates an `Identity` to represent the buyer in Finix. 3. The platform collects the buyer's payment information and creates a `Payment Instrument` to represent the payment method used by the buyer to complete the payment. Once created, Finix notifies the seller with: > - A webhook which only gets sent when a `Payment Instrument` gets created from a [bank account](/additional-resources/developers/webhooks/webhook-events#payment-instrument-created-bank-account), [debit or credit card](/additional-resources/developers/webhooks/webhook-events#payment-instrument-created-card). - A payment instrument entry on the `Payment Instruments` tab of the [Finix Dashboard](/guides/managing-operations/finix-dashboard). 4. The platform creates an `Authorization` to reserve the funds on the `Payment Instrument` to be captured (i.e. debited) at a later date, usually within seven days. > - An authorization entry also gets added on the `Authorizations` tab of the [Finix Dashboard](/guides/managing-operations/finix-dashboard). 5. If the `Authorization` is successful, `Authorization#state` gets updated to `SUCCEEDED` and `Authorization#expires_at` gets updated with a timestamp. The `Authorization` entry on the `Authorizations` tab of the [Finix Dashboard](/guides/managing-operations/finix-dashboard) also gets updated. > - If the `Authorization` fails, `Authorization#state` gets updated to `FAILED.` The `Authorization` entry on the `Authorizations` tab of the [Finix Dashboard](/guides/managing-operations/finix-dashboard) also gets updated. To proceed, the platform needs to submit the `Authorization` again. 6. The platform captures the `Authorization`. > - A webhook gets sent when the [`Authorization` gets captured](/additional-resources/developers/webhooks/webhook-events#authorization-captured). - The authorization entry gets updated on the `Authorizations` tab of the [Finix Dashboard](/guides/managing-operations/finix-dashboard). 7. Finix creates a `Transfer` to debit and move funds. > - The `id` of the `Transfer` is available in the `Authorization` captured webhook. - A `transaction` entry gets added on the `Transactions` tab of the [Finix Dashboard](/guides/managing-operations/finix-dashboard). 8. When funds get debited, the `Transfer` gets updated with a timestamp in `Transfer#ready_to_settle_at`. > - A webhook gets sent when the [`Transfer` is `ready_to_settle`](/additional-resources/developers/webhooks/webhook-events#transfer-ready-to-settle-5). - The transaction entry gets updated on the `Transactions` tab of the [Finix Dashboard](/guides/managing-operations/finix-dashboard). 9. Once the timestamp in `Transfer#ready_to_settle_at` passes, the `Transfer` will appear in the next `Settlement` that closes and requires approval. > - A webhook gets sent when a [`Settlement` is ready and waiting for your approval](/additional-resources/developers/webhooks/webhook-events#authorization-created). - A settlement entry also gets added on the `Settlements` tab of the [Finix Dashboard](/guides/managing-operations/finix-dashboard). 10. Once the `Settlement` is approved, a funding `Transfer` gets created to credit funds to the seller. > - The settlement entry also gets updated on the `Settlements` tab of the [Finix Dashboard](/guides/managing-operations/finix-dashboard). 11. When the funding `Transfer` gets updated to `SUCCEEDED`, the seller can expect funds to hit their bank account in 5-7 business days (depending on their bank). > - See [Managing Failed Payouts](/guides/platform-payments/seller-payouts/managing-failed-payouts) for details on how to handle a funding `Transfer` that gets updated to `FAILED.` - A webhook gets sent when the [`Transfer` gets updated](/additional-resources/developers/webhooks/webhook-events#transfer-updated-9). --- # Webhooks Source: https://docs.finix.com/additional-resources/developers/webhooks Webhooks let you receive notifications programmatically when your API resources are created or updated. When you subscribe to webhooks, Finix's servers will emit events that your servers can listen for. Webhooks can be helpful by letting your servers know when something has changed automatically, rather than requiring your servers to check. ## Learn more Integrating into Webhooks Learn how to integrate into Finix's webhooks. Webhook Events A comprehensive list of the webhook events that Finix offers. The following guide outlines the webhook message format, the embedded resource in the webhook body will match the latest representation as described on our [API Reference](/api) Webhook Logs View the webhooks that Finix has sent you in the past 30 days. --- # Integrating into Webhooks Source: https://docs.finix.com/additional-resources/developers/webhooks/integrating-into-webhooks Use webhooks to subscribe to automated notifications (also known as events) from Finix. When an event is triggered, Finix sends an HTTP `POST` request to the endpoint URL configured in the webhook. Rather than requiring your servers manually poll Finix's API to learn about changes to your resources, webhooks ***push*** notifications to the endpoint URL to notify you automatically. With webhooks, you can keep up with asynchronous state changes. Examples of changes include: - `Transfer` is created. - `Merchant` is approved. - `Disputes` are won. ## Managing Webhooks via Dashboard Finix also supports creating and updating webhooks through the Finix Dashboard. The dashboard provides the same webhook configuration options as you get [via API](#managing-webhooks-via-api): - **Set URL** - Set the URL you'd like Finix to send webhooks to. - **Set Authentication** - Choose Basic or Bearer authentication (recommended), or no authentication. - **Filter Events** - Subscribe to all events, or choose the specific events you'd like to subscribe to. - **Update Webhooks** - Update existing webhooks (e.g., change the URL or events). - **Disable Webhooks** - Disable existing webhooks you no longer use. ### Viewing Webhooks To create or update webhooks in the dashboard, navigate to **Developer > Webhooks**. There, you will see a list of all webhooks you have created. You will be able to create new webhooks as well as update existing ones. Webhooks List ### Creating Webhooks Click **Create Webhook** to create a new webhook. You'll set the URL, Authentication Type, and Events you'd like to subscribe to. For the full list of events, see [Webhook Events](/additional-resources/developers/webhooks/webhook-events) or create your own webhook with the dashboard. Webhooks Create Webhooks Events ### Editing Webhooks Under **Developer > Webhooks**, navigate to one of your webhook events to view it's current settings. On that page, you can also **Edit** or **Disable** the webhook (for example, to update the events the webhook subscribes to). Webhooks Edit ## Managing Webhooks via API Finix lets you create and update webhooks with Finix's API. This can be helpful for companies that want to manage webhook through their own dashboard or developer tools. When you create a webhook via API, Finix will send an empty test event to the endpoint URL configured in the webhook. The configured URL must respond to this event successfully to let Finix know the URL is valid, at which point Finix will enable the webhook. See [Validating Webhooks](#validating-webhooks) for more information. ### Creating Webhooks without authentication For most integrations, you should [create authenticated webhooks](#creating-authenticated-webhooks) instead. Authentication adds an `Authorization` header that your server validates on every event, and combined with [verifying the `Finix-Signature` header](#verifying-webhook-signatures-finix-signature), it gives you a layered way to confirm events are coming from Finix. Authenticate webhooks in production Use unauthenticated webhooks only for testing your integration in Sandbox. In production, always set an `authentication` type so your server can verify inbound events. To create a webhook with *no authentication*, send a `POST` request to Finix's `/webhooks` endpoint with just the URL. ```bash Request to Create Webhook curl "https://finix.sandbox-payments-api.com/webhooks" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -X POST \ -d '{ "url": "https://webhook.site/73b2d0d3-8cc3-4003-857d-2e3a137887ce" }' ``` ```json Created Webook { "id": "WHid2GDsvQaHhnLQa1HCjNiR", "created_at": "2024-12-31T15:11:43.41Z", "updated_at": "2024-12-31T15:11:43.41Z", "application": "APgPDQrLD52TYvqazjHJJchM", "authentication": { "type": "NONE" }, "enabled": true, "enabled_events": [], "is_accepting_events": true, "nickname": null, "previous_secret_expires_at": null, "secret_signing_key": "1676b0aa7f96e7f2cb3ef92ea266a13a534ad06593e930152343a36d14bdc3c5", "url": "https://webhook.site/************************************", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/webhooks/WHid2GDsvQaHhnLQa1HCjNiR" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" } } } ``` ### Creating authenticated Webhooks When creating a webhook, specify the authentication type (`authentication.type`) that Finix should use when sending events to the endpoint URL. When you add an authentication type, Finix will add an Authorization header to events sent to the configured endpoint URL. Your server can use the Authorization header to verify that the event came from Finix. There are two sets of credentials at play when you create an authenticated webhook; do not mix them up: - **Your Finix API credentials** authenticate the `POST /webhooks` request *to Finix*. These go in the `-u` flag (or your client's auth config), and are the same credentials you use for any other Finix API call. - **The credentials you set on the `authentication` field of the request body** are values *Finix sends to your server* on every event delivery. Pick values your own webhook receiver knows how to validate. Don't put your Finix API credentials in the request body The `username`/`password` under `authentication.basic` and the `token` under `authentication.bearer` are credentials **your own server** validates on incoming webhook events. Do not paste your Finix API key/secret here. If you reuse your Finix credentials, your receiver will be checking against the wrong values, and anyone who learns your webhook auth would also have your Finix API access. Finix supports two authentication types: 1. **Basic Authentication:** Finix will send the webhook event with [Basic Authentication](#basic-authentication). 2. **Bearer Token Authentication:** Finix will send the webhook with a [Bearer Token](#bearer-token-authentication). #### Basic authentication Finix uses the standard [Basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) format. When you set `authentication.type` to `BASIC`, each webhook event is sent with an `Authorization` header formatted as `Authorization: Basic `. Choose the `username` and `password` your webhook receiver expects to validate, and put them in `authentication.basic`. These are credentials Finix will send *to your server* on every event; they are not your Finix API credentials. In the example below, the placeholder values `your-webhook-user` and `your-webhook-password` should be replaced with values you control. ```bash Request to Create Webhook with Basic Authentication curl "https://finix.sandbox-payments-api.com/webhooks" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -X POST \ -d '{ "authentication": { "type": "BASIC", "basic": { "username": "your-webhook-user", "password": "your-webhook-password" } }, "url": "https://webhook.site/73b2d0d3-8cc3-4003-857d-2e3a137887ce" }' ``` In the request above, the `-u` flag is your Finix API credentials (used to authenticate this call to Finix). The values inside `authentication.basic` are credentials of your choosing that Finix will send to your webhook URL. To create the `Authorization` header included in events sent to that URL, Finix: 1. Combines the `username` and `password` with a colon (e.g., `your-webhook-user:your-webhook-password`) 2. Base64-encodes the string (e.g., `eW91ci13ZWJob29rLXVzZXI6eW91ci13ZWJob29rLXBhc3N3b3Jk`) 3. Adds the value to the Authorization Header with the Basic scheme (e.g., `Authorization: Basic eW91ci13ZWJob29rLXVzZXI6eW91ci13ZWJob29rLXBhc3N3b3Jk`) #### Bearer token authentication Finix supports sending [OAuth 2.0 Bearer Tokens RFC 6750](https://www.rfc-editor.org/rfc/rfc6750). These are opaque strings that it is up to your server to interpret. When you set `authentication.type` to `BEARER`, each webhook event is sent with an `Authorization` header formatted as `Authorization: Bearer `. The `token` you put in `authentication.bearer` is a value **you choose** that your webhook receiver validates; it is not a Finix API credential. Finix sends the token to your URL exactly as you provided it, and any further validation is up to your system. ```bash Request to Create Webhook with Bearer Token curl "https://finix.sandbox-payments-api.com/webhooks" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -H 'Accept: application/hal+json' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -X POST \ -d '{ "authentication": { "type": "BEARER", "bearer": { "token": "U3VwZXIgc2VjcmV0IGVuY29kZWQgdG9rZW4=" } }, "url": "https://webhook.site/73b2d0d3-8cc3-4003-857d-2e3a137887ce" }' ``` From this example, your server will receive events with the header `authorization: Bearer U3VwZXIgc2VjcmV0IGVuY29kZWQgdG9rZW4=`. ### Verifying Webhook signatures (`finix-signature`) Along with optional Authorization headers, every webhook event from Finix includes a Finix-Signature header that lets you verify the payload wasn’t tampered with and was sent recently. - Header name: `Finix-Signature` - Format: `timestamp=, sig=` - Algorithm: HMAC-SHA256 over the bytes of the string `":"` - Output encoding: lowercase hex Example: - Finix-Signature: `timestamp=1764948460, sig=0f0250ab7266dbe7a4d4cf7a502c9df1e76683cc739de289e30d0cc01bb8efd5` When you create a webhook, the API response includes a signing key you’ll use to validate future events: - Example signing key: `a1fc2b789d958e8a9a3517c9c8b129d5c2cecedfc68788345aaf9a5b2a859976` #### How the signature is produced 1. Finix takes the Unix epoch second from the header (the `timestamp` value). 2. It builds a string as: `timestamp:body` where `body` is the exact webhook request body as a string (including whitespace and line breaks, exactly as delivered). 3. It computes an HMAC-SHA256 over that string using the signing key. The signing key is used as a UTF‑8 string (not hex‑decoded). #### To validate a Webhook 1. Read the `Finix-Signature` header from the request. 2. Parse out: - `timestamp` (as a number of seconds since Unix epoch) - `sig` (the hex-encoded signature) 3. Ensure the timestamp is recent (for example, within 5 minutes/300 seconds) to protect against replay attacks. 4. Recompute the HMAC-SHA256 of `timestamp:body` using the webhook’s signing key (as a UTF‑8 string). Consider the validation successful if any provided signature exactly matches your computed value (case-insensitive compare or normalize to lowercase). Use a constant-time comparison if available. The following JSON is a webhook body. If this were the body received, it must be used verbatim when recomputing the signature. ```json { "id": "event_7eAz5GUWUGa9sGcToi1Xk3", "system_generated_idempotency_id": "7eAz5GUWUGa9sGcToi1Xk3", "type": "created", "entity": "application_profile", "occurred_at": "2025-12-05T15:27:40.285921482", "_embedded": { "application_profiles": [ { "id": "PP8P6TKwhQFFTz7MMqskzTJn", "created_at": "2025-12-05T15:27:39.86Z", "updated_at": "2025-12-05T15:27:39.86Z", "application": "AP9X9xQrii84kQC5xZaaqRdL", "card_present_fee_profile": null, "fee_profile": null, "risk_profile": "RPpCkzumM6AYti5pTHsV6xpp", "tags": {} } ] } } ``` #### Simple BASH example to verify a signature The example below shows how to recompute and compare the signature using common tools available on macOS/Linux. It treats the signing key as a plain UTF‑8 string (not hex‑decoded) to match Finix’s signing method. ```bash Verify Finix-Signature with bash # 1) Initial setup # Example webhook header: FINIX_SIGNATURE_HEADER='timestamp=1764948460, sig=0f0250ab7266dbe7a4d4cf7a502c9df1e76683cc739de289e30d0cc01bb8efd5' # From the /webhooks API response: SIGNING_KEY='a1fc2b789d958e8a9a3517c9c8b129d5c2cecedfc68788345aaf9a5b2a859976' # Use the actual webhook body (exact bytes, verbatim). Example: BODY='{ "id" : "event_7eAz5GUWUGa9sGcToi1Xk3", "system_generated_idempotency_id" : "7eAz5GUWUGa9sGcToi1Xk3", "type" : "created", "entity" : "application_profile", "occurred_at" : "2025-12-05T15:27:40.285921482", "_embedded" : { "application_profiles" : [ { "id" : "PP8P6TKwhQFFTz7MMqskzTJn", "created_at" : "2025-12-05T15:27:39.86Z", "updated_at" : "2025-12-05T15:27:39.86Z", "application" : "AP9X9xQrii84kQC5xZaaqRdL", "card_present_fee_profile" : null, "fee_profile" : null, "risk_profile" : "RPpCkzumM6AYti5pTHsV6xpp", "tags" : { } } ] } }' # 2) Extract timestamp and signature from the header TS=$(printf "%s" "$FINIX_SIGNATURE_HEADER" | sed -n 's/.*timestamp=\([0-9]*\).*/\1/p') SIG=$(printf "%s" "$FINIX_SIGNATURE_HEADER" | sed -n 's/.*sig=\([^,]*\).*/\1/p' | tr 'A-F' 'a-f') # 3) Recompute HMAC-SHA256 over "timestamp:body" using the signing key as UTF-8 text # Avoid adding extra newlines. We write timestamp, a colon, then the raw body bytes. COMPUTED_SIG=$( { printf "%s:" "$TS"; printf "%s" "$BODY"; } \ | openssl dgst -sha256 -mac HMAC -macopt key:"$SIGNING_KEY" -binary \ | xxd -p -c 256 ) printf "Header sig: %s\n" "$SIG" printf "Computed sig: %s\n" "$COMPUTED_SIG" if [ "$SIG" = "$COMPUTED_SIG" ]; then echo "Signature is valid" else echo "Signature is INVALID" fi ``` Notes - Use the body exactly as received. Any change in whitespace, ordering, or encoding will change the signature. - The signing key should be stored securely. - The comparison above normalizes the header signature to lowercase hex for consistency. ### Filtering Webhooks When configuring webhooks, customers typically subscribe to event types they are interested in and ignore those they are not. By default, newly created webhooks subscribe to a subset of events of interest to many users, such as Transfer creation and updates. Finix supports subscribing to specific webhook events through the webhook's `enabled_events` field to filter events sent to your webhook server. You can provide `enabled_events` when creating or updating a webhook to override the default events. Supported Webhook List See [Webhook Events](/additional-resources/developers/webhooks/webhook-events) for the complete list of events you can subscribe to. In this example, we'll update an existing webhook to enable more events of interest. ```shell curl -i -X PUT \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/webhooks/WHhEyB1GdW8NsP2T7Rv6nfc6 \ -H 'Content-Type: application/json' \ -d '{ "enabled_events": [ { "entity": "authorization", "types": [ "created", "updated" ] }, { "entity": "balance_transfer", "types": [ "created", "updated" ] }, { "entity": "evidence", "types": [ "created" ] }, { "entity": "gateway_integration", "types": [ "created" ] }, { "entity": "merchant", "types": [ "created", "updated" ] }, { "entity": "onboarding_form", "types": [ "created", "updated" ] }, { "entity": "transfer_attempt", "types": [ "created" ] }, { "entity": "verification", "types": [ "created", "updated" ] } ] }' ``` ```json Webhook with Enabled Events Set { "id": "WHhEyB1GdW8NsP2T7Rv6nfc6", "created_at": "2024-12-30T14:01:12.22Z", "updated_at": "2026-05-18T14:42:42.85Z", "application": "APc9vhYcPsRuTSpKD9KpMtPe", "authentication": { "type": "BASIC" }, "enabled": true, "enabled_events": [ { "entity": "authorization", "types": ["created", "updated"] }, { "entity": "balance_transfer", "types": ["created", "updated"] }, { "entity": "evidence", "types": ["created"] }, { "entity": "gateway_integration", "types": ["created"] }, { "entity": "merchant", "types": ["created", "updated"] }, { "entity": "onboarding_form", "types": ["created", "updated"] }, { "entity": "transfer_attempt", "types": ["created"] }, { "entity": "verification", "types": ["created", "updated"] } ], "is_accepting_events": true, "nickname": null, "previous_secret_expires_at": null, "url": "https://eohzjuj2prziycz.m.pipedream.net", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/webhooks/WHhEyB1GdW8NsP2T7Rv6nfc6" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" } } } ``` ### Validating Webhooks When you create a webhook via API, Finix will send an empty test event to the endpoint URL configured in the webhook. The configured URL must respond to this event successfully to let Finix know the URL is valid, at which point Finix will enable the webhook. If your URL does not respond to the event successfully, Finix will synchronously respond to your webhook creation request with an error. ```json Unsuccessful Webhook { "total": 1, "_embedded": { "errors": [ { "logref": "b3abf6fae189d7ce", "message": "Failed to create webhook. Unable to call the configured URL with an empty payload. Received Response Code: {404}", "code": "INVALID_FIELD", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/notification/webhooks" } } } ] } } ``` ### Disabling Webhooks You can disable existing webhooks by setting `enabled: false` in `PUT` requests. ```bash Update an Existing Webhook curl "https://finix.sandbox-payments-api.com/webhooks/WHLvrRTUcHYReDCMuuvKLxj" \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X PUT \ -d '{ "enabled": false }' ``` ## Delivery attempts and retries When a webhook delivery fails, Finix retries the event up to 10 times using exponential backoff. Any 2xx HTTP status code counts as a successful delivery and stops further retries. A delivery is considered failed when your endpoint returns a non-2xx status code or does not respond. Webhook Disabling If an endpoint URL hasn't accepted any events or responded with a successful 2xx HTTP status code for an extended period, Finix may disable the webhook. In Sandbox, Finix will disable failing webhooks and reach out to you about how the webhook is configured. In live environments, Finix will contact you before disabling a webhook. ### Retry schedule Delays between retries increase exponentially, up to a maximum of 15 minutes. Approximate times are listed below; actual delays include a small amount of jitter. | Retry | Approximate Delay | | --- | --- | | 1 | 1 minute | | 2 | 1.5 minutes | | 3 | 2 minutes | | 4 | 3 minutes | | 5 | 5 minutes | | 6 | 9 minutes | | 7 | 15 minutes | | 8 | 15 minutes | | 9 | 15 minutes | | 10 | 15 minutes | For example, if the initial delivery fails at 2:00 PM: 1. **Retry 1** at ~2:01 PM (1 minute later) 2. **Retry 2** at ~2:02:30 PM (1.5 minutes later) 3. **Retry 3** at ~2:04:30 PM (2 minutes later) This continues up to 10 retries. Once all retry attempts are exhausted, the event cannot be resent. If you suspect you missed events, use the [Finix API](/api) to query the relevant resources directly. ## Frequently asked questions ### Can I view all the webhook events Finix has sent? Yes, the Finix Dashboard offers a Webhooks Log that lists all the webhook events Finix has sent in the past 30 days. For more information, see [Webhook Logs](/additional-resources/developers/webhooks/webhook-logs). ### Can I manage webhooks on the Finix Dashboard? Yes, the Finix dashboard lets you view, create, update, and disable webhooks. For more information, see [Managing Webhooks via Dashboard](#managing-webhooks-via-dashboard). ### Will I receive a request for each event, or will I receive them in batches? You will receive a request for each individual event. Webhooks created at the `Application` level receive any state change under an `Application`. These changes include a change in state for a `Transfer`, `Merchant` account provisioning, and `Disputes`. ### Is there a specific time when events get sent? An event gets sent any time a state change occurs in our database; this helps make webhook events as real-time as possible. ### What type of response should we send? is there a way to notify Finix that an event got received successfully? Any 2xx HTTP code will let Finix know the event got successfully received. ### If we don't receive the event, will it be sent again? what type of response/exception should I send? Yes. If your endpoint doesn't respond or returns a non-2xx status code, Finix automatically retries up to 10 times. See [Delivery Attempts and Retries](#delivery-attempts-and-retries) for the full schedule. Once all retries are exhausted, the event will not be resent automatically. If you suspect you missed events, you can query the relevant resources directly via the [Finix API](/api) to reconcile your state. ### Is Finix sending any confidential information? i’d like to know if using a public service, like [https://pipedream.com](https://pipedream.com), is an option to test webhooks Yes, you can use public services like [https://pipedream.com](https://pipedream.com) to test webhooks. We won’t ever send sensitive credit card data, but will return less sensitive PII such as birthdates and addresses. For additional details on the specific data sent back, you can review our list of [sample webhook events](/additional-resources/developers/webhooks/webhook-events#sample-payloads). ### Is there a list of all the webhook events? Yes, see [Webhook Events](/additional-resources/developers/webhooks/webhook-events) to view the full list of webhook events Finix offers. #### Does Finix release new events? Occasionally Finix will release new events to ensure devs can receive alerts about any corner of our API. Webhooks subscribed to **All Events** automatically get subscribed to these new events. See [Webhook Events](/additional-resources/developers/webhooks/webhook-events) to view the full list of webhook events Finix offers. ### Is it possible to include a unique ID in each request? I want to make sure the same event isn't processed twice Every event your Webhook URL receives includes a unique `event#id`, which you can use to verify none of the events are duplicates. ```json Example Webhook { "id": "event_cgGzzdKrV3fbsd74ugymaX", "type": "updated", "entity": "transfer", "occurred_at": "2023-01-05T21:58:48.022174", "_embedded": { "transfers": [ { "fee": 0, "destination": null, "created_at": "2023-01-05T21:58:27.26Z", "failure_message": null, "source": "PI6fBxWjm2GfdhCughovSWQr", "type": "DEBIT", "additional_buyer_charges": null, "statement_descriptor": "FNX*FINIX FLOWERS", "additional_healthcare_data": null, "updated_at": "2023-01-05T21:58:28.21Z", "subtype": "API", "amount_requested": 662154, "currency": "USD", "id": "TR3CpnVVxM1iapJgxdyb5Hsz", "state": "SUCCEEDED", "idempotency_id": null, "amount": 662154, "failure_code": null, "trace_id": "97083fa0-712f-489d-bf38-bda18825f966", "address_verification": null, "security_code_verification": null, "raw": null, "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDvHGrfeVmB3i7uL78xjemNk", "tags": {}, "ready_to_settle_at": null, "application": "APgPDQrLD52TYvqazjHJJchM", "externally_funded": "UNKNOWN", "messages": [] } ] } } ``` ### Is there a processor transaction ID that gets sent with each event? I need a way to consolidate our transactions using the information received from the event Use the resource ID’s in each response to consolidate events. For example: 1. [Authorization](/additional-resources/developers/webhooks/webhook-events#authorization-created) 2. [Transfer (e.g. debit, refund, credit)](/additional-resources/developers/webhooks/webhook-events#transfer-updated) ### Do we need to whitelist a specific IP address? We submit requests from multiple IP addresses. ### How do I verify the event is from Finix? [Authenticate your webhooks](#creating-authenticated-webhooks) so events include an authorization header. Refer to the authorization header to confirm that events are from Finix. You should also [verify the `Finix-Signature` header](#verifying-webhook-signatures-finix-signature) on every event. ### If I change the endpoint URL of a webhook, will there be a delay before events get sent to the new URL? can we deactivate the old endpoint URL immediately, or do we need to wait? There shouldn’t be any delay. To prevent migration issues, you can enable multiple at the same time. You can immediately deactivate the old endpoint URL and disable the old webhook. ### How many times will you try to send a webhook that fails? Finix retries failed webhook events up to 10 times with exponential backoff. If your server is unavailable or continues to return non-2xx responses after all retry attempts, Finix will stop trying to deliver that event. For more details, see [Delivery Attempts and Retries](#delivery-attempts-and-retries). ### Why do I receive so many or so few events? The events you receive depend on the credentials used to create the `Webhook`: - `ROLE_PLATFORM` credentials receive every webhook event sent to onboarded `Applications`. - `ROLE_PARTNER` credentials only receive the webhook events related to the `Application` the credentials were created under. To change how many events you receive, you can either: - Create a new `Webhook` using the necessary credential level. - Use [Webhook Event Filtering](/additional-resources/developers/webhooks/integrating-into-webhooks#filtering-webhooks) to filter out unnecessary events. --- # Webhook Events Source: https://docs.finix.com/additional-resources/developers/webhooks/webhook-events A complete list of the webhook events that Finix offers. ## List of Webhook events Finix offers the following webhook events that various business flows (such as onboarding a seller or making a sale) trigger. Default Webhooks By default, newly created webhooks subscribe to a subset of common event types of interest to many users. | `entity` | `type` | Default | Description | | --- | --- | --- | --- | | `application` | `created` | No | An `Application` was created. This is only sent to Core customers. | | `application` | `updated` | No | An `Application` was updated. This is only sent to Core customers. | | `application_profile` | `created` | No | An `Application Profile` was created. This is only sent to Core customers. | | `application_profile` | `updated` | No | An `Application Profile` was updated. This is only sent to Core customers. | | `authorization` | `created` | No | An authorization was created. It still needs to be captured. | | `authorization` | `updated` | No | An authorization was updated. If it was captured, you are sent an event for the corresponding transfer that was created. For voids, the `void_state` will be `PENDING`. | | `balance_transfer` | `created` | No | A `Balance Transfer` was created. This is only sent to Core customers. | | `balance_transfer` | `updated` | No | A `Balance Transfer` was updated. This is only sent to Core customers. | | `checkout_form` | `created` | No | A `Checkout Form` was created. | | `checkout_form` | `updated` | No | A `Checkout Form` was updated. | | `compliance_form` | `created` | No | A `Compliance Form` was created. You need to get your user to [complete the compliance form](/guides/managing-operations/security-compliance/managing-pci-compliance#completing-compliance-forms) | | `compliance_form` | `updated` | No | A `Compliance Form` has been updated. Commonly sent when the [form has been completed.](/guides/managing-operations/security-compliance/managing-pci-compliance#completing-compliance-forms) | | `dispute` | `created` | No | A `Dispute` was created. A [chargeback dispute](/guides/after-the-payment/disputes/managing-disputes) was started. | | `dispute` | `updated` | Yes | A `Dispute` was updated. Usually this occurs when the [dispute's state has changed](/guides/after-the-payment/disputes/dispute-states). | | `evidence` | `created` | Yes | An `evidence` file was uploaded. | | `evidence` | `updated` | No | An `evidence` file was updated. Usually, the [state of the evidence has changed.](/guides/after-the-payment/disputes/) | | `external_link` | `created` | No | An `external_link` was created. You need to have your user upload a file via the link. | | `external_link` | `updated` | No | An `external_link` was updated. Usually sent when the `external_link` has expired. | | `fee` | `created` | No | A `fee` was created. The `linked_to` field indicates the entity that generated it (e.g., `TRfnif8f9U1r6k2zys27U4yP`). | | `fee` | `updated` | No | A `fee` was updated. | | `fee_profile` | `created` | No | A `Fee Profile` was created. This happens as part of [creating a merchant.](/guides/platform-payments/onboarding-sellers/seller-onboarding-process/#initial-settings-and-profiles) | | `fee_profile` | `updated` | No | A `Fee Profile` was updated. | | `file` | `created` | No | A `File` was created. It still needs a document to be uploaded to Finix. | | `file` | `updated` | No | A `File` was updated. Usually send when a document was uploaded. | | `gateway_integration` | `created` | No | A `Gateway Integration` was created and has a `state` of `PENDING` until Cybersource approves the `Merchant` or the integration fails. | | `gateway_integration` | `updated` | No | A `Gateway Integration` was updated. The `Gateway Integration` › `state` will change from `PENDING` to `SUCCEEDED` or `FAILED`. | | `identity` | `created` | No | An `Identity` was created. Usually occurs during [onboarding](/guides/platform-payments/onboarding-sellers/seller-onboarding-process/#key-onboarding-steps) or when [processing a payment](/guides/getting-started/developer-quickstart#step-1-create-an-identity-for-your-buyer). | | `identity` | `updated` | No | An `Identity` was updated. | | `instrument` | `created` | No | A `Payment Instrument` was created. The `payment_instrument.type` tells you what type of payment instrument was created. | | `instrument` | `updated` | No | A `Payment Instrument` was updated. | | `instrument_history` | `created` | Yes | A stored payment card's details were updated. | | `merchant` | `created` | Yes | A `Merchant` was created and is `PROVISIONING`. | | `merchant` | `updated` | Yes | A `Merchant` was updated. Typically, this happens to `PROVISIONING` Merchants during the onboarding process. The Merchant's `onboarding_state` will let you know if the Merchant is `APPROVED`, `REJECTED`, or `UPDATE_REQUESTED`. | | `merchant` | `underwritten` | Yes | A `Merchant` was underwritten and `APPROVED`, and is ready to start accepting payments. | | `merchant_profile` | `created` | No | A `Merchant Profile` was created. This happens as part of [creating a merchant.](/guides/platform-payments/onboarding-sellers/seller-onboarding-process/#initial-settings-and-profiles) | | `merchant_profile` | `updated` | No | A `Merchant Profile` was updated. This happens when the `tags` were updated. | | `onboarding_form` | `created` | No | An `onboarding_form` was created. This lets you know a seller has begun [onboarding](/guides/platform-payments/onboarding-sellers). | | `onboarding_form` | `updated` | No | An `onboarding_form` was updated. This lets you know the seller has completed the `onboarding_form`. | | `payment_link` | `created` | No | A `Payment Link` was created. | | `payment_link` | `updated` | No | A `Payment Link` was updated. | | `payout_profile` | `created` | No | The [payout settings](/guides/platform-payments/seller-payouts/managing-seller-payouts) of a `Merchant` were changed or updated. | | `subscription` | `created` | No | A `Subscription` was created. | | `subscription` | `updated` | No | A `Subscription` was updated. This includes when the `state` changes, for example, from `ACTIVE` to `CANCELED`. | | `risk_profile` | `created` | No | A `risk_profile` was created. Usually this happens when a [`merchant_profile` is created.](/guides/platform-payments/onboarding-sellers/seller-onboarding-process/#initial-settings-and-profiles) | | `risk_profile` | `updated` | No | A `risk_profile` was updated. This happens when the `tags` were updated. | | `settlement` | `accruing_started` | No | A `Settlement` has started accruing transactions. | | `settlement` | `created` | Yes | A `Settlement` was closed. `settlements.total_amount` and `settlements.net_amount` tells you the total of the payout. | | `settlement` | `updated` | No | A `Settlement` is awaiting approval. | | `transfer` | `created` | Yes | A transfer was created. The `transfer.type` and `transfer.state` tell you what type of transfer occurred and what state it is in (e.g., `PENDING`, `SUCCEEDED`, or `RETURNED` for ACH returns). | | `transfer` | `updated` | Yes | A transfer was updated. The transfer tells you the snapshot of the transfer at that moment of time. | | `transfer_attempt` | `created` | No | A transfer attempt was created. | | `transfer_attempt` | `updated` | No | A transfer attempt was updated. | | `verification` | `created` | No | A verification was created. The `verification.state` will tell you if the request was `APPROVED` or `REJECTED`. | | `verification` | `updated` | No | A verification was updated. This commonly happens when provisioning merchants and verifying payment instruments. | | `funding_transfer_attempt` | `created` | No | A `Funding Transfer Attempt` was created. | | `funding_transfer_attempt` | `updated` | No | A `Funding Transfer Attempt` was updated. | | `three_d_secure_session` | `created` | No | A 3D Secure Session was created. The session `state` is `PENDING`. | | `three_d_secure_session` | `updated` | No | A 3D Secure Session was updated. Check `state` and, when `SUCCEEDED`, `electronic_commerce_indicator` to determine the authentication outcome. | ## Sample Webhook events Every activity in Finix triggers several events. e.g. Capturing a `Transfer` can lead from anywhere between five to ten events getting delivered. Below is a list of example events and the activities in Finix that triggered them. While you may receive several events, keep an eye out for an event that looks like any example below to confirm the related activity occurred or completed in Finix. ### Authorization captured The event that gets sent when an `Authorization` gets captured. The event has `authorizations.transfer` populated: - `type: updated` - `entity: authorization` - `_embedded.authorizations[0].transfer: {{transfer_id}}` ```json Authorization Captured Webook { "type": "updated", "entity": "authorization", "occurred_at": "2020-04-26T23:00:23.467", "_embedded": { "authorizations": [ { "idempotency_id": null, "amount": 100, "trace_id": "db10f58f-b56b-4a38-bec2-7fd46e5569f4", "raw": null, "created_at": "2020-04-26T22:58:30.41Z", "source": "PI5JEJTNwLzZ8rMMFV9QkaHz", "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDdpvBpQ9m6D3JDCRq9UDB2E", "tags": { "order_number": "21DFASJSAKAS" }, "3ds_redirect_url": null, "void_state": "UNATTEMPTED", "transfer": "TRL2VyFmBBLKcR5nqbhcHRQ", "expires_at": "2020-05-03T22:58:30.41Z", "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T23:00:23.05Z", "is_void": false, "messages": [], "currency": "USD", "id": "AUWgEWUiRvi5PCeBaPHcfti", "state": "SUCCEEDED" } ] } } ``` ### Authorization captured (card present) When you capture a Card Present Authorization, Finix sends 2 webhook events: 1. Transfer Created (`PENDING`) 2. Transfer Updated (`SUCCEEDED`) #### Transfer created The event you receive when a Transfer is created and `PENDING`. ```json { "type": "created", "entity": "transfer", "occurred_at": "2020-04-29T20:31:32.348", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 1700, "trace_id": "FNX7jwSr5QhQdR2E4PZkLxYTW", "fee": 10, "destination": null, "raw": null, "created_at": "2020-04-29T20:31:25.22Z", "source": "PIaZwAfmK2YBX9bUT44uvCLa", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "DEBIT", "tags": {}, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": "2020-04-29T20:31:30.56Z", "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:31:30.55Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TR6XwvJApMTzNQaPxBWWSxFU", "state": "PENDING", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` #### Transfer updated The event you receive when a Transfer gets updated to `SUCCEEDED`. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2020-04-29T20:31:30.669", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 1700, "trace_id": "FNX7jwSr5QhQdR2E4PZkLxYTW", "fee": 10, "destination": null, "raw": null, "created_at": "2020-04-29T20:31:25.22Z", "source": "PIaZwAfmK2YBX9bUT44uvCLa", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "DEBIT", "tags": {}, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": "2020-04-29T20:31:30.56Z", "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:31:30.55Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TR6XwvJApMTzNQaPxBWWSxFU", "state": "SUCCEEDED", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` ### Authorization created The event that gets sent when an `Authorization` is created. ```json Authorization Created Webook { "type": "updated", "entity": "authorization", "occurred_at": "2020-04-26T22:58 :30.584", "_embedded": { "authorizations": [ { "idempotency_id": null, "amount": 100, "trace_id": "db10f58f-b56b-4a38-bec2-7fd46e5569f4", "raw": null, "created_at": "2020-04-26T22:58:30.41Z", "source": "PI5JEJTNwLzZ8rMMFV9QkaHz", "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDdpvBpQ9m6D3JDCRq9UDB2E", "tags": { "order_number": "21DFASJSAKAS" }, "3ds_redirect_url": null, "void_state": "UNATTEMPTED", "transfer": null, "expires_at": "2020-05-03T22:58:30.41Z", "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T22:58:30.52Z", "is_void": false, "messages": [], "currency": "USD", "id": "AUWgEWUiRvi5PCeBaPHcfti", "state": "SUCCEEDED" } ] } } ``` ### Authorization created (card present EMV card) When you create an Authorization with an EMV Card, Finix sends 6 webhook events: 1. Identity Created 2. Payment Instrument Created 3. Authorization Created 4. Authorization Captured 5. Transfer Created 6. Transfer Updated #### Identity created The event you receive when an `Identity` gets created. The new `Identity` gets used to create the `Payment Instrument` for the EMV card. ```json Identity Created Webook { "type": "created", "entity": "identity", "occurred_at": "2020-04-29T20:31:03.097", "_embedded": { "identitys": [ { "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:31:03.01Z", "created_at": "2020-04-29T20:31:03.01Z", "id": "IDd76bhnKyKTjzbqwd939WnV", "entity": { "title": null, "first_name": null, "last_name": null, "email": null, "business_name": null, "business_type": null, "doing_business_as": null, "phone": null, "business_phone": null, "personal_address": null, "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 }, "identity_roles": [], "tags": {} } ] } } ``` #### Payment Instrument created The event you receive when a `Payment Instrument` gets created for an EMV card. ```json Payment Instrument Created Webook { "type": "created", "entity": "instrument", "occurred_at": "2020-04-29T20:31:03.284", "_embedded": { "instruments": [ { "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:31:03.23Z", "identity": "IDd76bhnKyKTjzbqwd939WnV", "fingerprint": "FPR5w2uCguRwhbtWmcJmirkhf", "created_at": "2020-04-29T20:31:03.23Z", "currency": "USD", "id": "PIaZwAfmK2YBX9bUT44uvCLa", "instrument_type": "PAYMENT_CARD_PRESENT", "type": "PAYMENT_CARD_PRESENT", "tags": {} } ] } } ``` #### Authorization created The event you receive when an `Authorization` gets created. ```json { "type": "created", "entity": "authorization", "occurred_at": "2020-04-29T20:31:17.059", "_embedded": { "authorizations": [ { "idempotency_id": null, "amount": 1000, "trace_id": "FNX7jwSr5QhQdR2E4PZkLxYTW", "raw": null, "created_at": "2020-04-29T20:31:03.39Z", "source": "PIaZwAfmK2YBX9bUT44uvCLa", "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDd76bhnKyKTjzbqwd939WnV", "tags": {}, "3ds_redirect_url": null, "void_state": "UNATTEMPTED", "transfer": null, "expires_at": "2020-05-06T20:31:03.39Z", "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:31:16.99Z", "is_void": false, "messages": [], "currency": "USD", "id": "AUuf31ZzUArRnv7R8MpU5PbZ", "state": "SUCCEEDED", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` #### Authorization captured The event you receive when an [`authorization` gets captured](/guides/online-payments/payment-features/auth-and-captures/). ```json { "type": "updated", "entity": "authorization", "occurred_at": "2020-04-29T20:31:32.406", "_embedded": { "authorizations": [ { "idempotency_id": null, "amount": 1000, "trace_id": "FNX7jwSr5QhQdR2E4PZkLxYTW", "raw": null, "created_at": "2020-04-29T20:31:03.39Z", "source": "PIaZwAfmK2YBX9bUT44uvCLa", "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDd76bhnKyKTjzbqwd939WnV", "tags": {}, "3ds_redirect_url": null, "void_state": "UNATTEMPTED", "transfer": "TRdo2Br3gvYKTbiPWwaPvXzR", "expires_at": "2020-05-06T20:31:03.39Z", "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:31:25.24Z", "is_void": false, "messages": [], "currency": "USD", "id": "AUuf31ZzUArRnv7R8MpU5PbZ", "state": "SUCCEEDED", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` #### Transfer created The event you receive when a `Transfer` gets created for [a captured `Authorization`](/guides/online-payments/payment-features/auth-and-captures/). ```json { "type": "created", "entity": "transfer", "occurred_at": "2020-04-29T20:31:32.289", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 30, "trace_id": "FNX6h3WF8UsnEb4dSDu4D2aRf", "fee": 0, "destination": null, "raw": null, "created_at": "2020-04-29T20:31:31.47Z", "source": null, "fee_type": "CARD_FIXED", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDd76bhnKyKTjzbqwd939WnV", "type": "FEE", "tags": {}, "statement_descriptor": null, "ready_to_settle_at": "2020-04-29T20:31:30.78Z", "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:31:31.68Z", "subtype": "PLATFORM_FEE", "messages": [], "currency": "USD", "id": "TRdo2Br3gvYKTbiPWwaPvXzR", "state": "PENDING" } ] } } ``` #### Transfer updated The event you receive when a `Transfer` gets updated to `SUCCEEDED`. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2020-04-29T20:31:31.733", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 30, "trace_id": "FNX6h3WF8UsnEb4dSDu4D2aRf", "fee": 0, "destination": null, "raw": null, "created_at": "2020-04-29T20:31:31.47Z", "source": null, "fee_type": "CARD_FIXED", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDd76bhnKyKTjzbqwd939WnV", "type": "FEE", "tags": {}, "statement_descriptor": null, "ready_to_settle_at": "2020-04-29T20:31:30.78Z", "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:31:31.68Z", "subtype": "PLATFORM_FEE", "messages": [], "currency": "USD", "id": "TRdo2Br3gvYKTbiPWwaPvXzR", "state": "SUCCEEDED" } ] } } ``` ### Authorization created (card present non-EMV card) When you create an Authorization with an non-EMV Card, Finix sends 6 webhook events: 1. Identity Created 2. Payment Instrument Created 3. Authorization Created 4. Authorization Captured 5. Transfer Created 6. Transfer Updated #### Identity created The event you receive when an `Identity` gets created. The new `Identity` gets used to create the `Payment Instrument` for the non-EMV card. ```json { "type": "created", "entity": "identity", "occurred_at": "2020-04-29T20:28:32.926", "_embedded": { "identitys": [ { "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:28:32.88Z", "created_at": "2020-04-29T20:28:32.88Z", "id": "ID5ah4iYJqYjoVSwfxmjSjgC", "entity": { "title": null, "first_name": null, "last_name": null, "email": null, "business_name": null, "business_type": null, "doing_business_as": null, "phone": null, "business_phone": null, "personal_address": null, "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 }, "identity_roles": [], "tags": {} } ] } } ``` #### Payment Instrument created The event you receive when a `Payment Instrument` gets created for a non-EMV card. ```json { "type": "created", "entity": "instrument", "occurred_at": "2020-04-29T20:28:33.034", "_embedded": { "instruments": [ { "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:28:32.99Z", "identity": "ID5ah4iYJqYjoVSwfxmjSjgC", "fingerprint": "FPR5w2uCguRwhbtWmcJmirkhf", "created_at": "2020-04-29T20:28:32.99Z", "currency": "USD", "id": "PI9JbewhasbLg4rZeMWd47C7", "instrument_type": "PAYMENT_CARD_PRESENT", "type": "PAYMENT_CARD_PRESENT", "tags": {} } ] } } ``` #### Authorization created The event you receive when an `Authorization` gets created. ```json { "type": "created", "entity": "authorization", "occurred_at": "2020-04-29T20:28:48.413", "_embedded": { "authorizations": [ { "idempotency_id": null, "amount": 1000, "trace_id": "FNXmMdKcPXFrhj9UdCCdDYmW9", "raw": null, "created_at": "2020-04-29T20:28:33.12Z", "source": "PI9JbewhasbLg4rZeMWd47C7", "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "tags": {}, "3ds_redirect_url": null, "void_state": "UNATTEMPTED", "transfer": null, "expires_at": "2020-05-06T20:28:33.12Z", "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:28:48.36Z", "is_void": false, "messages": [], "currency": "USD", "id": "AUqAgQJY4s7KVj7qnBU3QzAQ", "state": "SUCCEEDED", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` #### Authorization captured The event you receive when an [`authorization` gets captured](/guides/online-payments/payment-features/auth-and-captures/). ```json { "type": "updated", "entity": "authorization", "occurred_at": "2020-04-29T20:29:03.524", "_embedded": { "authorizations": [ { "idempotency_id": null, "amount": 1000, "trace_id": "FNXmMdKcPXFrhj9UdCCdDYmW9", "raw": null, "created_at": "2020-04-29T20:28:33.12Z", "source": "PI9JbewhasbLg4rZeMWd47C7", "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "tags": {}, "3ds_redirect_url": null, "void_state": "UNATTEMPTED", "transfer": "TRsUwkcqkcnuVyNxmuSHz8A3", "expires_at": "2020-05-06T20:28:33.12Z", "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:28:55.01Z", "is_void": false, "messages": [], "currency": "USD", "id": "AUqAgQJY4s7KVj7qnBU3QzAQ", "state": "SUCCEEDED", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` #### Transfer created The event you receive when a `Transfer` gets created for [a captured `Authorization`](/guides/online-payments/payment-features/auth-and-captures/). ```json { "type": "created", "entity": "transfer", "occurred_at": "2020-04-29T20:29:03.301", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 1700, "trace_id": "FNXmMdKcPXFrhj9UdCCdDYmW9", "fee": 10, "destination": null, "raw": null, "created_at": "2020-04-29T20:28:54.99Z", "source": "PI9JbewhasbLg4rZeMWd47C7", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "DEBIT", "tags": {}, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": "2020-04-29T20:29:00.79Z", "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:29:00.78Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRsUwkcqkcnuVyNxmuSHz8A3", "state": "PENDING", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` #### Transfer updated The event you receive when a `Transfer` gets updated to `SUCCEEDED`. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2020-04-29T20:29:01.668", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 1700, "trace_id": "FNXmMdKcPXFrhj9UdCCdDYmW9", "fee": 10, "destination": null, "raw": null, "created_at": "2020-04-29T20:28:54.99Z", "source": "PI9JbewhasbLg4rZeMWd47C7", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "DEBIT", "tags": {}, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": "2020-04-29T20:29:00.79Z", "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:29:00.78Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRsUwkcqkcnuVyNxmuSHz8A3", "state": "SUCCEEDED", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` ### Authorization voided The event that gets sent when an [`authorization` is voided](/guides/after-the-payment/refunds). ```json Authorization Voided Webook { "type": "updated", "entity": "authorization", "occurred_at": "2020-04-26T23:04:04.585", "_embedded": { "authorizations": [ { "idempotency_id": null, "amount": 100, "trace_id": "894b3aaa-f839-4b73-9664-2605c5c952ba", "raw": null, "created_at": "2020-04-26T23:03:12.76Z", "source": "PI5JEJTNwLzZ8rMMFV9QkaHz", "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDdpvBpQ9m6D3JDCRq9UDB2E", "tags": { "order_number": "21DFASJSAKAS" }, "3ds_redirect_url": null, "void_state": "PENDING", "transfer": null, "expires_at": "2020-05-03T23:03:12.76Z", "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T23:04:04.52Z", "is_void": true, "messages": [], "currency": "USD", "id": "AUJKRcCGbLVQAGrAt5FY4wy", "state": "SUCCEEDED" } ] } } ``` ### Checkout Form created The event you receive when a Checkout Form is created. ```json { "_embedded": { "checkout_forms": [ { "additional_details": { "cart_return_url": "https://www.store.com/return", "collect_billing_address": false, "collect_email": true, "collect_name": true, "collect_phone": false, "collect_shipping_address": false, "expiration_in_minutes": 5, "expired_session_url": "https://store.com/expired", "receipt_requested_delivery_methods": [ { "destinations": ["2348765431"], "type": "SMS" } ], "send_receipt": false, "success_return_url": "https://www.store.com/success", "terms_of_service_url": "https://store.com/tos" }, "allowed_payment_methods": ["PAYMENT_CARD"], "amount_details": { "amount_breakdown": null, "amount_type": "FIXED", "currency": "USD", "max_amount": null, "min_amount": null, "total_amount": 100 }, "application_id": "APscsFoe6BF78faCJ53CCTe8", "attempt_level_two_level_three_payment": false, "branding": { "accent_color": "#FF0000", "brand_color": "#FF0000", "button_font_color": null, "icon": "https://imgur.com/icon", "logo": "https://imgur.com/logo", "logo_alternative_text": "logo alternative text checkout forms" }, "buyer_details": null, "created_at": "2025-05-28T15:09:38.033578Z", "id": "checkout_form_coz95HeufHYjTAtYJbAdE", "items": [], "link_expires_at": "2025-05-28T15:14:37.989286Z", "link_url": "https://link.qa-payments-checkout.com/at7e0I", "merchant_id": "MU5tYxn1K1foFfmCqWYBRQZL", "nickname": "My first checkout form", "payment_frequency": "ONE_TIME", "split_transfers": [], "state": "ACTIVE", "tags": {}, "updated_at": "2025-05-28T15:09:38.033578Z" } ] }, "entity": "checkout_form", "id": "event_2oqqVoCWLuV9oVFxcVxwB1", "occurred_at": "2025-05-28T15:09:38.869384444", "system_generated_idempotency_id": "2oqqVoCWLuV9oVFxcVxwB1", "type": "created" } ``` ### Checkout Form updated The event you receive when a Checkout Form is updated. ```json { "_embedded": { "checkout_forms": [ { "additional_details": { "cart_return_url": "https://www.store.com/return", "collect_billing_address": false, "collect_email": true, "collect_name": true, "collect_phone": false, "collect_shipping_address": false, "expiration_in_minutes": 5, "expired_session_url": "https://store.com/expired", "receipt_requested_delivery_methods": [ { "destinations": ["2348765431"], "type": "SMS" } ], "send_receipt": false, "success_return_url": "https://www.store.com/success", "terms_of_service_url": "https://store.com/tos" }, "allowed_payment_methods": ["PAYMENT_CARD", "BANK_ACCOUNT"], "amount_details": { "amount_breakdown": null, "amount_type": "FIXED", "currency": "USD", "max_amount": null, "min_amount": null, "total_amount": 100 }, "application_id": "APscsFoe6BF78faCJ53CCTe8", "attempt_level_two_level_three_payment": false, "branding": { "accent_color": "#FF0000", "brand_color": "#FF0000", "button_font_color": null, "icon": "https://imgur.com/icon", "logo": "https://imgur.com/logo", "logo_alternative_text": "logo alternative text checkout forms" }, "buyer_details": null, "created_at": "2025-05-28T15:09:38.033578Z", "id": "checkout_form_coz95HeufHYjTAtYJbAdE", "items": [], "link_expires_at": "2025-05-28T15:14:37.989286Z", "link_url": "https://link.qa-payments-checkout.com/at7e0I", "merchant_id": "MU5tYxn1K1foFfmCqWYBRQZL", "nickname": "My first checkout form", "payment_frequency": "ONE_TIME", "split_transfers": [], "state": "ACTIVE", "tags": {}, "updated_at": "2025-05-29T15:09:38.033578Z" } ] }, "entity": "checkout_form", "id": "event_2oqqVoCWLuV9oVFxcVxwB1", "occurred_at": "2025-05-28T15:09:38.869384444", "system_generated_idempotency_id": "2oqqVoCWLuV9oVFxcVxwB1", "type": "updated" } ``` ### Compliance Form created The event you receive when a `Compliance Form` gets created. ```json { "type": "created", "entity": "compliance_form", "occurred_at": "2020-04-26T22:58:30.584", "_embedded": { "compliance_form": [ { "id": "cf_bcu8rBtpCFJVuRpgCxt4HS", "type": "PCI_SAQ_A", "state": "INCOMPLETE", "created_at": "2021-08-15T18:26:56.15Z", "updated_at": "2021-08-15T18:26:56.15Z", "due_at": "2021-11-13T15:26:56.15Z", "linked_to": "MUas8jhZf3bWsqyp8neX3UwN", "linked_type": "MERCHANT", "pci_saq_a": { "name": null, "signed_at": null, "user_agent": null, "ip_address": null, "is_accepted": null, "title": null }, "files": { "unsigned_file": "FILE_qf952xmeuiF179wdMiPXrW", "signed_file": null }, "valid_from": "2022-03-18T18:26:56.15Z", "valid_until": "2023-03-18T18:26:56.15Z", "compliance_form_template": "cft_u56ZGx3Xb6U9gAqKfgNisd", "tags": {} } ] } } ``` ### Compliance Form updated The event you receive when a `Compliance Form` gets updated. - This indicates an update to the file service. - The most common use is when a file changes status to `UPLOADED` or `INVALID`. - It can also apply when a webhook is updated. ```json { "type": "updated", "entity": "compliance_form", "occurred_at": "2020-04-26T22:58:30.584", "_embedded": { "compliance_form": [ { "id": "cf_bcu8rBtpCFJVuRpgCxt4HS", "type": "PCI_SAQ_A", "state": "COMPLETED", "created_at": "2021-08-15T18:26:56.15Z", "updated_at": "2021-07-15T15:26:56.15Z", "due_at": "2021-11-13T15:26:56.15Z", "linked_to": "MUas8jhZf3bWsqyp8neX3UwN", "linked_type": "MERCHANT", "pci_saq_a": { "name": "John Booker", "signed_at": "2022-03-18T16:42:55Z", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)", "ip_address": "42.1.1.113", "is_accepted": true, "title": "CTO" }, "files": { "unsigned_file": "FILE_qf952xmeuiF179wdMiPXrW", "signed_file": "FILE_mmRiDs7YaSsqjP727gWD84" }, "valid_from": "2022-03-18T18:26:56.15Z", "valid_until": "2023-03-18T18:26:56.15Z", "compliance_form_template": "cft_u56ZGx3Xb6U9gAqKfgNisd", "tags": {} } ] } } ``` ### Dispute created The event you receive when a `Dispute` gets created. ```json { "type": "created", "entity": "dispute", "occurred_at": "2022-05-13T21:28:12.289991", "_embedded": { "disputes": [ { "reason": "FRAUD", "amount": 888888, "created_at": "2022-05-13T21:28:11.04Z", "message": null, "tags": { "order_number": "21DFASJSAKAS" }, "occurred_at": "2022-05-13T21:27:53.49Z", "dispute_details": { "arn": "123" }, "transfer": "TRikkDuedytMAj6A1pdfFCTg", "application": "AP3AB2itAWrrrPVS6spvrGYp", "updated_at": "2022-05-13T21:28:10.49Z", "identity": "IDsArLxCm9QGbi2QfhaFrTED", "action": null, "id": "DIaFfc4tNXbRDDXXFE5qt6Rq", "state": "PENDING", "respond_by": "2022-05-20T21:28:11.04Z" } ] } } ``` ### Dispute evidence created The event you receive when `evidence` gets created for a `Dispute`. ```json { "type": "created", "entity": "evidence", "occurred_at": "2022-08-10T21:05:16.417563", "_embedded": { "evidences": [ { "dispute": "DItff2xbqSx3vbSUoepqwF5R", "updated_at": "2022-08-10T21:05:11.99Z", "created_at": "2022-08-10T21:05:11.99Z", "id": "DFre6geC3iouMhzXjfGiwi5y", "state": "PENDING", "tags": { "file-extension": ".png", "content-type": "image/png", "file-name": "evidence.png" } } ] } } ``` ### Dispute evidence uploaded The event you receive when documents are successfully uploaded to a `evidence` for a `Dispute`. ```json { "type": "updated", "entity": "evidence", "occurred_at": "2022-08-09T17:23:37.554229", "_embedded": { "evidences": [ { "dispute": "DIs7yQRkHDdMYhurzYz72SFk", "updated_at": "2022-08-09T17:09:39.28Z", "created_at": "2022-08-09T17:09:39.28Z", "id": "DF45NRTbyfpuELmeTmvbpJwo", "state": "SUCCEEDED", "tags": { "file-extension": ".png", "content-type": "image/png", "file-name": "finix_file.png" } } ] } } ``` ### Dispute updated The event you receive when a `Dispute` gets updated. ```json { "type": "updated", "entity": "dispute", "occurred_at": "2022-05-13T21:31:43.249792", "_embedded": { "disputes": [ { "reason": "FRAUD", "amount": 888888, "created_at": "2022-05-13T21:28:11.04Z", "message": null, "tags": { "order_number": "21DFASJSAKAS" }, "occurred_at": "2022-05-13T21:27:53.49Z", "dispute_details": { "arn": "123" }, "transfer": "TRikkDuedytMAj6A1pdfFCTg", "application": "AP3AB2itAWrrrPVS6spvrGYp", "updated_at": "2022-05-13T21:31:33.22Z", "identity": "IDsArLxCm9QGbi2QfhaFrTED", "action": null, "id": "DIaFfc4tNXbRDDXXFE5qt6Rq", "state": "WON", "respond_by": "2022-05-20T21:28:11.04Z" } ] } } ``` ### File uploaded The following events detail the changes that happen while uploading files. For more information, see [Uploading Files to Finix](/guides/platform-payments/onboarding-sellers/seller-onboarding-uploading-files/). #### File created The event you receive sent when a `File` gets created. ```json { "type": "created", "entity": "file", "occurred_at": "2022-05-23T17:46:42.19914", "_embedded": { "files": [ { "updated_at": "2022-05-23T17:46:37.42Z", "platform_id": "PLm5E6FbtCZ5vjpCaKhq5PwN", "created_at": "2022-05-23T17:46:37.42Z", "id": "FILE_aiAQBbBz2wosPQjQoaGZHD", "linked_type": "MERCHANT", "display_name": "John's Drivers License", "type": "DRIVERS_LICENSE_FRONT", "linked_to": "MUucec6fHeaWo3VHYoSkUySM", "application_id": "APgPDQrLD52TYvqazjHJJchM", "status": "REQUIRES_UPLOAD", "tags": { "key_1": "value_1" } } ] } } ``` #### File approved The event you receive when a `File` is approved. When approved, the `status` of the `File` gets updated to `UPLOADED`. ```json { "type": "updated", "entity": "file", "occurred_at": "2022-05-23T17:46:42.19914", "_embedded": { "files": [ { "updated_at": "2022-05-23T17:46:37.42Z", "platform_id": "PLm5E6FbtCZ5vjpCaKhq5PwN", "created_at": "2022-05-23T17:46:37.42Z", "id": "FILE_aiAQBbBz2wosPQjQoaGZHD", "linked_type": "MERCHANT", "display_name": "John's Drivers License", "type": "DRIVERS_LICENSE_FRONT", "linked_to": "MUucec6fHeaWo3VHYoSkUySM", "application_id": "APgPDQrLD52TYvqazjHJJchM", "status": "UPLOADED", "tags": { "key_1": "value_1" } } ] } } ``` #### File rejected The event you receive when a `File` gets rejected. When rejected, the `status` of the `File` gets updated to `INVALID`. ```json { "type": "updated", "entity": "file", "occurred_at": "2022-05-23T17:46:42.19914", "_embedded": { "files": [ { "updated_at": "2022-05-23T17:46:37.42Z", "platform_id": "PLm5E6FbtCZ5vjpCaKhq5PwN", "created_at": "2022-05-23T17:46:37.42Z", "id": "FILE_KUCDz2GzXtfgVUPFq8CqL", "linked_type": "MERCHANT", "display_name": "John's Drivers License", "type": "DRIVERS_LICENSE_FRONT", "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk", "application_id": "APgPDQrLD52TYvqazjHJJchM", "status": "INVALID", "tags": { "key_1": "value_1" } } ] } } ``` #### External Link created The event you receive when an `external_link` gets created. ```json { "type": "created", "entity": "external_link", "occurred_at": "2022-05-23T18:21:44.726992", "_embedded": { "external_links": [ { "expires_at": "2022-05-23T18:31:39.62Z", "expired": false, "user_id": "USsRhsHYZGBPnQw8CByJyEQW", "file_id": "FILE_aiAQBbBz2wosPQjQoaGZHD", "created_at": "2022-05-23T18:21:39.62Z", "id": "EL_6YjrZF3yCLB3zCLm24yAGm", "type": "UPLOAD", "url": "https://finix-file-quarantine-sb.s3.us-east-2.amazonaws.com/MERCHANT/MUucec6fHeaWo3VHYoSkUySM/DRIVERS_LICENSE_FRONT/FILE_aiAQBbBz2wosPQjQoaGZHD/file?X-Amz-Security-Token=...", "tags": { "key": "value" } } ] } } ``` #### External Link updated The event you receive when an `external_link` gets updated. ```json { "type": "updated", "entity": "external_link", "occurred_at": "2022-05-23T18:21:44.726992", "_embedded": { "external_links": [ { "expires_at": "2022-05-23T18:31:39.62Z", "expired": false, "user_id": "USsRhsHYZGBPnQw8CByJyEQW", "file_id": "FILE_aiAQBbBz2wosPQjQoaGZHD", "created_at": "2022-05-23T18:21:39.62Z", "id": "EL_6YjrZF3yCLB3zCLm24yAGm", "type": "UPLOAD", "url": "https://finix-file-quarantine-sb.s3.us-east-2.amazonaws.com/MERCHANT/MUucec6fHeaWo3VHYoSkUySM/DRIVERS_LICENSE_FRONT/FILE_aiAQBbBz2wosPQjQoaGZHD/file?X-Amz-Security-Token=...", "tags": { "key": "value" } } ] } } ``` ### Gateway integration created The event you receive when a `Gateway Integration` gets created. At this time, the only supported gateway is Cybersource. The `Gateway Integration` › `state` will be `PENDING` until Cybersource approves the `Merchant`, after which the `state` changes to `SUCCEEDED`. If there are issues with the onboarding request, the state changes to `FAILED`. ```json { "type": "created", "entity": "gateway_integration", "occurred_at": "2020-04-29T20:31:32.348", "_embedded": { "gateway_integrations": [ { "created_at": "2024-08-16T13:11:36.72Z", "updated_at": "2024-08-16T13:11:36.72Z", "application_id": "APgPDQrLD52TYvqazjHJJchM", "linked_to": "MUeg77opgdgQpwejzC9wCNmK", "linked_type": "MERCHANT", "email": "johndoe@acme.com", "state": "PENDING", "type": "CYBERSOURCE", "tags": { "gateway_name": "shopify" } } ] } } ``` ### Gateway integration updated This event occurs when a `Gateway Integration` is updated. The `Gateway Integration` › `state` field shows whether the `Merchant` was successfully approved by Cybersource or if the integration failed (`SUCCEEDED` or `FAILED`). ```json { "type": "updated", "entity": "gateway_integration", "occurred_at": "2020-04-29T20:31:32.348", "_embedded": { "gateway_integrations": [ { "created_at": "2024-08-16T13:11:36.72Z", "updated_at": "2024-08-16T13:11:36.72Z", "application_id": "APgPDQrLD52TYvqazjHJJchM", "linked_to": "MUeg77opgdgQpwejzC9wCNmK", "linked_type": "MERCHANT", "email": "johndoe@acme.com", "state": "SUCCEEDED", "type": "CYBERSOURCE", "tags": { "gateway_name": "shopify" } } ] } } ``` ### Identity created (Buyer) The event you receive when an `Identity` gets created for a buyer. ```json { "type": "created", "entity": "identity", "occurred_at": "2020-04-26T20:58:46.298", "_embedded": { "identitys": [ { "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T20:58:46.25Z", "created_at": "2020-04-26T20:58:46.25Z", "id": "IDe5JkBhBeW3ZEvzqWc8kmXd", "entity": { "title": null, "first_name": "Joe", "last_name": "Jon", "email": "therock@gmail.com", "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 }, "identity_roles": [], "tags": { "key": "value" } } ] } } ``` ### Identity created (Merchant) The event you receive when an `Identity` gets created for a merchant. ```json { "type": "created", "entity": "identity", "occurred_at": "2020-04-26T21:06:11.343", "_embedded": { "identitys": [ { "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T21:06:11.27Z", "created_at": "2020-04-26T21:06:11.27Z", "id": "IDdpvBpQ9m6D3JDCRq9UDB2E", "entity": { "title": "CEO", "first_name": "John", "last_name": "Smith", "email": "user@example.org", "business_name": "Lees Sandwiches", "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP", "doing_business_as": "Lees Sandwiches", "phone": "1234567890", "business_phone": "+1 (408) 756-4497", "personal_address": { "line1": "741 Douglass St", "line2": "Apartment 7", "city": "San Mateo", "region": "CA", "postal_code": "94114", "country": "USA" }, "business_address": { "line1": "741 Douglass St", "line2": "Apartment 8", "city": "San Mateo", "region": "CA", "postal_code": "94114", "country": "USA" }, "mcc": "4900", "dob": { "day": 27, "month": 6, "year": 1978 }, "max_transaction_amount": 12000000, "amex_mid": null, "discover_mid": null, "url": "www.LeesSandwiches.com", "annual_card_volume": 12000000, "has_accepted_credit_cards_previously": true, "incorporation_date": { "day": 27, "month": 6, "year": 1978 }, "principal_percentage_ownership": 50, "short_business_name": null, "ownership_type": "PRIVATE", "tax_authority": null, "tax_id_provided": true, "business_tax_id_provided": true, "default_statement_descriptor": "Lees Sandwiches" }, "identity_roles": [], "tags": { "Studio Rating": "4.7" } } ] } } ``` ### Identity updated The event you receive when an `Identity` gets updated. ```json { "type": "updated", "entity": "identity", "occurred_at": "2020-04-26T21:20:41.439", "_embedded": { "identitys": [ { "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T21:20:41.35Z", "created_at": "2020-04-26T21:06:11.27Z", "id": "IDdpvBpQ9m6D3JDCRq9UDB2E", "entity": { "title": "CTO", "first_name": "Bernard", "last_name": "Sterling", "email": "user@example.org", "business_name": "Finix Flowers", "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP", "doing_business_as": "Finix Flowers", "phone": "7144177878", "business_phone": "+1 (408) 756-4497", "personal_address": { "line1": "712 Douglass St", "line2": "Apartment 2", "city": "San Diego", "region": "CA", "postal_code": "94194", "country": "USA" }, "business_address": { "line1": "741 Douglass St", "line2": "Apartment 8", "city": "San Mateo", "region": "CA", "postal_code": "94114", "country": "USA" }, "mcc": "4900", "dob": { "day": 2, "month": 5, "year": 1988 }, "max_transaction_amount": 1200000, "amex_mid": null, "discover_mid": null, "url": "www.Finix.com", "annual_card_volume": 12000000, "has_accepted_credit_cards_previously": true, "incorporation_date": { "day": 27, "month": 6, "year": 1978 }, "principal_percentage_ownership": 50, "short_business_name": null, "ownership_type": "PRIVATE", "tax_authority": null, "tax_id_provided": true, "business_tax_id_provided": true, "default_statement_descriptor": "Finix Flowers" }, "identity_roles": [], "tags": { "key": "value_2" } } ] } } ``` ### Instrument history entry created The event you receive when a stored payment card's details are updated, creating an `Instrument History Entry` in a specific `Payment Instrument`'s history. ```json { "type": "created", "entity": "instrument_history", "occurred_at": "2020-04-26T22:58 :30.584", "_embedded": { "instrument_histories": [ { "id": "instrument_history_xxxxx", "created_at": "2022-10-11T01:42:22.32Z", "type": "NUMBER_AND_EXPIRATION_UPDATED", "application_id": "APgPDQrLD52TYvqazjHJJchM", "payment_instrument_id": "PIxxx", "payment_instrument_type": "PAYMENT_CARD", "old_instrument_details": { "bin": "411111", "brand": "VISA", "expiration_month": "11", "expiration_year": "2029", "last_four": "4111", "fingerprint": "FPRonNPcX7ifi8SXBgcZs7a52" }, "new_instrument_details": { "bin": "411111", "brand": "VISA", "expiration_month": "10", "expiration_year": "2030", "last_four": "4112", "fingerprint": "FPRnpe4F5RfPbyKaATT5Udjif" } } ] } } ``` ### Merchant provisioned When your Merchant is provisioned, Finix sends 6 webhook events: 1. Merchant Created 2. Merchant Profile Created 3. Verification Created 4. Merchant Underwritten 5. Verification Approved 6. Merchant Approved #### Merchant created The event you receive when you create a `Merchant`. ```json { "type": "created", "entity": "merchant", "occurred_at": "2020-04-26T21:54:59.958", "_embedded": { "merchants": [ { "card_expiration_date_required": false, "settlement_enabled": false, "mid": null, "merchant_name": "Finix Flowers", "created_at": "2020-04-26T21:54:59.43Z", "processing_enabled": false, "mcc": "4900", "processor": "DUMMY_V1", "creating_transfer_from_report_enabled": false, "merchant_profile": "MPcQELZpgPU7dq1ZsCjnZQDS", "tags": { "key_2": "value_2" }, "card_cvv_required": false, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T21:54:59.43Z", "identity": "IDdpvBpQ9m6D3JDCRq9UDB2E", "processor_details": {}, "id": "MUrFRV3YDxDGJBA9G8dmuKCk", "onboarding_state": "PROVISIONING", "verification": null, "gross_settlement_enabled": false } ] } } ``` #### Merchant profile created The event you receive when the `Merchant Profile` gets automatically created for your new `Merchant`. ```json { "type": "created", "entity": "merchant_profile", "occurred_at": "2020-04-26T21:54:59.692", "_embedded": { "merchant_profiles": [ { "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T21:54:59.42Z", "fee_profile": null, "risk_profile": "RPjhkhnYKWWMHwwuX1JuxinW", "created_at": "2020-04-26T21:54:59.42Z", "id": "MPcQELZpgPU7dq1ZsCjnZQDS", "tags": {} } ] } } ``` #### Verification created The event you receive when you create the `Verification` to underwrite the new `Merchant`. ```json { "type": "created", "entity": "verification", "occurred_at": "2020-04-26T21:54:59.83", "_embedded": { "verifications": [ { "trace_id": "2456e6d0-f2b1-4626-8936-28728e7c2a0d", "payment_instrument": null, "raw": null, "created_at": "2020-04-26T21:54:59.46Z", "merchant": "MUrFRV3YDxDGJBA9G8dmuKCk", "processor": "DUMMY_V1", "tags": { "key_2": "value_2" }, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T21:54:59.50Z", "identity": null, "messages": [], "id": "VImsN9J9VU9y9uGNyaE3TjC5", "state": "PENDING" } ] } } ``` #### Merchant underwritten The event you receive when the `Merchant` gets submitted for underwriting. ```json { "type": "underwritten", "entity": "merchant", "occurred_at": "2020-04-26T21:55:06.626", "_embedded": { "merchants": [ { "card_expiration_date_required": false, "settlement_enabled": false, "mid": null, "merchant_name": "Finix Flowers", "created_at": "2020-04-26T21:54:59.43Z", "processing_enabled": false, "mcc": "4900", "processor": "DUMMY_V1", "creating_transfer_from_report_enabled": false, "merchant_profile": "MPcQELZpgPU7dq1ZsCjnZQDS", "tags": { "key_2": "value_2" }, "card_cvv_required": false, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T21:55:01.90Z", "identity": "IDdpvBpQ9m6D3JDCRq9UDB2E", "processor_details": { "api_key": "secretValue" }, "id": "MUrFRV3YDxDGJBA9G8dmuKCk", "onboarding_state": "APPROVED", "verification": "VImsN9J9VU9y9uGNyaE3TjC5", "gross_settlement_enabled": false } ] } } ``` #### Verification approved The event you receive when the `Verification` request to underwrite the `Merchant` get approved. If approved, `state` gets updated to `SUCCEEDED`. ```json { "type": "updated", "entity": "verification", "occurred_at": "2020-04-26T21:55:07.337", "_embedded": { "verifications": [ { "trace_id": "2456e6d0-f2b1-4626-8936-28728e7c2a0d", "payment_instrument": null, "raw": "RawDummyMerchantUnderwriteResult", "created_at": "2020-04-26T21:54:59.46Z", "merchant": "MUrFRV3YDxDGJBA9G8dmuKCk", "processor": "DUMMY_V1", "tags": { "key_2": "value_2" }, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T21:55:06.72Z", "identity": null, "messages": [], "id": "VImsN9J9VU9y9uGNyaE3TjC5", "state": "SUCCEEDED" } ] } } ``` #### Merchant approved The event you receive when the `Merchant` gets approved and enabled to process payments. When the `Merchant` gets approved, `processing_enabled` gets updated to `true`. ```json { "type": "updated", "entity": "merchant", "occurred_at": "2020-04-26T21:55:07.46", "_embedded": { "merchants": [ { "card_expiration_date_required": false, "settlement_enabled": true, "mid": null, "merchant_name": "Finix Flowers", "created_at": "2020-04-26T21:54:59.43Z", "processing_enabled": true, "mcc": "4900", "processor": "DUMMY_V1", "creating_transfer_from_report_enabled": false, "merchant_profile": "MPcQELZpgPU7dq1ZsCjnZQDS", "tags": { "key_2": "value_2" }, "card_cvv_required": false, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T21:55:06.72Z", "identity": "IDdpvBpQ9m6D3JDCRq9UDB2E", "processor_details": { "api_key": "secretValue" }, "id": "MUrFRV3YDxDGJBA9G8dmuKCk", "onboarding_state": "APPROVED", "verification": "VImsN9J9VU9y9uGNyaE3TjC5", "gross_settlement_enabled": false } ] } } ``` ### Merchant provisioned (card present) The events that get sent when a `Merchant` is provisioned to process card present transactions. #### Merchant created The event you receive when you create a `Merchant`. ```json { "type": "created", "entity": "merchant", "occurred_at": "2020-04-26T22:30:41.801", "_embedded": { "merchants": [ { "card_expiration_date_required": false, "settlement_enabled": false, "mid": null, "merchant_name": "Finix Flowers", "created_at": "2020-04-26T22:30:41.50Z", "processing_enabled": false, "mcc": "4900", "processor": "VANTIV_V1", "creating_transfer_from_report_enabled": false, "merchant_profile": "MPix8GV6WTWv8hWVxvWV2unm", "tags": {}, "card_cvv_required": false, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T22:30:41.50Z", "identity": "IDdpvBpQ9m6D3JDCRq9UDB2E", "processor_details": {}, "id": "MUeLemkwC6WSaaZLUUB1Y7mr", "onboarding_state": "PROVISIONING", "verification": null, "gross_settlement_enabled": false } ] } } ``` #### Merchant profile created The event you receive when the `Merchant Profile` gets automatically created for your new `Merchant`. ```json { "type": "created", "entity": "merchant_profile", "occurred_at": "2020-04-26T22:30:41.731", "_embedded": { "merchant_profiles": [ { "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T22:30:41.49Z", "fee_profile": null, "risk_profile": "RPjhkhnYKWWMHwwuX1JuxinW", "created_at": "2020-04-26T22:30:41.49Z", "id": "MPix8GV6WTWv8hWVxvWV2unm", "tags": {} } ] } } ``` #### Initial Verification created The event you receive when you create the `Verification` to underwrite the new `Merchant`. ```json { "type": "created", "entity": "verification", "occurred_at": "2020-04-26T22:30:41.636", "_embedded": { "verifications": [ { "trace_id": "FNX4YG8ut4zJQekpQGZbtZL2a", "payment_instrument": null, "raw": null, "created_at": "2020-04-26T22:30:41.50Z", "merchant": "MUeLemkwC6WSaaZLUUB1Y7mr", "processor": "VANTIV_V1", "tags": {}, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T22:30:41.52Z", "identity": null, "messages": [], "id": "VIpdSnQwTNeWgMHXvFDCPVsx", "state": "PENDING" } ] } } ``` #### Initial Verification failed The event you receive when the `Verification` request to underwrite the `Merchant` get denied. If denied, `state` gets updated to `FAILED`. ```json { "type": "updated", "entity": "verification", "occurred_at": "2020-04-26T22:31:15.486", "_embedded": { "verifications": [ { "trace_id": "FNX4YG8ut4zJQekpQGZbtZL2a", "payment_instrument": null, "raw": "MerchantResponse(correlationId=null, httpStatusCode=500, httpStatusMessage=Original response had no body, id=null, mid=null, acceptedCards=null, expressSubAccount=null, errors=[Error(errorCode=null, errorMessage=Original response had no body. Please check Vantiv credentials or health status of Vantiv service, target=null)])", "created_at": "2020-04-26T22:30:41.50Z", "merchant": "MUeLemkwC6WSaaZLUUB1Y7mr", "processor": "VANTIV_V1", "tags": {}, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T22:31:15.23Z", "identity": null, "messages": [ "Error(errorCode=null, errorMessage=Original response had no body. Please check Vantiv credentials or health status of Vantiv service, target=null)" ], "id": "VIpdSnQwTNeWgMHXvFDCPVsx", "state": "FAILED" } ] } } ``` #### Merchant rejected The event you receive when the request to underwrite the `Merchant` get denied. If denied, `onboarding_state` gets updated to `REJECTED`. ```json { "type": "updated", "entity": "merchant", "occurred_at": "2020-04-26T22:31:15.59", "_embedded": { "merchants": [ { "card_expiration_date_required": false, "settlement_enabled": false, "mid": null, "merchant_name": "Finix Flowers", "created_at": "2020-04-26T22:30:41.50Z", "processing_enabled": false, "mcc": "4900", "processor": "VANTIV_V1", "creating_transfer_from_report_enabled": false, "merchant_profile": "MPix8GV6WTWv8hWVxvWV2unm", "tags": {}, "card_cvv_required": false, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T22:31:15.23Z", "identity": "IDdpvBpQ9m6D3JDCRq9UDB2E", "processor_details": {}, "id": "MUeLemkwC6WSaaZLUUB1Y7mr", "onboarding_state": "REJECTED", "verification": "VIpdSnQwTNeWgMHXvFDCPVsx", "gross_settlement_enabled": false } ] } } ``` #### Second Verification created The event you receive when you create the second `Verification` to try underwriting the new `Merchant` again. ```json { "type": "created", "entity": "verification", "occurred_at": "2020-04-26T22:33:10.198", "_embedded": { "verifications": [ { "trace_id": "85f2b5a5-0c58-4382-bf94-349b738db6c3", "payment_instrument": null, "raw": null, "created_at": "2020-04-26T22:33:10.12Z", "merchant": "MUrFRV3YDxDGJBA9G8dmuKCk", "processor": "DUMMY_V1", "tags": {}, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T22:33:10.14Z", "identity": null, "messages": [], "id": "VIwq2UdpXyUoDGW3e4uwY2dB", "state": "PENDING" } ] } } ``` #### Second attempt to underwrite Merchant The event you receive when the `Merchant` gets submitted again for underwriting. ```json { "type": "underwritten", "entity": "merchant", "occurred_at": "2020-04-26T22:34:06.036", "_embedded": { "merchants": [ { "card_expiration_date_required": false, "settlement_enabled": true, "mid": null, "merchant_name": "Finix Flowers", "created_at": "2020-04-26T21:54:59.43Z", "processing_enabled": true, "mcc": "4900", "processor": "DUMMY_V1", "creating_transfer_from_report_enabled": false, "merchant_profile": "MPcQELZpgPU7dq1ZsCjnZQDS", "tags": { "key_2": "value_2" }, "card_cvv_required": false, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T21:55:06.72Z", "identity": "IDdpvBpQ9m6D3JDCRq9UDB2E", "processor_details": { "api_key": "secretValue" }, "id": "MUrFRV3YDxDGJBA9G8dmuKCk", "onboarding_state": "APPROVED", "verification": "VIwq2UdpXyUoDGW3e4uwY2dB", "gross_settlement_enabled": false } ] } } ``` #### Verification approved The event you receive when the second `Verification` request to underwrite the `Merchant` get approved. If approved, `state` gets updated to `SUCCEEDED`. ```json { "type": "updated", "entity": "verification", "occurred_at": "2020-04-26T22:34:06.323", "_embedded": { "verifications": [ { "trace_id": "85f2b5a5-0c58-4382-bf94-349b738db6c3", "payment_instrument": null, "raw": "RawDummyMerchantUnderwriteResult", "created_at": "2020-04-26T22:33:10.12Z", "merchant": "MUrFRV3YDxDGJBA9G8dmuKCk", "processor": "DUMMY_V1", "tags": {}, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T22:34:06.15Z", "identity": null, "messages": [], "id": "VIwq2UdpXyUoDGW3e4uwY2dB", "state": "SUCCEEDED" } ] } } ``` ### Merchant provisioning (reattempted) The events that get sent when another attempt is made to provision (underwrite) the `Merchant`. #### Verification created The event you receive when you create the `Verification` to underwrite (or provision) the new `Merchant`. ```json { "type": "created", "entity": "verification", "occurred_at": "2020-04-26T22:10:44.523", "_embedded": { "verifications": [ { "trace_id": "f7375d38-9ed0-4d86-b62d-a8f692f635cb", "payment_instrument": null, "raw": null, "created_at": "2020-04-26T22:10:44.42Z", "merchant": "MUrFRV3YDxDGJBA9G8dmuKCk", "processor": "DUMMY_V1", "tags": {}, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T22:10:44.45Z", "identity": null, "messages": [], "id": "VIb691JRnMdz4M73yi6jAmCN", "state": "PENDING" } ] } } ``` #### Verification approved The event you receive when the `Verification` request to underwrite the `Merchant` get approved. If approved, `state` gets updated to `SUCCEEDED`. ```json { "type": "updated", "entity": "verification", "occurred_at": "2020-04-26T22:11:05.955", "_embedded": { "verifications": [ { "trace_id": "f7375d38-9ed0-4d86-b62d-a8f692f635cb", "payment_instrument": null, "raw": "RawDummyMerchantUnderwriteResult", "created_at": "2020-04-26T22:10:44.42Z", "merchant": "MUrFRV3YDxDGJBA9G8dmuKCk", "processor": "DUMMY_V1", "tags": {}, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T22:11:05.76Z", "identity": null, "messages": [], "id": "VIb691JRnMdz4M73yi6jAmCN", "state": "SUCCEEDED" } ] } } ``` #### Merchant underwritten The event you receive when the `Merchant` gets submitted for underwriting. ```json { "type": "underwritten", "entity": "merchant", "occurred_at": "2020-04-26T22:11:05.686", "_embedded": { "merchants": [ { "card_expiration_date_required": false, "settlement_enabled": true, "mid": null, "merchant_name": "Finix Flowers", "created_at": "2020-04-26T21:54:59.43Z", "processing_enabled": true, "mcc": "4900", "processor": "DUMMY_V1", "creating_transfer_from_report_enabled": false, "merchant_profile": "MPcQELZpgPU7dq1ZsCjnZQDS", "tags": { "key_2": "value_2" }, "card_cvv_required": false, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T21:55:06.72Z", "identity": "IDdpvBpQ9m6D3JDCRq9UDB2E", "processor_details": { "api_key": "secretValue" }, "id": "MUrFRV3YDxDGJBA9G8dmuKCk", "onboarding_state": "APPROVED", "verification": "VIb691JRnMdz4M73yi6jAmCN", "gross_settlement_enabled": false } ] } } ``` ### Onboarding Form created The event you receive when an [`onboarding_form` gets created](/guides/platform-payments/onboarding-sellers/seller-onboarding-forms/). ```json { "id": "event_3M7pFpzorXGdtSDaBubCkt", "type": "created", "entity": "onboarding_form", "occurred_at": "2022-12-12T21:37:44.385255", "_embedded": { "onboarding_forms": [ { "merchant_processors": [ { "processor": "DUMMY_V1" } ], "onboarding_link": { "expires_at": "2022-12-12T22:07:43.48Z", "link_url": "https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_7EMbv4C2bCvzFkVFwDWnEo&applicationId=APgPDQrLD52TYvqazjHJJchM&bearerToken=..." }, "onboarding_data": { "entity": {}, "associated_entities": [], "payment_instruments": {}, "additional_underwriting_data": {}, "max_transaction_amount": 100000 }, "updated_at": "2022-12-12T21:37:43.466129Z", "identity_id": null, "onboarding_link_details": { "return_url": "https://www.finix.com/docs", "expired_session_url": "https://www.finix.com/", "fee_details_url": "https://www.finix.com/docs", "terms_of_service_url": "https://www.finix.com/terms-and-policies", "expiration_in_minutes": 10080 }, "created_at": "2022-12-12T21:37:43.466129Z", "id": "obf_7EMbv4C2bCvzFkVFwDWnEo", "application_id": "APgPDQrLD52TYvqazjHJJchM", "status": "IN_PROGRESS", "tags": {} } ] } } ``` ### Onboarding Form updated The event you receive when an [`onboarding_form` gets updated or submitted](/guides/platform-payments/onboarding-sellers/seller-onboarding-forms/). ```json { "type": "updated", "entity": "onboarding_form", "occurred_at": "2022-12-12T21:37:44.385255", "_embedded": { "onboarding_forms": [ { "id": "obf_7EMbv4C2bCvzFkVFwDWnEo", "onboarding_data": { "entity": { "title": "CEO", "first_name": "John", "last_name": "Smith", "email": "john@example.com", "business_name": "Finix Flowers", "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP", "doing_business_as": "Finix Flowers", "phone": "5558675309", "business_phone": "5558675309", "mcc": "4900", "url": "example.com", "ownership_type": "PRIVATE", "default_statement_descriptor": "FNX", "max_transaction_amount": 100000, "annual_card_volume": "10000000", "principal_percentage_ownership": "100", "tax_id": "*****6789", "business_tax_id": "*****6890", "personal_address": { "line1": "631 Howard St.", "city": "San Francisco", "region": "CA", "postal_code": "94105", "country": "USA" }, "business_address": { "line1": "631 Howard St.", "city": "San Francisco", "region": "CA", "postal_code": "94105", "country": "USA" }, "dob": { "day": 1, "month": 1, "year": 1981 }, "incorporation_date": { "day": 1, "month": 1, "year": 2007 } }, "payment_instruments": { "name": "John Smith", "bank_code": "123456789", "account_number": "*****6789", "account_type": "CHECKING", "type": "BANK_ACCOUNT" }, "additional_underwriting_data": { "refund_policy": "NO_REFUNDS", "average_ach_transfer_amount": 0, "average_card_transfer_amount": 10000, "merchant_agreement_ip_address": "4.14.107.114", "merchant_agreement_accepted": true, "merchant_agreement_timestamp": "2022-11-16T00:53:45.228537Z", "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36", "annual_ach_volume": 0, "business_description": "Flowers", "volume_distribution_by_business_type": { "other_volume_percentage": 0, "business_to_business_volume_percentage": 100, "business_to_consumer_volume_percentage": 0 }, "card_volume_distribution": { "ecommerce_percentage": 100, "card_present_percentage": 0, "mail_order_telephone_order_percentage": 0 } }, "max_transaction_amount": 100000 }, "merchant_processors": [ { "processor": "DUMMY_V1" } ], "onboarding_link_details": { "return_url": "https://www.example.com/finix-handlers/onboarding-return", "expired_session_url": "https://www.example.com/finix-handlers/onboarding-expires", "fee_details_url": "https://www.finix.com/docs", "terms_of_service_url": "https://www.finix.com/terms-and-policies", "expiration_in_minutes": 10080 }, "status": "COMPLETED", "identity_id": "ID8XfQPGnxM2oviYgdzjMWsn", "application_id": "APgPDQrLD52TYvqazjHJJchM", "created_at": "2022-11-16T00:50:23.787426Z", "updated_at": "2022-11-16T00:53:46.124008Z", "tags": { "seller": "Finix Flowers" } } ] } } ``` ### Payment Instrument created (bank account) The event you receive when a `Payment Instrument` is created using the information of a bank account. ```json { "type": "created", "entity": "instrument", "occurred_at": "2020-04-26T21:24:03.139", "_embedded": { "instruments": [ { "bank_code": "123123123", "country": "USA", "account_type": "SAVINGS", "created_at": "2020-04-26T21:24:03.06Z", "instrument_type": "BANK_ACCOUNT", "type": "BANK_ACCOUNT", "tags": { "Bank Account": "Company Account" }, "masked_account_number": "XXXXX3123", "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T21:24:03.06Z", "identity": "IDdpvBpQ9m6D3JDCRq9UDB2E", "fingerprint": "FPRd5moHxL3Ltuvk4cczxetCg", "name": "John", "currency": "USD", "id": "PInwJvRi22wrz4j5Mx3ghBE9" } ] } } ``` ### Payment Instrument created (card) The event you receive when a `Payment Instrument` is created from a credit or debit card. ```json { "type": "created", "entity": "instrument", "occurred_at": "2020-04-26T21:22:57.287", "_embedded": { "instruments": [ { "address": { "line1": "900 Metro Center Blv", "line2": null, "city": "San Francisco", "region": "CA", "postal_code": "94404", "country": "USA" }, "address_verification": "UNKNOWN", "bin": "489514", "security_code_verification": "UNKNOWN", "created_at": "2020-04-26T21:22:57.21Z", "instrument_type": "PAYMENT_CARD", "card_type": "UNKNOWN", "type": "PAYMENT_CARD", "tags": { "card_name": "Business Card" }, "expiration_year": 2029, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T21:22:57.21Z", "last_four": "0006", "identity": "IDe5JkBhBeW3ZEvzqWc8kmXd", "fingerprint": "FPRogKWsRQks2HGaau5eGR9AF", "expiration_month": 3, "name": "John Smith", "currency": "USD", "id": "PIoBQHZFB3p8UM8HasuN6icB", "brand": "VISA" } ] } } ``` ### Payment Instrument updated The events that get sent when [`Payment Instruments` gets manually updated with a PUT request](/api/payment-instruments/updatepaymentinstrument). ```json { "id": "event_7849EPiVUN9dknfmPoctE6", "system_generated_idempotency_id": "7849EPiVUN9dknfmPoctE6", "type": "updated", "entity": "instrument", "occurred_at": "2023-03-03T17:31:01.465843", "_embedded": { "instruments": [ { "bin": "558958", "created_at": "2023-03-03T17:30:59.89Z", "instrument_type": "PAYMENT_CARD", "type": "PAYMENT_CARD", "enabled": true, "issuer_country": "USA", "updated_at": "2023-03-03T17:30:59.89Z", "last_four": "0770", "identity": "ID4NxfCXYDu8NiueXHm8JUCb", "fingerprint": "FPRoD2LpBkgJDaUBAAmtdQPAn", "expiration_month": 9, "currency": "USD", "id": "PIicBscsDiBfs6QW2C5gQvGa", "brand": "VISA", "disabled_code": null, "address": { "line1": "631 Howard St", "line2": null, "city": "San Francisco", "region": "CA", "postal_code": "94105", "country": null }, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "created_via": "API", "security_code_verification": "MATCHED", "disabled_message": null, "card_type": "CREDIT", "tags": {}, "expiration_year": 2027, "application": "APot9H635fZLZuRNZDS6bbsU", "name": "John Smith" } ] } } ``` ### Payment Link created The event you receive when a Payment Link is created. ```json { "_embedded": { "payment_links": [ { "additional_details": { "collect_billing_address": false, "collect_email": true, "collect_name": true, "collect_phone": false, "collect_shipping_address": false, "expiration_in_minutes": 10080, "expired_session_url": "https://cannon.com/error.html", "receipt_requested_delivery_methods": [ { "destinations": ["2348765431"], "type": "SMS" } ], "send_receipt": false, "success_return_url": "https://www.cannon.com/success/123rw21w.html", "terms_of_service_url": "https://cannon.com/terms_of_service.html", "unsuccessful_return_url": "https://www.cannon.com/success/123rw21w.html" }, "allowed_payment_methods": [ "BANK_ACCOUNT", "PAYMENT_CARD", "APPLE_PAY", "GOOGLE_PAY" ], "amount_details": { "amount_breakdown": { "additional_buyer_charges": null, "customs_duty_amount": null, "discount_amount": 1000, "estimated_tax_amount": 429, "shipping_amount": 995, "subtotal_amount": 3994, "tax_exempt": false, "tip_amount": 1000 }, "amount_type": "FIXED", "currency": "USD", "max_amount": null, "min_amount": null, "total_amount": 5418 }, "application_id": "APscsFoe6BF78faCJ53CCTe8", "attempt_l2_l3_payment": false, "branding": { "accent_color": "my_accent_color", "brand_color": "my_brand_color", "button_font_color": null, "icon": "my_icon_url", "logo": "my_logo_url", "logo_alternative_text": "logo alternative text payment links" }, "buyer_details": null, "created_at": "2025-05-28T15:10:07.809171Z", "id": "payment_link_coz97Uxc1o9JV3Yr9rQfd", "is_multiple_use": true, "items": [ { "description": "this is cool sunglasses", "image_details": { "alternative_image_urls": [ "https://google.com/image1", "https://google.com/image2" ], "primary_image_url": "https://google.com/image" }, "item_details": null, "name": null, "price_details": { "amount_excluding_sales_tax": null, "currency": "USD", "item_discount_amount": null, "price_type": "PROMOTIONAL", "regular_amount": 5000, "sale_amount": 4000 }, "quantity": 1 } ], "link_expires_at": "2025-06-04T15:10:07.769552Z", "link_url": "https://link.qa-payments-checkout.com/zW6Xpq", "merchant_id": "MU5tYxn1K1foFfmCqWYBRQZL", "nickname": "string", "payment_frequency": "ONE_TIME", "state": "ACTIVE", "tags": {}, "updated_at": "2025-05-28T15:10:07.809171Z" } ] }, "entity": "payment_link", "id": "event_qDjqAX2xUQC8zmoLeVSwcv", "occurred_at": "2025-05-28T15:10:08.173467826", "system_generated_idempotency_id": "qDjqAX2xUQC8zmoLeVSwcv", "type": "created" } ``` ### Payment Link updated The event you receive when a Payment Link is updated. ```json { "_embedded": { "payment_links": [ { "additional_details": { "collect_billing_address": false, "collect_email": true, "collect_name": true, "collect_phone": false, "collect_shipping_address": false, "expiration_in_minutes": 10080, "expired_session_url": "https://cannon.com/error.html", "receipt_requested_delivery_methods": [ { "destinations": ["2348765431"], "type": "SMS" } ], "send_receipt": false, "success_return_url": "https://www.cannon.com/success/123rw21w.html", "terms_of_service_url": "https://cannon.com/terms_of_service.html", "unsuccessful_return_url": "https://www.cannon.com/success/123rw21w.html" }, "allowed_payment_methods": ["BANK_ACCOUNT", "APPLE_PAY", "GOOGLE_PAY"], "amount_details": { "amount_breakdown": { "additional_buyer_charges": null, "customs_duty_amount": null, "discount_amount": 1000, "estimated_tax_amount": 429, "shipping_amount": 995, "subtotal_amount": 3994, "tax_exempt": false, "tip_amount": 1000 }, "amount_type": "FIXED", "currency": "USD", "max_amount": null, "min_amount": null, "total_amount": 5418 }, "application_id": "APscsFoe6BF78faCJ53CCTe8", "attempt_l2_l3_payment": false, "branding": { "accent_color": "my_accent_color", "brand_color": "my_brand_color", "button_font_color": null, "icon": "my_icon_url", "logo": "my_logo_url", "logo_alternative_text": "logo alternative text payment links" }, "buyer_details": null, "created_at": "2025-05-28T15:10:07.809171Z", "id": "payment_link_coz97Uxc1o9JV3Yr9rQfd", "is_multiple_use": true, "items": [ { "description": "this is cool sunglasses", "image_details": { "alternative_image_urls": [ "https://google.com/image1", "https://google.com/image2" ], "primary_image_url": "https://google.com/image" }, "item_details": null, "name": null, "price_details": { "amount_excluding_sales_tax": null, "currency": "USD", "item_discount_amount": null, "price_type": "PROMOTIONAL", "regular_amount": 5000, "sale_amount": 4000 }, "quantity": 1 } ], "link_expires_at": "2025-06-04T15:10:07.769552Z", "link_url": "https://link.qa-payments-checkout.com/zW6Xpq", "merchant_id": "MU5tYxn1K1foFfmCqWYBRQZL", "nickname": "string", "payment_frequency": "ONE_TIME", "state": "ACTIVE", "tags": {}, "updated_at": "2025-05-28T15:10:07.809171Z" } ] }, "entity": "payment_link", "id": "event_qDjqAX2xUQC8zmoLeVSwcv", "occurred_at": "2025-05-28T15:10:08.173467826", "system_generated_idempotency_id": "qDjqAX2xUQC8zmoLeVSwcv", "type": "updated" } ``` ### Payout Profile created The event that's sent when the [payout settings](/guides/platform-payments/seller-payouts/managing-seller-payouts) of a `Merchant` are changed or updated. ```json { "type": "created", "entity": "payout_profile", "occurred_at": "2022-08-05T18:46:47.488477", "_embedded": { "payout_profiles": [ { "updated_at": "2022-08-05T11:46:46.52Z", "created_at": "2022-08-05T11:46:46.52Z", "id": "POwgvawdPpTfE2fvayUi4FJ1", "linked_type": "MERCHANT", "type": "NET", "net": { "frequency": "DAILY", "submission_delay_days": 0, "payment_instrument_id": "PI8K6j4DkAuoD56mcxKxic9d", "rail": "STANDARD" }, "linked_id": "MU84HSuYw9GSVxWoiXuMsPdH", "tags": {} } ] } } ``` ### Subscription created The event you receive when a `Subscription` is created. ```json { "_embedded": { "subscriptions": [ { "id": "subscription_copEkMmqfLWCWKmeeYMHS", "amount": 10000, "billing_interval": "MONTHLY", "buyer_details": { "identity_id": "IDiyCN29J7cLjKftvqayu7km", "instrument_id": "PI5YgtbPbBdCcYnf9zNpyX3b", "requested_delivery_methods": [] }, "canceled_via": null, "created_at": "2025-05-23T15:00:30.64Z", "currency": "USD", "expires_at": null, "first_charge_at": "2025-05-23T15:00:30.00Z", "linked_to": "MUvPwWkxGW4ddABQsnBe133o", "linked_type": "MERCHANT", "next_billing_date": { "day": 23, "month": 5, "year": 2025 }, "nickname": "My awesome subscription", "start_subscription_at": "2025-05-23T00:00:00.000Z", "state": "ACTIVE", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "discount_phase_details": null, "send_invoice": false, "send_receipt": false, "trial_details": null }, "subscription_link_id": null, "subscription_phase": "EVERGREEN", "subscription_plan_id": "subscription_plan_copEkD65sYwiLR39ffSWk", "tags": {}, "total_billing_intervals": null, "updated_at": "2025-05-23T15:00:44.43Z" } ] }, "entity": "subscription", "id": "event_4K9BCzgFetumnw4JGat7r5", "occurred_at": "2025-05-23T15:01:11.134482181", "system_generated_idempotency_id": "4K9BCzgFetumnw4JGat7r5", "type": "created" } ``` ### Subscription updated The event you receive when a `Subscription` is updated. ```json { "_embedded": { "subscriptions": [ { "id": "subscription_copEkMmqfLWCWKmeeYMHS", "amount": 10000, "billing_interval": "MONTHLY", "buyer_details": { "identity_id": "IDiyCN29J7cLjKftvqayu7km", "instrument_id": "PI5YgtbPbBdCcYnf9zNpyX3b", "requested_delivery_methods": [] }, "canceled_via": null, "created_at": "2025-05-23T15:00:30.64Z", "currency": "USD", "expires_at": null, "first_charge_at": "2025-05-23T15:00:30.00Z", "linked_to": "MUvPwWkxGW4ddABQsnBe133o", "linked_type": "MERCHANT", "next_billing_date": { "day": 23, "month": 5, "year": 2025 }, "nickname": "My awesome subscription", "start_subscription_at": "2025-05-23T00:00:00.000Z", "state": "ACTIVE", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "discount_phase_details": null, "send_invoice": false, "send_receipt": false, "trial_details": null }, "subscription_link_id": null, "subscription_phase": "EVERGREEN", "subscription_plan_id": "subscription_plan_copEkD65sYwiLR39ffSWk", "tags": {}, "total_billing_intervals": null, "updated_at": "2025-05-23T15:00:44.43Z" } ] }, "entity": "subscription", "id": "event_4K9BCzgFetumnw4JGat7r5", "occurred_at": "2025-05-23T15:01:11.134482181", "system_generated_idempotency_id": "4K9BCzgFetumnw4JGat7r5", "type": "updated" } ``` ### Refund, debit The event you receive when refunding or reversing a debit. The event that gets sent has: - `type: created` - `entity: transfer` - `_embedded.transfers[0].type: REVERSAL` ```json { "type": "created", "entity": "transfer", "occurred_at": "2020-04-26T23:47:33.443", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 100, "trace_id": "df499916-5cda-45f0-b1d9-3d59460cd867", "fee": 0, "destination": "PI5JEJTNwLzZ8rMMFV9QkaHz", "raw": null, "created_at": "2020-04-26T23:47:33.17Z", "source": null, "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDdpvBpQ9m6D3JDCRq9UDB2E", "type": "REVERSAL", "tags": {}, "statement_descriptor": "FIN*FINIX FLOWERS", "ready_to_settle_at": null, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T23:47:33.39Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRxiRsBXhWp7ZdVwkRiEEjFm", "state": "PENDING" } ] } } ``` ### Refund, referenced (card present) The events you receive when a Card Present Transfer gets refunded/reversed. #### Transfer created The event you receive when a `Transfer` gets created to refund a transaction. A `Transfer` created to process a refund will have `type: REVERSAL`. ```json { "type": "created", "entity": "transfer", "occurred_at": "2020-04-29T20:37:36.256", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 1000, "trace_id": "FNX2kW6zCR27aD9rqgxzXuHRE", "fee": 0, "destination": "PInJceezonsp9C5Vcta3azs1", "raw": null, "created_at": "2020-04-29T20:37:33.74Z", "source": null, "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "REVERSAL", "tags": {}, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": "2020-04-29T20:37:35.87Z", "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:37:35.87Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TR9c8iiP5dsWnqQvMQgWowH1", "state": "PENDING", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` #### Transfer updated The event you receive when a reversal `Transfer` gets updated to `SUCCEEDED`. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2020-04-29T20:37:35.955", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 1000, "trace_id": "FNX2kW6zCR27aD9rqgxzXuHRE", "fee": 0, "destination": "PInJceezonsp9C5Vcta3azs1", "raw": null, "created_at": "2020-04-29T20:37:33.74Z", "source": null, "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "REVERSAL", "tags": {}, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": null, "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:37:35.87Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TR9c8iiP5dsWnqQvMQgWowH1", "state": "SUCCEEDED", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` #### Transfer ready to settle The event you receive when the `Transfer` is ready [for approval in a `Settlement`](/guides/platform-payments/seller-payouts). A transfer is ready to settle when `ready_to_settle_at` gets updated with a timestamp. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2020-04-29T20:37:35.955", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 1000, "trace_id": "FNX2kW6zCR27aD9rqgxzXuHRE", "fee": 0, "destination": "PInJceezonsp9C5Vcta3azs1", "raw": null, "created_at": "2020-04-29T20:37:33.74Z", "source": null, "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "REVERSAL", "tags": {}, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": "2020-04-29T20:37:35.87Z", "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:37:35.87Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TR9c8iiP5dsWnqQvMQgWowH1", "state": "SUCCEEDED", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` ### Refund, unreferenced (card present swipe card) The events you receive when an unreferenced refund gets processed for a card present transaction. #### Transfer created The event you receive when a `Transfer` gets created to refund a transaction where the card was swiped. A `Transfer` created to process a refund for a swiped card will have `type: CREDIT`. ```json { "type": "created", "entity": "transfer", "occurred_at": "2020-04-29T20:38:15.648", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 5000, "trace_id": "FNX4KXt8NXXttQZAghLj4jxtR", "fee": 0, "destination": "PI2KVAR4aohyZB9FTi23s18L", "raw": null, "created_at": "2020-04-29T20:38:15.49Z", "source": null, "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "CREDIT", "tags": { "order_number": "test" }, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": null, "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:38:15.59Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRc7FYetjSmUbKFVUTG5cJKq", "state": "PENDING", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` #### Transfer updated The event you receive when a reversal `Transfer` gets updated to `SUCCEEDED`. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2020-04-29T20:38:30.613", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 5000, "trace_id": "FNX4KXt8NXXttQZAghLj4jxtR", "fee": 0, "destination": "PI2KVAR4aohyZB9FTi23s18L", "raw": null, "created_at": "2020-04-29T20:38:15.49Z", "source": null, "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "CREDIT", "tags": { "order_number": "test" }, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": null, "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:38:30.56Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRc7FYetjSmUbKFVUTG5cJKq", "state": "SUCCEEDED", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` #### Transfer ready to settle The event you receive when the `Transfer` is ready [for approval in a `Settlement`](/guides/platform-payments/seller-payouts). A transfer is ready to settle when `ready_to_settle_at` gets updated with a timestamp. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2020-04-29T20:38:30.335", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 5000, "trace_id": "FNX4KXt8NXXttQZAghLj4jxtR", "fee": 0, "destination": "PI2KVAR4aohyZB9FTi23s18L", "raw": null, "created_at": "2020-04-29T20:38:15.49Z", "source": null, "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "CREDIT", "tags": { "order_number": "test" }, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": "2020-04-29T20:38:30.29Z", "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:38:30.28Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRc7FYetjSmUbKFVUTG5cJKq", "state": "SUCCEEDED", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` ### Sale with EMV card (card present) The events you receive when processing a `Transfer` with an EMV card. #### Transfer created The event you receive when a `Transfer` gets created to process a `Transfer` with an EMV card. The `Transfer` gets created with `state: PENDING`. ```json { "type": "created", "entity": "transfer", "occurred_at": "2020-04-29T20:32:40.5", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 20000, "trace_id": "FNXaEQJjdH6SLSNcU3JgUXenX", "fee": 0, "destination": null, "raw": null, "created_at": "2020-04-29T20:32:40.39Z", "source": "PIbARkH2cDxpXChBDTDtGzZz", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "DEBIT", "tags": {}, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": null, "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:32:40.46Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRj4BxdJJu3XHF2xh9BgF8J9", "state": "PENDING", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` #### Transfer updated The event you receive when a `Transfer` gets updated to `SUCCEEDED`. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2020-04-29T20:32:57.697", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 20000, "trace_id": "FNXaEQJjdH6SLSNcU3JgUXenX", "fee": 0, "destination": null, "raw": null, "created_at": "2020-04-29T20:32:40.39Z", "source": "PIbARkH2cDxpXChBDTDtGzZz", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "DEBIT", "tags": {}, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": null, "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:32:57.55Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRj4BxdJJu3XHF2xh9BgF8J9", "state": "SUCCEEDED", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` #### Transfer ready to settle The event you receive when the `Transfer` is ready for approval in a `Settlement`. A transfer is ready to settle when `ready_to_settle_at` gets updated with a timestamp. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2020-04-29T20:32:56.547", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 20000, "trace_id": "FNXaEQJjdH6SLSNcU3JgUXenX", "fee": 0, "destination": null, "raw": null, "created_at": "2020-04-29T20:32:40.39Z", "source": "PIbARkH2cDxpXChBDTDtGzZz", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "DEBIT", "tags": {}, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": "2020-04-29T20:32:56.51Z", "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:32:56.50Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRj4BxdJJu3XHF2xh9BgF8J9", "state": "SUCCEEDED", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` ### Sale with manual entry (card present) The events you receive when a `Transfer` is created for a transaction processed via manual entry. #### Transfer created The event you receive when a `Transfer` gets created for a transaction processed via manual entry. ```json { "type": "created", "entity": "transfer", "occurred_at": "2020-04-29T20:34:06.854", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 20000, "trace_id": "FNXaarxCYxm5ckVFPiyCKh8d1", "fee": 0, "destination": null, "raw": null, "created_at": "2020-04-29T20:34:06.69Z", "source": "PInJceezonsp9C5Vcta3azs1", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "DEBIT", "tags": {}, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": null, "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:34:06.80Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRqq52oDiPVv3WJNb1B7M1UU", "state": "PENDING", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` #### Transfer updated The event you receive when a `Transfer` gets updated to `SUCCEEDED`. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2020-04-29T20:35:13.819", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 20000, "trace_id": "FNXaarxCYxm5ckVFPiyCKh8d1", "fee": 0, "destination": null, "raw": null, "created_at": "2020-04-29T20:34:06.69Z", "source": "PInJceezonsp9C5Vcta3azs1", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "DEBIT", "tags": {}, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": null, "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:35:13.57Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRqq52oDiPVv3WJNb1B7M1UU", "state": "SUCCEEDED", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` #### Transfer ready to settle The event you receive when the `Transfer` is ready [for approval in a `Settlement`](/guides/platform-payments/seller-payouts). A transfer is ready to settle when `ready_to_settle_at` gets updated with a timestamp. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2020-04-29T20:35:11.986", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 20000, "trace_id": "FNXaarxCYxm5ckVFPiyCKh8d1", "fee": 0, "destination": null, "raw": null, "created_at": "2020-04-29T20:34:06.69Z", "source": "PInJceezonsp9C5Vcta3azs1", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "DEBIT", "tags": {}, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": "2020-04-29T20:35:11.94Z", "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:35:11.93Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRqq52oDiPVv3WJNb1B7M1UU", "state": "SUCCEEDED", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` ### Sale (card present) The events you receive when a `Transfer` gets created for card present transactions. #### Transfer created The event you receive when a `Transfer` gets created to process a card present transaction. ```json { "type": "created", "entity": "transfer", "occurred_at": "2020-04-29T20:32:07.555", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 20000, "trace_id": "FNXrkV69dG3nU4fNmW4Mtwpoo", "fee": 0, "destination": null, "raw": null, "created_at": "2020-04-29T20:32:07.37Z", "source": "PI3WYRq5CjwrMAUV8STDXYJJ", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "DEBIT", "tags": {}, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": null, "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:32:07.50Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRgCH1Mo7dn9m1abgFDjQBzo", "state": "PENDING", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` #### Transfer attempt created The event you receive when a `Transfer Attempt` gets created to process a hosted payment. ```json { "type": "created", "entity": "transfer_attempt", "occurred_at": "2020-04-29T20:31:32.348", "_embedded": { "transfer_attempts": [ { "id": "transfer_attempt_ciACBK59kDhfx2Mi4Vy81", "created_at": "2024-12-27T05:52:07.44Z", "updated_at": "2024-12-27T05:52:07.44Z", "merchant_id": "MUmfEGv5bMpSJ9k5TFRUjkmm", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "amount": 200, "currency": "USD", "state": "SUCCEEDED", "payment_frequency": "ONE_TIME", "transfer_id": "TRodANv8j3CVRUQz4sgZa8sK", "payment_instrument_id": "PI7AS61AmsnJQ5Y7sL7dM1Ux", "entity_id": "payment_link_ciACu5E9CqjqTmPq4k5WT", "entity_type": "PAYMENT_LINK", "buyer_details": { "first_name": "", "last_name": "", "email": "test@gmail.com", "identity_id": "IDew6Bkcj1AwEP2aWhjjfdqS", "phone": null, "billing_address": null, "shipping_address": { "city": null, "country": "USA", "line1": null, "line2": null, "postal_code": null, "region": null } }, "failure_code": null, "failure_message": null, "tags": {}, "recipient_details": null, "operation_key": "SALE", "type": "DEBIT", "recipient_merchant_id": null, "receipt_requested_delivery_methods": [ { "type": "EMAIL", "destinations": ["test@gmail.com"] } ], "additional_buyer_charges": null, "amount_requested": 200 } ] } } ``` #### Transfer attempt updated The event you receive when a `Transfer Attempt` is updated. ```json { "type": "created", "entity": "transfer_attempt", "occurred_at": "2020-04-29T20:31:32.348", "_embedded": { "transfer_attempts": [ { "id": "transfer_attempt_ciACBK59kDhfx2Mi4Vy81", "created_at": "2024-12-27T05:52:07.44Z", "updated_at": "2024-12-27T06:52:07.44Z", "merchant_id": "MUmfEGv5bMpSJ9k5TFRUjkmm", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "amount": 200, "currency": "USD", "state": "SUCCEEDED", "payment_frequency": "ONE_TIME", "transfer_id": "TRodANv8j3CVRUQz4sgZa8sK", "payment_instrument_id": "PI7AS61AmsnJQ5Y7sL7dM1Ux", "entity_id": "payment_link_ciACu5E9CqjqTmPq4k5WT", "entity_type": "PAYMENT_LINK", "buyer_details": { "first_name": "", "last_name": "", "email": "test@gmail.com", "identity_id": "IDew6Bkcj1AwEP2aWhjjfdqS", "phone": null, "billing_address": null, "shipping_address": { "city": null, "country": "USA", "line1": null, "line2": null, "postal_code": null, "region": null } }, "failure_code": null, "failure_message": null, "tags": { "new key": "new value" }, "recipient_details": null, "operation_key": "SALE", "type": "DEBIT", "recipient_merchant_id": null, "receipt_requested_delivery_methods": [ { "type": "EMAIL", "destinations": ["test@gmail.com"] } ], "additional_buyer_charges": null, "amount_requested": 200 } ] } } ``` #### Identity created The event you receive when an `Identity` gets created. The new `Identity` gets used to create the `Payment Instrument` for the non EMV card. ```json { "type": "created", "entity": "identity", "occurred_at": "2020-04-29T20:32:07.637", "_embedded": { "identitys": [ { "application": null, "updated_at": "2020-04-29T20:32:07.37Z", "created_at": "2020-04-29T20:32:07.37Z", "id": "ID6ckSipRZQE6jDRYS78qEeH", "entity": { "title": null, "first_name": null, "last_name": null, "email": null, "business_name": null, "business_type": null, "doing_business_as": null, "phone": null, "business_phone": null, "personal_address": null, "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 }, "identity_roles": [], "tags": {} } ] } } ``` #### Transfer updated The event you receive when a `Transfer` gets updated to `SUCCEEDED`. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2020-04-29T20:32:31.508", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 20000, "trace_id": "FNXrkV69dG3nU4fNmW4Mtwpoo", "fee": 0, "destination": null, "raw": null, "created_at": "2020-04-29T20:32:07.37Z", "source": "PI3WYRq5CjwrMAUV8STDXYJJ", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "DEBIT", "tags": {}, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": null, "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:32:31.32Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRgCH1Mo7dn9m1abgFDjQBzo", "state": "SUCCEEDED", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` #### Transfer ready to settle The event you receive when the `Transfer` is ready for approval in a `Settlement`. A transfer is ready to settle when `ready_to_settle_at` gets updated with a timestamp. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2020-04-29T20:32:29.772", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 20000, "trace_id": "FNXrkV69dG3nU4fNmW4Mtwpoo", "fee": 0, "destination": null, "raw": null, "created_at": "2020-04-29T20:32:07.37Z", "source": "PI3WYRq5CjwrMAUV8STDXYJJ", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDgk8BqH6Kp176UF7KsQecio", "type": "DEBIT", "tags": {}, "statement_descriptor": "FIN*FINIX", "ready_to_settle_at": "2020-04-29T20:32:29.67Z", "application": "APiDZzAY28F2uSz47L88EuPk", "updated_at": "2020-04-29T20:32:29.66Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRgCH1Mo7dn9m1abgFDjQBzo", "state": "SUCCEEDED", "device": "DV4b5w1TNAkBu9RTgXU7C19b" } ] } } ``` ### Settlement accruing The event you receive when a [`Settlement` begins accruing transactions](/guides/platform-payments/seller-payouts/accruing-settlements). This is the first webhook that is received for a `Settlement`. ```json { "type": "accruing_started", "entity": "settlement", "occurred_at": "2018-03-06T20:41:34.277", "_embedded": { "settlements": [ { "id": "STc4qcqYJn4tKaD6bkHzkzMG", "application": "APcL6gyMzeFqDf6RHJid3SEq", "tags": {}, "identity": "ID57iuPnKwuopPn93YsGmvkP", "currency": "USD", "merchant_id": "MUgRjRrRwDyMbzS6CVQYPECC", "created_at": "2022-08-18T19:00:00.93Z", "updated_at": "2022-08-18T19:00:00.93Z", "processor": "DUMMY_V1", "type": "MERCHANT_REVENUE", "funds_flow": null, "payment_type": null, "total_amount": 662154, "total_fees": 19232, "total_fee": 19232, "net_amount": 642922, "destination": null, "status": "PENDING" } ] } } ``` ### Settlement approved The event sent when a `Settlement` is approved. ```json { "type": "updated", "entity": "settlement", "occurred_at": "2022-05-05T22:19:42.101668", "_embedded": { "settlements": [ { "total_fees": 54321, "destination": null, "created_at": "2022-05-05T16:51:24.75Z", "merchant_id": "MUvrfZpyZtaaFWJjBt2kSd5t", "type": "MERCHANT_REVENUE", "processor": "DUMMY_V1", "tags": {}, "payment_type": null, "application": "AP67hTPMFqeM9mvCkRN81c4f", "updated_at": "2022-05-05T22:19:39.51Z", "total_amount": 0, "identity": "IDigyAkvecqA4KBKkvUbK9gP", "total_fee": 54321, "currency": "USD", "id": "STjWJZEp51zLebP78s974o1w", "net_amount": -54321, "funds_flow": "NET", "status": "APPROVED" } ] } } ``` ### Settlement created The event you receive when a [`Settlement` closes and awaiting Finix approval.](/guides/platform-payments/seller-payouts). This is the second webhook that is received for a `Settlement`. ```json { "type": "created", "entity": "settlement", "occurred_at": "2022-08-18T16:45:30.253835", "_embedded": { "settlements": [ { "total_fees": 1388, "destination": null, "created_at": "2022-08-18T16:30:06.07Z", "merchant_id": "MUeDVrf2ahuKc9Eg5TeZugvs", "type": "MERCHANT_REVENUE", "processor": "DUMMY_V1", "tags": {}, "payment_type": null, "application": "APgPDQrLD52TYvqazjHJJchM", "updated_at": "2022-08-18T16:45:27.03Z", "total_amount": 49380, "identity": "IDuqZpDw28f2KK6YuDk4jNLg", "total_fee": 1388, "currency": "USD", "id": "STzcJD5WSsMojBzsuH65N8j", "net_amount": 47992, "funds_flow": "NET", "status": "AWAITING_APPROVAL" } ] } } ``` ### Settlement funding Transfer created The event you receive when the funding [`transfer` of a `Settlement` gets created](/guides/platform-payments/seller-payouts) for a `Merchant`. ```json { "id": "event_8hv9UJRJG4LweMMoDgys5a", "type": "created", "entity": "transfer", "occurred_at": "2022-12-13T19:12:53.829814", "_embedded": { "transfers": [ { "fee": 0, "destination": "PIshDA1jsiEJH5RStcctoqGR", "created_at": "2022-12-13T19:12:52.49Z", "failure_message": null, "fee_type": "CARD_FIXED", "source": null, "type": "CREDIT", "additional_buyer_charges": null, "statement_descriptor": null, "additional_healthcare_data": null, "updated_at": "2022-12-13T19:12:52.58Z", "subtype": "SETTLEMENT_MERCHANT", "amount_requested": 194408, "currency": "USD", "id": "TRund4D4dYB3EoMFjHADw1X4", "state": "PENDING", "idempotency_id": null, "amount": 194408, "failure_code": null, "trace_id": "770788e0-84eb-4350-81a8-34d5d4fa4201", "address_verification": null, "security_code_verification": null, "raw": null, "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDtLE8194YeihTtmtTSzucoP", "tags": {}, "ready_to_settle_at": null, "application": "AP7Geeyfse2KNHiZU6BYZqo5", "externally_funded": "UNKNOWN", "messages": [] } ] } } ``` ### Settlement updated and awaiting approval The event you receive after Finix approves a `Settlement` and it becomes available for approval. ```json { "id": "event_9op0ILKJG4LweMMoDers4l", "type": "updated", "entity": "settlement", "occurred_at": "2023-02-16T22:19:57.64Z", "_embedded": { "transfers": [ { "id": "ST2sg1vzfNdeNBr8a4iqVxDt", "created_at": "2023-02-16T22:19:57.64Z", "updated_at": "2023-02-16T22:37:05.11Z", "adjustment_credit_amount": 0, "adjustment_credit_count": 0, "adjustment_debit_amount": 0, "adjustment_debit_count": 0, "application": "APxxJrYiqedWNXKsbKz939r8", "auto_close_time": "2023-02-17T13:00:00.00Z", "currency": "USD", "dispute_credit_amount": 0, "dispute_credit_count": 0, "dispute_debit_amount": 0, "dispute_debit_count": 0, "exception": false, "externally_funded_amount": 0, "externally_funded_count": 0, "fee_count": 12, "finix_fee_count": 0, "merchant": "MUnawwFb6vCdrnteVtPDdwmK", "payout_plan": "POa1KmjxP1RXXg3nWdhoPSfG", "processor_type": "DUMMY_V1", "reverse_amount": 0, "reverse_count": 0, "schedule_type": "DAILY", "settlement_group": "SG2senctJE9aMysfYz7AUheu", "split_count": 0, "status": "AWAITING_APPROVAL", "tags": {}, "total_amount": 39450, "total_fee_amount": 1857, "total_finix_fee_amount": 0, "total_split_amount": 0, "transfer_credit_amount": 0, "transfer_credit_count": 0, "transfer_debit_amount": 39450, "transfer_debit_count": 6, "window_end": "2023-02-16T22:37:00.00Z", "window_start": "2023-02-16T05:00:00.00Z" } ] } } ``` ### Transfer cancelled The event you receive when a `Transfer` gets cancelled. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2022-08-09T22:30:09.692475", "_embedded": { "transfers": [ { "idempotency_id": "4c39e773d04d60eb24ea767258cec28b", "amount": 3238, "trace_id": "FNX4hvw94KQPfipvLZVUUSx8y", "failure_code": null, "fee": 0, "destination": null, "raw": null, "created_at": "2022-08-07T16:20:29.40Z", "source": "PI8EV9PDtnTomU1SbhtXfss1", "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDndzozsxaoZFPLgCAhTgpaN", "failure_message": null, "type": "DEBIT", "tags": {}, "statement_descriptor": "FI *BEYOND", "additional_buyer_charges": null, "ready_to_settle_at": null, "application": "APwug8rgLYVRAvDvBeuF3oFU", "updated_at": "2022-08-09T22:30:08.48Z", "subtype": "API", "externally_funded": "UNKNOWN", "messages": [], "currency": "USD", "id": "TRsXVRii1UWCGYG1XKXbpEVw", "state": "CANCELED" } ] } } ``` ### Transfer created (bank account debit) The events you receive using ACH (also called eCheck) to debit a bank account. #### Transfer created The event you receive when a [`transfer` gets created to debit a bank account](/guides/online-payments/bank-payments/ach-direct-debits). ```json { "type": "created", "entity": "transfer", "occurred_at": "2020-04-26T23:41:55.297", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 95073, "trace_id": "c2bf4ba1-ef59-4c1d-9313-8a46c096cf95", "fee": 9507, "destination": null, "raw": null, "created_at": "2020-04-26T23:41:55.13Z", "source": "PI4CxWXFQBPjTiU1F1oUcRqz", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDdpvBpQ9m6D3JDCRq9UDB2E", "type": "DEBIT", "tags": { "order_number": "21DFASJSAKAS" }, "statement_descriptor": "FIN*FINIX FLOWERS", "ready_to_settle_at": null, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T23:41:55.23Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRhb7bDRw4TQwUrGj7zCetVG", "state": "PENDING" } ] } } ``` #### Transfer succeeded The event you receive when a `Transfer` gets updated to `SUCCEEDED`. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2020-04-26T23:42:18.582", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 95073, "trace_id": "c2bf4ba1-ef59-4c1d-9313-8a46c096cf95", "fee": 9507, "destination": null, "raw": null, "created_at": "2020-04-26T23:41:55.13Z", "source": "PI4CxWXFQBPjTiU1F1oUcRqz", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDdpvBpQ9m6D3JDCRq9UDB2E", "type": "DEBIT", "tags": { "order_number": "21DFASJSAKAS" }, "statement_descriptor": "FIN*FINIX FLOWERS", "ready_to_settle_at": null, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T23:42:18.53Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRhb7bDRw4TQwUrGj7zCetVG", "state": "SUCCEEDED" } ] } } ``` ### Transfer updated (succeeded) The events that get sent when a `Transfer` gets updated to `SUCCEEDED`. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2020-04-26T23:51:06.063", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 100, "trace_id": "df499916-5cda-45f0-b1d9-3d59460cd867", "fee": 0, "destination": "PI5JEJTNwLzZ8rMMFV9QkaHz", "raw": null, "created_at": "2020-04-26T23:47:33.17Z", "source": null, "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDdpvBpQ9m6D3JDCRq9UDB2E", "type": "REVERSAL", "tags": {}, "statement_descriptor": "FIN*FINIX FLOWERS", "ready_to_settle_at": null, "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T23:48:12.40Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRxiRsBXhWp7ZdVwkRiEEjFm", "state": "SUCCEEDED" } ] } } ``` ### Transfer updated (ready to settle) The event you receive when the `Transfer` is ready [for approval in a `Settlement`](/guides/platform-payments/seller-payouts). A transfer is ready to settle when `ready_to_settle_at` gets updated with a timestamp. ```json { "type": "updated", "entity": "transfer", "occurred_at": "2020-04-26T23:51:27.34", "_embedded": { "transfers": [ { "idempotency_id": null, "amount": 95073, "trace_id": "c2bf4ba1-ef59-4c1d-9313-8a46c096cf95", "fee": 9507, "destination": null, "raw": null, "created_at": "2020-04-26T23:41:55.13Z", "source": "PI4CxWXFQBPjTiU1F1oUcRqz", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDdpvBpQ9m6D3JDCRq9UDB2E", "type": "DEBIT", "tags": { "order_number": "121212123" }, "statement_descriptor": "FIN*FINIX FLOWERS", "ready_to_settle_at": "2020-04-27T04:00:00.00Z", "application": "APkBUdiWzBjUAkfnbkirXs6d", "updated_at": "2020-04-26T23:51:27.27Z", "subtype": "API", "messages": [], "currency": "USD", "id": "TRhb7bDRw4TQwUrGj7zCetVG", "state": "SUCCEEDED" } ] } } ``` ### Funding Transfer attempt created The event you receive when a `Funding Transfer Attempt` gets created. Funding Transfer Attempts are used for settlement instant payouts. ```json { "id": "event_tWshA2ni3ypPgsEfA38UQb", "system_generated_idempotency_id": "tWshA2ni3ypPgsEfA38UQb", "type": "updated", "entity": "funding_transfer_attempt", "occurred_at": "2025-01-27T22:08:58.270890776", "_embedded": { "funding_transfer_attempts": [ { "amount": 1000, "failure_code": null, "settlement_id": "ST21qGT94EoDyyDuuivppQ5Z", "created_at": "2025-01-27T22:07:39.33Z", "failure_message": null, "merchant_id": "MUtyBMRg9V6SH5m1SSNrvdaU", "application_id": "APeiHHWMaRgg3zcUTUVj6xuk", "instrument_id": "PIvbR383jYuAv9BU3NTZFBB5", "updated_at": "2025-01-27T22:07:41.11Z", "funding_transfer_id": null, "currency": "USD", "id": "funding_transfer_attempt_p13eJSrJsmpfB2H7c33W3y", "state": "PENDING" } ] } } ``` ### Funding Transfer attempt updated The event you receive when a `Funding Transfer Attempt` gets created. Funding Transfer Attempts are used for settlement instant payouts. You can track changes to `state` and `funding_transfer_id` using this webhook. ```json { "id": "event_bMFrW4JsdKhgub4QyQ2q4W", "system_generated_idempotency_id": "bMFrW4JsdKhgub4QyQ2q4W", "type": "updated", "entity": "funding_transfer_attempt", "occurred_at": "2025-01-27T22:10:37.45411079", "_embedded": { "funding_transfer_attempts": [ { "amount": 1000, "failure_code": null, "settlement_id": "STaQiUn9EraADgE6APjD2vwf", "created_at": "2025-01-27T22:09:48.69Z", "failure_message": null, "merchant_id": "MUtyBMRg9V6SH5m1SSNrvdaU", "application_id": "APeiHHWMaRgg3zcUTUVj6xuk", "instrument_id": "PIhm2APRxomyiQ16jnDTGQnm", "updated_at": "2025-01-27T22:09:50.71Z", "funding_transfer_id": "TRerSoEHQLPdU41s8YwAbh2n", "currency": "USD", "id": "funding_transfer_attempt_2fqSr4tc74MBBh1a1bYQVF", "state": "SUCCEEDED" } ] } } ``` ### 3D Secure Session created The event you receive when a 3D Secure Session is created. The `state` is `PENDING` and authentication has not yet run. ```json { "id": "event_mK2NR11jPqwWUoNXAUnkyf", "system_generated_idempotency_id": "mK2NR11jPqwWUoNXAUnkyf", "type": "created", "entity": "three_d_secure_session", "occurred_at": "2026-10-03T17:55:03.609628Z", "_embedded": { "three_d_secure_sessions": [ { "id": "3d_secure_session_qqfEsTQDPhjb3htdDyabLB", "created_at": "2026-10-03T17:55:01.592199Z", "updated_at": "2026-10-03T17:55:01.592201Z", "3d_secure_authentication": null, "3d_secure_authentication_session_id": null, "3d_secure_authentication_url": null, "3d_secure_version": null, "amount": 1000, "authentication_type": null, "currency": "USD", "failure_code": null, "failure_message": null, "merchant_id": "MUxxxxxxxxxxxxxxxxxxxxxxxxx", "payment_instrument_id": null, "redirect_url": "https://finix.com", "state": "PENDING", "tags": {} } ] } } ``` ### 3D Secure Session updated The event you receive when a 3D Secure Session is updated. When `state` is `SUCCEEDED`, read `electronic_commerce_indicator` to determine the authentication outcome and liability. For more information, see [3D Secure liability shift](/guides/online-payments/fraud-and-risk/3d-secure/3ds-liability-shift). ```json { "id": "event_pA6CRrhEMouVzk7tRCThMa", "system_generated_idempotency_id": "pA6CRrhEMouVzk7tRCThMa", "type": "updated", "entity": "three_d_secure_session", "occurred_at": "2026-10-03T17:55:38.423911Z", "_embedded": { "three_d_secure_sessions": [ { "id": "3d_secure_session_qqfEsTQDPhjb3htdDyabLB", "created_at": "2026-10-03T17:55:01.592199Z", "updated_at": "2026-10-03T17:55:36.993541Z", "3d_secure_authentication": { "cardholder_authentication": "KAUocMh1fJWYtQUQ50tfdJ0TOiw=", "electronic_commerce_indicator": "AUTHENTICATED", "transaction_id": "b146df97-b54a-478c-816f-4762b96b34cb" }, "3d_secure_authentication_session_id": "tds_mastercard_8415025c557b", "3d_secure_authentication_url": null, "3d_secure_version": "2.2.0", "amount": 1000, "authentication_type": "FRICTIONLESS", "currency": "USD", "failure_code": null, "failure_message": null, "merchant_id": "MUxxxxxxxxxxxxxxxxxxxxxxxxx", "payment_instrument_id": null, "redirect_url": "https://finix.com", "state": "SUCCEEDED", "tags": {} } ] } } ``` --- # Webhook Logs Source: https://docs.finix.com/additional-resources/developers/webhooks/webhook-logs Finix's Webhook Logs allow you to view the webhooks sent by Finix in the past 30 days. In the Finix Dashboard, visit **Developer > Webhook Logs** to view all webhook events Finix has sent you in the past 30 days. For example, you might use this page to find specific webhooks or debug your integration. You can filter the webhooks by: - Attempt ID - Event entity - Event ID - Event type - Status - Webhook ID Webhook Logs List When you view a specific webhook log, you will be able see the webhook event's body. Webhook Logs List --- # Adobe Commerce Source: https://docs.finix.com/additional-resources/plugins/adobe-commerce-integration Accept payments with Finix on [Adobe Commerce](https://business.adobe.com/products/magento/magento-commerce.html) (formerly Magento). Adobe Commerce ## Adobe Commerce overview Adobe Commerce (formerly Magento) is an enterprise-grade eCommerce platform used by mid-market and Fortune 1000 retailers. It supports both cloud-hosted (Adobe Commerce Cloud) and self-hosted (Magento Open Source) deployments, with a flexible extension marketplace and headless storefront capabilities. Finix integrates with Adobe Commerce through the Cybersource payment gateway, enabling merchants to accept card payments directly within their storefront checkout. ### Finix requirements - Finix Live Account - Active Adobe Commerce store (Adobe Commerce Cloud or Magento Open Source) ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports Adobe Commerce via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure Adobe Commerce: - **Merchant ID** (also called Organization ID) - **REST API Keys** (required for Microform checkout) - **SOAP Keys** (required for all other integrations) Cybersource Key Management ### Step 3: Set up your Adobe Commerce store Before proceeding, ensure your Adobe Commerce environment is ready: - A working instance of Adobe Commerce or Magento. Learn more with Adobe's [Getting Started Guide](https://experienceleague.adobe.com/en/docs/commerce-admin/start/guide-overview). - Set up your Adobe Commerce Marketplace account and generate [Access Keys](https://experienceleague.adobe.com/en/docs/commerce-admin/start/resources/commerce-marketplace#create-an-access-key). ### Step 4: Install the Cybersource extension Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Adobe Commerce Account & Adobe Commerce Marketplace Access Keys To install the extension: 1. Navigate to the [Cybersource Payment Management Platform](https://commercemarketplace.adobe.com/cybersource-global-payment-management.html) on the Adobe Commerce Marketplace. 2. Select your Adobe Commerce edition and version (2.4), then complete checkout to add it to your account. 3. In your Magento root directory, rename `auth.json.sample` to `auth.json` and populate it with your Marketplace Public and Private Keys: ```json { "http-basic": { "repo.magento.com": { "username": "Your_Public_Key", "password": "Your_Private_Key" } } } ``` 1. Run the following Composer commands to install the extension and its dependencies: ```bash composer require cybersource/global-payment-management composer require cybersource/module-recaptcha ``` 1. Enable all Cybersource modules: ```bash php bin/magento module:enable CyberSource_AccountUpdater CyberSource_Core CyberSource_ApplePay CyberSource_Atp CyberSource_BankTransfer CyberSource_SecureAcceptance CyberSource_ECheck CyberSource_GooglePay CyberSource_KlarnaFinancial CyberSource_VisaCheckout CyberSource_Address CyberSource_Tax CyberSource_ThreeDSecure CyberSource_PayPal CyberSource_WeChatPay CyberSource_Recaptcha ``` 1. Run the post-installation commands to compile, reindex, and clear caches: ```bash php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento setup:static-content:deploy -f php bin/magento indexer:reindex php bin/magento cache:clean php bin/magento cache:flush ``` For full installation details, refer to the [Cybersource Adobe Commerce developer documentation](https://developer.cybersource.com/technology-partners/adobe-commerce.html). ### Step 5: Configure Adobe Commerce In your Adobe Commerce admin, navigate to **Stores → Configuration → Sales → Payment Methods** and locate the **Cybersource** section. 1. Under Webservice Configurations, enter: - Merchant ID — your Cybersource Organization ID - Set Test Mode to Yes for sandbox or No for production 2. Enter your REST API or SOAP credentials. 3. Under Credit Card Settings: - Set Enable to Yes - Set Payment API to SOAP Toolkit - Set Checkout Flow to Flex Microform 4. Enable the card brands and payment methods you want to offer. After configuring your payment methods, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Adobe Commerce transactions When you run a transaction on Adobe Commerce, you can locate it: - In your Adobe Commerce admin under **Sales** → **Orders**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Partners Source: https://docs.finix.com/additional-resources/plugins/become-a-partner Learn more about Finix's Partner Program. ## Overview The Finix Partner Program enables platforms and solution providers to embed payments directly into their existing products and services. Through our integrations and plugin partnerships, Finix helps customers simplify payment acceptance without rebuilding their workflows. Partners can leverage our APIs, onboarding tools, and payments infrastructure to offer their customers a fully integrated payments experience. See our current [plugin partners](/additional-resources/plugins) to learn more about their platforms and how to integrate onto them. This page outlines how to become a Finix partner and begin the integration process. You’ll learn how to connect with our Partner team, explore available integration options, and understand how Finix works alongside your platform to deliver compliant and feature-rich payment solutions that grow with your platform. Whether you’re looking to enhance your existing platform with payments or expand your service offerings, Finix provides the tools and support to help you grow. ## Become a Finix partner Join the Finix Partner Program by filling out our [Partner Application](https://finix.com/partner-submission). Finix's partnership team will review the application and get in touch with you about Finix's partner offerings. Finix's partner program is designed to meet your needs and scale with you. Our representatives will share the resources and guidance required to move forward. ## Resources If you have a referral or a quick question, contact your partner manager or send us an email at [partnerships@finix.com](mailto:partnerships@finix.com). --- # BigCommerce Source: https://docs.finix.com/additional-resources/plugins/bigcommerce-integration Accept payments with Finix on [BigCommerce](https://www.bigcommerce.com). BigCommerce ## BigCommerce overview BigCommerce is a leading open SaaS eCommerce platform trusted by more than 130,000 mid-market and enterprise merchants worldwide. It offers a flexible, headless architecture with built-in tools for storefront management, multi-channel selling, inventory, and promotions — without requiring a full platform replatform. Finix integrates with BigCommerce through the Cybersource payment gateway, enabling merchants to accept payments directly within their BigCommerce checkout. ### Finix requirements - Finix Live Account - Active BigCommerce account ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports BigCommerce via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, your Cybersource account will be provisioned and ready to connect. BigCommerce connects to Cybersource via OAuth — no manual API key entry is required. ### Step 3: Set up your BigCommerce environment Before proceeding, ensure your BigCommerce environment is ready: - Active BigCommerce [merchant account](https://developer.cybersource.com/technology-partners/BigCommerce.html) with admin access - Store configured to use **Optimized One Page Checkout** - Services enabled on your Cybersource gateway account before configuration - Payer Authentication fully configured if using 3D Secure transactions ### Step 4: Install and connect the Cybersource app Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - BigCommerce store with Optimized One Page Checkout enabled Install the Cybersource app from the [BigCommerce App Marketplace](https://www.bigcommerce.com/apps/). Cybersource publishes and maintains this integration. For full installation details, refer to the [Cybersource BigCommerce developer documentation](https://developer.cybersource.com/technology-partners/BigCommerce.html). #### Enable Extension 1. Navigate to **Store Setup → Payments** in your BigCommerce admin. 2. Select **Cybersource** from the list of online payment methods. 3. Choose your environment — **Test** for sandbox or **Live** for production. 4. Click **Connect to Cybersource Business Center**. 5. Log in to your Business Center account and approve the requested OAuth connection scopes. 6. You'll be redirected back to BigCommerce upon successful connection. BigCommerce Cybersource Connect ### Step 5: Configure the Cybersource extension Once connected, configure the following settings based on your business needs and click **Save**: - **Display Name** - controls how the payment gateway appears at checkout - **Transaction Type** - select **Authorize & Capture** or **Authorize Only** - **Test Mode** - set to **No** when ready for live payments - **Require CVV** - toggle to require card security code at checkout - **Enable 3D Secure** - enable for SCA-compliant transactions - **Enable Google Pay** - enable to accept Google Pay at checkout BigCommerce Cybersource Settings After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## BigCommerce transactions When you run a transaction on BigCommerce, you'll see it: - In your BigCommerce admin under **Orders → View**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # CheckoutChamp Source: https://docs.finix.com/additional-resources/plugins/checkoutchamp-plugin Accept payments with Finix on [CheckoutChamp](https://checkoutchamp.com). Finix for CheckoutChamp ## Finix for CheckoutChamp overview CheckoutChamp is a comprehensive CRM and payment orchestration platform that enables merchants to manage transactions, customer data, and subscription billing through a single, intuitive interface. It allows businesses to create optimized checkout experiences while integrating seamlessly with payment processors and gateways. Connecting Finix to CheckoutChamp enables merchants to manage their entire payment workflow directly within the CheckoutChamp platform, pairing CheckoutChamp’s streamlined checkout and CRM capabilities with Finix’s payments infrastructure. ### Finix requirements - Finix Sandbox Account to process Sandbox transactions. You will not be able to move real money in this environment. - Finix Live Account to run card or ACH transactions. ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create API keys API Environments API Keys are specific to either the Sandbox or Live environments, depending on whether you get them from the Sandbox or Live Dashboard. Sandbox Keys cannot be used in the Live Environment and vice-versa. [Learn more here](/api/section/environments). To create an API Key: 1. Navigate to **Developers → API Keys** in the Finix dashboard. 2. Click **Create API Key** and enter a **Display Name**. 3. Save the credentials somewhere secure. Store API Keys Securely Save your password somewhere secure. You **cannot** re-copy the password, but you can always create another API Key. API Keys are sensitive data and must be treated like passwords. Store them securely and only share them on an as-needed basis. To learn more see our [API Keys](/additional-resources/developers/authentication-and-api-basics/api-keys) documentation. ### Step 3: Connect with CheckoutChamp In your CheckoutChamp CRM, navigate to Gateways → Gateway Integrations. Locate the Finix tile and click +Activate to create the gateway profile. Activate Finix ### Step 4: Configure Finix credentials in CheckoutChamp Enter your Finix credentials in the corresponding fields within the CheckoutChamp gateway profile. You can locate these details in your Finix Dashboard: - Merchant Account ID: Developer → Finix Integration → Merchant ID - Merchant Identity ID: Developer → Finix Integration → Merchant Identity ID Dashboard IDs - Username: The username associated with your Finix API Key created in Step 2 - Password: The password associated with your Finix API Key created in Step 2 CheckoutChamp Gateway Profile These credentials allow CheckoutChamp to securely connect to your Finix account for payment processing. ## Searching for transactions on the Finix Dashboard You can find Payments using CheckoutChamp Order IDs on the Finix Dashboard. Filter Transaction 1. Navigate to the Payments list page. 2. Click on the Filters. 3. Under **Tags**, enter the CheckoutChamp Order ID. 4. Click **Apply**. --- # commercetools Source: https://docs.finix.com/additional-resources/plugins/commercetools-integration Accept payments with Finix on [commercetools](https://commercetools.com). commercetools ## Commercetools overview commercetools is a headless, cloud-native commerce platform built on MACH principles (Microservices, API-first, Cloud-native, Headless). It enables global enterprises to build composable commerce experiences by providing modular services for product catalogs, cart and checkout, order management, and customer data — all exposed via APIs. Finix integrates with commercetools through the Cybersource payment gateway, enabling merchants to process payments and reconcile transaction data within their commercetools storefront. ### Finix requirements - Finix Live Account - Active commercetools account ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports commercetools via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure commercetools: - **Merchant ID** (also called Organization ID) - **REST API Key** Cybersource Key Management ### Step 3: Set up your commercetools environment Before proceeding, ensure your commercetools environment is ready: - Active commercetools [Merchant Center account](https://identity.commercetools.com/login?returnTo=https%3A%2F%2Fmc-api.europe-west1.gcp.commercetools.com%2Fcallbacks%2Flogin%3FreturnTo%3Dhttps%253A%252F%252Fmc.europe-west1.gcp.commercetools.com%252Flogin%252Fchoose) with a configured project - API Client with **Manage** and **View** scopes for: Customers, Extensions, Orders, Payments, and Types - Node.js v16.3.0 or later - 256MB minimum memory allocation for the plugin service ### Step 4: Install and configure the Cybersource plugin Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - commercetools project with API Client configured Install the `cybersource-plugins-commercetools` package from the Cybersource GitHub repository. For full installation details, refer to the [Cybersource commercetools developer documentation](https://developer.cybersource.com/technology-partners/commercetools.html). Once installed, populate the following environment variables in your `.env` file: **Cybersource credentials:** - `PAYMENT_GATEWAY_MERCHANT_ID` - your Cybersource Merchant ID from Step 2 - `PAYMENT_GATEWAY_MERCHANT_KEY_ID` - your REST API Key ID from Step 2 - `PAYMENT_GATEWAY_MERCHANT_SECRET_KEY` - your REST API Shared Secret from Step 2 - `PAYMENT_GATEWAY_RUN_ENVIRONMENT` - set to `TEST` for sandbox or `PRODUCTION` for live - `PAYMENT_GATEWAY_TARGET_ORIGIN` - your frontend base URL **commercetools credentials:** - `CT_PROJECT_KEY`, `CT_CLIENT_ID`, `CT_CLIENT_SECRET` — from your commercetools API Client - `CT_AUTH_HOST`, `CT_API_HOST` — your commercetools server URLs **Optional feature flags:** - `PAYMENT_GATEWAY_DECISION_MANAGER` - enable Cybersource Decision Manager for fraud prevention - `PAYMENT_GATEWAY_SCA_CHALLENGE` - enforce 3D Secure for SCA-compliant transactions - `PAYMENT_GATEWAY_3DS_RETURN_URL` - redirect URL for 3D Secure authentication flow - `PAYMENT_GATEWAY_ENABLE_RATE_LIMITER` - restrict saved card usage ### Step 5: Deploy and activate the plugin Once your environment variables are configured, start the plugin service: ```bash npm run start ``` Then call the `/configurePlugin` endpoint to register the API extensions within your commercetools project. This establishes the payment extension hooks that route transactions through Cybersource. After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Commercetools transactions When you run a transaction on commercetools, you'll see it: - In your commercetools Merchant Center under **Orders**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Cvent Source: https://docs.finix.com/additional-resources/plugins/cvent-integration Accept payments with Finix on [Cvent](https://www.cvent.com). Cvent ## Cvent overview Cvent is a leading enterprise event management platform to plan, manage, and execute in-person, virtual, and hybrid events. It provides end-to-end tools for event registration, attendee management, venue sourcing, and payment collection — all within a single platform. Finix integrates with Cvent through the Cybersource payment gateway, enabling merchants to collect event payments and reconcile transaction data within their Cvent environment. ### Finix requirements - Finix Live Account - Active Cvent account ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports Cvent via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure Cvent: - **Merchant ID** (also called Organization ID) - **REST API Key** Cybersource Key Management ### Step 3: Set up your Cvent environment Before proceeding, ensure your Cvent environment is ready: - Active Cvent account with administrator access - Payment collection enabled on your Cvent account - Events configured and ready to accept payments ### Step 4: Configure Cybersource in Cvent Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Cybersource credentials from Step 2 #### Generate and Deploy the Security Key In the Cybersource Business Center: 1. Select **Transaction Processing**, then click **Next Step**. 2. Select **Simple Order**, then click **Submit**. The security key file will automatically download — the filename will include your Merchant ID. To verify your Merchant ID is correct, log in to your Cvent account and go to **Admin → Integrations → Merchant Accounts**. 1. Open the downloaded file in a web browser to deploy the key on your system. 2. Open a support case with Cvent and send them the file. This step is required to finalize the connection between Cvent and Cybersource. For full details, refer to the [Cvent CyberSource setup guide](https://support.cvent.com/s/communityarticle/Setting-Up-CyberSource). After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Cvent transactions When you run a transaction on Cvent, you'll see it: - In your Cvent admin under **Reports → Financial Transactions**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # DocuSign Source: https://docs.finix.com/additional-resources/plugins/docusign-integration Accept payments with Finix on [DocuSign](https://www.docusign.com). DocuSign ## DocuSign overview DocuSign is the global leader in electronic signature and agreement management. Its Agreement Cloud platform enables organizations to prepare, sign, act on, and manage agreements digitally — spanning contracts, approvals, and payment collection. Finix integrates with DocuSign through the Cybersource payment gateway, enabling merchants to collect payments directly within DocuSign envelopes and reconcile transaction data without leaving their agreement workflow. ### Finix requirements - Finix Live Account - Active DocuSign account with DocuSign Payments enabled ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports DocuSign via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure DocuSign: - **Merchant ID** (also called Organization ID) - **[Simple Order API Key](https://developer.cybersource.com/docs/cybs/en-us/security-keys/user/all/ada/security-keys/keys-manage/keys-simple-order-intro.html)** Cybersource Key Management ### Step 3: Configure the Cybersource payment gateway in DocuSign Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Cybersource credentials from Step 2 In your DocuSign admin: 1. Navigate to **Settings → Payments → Payment Gateways**. 2. Click **Add Payment Gateway** and select **Cybersource**. 3. Enter the following credentials: - **Account Name** - a name for the gateway - **Merchant ID** - your Cybersource account ID - **Transaction Security Key File** - the [Simple Order API](https://developer.cybersource.com/docs/cybs/en-us/security-keys/user/all/ada/security-keys/keys-manage/keys-simple-order-intro.html) `.p12` file you created and downloaded from the Business Center - **Effective Password** - the password you created when generating the security key DocuSign Cybersource Gateway Configuration 1. Save the configuration. 2. Attach the Cybersource gateway to the envelopes where payment collection is required. For full details, refer to the [DocuSign CyberSource payment gateway guide](https://support.docusign.com/s/document-item?language=en_US&bundleId=juu1573854950452&topicId=wrz1744672733405.html). After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## DocuSign transactions When you run a transaction on DocuSign, you'll see it: - In your DocuSign admin under **Reports → Payments**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Drupal Commerce Source: https://docs.finix.com/additional-resources/plugins/drupal-commerce-integration Accept payments with Finix on [Drupal Commerce](https://drupalcommerce.org). Drupal Commerce ## Drupal Commerce overview Drupal Commerce is a flexible, open-source eCommerce framework built on Drupal, trusted by thousands of developers to power content-rich commerce sites. It provides a highly customizable architecture for managing products, orders, payments, and promotions — making it a popular choice for organizations that need tight integration between their content management and commerce layers. Finix integrates with Drupal Commerce through the Cybersource payment gateway, enabling merchants to accept payments directly within their Drupal Commerce storefront and reconcile transaction data within their Finix Dashboard. ### Finix requirements - Finix Live Account - Active Drupal Commerce site (Drupal 10.3 or later) ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports Drupal Commerce via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure Drupal Commerce: - **Merchant ID** (also called Organization ID) - **REST API Key** Cybersource Key Management ### Step 3: Install the Cybersource module Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Cybersource credentials from Step 2 - Drupal Commerce site running Drupal 10.3 or later - Composer installed For full installation details, refer to the [commerce_cybersource module page](https://www.drupal.org/project/commerce_cybersource). Run the following command to install the module: ```bash composer require 'drupal/commerce_cybersource:^1.8' ``` Then enable the module in your Drupal admin under **Extend**. ### Step 4: Configure the Cybersource payment gateway The `commerce_cybersource` module supports two integration methods: **Secure Acceptance Hosted Checkout (SAHC)** — an off-site redirect to CyberSource's hosted payment page, and **Flex Microform v2** — an on-site iframe that keeps customers on your storefront. Choose the method that best fits your PCI requirements. In your Drupal admin: 1. Navigate to **Commerce → Configuration → Payment gateways**. 2. Click **Add payment gateway** and select **Cybersource**. 3. Enter the following credentials from Step 2: - **Merchant ID** - your Cybersource Organization ID - **REST API Key ID** - your REST Key ID - **REST API Shared Secret** - your REST Shared Secret 4. Select your **Integration method** (SAHC or Flex Microform v2). 5. Set the **Mode** to **Test** for sandbox or **Live** for production. 6. Save the configuration and clear the Drupal cache. After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Drupal Commerce transactions When you run a transaction on Drupal Commerce, you'll see it: - In your Drupal admin under **Commerce → Orders**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Fyntek Source: https://docs.finix.com/additional-resources/plugins/fyntek-plugin Accept payments with Finix on [Fyntek](https://fyntek.ai/). Finix for Fyntek ## Finix for fyntek overview Fyntek is a payment orchestration platform that gives businesses a single access point to manage payment providers, configure payment flows, and process payouts across multiple channels. It enables merchants to offer a wide range of payment options including cards, digital wallets, and regional methods like ACH without complex integrations. Connecting Finix to Fyntek allows merchants to process payments using Finix's payments infrastructure directly within the Fyntek platform, pairing Fyntek's orchestration capabilities with Finix's payment processing. ### Finix requirements - Finix Sandbox Account to process Sandbox transactions. You will not be able to move real money in this environment. - Finix Live Account to run card or ACH transactions. ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create API keys API Environments API Keys are specific to either the Sandbox or Live environments, depending on whether you get them from the Sandbox or Live Dashboard. Sandbox Keys cannot be used in the Live Environment and vice-versa. [Learn more here](/api/section/environments). To create an API Key: 1. Navigate to **Developers → API Keys** in the Finix dashboard. 2. Click **Create API Key** and enter a **Display Name**. 3. Save the credentials somewhere secure. Store API Keys Securely Save your password somewhere secure. You **cannot** re-copy the password, but you can always create another API Key. API Keys are sensitive data and must be treated like passwords. Store them securely and only share them on an as-needed basis. To learn more see our [API Keys](/additional-resources/developers/authentication-and-api-basics/api-keys) documentation. ### Step 3: Connect with fyntek To create a Fyntek account, [sign up](https://fyntek.ai/) directly on the Fyntek website. Once logged in, navigate to **Terminals** and click **Create**. Search for and select **Finix** as the gateway, enter a name for your terminal, and set the **State** to **Active**. Fyntek Create Terminal ### Step 4: Configure Finix credentials in fyntek Contact your Fyntek point of contact to help you fill out the following details in the Fyntek gateway profile. You can locate your Finix credentials in your Finix Dashboard: Dashboard IDs - **Merchant ID** - Found in your Finix Dashboard under **Developer → Finix Integration → Merchant ID** - **Merchant Identity ID** - Found in your Finix Dashboard under **Developer → Finix Integration → Merchant Identity ID** - **Merchant Name** - The name associated with your Finix merchant account - **Username** - The username associated with your Finix API Key created in Step 2 - **Password** - The password associated with your Finix API Key created in Step 2 Fyntek Gateway Profile ## Additional features Fyntek supports digital wallet payments through Finix. To enable Apple Pay or Google Pay for your integration, follow the Finix setup guides below: - [Apple Pay](/guides/online-payments/digital-wallets/apple-pay/) - [Google Pay](/guides/online-payments/digital-wallets/google-pay/) ## Searching for transactions on the Finix Dashboard You can locate payments using the External ID visible in the Fyntek dashboard. In your Fyntek dashboard, navigate to **Gateway → Payments** and click on a payment to open the payment details. Locate the **External ID**. Fyntek Transaction Then, in the Finix Dashboard, either search or filter by the External ID: Filter Transaction 1. Navigate to the Payments list page. 2. Click on the Filters → Search by ID. 3. In the Payment ID field, filter by the External ID copied from the Fyntek dashboard. --- # Gravity Forms Source: https://docs.finix.com/additional-resources/plugins/gravity-forms-integration Accept payments with Finix on [Gravity Forms](https://www.gravityforms.com). Gravity Forms ## Gravity Forms overview Gravity Forms is a leading WordPress form builder used by more than 1 million sites worldwide. It provides a drag-and-drop interface for building advanced forms with conditional logic, multi-page flows, file uploads, and built-in payment collection. It integrates natively with WordPress and supports hundreds of third-party add-ons for CRM, email marketing, and payment processing. Finix integrates with Gravity Forms through the Cybersource payment gateway, enabling merchants to collect payments directly within their WordPress forms and reconcile transaction data within their Finix Dashboard. ### Finix requirements - Finix Live Account - Active Gravity Forms license with WordPress site ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports Gravity Forms via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Secure Acceptance Settings** — you'll need these to configure Gravity Forms: - **Merchant ID** - **REST API Key** - **Profile ID** Cybersource Key Management ### Step 3: Install the Cybersource gateway add-on Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Cybersource credentials from Step 2 - Gravity Forms 2.3.0 or later installed on your WordPress site - A valid SSL certificate on your WordPress site The Cybersource Gateway for Gravity Forms is a third-party add-on developed by [WP Gateways](https://www.gravityforms.com/add-ons/cybersource-payment-gateway/). For full installation details, refer to the [Gravity Forms Cybersource Gateway add-on page](https://www.gravityforms.com/add-ons/cybersource-payment-gateway/). To install: 1. Purchase and download the add-on from WP Gateways. 2. In your WordPress admin, navigate to **Plugins → Add New → Upload Plugin**. 3. Upload the plugin `.zip` file and click **Install Now**. 4. Click **Activate Plugin**. ### Step 4: Configure the Cybersource add-on This add-on uses CyberSource's Secure Acceptance Hosted Checkout — customers are redirected to CyberSource's hosted payment page to enter their card details, keeping your site out of PCI scope. In your WordPress admin: 1. Navigate to **Forms → Settings → Cybersource**. 2. Enter the following credentials from Step 2: - **Merchant ID** - your Cybersource Merchant ID - **Access Key** - your Secure Acceptance Access Key - **Profile ID** - your Secure Acceptance Profile ID - **Secret Key** - your Secure Acceptance Secret Key 3. Set the **Environment** to **Test** for sandbox or **Production** for live payments. 4. Save the settings. After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Gravity Forms transactions When you run a transaction on Gravity Forms, you'll see it: - In your WordPress admin under **Forms → Entries**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Plugins & Partners Source: https://docs.finix.com/additional-resources/plugins Learn about the plugins that Finix supports. Plugins Hero br br br Finix supports plugins to offer seamless integrations that make payments easy. With our plugins, you can use Finix to accept payments with the tools you already use, such as WooCommerce. ## Become a partner Join the [Finix Partner Program](/additional-resources/plugins/become-a-partner). ## Built by Finix WooCommerce Logo **WooCommerce** ## Built by our partners Checkout Champ **CheckoutChamp** Evervault **Evervault** Fyntek **Fyntek** GambleID **GambleID** GammaSweep **GammaSweep** Hyperswitch **Hyperswitch** Paysight **Paysight** Sticky Logo **StickyIO** Tagada **Tagada** --- # Jotform Source: https://docs.finix.com/additional-resources/plugins/jotform-integration Accept payments with Finix on [Jotform](https://www.jotform.com). Jotform ## Jotform overview Jotform is a leading no-code form builder to create payment forms, surveys, lead capture tools, and workflow automations. It provides a drag-and-drop interface with built-in support for payment collection, conditional logic, and third-party integrations. Finix integrates with Jotform through the Cybersource payment gateway, enabling merchants to collect payments directly within Jotform forms and reconcile transaction data within their Finix Dashboard. ### Finix requirements - Finix Live Account - Active Jotform account ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports Jotform via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center — you'll need these to configure Jotform: - **Merchant ID** - your unique Cybersource account identifier - **Transaction Key** - generated in the Business Center; authorizes and encrypts transaction requests between Jotform and Cybersource ### Step 3: Add and configure the CyberSource payment element Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Cybersource credentials from Step 2 Jotform includes a native CyberSource payment element in the Form Builder. For full details, refer to the [Jotform CyberSource integration guide](https://www.jotform.com/help/588-how-to-integrate-cybersource-with-jotform/). #### Add the CyberSource element 1. Open your form in the Jotform Form Builder and click **Add Element** in the left sidebar. Jotform Add Element 1. Navigate to the **Payments** tab and search for and select **CyberSource**. Jotform CyberSource in Payments Tab 1. In the integration window, enter your credentials and configure the following: - **Merchant ID** - from Step 2 - **Transaction Key** - from Step 2 - **Currency** - select your preferred currency - **Bill to** - map to the email address field on your form - **Billing address** - map to the address field on your form Jotform CyberSource Authentication Settings 1. Select your **Payment Type**: - **Sell Products** - one-time purchases at fixed prices - **Sell Subscriptions** - recurring charges for services or memberships - **User-Defined Amount** - customer-entered amounts with optional suggested minimums - **Collect Donations** - voluntary contributions for nonprofits or fundraising Jotform CyberSource Payment Type 1. Expand **Additional Gateway Settings** to configure optional fields: - **Sandbox Mode** - toggle on for testing, off for live payments - **Authorization Only** - authorize without immediate capture - **Order Prefix** - appended to the Order ID sent to CyberSource - **Show Total Price on Form**, **Decimal Separator**, and other display options Jotform CyberSource Additional Gateway Settings 1. Click **Continue** (for products or subscriptions) or **Save** (for all other payment types). #### Set up Cybersource as a reusable payment connection To reuse your CyberSource credentials across multiple forms: 1. In Form Builder, click **Add Element** on the left side of the page. 2. In the Form Elements menu, under the **Payments** tab, search for **CyberSource** and click on it — or drag and drop it to the desired location on your form. 3. In Payment Properties, click the **plug icon** to open connection settings. Jotform CyberSource Plug Icon 1. Select **Test Mode** or **Live Mode**. 2. Enter a **Connection Name**, your **Merchant ID**, and your **Transaction Key**. 3. Click **Connect With CyberSource**, then click **Save**. Jotform CyberSource Connection Credentials 1. In the Payment Connections window, select your saved connection and click **Use**. Jotform CyberSource Payment Connections 1. In Payment Properties, configure your **Payment Type**, **Currency**, **Bill to**, and **Billing address**. Jotform CyberSource Payment Properties After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Jotform transactions When you run a transaction on Jotform, you'll see it: - In your Jotform account under **My Forms → Submissions**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Kibo Commerce Source: https://docs.finix.com/additional-resources/plugins/kibo-commerce-integration Accept payments with Finix on [Kibo Commerce](https://kibocommerce.com). Kibo Commerce ## Kibo Commerce overview Kibo Commerce is a headless commerce platform built for enterprise retailers. It provides a modular suite of tools spanning eCommerce, order management, and AI-driven personalization - enabling brands to deliver consistent buying experiences across web, mobile, and in-store channels. Kibo supports complex B2C and B2B commerce operations at scale. Finix integrates with Kibo Commerce through the Cybersource payment gateway, enabling merchants to process payments and reconcile transaction data within their Kibo environment. ### Finix requirements - Finix Live Account - Active Kibo Commerce tenant ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports Kibo Commerce via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure Kibo Commerce: - **Merchant ID** (also called Organization ID) - **REST API Key** Cybersource Key Management ### Step 3: Configure Cybersource in Kibo Commerce Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Cybersource credentials from Step 2 - Administrator access to your Kibo Commerce admin Kibo Commerce supports Cybersource natively — no extension installation required. For full details, refer to the [Kibo Commerce Payment Gateways documentation](https://docs.kibocommerce.com/pages/payment-gateways). 1. In your Kibo Commerce admin, navigate to **System → Settings → Payment Gateways**. 2. Click **Create New Payment Gateway** and select **Cybersource V2** from the dropdown. 3. Enter the following credentials: - **Nickname** - a custom name for this gateway instance - **Merchant ID** - your Cybersource Merchant ID from Step 2 - **API Key** - your REST API Key ID from Step 2 - **API Shared Secret** - your REST API Shared Secret from Step 2 4. Save the configuration. Kibo Commerce Cybersource Gateway Configuration After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Kibo Commerce transactions When you run a transaction on Kibo Commerce, you'll see it: - In your Kibo Admin under **Orders → Orders**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Manhattan Associates Source: https://docs.finix.com/additional-resources/plugins/manhattan-associates-integration Accept payments with Finix on [Manhattan Associates](https://www.manh.com). Manhattan Associates ## Manhattan Associates overview Manhattan Associates is a leader in supply chain and commerce software trusted by retailers worldwide. Its Manhattan Active Omni platform provides unified order management, point-of-sale, store inventory, and customer engagement tools — enabling retailers to fulfill and service orders across every channel from a single system. Finix integrates with Manhattan Active Omni through the Cybersource payment gateway, enabling merchants to process payments and reconcile transaction data within their Manhattan environment. ### Finix requirements - Finix Live Account - Active Manhattan Active Omni account ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports Manhattan Associates via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure Manhattan Active Omni: - **Merchant ID** (also called Organization ID) - **REST API Key** Cybersource Key Management ### Step 3: Configure Cybersource in manhattan active omni Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Cybersource credentials from Step 2 - Administrator access to your Manhattan Active Omni account Manhattan Active Omni integrates with Cybersource natively as a credit card gateway. For full details, refer to the [Manhattan Associates Cybersource developer documentation](https://developer.manh.com/docs/reference/app/mao/credit-card/cybersource/). 1. In your Manhattan Active Omni admin, navigate to **Settings → Payment Configuration → Credit Card Gateway**. 2. Select **Cybersource** as the gateway provider. 3. Enter the following credentials from Step 2: - **Merchant ID** - your Cybersource Organization ID - **REST API Key ID** - your REST Key ID - **REST API Shared Secret** - your REST Shared Secret 4. Select the environment (**Test** for sandbox, **Production** for live). 5. Save the configuration and assign the gateway to the relevant business units or stores. After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Manhattan Associates transactions When you run a transaction on Manhattan Associates, you'll see it: - In your Manhattan Active Omni dashboard under **Orders → Payment Transactions**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # NetSuite Source: https://docs.finix.com/additional-resources/plugins/netsuite-integration Accept payments with Finix on [NetSuite](https://www.netsuite.com). NetSuite ## NetSuite overview NetSuite is Oracle's leading cloud ERP suite, used by organizations worldwide for unified financials, CRM, inventory, and eCommerce management. It provides businesses with a single platform to manage accounting, order processing, billing, and revenue recognition — eliminating the need for multiple disconnected systems. Finix integrates with NetSuite through the Cybersource payment gateway, allowing merchants to process card payments and automatically sync transaction data back into their NetSuite financial records. ### Finix requirements - Finix Live Account - Active NetSuite account with SuiteBundler access ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports NetSuite via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure NetSuite: - **Merchant ID** (also called Organization ID) - **REST API Keys** Cybersource Key Management ### Step 3: Set up your NetSuite account Before proceeding, ensure your NetSuite environment is ready: 1. In NetSuite, navigate to Customization → SuiteBundler → Search and Install Bundles and search for **316818** or **Cybersource for NetSuite**. 2. Select the bundle from the results and click Install. 3. Once installed, enable the plugin via Customization → Plug-ins → Manage Plug-ins. ### Step 4: Configure SuiteApp Once the bundle is installed and enabled, complete the following in NetSuite to set up the SuiteApp. Navigate to **Cybersource Integration → SuiteApp Configuration → Step 1: Payment Methods** and create a payment method for each card brand you want to accept (e.g., Visa, Mastercard, American Express). Include tokenization methods if you plan to save card details for future transactions. NetSuite Payment Methods ### Step 5: Map payment methods and create a payment processing profile #### Payment Method Mapping Navigate to Cybersource Integration → SuiteApp Configuration → Step 2: Payment Method Mapping → Map Payment Methods. The SuiteApp automatically maps your created payment methods to the corresponding NetSuite payment records. #### Payment Processing Profile Navigate to Cybersource Integration → SuiteApp Configuration → Step 3: Payment Processing Profile → Create Payment Processing Profile and enter the following: - **Name** - enter a name of payment processing profile - **Website** and **Subsidiary** — the scope this profile applies to - **Merchant ID** - your Cybersource Organization ID - **Key ID** and **Secret Key** — your REST credentials from Step 2 - **Supported Payment Methods** - select the card brands created in Step 4 - **Gateway Request Types** - enable the transaction types you need: Authorization, Capture, Sale, Refund, Credit - **Test Mode** - check for sandbox; uncheck for production After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## NetSuite transactions When you run a transaction on NetSuite, you'll see it: - In your NetSuite dashboard under **Transactions → Sales → Customer Payments**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Odoo Source: https://docs.finix.com/additional-resources/plugins/odoo-integration Accept payments with Finix on [Odoo](https://www.odoo.com). Odoo ## Odoo overview Odoo is an open-source business management suite used by more than 12 million users globally. It brings together ERP, CRM, eCommerce, accounting, inventory, and more in a single modular platform. Its flexible app marketplace and headless eCommerce capabilities make it a popular choice for businesses of all sizes. Finix integrates with Odoo through the Cybersource payment gateway, enabling merchants to accept payments directly within their Odoo storefront and reconcile transaction data within their Finix Dashboard. ### Finix requirements - Finix Live Account - Active Odoo instance (Odoo 16 or later) ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports Odoo via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure Odoo: - **Merchant ID** (also called Organization ID) - **REST API Key** Cybersource Key Management ### Step 3: Install the Cybersource payment module Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Cybersource credentials from Step 2 - Odoo 16 or later - The following Odoo apps installed: **eCommerce**, **Website**, **Invoicing**, and **Discuss** For full details, refer to the [Odoo CyberSource Payment Gateway module page](https://apps.odoo.com/apps/modules/16.0/ws_payment_cybersource). Install the required Python dependency on your Odoo server: ```bash pip install suds-py3 ``` Then purchase and download the `ws_payment_cybersource` module from the Odoo Apps Store. Add the module folder to your Odoo add-ons path and activate it from **Apps**. ### Step 4: Configure the Cybersource payment provider 1. In your Odoo instance, navigate to **Website → Configuration → Payment Transactions**. 2. Select **CyberSource** from the payment provider list. Odoo CyberSource Payment Provider 1. Enter the following credentials from Step 2: - **Merchant ID** - your CyberSource Organization ID - **CyberSource Key** - your CyberSource authentication key 2. Configure the associated **Payment Journal**. 3. Set the provider to **Enabled** for live payments or **Test Mode** for sandbox. 4. Save the configuration. Odoo CyberSource Settings After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Odoo transactions When you run a transaction on Odoo, you'll see it: - In your Odoo dashboard under **Sales → Orders**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # OpenCart Source: https://docs.finix.com/additional-resources/plugins/opencart-integration Accept payments with Finix on [OpenCart](https://www.opencart.com). OpenCart ## OpenCart overview OpenCart is a free, open-source eCommerce platform used by merchants worldwide to build and manage online stores. It offers a modular extension marketplace, multi-store and multi-language support, and a flexible admin panel for managing products, orders, and payments. Finix integrates with OpenCart through the Cybersource payment gateway, enabling merchants to accept payments directly within their OpenCart storefront and reconcile transaction data within their Finix Dashboard. ### Finix requirements - Finix Live Account - Active OpenCart store ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports OpenCart via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure OpenCart: - **Merchant ID** (also called Organization ID) - **REST API Key** Cybersource Key Management ### Step 3: Install the Cybersource plugin Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Cybersource credentials from Step 2 - OpenCart version 3.0.3.7, 3.0.3.8, or 3.0.3.9 - Administrator access to your OpenCart Back Office Download the official Cybersource plugin from the [OpenCart Marketplace](https://www.opencart.com/index.php?route=marketplace/extension) as a `.zip` file. For full installation details, refer to the [Cybersource OpenCart developer documentation](https://developer.cybersource.com/technology-partners/OpenCart.html). To install: 1. In your OpenCart Back Office, navigate to **Extensions → Installer**. 2. Click **Upload** and select the `cybersource.ocmod.zip` file. 3. Confirm the upload progress reaches 100% and the file appears in the installed extensions list. 4. Navigate to **Extensions → Extensions** and select **Modules** from the extension type dropdown. 5. Locate **Cybersource Configuration** and click **Install**. ### Step 4: Configure the Cybersource plugin Navigate to **Extensions → Payments → Cybersource → Edit** and enter the following: **General Configuration:** - **Merchant ID** - your Cybersource Organization ID from Step 2 - **Merchant Key ID** - your REST API Key ID from Step 2 - **Merchant Secret Key** - your REST API Shared Secret from Step 2 - **Sandbox Mode** - enable for testing, disable for live payments - **Fraud Management** - enable to activate Cybersource Decision Manager - **Device Fingerprint** - enable for enhanced fraud detection - **Enhanced Logs** - enable for detailed transaction logging **Report Configuration:** - **Payment Batch Configuration** - enable or disable batch payment reporting - **Transaction Request Report** - enable or disable transaction request reporting - **Conversion Detail Report** - enable or disable; if running manual fraud reviews in Cybersource, this will pull fraud updates into OpenCart After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## OpenCart transactions When you run a transaction on OpenCart, you'll see it: - In your OpenCart admin under **Sales → Orders**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Oracle Commerce Cloud Source: https://docs.finix.com/additional-resources/plugins/oracle-commerce-cloud-integration Accept payments with Finix on [Oracle Commerce Cloud](https://www.oracle.com/cx/commerce/). Oracle Commerce Cloud ## Oracle Commerce Cloud overview Oracle Commerce Cloud is Oracle's enterprise SaaS commerce platform designed for mid-market and enterprise retailers running B2C and B2B storefronts. It offers a fully managed, cloud-native environment with built-in tools for catalog management, promotions, order management, and personalization. Cybersource is pre-integrated as the default payment gateway, making it straightforward to connect to Finix. ### Finix requirements - Finix Live Account - Active Oracle Commerce Cloud instance ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports Oracle Commerce Cloud via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure Oracle Commerce Cloud: - **Merchant ID** (also called Organization ID) - **REST API Keys** Cybersource Key Management ### Step 3: Set up your Oracle Commerce Cloud environment Before proceeding, ensure your local development environment meets the following requirements: - **Node.js** v18.16.1 (use [NVM](https://github.com/nvm-sh/nvm) to manage multiple versions) - **Yarn** v1.22.4 - An active Oracle Commerce Cloud instance (OCC v23.11 or compatible) ### Step 4: Register and upload the payment gateway extension Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Oracle Commerce Cloud instance with developer access - Node.js and Yarn installed per Step 3 To install the extension: 1. Log into your Oracle Commerce Cloud admin and navigate to Settings → Extensions → Developer tab. 2. Click Generate ID, name your extension, and copy the generated ID into `packages/payment-gateway/ext.json`. 3. Zip all files in the `packages/payment-gateway` directory (exclude `settings.json`), then navigate to Settings → Extensions and click Upload Extension to upload your zip file. For full installation details, refer to the [Cybersource Oracle Commerce Cloud developer documentation](https://developer.cybersource.com/technology-partners/OracleCommerceCloud.html). ### Step 5: Configure the Cybersource payment gateway In your Oracle Commerce Cloud admin, navigate to **Settings → Payment Processing**. 1. Select the **Payment Gateways** tab, choose **Cybersource Official** from the list, and check **Payment Gateway Enabled**. 2. Enter your Finix-provisioned Cybersource credentials. This includes the Merchant ID and API Keys. 3. Return to the **Payment Types** tab and select the card brands you want to accept: Visa, Mastercard, Amex, Discover, Diners Club, JCB, Maestro, or others as needed. 4. Navigate to **Settings → Web APIs → Function APIs** and configure the Production and Preview webhooks, replacing the `{env}` placeholder with your environment value. Save the secret key for your SSE deployment. After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Oracle Commerce Cloud transactions When you run a transaction on Oracle Commerce Cloud, you'll see it: - In your Oracle Commerce Cloud admin under **Orders**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Paysight Source: https://docs.finix.com/additional-resources/plugins/paysight-plugin Accept payments with Finix on [Paysight](https://www.paysight.io). Finix for Paysight ## Finix for Paysight overview Paysight is a comprehensive CRM and payments management platform that helps merchants centralize customer data, payment activity, and operational workflows within a single, intuitive interface. It enables businesses to streamline their customer lifecycle, track transactions, and manage billing, while integrating seamlessly with payment processors and gateways. Connecting Finix to Paysight allows merchants to manage their entire payment workflow directly within the Paysight platform, pairing Paysight’s CRM and operational tools with Finix’s payments infrastructure. ### Finix requirements - Finix Sandbox Account to process Sandbox transactions. You will not be able to move real money in this environment. - Finix Live Account to run card or ACH transactions. ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create API keys API Environments API Keys are specific to either the Sandbox or Live environments, depending on whether you get them from the Sandbox or Live Dashboard. Sandbox Keys cannot be used in the Live Environment and vice-versa. [Learn more here](/api/section/environments). To create an API Key: 1. Navigate to **Developers → API Keys** in the Finix dashboard. 2. Click **Create API Key** and enter a **Display Name**. 3. Save the credentials somewhere secure. Store API Keys Securely Save your password somewhere secure. You **cannot** re-copy the password, but you can always create another API Key. API Keys are sensitive data and must be treated like passwords. Store them securely and only share them on an as-needed basis. To learn more see our [API Keys](/additional-resources/developers/authentication-and-api-basics/api-keys) documentation. ### Step 3: Connect with Paysight In your Paysight Dashboard, navigate to MID Management → MID Accounts. Locate the +Connect Merchant Account, on the top right corner, to create a merchant profile. Activate Finix ### Step 4: Configure Finix credentials in Paysight Enter your Finix credentials in the corresponding fields within the Gateway Setup section of Paysight merchant account onboarding form. You can locate these details in your Finix Dashboard: - Gateway: Select Finix - Currency: USD or CAD - Merchant ID: Found in your Finix Dashboard under Developer → Finix Integration → Merchant ID Dashboard IDs - API Username: The username associated with your Finix API Key created in Step 2 - API Password: The password associated with your Finix API Key created in Step 2 Paysight Gateway Profile These credentials allow Paysight to securely connect to your Finix account for payment processing. For more information on how to complete the Paysight Onboarding Form, see the [Paysight Guide](https://docs.paysight.io/guides/creating-a-mid). ## Searching for transactions on the Finix Dashboard You can find Payments using the Gateway Transaction ID on the Finix Dashboard. On Paysight Dashboard, navigate to Transactions → Gateway Transaction ID & Gateway column and copy transaction ID. Paysight Dashboard Then, in the Finix Dashboard, either search or filter by transaction ID: Filter Transaction 1. Navigate to the Payments list page. 2. Click on the Filters → Search by ID. 3. In the Payment ID field, filter by transaction ID copied from Paysight Dashboard. --- # PrestaShop Source: https://docs.finix.com/additional-resources/plugins/prestashop-integration Accept payments with Finix on [PrestaShop](https://www.prestashop.com). PrestaShop ## PrestaShop overview PrestaShop is a leading open-source eCommerce platform powering more than 300,000 stores worldwide, with especially strong adoption across Europe. It provides a modular, customizable storefront with a built-in marketplace of thousands of add-ons for payments, shipping, marketing, and more. Merchants can manage products, orders, customers, and promotions from a centralized admin panel. Finix integrates with PrestaShop through the Cybersource payment gateway, enabling merchants to accept payments directly within their PrestaShop storefront and reconcile transaction data within their Finix Dashboard. ### Finix requirements - Finix Live Account - Active PrestaShop store ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports PrestaShop via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure PrestaShop: - **Merchant ID** (also called Organization ID) - **REST API Key** Cybersource Key Management ### Step 3: Install the Cybersource plugin Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Cybersource credentials from Step 2 - PrestaShop version 1.7.0 through 8.2 - Administrator access to your PrestaShop Back Office Search for **Cybersource Official** on the [PrestaShop Marketplace](https://addons.prestashop.com) and download the plugin. For full installation details, refer to the [Cybersource PrestaShop developer documentation](https://developer.cybersource.com/technology-partners/PrestaShop.html). To install: 1. In your PrestaShop Back Office, navigate to **Modules → Module Manager**. 2. Click **Upload a Module** and drag and drop the plugin file or select it from your system. 3. Confirm the installation and verify the module appears in the **Payments** section. ### Step 4: Configure the Cybersource plugin In your PrestaShop Back Office, navigate to the Cybersource module settings and configure the **General Settings** tab: - **Sandbox Mode** - select **Sandbox** for testing or **Production** for live payments - **Merchant ID** - your Cybersource Organization ID from Step 2 - **Merchant Key ID** - your REST Key ID from Step 2 - **Merchant Secret Key** - your REST Shared Secret from Step 2 - **Payment Action** - select **Authorize** to capture manually, or **Sale** to authorize and capture immediately - **Enhanced Logs** - enable for detailed transaction logging during troubleshooting After saving General Settings, switch to the **Payment Settings** tab and enable **Credit Cards**. After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## PrestaShop transactions When you run a transaction on PrestaShop, you'll see it: - In your PrestaShop back office under **Orders → Orders**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Salesforce Billing Source: https://docs.finix.com/additional-resources/plugins/salesforce-billing-integration Accept payments with Finix on [Salesforce Billing](https://www.salesforce.com/products/revenue-cloud/overview/). Salesforce Billing ## Salesforce billing overview Salesforce Billing is part of Salesforce Revenue Cloud, built natively on the Salesforce platform to automate quote-to-cash workflows — from generating invoices and collecting payments to managing revenue recognition and financial reporting. It integrates directly with Salesforce CPQ, Sales Cloud, and the broader Customer 360 ecosystem, giving teams a unified view of the customer lifecycle from opportunity to payment. Finix integrates with Salesforce Billing through the Cybersource payment gateway, enabling merchants to process payments and reconcile transaction data within their Salesforce environment. ### Finix requirements - Finix Live Account - Active Salesforce org with Salesforce Billing and Revenue Cloud licenses ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports Salesforce Billing via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure Salesforce Billing: - **Merchant ID** (also called Organization ID) - **REST API Key ID** Cybersource Key Management ### Step 3: Install the Cybersource managed package Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Cybersource credentials from Step 2 - Salesforce CPQ installed (required before installing Salesforce Billing) - Salesforce Billing license Install the **Cybersource for Salesforce Billing** managed package from AppExchange. For full installation details, refer to the [Cybersource Salesforce Billing developer documentation](https://developer.cybersource.com/technology-partners/salesforce-Billing.html). - **AppExchange listing:** [Cybersource for Salesforce Billing](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N4V00000G2HK9UAN) ### Step 4: Assign permission sets After installing the package, assign the following permission sets to the appropriate users in your Salesforce org: - **Cybersource Admin User** - for administrators managing the gateway configuration - **Cybersource Billing User** - for users processing payments through Salesforce Billing Then assign the **Cybersource Gateway Layout** to the user profile that manages the Cybersource key management: 1. Go to **Setup** (gear icon, top right). 2. Click **Object Manager** and open the **Payment Gateway** (`blng__PaymentGateway__c`) object. 3. Click **Page Layouts → Page Layout Assignment**. 4. Click **Edit Assignment** and assign the **Cybersource Gateway Layout** to the appropriate profile. ### Step 5: Create a payment gateway record Create the **Payment Gateway** via **Setup → Object Manager → Payment Gateway**, then create a new Payment Gateway record with the following fields: - **Payment Gateway Name** - a name for this gateway instance - **Merchant ID** - your Cybersource Merchant ID from Step 2 - **Gateway Type** - select **Cybersource Payments** - **Endpoint** - select **Test** for sandbox or **Production** for live payments - **Key ID** - your Cybersource Key ID from Step 2 - **Shared Secret** - your Cybersource Shared Secret Key from Step 2 - **Active** - enable to make this gateway available - **Default** - enable to set as the default payment gateway After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Salesforce billing transactions When you run a transaction on Salesforce Billing, you'll see it: - In your Salesforce org under **Billing → Payments**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Salesforce Commerce Cloud Source: https://docs.finix.com/additional-resources/plugins/salesforce-commerce-cloud-integration Accept payments with Finix on [Salesforce Commerce Cloud](https://www.salesforce.com/commerce/). Salesforce Billing ## Salesforce Commerce Cloud overview Salesforce Commerce Cloud is an enterprise eCommerce platform used by global brands to deliver B2C and B2B digital shopping experiences. It provides a fully managed, cloud-hosted environment with tools for storefront merchandising, AI-driven personalization, order management, and omnichannel fulfillment. Finix integrates with Salesforce Commerce Cloud through the Cybersource payment gateway enabling merchants to accept payments directly within their B2C Commerce storefront. ### Finix requirements - Finix Live Account - Active Salesforce B2C Commerce Cloud instance ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports Salesforce Commerce Cloud via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure Salesforce Commerce Cloud: - **Merchant ID** (also called Organization ID) - **REST Shared Secret Key and Key ID** (required for Microform) - **SOAP Toolkit Key** (used for all other integrations) Cybersource Key Management ### Step 3: Set up your Salesforce Commerce Cloud environment Before proceeding, ensure your environment is ready: - Active Salesforce Commerce Cloud subscription - Store Front Reference Architecture (SFRA) `app_storefront_base` cartridge installed and configured ### Step 4: Install and upload the Cybersource cartridge Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Salesforce Commerce Cloud instance with developer access - Node.js and npm installed To install the cartridge: 1. Download the integration package from [Salesforce AppExchange](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N4V00000JfuFgUAJ). 2. Create a `Cybersource` folder in your project workspace and place the `int_cybersource_sfra` cartridge inside it. 3. Configure your `dw.json` file with your SFCC instance credentials for IDE integration: ```json { "hostname": "your-sandbox-hostname.demandware.net", "username": "yourlogin", "password": "yourpwd", "version": "version_to_upload_to", "cartridge": ["int_cybersource_sfra", "app_storefront_base", "modules"] } ``` 1. Install `sgmf-scripts` and `copy-webpack-plugin` with the following commands: ```bash npm install sgmf-scripts npm install copy-webpack-plugin ``` 1. Compile cartridge assets: ```bash npm run compile:js npm run compile:scss ``` 1. Upload the cartridge to your Salesforce Commerce Cloud instance: ```bash npm run uploadCartridge ``` For full installation details, refer to the [Cybersource Salesforce Commerce Cloud developer documentation](https://developer.cybersource.com/technology-partners/salesforce-commerce-cloud.html). ### Step 5: Configure Salesforce Commerce Cloud cartridge Once the cartridge is uploaded, complete the following configuration in Business Manager: #### Cartridge Path Navigate to **Administration → Sites → Manage Sites → [Your Site] → Settings** and add the following to your cartridge path: ```text int_cybersource_sfra:app_storefront_base ``` #### Import Metadata 1. In the downloaded package, navigate to `Cybersource/metadata/sfra_meta/sites/` and rename the `yourSiteID` folder to match your actual site identifier. 2. Compress the `sfra_metadata` folder as a `.zip` file. 3. Import it via **Administration → Site Development → Site Import & Export**. This imports payment processors, payment methods, site preference groups, and Cybersource services. #### Credentials and Endpoint Navigate to **Merchant Tools → Custom Preferences → Cybersource Core** and enter: - **Merchant ID** - **REST API Key** or **SOAP Key** — your credentials from Step 2 - **API Endpoint** - select **Test** for sandbox or **Production** for live SFCC Cybersource Core Configuration ### Step 6: Set up payment methods Navigate to **Merchant Tools → Ordering → Payment Methods → CREDIT_CARD** and verify the Payment Processor is set to `CYBERSOURCE_CREDIT`. For Microform card capture, navigate to **Merchant Tools → Site Preferences → Custom Preferences → Cybersource_SecureAcceptance** and: - Set **Secure Acceptance Type** to `SA_FLEX` - Enter your **REST Key ID** and **Shared Secret** - Configure the **CS Transaction Type** based on your business requirements SFCC Cybersource Core Configuration After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Salesforce Commerce Cloud transactions When you run a transaction on Salesforce Commerce Cloud, you'll see it: - In your Business Manager admin under **Merchant Tools → Ordering → Orders**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Salesforce Order Management Source: https://docs.finix.com/additional-resources/plugins/salesforce-order-management-integration Accept payments with Finix on [Salesforce Order Management](https://www.salesforce.com/commerce/order-management/). Salesforce Billing ## Salesforce order management overview Salesforce Order Management is a native Salesforce application that enables retailers to orchestrate the full order lifecycle — from order capture and routing to fulfillment, invoicing, and returns — across channels and locations. Built on the Customer 360 platform, it gives operations teams a unified view of inventory, shipments, and payments in a single system. Finix integrates with Salesforce Order Management through the Cybersource payment gateway, allowing merchants to capture payments, process refunds, and reconcile transaction data. ### Finix requirements - Finix Live Account - Active Salesforce org with Order Management licenses ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports Salesforce Order Management via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure Salesforce Order Management: - **Merchant ID** (also called Organization ID) - **REST API Key ID** Cybersource Key Management ### Step 3: Set up your Salesforce order management environment Before proceeding, ensure your Salesforce environment is ready: - Active instance of Salesforce with Order Management subscription - Lightning Experience enabled - Purchase and activate an Order Management license. ### Step 4: Install the managed package Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Salesforce Order Management with Lightning Experience enabled Install the managed package from the [Salesforce AppExchange](https://appexchange.salesforce.com) by searching for **"Cybersource for Lightning Order Management"** and following the install wizard in your Salesforce org. For full installation details, refer to the [Cybersource Salesforce Order Management developer documentation](https://developer.cybersource.com/technology-partners/Salesforce-Order-Management.html). ### Step 5: Create a payment gateway provider Using Workbench, create a `PaymentGatewayProvider` record with the following fields: ```json { "ApexAdapterId": "", "DeveloperName": "Cybersource_Provider", "MasterLabel": "Cybersource_Provider", "IdempotencySupported": "Yes", "Comments": "Comments" } ``` ### Step 6: Create named credentials Navigate to **Setup → Named Credentials → New** and configure the following: - **Label / Name** - use the same value for both - **URL** - refer to the [Cybersource API endpoints](https://developer.cybersource.com/api-reference-assets/index.html#static-api-endpoints-section) for the correct URL for your environment - **Certificate** - leave blank - **Identity Type** - set to **Anonymous** - **Authentication Protocol** - set to **No Authentication** - **Generate Authorization Header** - deselect this checkbox - **Allow Merge Fields in HTTP Header** - select this checkbox - **Allow Merge Fields in HTTP Body** - select this checkbox ### Step 7: Create a payment gateway record Open the **App Launcher**, navigate to **Payment Gateways → New**, and fill in the following fields: - **Payment Gateway Name** - name your payment gateway - **Payment Gateway Provider** - select the provider created in Step 5 - **Merchant Credential** - select the Named Credential created in Step 6 - **Status** - set to **Active** - **External Reference** - enter the Processor ID from your Salesforce Commerce Cloud instance ### Step 8: Create a payment configuration record Navigate to **Setup → Custom Metadata Types → Payment Configuration (Managed) → New** and enter: - **Label** - a name for this configuration - **Merchant ID** - your Cybersource Organization ID - **Endpoint** - select **TEST** for sandbox or **PRODUCTION** for live - **REST Key ID** and **Shared Secret Key** — your credentials from Step 2 After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Salesforce order management transactions When you run a transaction on Salesforce Order Management, you'll see it: - In your Salesforce org under **Order Management → Payments**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # SAP Commerce Cloud Source: https://docs.finix.com/additional-resources/plugins/sap-commerce-cloud-integration Accept payments with Finix on [SAP Commerce Cloud](https://www.sap.com/products/crm/commerce-cloud.html). SAP Commerce Cloud ## SAP Commerce Cloud overview SAP Commerce Cloud (formerly Hybris) is SAP's enterprise commerce platform built for B2B, B2C, and B2B2C brands. It delivers a unified commerce experience across web, mobile, and in-store channels — with tools for product catalog management, personalization, order management, and checkout. Cybersource is the only payment service provider natively integrated across three SAP commerce products. Finix integrates with SAP Commerce Cloud through the Cybersource payment gateway, enabling merchants to process payments and reconcile transaction data within their SAP Commerce environment. ### Finix requirements - Finix Live Account - Active SAP Commerce Cloud tenant ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports SAP Commerce Cloud via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure SAP Commerce Cloud: - **Merchant ID** (also called Organization ID) - **REST API Key** Cybersource Key Management ### Step 3: Set up your SAP Commerce Cloud environment Before proceeding, ensure your SAP Commerce Cloud environment is ready: - SAP Commerce platform release **v2011** - Java 11 - Maven repository with required dependencies - Administrator access to your SAP Commerce Cloud landscape ### Step 4: Install the Cybersource payment plugin Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Cybersource credentials from Step 2 - `sap-commerce-payment-plugin-3.2.0.zip` downloaded from Cybersource For full installation details, refer to the [Cybersource SAP Commerce Cloud developer documentation](https://developer.cybersource.com/technology-partners/SAP_CommerceCloud.html). There are two installation options: **Automated Installation** using a custom Gradle recipe, or **Manual Installation** for a step-by-step approach. Automated Installation Using a custom recipe, Gradle manages most of the configuration automatically. 1. Extract the SAP Commerce suite: ```bash unzip sap-commerce-suite-2011.zip ``` 1. Deploy the payment plugin extensions: ```bash unzip sap-commerce-payment-plugin.zip -d sap-commerce-suite-2011 ``` 1. In `/resources/isvpaymentsampledata/import`, rename `.tpl` files to `.impex` and add your merchant details. 2. Run the installation recipe for your storefront type: ```bash # B2C ./install.sh -r b2c_acc_isv # B2B ./install.sh -r b2b_acc_isv ``` 1. Initialize the platform and start the server: ```bash ./install.sh -r b2c_acc_isv initialize ./install.sh -r b2c_acc_isv start ``` Manual Installation The manual approach requires individual file placement and configuration at each step. 1. Extract the SAP Commerce suite and install the B2C or B2B accelerator components. 2. Generate a storefront extension using the `extgen` tool. 3. Copy the payment plugin extensions into your project, maintaining the required folder structure. 4. Update `localextensions.xml` to include the Cybersource payment extensions. 5. Configure `local.properties` with your Java version and payment-specific settings. 6. Install the payment add-ons using Ant: ```bash ant addoninstall -Daddonnames="isvpaymentaddon" -DaddonStorefront.yacceleratorstorefront="yb2cacceleratorstorefront" ``` 1. Update your system hosts file for local DNS resolution: ```text # B2C 127.0.0.1 apparel-de.local apparel-uk.local # B2B 127.0.0.1 powertools.local ``` 1. Initialize the platform and start the server. ### Step 5: Configure the Cybersource plugin In your `local.properties` file, add the following merchant-specific configuration: ```properties isv.payment.api.rest.runEnvironment=CyberSource.Environment.SANDBOX isv.payment.api.rest.authenticationType=http_signature isv.payment.api.rest..merchantKeyId= isv.payment.api.rest..merchantsecretKey= ``` Replace ``, ``, and `` with your credentials from Step 2. Set `runEnvironment` to `CyberSource.Environment.PRODUCTION` for live payments. #### PCI Strategy Set `site.pci.strategy` to your preferred card capture method: - `FLEX` - Flex Microform (default, most secure) - `HOP` - Secure Acceptance Web/Mobile - `SOP` - Secure Acceptance Silent Order POST After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## SAP Commerce Cloud transactions When you run a transaction on SAP Commerce Cloud, you'll see it: - In your SAP Commerce Cloud Backoffice under **Order Management → Orders**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # SAP Source: https://docs.finix.com/additional-resources/plugins/sap-integration Accept payments with Finix on [SAP](https://www.sap.com). SAP ## SAP overview SAP is a global leader in enterprise software, trusted by the world's largest businesses to run their core operations across finance, procurement, supply chain, and commerce. Its flagship platform, provides a cloud-native ERP suite that unifies real-time data across business functions. Finix integrates with SAP through the Cybersource payment gateway via the SAP Digital Payments Add-on, enabling merchants to process payments and reconcile transaction data. ### Finix requirements - Finix Live Account - Active SAP landscape (S/4HANA, SAP Commerce Cloud, or related) ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports SAP via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure SAP: - **Merchant ID** (also called Organization ID) - **REST API Key** Cybersource Key Management ### Step 3: Install and set up the SAP digital Payments add-on Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - An active SAP landscape (S/4HANA, SAP Commerce Cloud, or related) - Your **SAP Tenant ID** — required for MID mapping in Step 4 - Administrator access to your SAP Digital Payments Add-On instance Install the SAP Digital Payments Add-On (DPA), the cloud-based connector that enables Cybersource payment processing across SAP applications. Follow SAP's deployment guide for your specific SAP landscape. For full installation details, refer to the [Cybersource SAP DPA developer documentation](https://developer.cybersource.com/technology-partners/sap-dpa.html). ### Step 4: Map your Merchant ID to your SAP tenant Contact the Cybersource SAP DPA integration team at **GDLSAPDPA@visa.com** with the following information: - Your **SAP Tenant ID** - Your **Cybersource Merchant ID** - Whether the mapping is for **TEST** or **PRODUCTION** The team will complete the MID-to-tenant mapping required to route payments through your Finix-provisioned Cybersource account. ### Step 6: Activate Cybersource as your payment service provider Once the mapping is confirmed, navigate to the following URL in your SAP environment: ```text https://{{yourbaseURL}}/pspStatus/index.html ``` Select **Cybersource** from the list and activate it as your payment service provider. The system will display **Active** status upon successful activation. ### Step 7: Verify your Merchant ID configuration Navigate to the following URL to confirm your Merchant ID is correctly configured: ```text https://{{yourbaseURL}}/pspDetermination/index.html ``` Verify that your requested MIDs appear in the **Merchant** column. Once confirmed, your SAP environment is ready to process payments through Finix via the Cybersource gateway. After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## SAP transactions When you run a transaction on SAP, you'll see it: - In your SAP dashboard under the Digital Payments Add-On transaction log. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Shopify Source: https://docs.finix.com/additional-resources/plugins/shopify-integration Accept payments with Finix on [Shopify](https://www.shopify.com). Shopify ## Shopify overview Shopify is a leading cloud-based, all-in-one commerce platform that enables individuals and businesses to build, customize, and scale online store without complex development requirements. It offers a comprehensive suite of tools, including website builders, secure payment processing, inventory management, and built-in marketing capabilities. With its flexible architecture and extensive app ecosystem, Shopify supports businesses at every stage. ### Finix requirements - Finix Live Account - US Based Shopify Account ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports Shopify via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). ### Step 3: Sign up with Shopify To proceed to the next step, please ensure your Shopify account is fully registered. This includes completing all required onboarding steps and submitting KYC/KYB information to Shopify. ### Step 4: Accept terms Before you proceed forward, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Registered US based Shopify account For the next steps: 1. Navigate to [https://apps.shopify.com/cybersource](https://apps.shopify.com/cybersource). This URL will take you Cybersource production login. 2. Click Install or Open (the button may vary depending on whether you’ve previously accessed the page). 3. Review and accept the Shopify and Cybersource Terms. Cybersource-Shopify-Terms Cybersource Integration Ensure you only select Access Agreement and not Payer Authentication. ### Step 5: Navigate back to Shopify and select Payments tab In this last step, you'll configure your card brands and Payment Methods. Cybersource-Shopify-Payment Methods After you configure your card brands and payment methods on Shopify, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Shopify transactions When you run a transaction on Shopify, you should now see the transaction on your Shopify Account and also on Cybersource. Shopify Screenshot These transactions will be ingested by Finix and added into `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Sitecore Source: https://docs.finix.com/additional-resources/plugins/sitecore-integration Accept payments with Finix on [Sitecore](https://www.sitecore.com). Sitecore ## Sitecore overview Sitecore is a leading enterprise digital experience platform trusted by global brands. It combines content management, commerce, personalization, and analytics into a unified platform — enabling organizations to deliver tailored digital experiences across web, mobile, and in-store channels. Sitecore OrderCloud, its headless commerce API, powers flexible B2B, B2C, and marketplace scenarios at scale. Finix integrates with Sitecore through the Cybersource payment gateway, enabling merchants to process payments and reconcile transaction data within their Sitecore environment. ### Finix requirements - Finix Live Account - Active Sitecore Experience Commerce or Sitecore OrderCloud instance ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports Sitecore via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from your CyberSource account dashboard — you'll need these to configure your Sitecore OrderCloud middleware: - **Merchant ID** - **Rest API Key** Cybersource Key Management ### Step 3: Install the CyberSource .NET SDK Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Cybersource credentials from Step 2 - Active Sitecore OrderCloud instance - .NET Core SDK installed Sitecore OrderCloud connects to CyberSource through a custom middleware layer using the CyberSource REST .NET client library. Install the package in your middleware project: ```bash Install-Package CyberSource.Rest.Client.NetStandard ``` ### Step 4: Configure your middleware In your middleware project, implement the following payment methods by calling the corresponding CyberSource REST APIs: - **ProcessPayment** - process a payment transaction - **AuthorizePayment** - authorize a payment without capturing - **CheckPaymentStatus** - retrieve the status of a transaction - **CapturePayment** - capture a previously authorized payment - **RefundPayment** - issue a refund for a completed transaction - **VoidPayment** - void an authorized or captured transaction - **CreateCustomer** - create a tokenized customer profile Configure the following credentials in your middleware settings using the values from Step 2: - **Merchant ID** - your CyberSource Merchant ID - **API Login ID** - your CyberSource API Login ID - **Transaction Key** - your CyberSource Transaction Key In your CyberSource account dashboard, add your Sitecore OrderCloud middleware URL as an approved URL to permit communication between the two systems. After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Sitecore transactions When you run a transaction on Sitecore, you'll see it: - In your Sitecore admin under **Commerce → Orders**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Sticky.io Source: https://docs.finix.com/additional-resources/plugins/sticky-plugin Accept payments with Finix on [sticky.io](https://sticky.io). Finix for Sticky.io ## Finix for Sticky.io overview Sticky.io is a comprehensive subscription commerce and payments management platform that helps merchants manage recurring billing, customer lifecycle, and payment operations from a single interface. It enables businesses to configure payment gateways, manage orders and subscriptions, route transactions, and access detailed reporting tools. Connecting Finix to Sticky.io allows merchants to process payments using Finix's payments infrastructure directly within the Sticky.io platform, pairing Sticky.io's commerce tools with Finix's payment processing capabilities. ### Finix requirements - Finix Sandbox Account to process Sandbox transactions. You will not be able to move real money in this environment. - Finix Live Account to run card or ACH transactions. ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create API keys API Environments API Keys are specific to either the Sandbox or Live environments, depending on whether you get them from the Sandbox or Live Dashboard. Sandbox Keys cannot be used in the Live Environment and vice-versa. [Learn more here](/api/section/environments). To create an API Key: 1. Navigate to **Developers → API Keys** in the Finix dashboard. 2. Click **Create API Key** and enter a **Display Name**. 3. Save the credentials somewhere secure. Store API Keys Securely Save your password somewhere secure. You **cannot** re-copy the password, but you can always create another API Key. API Keys are sensitive data and must be treated like passwords. Store them securely and only share them on an as-needed basis. To learn more see our [API Keys](/additional-resources/developers/authentication-and-api-basics/api-keys) documentation. ### Step 3: Connect with Sticky.io In your Sticky.io dashboard, navigate to **Payments → Gateways** in the top navigation menu. Sticky.io Gateways Dashboard Navigate to **Actions** and click **Add New Provider Profile**. Sticky.io Add Provider ### Step 4: Configure Finix credentials in Sticky.io Enter your Finix credentials in the corresponding fields within the gateway provider profile. You can locate these details in your Finix Dashboard: Dashboard IDs - **Provider** - Select Finix as your gateway provider. - **Merchant ID** - Found in your Finix Dashboard under **Developer → Finix Integration → Merchant ID** - **Username** - The username associated with your Finix API Key created in Step 2 - **Password** - The password associated with your Finix API Key created in Step 2 Sticky.io Gateway Setup In the **Merchant Account Details** section, you can set additional merchant details such as a payment descriptor, website URL, and cancellation URL. Sticky.io Gateway Merchant Account Details In the **Limits & Fees** section, you can configure transaction limits and fees for this gateway profile. Sticky.io Gateway Limits & Fees To learn more about sticky.io, visit the [sticky.io Support Center](https://support.sticky.io). ## Searching for transactions on the Finix Dashboard You can locate payments using the Finix Transaction ID visible in sticky.io order details. In your sticky.io dashboard, navigate to **Customers → Orders** in the top navigation menu to view all orders. Sticky.io Orders Page Click on an order to open the order detail view and locate the **Finix Transaction ID**. Sticky.io transaction example Then, in the Finix Dashboard, either search or filter by transaction ID: Filter Transaction 1. Navigate to the Payments list page. 2. Click on the Filters → Search by ID. 3. In the Payment ID field, filter by the Finix Transaction ID copied from the sticky.io order detail view. --- # Tagada Source: https://docs.finix.com/additional-resources/plugins/tagada-plugin Accept payments with Finix on [Tagada](https://tagadapay.com/). Finix for Tagada ## Finix for Tagada overview TagadaPay is a payment orchestration and commerce platform that helps merchants accept, manage, and track payments across multiple channels through a unified interface. It enables businesses to monitor transactions, configure payment flows, and access detailed reporting while building scalable and modern commerce systems. Connecting Finix to TagadaPay allows merchants to process payments using Finix’s payments infrastructure directly within the Tagada platform. ### Finix requirements - Finix Sandbox Account to process Sandbox transactions. You will not be able to move real money in this environment. - Finix Live Account to run card or ACH transactions. ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create API keys API Environments API Keys are specific to either the Sandbox or Live environments, depending on whether you get them from the Sandbox or Live Dashboard. Sandbox Keys cannot be used in the Live Environment and vice-versa. [Learn more here](/api/section/environments). To create an API Key: 1. Navigate to **Developers → API Keys** in the Finix dashboard. 2. Click **Create API Key** and enter a **Display Name**. 3. Save the credentials somewhere secure. Store API Keys Securely Save your password somewhere secure. You **cannot** re-copy the password, but you can always create another API Key. API Keys are sensitive data and must be treated like passwords. Store them securely and only share them on an as-needed basis. To learn more see our [API Keys](/additional-resources/developers/authentication-and-api-basics/api-keys) documentation. ### Step 3: Connect with Tagada In the Tagada Dashboard, navigate to Payment Flows from the left sidebar. Click + Add Processor in the top-right corner. Add Processor Search for and select Finix as the processor, then click Next at the bottom of the page. Activate Finix ### Step 4: Configure Finix credentials in Tagada Enter your Finix credentials in the corresponding fields within the Tagada gateway profile. You can locate these details in your Finix Dashboard: Dashboard IDs - Name: Enter the processor name. - Currency Settings: Select all currencies supported by this merchant and the processing capacity. - Finix API Settings: - Merchant ID: Available in your Finix Dashboard under Developer → Finix Integration → Merchant ID - API Username: The username associated with your Finix API Key created in Step 2 - API Password: The password associated with your Finix API Key created in Step 2 - Use Sandbox Mode: Enable this option when testing with a sandbox merchant account. - Webhook Settings: Enter the URL endpoint to receive webhook event notifications. Tagada Gateway Profile These credentials allow Tagada to securely connect to your Finix account for payment processing. To learn more about Tagada, visit [TagadaPay Documentation](https://docs.tagadapay.com/). ## Searching for transactions on the Finix Dashboard You can locate payments using the Payment ID in the Finix Dashboard. In the Tagada Dashboard, navigate to Payments from the left sidebar to view all payments. Select a payment view the payment details. Tagada Dashboard Then, in the Finix Dashboard filter by Tag Value: Filter Transaction 1. Navigate to the Payments list page. 2. Click on the Filters. 3. Under **Tags**, enter the payment ID copied from Tagada Dashboard. 4. Click **Apply**. --- # Vindicia Source: https://docs.finix.com/additional-resources/plugins/vindicia-integration Accept payments with Finix on [Vindicia](https://www.vindicia.com). Vindicia ## Vindicia overview Vindicia, part of Amdocs, is an AI-driven subscription billing and payment recovery platform that has processed over 1.8 billion transactions for subscription businesses worldwide. It provides end-to-end tools for recurring billing, involuntary churn reduction, revenue recovery, and subscriber analytics — making it a trusted choice for media, streaming, SaaS, and digital services companies managing large subscriber bases. Finix integrates with Vindicia through the Cybersource payment gateway, enabling merchants to process payments and reconcile transaction data within their Vindicia environment. ### Finix requirements - Finix Live Account - Active Vindicia account ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports Vindicia via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure Vindicia: - **Merchant ID** (also called Organization ID) - **REST API Key** Cybersource Key Management ### Step 3: Configure Cybersource in Vindicia Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Cybersource credentials from Step 2 - Active Vindicia Subscribe or Vindicia Retain account Vindicia and Cybersource offer a pre-integrated joint solution for subscription billing and payment recovery. Vindicia Subscribe handles recurring billing and subscriber lifecycle management, while Vindicia Retain uses AI-driven recovery to reduce failed payment churn. For full configuration details, refer to the [Vindicia + Cybersource partner datasheet](https://vindicia.com/resources/datasheets/vindicia-and-cybersource-partner-solution/) or contact your Vindicia account team. Enabling the Cybersource connection in Vindicia is managed through your Vindicia account team and is not self-serve. Reach out to Vindicia Client Services to initiate the setup. In your Vindicia admin, configure the Cybersource payment processor with the following credentials from Step 2: - **Merchant ID** - your Cybersource Organization ID - **REST API Key ID** - your REST Key ID - **REST API Shared Secret** - your REST Shared Secret Select **Test** for sandbox or **Production** for live payments, then save the configuration. After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Vindicia transactions When you run a transaction on Vindicia, you'll see it: - In your Vindicia admin under **Transactions**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # VTEX Source: https://docs.finix.com/additional-resources/plugins/vtex-integration Accept payments with Finix on [VTEX](https://vtex.com). VTEX ## VTEX overview VTEX is a global composable commerce platform built for enterprise retail. It provides a unified suite of tools spanning storefront, order management, marketplace, and fulfillment — enabling brands to deliver consistent commerce experiences across digital and physical channels. Serving over 3,200 enterprise customers, with especially strong adoption in Latin America, VTEX is trusted by some of the world's leading brands for complex B2C and B2B operations. Finix integrates with VTEX through the Cybersource payment gateway, enabling merchants to process payments and reconcile transaction data within their VTEX environment. ### Finix requirements - Finix Live Account - Active VTEX account ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports VTEX via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure VTEX: - **Merchant ID** - **REST API Key** Cybersource Key Management ### Step 3: Install the Cybersource apps in VTEX Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Cybersource credentials from Step 2 - Administrator access to your VTEX account - VTEX IO CLI installed For full installation details, refer to the [VTEX Cybersource Gateway setup guide](https://help.vtex.com/docs/tutorials/setting-up-cybersource-gateway). Using the VTEX IO CLI, install the following required Cybersource apps: - `vtex.cybersource-ui` - `vtex.cybersource` - `vtex.cybersource-payer-auth` ### Step 4: Configure the Cybersource app In your VTEX Admin, navigate to **Apps → Installed Apps → Cybersource** and enter the following: - **Merchant ID** - your Cybersource Merchant ID from Step 2 - **Merchant Key** - your REST Shared Secret Key ID from Step 2 - **Shared Secret Key** - your REST Shared Secret from Step 2 - **Processor** - select your processor - **Region** - select your region VTEX Cybersource App Configuration ### Step 5: Configure the gateway provider and payment conditions 1. In your VTEX Admin, navigate to **Store Settings → Payment → Providers**. 2. Click **New Provider**, search for, and select **Cybersource IO**. Leave the **App key** and **App token** fields blank on this screen. Also leave **Merchant ID**, **Merchant Key**, and **Shared Secret Key** blank here — these are configured in the app settings in Step 4, not the provider screen. 1. Configure **Capture Setting** and **Payer Authentication** options as needed, then save. 2. Navigate to **Store Settings → Payment → Settings**. 3. Click **+** under **Payment Conditions**, select your credit card type, and enter a condition name. 4. Set **Process with provider** to **Cybersource - IO** and activate the condition. 5. Save the configuration. After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## VTEX transactions When you run a transaction on VTEX, you'll see it: - In your VTEX Admin under **Orders → All orders**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # WooCommerce Source: https://docs.finix.com/additional-resources/plugins/woocommerce-plugin Accept payments with Finix on your WooCommerce Store Finix for Woocommerce ## Finix for WooCommerce overview Download Finix for WooCommerce Accept Card and Bank Payments with WooCommerce. View Sample Site View a demo of our plugin at finixsamplewoo.com The Finix plugin for WooCommerce lets you accept payments and manage orders directly from your WordPress admin. - **Payment methods:** Credit and debit cards, Apple Pay, Google Pay, and bank transfers (ACH). - **Pricing:** Interchange-plus pricing with itemized fee breakdowns. - **Blocks checkout:** Compatible with WooCommerce's block-based checkout and the classic checkout flow. - **Dispute and bank return handling:** Order statuses update automatically via webhooks when disputes or bank returns occur. - **Sandbox environment:** Test your integration before going live. ### Download Finix for WooCommerce is available for [download at wordpress.org](https://wordpress.org/plugins/finix-for-woocommerce/). ### Finix requirements - Finix Sandbox Account to process Sandbox transactions. You will not be able to move real money in this environment. - Finix Live Account to run card or ACH transactions. ### Apple Pay requirements Apple Pay requires domain verification, which involves hosting a file in the `/.well-known/` directory of your site. Whether this is supported depends on your WordPress hosting plan. | Platform | Can Host Verification File? | Notes | | --- | --- | --- | | WordPress.org (self-hosted) | Yes | Full server access to place files in `/.well-known/` | | WordPress.com Business/Commerce plan | Yes | Allows plugins and some server-level access | | WordPress.com Free/Personal/Premium | No | No access to server file system; cannot place arbitrary files at custom paths | ## Before you begin Keep your existing payment gateway enabled while you install and configure Finix. After you have configured and verified Finix in Production, disable the old gateway if you do not want to present multiple payment options. To disable an existing payment gateway: 1. In your WordPress admin, go to **WooCommerce** → **Settings** → **Payments**. 2. Find the gateway you want to remove and toggle it off. ## Installation The steps below are split into two tabs - **Sandbox** and **Production**. If you want to test your setup before going live, start with **Sandbox**. Once you are approved and ready to accept real payments, follow the **Production** tab. - **Sandbox**: A test environment where no real money is moved. Use this to verify your integration before launch. - **Production**: Your live environment that processes real transactions with real customers. ### Step 1. Download Finix for WooCommerce plugin Download Finix for WooCommerce Accept Card and Bank Payments with WooCommerce. ### Step 2. Install Finix for WooCommerce plugin Add new plugin 1. In your WordPress admin, click **Plugins** → **Add New Plugin**. 2. Click **Upload Plugin**. 3. Click **Choose File**, select the downloaded plugin file, and click **Install Now**. 4. Click **Activate Plugin**. ### Step 3. Configure for your environment Sandbox #### Step 3a. Sign up for a Finix Sandbox account To create a Sandbox account, read our [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly. We recommend choosing **Direct Merchant** as your Customer Type. #### Step 3b. Open the Finix plugin settings and select Sandbox WooCommerce Payments settings 1. In your WordPress admin, go to **WooCommerce** → **Settings**. 2. Click the **Payments** tab. 3. Find **Finix Gateway** in the list and click **Manage**. 4. Locate the **Environment** dropdown and select **Sandbox**. #### Step 3c. Configure your webhook A **webhook** is an automated notification that Finix sends to your WooCommerce store when an event occurs - for example, when a payment is processed or a dispute is opened. Setting up a webhook keeps your order statuses in sync automatically. ##### Part 1: Get webhook details from the plugin Webhook configuration In the Finix plugin settings, scroll down to the webhook section. Note the **Webhook URL**, **Username**, and **Password** - you will need these in the next step. ##### Part 2: Create a webhook in the Finix Dashboard 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login). 2. Select the **Sandbox** environment from the environment selector. Finix automatically selects your environment if you only have access to one. 3. Click **Developer** in the left menu. 4. Click the **Webhooks** tab. 5. Click **Create Webhook**. 6. Enter the **URL**, **Username**, and **Password** from Part 1. Set **Authentication Type** to `Basic`. Add a nickname to identify this webhook later. 7. Go to **Events** and select **Only the following entities and types**. 8. Check **Transfer** and **Disputes** for both **created** and **updated**, then save the webhook. #### Step 3d: Enter your Sandbox credentials **API keys** are unique credentials that let the Finix plugin securely communicate with Finix on your behalf. In the Finix Dashboard, go to the **Developer** page. You will find: - **Application ID**: starts with `AP` - **Merchant ID**: starts with `MU` Enter both values in the Finix plugin settings. To generate API keys: 1. On the **Developer** page, click **Create API Key**. 2. Copy the **Username** and **Password** and enter them in the Finix plugin settings. #### Step 3e. Enable payment methods With your credentials saved, enable the Finix Gateway. Your customers will now see Finix as a payment option at checkout. **Credit card payment is enabled by default.** Apple Pay, Google Pay, and bank transfer are available but disabled. You can enable them in their respective tabs within the plugin settings if you want to offer them. Because WooCommerce already collects billing and shipping information during checkout, your customers will not be asked to re-enter their billing details in the Finix payment form. Production #### Step 3a. Get approved for a Finix Live account Contact Finix or log in to the Finix Dashboard to complete your live account application. Once approved, you will receive Production credentials. #### Step 3b. Open the Finix plugin settings and select Production WooCommerce Payments settings 1. In your WordPress admin, go to **WooCommerce** → **Settings**. 2. Click the **Payments** tab. 3. Find **Finix Gateway** in the list and click **Manage**. 4. Locate the **Environment** dropdown and select **Production**. #### Step 3c. Configure your Production webhook A **webhook** is an automated notification that Finix sends to your WooCommerce store when an event occurs - for example, when a payment is processed or a dispute is opened. Setting up a webhook keeps your order statuses in sync automatically. ##### Part 1: Get Production webhook details from the plugin Webhook configuration In the Finix plugin settings, scroll down to the webhook section. Note the **Webhook URL**, **Username**, and **Password** - you will need these in the next step. ##### Part 2: Create a Production webhook in the Finix Dashboard 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login). 2. Select the **Production** environment from the environment selector. 3. Click **Developer** in the left menu. 4. Click the **Webhooks** tab. 5. Click **Create Webhook**. 6. Enter the **URL**, **Username**, and **Password** from Part 1. Set **Authentication Type** to `Basic`. Add a nickname to identify this webhook later. 7. Go to **Events** and select **Only the following entities and types**. 8. Check **Transfer** and **Disputes** for both **created** and **updated**, then save the webhook. #### Step 3d: Enter your Production credentials **API keys** are unique credentials that let the Finix plugin securely communicate with Finix on your behalf. In the Finix Dashboard, go to the **Developer** page. You will find: - **Application ID**: starts with `AP` - **Merchant ID**: starts with `MU` Enter both values in the Finix plugin settings. To generate API keys: 1. On the **Developer** page, click **Create API Key**. 2. Copy the **Username** and **Password** and enter them in the Finix plugin settings. #### Step 3e. Activate Production payment methods With your credentials saved, enable the Finix Gateway. Your customers will now see Finix as a payment option at checkout. **Credit card payment is enabled by default.** Apple Pay, Google Pay, and bank transfer are available but disabled. You can enable them in their respective tabs within the plugin settings if you want to offer them. Because WooCommerce already collects billing and shipping information during checkout, your customers will not be asked to re-enter their billing details in the Finix payment form. ## Set up Apple Pay ### Step 1. Enable Apple Pay in WooCommerce 1. Navigate to the **Apple Pay** tab in the Finix plugin settings. 2. Select **Enable Apple Pay Gateway**. 3. Customize your Apple Pay button style and type to match your storefront. Add Web Domain modal with the verification file download ### Step 2. Register your domain Before you can accept Apple Pay, verify and register your domain with Apple. You complete this step in the Finix Dashboard. After you register the domain, download the verification file and host it on your website. To register your domain: 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login) and click **Developer**. 2. Click the **Alt Payment Methods** tab. 3. Click **Add Web Domain** and follow the instructions to host the verification file. Add Web Domain modal with the verification file download Do not close the modal until you have hosted the verification file Do not click **Submit** on step 3 in the modal until you have uploaded the verification file that Finix generates in the steps below. 1. Enter a domain name. Add Web Domain modal with the verification file download 1. Download the verification file. Add Web Domain modal with the verification file download 1. Host the verification file at `/.well-known/apple-developer-merchantid-domain-association`. Add Web Domain modal with the verification file download ## Set up Google Pay ### Step 1. Enable Google Pay in WooCommerce 1. Navigate to the **Google Pay** tab in the Finix plugin settings. 2. Select **Enable Google Pay Gateway**. 3. Customize your Google Pay button style and type to match your storefront. Add Web Domain modal with the verification file download ### Step 2. Register with Google Business Console To accept Google Pay, you need a Google Merchant ID from the [Google Pay & Wallet Console](https://pay.google.com/business/console). 1. Sign in to the [Google Pay & Wallet Console](https://pay.google.com/business/console). 2. Complete the business profile and agree to the Google Pay API Terms of Service. 3. Once approved, copy your **Google Merchant ID**. 4. Enter your Google Merchant ID in the Finix plugin settings. ## Searching for transactions on the Finix Dashboard Filter by Order ID You can find Payments using WooCommerce Order Ids on the Finix Dashboard. 1. Navigate to the Payments list page. 2. Click on the **Filters**. 3. Under **Tags**, enter WooCommerce Order Id. 4. Click **Apply**. --- # Zuora Source: https://docs.finix.com/additional-resources/plugins/zuora-integration Accept payments with Finix on [Zuora](https://www.zuora.com). Zuora ## Zuora overview Zuora is the leading subscription management platform, helping businesses launch, manage, and scale recurring revenue models. It handles the full quote-to-cash lifecycle, from product catalog and pricing to invoicing, collections, and revenue recognition. Finix integrates with Zuora through the Cybersource payment gateway, enabling merchants to process payments and automatically reconcile transaction data within their Zuora billing environment. ### Finix requirements - Finix Live Account - Active Zuora tenant ## Integration ### Step 1: Sign up for a Finix account To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account. We recommend choosing Direct Merchant as your Customer Type. ### Step 2: Create a Cybersource gateway integration Cybersource Integration Finix supports Zuora via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration. For more information, please reach out to your Finix point of contact. 1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard. 2. Sign up for Cybersource. For detailed instructions, see the [Cybersource integration guide](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard). 3. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure Zuora: - **Merchant ID** (also called Organization ID) - **REST API Key** Cybersource Key Management ### Step 3: Set up your Zuora tenant Before proceeding, ensure your Zuora environment is ready: - Active Zuora tenant with Payments enabled - Administrator access to **Settings → Payments** - Cybersource gateway integration enabled for your tenant (contact your Zuora account team if not already enabled) ### Step 4: Configure the Cybersource payment gateway Before you proceed, ensure you have: - Approved Finix Merchant Account - Cybersource Gateway Integration linked to your Finix Merchant Account - Cybersource credentials from Step 2 In your Zuora admin, navigate to **Settings → Payments → Setup Payment Gateway** and select **CyberSource** (use **CyberSource Tokenization** if you plan to store and reuse payment methods). Enter the following credentials from your Finix-provisioned Cybersource account: - **Merchant ID** - your Cybersource Organization ID - **Security Key** - for CyberSource Payment API v2.0, copy the REST API key content from the Cybersource Business Center and paste it into this field - **Use Gateway Test Environment** - check this for sandbox testing; uncheck for production Save the gateway instance and assign it to the relevant Zuora billing entity. After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration. To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource). If you need additional assistance contact [support@finix.com](mailto:support@finix.com). ## Zuora transactions When you run a transaction on Zuora, you'll see it: - In your Zuora admin under **Payments → Transactions**. - In the Cybersource Business Center. - In your Finix Dashboard under **Transactions** → **Payments**. These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, see [how to locate Cybersource transactions](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions). --- # Motor Vehicle Rental Source: https://docs.finix.com/guides/industry-considerations/auto-rental Motor vehicle rental merchants operating under eligible MCCs can include rental-specific details directly on their transactions, such as pickup location, return date, and agreement number. Submitting this data qualifies transactions for lower interchange rates and helps avoid downgrades to costlier interchange tiers. ## Requirements - Your business must operate under an [eligible MCC](#eligible-mccs-for-motor-vehicle-rental-data). - Transactions must be captured within two days. ### Eligible MCCs for motor vehicle rental data | MCC | Description | | --- | --- | | 3351–3500 | Automobile/vehicle rentals | | 7512 | Automobile rental agency | | 7513 | Truck and utility trailer rentals | | 7519 | Motor home and recreational vehicle rentals | ## Motor vehicle rental data fields The following fields are available under the `additional_motor_vehicle_rental_data` object on both `Authorization` and `Transfer` resources. All fields are optional for motor vehicle rental MCC transactions. | Field | Description | Data Type | | --- | --- | --- | | `additional_motor_vehicle_rental_data` | Nested object containing all motor vehicle rental-specific fields. Optional for motor vehicle rental MCC transactions (MCC 3351–3500, 7512). Null for all other transactions. | Object | | `motor_vehicle_rental_agreement_number` | The rental agreement or contract reference number for the rental. Max 9 characters; longer values are truncated. | String | | `customer_service_number` | The phone number customers can call for support or inquiries related to their rental. | String | | `extra_charge_details` | Additional charges beyond the base rental rate being billed. Each field represents a specific charge type, in cents. | Object | | `extra_charge_details.one_way_service_fee_amount` | The amount of the additional charge, in cents. | Integer | | `extra_charge_details.fuel_amount` | The amount of the additional charge, in cents. | Integer | | `extra_charge_details.extra_mileage_amount` | The amount of the additional charge, in cents. | Integer | | `extra_charge_details.late_return_amount` | The amount of the additional charge, in cents. | Integer | | `extra_charge_details.parking_violation_amount` | The amount of the additional charge, in cents. | Integer | | `extra_charge_details.insurance_amount` | The amount of the additional charge, in cents. | Integer | | `is_no_show` | An indicator that the cardholder is being billed for a reserved vehicle that was not actually rented (that is, a "no-show" charge). | Boolean | | `number_of_days` | The total number of days for the vehicle rental. | Integer | | `pickup_address` | The full address of the rental pickup location. | Object | | `pickup_date` | The scheduled vehicle pickup date. | Object | | `return_address` | The full address of the vehicle return location. | Object | | `return_date` | The scheduled vehicle return date. Must be on or after `pickup_date`. | Object | ## Motor vehicle rental transaction flow using the API Once you have a buyer `Identity` and `Payment Instrument`, include the `additional_motor_vehicle_rental_data` object in your request to pass rental details. ### Create an Authorization with motor vehicle rental data Include the `additional_motor_vehicle_rental_data` object in the request body to pass rental details at authorization time: Example API Definition `additional_motor_vehicle_rental_data` is **not** required at capture time (`PUT /authorizations/{id}`). The motor vehicle rental data is automatically inherited from the original `Authorization`. #### Authorization response ```json { "id": "AUmFm6HiHMHr9EsYpbEA4Uhi", "created_at": "2026-06-25T23:08:46.46Z", "updated_at": "2026-06-25T23:08:46.46Z", "amount": 35000, "amount_requested": 35000, "currency": "USD", "state": "SUCCEEDED", "failure_code": null, "failure_message": null, "additional_motor_vehicle_rental_data": { "motor_vehicle_rental_agreement_number": "RENT1xxxx", "customer_service_number": "8005551234", "extra_charge_details": { "one_way_service_fee_amount": 5000 }, "is_no_show": false, "number_of_days": 4, "pickup_address": { "line1": "123 Market St", "line2": null, "city": "San Francisco", "region": "CA", "postal_code": "94105", "country": "USA" }, "pickup_date": { "month": 4, "day": 1, "year": 2026 }, "rental_rate": "7500", "renter_name": "John Smith", "return_address": { "line1": "456 Hollywood Blvd", "line2": "Suite 100", "city": "Los Angeles", "region": "CA", "postal_code": "90028", "country": "USA" }, "return_date": { "month": 4, "day": 4, "year": 2026 } }, "additional_purchase_data": null, "additional_healthcare_data": null, "additional_lodging_data": null, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "expires_at": "2026-07-02T23:08:46.46Z", "is_void": false, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "network_details": { "brand": "VISA", "authorization_code": "978203" }, "source": "PIkxmtueemLD6dN9ZoWGHT44", "tags": { "order_number": "RENTAL-2026-001" }, "trace_id": "f30f3eed-447a-4cfd-b961-8a2c00809829", "transfer": null, "void_state": "UNATTEMPTED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUmFm6HiHMHr9EsYpbEA4Uhi" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" } } } ``` ### Create a Transfer with motor vehicle rental data Visa cards qualify for lower interchange rates only when using the authorization and capture flow. If you submit a `Transfer` (e.g. Sale) with Visa, the transaction will not receive the reduced interchange rate. The same `additional_motor_vehicle_rental_data` object is supported on direct `Transfer` creation: Example API Definition #### Transfer response ```json { "id": "TRtcWvZT9EGKDLnTuhHdV7zu", "created_at": "2026-06-25T23:09:04.61Z", "updated_at": "2026-06-25T23:09:04.61Z", "amount": 35000, "amount_requested": 35000, "currency": "USD", "state": "SUCCEEDED", "type": "DEBIT", "failure_code": null, "failure_message": null, "additional_motor_vehicle_rental_data": { "motor_vehicle_rental_agreement_number": "RENT1xxxx", "customer_service_number": "8005551234", "extra_charge_details": { "one_way_service_fee_amount": 5000 }, "is_no_show": false, "number_of_days": 4, "pickup_address": { "line1": "123 Market St", "line2": null, "city": "San Francisco", "region": "CA", "postal_code": "94105", "country": "USA" }, "pickup_date": { "month": 4, "day": 1, "year": 2026 }, "rental_rate": "7500", "renter_name": "John Smith", "return_address": { "line1": "456 Hollywood Blvd", "line2": "Suite 100", "city": "Los Angeles", "region": "CA", "postal_code": "90028", "country": "USA" }, "return_date": { "month": 4, "day": 4, "year": 2026 } }, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "fee": 0, "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj", "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "network_details": { "brand": "VISA", "authorization_code": "601883", "acquirer_reference_number": null }, "operation_key": "CARD_NOT_PRESENT_SALE", "ready_to_settle_at": "2026-06-26T23:09:04.61Z", "source": "PIkxmtueemLD6dN9ZoWGHT44", "statement_descriptor": "FLX*FINIX FLOWERS", "tags": {}, "trace_id": "c589c75f-3293-436f-88e0-3d3cd4a6195c", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtcWvZT9EGKDLnTuhHdV7zu" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtcWvZT9EGKDLnTuhHdV7zu/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtcWvZT9EGKDLnTuhHdV7zu/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRtcWvZT9EGKDLnTuhHdV7zu" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtcWvZT9EGKDLnTuhHdV7zu/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkxmtueemLD6dN9ZoWGHT44" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj" } } } ``` --- # Gaming Source: https://docs.finix.com/guides/industry-considerations/gaming Some industries need extra steps for compliance and smooth payment processing. Check these requirements before you integrate gaming merchants. ## Required fields for a gaming transaction Card networks require gaming MCC (7994 and 5816) transactions to include extra data for compliance. Here are the four required fields: 1. **IP Address:** A new field required when creating `Authorizations` and `Transfers` 2. **Email:** Existing optional field on the `Buyer Identity` will now be required 3. **Phone number:** Existing optional field on the `Buyer Identity` will now be required 4. **Name:** Existing optional field on the `Payment Instrument` will now be required If your app includes a merchant with MCC 7994 or 5816, all merchants must provide the four required fields. Finix will block any transactions missing these fields before they reach the card networks to keep you compliant. ## Operational requirements Once your account is approved, there are additional steps to register it with the card networks. Finix completes this registration process on your behalf and passes through the associated costs, which include both an initial registration fee and an annual renewal fee. Please contact your Customer Delivery Manager if you’d like more details or have any questions. ## Gaming transaction flow using the API Follow these steps to process a compliant gaming transaction from buyer setup to payment completion. ### 1. Create a Buyer Identity Begin by creating a buyer identity and include the required fields for gaming: - `entity.​email` - `entity.​phone` Example API Definition If your request is successful, you’ll receive a `201 Created` status code and the buyer’s `Identity` in the response. Save the `id` for your next step. ### 2. Create a Buyer Payment Instrument Now, use the buyer’s `Identity` ID to create their `Payment Instrument`. Make sure to include the required `name` field in the request body: Example API Definition If your request works, you’ll get a `201 Created` status code and the buyer’s `Payment Instrument` in the response. Save the `id` for your next step. ### 3A. creating a Transfer with required gaming fields After you’ve created the buyer `Identity` and `Payment Instrument` with the required fields, you can create a `Transfer`. To make it valid for gaming, include the `ip_address_v4` in the request body: Example API Definition ### 3B. creating an Authorization with required gaming fields Just like with transfers, include the `ip_address_v4` in the request body to make the `Authorization` valid for gaming: Example API Definition --- # Industry Considerations Source: https://docs.finix.com/guides/industry-considerations Some Merchant Category Codes (MCCs) have their own setup steps, such as special registrations, additional data fields, or unique card network rules. If you follow these requirements, your integration will work smoothly and remain compliant, whether you are onboarding a gaming merchant or ensuring your API setup meets network rules. ## Industry-Specific guidance Gaming Learn the requirements for supporting gaming merchants as you build your integration. Motor Vehicle Rental Learn the requirements for supporting motor vehicle rental merchants as you build your integration. Lodging Learn the requirements for supporting lodging merchants as you build your integration. --- # Lodging Source: https://docs.finix.com/guides/industry-considerations/lodging Lodging merchants operating under travel-related MCCs can pass enhanced stay details alongside their transactions, including check-in and check-out dates. Sending this data helps optimize interchange rates across all major card networks and prevents downgrades to higher commercial standard rates. ## Requirements - Your business must operate under an [eligible MCC](#eligible-mccs-for-lodging-data). - Transactions must be captured within two days. ### Eligible MCCs for lodging data | MCC | Description | | --- | --- | | 3501–3999 | Hotels and motel chains | | 7011 | Lodging - hotels, motels, and resorts | ## Lodging data fields The following fields are available under the `additional_lodging_data` object on both `Authorization` and `Transfer` resources. All fields are optional for lodging MCC transactions. | Field | Description | Data Type | | --- | --- | --- | | `additional_lodging_data` | Nested object containing all lodging-specific fields. Returns `null` for non-lodging MCCs. | Object | | `check_in_date` | The guest's scheduled arrival date. | Object | | `check_out_date` | The guest's scheduled departure date. Must represent a date on or after `check_in_date`. | Object | | `customer_service_phone` | The phone number guests can call for support or inquiries related to their stay. | String | | `extra_charge_details` | Additional charges billed beyond the room rate. Each field represents a specific charge type, in cents. | Object | | `extra_charge_details.restaurant_amount` | The amount of the additional charge, in cents. | Integer | | `extra_charge_details.mini_bar_amount` | The amount of the additional charge, in cents. | Integer | | `extra_charge_details.laundry_amount` | The amount of the additional charge, in cents. | Integer | | `extra_charge_details.other_amount` | The amount of the additional charge, in cents. | Integer | | `extra_charge_details.phone_amount` | The amount of the additional charge, in cents. | Integer | | `extra_charge_details.gift_shop_amount` | The amount of the additional charge, in cents. | Integer | | `hotel_agreement_number` | The folio or agreement number associated with the reservation. Max 12 characters; longer values are truncated. | String | | `is_advance_deposit` | Indicates whether the lodging charge is an advance deposit. | Boolean | | `is_no_show` | Set to `true` if the cardholder is being billed for a reserved room that was not occupied. | Boolean | | `number_of_nights` | The total number of nights for the lodging stay. | Integer | | `property_phone` | The direct phone number of the lodging property. | String | | `room_rate` | The nightly room rate, in cents. | String | | `room_tax` | The tax amount applied to the room rate, in cents. | String | ## Lodging transaction flow using the API Once you have a buyer `Identity` and `Payment Instrument`, include the `additional_lodging_data` object in your request to pass stay details. ### Create an Authorization with lodging data Include the `additional_lodging_data` object in the request body to pass stay details at authorization time: Example API Definition `additional_lodging_data` is **not** required at capture time (`PUT /authorizations/{id}`). The lodging data is automatically inherited from the original `Authorization`. #### Authorization response ```json { "id": "AUwv72KC1ZG2BKS9zCoVgSG4", "created_at": "2026-06-25T23:08:50.93Z", "updated_at": "2026-06-25T23:08:50.93Z", "amount": 45000, "amount_requested": 45000, "currency": "USD", "state": "SUCCEEDED", "failure_code": null, "failure_message": null, "additional_lodging_data": { "check_in_date": { "month": 4, "day": 1, "year": 2026 }, "check_out_date": { "month": 4, "day": 5, "year": 2026 }, "customer_service_phone": "8005551234", "extra_charge_details": { "mini_bar_amount": 500 }, "hotel_agreement_number": "HTL98765", "is_advance_deposit": false, "is_no_show": false, "number_of_nights": 4, "property_phone": "4155559876", "room_rate": "10000", "room_tax": "1500" }, "additional_purchase_data": null, "additional_healthcare_data": null, "additional_motor_vehicle_rental_data": null, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "expires_at": "2026-07-02T23:08:50.93Z", "is_void": false, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "network_details": { "brand": "VISA", "authorization_code": "664979" }, "source": "PIkxmtueemLD6dN9ZoWGHT44", "tags": { "order_number": "HOTEL-2026-001" }, "trace_id": "7354286f-b769-491e-9e4e-9353af0a4f4f", "transfer": null, "void_state": "UNATTEMPTED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUwv72KC1ZG2BKS9zCoVgSG4" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" } } } ``` ### Create a Transfer with lodging data Visa cards qualify for lower interchange rates only when using the authorization and capture flow. If you submit a `Transfer` (e.g. Sale) with Visa, the transaction will not receive the reduced interchange rate. The same `additional_lodging_data` object is supported on direct `Transfer` creation: Example API Definition #### Transfer response ```json { "id": "TRtxRnYL2jveAWBSPrKZPJ15", "created_at": "2026-06-25T23:09:09.28Z", "updated_at": "2026-06-25T23:09:09.28Z", "amount": 45000, "amount_requested": 45000, "currency": "USD", "state": "SUCCEEDED", "type": "DEBIT", "failure_code": null, "failure_message": null, "additional_lodging_data": { "check_in_date": { "month": 4, "day": 1, "year": 2026 }, "check_out_date": { "month": 4, "day": 5, "year": 2026 }, "customer_service_phone": "8005551234", "extra_charge_details": { "mini_bar_amount": 500 }, "hotel_agreement_number": "HTL98765", "is_advance_deposit": false, "is_no_show": false, "number_of_nights": 4, "property_phone": "4155559876", "room_rate": "10000", "room_tax": "1500" }, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "fee": 0, "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj", "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "network_details": { "brand": "VISA", "authorization_code": "999048", "acquirer_reference_number": null }, "operation_key": "CARD_NOT_PRESENT_SALE", "ready_to_settle_at": "2026-06-26T23:09:09.28Z", "source": "PIkxmtueemLD6dN9ZoWGHT44", "statement_descriptor": "FLX*FINIX FLOWERS", "tags": { "order_number": "HOTEL-2026-001" }, "trace_id": "05efc73f-8ad4-47d7-8bd3-e67a3b0fdafe", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtxRnYL2jveAWBSPrKZPJ15" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtxRnYL2jveAWBSPrKZPJ15/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtxRnYL2jveAWBSPrKZPJ15/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRtxRnYL2jveAWBSPrKZPJ15" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtxRnYL2jveAWBSPrKZPJ15/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkxmtueemLD6dN9ZoWGHT44" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj" } } } ``` --- # Canada Source: https://docs.finix.com/guides/regional-considerations/canada This guide outlines how Finix supports payments in Canada and what you need to know when building integrations for Canadian merchants. Finix Canada ## Payments overview Finix supports Interac, Visa, Mastercard, American Express, and Discover payments for Canadian merchants. All transactions must be processed in Canadian dollars (CAD). ## Online Payments You can use our existing API calls and low-code/no-code features in Canada. Finix's Payment Links, Checkout Forms, Subscriptions are supported for USA and CAN merchants. ## In-Person Payments **In Person Payments in Canada is currently in pilot and not generally available.** To participate in the pilot, you must reach out to [Finix Support](mailto:support@finix.com). ### Supported devices Finix currently supports the following two certified devices in Canada: - [**PAX A800**](/guides/in-person-payments/select-your-device/pax-a800) - [**PAX A920 Pro**](/guides/in-person-payments/select-your-device/pax-a920-pro) ### Cardholder language selection Cardholders can toggle between English and French on the terminal when processing a transaction. div div img div img div img ## Interac Payments Interac is the domestic debit network in Canada. Debit cards issued by Canadian banks typically display the Interac logo, even when co-branded with Visa or Mastercard. Regardless of co-branding, all Canadian debit transactions are routed through the Interac network when processed in Canada. Payment Instruments associated with Interac cards will have a `brand` value of `INTERAC`. You can find all potential values for the `brand` field in the [Payment Instrument API Reference](/api/payment-instruments/createpaymentinstrument#payment-instruments/createpaymentinstrument/t=response&c=201&path=&oneof=0/brand). Interac Payment Instruments can only be used for card-present transactions and do not support card-not-present transactions. ### Interac Sales All Interac payments must be submitted as sales and are authorized and captured in one request. Interac does not support multi-step authorization and capture flows. That means: - The `POST /authorizations` flow is not supported for Interac transactions. - Attempting to use `POST /authorizations` with an Interac card will return an error. Example response below Sample Response: ```json { "total": 1, "_embedded": { "errors": [ { "logref": "c5a343f2egf4f37b", "message": "Authorization AUhKLUbEwkVFfDECA9Aom71A was declined.", "code": "DECLINED", "failure_code": "TRANSACTION_NOT_PERMITTED", "failure_message": "The transaction was declined because the card or transaction type is not permitted. The cardholder needs to use a different type of card or attempt a different transaction method.", "_links": { "authorization": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUhKLUbEwkVFfDECA9Aom71A" }, "self": { "href": "https://finix.sandbox-payments-api.com/authorizations" } }, "authorization": "AUhKLUbEwkVFfDECA9Aom71A" } ] } } ``` ### Refunds for Interac transactions Refunds for Interac transactions must be performed **in person** using a supported terminal and the **same card** that was used in the original transaction. If the card is unavailable, merchants may offer store credit or cash as an alternative refund method. The following demonstrates how to initiate a refund on a Standalone Terminal, via API, or via the Finix Dashboard. Standalone On a Standalone Terminal, navigate to the transaction you wish to refund and select **Create Refund**. The terminal will prompt for the amount you wish to refund and for the card to be presented. div div img div img API The following example demonstrates how to initiate an Interac refund via API. #### Request ```bash curl -i -X POST \ -H 'Authorization: Basic xxxx' \ https://finix.sandbox-payments-api.com/transfers/TRnErBfrHLgdAi3BqAkWLN27/reversals \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "refund_amount": 500, "device": "DVsEanpBtsAVvCHbNXkFaH6f", "operation_key": "CARD_PRESENT_REFERENCED_REFUND", "tags": { "order_number": "test-interac-refund" } }' ``` #### Response ```json { "id": "TRqBvXgM7dKp2JtNwY4HnRZcs", "created_at": "2025-06-13T08:22:56.38Z", "updated_at": "2025-06-13T08:22:57.59Z", "amount": 500, "amount_requested": 500, "application": "APeUbTUjvYb1CdPXvNcwW1wP", "card_present_details": { "payment_type": "NONE" }, "currency": "CAD", "destination": "PIdk3BzKSmtMXAN42W6mvD3Y", "device": "DVsEanpBtsAVvCHbNXkFaH6f", "failure_code": null, "failure_message": null, "fee": 0, "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDsbTBawhnLBAVeinRb84vFR", "operation_key": "CARD_PRESENT_REFERENCED_REFUND", "state": "SUCCEEDED", "statement_descriptor": "FIN*FINIX FLOWERS", "subtype": "API", "tags": { "order_number": "test-interac-refund" }, "trace_id": "FNXoXopxGC9Bk8cwmiHRxBUaV", "type": "REVERSAL", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRqBvXgM7dKp2JtNwY4HnRZcs" }, "parent": { "href": "https://finix.sandbox-payments-api.com/transfers/TRnErBfrHLgdAi3BqAkWLN27" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR" }, "device": { "href": "https://finix.sandbox-payments-api.com/devices/DVsEanpBtsAVvCHbNXkFaH6f" }, "destination": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIdk3BzKSmtMXAN42W6mvD3Y" } } } ``` Dashboard To initiate a refund via the Finix Dashboard, navigate to the transaction you wish to refund and select **Issue Refund**. The dashboard will prompt for the amount you wish to refund and to select the device that will be used to process the refund. div div img ## Settlements Interac transactions are settled independently from other card networks. When a merchant processes both Interac and non-Interac transactions, Finix will generate **two separate settlements**: - One settlement for all Interac transactions - One settlement for all other card brands (such as Visa, Mastercard, and Discover) This separation ensures compliance with Interac’s clearing and settlement rules and helps merchants reconcile their payouts accurately by card network. ### Funding schedule The table below outlines funding timelines for sales created by Canadian merchants, based on when the sale is created (relative to the 7 PM PST cutoff) and the currency or card type used. | Card Type | Created Before 7 PM PST | Created After 7 PM PST | | --- | --- | --- | | Domestic Cards | 1 business day | 2 business days | | International Visa | 2 business days | 3 business days | | International Mastercard | 1 business day | 2 business days | --- # Regional Considerations Source: https://docs.finix.com/guides/regional-considerations As you expand your payments integration beyond the United States, it's important to understand that there may be regional differences to consider. Some countries may have different card network rules, supported devices, refund handling requirements, or settlement logic. Finix provides documentation and integration guidance tailored to each supported region so that you can adapt your implementation as needed. These guidelines help ensure your integration aligns with local network expectations and merchant needs—whether it's enabling Interac support in Canada or managing region-specific compliance requirements. ## Supported regions Canada Learn about Interac support, supported devices, and settlement differences for Canadian merchants. --- # New Dashboard Designs, Embedded Onboarding Forms, & Payout Settings Source: https://docs.finix.com/release-notes/2022/11/new-dashboard-designs-embedded-onboarding-forms-payout ![Release Notes](/assets/release-notes-2022-11-release-notes.ab9180184bda35e7f455282896776d4ec202e6dd5143aee3b7962f6c3b1cdcd8.08ff7529.png) - Thanks to the collective feedback from our customers about the Finix Dashboard, every page of the Finix Dashboard has been redesigned, focusing specifically on how content is organized, utilized by different teams (such as features catered to developers and to payment operations), and laid out for greater clarity, discoverability, and ease of use. This release kicked off the implementation of those designs. - Thanks to the collective feedback from our customers about the Finix Dashboard, every page of the Finix Dashboard has been redesigned, focusing specifically on how content is organized, utilized by different teams (such as features catered to developers and to payment operations), and laid out for greater clarity, discoverability, and ease of use. This release kicked off the implementation of those designs. - We’ve updated naming conventions to be more intuitive, for instance: “Transfers” that are buyer purchases are now called “Payments” in the dashboard. Payments now appear along with “Authorizations” and “Refunds” in the “Transactions” list in the left navigation bar of your dashboard. - We’ve better organized pages within each section of the dashboard, and added more filters so you can easily sort and report on information you want to see at any given time. These filters are also helpful to pull on-demand reports from the dashboard so that you don’t need to wait for settlement reports, which come at the end of the day and include full information, which may not be needed if your goal is to extract a finite set of information from a given time period. These reports can be found in your exports section of the dashboard–at the bottom left–so you can go back and reference them at any time. You can also download them as a CSV file. - We’ve better organized pages within each section of the dashboard, and added more filters so you can easily sort and report on information you want to see at any given time. These filters are also helpful to pull on-demand reports from the dashboard so that you don’t need to wait for settlement reports, which come at the end of the day and include full information, which may not be needed if your goal is to extract a finite set of information from a given time period. These reports can be found in your exports section of the dashboard–at the bottom left–so you can go back and reference them at any time. You can also download them as a CSV file. - Lastly, we improved the settlements experience with detailed page headers that showcase the payout type of a given transaction (such as net versus gross payout type). - Lastly, we improved the settlements experience with detailed page headers that showcase the payout type of a given transaction (such as net versus gross payout type). - We released an entirely new suite of payment terminals for [In-Person Payments](/guides/in-person-payments) including the addition of new Finix Mobile SDKs and new Finix APIs so that you can choose the software and hardware pairing that works best for your business. - We released an entirely new suite of payment terminals for [In-Person Payments](/guides/in-person-payments) including the addition of new Finix Mobile SDKs and new Finix APIs so that you can choose the software and hardware pairing that works best for your business. - You can now white label using your own branding with Finix! - You can now [white-label, or customize](/guides/managing-operations/finix-dashboard) your dashboard, your merchants’ dashboards, and embedded merchant onboarding forms using your own company branding - including your company logo and colors. - White labeling creates a consistent user experience for your merchants which can lead to increased trust and translate to a higher willingness to complete onboarding more quickly. - You can now white label using your own branding with Finix! - You can now [white-label, or customize](/guides/managing-operations/finix-dashboard) your dashboard, your merchants’ dashboards, and embedded merchant onboarding forms using your own company branding - including your company logo and colors. - White labeling creates a consistent user experience for your merchants which can lead to increased trust and translate to a higher willingness to complete onboarding more quickly. --- # Dashboard Updates Source: https://docs.finix.com/release-notes/2022/12/dashboard-updates ![Applications Page](/assets/release-notes-2022-12-release-notes-app-page.c6b8c498772c9895ba0984de5d85bffa302f836d137e3f385a71d03a1e66eebd.08ff7529.png) This is the last of a three-part release to refresh the user experience of our entire dashboard. The additional user experience improvements include reorganizing the Application, Merchant, and Push-to-Card pages to simplify where to find the most helpful information and make finding that information more intuitive. The changes made to the dashboard the past three weeks should help you complete tasks more quickly and efficiently–for example, by using new filters to easily create on-demand reports for information you’re seeking, or using the click-to-copy function to accurately and efficiently transfer data to external databases. For more information about what's available in the Finix Dashboard, see [Finix Dashboard](/guides/managing-operations/finix-dashboard). --- # Android Mobile Tokenization Source: https://docs.finix.com/release-notes/2023/02/android-mobile-tokenization Android Tokenization enables you to accept and tokenize payment details in your Android app without exposing yourselves to PCI risk. This completes the rollout of our tokenization offerings, which now includes: [web](/guides/online-payments/payment-tokenization), [iOS](/guides/online-payments/payment-tokenization/mobile-tokenization-ios), and [Android](/guides/online-payments/payment-tokenization/mobile-tokenization-android). --- # Test ACH Returns in Sandbox Source: https://docs.finix.com/release-notes/2023/02/test-ach-returns-in-sandbox You can now test ACH Returns in your sandbox! This enables you to test scenarios, process failure reasons, and help your sellers understand how to handle failed ACH payments–all in a test environment. Tests include: - Insufficient Funds - Account is Closed - No account on file - Invalid Account Number - Insufficient Funds - Account is Closed - No account on file - Invalid Account Number For more details, see [Testing ACH Returns](/additional-resources/developers/implementation-and-testing/testing-your-integration/##testing-ach-returns). --- # Customized Developer Sandboxes for Different Business Types Source: https://docs.finix.com/release-notes/2023/03/customized-developer-sandboxes-for-different-business-types We’ve enhanced the Finix Sandbox to provide tailored testing experiences for different types of businesses. This latest release adds specialized sandbox environments for different business types, including Software Platforms, Online Marketplaces and Direct Merchants. Now, when a user signs up for a Sandbox account, they will select their business type and be taken to a Finix Sandbox dashboard designed specifically for the business type they selected. The Finix Sandbox allows users to easily sign up for an account via our website and explore the Finix dashboard and simulate what their live production experience would be - including accepting test payment transactions, simulating merchant payouts, and building test integrations with Finix, all before applying for a live production account. For more info, see [Signing up for a Finix Account](/guides/getting-started/finix-sign-up/). --- # Improved Search Functionalities - Find the info you need more easily Source: https://docs.finix.com/release-notes/2023/03/improved-search-functionalities-find-the-info-you-need-more ![Tag Search](/assets/release-notes-2023-03-tag-search.d810ab82dc6904a687b0c847ac0d513e35f87f8c1e78049ad9d91200293f6e9e.08ff7529.png) Customers now have the ability to search for tags in the dashboard. You can now search the following resources by the keys and values of any tags that have been applied: - `Authorizations` - `Transfers` - `Payment Instruments` - `Identities` - `Authorizations` - `Transfers` - `Payment Instruments` - `Identities` Customers can also search for tags in the Finix API [using our new tag filters](/api/section/tags), allowing you to enable more functionality with our system and the ability to link your own system’s IDs with Finix. We've also made general improvements to the logic around our search! You can type partial words or terms and we’ll return all results that include that partial search term. --- # Max Transaction Limit on ACH Source: https://docs.finix.com/release-notes/2023/03/max-transaction-limit-on-ach Using our API, customers can set a different maximum transaction limit for ACH Direct Debits than the maximum set for Credit Card transactions. This gives you flexibility with ACH Direct Debits and allows you to create a maximum transaction limit specifically for ACH transactions. For more details see the [`ach_max_transaction_amount` field](/api/identities/createidentity). --- # More Dispute Functionality Available in the Finix Sandbox Source: https://docs.finix.com/release-notes/2023/03/more-dispute-functionality-available-in-the-finix-sandbox In the Finix Sandbox, users submitting and accepting disputes will now receive an API response that echoes the Dispute resource. Previously, they’d only receive a return indicating that their API call was accepted and that the dispute exists. This update allows Sandbox users to better simulate disputes with more of the same functionalities they’d experience with a live payment processing account, like seeing the status of a dispute (“Won", “Closed” and “In Progress”), as well as other information. For more details, see [Responding to Disputes](/guides/after-the-payment/disputes/responding-to-disputes). --- # Payment Solutions for Direct Merchants and Online Marketplaces Source: https://docs.finix.com/release-notes/2023/03/payment-solutions-for-direct-merchants-and-online Finix’s payment platform can now support Direct Merchants and Online Marketplaces, along with our existing customer segments. This release delivers more configurations of our platform and different bundles of features for payments solutions tailored to the unique needs of different supported business models and their specific payments use cases. We support: - **Direct Merchants:** eCommerce and other direct merchants who sell goods and services directly to buyers online, in-person, or both. - **Software Platforms:** SaaS companies offering embedded payments to their customers online, in-person, or both. - **Online Marketplaces:** Digital marketplaces that connect buyers and sellers online. - **Payfacs:** Large enterprise organizations registered as payment facilitators. - **Direct Merchants:** eCommerce and other direct merchants who sell goods and services directly to buyers online, in-person, or both. - **Software Platforms:** SaaS companies offering embedded payments to their customers online, in-person, or both. - **Online Marketplaces:** Digital marketplaces that connect buyers and sellers online. - **Payfacs:** Large enterprise organizations registered as payment facilitators. For more info, see [Who We Serve](https://finix.com/who-we-serve/customers). --- # Save Time & API Calls with the New Merchant Field on Transfers and Authorizations Source: https://docs.finix.com/release-notes/2023/03/save-time-api-calls-with-the-new-merchant-field Now that we’ve added the `merchant` field to `Transfers` and `Authorizations`, you can save multiple API calls by directly referencing a `Merchant` resource instead of using the Seller’s `Identity` to reach it. This is especially helpful when you’re looking to understand the origin of a transaction. --- # Updated Finix Team Members & Roles in the Finix Dashboard Source: https://docs.finix.com/release-notes/2023/03/updated-finix-team-members-roles-in-the-finix-dashboard ![Roles](/assets/release-notes-2023-03-roles.5bc5282f29cf4b1b61f98313c105c58c3488410870fca8c400cd44ee84a5ce18.08ff7529.png) This feature enables customers to manage their [Team Members, Roles, and access levels](/guides/managing-operations/managing-team-members/) in the Finix dashboard. These enhancements make it possible for administrators (those with the highest level of access) to add, customize, and manage the users from their company, directly in the Finix dashboard. Managed permissions provide enhanced security and limit who can see sensitive payments data. In the Finix dashboard you can now easily: - Add and deactivate team members - Assign different permission-based roles - Create custom roles to address unique business needs - Add and deactivate team members - Assign different permission-based roles - Create custom roles to address unique business needs The variety of configurable profiles to choose from include: - [Administrator](/guides/managing-operations/managing-team-members/roles-permissions#administrator) - [Payment Operations Manager](/guides/managing-operations/managing-team-members/roles-permissions#payment-operations-manager) - [Merchant Manager](/guides/managing-operations/managing-team-members/roles-permissions#merchant-manager) - [Settlement Specialist](/guides/managing-operations/managing-team-members/roles-permissions#settlement-specialist) - [Developer](/guides/managing-operations/managing-team-members/roles-permissions#developer) - [Viewer](/guides/managing-operations/managing-team-members/roles-permissions#viewer) - [User Management Admin](/guides/managing-operations/managing-team-members/roles-permissions#user-management-admin) - [Custom Roles](/guides/managing-operations/managing-team-members/roles-permissions#custom-roles) - [Administrator](/guides/managing-operations/managing-team-members/roles-permissions#administrator) - [Payment Operations Manager](/guides/managing-operations/managing-team-members/roles-permissions#payment-operations-manager) - [Merchant Manager](/guides/managing-operations/managing-team-members/roles-permissions#merchant-manager) - [Settlement Specialist](/guides/managing-operations/managing-team-members/roles-permissions#settlement-specialist) - [Developer](/guides/managing-operations/managing-team-members/roles-permissions#developer) - [Viewer](/guides/managing-operations/managing-team-members/roles-permissions#viewer) - [User Management Admin](/guides/managing-operations/managing-team-members/roles-permissions#user-management-admin) - [Custom Roles](/guides/managing-operations/managing-team-members/roles-permissions#custom-roles) Customers can manage which team members have access to their company’s dashboard and their specific permissions, deactivate users who no longer need access, as well as create new custom roles tailored to their unique user requirements. A common example of a custom role you might create is for an outside accountant, who may need access to specific data for a set amount of time during the year. Start managing your team’s [roles and permissions](/guides/managing-operations/managing-team-members/). --- # Webhook Event Logs Source: https://docs.finix.com/release-notes/2023/03/webhook-event-logs ![Log](/assets/release-notes-2023-03-webhooks-logs.ba906be8fec072b1075c6cc16dde2ccca7df65de87992145a2f117f40b35dbcb.08ff7529.png).. From the developer section of the dashboard, [users can now review logs](/additional-resources/developers/webhooks/integrating-into-webhooks#managing-webhooks-via-dashboard) that detail all the webhook events they’ve received. Developers are also able to receive dashboard and email notifications about webhook events they’ve received. With an easily accessible log you can check at any time, it’s an easier path to debug, troubleshoot, and audit the activity you process. The webhook events log allows you to: - Review how webhooks are configured - Review a history of all webhook event attempts - Filter webhooks by attempts and troubleshoot any failed events - Reattempt events that have failed - Enable email and in-dashboard notifications for failing webhooks - Review how webhooks are configured - Review a history of all webhook event attempts - Filter webhooks by attempts and troubleshoot any failed events - Reattempt events that have failed - Enable email and in-dashboard notifications for failing webhooks --- # Apply for Live Payment Processing via the Finix Sandbox Source: https://docs.finix.com/release-notes/2023/04/apply-for-live-payment-processing-via-the-finix-sandbox You can now apply for a live payment processing account in the Finix Sandbox! The Finix Sandbox allows you to easily sign up for an account via our website to explore the Finix dashboard and simulate what your live production experience would be - including accepting test payment transactions, simulating merchant payouts, and building test integrations with Finix. If you’re ready to start processing payments with Finix, you can easily apply for a live account via your sandbox dashboard, by submitting all the needed application info and selecting what pricing schema and business configuration works best for you. If approved, you can begin accepting payments with Finix in live production. --- # Faster in-person payments Source: https://docs.finix.com/release-notes/2023/04/faster-in-person-payments In-person payments are now faster than ever! We’ve improved the time it takes our in-person payments API to share the result of a transaction with your system to an average speed of 0.5 seconds. This helps speed up the overall transaction flow and deliver more seamless checkout experiences for your buyers. --- # More Failure Codes for Processing In-Person Payments Source: https://docs.finix.com/release-notes/2023/04/more-failure-codes-for-processing-in-person-payments Below, we’ve added two additional in-person payment failure codes to help you better understand why a certain transaction failed and trigger your own workflows in response to the issue. You can see the full list of [failure codes and associated failure messages here.](/additional-resources/developers/implementation-and-testing/failure-codes) - **DEVICE_IN_USE:** *The device is currently processing a request. Attempt a request again once the request is complete, or within 6 minutes.* - **DEVICE_NOT_ENABLED:** *The device is not activated. Please activate the device and try again.* - **DEVICE_IN_USE:** *The device is currently processing a request. Attempt a request again once the request is complete, or within 6 minutes.* - **DEVICE_NOT_ENABLED:** *The device is not activated. Please activate the device and try again.* We also updated the [failure messages](/additional-resources/developers/implementation-and-testing/failure-codes) for the following existing in-person payment failure codes: - **GENERIC_DECLINE:** *The transaction was declined for an unknown reason. The account owner needs to contact their issuer for more information.* - **TRANSACTION_NOT_PERMITTED:** *The transaction was declined because the card or transaction type is not permitted. The cardholder needs to use a different type of card or attempt a different transaction method.* - **GENERIC_DECLINE:** *The transaction was declined for an unknown reason. The account owner needs to contact their issuer for more information.* - **TRANSACTION_NOT_PERMITTED:** *The transaction was declined because the card or transaction type is not permitted. The cardholder needs to use a different type of card or attempt a different transaction method.* --- # Webhook enhancements Source: https://docs.finix.com/release-notes/2023/04/webhook-enhancements To make your dashboard experience more intuitive and powerful, we’ve added the Onboarding Form webhook event to dashboard and Updated API + Webhook logs. --- # Easily Link Disputes and Dispute Evidence with Tags Source: https://docs.finix.com/release-notes/2023/05/easily-link-disputes-and-dispute-evidence-with-tags You can now add and edit tags for Disputes and Dispute Evidence Files via API, just like you would for the other Finix API resources you use (Transfers, Payment Instruments, etc.) Assigning tags to Disputes and Dispute Evidence files allows you to link Finix dispute resources directly to your own system and include additional data about disputes, such as a custom unique id. For more details on using tags, see [Tags](/api/section/tags). --- # Edit Buyer Names for Payment Instruments via API Source: https://docs.finix.com/release-notes/2023/05/edit-buyer-names-for-payment-instruments-via-api The name of a buyer linked to a payment instrument (card, bank account, token, etc.) can now be edited via API. This is helpful in situations where you need to change a name to correct an error or reflect an update to the name of the payment instrument’s owner. To update the name associated with a `Payment Instrument`, see [Update a Payment Instrument](/api/payment-instruments/updatepaymentinstrument). --- # Prevent Duplicate Refunds Source: https://docs.finix.com/release-notes/2023/05/prevent-duplicate-refunds You can now include an `idempotency_id` when creating a Refund or Reversal. Including this unique identifier with your refund API requests helps ensure that even if duplicate API requests for the same refund are sent, the refund is only initiated once. This is key, because sometimes an issue like an interruption with your network connection or problem with your server can cause an API request for the same refund to get submitted multiple times. For more details on the `idempotency_id`, see [Idempotent Requests](/api/section/idempotent-requests). --- # Upgraded Dashboard Date Selection Button Source: https://docs.finix.com/release-notes/2023/05/upgraded-dashboard-date-selection-button We’ve upgraded the look and feel of the date selection button that appears throughout the Finix dashboard, to make filtering your dashboard payments data by specific dates or periods more intuitive and responsive. --- # Validate and Tokenize Bank Accounts at the Same Time Source: https://docs.finix.com/release-notes/2023/05/validate-and-tokenize-bank-accounts-at-the-same-time You can now validate new bank accounts when they’re tokenized and used to create payment instruments. This helps you know for certain whether a new bank account is valid before using it in a transaction. To verify that a bank account actually exists when creating a token, you can include the `attempt_bank_account_validation_check` field. If a bank account doesn’t exist, the token will create a `payment_instrument` with an error in the `address_verification` field. - For details on how to tokenize the details of a bank account, see [Tokenization Forms](/guides/online-payments/payment-tokenization/tokenization-forms). - For details on how to create a Payment Instrument using a token, see [Create a Payment Instrument](/api/payment-instruments/createpaymentinstrument). - For details on how to tokenize the details of a bank account, see [Tokenization Forms](/guides/online-payments/payment-tokenization/tokenization-forms). - For details on how to create a Payment Instrument using a token, see [Create a Payment Instrument](/api/payment-instruments/createpaymentinstrument). --- # Added ID fields for dispute and dispute evidence files APIs Source: https://docs.finix.com/release-notes/2023/06/added-id-fields-for-dispute-and-dispute-evidence-files-apis We added new fields to the `Dispute` and Dispute Evidence APIs that makes it easier to manage these resources; especially if you have multiple applications or merchants with Finix. - Added `application` to the [Dispute Evidence File resource.](/api/disputes/submitdisputeevidence) - Added `identity` and `merchant` to [Dispute](/api/disputes/getdispute) and [Dispute Evidence File](/api/disputes/submitdisputeevidence) resources. - Added `application` to the [Dispute Evidence File resource.](/api/disputes/submitdisputeevidence) - Added `identity` and `merchant` to [Dispute](/api/disputes/getdispute) and [Dispute Evidence File](/api/disputes/submitdisputeevidence) resources. --- # Auto-complete for merchant addresses on Hosted Onboarding Forms Source: https://docs.finix.com/release-notes/2023/06/auto-complete-for-merchant-addresses-on-hosted-onboarding We’ve added Google address autocomplete to Finix hosted merchant onboarding forms to provide a more convenient experience for your merchants and better ensure the accuracy of the address information they provide. Now when a user is filling out an onboarding form and begins to enter their address, the field will expand into a list of predicted matches they can select from to autocomplete the field based on the info they’ve already typed. --- # Developers can now see raw API response on failed Transfers Source: https://docs.finix.com/release-notes/2023/06/developers-can-now-see-raw-api-response-on-failed-transfers If a transfer fails, the raw API response is now available for review in the Finix Dashboard. This is especially helpful for developers who can quickly access the response to see why the payment failed and troubleshoot. --- # Easily accept and close disputes in the dashboard Source: https://docs.finix.com/release-notes/2023/06/easily-accept-and-close-disputes-in-the-dashboard If a dispute gets filed that you don’t want to challenge, you can now easily accept and close that dispute directly in the dashboard. Reasons you might want to accept liability for a dispute could include: - The buyer’s dispute is valid . - There isn’t sufficient evidence to counter the claim. - Low transaction amount that doesn’t justify the time/resources needed to respond to the dispute. - You suspect there is fraud or it was caused by an internal issue. - The buyer’s dispute is valid . - There isn’t sufficient evidence to counter the claim. - Low transaction amount that doesn’t justify the time/resources needed to respond to the dispute. - You suspect there is fraud or it was caused by an internal issue. On **Pending** disputes, you’ll now see a button to “Accept Liability”. You can also include a note to communicate to the issuer why it was accepted and provide any other relevant information. We’ll then forward this information to the appropriate parties to finalize acceptance of the dispute. For more information, please see [Accepting a Dispute](/guides/after-the-payment/disputes/accepting-disputes/). This functionality is also available via [API](/guides/after-the-payment/disputes/accepting-disputes#accept-a-dispute-with-the-api). Please note, this action is final and accepted disputes count toward your maximum permitted quantity. Once accepted, the dispute will move to a closed state. --- # Seamlessly upload dispute evidence files via dashboard Source: https://docs.finix.com/release-notes/2023/06/seamlessly-upload-dispute-evidence-files-via-dashboard We’ve made the experience of responding to disputes in the Finix dashboard a lot more seamless. You can now upload and submit dispute evidence files (receipts, shipping information, customer communications, etc.) directly in the Finix dashboard. Once submitted, we’ll then forward the uploaded evidence to support your defense against the dispute. For a single dispute, you can upload up to 8 files (total size of all files must be less than 10 mb) in JPG, PNG, or PDF formats. We also recommend using the “Summary of Evidence” field to include information that describes or supports the evidence you’ve uploaded for the issuer to review. After we forward your evidence to the appropriate parties, we’ll update the status of your evidence files to confirm they were submitted successfully. For more information, please see [Uploading Evidence on the Dashboard](/guides/after-the-payment/disputes/responding-to-disputes#respond-on-the-dashboard). This functionality is also available via [API](/guides/after-the-payment/disputes/responding-to-disputes#respond-with-the-api). --- # Surcharge enabled is now on merchant resource Source: https://docs.finix.com/release-notes/2023/06/surcharge-enabled-is-now-on-merchant-resource We added a field to the `Merchant` API resource that details if a seller has surcharges enabled to make it easier for you to identify if processing surcharges is active for the seller. --- # Updated look & feel for payout settings Source: https://docs.finix.com/release-notes/2023/06/updated-look-feel-for-payout-settings We’ve refreshed the look and feel of payout settings in the dashboard to make them more intuitive. Changes include various copy, layout, and visual updates that make it easier to see all payout settings you have configured and when settlements and fees get delivered. --- # Upgraded disputes dashboard UI Source: https://docs.finix.com/release-notes/2023/06/upgraded-disputes-dashboard-ui We’ve added and improved elements of the Disputes section of the dashboard to better deliver the critical information you need to manage disputes. This includes: - New **Respond Within** column on the Disputes page that shows how many days you have left to respond to a dispute - New **Card Last 4** column on the Disputes page that shows the last 4 digits and card brand associated with a dispute - Improvements to the layout of individual Dispute pages - New **Respond Within** column on the Disputes page that shows how many days you have left to respond to a dispute - New **Card Last 4** column on the Disputes page that shows the last 4 digits and card brand associated with a dispute - Improvements to the layout of individual Dispute pages --- # User permissions list on team member view page Source: https://docs.finix.com/release-notes/2023/06/user-permissions-list-on-team-member-view-page Administrators managing your company’s team members and roles, can now see all the permissions enabled for a given user when looking at a specific team member’s user page in the dashboard. This permission list helps provide at-a-glance information on what level of access to sensitive payments data and available actions a specific user of yours has. --- # 40+ New Insights & Analytics in the Finix Dashboard Source: https://docs.finix.com/release-notes/2023/07/40-new-insights-analytics-in-the-finix-dashboard We’ve upgraded the Finix dashboard with dozens of new metrics, charts and visuals to help you see your payments data in powerful new ways. ![Home](/assets/release-notes-2023-07-home-insights.7c56f6842f221db9c41699121f73200bba1f7a66e74939486bd444afae5c4204.08ff7529.png) --- # New Transaction Insights page Source: https://docs.finix.com/release-notes/2023/07/new-transaction-insights-page We’ve added a brand new **Transaction Insights** page with three individual tabs to visualize your Payments, Authorizations, and Refunds data. View and filter across different card brands, payment methods, issuer countries, merchants, date ranges, and more to get a deeper look at your transaction data. Stay tuned for even more data and analytics tools coming to your dashboard soon! --- # Redesigned Homepage Source: https://docs.finix.com/release-notes/2023/07/redesigned-homepage Get a complete look at your payments activity with the sleeker, smarter and more data-rich [**Home**](https://finix.payments-dashboard.com/) page. Use the new and improved [**Home**](https://finix.payments-dashboard.com/) page to get an at-a-glance view of your most important metrics with interactive visualizations and other key insights that can be sliced and diced across specific time periods and several data points with enhanced filtering. --- # Easier bulk exports on dashboard pages Source: https://docs.finix.com/release-notes/2023/08/easier-bulk-exports-on-dashboard-pages Exporting payments data in the dashboard is now a whole lot easier! We added the ability to perform bulk exports on the Authorizations, Merchant Accounts, Settlements, Disputes and Settlement Entries pages of the dashboard. Instead of needing to scroll through all the data listed on these specific pages first, you can now generate a bulk export for all the available data with a single click of a button. --- # Enable surcharging for in-person payments via API Source: https://docs.finix.com/release-notes/2023/08/enable-surcharging-for-in-person-payments-via-api You can now enable buyer surcharge fees for your merchants on in-person payments via API. Please consult your legal counsel if you have questions about a seller's eligibility to assess surcharges or surcharging requirements. Eligibility and requirements are governed by applicable state laws and card brand rules. For more information, see [Buyer Charges.](/guides/online-payments/payment-features/buyer-charges#comparing-buyer-charges) --- # Introducing 6 new in-person payment terminals Source: https://docs.finix.com/release-notes/2023/08/introducing-6-new-in-person-payment-terminals We’ve introduced six additional payment terminals to our diverse selection of supported in-person payments hardware. These newly added devices feature a wide array of form factors and functionalities to help support all your in-person payment needs. For more information on the terminals Finix supports, see [Managing Your Devices.](/guides/in-person-payments/managing-your-devices) --- # New Exceptions Insights page Source: https://docs.finix.com/release-notes/2023/08/new-exceptions-insights-page We’ve added a brand new Exceptions Insights page with two individual tabs for Disputes and ACH Returns data. Get a simpler view of your exception management with key dispute and ACH return metrics at-a-glance and track data across specific time periods and different filters. --- # Test Split Transactions via API in your Finix sandbox Source: https://docs.finix.com/release-notes/2023/08/test-split-transactions-via-api-in-your-finix-sandbox You can now test split transactions in the sandbox via API. Split transactions enable you to split the settlements from a singular transaction across several different test sellers. Please note, Split Transactions is currently in early access and subject to further changes. For more information, reach out to the [Finix Support team.](mailto:support@finix.com) To learn more about this feature, see [Split a Transaction.](/guides/online-payments/payment-features/split-transactions#split-transactions) --- # Tokenize international cards on iOS and Android devices Source: https://docs.finix.com/release-notes/2023/08/tokenize-international-cards-on-ios-and-android-devices You can now tokenize international cards on both iOS and Android devices using our mobile tokenization tools. Previously, mobile tokenization was limited to only cards issued within the U.S. Please note, this only applies to international card transactions with U.S. merchants, in which the international currency is converted into USD. For more information, see [Mobile Tokenization.](/guides/online-payments/payment-tokenization/mobile-tokenization-ios) --- # Enhanced dispute search with 30+ new filters Source: https://docs.finix.com/release-notes/2023/09/enhanced-dispute-search-with-30-new-filters We’ve added more than 30 new filters to help you easily search, sort and export your dispute data. These dispute filters are available via both dashboard and API and are especially helpful if you’re looking to pull on-demand CSV reports of your disputes customized around your desired parameters. For more information, see [List Disputes](/api/disputes/listdisputes). --- # New insights for customers who manage sellers Source: https://docs.finix.com/release-notes/2023/09/new-insights-for-customers-who-manage-sellers If you’re a Finix customer who manages sellers, you can now access a brand new Insights page that helps you get a complete look at your merchant management activity. Get an at-a-glance view of key metrics, see trends around onboarding statuses and active merchants, analyze transaction data by each of your merchants and other variables, and more, right in your Finix dashboard. Just like other insights in our dashboard you can easily slice and dice these data points across specific time frames and variables to find the exact info you’re looking for. --- # Split transactions in your Finix sandbox dashboard Source: https://docs.finix.com/release-notes/2023/10/split-transactions-in-your-finix-sandbox-dashboard You can now view and manage test split transactions in your Finix sandbox dashboard. Split transactions enable you to split the funds from a singular transaction across several different sellers. Please note, Split Transactions is currently in early access and subject to further changes. For more information, reach out to the [Finix Support Team](mailto:support@finix.com). To learn more about Split Transactions, see [Split Transactions](/guides/online-payments/payment-features/split-transactions). --- # New Tokenization Forms: Securely accept payment details with less code Source: https://docs.finix.com/release-notes/2023/11/new-tokenization-forms-securely-accept-payment-details We’ve released a new suite of embeddable payment forms that make it easier to securely accept payment information in your app or website. These low-code tools integrate directly into your checkout flow to help you accept and tokenize card and bank account details buyers enter for a payment–reducing your compliance burden with data securely handled by Finix. Compared to our existing Hosted Fields, these pre-built forms require minimal code–developers can get started with less than 10 lines of code. They also give you more control over customization to match the look of your brand and unique checkout requirements. Plus, better error handling and validation and a more intuitive design to help drive conversions. To learn more, see [Tokenization Forms](/guides/online-payments/payment-tokenization/tokenization-forms). --- # Power checkouts across channels with Payment Links Source: https://docs.finix.com/release-notes/2023/12/power-checkouts-across-channels-with-payment-links ![Payment Links](/assets/payment-links.ffd26ab1fa40e8d5554df78841a3943e026e5a8fb9144f6062f4fe56abe56a6f.fec90461.svg) Our new Payment Links enable you to easily create shareable links you can use to accept payments from buyers online–with no code required. You can share these links across many channels, like sms, email, and social, or embed them into QR codes, content, buttons, and more— anywhere a link can go! You can create these links in the new **Payment Links** section of your dashboard–note, this requires admin-level permissions. In this new section of the dashboard, you can track and analyze all the links you’ve created and payments you’ve received for a specific link. You can also integrate with our Payment Links via API if you’re looking to create custom payment workflows with your own internal tools. To learn more, please see [Payment Links](/low-code-no-code/payment-links). ![Virtual Terminal](/assets/virtual-terminal.ec12abd21153afb7fd08d11a82bbc9e0c9b95df4861c3760b04866bf4a45a282.fec90461.svg) --- # Take payments from your browser with the new Virtual Terminal Source: https://docs.finix.com/release-notes/2023/12/take-payments-from-your-browser-with-the-new-virtual With our new Virtual Terminal, you can manually take payments right from your Finix dashboard. This allows members of your team with admin-level permissions to manually key in and process payments received over the phone, via mail, in-person or other channels without a physical point of sale or online checkout form required. This enables you to accept payments in a more convenient way for certain customers and power sales you’d otherwise miss. To learn more, please see [Virtual Terminal](/low-code-no-code/virtual-terminal). --- # Automate your merchant underwriting with Finix’s new solution Source: https://docs.finix.com/release-notes/2024/02/automate-your-merchant-underwriting-with-finixs-new-solution ![Finix Merchant Underwriting](/assets/merchant-underwriting.0824fd0d88bc526930c02943e69c752f4d0ba243cbce44cd3e11fa3c9a24762e.fec90461.svg) Introducing Merchant Underwriting! Our new solution automates underwriting workflows to help you onboard merchants faster and more efficiently scale your business. Use our solution to underwrite merchants for payments with any processor or power merchant verification for many financial use cases. Bring your underwriting processes together in a single place: - Easily collect onboarding information with prebuilt flows you can customize to your brand - Automate identity verification and compliance reporting, risk scoring and underwriting decisioning - Efficiently manage cases and manual reviews with enriched decision data, contextual insights and built-in dashboard workflows - Get visibility and control over your underwriting operations, merchant statuses and seller compliance forms - Easily collect onboarding information with prebuilt flows you can customize to your brand - Automate identity verification and compliance reporting, risk scoring and underwriting decisioning - Efficiently manage cases and manual reviews with enriched decision data, contextual insights and built-in dashboard workflows - Get visibility and control over your underwriting operations, merchant statuses and seller compliance forms Reduce time-to-decisions to seconds without compromising risk through streamlined underwriting orchestration. To learn more, visit [Merchant Underwriting](https://finix.com/merchant-underwriting). --- # Easily add and manage terminals in your dashboard Source: https://docs.finix.com/release-notes/2024/02/easily-add-and-manage-terminals-in-your-dashboard ![Finix Device Management](/assets/device-management.df339eb0359416975761308f77c18b0b810787ae879de9fc96bec05834cd8fb8.fec90461.svg) We’ve built a new *Payment Devices* section in your Finix dashboard that helps you add, manage, and configure your payment terminals in a single place. Seamlessly manage your fleet across all your locations with self-service capabilities to: - Quickly add, configure, and activate new terminals - Manage all your terminals from a centralized view - Customize and enable device settings - Easily track each terminal’s real-time status, processed transactions, and idle messages - Check connections, ping devices and deactivate terminals for quick troubleshooting - Quickly add, configure, and activate new terminals - Manage all your terminals from a centralized view - Customize and enable device settings - Easily track each terminal’s real-time status, processed transactions, and idle messages - Check connections, ping devices and deactivate terminals for quick troubleshooting Please note, device management only applies to Finix-supported terminals. --- # Finix is now live in Canada 🇨🇦 Source: https://docs.finix.com/release-notes/2024/02/finix-is-now-live-in-canada ![Finix Canada](/assets/canada.936b7469400135b74e4841f8b7cfc5edd0d7efa2a7a6acbec5f5ae414e334ac9.fec90461.svg) We’re excited to announce our launch as a payment processor in Canada! Our unified platform now equips Canadian businesses with everything you need to accept payments online and in person and efficiently manage your business, including embedded tools for financial reporting, fraud prevention, compliance and more. Our flexible technology is built to support the needs of Canadian businesses of all sizes and industries, from software platforms to digital marketplaces and many types of ecommerce and merchant businesses. If you’re a Canadian business or international business with a Canadian presence, Finix is here to help you simplify cross-border payments with a platform purpose-built for growth. Read our announcement blog to [learn more](https://finix.com/resources/blogs/canada-meet-finix-a-new-era-of-unified-cross-border-payments-has-arrived). --- # Seamlessly add and verify merchant bank accounts with Plaid Source: https://docs.finix.com/release-notes/2024/03/seamlessly-add-and-verify-merchant-bank-accounts-with-plaid We’ve partnered with Plaid to help you instantly add and verify merchant bank accounts during onboarding with a seamless and secure flow for your sellers, buyers, and recipients. **Embedded Verification:** Plaid is now directly embedded into our no-code Onboarding Forms, giving merchants the option to link their financial accounts in seconds using their banking credentials. Finix supports Plaid bank authentication for thousands of U.S. and Canadian institutions, so you can quickly confirm account existence and ownership to sign up trusted merchants for payments. **Dashboard Enhancement:** We’ve added Plaid’s authentication flow to Finix dashboards to equip your merchants with a simple way to update their bank accounts. **API Flexibility:** You can leverage our partnership to integrate Plaid into your own onboarding forms or product experience using Finix’s APIs. This helps you create tailored bank account processes that meet your specific business needs. Read our integration guide to [learn more](/guides/online-payments/bank-payments/plaid-integration#plaid-integration). --- # Send Money on the Dashboard Source: https://docs.finix.com/release-notes/2024/04/send-money-on-the-dashboard ![Send Payout on Dashboard](/assets/release-notes-2024-04-send-money-via-dashboard.08c790c82e1f6b0ffdf17180f74a389047c0c3c1c421f3a5b9f89118f1d23e7d.08ff7529.png) You now have the option to send payouts to previously onboarded recipients using the dashboard. You can also add a new recipient on the dashboard and send them money once they are successfully onboarded. ![Add Recipients on Dashboard](/assets/release-notes-2024-04-add-recipient.fbc1129bb4ee68440ec7c6f72b641763df92271a654d9ffb2da16e8063387c40.08ff7529.png) --- # Sub-merchant Dashboard Updates Source: https://docs.finix.com/release-notes/2024/04/sub-merchant-dashboard-updates ## Payment Links are now available to sub-merchants ![Virtual Terminal Sub-Merchants](/assets/release-notes-2024-04-submerchant-payment-links.1fe029a8c4316bb054671e9f013d106f9b472eaccace7e504a59fc07e316a480.08ff7529.png) Sub-merchants will now be able to create Payment Links and send them to their buyers. They can customize the branding for the payment link, items, expiration time, and the allowed payment methods. Read more about [Payment Links](/low-code-no-code/payment-links). ## Virtual Terminal now available to sub-merchants ![Virtual Terminal Sub-Merchants](/assets/release-notes-2024-04-submerchant-virtual-terminal.79c833c918f6e42ecd5d14e49606672b4678a36e3d14e3dfaa23dbc9a957c22d.08ff7529.png) Sub-merchants can now create Sales and Authorizations on the Dashboard using the virtual terminal. They can enter card information and create a transaction on our white-labeled dashboard. ## Sub-merchants now have access to our Insights data ![Sub-merchants Insights Data](/assets/release-notes-2024-04-submerchant-insights.5cd625bf103b412cc904b76086ae011540b9ca06b9f93ea234b8d2f9723f0a14.08ff7529.png) Sub-merchants will have access to high-level business insights on the home page and more detailed insights related to their payments, authorizations, and refunds on the Transactions Insights page. They can view their transaction volume, trends, and more within our white-labeled dashboards. --- # Token Form Updates Source: https://docs.finix.com/release-notes/2024/04/token-form-updates ![finix.js update to version 1.1.0](/assets/release-notes-2024-04-token-form.839f94eff5bb504fc807bd586d9151b1c7d66e5a71c9826effa270c3a4e444e2.08ff7529.png) We’ve updated our finix.js library to version 1.1.0. This is our javascript library for tokenizing payment instruments using our Token Forms. Summary of our recent changes: - Added support for a new `defaultCountry` option to set the default country experience for your Tokenization form. - We removed all address fields from the Bank Tokenization Form except for the `country` field, which was not required to tokenize bank accounts. - onUpdate function's first param `state` now returns additional metadata for select fields called `selected`. Currently supported fields are: `account_type`, `address_state` and `address_country`. - We fixed a bug related to loading the Tokenization library when only `address_state` is hidden. --- # Updated Left Navigation Bar Source: https://docs.finix.com/release-notes/2024/04/updated-left-navigation-bar ![Left Navigation update](/assets/release-notes-2024-04-updated-nav-bar.bb1635fc4520c7afd22d63842e97c422cd4ae9a9feb7a090de50968e5ec859f0.08ff7529.svg) We’ve updated our left nav bar to a lighter theme to better match the aesthetics of the dashboard. If you have custom branding on the dashboard, your view will be unaffected by this change. --- # Send money with Finix Payouts Source: https://docs.finix.com/release-notes/2024/01/send-money-with-finix-payouts ![Finix Payouts](/assets/payouts.6dbd27809b072f4c19158931e787d91afbd6850b2328a91f476fe7d0fc36050f.fec90461.svg) Introducing Finix Payouts! Send fast digital payouts from your business to a business or individual recipient’s card or bank account. With our new solution you can easily automate payout workflows via API and send money at scale. No matter your use case, we’ve got you covered. Power near limitless payout possibilities—like disbursing funds for gig workers, insurance claims, deposit refunds, payroll and more. Use Finix Payouts to flexibly send money on the timeline you choose: - Send money instantly to cards1 - Send money next-day to bank accounts via ACH - Send money instantly to cards1 - Send money next-day to bank accounts via ACH One seamless API integration, powerful custom dashboards, embedded compliance, and more equip you with the tools you need to start sending money quickly and efficiently manage your payouts. Easily toggle between your Payments and Payouts in your dashboard with an all-in-one provider that helps you power both. To learn more, visit [Payouts](https://finix.com/payouts). 1*Actual fund availability depends on receiving financial institution and region* --- # Finix Dashboard is now Mobile Responsive Source: https://docs.finix.com/release-notes/2024/05/finix-dashboard-is-now-mobile-responsive ![Mobile Responsive Dashboard](/assets/release-notes-2024-05-mobile-responsiveness.70da662dc562dbac8cc4c55b72b84171ea829bac64f73fb03837cc224b9ac699.08ff7529.png) We updated the Finix Dashboard to be mobile responsive. Merchants can use the Virtual Terminal and Payment Links easily on their phones to take a payment. You can also view our insights on the go using your phone or tablet. --- # New Point of Sale Devices Available on our FINIX_V1 Processor Source: https://docs.finix.com/release-notes/2024/05/new-point-of-sale-devices-available-on-our-finixv1-processor ## Pax A920 Pro ![Pax A920Pro](/assets/release-notes-2024-05-pax-a920pro.6b82e44c2ceba61a4be3f06978d5e4a6c0f44788f9de053d19cd73f1fe657a11.08ff7529.svg) The PAX A920 Pro is an upgraded version of the A920 with a faster processor, larger HD screen, professional infrared barcode scanner, and a 5MP camera. It supports advanced connectivity options, NFC contactless, and electronic signature capture, ## Pax A800 ![Pax A800](/assets/release-notes-2024-05-pax-a800.59662cf4821e9301f095ee0284a890448e4a34ed407f24acef3cbf27d9136323.08ff7529.svg) The A800 offers high performance and the flexibility to be used as either a countertop device or mobile solution. Used as a countertop device, connected to an optional hub, the A800 allows merchants to connect to the Internet via Ethernet. ## Pax MPOS ![Pax D135](/assets/release-notes-2024-05-pax-d135.4c2df8d05de16fa0bcc924eb763c54834f000bf8dfe55186871c676ec6b7bb1a.08ff7529.svg) Weighing less than 3 oz, the ultra-light D135 packs high efficiency and portability to deliver a reliable payment experience for merchants of any size. You can take NFC payments, chip payments, and swiped cards. You can connect this device to a phone or tablet via Bluetooth or with a wired USB chord. --- # New Tipping Configurations Source: https://docs.finix.com/release-notes/2024/05/new-tipping-configurations ![New Tipping Options](/assets/release-notes-2024-05-tipping.d8a840b2b330a1a050bf156e80e4b8898d751963b3613f4d46845a6380b28ed9.08ff7529.png) You now choose how to configure tipping on in-person devices using the Finix Dashboard and via API. We support three values for different tip percentages. We also let buyers enter in a custom tip amount. You have the option to do fixed amounts for lower transaction amounts. This feature is helpful for coffee shops or other locations with variable low and high transaction amounts. --- # Payout Links Source: https://docs.finix.com/release-notes/2024/05/payout-links ![Mobile Responsive Dashboard](/assets/release-notes-2024-05-payout-links.cce5ca482fb0882682591c899860bc25970f6c22a1db88c7f3aea42dfbcee977.08ff7529.png) Payout Links are one-time use links to send a payout to a recipient. You can email or text the link to your recipient. If conducting a card payout, funds are usually available in minutes. You can use payout links to send insurance payouts, sales commissions, and more. You can customize the payout link with your brand name and logo. Learn more about [Payout Links](/guides/payouts/payout-links). --- # Email receipts now available using the Virtual Terminal Source: https://docs.finix.com/release-notes/2024/06/email-receipts-now-available-using-the-virtual-terminal ![Receipts added to Virtual Terminal](/assets/release-notes-2024-06-virtual-terminal-receipt.75ce27714a00cc1cd884ce5530b6d1f9fd838b2c1495982f4a82300d7ae66675.08ff7529.png) We've updated our Virtual Terminal so you can send receipts. You can now select to automatically email a PDF receipt to the buyer and can optionally choose a copy be sent to yourself. You can also generate a new receipt for an existing payment that was processed in the past. --- # SMS Multi Factor Authentication Source: https://docs.finix.com/release-notes/2024/06/sms-multi-factor-authentication ![SMS Multi Factor Authentication](/assets/release-notes-2024-06-sms-auth.6ddf6e80c1ccffdcccb2eb207852c875c93a4a2195bb5a667b9bb6fd70010b53.08ff7529.png) Users can now use SMS as an alternative for Multi Factor Authentication (MFA). Finix now supports MFA via: - SMS - Mobile Authenticator (Google Authenticator, Okta, Duo) - SMS - Mobile Authenticator (Google Authenticator, Okta, Duo) [Read more about SMS here.](/guides/managing-operations/managing-team-members/multi-factor-authentication) --- # Updated Navigation Bar on Finix Dashboard Source: https://docs.finix.com/release-notes/2024/06/updated-navigation-bar-on-finix-dashboard ![Finix Dashboard Navigation Bar](/assets/release-notes-2024-06-navbar.e541ab5b76f05efa663779966ee1e4f5e75dc540f55adfa597dcc0285127ebcd.08ff7529.png) We've updated our Navigation Bar to make it easier to navigate on the Finix Dashboard. - Disputes and ACH Returns will be shown under ‘Transactions’. This means that all your transactions including payments, authorizations, refunds, disputes, and ACH returns will be grouped together. - A new menu item called ‘Data Resources’ will be added to the left navigation menu and it will have all your buyer identities as well as all your payment instruments. - ‘Reports’ will now include all the system generated reports as well as any exports that are initiated by your dashboard users. - We have moved the ‘Company’ menu under ‘Settings’. This will allow you to access all dashboard-level settings as well as user-level settings under the ‘Settings’ menu. --- # Subscription Billing now available Source: https://docs.finix.com/release-notes/2024/07/subscription-billing-now-available ![Subscription Billing 01](/assets/release-notes-2024-07-subscription-billing-01.e2f924adda416453c7f7bb0a9aeb83808dcaa3503ee64f3788e7371fcf3aac18.08ff7529.png) ![Subscription Billing 02](/assets/release-notes-2024-07-subscription-billing-02.37df489b370b8835ef3011744e0a3337058d0d6ea66ea4862d5426e977914f9d.08ff7529.png) Early Access This is an early access feature. Please contact your Finix Point of Contact if you are interested in learning more. Direct Merchants and Platforms can take can now charge subscriptions to buyers. Subscriptions let you charge a fixed amount to a card or bank account on a recurring time period. You can use Subscriptions to charge buyers, customers, or even merchants. Example use cases for Subscriptions: - Charging buyers a recurring monthly fee to access a gym or health club - Charging buyers an annual membership fee for services or goods rendered - Charging merchants a monthly or annual fee for using your software - Charging buyers a recurring monthly fee to access a gym or health club - Charging buyers an annual membership fee for services or goods rendered - Charging merchants a monthly or annual fee for using your software For more details, read [the full guide](/guides/subscriptions). --- # Send Receipts on Payment Links Source: https://docs.finix.com/release-notes/2024/08/send-receipts-on-payment-links ![Payment Link Receipts 01](/assets/release-notes-2024-08-payment-link-receipts-01.589bd40dd5d9dbf985ad85a375eb84fd26a8902d8656f8ab237aaa3fcd5e6590.08ff7529.png) ![Payment Link Receipts 02](/assets/release-notes-2024-08-payment-link-receipts-02.61175da19ab667da4a1a9ca98f94fb9d9ed9aab41d7f282e3e27c86a21ff63b4.08ff7529.png) You can now add receipts to Payment Links. You can also optionally have a copy of the receipt be sent to yourself. When a buyer is completing their transaction via Payment Link, they'll input the email address or phone number of where to send the receipt. --- # Merchant Update Request Improvements Source: https://docs.finix.com/release-notes/2024/09/merchant-update-request-improvements To simplify update requests during Seller Merchant onboarding, Finix introduced several new features: - A new "Update Requested" state for your Merchants, making it easy to see Merchants with outstanding requests - New outcome codes, making it easy to see the specific documents and data updates Finix is requesting - The ability for your Merchants to make update requests using their original Onboarding Forms - Dashboard and email notifications to keep your team in the loop (e.g., "Merchant Updates Requested") - A new "Update Requested" state for your Merchants, making it easy to see Merchants with outstanding requests - New outcome codes, making it easy to see the specific documents and data updates Finix is requesting - The ability for your Merchants to make update requests using their original Onboarding Forms - Dashboard and email notifications to keep your team in the loop (e.g., "Merchant Updates Requested") For more details, read [the full guide](/guides/platform-payments/onboarding-sellers/seller-onboarding-update-requests). ![Merchant Update Requests Notifications](/assets/release-notes-2024-09-update-requests-notifications.8198864b9507b16bc4a5fce475822cc6b1821fa4f414d1b0c1addf4b03458cf4.08ff7529.png) ![Merchant Update Requests Merchant Detail Page](/assets/release-notes-2024-09-update-requests-business-merchant-page.77f1248559f5af54a325c375b8d1fb560edfb8097348f5d673c288a3758a1c71.08ff7529.png) ![Merchant Update Requests Business Info Page](/assets/release-notes-2024-09-update-requests-business-info.0690fe15b52fd4af806bef455ce7214972d56bd0a943f98c315ebf497995462b.08ff7529.png) --- # New Sidepanels on Payment and Authorization Pages Source: https://docs.finix.com/release-notes/2024/09/new-sidepanels-on-payment-and-authorization-pages ![New Side Panels 01](/assets/release-notes-2024-09-side-panel-01.36e6e3f19bf9ced83cce2ed22641341b034b4c512e43de7dc94d5c682661b615.08ff7529.png) ![New Side Panels 02](/assets/release-notes-2024-09-side-panel-02.f84dc46fd7d286f484ec65670e2f341752d39d9359fb1ee50db4d95e0a7f6ef3.08ff7529.png) We added sidepanels to the Payment and Authorization pages. The sidepanels allow you to quickly view information about each payment without going to a different page. This can be useful for reviewing transactions quickly. --- # QR Codes for Payment Links Source: https://docs.finix.com/release-notes/2024/09/qr-codes-for-payment-links ![Payment Links QR Code](/assets/release-notes-2024-09-qr-code.466eedf0761d33d0b4d5701770a99684bff9edb408387561650cfb7f1f75c877.08ff7529.png) We've added an option to generate a QR Code on a payment link. Sellers can choose to either copy the image or download it. --- # Subscription Billing Updates Source: https://docs.finix.com/release-notes/2024/10/subscription-billing-updates ## View all payments for a subscription ![Subscription Payment List Page](/assets/release-notes-2024-10-subscription-billing-01.170b2f46adc9e9bdfe2ed3d37f255fc9c105132f86fb8d33bed74ec855c21c32.08ff7529.png) You can now see all the Payments for a Subscription on the Finix Dashboard. When you click on an individual Subscription, there will be a new Payments Tab. ## Buyer Page now shows all subscriptions for a buyer ![Subscription Buyer Subscriptions](/assets/release-notes-2024-10-subscription-billing-02.89e7c47ae3a457c81f3321605d0af291f4cba674955e9404a98fff2d26719f5e.08ff7529.png) When you click on a Buyer, you will now see all the Subscriptions associated to them. This can be a time saver for customer support or modifying subscriptions for a Buyer. --- # New Merchant Filters Source: https://docs.finix.com/release-notes/2024/11/new-merchant-filters We've extended our [Merchant Filters](/api/merchants/listmerchants) by: - `country`: Filter by the Merchant's country (ISO 3166 alpha-3). - `currency`: Filter by the Merchant's currencies (ISO 4217). - `identity_role` Filter by the `identity_roles` of the Merchant's `identity`. --- # New Transfer Filters Source: https://docs.finix.com/release-notes/2024/11/new-transfer-filters We've extended our [Transfer Filters](/api/transfers/listtransfers) to now all you to filter by: - `bank_return_reason_code`: Filter bank reversals by ACH Return Code. Use comma-separation to query for multiple values. - `buyer_business_name`: Filter by the Buyer Identity's business name (exact match). - `buyer_business_name.like`: Filter by the Buyer Identity's business name (partial match). - `buyer_doing_business_as`: Filter by the Buyer Identity's Doing Business As (exact match). - `buyer_doing_business_as.like`: Filter by the Buyer Identity's Doing Business As (partial match). - `buyer_identity_first_name`: Filter by the Buyer Identity's first name (exact match). - `buyer_identity_first_name.like`: Filter by the Buyer Identity's first name (partial match). - `buyer_identity_id`: Filter by the Buyer Identity's ID. - `buyer_identity_last_name`: Filter by the Buyer Identity's last name (exact match). - `buyer_identity_last_name.like`: Filter by the Buyer Identity's last name (partial match). - `buyer_identity_name`: Filter by the Buyer Identity's full personal name (exact match). - `buyer_identity_name.like`: Filter by the Buyer Identity's full personal name (partial match). - `bank_return_reason_code`: Filter bank reversals by ACH Return Code. Use comma-separation to query for multiple values. - `buyer_business_name`: Filter by the Buyer Identity's business name (exact match). - `buyer_business_name.like`: Filter by the Buyer Identity's business name (partial match). - `buyer_doing_business_as`: Filter by the Buyer Identity's Doing Business As (exact match). - `buyer_doing_business_as.like`: Filter by the Buyer Identity's Doing Business As (partial match). - `buyer_identity_first_name`: Filter by the Buyer Identity's first name (exact match). - `buyer_identity_first_name.like`: Filter by the Buyer Identity's first name (partial match). - `buyer_identity_id`: Filter by the Buyer Identity's ID. - `buyer_identity_last_name`: Filter by the Buyer Identity's last name (exact match). - `buyer_identity_last_name.like`: Filter by the Buyer Identity's last name (partial match). - `buyer_identity_name`: Filter by the Buyer Identity's full personal name (exact match). - `buyer_identity_name.like`: Filter by the Buyer Identity's full personal name (partial match). These filters will allow you to build a much more rich experience if you are integrating via API. If you are using the Finix dashboard, these filters are ready to be used now. --- # Apply custom fees to merchants Source: https://docs.finix.com/release-notes/2024/12/apply-custom-fees-to-merchants Software Platforms and Marketplaces now have the ability create custom fees to their sub-merchants. This is helpful if you have a custom charge you want to pass through to your sub-merchants through Finix's settlement engine. The fee would be paid out as part of your monthly residual after subtracting Finix's costs. To learn how to use this feature, visit our [API reference](/api/fees/createfee). --- # Additional Merchant Fees Now Available Source: https://docs.finix.com/release-notes/2025/01/additional-merchant-fees-now-available ![Instant Payouts](/assets/feb-2025-new-merchant-fees.b02ed51ff91604b4d78d2c7fe17ac51f84993641fa79ae3fb7990f9398d3ff56.08ff7529.svg) For software platforms and marketplaces, we've added new fees available to charge `merchants`. You can view all our fees on our [Fee Profile](/api/fee-profiles/createfeeprofile) API reference or on our Dashboard when you create a Fee Profile. ## Support for fees on for NOCs on ACH sales and Refunds We've added the ability to set fees to merchants if there is a Notice of Change (NOC) on an ACH Sale or Refund. ## Support for fees on NOCs for Settlement Funding Transfers We've added support to charge for Notice of Change (NOC) events on Settlement Funding transfers. These are the payouts issued to your merchants that may fail completely (ACH Return) or alternatively result in a NOC. ## Support for Fees on Settlement Funding Transfers (Next Day ACH, Same Day ACH, Instant Payouts) We've added support to create Settlement Funding Transfer fees to your merchants. You can set different rates for: - **Next Day ACH:** This is our standard offering for payouts. - **Same Day ACH:** Same Day ACH allows merchants to be funded the same day a Settlement is Approved. - **Instant Payouts:** If a merchant requests an instant payout, Finix can apply a basis point or fixed fee for this event. - **Next Day ACH:** This is our standard offering for payouts. - **Same Day ACH:** Same Day ACH allows merchants to be funded the same day a Settlement is Approved. - **Instant Payouts:** If a merchant requests an instant payout, Finix can apply a basis point or fixed fee for this event. ## Fees for Transfers created via Subscription Billing If a merchant uses Finix's subscription billing product to create `subscriptions`, you can now charge for this event. You can set different rates for ACH, Card, and EFT `subscriptions.` The fees are applied on `SUCCEEDED` `transfers`. --- # Instant Payouts for Settlements Source: https://docs.finix.com/release-notes/2025/01/instant-payouts-for-settlements ![Instant Payouts](/assets/feb-2025-instant-payouts-confirmation.08ce862c8cbf95d00ff8e52cc1f33b158a913e3e017c1c1355a84436fc02a87e.08ff7529.svg) This is a new feature for merchants who need quick access to funds from card transactions. Whether it's to cover unexpected expenses or improve cash flow, merchants can now request instant settlements directly to a specified debit card. ## Key Benefits - **Immediate Access to Funds:** Get funds instantly instead of waiting days for standard settlements specifically from card transactions. - **Flexible Usage:** Take control of your cash flow with the following pricing. - **Immediate Access to Funds:** Get funds instantly instead of waiting days for standard settlements specifically from card transactions. - **Flexible Usage:** Take control of your cash flow with the following pricing. ## Pricing Details 1.5% per payout. ## How to Enable Contact your Finix Representative on or after February 1, 2025 to initiate a risk review. Once approved, the feature will be activated in your dashboard, allowing you to request instant settlements at the rate above. If you are interested in getting activated earlier please contact your Support Representative. --- # New Dynamic Fee Workflows Source: https://docs.finix.com/release-notes/2025/01/new-dynamic-fee-workflows ## Supplemental Fees You can now create a `supplemental_fee` at the time of `transfer` creation or `authorization` capture. This allows you to charge interchange plus pricing and for customer to calculate and charge an additional fee for each transfer. You can view how to create a supplemental fee using our API reference for a [Transfer](/api/transfers/createtransfer) or [Authorization](/api/authorizations/createauthorization). ## Attaching a Fee Profile to a Transfer or Authorization Capture Ability to provide which fee_profile to use at time of transfer creation or authorization capture. This allows you to create multiple fee profiles and choose which one they want to apply for each transfer. If not provided fee_profile will default to the on assigned to the merchant You can view how to attach a Fee Profile using our API Reference for a [Transfer](/api/transfers/createtransfer) or [Authorization](/api/authorizations/captureauthorization). --- # Passing through Dues and Assessments now Available Source: https://docs.finix.com/release-notes/2025/01/passing-through-dues-and-assessments-now-available ![Instant Payouts](/assets/feb-2025-interchange-dues-assessments.a892a0b354e6d4bfb10cbfeff07cb692e05d6d2ec71601efbdd891dcf459e99b.08ff7529.svg) Software Platforms and Marketplaces can now choose to pass through Dues and Assessments to sub-merchants. This functionality is available in our Dashboard or via API. `API Details` To use our API functionality, you can simply pass in `"charge_dues_asssessments": true` in our [`Fee Profile`](/api/fee-profiles/createfeeprofile). This functionality is only available in our `FINIX_V1` Processor. --- # Account Updater Improvements Source: https://docs.finix.com/release-notes/2025/02/account-updater-improvements ![Account Updater Logs](/assets/account_updater_logs.4b956bb80696b92aecee6fe9ba870d9a01da83086b242ba30fc89915130f99a8.08ff7529.svg) Card Account Updater is a service offered by the card brands. When a card expires or is replaced, the card brands will push the new information to Finix’s platform, keeping your customer’s payment data up-to-date. ## Key Benefits - Minimize failed transactions - Ensure uninterrupted services, helping sub-merchants retain customers - Minimize failed transactions - Ensure uninterrupted services, helping sub-merchants retain customers ## New Improvements - Ability to set net-new payment instruments to be enabled for Account Updater or as specified - You do not need to submit an Account Updater batch. Finix will handle updates automatically. - Ability to set net-new payment instruments to be enabled for Account Updater or as specified - You do not need to submit an Account Updater batch. Finix will handle updates automatically. ## Pricing Details $0.55 USD; $0.80 CAD per card updated unless a different price is specified in your current contract. ## How to Enable Contact our support team to enable Account Updater for net-new payment instruments or historical ones. To learn more about Account Updater, visit our [Account Updater Guide](/guides/after-the-payment/account-updater). --- # Dashboard Enhancements Source: https://docs.finix.com/release-notes/2025/02/dashboard-enhancements ## Transaction Flow available on Payments and Authorizations ![Transaction Flow](/assets/feb-2025-transaction-flow.422d3b619d22d7b3b3324db3dbd83b4201f78c7abaf9b6c7d1e8f4ae410a725c.08ff7529.png) Merchants can now easily see a Transaction Flow when viewing a Payment. This allows for an easier understanding of where a Payment is and whether a Merchant's `Settlement` was Approved. ## Payment Links can now be Edited after being Created ![Transaction Flow](/assets/feb-2025-edit-payment-links-dropdown.1acecc8eaeb0f150c7503685da84f90ab0564a8e0edd964375c993f58f038e5b.08ff7529.png) Merchants can now easily edit Payment Links. For all Payment Links, you can now edit them. Depending on the type of payment link and state different fields are editable. This can be handy for merchants who want to rename Payment Links and especially for Single Use Payment Links which have more editable fields. --- # Network Tokenization Source: https://docs.finix.com/release-notes/2025/02/network-tokenization ![Account Updater Logs](/assets/feb-2025-network-tokens.e058d80505c64bbf7b29fc456db4a7befbb1d0d028132f5c214b0642cf63688b.08ff7529.svg) Network tokens replace card information with a randomized string of letters and numbers when sending data to a card network. When a card is expired or replaced, the card information is automatically updated. ## Key Benefits - **Increased Authorization Rates:** Network tokens can increase authorization rates, leading to more approved payments and higher revenue for your business. - **Lower Interchange Fees:** Card schemes, such as Visa, often charge lower interchange fees on transactions utilizing network tokens. - **Pricing Details:** $0.15 USD; $0.25 CAD per card tokenized by the card networks unless a different price is specified in your current contract. - **Increased Authorization Rates:** Network tokens can increase authorization rates, leading to more approved payments and higher revenue for your business. - **Lower Interchange Fees:** Card schemes, such as Visa, often charge lower interchange fees on transactions utilizing network tokens. - **Pricing Details:** $0.15 USD; $0.25 CAD per card tokenized by the card networks unless a different price is specified in your current contract. ## How to Enable Contact our support team to enable Account Updater for net-new Payment Instruments or historical ones. To learn more about Network Tokenization, visit our [Network Tokenization Guide](/guides/after-the-payment/network-tokens) --- # Streamlined Checkout Experience for Pax Terminals Source: https://docs.finix.com/release-notes/2025/02/streamlined-checkout-experience-for-pax-terminals ## Faster and More Intuitive Transactions on Standalone Mode Standalone Mode Checkout Screen Standalone Mode Review Screen We've redesigned the core checkout flow for speed and ease of use. From initiating a sale to completing the transaction, the process is intuitive and efficient. For a full breakdown, see the [Standalone Mode enhancements guide](/guides/in-person-payments/standalone-terminals/standalone-terminals-experience). ## Enhanced Payment Confirmation for both Standalone and Cloud Integrations Standalone Mode Amount Screen Standalone Mode Processing Screen Standalone Mode Approval Screen Standalone Mode Thank You Screen Clearer on-screen confirmations and receipt options ensure both you and your customers have a seamless checkout experience. --- # Subscription Billing Available to All Customers Source: https://docs.finix.com/release-notes/2025/02/subscription-billing-available-to-all-customers ![Subscriptions Creation](/assets/feb-2025-subscriptions.fb5646897c9806999c5c12a64c7794154f2de2b2c3ee129e327a3e83de79686b.08ff7529.svg) Subscription Billing allows you to charge your customers for a product or service at regular intervals. ## New features include - **Set Future Start Dates:** Schedule subscriptions to start at a later date. - **Define Subscription Duration:** Set a fixed number of billing cycles. - **Subscription Receipts:** If receipts are turned on, buyers will receive consistent, detailed receipts for each billing cycle. - **Billing Credits:** Make one-time adjustments to an upcoming subscription payment without impacting the entire subscription. - **Trial Phase Enhancements:** Clearer visibility into trial periods and how they transition to paid cycles. - **Next Billing Date Visibility:** Users can now easily see when the next charge will occur. - **Set Future Start Dates:** Schedule subscriptions to start at a later date. - **Define Subscription Duration:** Set a fixed number of billing cycles. - **Subscription Receipts:** If receipts are turned on, buyers will receive consistent, detailed receipts for each billing cycle. - **Billing Credits:** Make one-time adjustments to an upcoming subscription payment without impacting the entire subscription. - **Trial Phase Enhancements:** Clearer visibility into trial periods and how they transition to paid cycles. - **Next Billing Date Visibility:** Users can now easily see when the next charge will occur. ## How to Enable You can use Subscriptions in your dashboard or use our API. Please refer to the Subscription Guidelines for important compliance information. To learn more about Subscription Billing, visit our [Subscription Guide](/guides/subscriptions/subscriptions-quickstart). --- # Multi Factor Authentication (MFA) Required Starting March 1st Source: https://docs.finix.com/release-notes/2025/03/multi-factor-authentication-mfa-required-starting-march-1st ![MFA Setup](/assets/mfa_set_up.9326ed5d173638329960baad55f3d2b89120c6d6447825033e6548da5c2708e3.08ff7529.svg) At Finix, we prioritize the security of your account and sensitive information. To further strengthen account protection, we will begin enforcing Multi-Factor Authentication (MFA) starting on March 1st. MFA adds an extra layer of security by requiring not only your username and password, but also a second verification step. This is essential in preventing unauthorized access and ensuring the safety of your data. ## Finix offers the following options for MFA - **SMS (Text Message):** Finix supports an SMS option for users to login. - **Mobile Authenticator:** You can also use a Mobile Authenticator App such as Google Authenticator or Okta Verify to login. - **SMS (Text Message):** Finix supports an SMS option for users to login. - **Mobile Authenticator:** You can also use a Mobile Authenticator App such as Google Authenticator or Okta Verify to login. ## Before March 1st 1. Please enable MFA for your account by following the simple steps outlined in this [guide](/guides/managing-operations/managing-team-members/multi-factor-authentication). 2. If your merchants log into the Finix Dashboard, we recommend pass along this [guide](/guides/managing-operations/managing-team-members/multi-factor-authentication) or similar content and communicate that MFA will be required to login starting on March 1st. ## After March 1st Anyone who does not have MFA enabled will be prompted to do so when they login. If you have any questions or need assistance setting up MFA, please contact us at [support@finix.com](mailto:support@finix.com). If you have any questions or need assistance setting up MFA, please contact us at [support@finix.com](mailto:support@finix.com). --- # Manual Entry of Card Details on the Terminal for POS Integration Source: https://docs.finix.com/release-notes/2025/04/manual-entry-of-card-details-on-the-terminal-for-pos Not every transaction starts with a tap or swipe. Manual entry gives your business the flexibility to accept payments even when cards can’t be read physically. With Finix, you can enable secure, network-compliant manual card entry right on the terminal—ideal for phone orders, card damage, or remote checkout scenarios. In this guide, you can learn how to manually enter card details on the terminal when integrated via API. div div img div img div img div img --- --- # Residual Settlements now available on the Finix Dashboard Source: https://docs.finix.com/release-notes/2025/04/residual-settlements-now-available-on-the-finix-dashboard If you are a platform, you can now see your residuals on the Finix Dashboard. This updated system will be used for all future residual calculations and payouts. Note: Some customers will remain on the Net Profit Report. Please contact your Finix Representative if you have questions. We’re rolling out a new way of calculating residuals this month and going forward. This updated system will be used for all future residual calculations and payouts. ## What’s changing? Instead of using the Net Profit Report, Finix will now generate Residual Settlements that contain: - Merchant Fees: Fees used to bill your merchants for transaction costs on Finix. These can be set using the Merchant Fee Profile or passed in per transaction via API. - Finix Costs: Costs for using the Finix system for acquiring. These are defined in your legal agreement (MSA) with Finix. - Merchant Fees: Fees used to bill your merchants for transaction costs on Finix. These can be set using the Merchant Fee Profile or passed in per transaction via API. - Finix Costs: Costs for using the Finix system for acquiring. These are defined in your legal agreement (MSA) with Finix. ## What reports are available? Finix will provide a report to help you analyze your billing settlements: - **Residual by Merchant:** Breaks down residuals by individual merchants. ## How do I access residual settlements? There will be a new Company Financials tab under Settings → Company Page. Within this tab, you’ll find four sections: - **Residual Settlements:** Lists all residual calculations (previously provided via the Net Profit report). - **Cost Profile:** Shows the rates defined in your MSA. - **Service Agreement:** Displays your customer type. - **Billing Settings:** View your billing configuration. - **Residual Settlements:** Lists all residual calculations (previously provided via the Net Profit report). - **Cost Profile:** Shows the rates defined in your MSA. - **Service Agreement:** Displays your customer type. - **Billing Settings:** View your billing configuration. --- # Sample Ecommerce Application Source: https://docs.finix.com/release-notes/2025/04/sample-ecommerce-application To help make it easier to integrate to Finix, we've created an example e-commerce application. This Next.js web app demonstrates how to integrate it Finix using either: - **Finix Hosted Checkout** - Redirects customers to a secure Finix-hosted checkout page - **Finix Tokenization Form** - Embeds the Finix Tokenization Form directly in the website - **Finix Hosted Checkout** - Redirects customers to a secure Finix-hosted checkout page - **Finix Tokenization Form** - Embeds the Finix Tokenization Form directly in the website Sample Accept a Payment App Sample e-commerce application that shows how to use Finix's checkout forms and how to take a payment with our Token Forms. --- # Tokenization Form Improvements Source: https://docs.finix.com/release-notes/2025/04/tokenization-form-improvements We’re excited to announce updates to our finix.js library launching on April 15. These improvements apply to our Tokenization Forms—BankTokenForm, CardTokenForm, and TokenForm—as we move from version `1.2.3` to `1.3.1`. **What’s New in Version `1.3.1`:** - **Bank Account Double Confirmation:** An optional setting to help reduce ACH returns caused by mistyped account numbers. - **"Bank Code" Renamed to "Routing Number":** Update to reflect more common U.S. terminology. - **Improved Routing Number Validation:** Ensures 9-digit numeric input only. - **Dark Mode Support:** Built-in integration with dark-themed sites. - **CSS Enhancements:** Minor enhancements for improved default styling. - **Bank Account Double Confirmation:** An optional setting to help reduce ACH returns caused by mistyped account numbers. - **"Bank Code" Renamed to "Routing Number":** Update to reflect more common U.S. terminology. - **Improved Routing Number Validation:** Ensures 9-digit numeric input only. - **Dark Mode Support:** Built-in integration with dark-themed sites. - **CSS Enhancements:** Minor enhancements for improved default styling. If you're not using a locked version of the library, this update will roll out automatically. - Current Version: `1.2.3` - New Version: `1.3.1` --- # Updated Finix Documentation Site Source: https://docs.finix.com/release-notes/2025/04/updated-finix-documentation-site We've made improvements to our documentation site: - Improved search - Improved navigation - Improved styling - Dark mode - Leave feedback on pages - Improved search - Improved navigation - Improved styling - Dark mode - Leave feedback on pages ## Improved Search - Searching is now lightning-fast, giving you results within moments of typing - You'll now have a large area to view and pick between search results - You can filter search results by Guides versus API Reference, as well as apply detailed API Reference filters - Access search by selecting the search bar on the top-left, or typing `/` or `Cmd + K` on your keyboard - Searching is now lightning-fast, giving you results within moments of typing - You'll now have a large area to view and pick between search results - You can filter search results by Guides versus API Reference, as well as apply detailed API Reference filters - Access search by selecting the search bar on the top-left, or typing `/` or `Cmd + K` on your keyboard ![Docs Search 1](/assets/docs-search-1.a52396595a2e5f9efe30880f08c33d7c27de935f950ac8ac47c3757838723a77.08ff7529.png) ![Docs Search 2](/assets/docs-search-2.c9d372f1b9b7db492e5190679a0f37a2b858466a1010aaa27a61e816d2e76c73.08ff7529.png) ![Docs Search 3](/assets/docs-search-3.9a72b53efdb99978d27493c1f8b047a44f04d428812b4a25bb1284819e903eb7.08ff7529.png) ## Improved Navigation - We've re-organized all our content into sections that are clearer and easier to follow - We've added cards on all section homepages, making it easier for readers to find all topics - We've re-organized all our content into sections that are clearer and easier to follow - We've added cards on all section homepages, making it easier for readers to find all topics ![Docs Navigation 1](/assets/docs-navigation-1.84521a0499ca061c68bfe34775f0098243d6468614eac44cf25960d9b053aad6.08ff7529.png) ## Improved Styling - We've improved styling across our entire docs site, making the reading experience easier and more consistent - These styling improvements include code blocks, section titles, and more - We've improved styling across our entire docs site, making the reading experience easier and more consistent - These styling improvements include code blocks, section titles, and more ![Docs Styling 1](/assets/docs-styling-1.332d410b170be3d00eaf5a8f62227f20c06254953f4123e67f5a3652eabed2c0.08ff7529.png) ## Dark Mode - Now, you can read our docs in dark-mode - To do so, toggle between dark-mode and light-mode with the icon in the upper-right corner - Now, you can read our docs in dark-mode - To do so, toggle between dark-mode and light-mode with the icon in the upper-right corner ![Docs Light Mode 1](/assets/docs-light-mode-1.add99b086878b719e5cc10d018873101df317c9450086653c4973186b239b299.08ff7529.png) ![Docs Dark Mode 1](/assets/docs-dark-mode-1.b63abcd7aad38ae359f64269118ab6f30e9a2a89df5ed85a98ca6f0d7167e859.08ff7529.png) ## Leave Feedback on Pages - Now, you can leave feedback directly on the bottom of each page - This feedback goes directly to our team for review, and we'll reach out if needed - Now, you can leave feedback directly on the bottom of each page - This feedback goes directly to our team for review, and we'll reach out if needed ![Docs Feedback 1](/assets/docs-feedback-1.37923c75dd161b00a2e528c71107a9c4a64218712da0d1a32b277025f37ac5d5.08ff7529.png) --- # Virtual Terminal Updates Source: https://docs.finix.com/release-notes/2025/05/virtual-terminal-updates ![Virtual Terminal Updates](/assets/release-notes-2025-05-virtual-terminal.bee5efdde5c751ddecc338341a0b1e683dc0dcd5029bd9c3b987daecec58f66a.08ff7529.png) ## Surcharging You can now use surcharging on the Virtual Terminal. Our Virtual Terminal supports surcharging on online and in-person payments via a connected POS Terminal. Note: Surcharging only works on Credit Cards and if the merchant is enabled for surcharging. To learn more about Surcharging, see our [Surcharge Fees guide](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/surcharge-fees). ## Statement Descriptors On the Virtual Terminal, you can now pass in Custom Statement Descriptors. These statement descriptors show up on your buyer's bank statement and may help them identify the purchase. Using statement descriptors may lead to less support tickets or chargebacks. ## Device Configuration Overrides You can now override the device configuration for a specific transaction. This is useful if you need to change the device configuration for a specific transaction. For additional details, see our [Device Configuration Overrides Guide](/guides/in-person-payments/device-capabilities/overrides). Device configuration overrides is supported for the following features: - Prompt for Tip If there is a configuration override that is not listed above, please reach out to [Finix Support](mailto:support@finix.com) to submit the request. --- # Updated Dashboard Sidebar Source: https://docs.finix.com/release-notes/2025/06/updated-dashboard-sidebar ![Sidebar Gif](/assets/new-sidebar.80009c556ef20a85229b9fbd182c25759c4c701980f754d56c8da6781b26a316.5e9145fa.gif) **Key Updates:** - **Collapsible sidebar allows for more space on smaller screens:** You can now collapse the sidebar navigation and give yourself more horizontal space to view the dashboard. This can be handy for investigating transactions or seeing more columns on certain pages. - **Ability to upload a small icon is now available:** If you use a white-labeled dashboard, you can now upload a smaller icon logo to be displayed when the sidebar is collapsed. We recommend uploading a square icon logo. We will use a generic unbranded icon if you don't upload one. ## Steps to upload a logo for the collapsed sidebar ![Branded Minimized Logo](/assets/release-notes-2025-05-minimized-sidebar-icon.162b941abf70baeb1e8be599f40c3a56cb8672594382d5cfc0ecca06b6457cff.08ff7529.png) Follow the steps below to upload a icon for the collapsed sidebar. If you don't upload one, we will use a generic unbranded icon for your merchants. 1. Head towards the Settings > Company > Branding Page. 2. Upload a square logo in the Icon Logo section. 3. Save and review your image once you collapse the sidebar. ## Standalone Mode Filters You can now filter transactions on the Standalone Mode. This is useful if you need to find a specific transaction or see transactions for a specific merchant. For additional details, see our [Standalone Mode Filters Guide](/guides/in-person-payments/device-capabilities/standalone-mode-filters). Below is a gif showing how to filter transactions on the Standalone Mode. img ## Custom Fields to Receipts You can now add custom fields to receipts. This allows you to add custom data fields—like invoice numbers — to printed receipts directly through the API. This enhancement gives you more flexibility to tailor receipts to your business needs. For example, you can now include fields like "Invoice Number: 12345" directly on the printed receipt. For additional details, see our [Custom Fields to Receipts Guide](/guides/in-person-payments/device-capabilities/receipts#adding-custom-fields-to-receipts). --- # Updated WooCommerce Plugin Source: https://docs.finix.com/release-notes/2025/06/updated-woocommerce-plugin ![Subscription Change Plan](/assets/release-notes-2025-06-24-woocommerce.b1e536aff75918451824406e1cf88825550417b23d19a627ca3e91afa9d4b60c.08ff7529.png) Our Finix for WooCommerce plugin allows merchants to have fast, flexible, and reliable payments with Finix. Whether you're launching a new shop or scaling an existing one, We makes it easy to accept payments and manage orders. In our latest release, we've updated our plugin to version `1.2.0`. This plugin comes with a number of updates including: - **Google Pay Support:** You can now use Google Pay alongside our Card, Bank, and Apple Pay options. - **$CAD Support:** If you are a merchant in Canada, you can use our WooCommerce Plugin to process $CAD payments. - **Performance improvements and bug fixes**: We've updated a number of our internals of the application to ensure a smoother experience for merchants and buyers. To download and install our plugin, you can [install it from WordPress.org](https://wordpress.org/plugins/finix-for-woocommerce/) or read our [guide](/additional-resources/plugins/woocommerce-plugin). If you have auto updates enabled the plugin should update automatically depending on your WordPress settings. --- # Buyer Fees now available on our Payment Links and Checkout Forms Source: https://docs.finix.com/release-notes/2025/07/buyer-fees-now-available-on-our-payment-links-and-checkout ## Surcharging You can now surcharge on our Payment Links and Checkout Forms. Surcharge fees are available to sellers to help cover the cost of processing payments. Note: Surcharging only works on Credit Cards and if the merchant is enabled for surcharging. To learn more about Surcharging, see our [Surcharge Fees guide](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/surcharge-fees). --- # Convenience Fees Source: https://docs.finix.com/release-notes/2025/07/convenience-fees You can now use Convenience Fees on our Payment Links and Checkout Forms. A convenience fee is a Buyer Charge that can only get passed to buyers when the seller is providing a method of payment (usually internet or over the phone) different from its standard payment channel (historically mail or in-person). To learn more about Convenience Fees, see our [Convenience Fees guide](/guides/online-payments/payment-features/buyer-charges/card-brand-fees/convenience-fees). --- # Updated Postman Collection Source: https://docs.finix.com/release-notes/2025/08/updated-postman-collection ![Postman Collection](/assets/release-notes-2025-09-05-finix-postman.bdc7ea178e81a1f771386da4ecede4296bd861e5bb0bbac8c11bba3d0a2374b8.08ff7529.png) We have updated our **API Reference** Postman collection to include all the examples available in Finix's API documentation. This enhancement allows the Postman collection to serve as a standalone API reference. To explore specific examples, expand the requests. For instance, you can expand the "POST Create a Payment Instrument" request to view example requests for creating cards, bank accounts, and more. ![Postman API Reference Collection](/assets/release-notes-2025-09-05-postman-api-ref.f7995f76f64d3523de1eccfb564e3dd59ac7f8cf310bbf7c52c61cdcfdaaa589.08ff7529.png) You can access [our Postman collection](https://www.postman.com/finixpayments/finix-api/collection/s2go2pn/finix-api-reference). --- # Dispute Updates Source: https://docs.finix.com/release-notes/2025/09/dispute-updates ## Improved WON / LOST Updates We've improved Dispute statuses to update more frequently to WON or LOST. You'll see Disputes update quicker than in the past. You can read more about [winning and losing disputes](/guides/after-the-payment/disputes/how-disputes-work#winning-and-losing-disputes). ## Updated Filters ![Disputes List](/assets/release-notes-2025-09-05-disputes-list.8b3f437a3ef08e071974fb95bdba72dd2ac72dd8762a3cad6e1f88efeee9eee1.08ff7529.png) We've updated the default landing page of disputes to automatically filter which disputes need a response. This makes it easier to focus on which disputes need to be challenged or accepted. ## Ability to Submit a Partial Dispute Response ![Disputes Partial Response](/assets/release-notes-2025-09-05-disputes-partial-response.212ab4fd34aa511951f8f25837d1e9775c54cd7a7766bf20cc8b1d689a8ec98f.08ff7529.png) We now allow you to respond to partial dispute amounts. This can be helpful if you disagree with the amount of the inquiry or chargeback, but acknowledge that part of it is valid. ## Including a previously initiated refund when Responding to a Dispute ![Disputes Refund](/assets/release-notes-2025-09-05-disputes-refund.892261e3ee06670b3515332f826428e884ff3eaa155c2d48124f7fe6e99fd73b.08ff7529.png) Specifying a refund when responding to a dispute can be useful when you refunded the cardholder but they separately opened up a dispute with their bank. For both full dispute amounts and partial dispute amounts, you can specify if a refund was already provided to the cardholder. We'll submit this information to the card networks as part of the response. If you don't see the refund, you can manually link a refund. This may be applicable if you did an unreferenced refund. --- # Google Pay support on Payment Links and Checkout Forms Source: https://docs.finix.com/release-notes/2025/09/google-pay-support-on-payment-links-and-checkout-forms ![Google Pay Payment Link](/assets/payment-links-google-pay.164e0f990a5579fdce3f7049c0e39a73c850fb8922ccb7df6b7ded650a4b9e3c.08ff7529.png) We've updated our Payment Links and Checkout Forms to support Google Pay. For Payment Links, you'll see an additional option under Allowed Payment Methods in our Dashboard to let buyers pay using Google Pay. --- # Receipt Improvements Source: https://docs.finix.com/release-notes/2025/09/receipt-improvements We've updated the layout of our receipts for Payments, Refunds, and Authorizations. These include changes to the email and PDF generated by Finix. --- # Subscription Confirmation Emails Now Available Source: https://docs.finix.com/release-notes/2025/09/subscription-confirmation-emails-now-available ![Subscription Confirmation](/assets/subscription-confirmation.e0a096c2db6e6cc582e51701ed3312fed77982ce81b0f8f93ed697cdad62f3f4.08ff7529.png) We've updated our Subscriptions and Subscription Links to allow buyers to receive a confirmation email. Learn more about [Subscription Notifications](/guides/subscriptions/subscription-notifications). --- # Interac Debit support Now Available Source: https://docs.finix.com/release-notes/2025/10/interac-debit-support-now-available ![Finix Interac](/assets/finix-interac.fef309941ac684a9c2e1896855d66f8042958eb82feb299ab04ae8979c33d1cd.fec90461.webp) We've released support for Interac Debit on our PAX A800 and A920 Pro. Customers and merchants can now take payments in Canada with Interac, Visa, Mastercard, Discover, and American Express. Finix continues to grow its presence in Canada through local hiring, new partnerships, and long-term investment to help more businesses modernize their payment infrastructure. To learn more about Interac see our [joint press release](https://www.interac.ca/en/content/news/finix-integrates-with-interac-to-expand-its-payment-options-in-canada/) or our [documentation](/guides/regional-considerations/canada#interac-payments). --- # Dispute Evidence Files can now be Deleted Source: https://docs.finix.com/release-notes/2025/11/dispute-evidence-files-can-now-be-deleted We have released the ability to delete dispute evidence files before the dispute evidence has been submitted to the card networks. See [API documentation](/api/disputes/deletedisputeevidence). --- # PAX D135 Sample Apps for Android and iOS Source: https://docs.finix.com/release-notes/2025/11/pax-d135-sample-apps-for-android-and-ios We have released updated versions of our sample apps showcasing how to integrate our Android and iOS D135 SDKs. You can use these apps to speed up your development. - [Android Github Sample App](https://github.com/finix-payments/finix-pax-mpos-android-sdk-demo-app) - [iOS Github Sample App](https://github.com/finix-payments/finix-pax-mpos-ios-sdk-demo-app) --- # finix.js v2 update Source: https://docs.finix.com/release-notes/2025/12/finixjs-v2-update We're excited to introduce **Finix.js v2**, a major upgrade to our client-side tokenization library. This release focuses heavily on performance, security, modern web compatibility, and developer experience. With a **10× smaller bundle**, simplified configuration, improved validation, and a fully refreshed UI system, v2 makes it easier than ever to build secure, PCI-compliant payment flows across modern web applications. ## What's New in v2 ### 🚀 10× Smaller Bundle Size Faster load times, reduced bandwidth usage, and dramatically improved behavior on slower networks and mobile devices. ### ✔️ Improved Form Validation Enhanced client-side validation, including improved international card validation, bank-account validation, and real-time error feedback. #### 🌐 Shadow DOM and Web App Support Full compatibility with web components, micro-frontends, and modern reactive frameworks. #### 🎨 New Pre-Built Themes + Dark Mode Cleaner UI out of the box with theme presets (`finix`, `amethyst`, `sapphire`, etc.) and complete dark-mode support. ### 🛠️ Enhanced Customization Improved `styles` and `fonts` APIs allow for even more brand-level customization. ### 🏦 Plaid Link Support When accepting ACH / bank payments, the form now automatically integrates with **Plaid Link** for a modern, secure bank-account experience. Learn more about our finix.js v2 by visiting our [tokenization form guide](/guides/online-payments/payment-tokenization/tokenization-forms). --- # Payouts Auto Top-Ups Source: https://docs.finix.com/release-notes/2025/12/payouts-auto-top-ups Auto-Top Ups are now available for Payouts customers. Payouts customers can now set up Auto-Top Up Rules. Finix will check customer's pending balance at 6PM PT daily. If it drops below the set minimum, we'll automatically create a top-up with maximum amount set. Learn more on our [guide](https://docs.finix.com/guides/payouts/adding-funds#setting-up-auto-top-up-using-the-dashboard) --- # Splitting ACH Returns and Disputes Source: https://docs.finix.com/release-notes/2026/01/splitting-ach-returns-and-disputes When a buyer disputes a split transaction or an ACH payment is returned, you can now choose how those amounts are distributed across the sellers involved in the original sale. By default, the primary merchant absorbs the full amount of any dispute or ACH return. You can now optionally enable **proportional distribution**, where the dispute or return amount is split across all participating sellers based on their share of the original transaction — so each seller is responsible for only their portion. To enable proportional distribution for disputes or ACH returns, contact [Finix Support](mailto:support@finix.com). For information on handling disputes and ACH returns with split transactions, please see our [Split Transactions](/guides/online-payments/payment-features/split-transactions#disputes) guide. --- # Invoices is in Early Access Source: https://docs.finix.com/release-notes/2026/02/invoices-is-in-early-access [Invoices](/low-code-no-code/invoices) are formal documents used to request payment from a specific buyer for goods or services. Each invoice includes a unique number, itemized details, and a due date. Invoices can be paid in full or in installments and are suitable for business transactions and tax records. To access Invoices: 1. In the Finix Dashboard, expand **Payment Tools** in the left navigation. 2. Click **Invoices**. Invoice PDF Check out our [Invoices Quickstart](https://docs.finix.com/low-code-no-code/invoices/invoices-quickstart) guide to see how you can create invoices in the Finix Dashboard. Invoices Early Access Invoices is in **early access**. During our early access promotional period, each invoice payment will be processed at a 0.10% fee per successful transaction. Starting July 1st, 2026, the standard rate will be increased to 0.40% fee per successful transaction. Please reach out to [Finix Support](mailto:support@finix.com) or your Finix point of contact if you have any questions. --- # MCP Server now available Source: https://docs.finix.com/release-notes/2026/02/mcp-server-now-available The [Finix MCP Server](/additional-resources/developers/mcp-server) connects AI assistants like Claude and ChatGPT directly to Finix's live documentation. Instead of guessing or relying on outdated training data, AI tools can now retrieve accurate, up-to-date answers about Finix APIs, guides, and integrations on demand—reducing errors and speeding up development workflows. Claude CLI Check out [our guides](/additional-resources/developers/mcp-server) on how to set up AI models with Finix's MCP server. The supported AI models include: Invoice PDF Invoice PDF --- # Statement Descriptors on Payment Links Source: https://docs.finix.com/release-notes/2026/02/statement-descriptors-on-payment-links With Payment Links, you can now set a **custom card statement descriptor** for your business. This description will show up on your buyer’s bank or card statement. Invoice PDF Check our [Payment Links quickstart](/low-code-no-code/payment-links/quickstart-dashboard#advanced-settings) to see how you can add a card statement descriptor. --- # Surcharging now available on Variable Payment Links Source: https://docs.finix.com/release-notes/2026/02/surcharging-now-available-on-variable-payment-links Variable Payment Links now support surcharge fees to help offset payment processing costs. Payment Link Creation Form - Surcharge Fee The buyer payment page will display a notice indicating that a surcharge applies and specify the exact amount. Payment Link Preview - Surcharge Fee See our [Surcharge Fees for Payment Links](/low-code-no-code/payment-links/buyer-fees/surcharge-fees) guide for more details. --- # Payment Links on Finix Checkout iOS App Source: https://docs.finix.com/release-notes/2026/03/payment-links-on-finix-checkout-ios-app You can now create and share [Payment Links](/low-code-no-code/payment-links) using the [Finix Checkout iOS App](https://apps.apple.com/us/app/finix-checkout/id6746730500). The app is available in the U.S. and supports: - Creating Sales and Authorizations via the Pax D135 and Manual Entry - Creating and Managing Payment Links - Viewing Transaction, Buyer, and Payment Instrument details - Creating SMS and Email Receipts Finix Checkout iOS App - Payment Links Finix Checkout iOS App - Sharing Payment Links --- # Cardholder Name Verification Now Included with Push-to-Card Checks Source: https://docs.finix.com/release-notes/2026/04/cardholder-name-verification-now-included-with-push-to-card When checking a card's eligibility for Push-to-Card (instant payouts to cards), Finix now automatically returns cardholder name verification results alongside the eligibility response. This gives you a richer signal on cardholder identity—without any additional API calls. Name verification results cover first, last, and middle name matching against the issuing bank and apply to both Visa and Mastercard. If the name on file doesn't match, you can update the cardholder name on the payment instrument and request a re-verification. Dashboard support for name verification results is coming soon. For more details, see: - [Verify Push-to-Card Eligibility](/api/payment-instruments/createpaymentinstrumentverificationpushtocard) - [Testing Name Verification](/additional-resources/developers/implementation-and-testing/testing-your-integration#testing-payment-instrument-name-verification) - [Update a Payment Instrument](/api/payment-instruments/updatepaymentinstrument) --- # PAX IM30 Now Available Source: https://docs.finix.com/release-notes/2026/04/pax-im30-now-available Finix now supports the PAX IM30, a payment terminal built for self-service, semi-attended, and unattended environments. This device enables businesses to deploy Finix-powered payments in kiosks, vending machines, and unattended checkout stations—extending in-person payment acceptance to locations where a dedicated operator isn't always present. The PAX IM30 is available to customers in the United States and Canada and integrates with Finix via the semi-integrated API. PAX IM30 with Finix To learn more: - [PAX IM30 device guide](https://docs.finix.com/guides/in-person-payments/select-your-device/pax-im30) - [Build your POS integration](https://docs.finix.com/guides/in-person-payments/building-your-integration/pos-integration) --- # Update to ACH Settlement Statement Descriptors Source: https://docs.finix.com/release-notes/2026/04/update-to-ach-settlement-statement-descriptors Effective April 22, 2026, Finix is updating the Originator Company Name that appears on ACH credit and debit settlement transactions to comply with NACHA rules. This is the name that shows up on your merchants' bank statements to identify who initiated the settlement. Previously, merchants saw your company's default Statement Descriptor listed as the originator. Going forward, the descriptor will use the following format: `Finix-Your Statement Descriptor` For example: `Finix-PARTNER Name` Please communicate this change to your merchants so they are aware of the updated descriptor on ACH settlement transactions. This change does not impact settlement timing, reporting, or reconciliation processes. Merchants accepting ACH payments can still set a custom statement descriptor that appears on the end buyer's bank statement. This update only affects how ACH settlement transactions to and from merchant bank accounts are identified. If you have any questions, reach out to your Customer Delivery Manager or [support@finix.com](mailto:support@finix.com). --- # Auto and Hotel Rental Support Source: https://docs.finix.com/release-notes/2026/05/auto-and-hotel-rental-support We've added support for auto rental and lodging (hotel) merchants. Merchants in these industries can now pass industry-specific details on Authorizations and Transfers to qualify for lower interchange rates and avoid costly downgrades. - **Auto rental**: Include rental details, such as the rental agreement number, pickup and return dates, and rental rate, using the `additional_motor_vehicle_rental_data` object. - **Lodging**: Include stay details, such as check-in and check-out dates, room rate, and folio number, using the `additional_lodging_data` object. To learn more: - [Motor vehicle rental guide](/guides/industry-considerations/auto-rental) - [Lodging guide](/guides/industry-considerations/lodging) --- # Cybersource Gateway Integration Now Available Source: https://docs.finix.com/release-notes/2026/05/cybersource-gateway-integration-now-available Cybersource Finix now supports Cybersource as a gateway integration. Cybersource, a Visa-owned payment gateway, acts as the gateway layer routing transactions to card networks. Merchants can retain their existing checkout solutions while Finix continues to handle merchant onboarding, settlements, and payouts. Key benefits include: - **Global card support**: Accept many international cards including Visa, Mastercard, American Express, and Discover. - **Flexible checkout**: Keep existing checkout providers like Shopify while routing transactions through Cybersource. Merchants must use a Finix-issued Cybersource account. Once a Gateway Integration is created, Cybersource sends an email invitation to activate the account and retrieve transacting credentials. To learn more: - [Cybersource Integration Guide](/guides/online-payments/gateway-integration/cybersource) - [Create a Gateway Integration](/api/gateway-integrations/creategatewayintegration) --- # Government Payouts Now Available Source: https://docs.finix.com/release-notes/2026/06/government-payouts-now-available Finix Payouts now supports government disbursements. Government agencies, and the platforms that serve them, can send payouts directly to a recipient's debit card or bank account instead of mailing paper checks. Paper checks take weeks to arrive, get lost or stolen in the mail, and create recovery work when they do. With Finix Payouts, recipients receive funds on the debit card they already carry, with no routing numbers to track down and no checks to chase. Common use cases include: - Tax refunds - Disaster relief payments - Juror fees - Unclaimed property disbursements - Small-dollar reimbursements To enable Government Payouts on your Finix Application, reach out to your Finix point of contact or email [support@finix.com](mailto:support@finix.com). --- # Me-to-Me Payouts Now Available Source: https://docs.finix.com/release-notes/2026/06/me-to-me-payouts-now-available Finix Payouts now supports Me-to-Me payouts, which let your users move funds between their own payment instruments. Pull funds from a card or bank account, then push them to another card or bank account belonging to the same person. Both transfers run under a single Identity. Common use cases include moving a balance to a preferred account, funding a debit card from a bank account, and consolidating funds across accounts. To learn more, see the [Me-to-Me payouts guide](/guides/payouts/me-to-me-payouts). --- # Card Scanning Available for iOS and Android Source: https://docs.finix.com/release-notes/2026/07/card-scanning-available-for-ios-and-android We've added card scanning to our mobile payment experiences. Buyers can scan their card with the device camera to fill in the card number and expiration date automatically. This reduces typos and speeds up checkout. For security, buyers always enter the CVV manually. Card scanning is now available in: - **iOS SDK**: Built into the Payment Sheet and enabled by default. - **Android SDK**: Uses on-device text recognition to populate the payment form. - **Finix Checkout App**: Scan cards when taking payments on the go. To learn more: - [Card scanning on iOS](/ios/online/card-scanner) - [Card scanning on Android](/android/online/card-scanner) --- # Pass Through Decrypted Apple Pay and Google Pay Tokens Source: https://docs.finix.com/release-notes/2026/07/decrypted-apple-pay-and-google-pay-token-passthrough Apple Pay and Google Pay If you decrypt Apple Pay or Google Pay tokens on your own systems, you can now pass the decrypted values directly to Finix when creating a Payment Instrument, instead of sending the encrypted token for Finix to decrypt. This passthrough path is available to PCI DSS Level 1 compliant merchants and gives you full control over token decryption. Send the decrypted card `number`, `cryptogram`, `expiration_month`, `expiration_year`, and `electronic_commerce_indicator_code` directly to the API. To learn more: - [Apple Pay passthrough guide](/guides/online-payments/digital-wallets/apple-pay/apple-pay-passthrough) - [Google Pay passthrough guide](/guides/online-payments/digital-wallets/google-pay/google-pay-passthrough) --- # Finix WooCommerce 1.60 Release Source: https://docs.finix.com/release-notes/2026/07/finix-woocommerce-1-60-release Finix for WooCommerce We've released version `1.60` of the Finix for WooCommerce plugin. The plugin now supports **WooCommerce Subscriptions**, so merchants can offer recurring payment options managed by WooCommerce and processed through Finix. This release also includes compatibility updates: - Tested and fully compatible with WooCommerce 10.9. - Tested and fully compatible with WooCommerce Subscriptions 9.0. - Tested and fully compatible with WordPress 7.0. To download and install the plugin, visit [wordpress.org](https://wordpress.org/plugins/finix-for-woocommerce/) or read our [WooCommerce plugin guide](/additional-resources/plugins/woocommerce-plugin). If you have auto-updates enabled, the plugin updates automatically depending on your WordPress settings. --- # PAX A35 Now Supported Source: https://docs.finix.com/release-notes/2026/07/pax-a35-now-supported PAX A35 with Finix Finix now supports the PAX A35, a compact Android smart PIN pad built for retail checkout. Its slim footprint fits countertop and multilane deployments without taking up valuable counter space. Key benefits include: - **Flexible payment acceptance**: Accept EMV chip, contactless, and magnetic stripe payments. - **Built for the counter**: A 4-inch touchscreen in a compact design suited to countertop and multilane retail environments. - **Reliable connectivity**: Connect over Wi-Fi or Ethernet to fit your store's setup. The PAX A35 is available to customers in the United States and Canada and integrates with Finix via the semi-integrated API. Standalone Mode is not available on this device. To learn more: - [PAX A35 device guide](/guides/in-person-payments/select-your-device/pax-a35) - [Build your POS integration](/guides/in-person-payments/building-your-integration/pos-integration) --- # PAX A3700 Now Supported Source: https://docs.finix.com/release-notes/2026/07/pax-a3700-now-supported PAX A3700 with Finix Finix now supports the PAX A3700, also known as the Elys Tablet. The A3700 is a customer-facing Android payment tablet built for retail checkout and suitable for many business environments. Key benefits include: - **Large customer-facing display**: A 7-inch HD touchscreen gives buyers a clear view of prompts and payment details at checkout. - **Flexible payment acceptance**: Accept EMV chip, contactless, and magnetic stripe payments, with card readers on both sides of the device. - **Fits multiple setups**: Use the tablet on its own at the counter, or attach it to an Elys Station for a full checkout station. The PAX A3700 is available to customers in the United States and Canada and integrates with Finix via the semi-integrated API. Standalone Mode is not available on this device. To learn more: - [PAX A3700 device guide](/guides/in-person-payments/select-your-device/pax-a3700) - [Build your POS integration](/guides/in-person-payments/building-your-integration/pos-integration) --- # Update Card Expiration Dates via API and Dashboard Source: https://docs.finix.com/release-notes/2026/07/update-card-expiration-dates-via-api-and-dashboard You can now update the expiration date on an existing card Payment Instrument. This keeps cards on file current without recreating them or asking the cardholder to re-enter their details. - **Via API**: Pass `expiration_month` and `expiration_year` (a 4-digit year) together when updating a Payment Instrument. - **Via Dashboard**: Edit the expiration date directly from the Payment Instrument's detail page. For more information, see [Update a Payment Instrument](/api/payment-instruments/updatepaymentinstrument). --- # Deploying Your App to Terminals Source: https://docs.finix.com/release-notes/2026/08/deploying-your-app-to-terminals Android app built with the Finix Device Reader SDK running on a PAX terminal You can now build your own applications and deploy them directly to Finix-supported payment terminals. With the Device Reader SDK, your app runs on the terminal itself and controls the full in-person payment experience: registering the device, initializing the terminal, and processing transactions. Use this to build a custom point of sale, or to embed payments into an existing workflow. You keep complete control over the checkout experience on the device. To learn more: - [Deploy Apps to Your Terminals](/guides/in-person-payments/deploy-apps-terminals) - [Android Device Reader SDK quickstart](/guides/in-person-payments/building-your-integration/mobile-integration/pax_d135_android_quickstart) - [iOS Device Reader SDK quickstart](/guides/in-person-payments/building-your-integration/mobile-integration/pax_d135_ios_quickstart) --- # Failed Transactions, Failed Authorizations, and Refund Fees can now be passed on to your merchants Source: https://docs.finix.com/release-notes/2026/08/pass-failed-and-refund-fees-to-your-merchants Fee Settings step of the Fee Profile editor in the Finix Dashboard with toggles enabled for charging fees on failed payments, refunds, and uncaptured authorizations You can now pass these fees on to your merchants for failed transactions, failed authorizations, and refunds. These are industry-standard fees, and applying them recovers costs you would otherwise absorb. You can set these on a merchant's Fee Profile from your Finix Dashboard or through the API. Three new Fee Profile settings control which attempts your merchants are charged the fixed fee for: - **Failed transactions:** Charge the fixed fee when a sale or capture fails. Set `charge_all_transfer_requests` to `true`. - **Refunds:** Charge the fixed fee on refunds, both successful and failed. Set `charge_all_reversal_requests` to `true`. - **Failed authorizations:** Charge the fixed fee when an authorization fails, is voided, or expires. Set `charge_all_authorization_requests` to `true`. Only the fixed fee from the merchant's Fee Profile applies to these events, not the percentage-based basis points. Finix charges the flat fixed fee that matches the card brand or payment method, such as the Visa fixed fee on a Visa payment or the ACH fixed fee on a bank refund. Each transaction is charged a single fixed fee. By default these fees are not enabled for your merchants, so nothing changes for your merchants until you enable it. --- # Set a Billing Cycle Day for Subscriptions Source: https://docs.finix.com/release-notes/2026/08/set-a-billing-cycle-day-for-subscriptions Create a Subscription form in the Finix Dashboard with the new Billing Date field set to the 1st of the month You can now choose the day of the month a subscription bills, no matter what day it starts. Set `billing_cycle_day` when creating a Subscription to charge the buyer on that day every cycle, or select a **Billing Date** when creating a subscription in the Finix Dashboard. You can also change the billing cycle day on an existing Subscription at any time. - **Prorated first invoice**: If the subscription starts on a different day, Finix prorates the first invoice so the buyer only pays for the days until the first billing cycle day. - **End of month handling**: If a month does not include the day you selected, Finix charges the buyer on the last day of that month instead. - **Prorated updates**: When you change the billing cycle day on an existing subscription, Finix charges a prorated amount to bridge the gap, then resumes full billing on the new day. Billing cycle days are supported for `MONTHLY` and longer billing intervals, up to `TRIYEARLY`. To learn more, see [Billing cycle day](/guides/subscriptions/subscriptions-quickstart#billing-cycle-day) in the Subscriptions Quickstart. For request details, see [Create a Subscription](/api/subscriptions/createsubscription) and [Update a Subscription](/api/subscriptions/updatesubscription) in the API reference. --- # Tap to Pay on iPhone for Finix Checkout Source: https://docs.finix.com/release-notes/2026/08/tap-to-pay-on-iphone-for-finix-checkout Tap to Pay on iPhone with Finix Checkout The Finix Checkout iOS app now supports Tap to Pay on iPhone. Accept in-person payments using only an iPhone. No card reader or extra hardware is required. Buyers hold their contactless card or device near your iPhone to pay. Tap to Pay on iPhone accepts: - **Contactless credit and debit cards**: All major card brands are supported. - **Digital wallets:** This includes Apple Pay and Google Pay. Tap to Pay on iPhone requires an iPhone XS or newer running iOS 18.1 or later. To learn more, see the [Tap to Pay on iPhone guide](/low-code-no-code/mobile-apps/finix-checkout/tap-to-pay-on-iphone).