# 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](/assets/online-payments.c670fabaef9307e5ff2f0377a43aeebaf826b162984a2e04bb3d5b8693cd309a.fec90461.svg) 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, we’ll 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. Usually, we suggest 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. ```shell curl https://finix.sandbox-payments-api.com/identities \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -d '{ "entity": { "phone": "7145677613", "first_name": "Collen", "last_name": "Wade", "email": "therock@gmail.com", "personal_address": { "city": "San Mateo", "country": "USA", "region": "CA", "line2": "Apartment 7", "line1": "741 Douglass St", "postal_code": "94114" } } }' ``` A successful response returns the `Identity` you'll use in the next step. ```json { "id": "IDn7rfwM88AJrBituwUjcX2Y", "created_at": "2023-10-25T17:42:22.23Z", "updated_at": "2023-10-25T17:42:22.23Z", "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": "therock@gmail.com", "first_name": "Collen", "has_accepted_credit_cards_previously": false, "incorporation_date": null, "last_name": "Wade", "max_transaction_amount": 0, "mcc": null, "ownership_type": null, "personal_address": { "line1": "741 Douglass St", "line2": "Apartment 7", "city": "San Mateo", "region": "CA", "postal_code": "94114", "country": "USA" }, "phone": "7145677613", "principal_percentage_ownership": null, "short_business_name": null, "tax_authority": null, "tax_id_provided": false, "title": null, "url": null }, "identity_roles": [], "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" } } } ``` ### Step 2: Tokenize Payment Details Now that we have an `Identity` resource representing your buyer, we’ll 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. ```shell curl https://finix.sandbox-payments-api.com/payment_instruments \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -d '{ "address": { "city": "San Francisco", "country": "USA", "line1": "900 Metro Center Blv", "postal_code": "94404", "region": "CA" }, "expiration_month": 12, "expiration_year": 2029, "identity": "IDbKCkEWUXALZGkvrMfQcnS9", "name": "John Smith", "number": "4895142232120006", "security_code": "022", "type": "PAYMENT_CARD" }' ``` A successful response returns the newly created `Payment Instrument` you'll use to process the buyer's payment. ```json { "id": "PIcacm9WBYXZSd7NB5DmpN6E", "created_at": "2023-10-25T17:43:09.94Z", "updated_at": "2023-10-25T17:43:09.94Z", "application": "APgPDQrLD52TYvqazjHJJchM", "created_via": "API", "currency": "USD", "disabled_code": null, "disabled_message": null, "enabled": true, "fingerprint": "FPRogKWsRQks2HGaau5eGR9AF", "identity": "IDbKCkEWUXALZGkvrMfQcnS9", "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": "489514", "brand": "VISA", "card_type": "UNKNOWN", "expiration_month": 12, "expiration_year": 2029, "issuer_country": "UNKNOWN", "last_four": "0006", "name": "John Smith", "security_code_verification": "UNKNOWN", "tags": {}, "type": "PAYMENT_CARD", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcacm9WBYXZSd7NB5DmpN6E" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcacm9WBYXZSd7NB5DmpN6E/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcacm9WBYXZSd7NB5DmpN6E/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcacm9WBYXZSd7NB5DmpN6E/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9" }, "updates": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcacm9WBYXZSd7NB5DmpN6E/updates" } } } ``` ### 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 For the request below, please note that the `amount` field is in cents. ```shell 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": 662154, "currency": "USD", "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "source": "PIcacm9WBYXZSd7NB5DmpN6E" }' ``` A successful response returns the `Transfer` with `type: DEBIT` and `state: SUCCEEDED`. ```json { "id": "TRBuZ2qrAw268K2npdBpdT9", "created_at": "2023-10-25T17:43:34.23Z", "updated_at": "2023-10-25T17:43:35.10Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 662154, "amount_requested": 662154, "application": "APgPDQrLD52TYvqazjHJJchM", "currency": "USD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "idempotency_id": null, "merchant": "MU7cXuKj2xx41hhZZi6bZ13A", "merchant_identity": "IDvHGrfeVmB3i7uL78xjemNk", "messages": [], "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": "PIcacm9WBYXZSd7NB5DmpN6E", "split_transfers": [], "state": "SUCCEEDED", "statement_descriptor": "FNX*FINIX FLOWERS", "subtype": "API", "tags": {}, "trace_id": "a395feb9-0fcd-45ab-b4e6-280d2d7cdf5d", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRBuZ2qrAw268K2npdBpdT9" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDvHGrfeVmB3i7uL78xjemNk" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRBuZ2qrAw268K2npdBpdT9/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRBuZ2qrAw268K2npdBpdT9/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TRBuZ2qrAw268K2npdBpdT9/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRBuZ2qrAw268K2npdBpdT9/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcacm9WBYXZSd7NB5DmpN6E" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8" } } } ``` 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). #### Fraud Session ID We recommend including a `fraud_session_id` to detect and block potential fraudulent payments. For more information, see [Fraud Detection](/guides/online-payments/fraud-and-risk/fraud-detection). Finix Hosted Checkout Redirect to a hosted payment page using Finix Checkout Forms. This option allows you to quickly get running with a branded page built and maintained by Finix. Checkout Form Example br Using checkout pages you can quickly accept payments from buyers with minimal development work. Checkout pages are a low-code solution that enables you to create a customizable payment page where buyers can easily enter their payment details and submit a payment on both desktop and mobile devices. Checkout pages are only available via the Finix API. If you want to create a similar experience on the Dashboard, look into our [Payment Links](/guides/online-payments/low-code-no-code/payment-links). To learn more about Checkout Forms visit our [comprehensive guide](/guides/online-payments/low-code-no-code/checkout-pages). ### Step 1: Create a Checkout Form To create a checkout form, include: - The `ID` of the `Merchant` that the payment will be created under. - The amount of the transaction. - Any additional URLs (terms of service required). - Allowed payment methods. - The branding you would like to have on the checkout form. Finix supports customizing colors and adding your desired logo. At this time, only `APPROVED` `Merchants` with one of the following `processors` can create checkout pages: - `DUMMY_V1` - `LITLE_V1` - `FINIX_V1` To learn about all the available fields, see [Checkout Form](/api/checkout-forms/createcheckoutform) ```shell Checkout Form Request curl https://finix.sandbox-payments-api.com/checkout_forms \ -H "Content-Type: application/json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X POST \ -d '{ "merchant_id": "MUucec6fHeaWo3VHYoSkUySM", "payment_frequency": "ONE_TIME", "is_multiple_use": false, "allowed_payment_methods": ["PAYMENT_CARD"], "nickname": "string", "items": [ { "image_details": { "primary_image_url": "https://images.unsplash.com/photo-1511499767150-a48a237f0083?q=80&w=2980&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D", "alternative_image_urls": [ "https://google.com/image1", "https://google.com/image2" ] }, "description": "These are cool sunglasses", "price_details": { "sale_amount": 4000, "currency": "USD", "price_type": "PROMOTIONAL", "regular_amount": 5000 }, "quantity": "1" } ], "buyer_details": { "first_name": "Oscar", "last_name": "Barillas", "email": null, "shipping_address": null, "billing_address": null, "phone_number": null }, "amount_details": { "amount_type": "FIXED", "total_amount": 5418, "currency": "USD", "min_amount": null, "max_amount": null, "amount_breakdown": { "subtotal_amount": 3994, "shipping_amount": 995, "estimated_tax_amount": 429, "discount_amount": "1000", "tip_amount": "1000" } }, "branding": { "brand_color": "#fbe5d0", "accent_color": "#ff4838", "logo": "https://s3.amazonaws.com/customer-uploaded-assets-prod/04-12-2023-05_13_37_ACME_logo-01%20%281%29.png", "icon": "https://s3.amazonaws.com/customer-uploaded-assets-prod/04-12-2023-05_13_37_ACME_logo-01%20%281%29.png" }, "additional_details": { "collect_name": true, "collect_email": true, "collect_phone_number": true, "collect_billing_address": true, "collect_shipping_address": true, "success_return_url": "https://www.example.com/success/123rw21w.html ", "cart_return_url": "https://www.example.com/my_cart.html", "expired_session_url": "https://example.com/error.html ", "terms_of_service_url": "https://example.com/terms_of_service.html ", "expiration_in_minutes": 57680 } }' ``` ```json Checkout Form { "id": "checkout_form_cgiWUmK32ssj1nsuqQsVK", "created_at": "2024-10-18T03:52:54.321458Z", "updated_at": "2024-10-18T03:52:54.321458Z", "merchant_id": "MUucec6fHeaWo3VHYoSkUySM", "application_id": "APgPDQrLD52TYvqazjHJJchM", "payment_frequency": "ONE_TIME", "allowed_payment_methods": ["PAYMENT_CARD"], "nickname": "string", "state": "ACTIVE", "items": [ { "image_details": { "primary_image_url": "https://images.unsplash.com/photo-1511499767150-a48a237f0083?q=80&w=2980&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D", "alternative_image_urls": [ "https://google.com/image1", "https://google.com/image2" ] }, "description": "These are cool sunglasses", "price_details": { "sale_amount": 4000, "currency": "USD", "price_type": "PROMOTIONAL", "regular_amount": 5000 }, "name": null, "quantity": 1 } ], "buyer_details": { "identity_id": null, "first_name": "Oscar", "last_name": "Barillas", "email": null, "phone": null, "billing_address": null, "shipping_address": null }, "amount_details": { "amount_type": "FIXED", "total_amount": 5418, "currency": "USD", "min_amount": null, "max_amount": null, "amount_breakdown": { "subtotal_amount": 3994, "shipping_amount": 995, "estimated_tax_amount": 429, "discount_amount": 1000, "tip_amount": 1000 } }, "branding": { "brand_color": "#fbe5d0", "accent_color": "#ff4838", "logo": "https://s3.amazonaws.com/customer-uploaded-assets-prod/04-12-2023-05_13_37_ACME_logo-01%20%281%29.png", "icon": "https://s3.amazonaws.com/customer-uploaded-assets-prod/04-12-2023-05_13_37_ACME_logo-01%20%281%29.png", "logo_alternative_text": null, "button_font_color": null }, "additional_details": { "collect_name": true, "collect_email": true, "collect_phone": false, "collect_billing_address": true, "collect_shipping_address": true, "success_return_url": "https://www.example.com/success/123rw21w.html ", "cart_return_url": "https://www.example.com/my_cart.html", "expired_session_url": "https://example.com/error.html ", "terms_of_service_url": "https://example.com/terms_of_service.html ", "expiration_in_minutes": 57680, "send_receipt": false, "receipt_requested_delivery_methods": [] }, "link_url": "https://link.sandbox-payments-checkout.com/fLnady", "link_expires_at": "2024-11-27T05:12:54.177946Z", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/checkout_forms/checkout_form_cgiWUmK32ssj1nsuqQsVK" } } } ``` ### Step 2. Redirect User to Checkout Form Now that you've created a `checkout_form`, redirect your buyer to the `checkout_form#link_url` provided. This `link_url` will contain the white-labeled checkout form and allow your buyer to checkout. ### Step 3. Await checkout_form state By default, `checkout_forms` expire after 10 minutes. You can extend the expiration date to a maximum of 3 weeks. Please note the expiration time of the `checkout_form` must be less than your cart expiration time; otherwise, timeout issues can come up for your buyers when submitting a payment. `checkout_forms` can only be used once. After a buyer makes a successful payment, the `checkout_form` cannot be used again. If a buyer returns to a successful `checkout_form` link, they'll see a *You have already paid* message and/or get redirected to a new page. When a `checkout_form` is *successful*, the `state` of the checkout form will update to `COMPLETED`. If a `checkout_form` is *unsuccessful*, the buyer is taken back to the checkout form to try submitting payment details again. The `checkout_form#state` will remain `ACTIVE` until the form expires or gets deactivated. Subscriptions Finix allows you to sign up and manage subscriptions for your buyers or customers. For a comprehensive guide on Susbcriptions, 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: ```shell Create Subscription Request curl https://finix.sandbox-payments-api.com/subscriptions \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USksBJMwkNUz5GyxPevL2yFY:71b641c1-861d-435b-9a9c-532760731c5e \ -X POST \ -d '{ "amount": 2900, "currency": "USD", "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N", "nickname": "Test Subscription", "billing_interval": "MONTHLY", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "trial_details": { "interval_type": "MONTH", "interval_count": "1" } }, "buyer_details": { "identity_id": "ID2maTpthyAYJWnZ5kDD42Cd", "instrument_id": "PInE8utFwr4eoXdftZBQuxGw" } }' ``` ```json Create Subscription Response { "id": "subscription_cd5brMYg6u1WuicGTbq1P", "created_at": "2024-07-10T23:38:47.43Z", "updated_at": "2024-07-10T23:38:47.43Z", "first_charge_at": "2024-07-10T23:38:47.00Z", "amount": 2900, "buyer_details": { "identity_id": "ID2maTpthyAYJWnZ5kDD42Cd", "instrument_id": "PInE8utFwr4eoXdftZBQuxGw", "requested_delivery_methods": [] }, "currency": "USD", "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N", "linked_type": "MERCHANT", "nickname": "Test Subscription", "billing_interval": "MONTHLY", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false, "trial_details": null, "discount_phase_details": null }, "subscription_phase": "TRIAL", "state": "ACTIVE", "subscription_plan_id": null, "start_subscription_at": "2025-01-01T00:00:00.000Z", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cd5brMYg6u1WuicGTbq1P" } } } ``` ### 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. ```shell Create Subscription Request curl https://finix.sandbox-payments-api.com/subscriptions \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USksBJMwkNUz5GyxPevL2yFY:71b641c1-861d-435b-9a9c-532760731c5e \ -X POST \ -d '{ "amount": 2900, "currency": "USD", "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N", "nickname": "Test Subscription", "billing_interval": "MONTHLY", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "trial_details": { "interval_type": "MONTH", "interval_count": "1" } }, "buyer_details": { "identity_id": "ID2maTpthyAYJWnZ5kDD42Cd", "instrument_id": "PInE8utFwr4eoXdftZBQuxGw" } }' ``` ```json Create Subscription Response { "id": "subscription_cd5brMYg6u1WuicGTbq1P", "created_at": "2024-07-10T23:38:47.43Z", "updated_at": "2024-07-10T23:38:47.43Z", "first_charge_at": "2024-07-10T23:38:47.00Z", "amount": 2900, "buyer_details": { "identity_id": "ID2maTpthyAYJWnZ5kDD42Cd", "instrument_id": "PInE8utFwr4eoXdftZBQuxGw", "requested_delivery_methods": [] }, "currency": "USD", "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N", "linked_type": "MERCHANT", "nickname": "Test Subscription", "billing_interval": "MONTHLY", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false, "trial_details": { "interval_type": "MONTH", "interval_count": 1, "trial_started_at": "2024-07-10T19:13:14.00Z", "trial_expected_end_at": "2024-08-10T19:13:14.00Z" }, "discount_phase_details": null }, "subscription_phase": "TRIAL", "state": "ACTIVE", "subscription_plan_id": null, "start_subscription_at": "2024-07-10T23:38:47.00Z", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cd5brMYg6u1WuicGTbq1P" } } } ``` ### 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 `2000` and `discount_phase_details.billing_interval_count` to `3`. After this discount period, the subscriber will be charged the full `amount` of the `Subscription`. ```shell Create Subscription Request curl https://finix.sandbox-payments-api.com/subscriptions \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USksBJMwkNUz5GyxPevL2yFY:71b641c1-861d-435b-9a9c-532760731c5e \ -X POST \ -d '{ "amount": 2000, "currency": "USD", "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N", "linked_type": "MERCHANT", "nickname": "Finflix Gold Package", "billing_interval": "MONTHLY", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "discount_phase_details": { "amount": 1000, "billing_interval_count": 3 } }, "buyer_details": { "identity_id": "ID2maTpthyAYJWnZ5kDD42Cd", "instrument_id": "PInE8utFwr4eoXdftZBQuxGw" } }' ``` ```json Create Subscription Response { "id": "subscription_ckpv3GLDNjDTWmxzgmptd", "created_at": "2025-02-20T15:15:14.63Z", "updated_at": "2025-02-20T15:15:14.63Z", "first_charge_at": "2025-02-20T15:15:14.00Z", "next_billing_date": { "year": 2025, "month": 2, "day": 20 }, "amount": 2000, "buyer_details": { "identity_id": "ID2maTpthyAYJWnZ5kDD42Cd", "instrument_id": "PInE8utFwr4eoXdftZBQuxGw", "requested_delivery_methods": [] }, "currency": "USD", "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N", "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 } }, "subscription_phase": "DISCOUNT", "state": "ACTIVE", "subscription_plan_id": null, "start_subscription_at": "2025-02-20T00:00:00.000Z", "total_billing_intervals": null, "expires_at": null, "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_ckpv3GLDNjDTWmxzgmptd" } } } ``` ### 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. ```shell Create Subscription Request curl https://finix.sandbox-payments-api.com/subscriptions \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USksBJMwkNUz5GyxPevL2yFY:71b641c1-861d-435b-9a9c-532760731c5e \ -X POST \ -d '{ "amount": 2900, "currency": "USD", "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N", "nickname": "Test Subscription", "billing_interval": "MONTHLY", "start_subscription_at": "2025-05-05T22:42:05.490Z", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY" }, "buyer_details": { "identity_id": "ID2maTpthyAYJWnZ5kDD42Cd", "instrument_id": "PInE8utFwr4eoXdftZBQuxGw" } }' ``` ```json Create Subscription Response { "id": "subscription_cj5AmwBg2iu8xUvcs8DUG", "created_at": "2025-01-11T00:19:05.57Z", "updated_at": "2025-01-11T00:19:05.57Z", "first_charge_at": "2025-05-05T22:42:05.49Z", "amount": 2900, "buyer_details": { "identity_id": "ID2maTpthyAYJWnZ5kDD42Cd", "instrument_id": "PInE8utFwr4eoXdftZBQuxGw", "requested_delivery_methods": [] }, "currency": "USD", "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N", "linked_type": "MERCHANT", "nickname": "Test Subscription", "billing_interval": "MONTHLY", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false, "trial_details": null, "discount_phase_details": null }, "subscription_phase": "NONE", "state": "NOT_STARTED", "subscription_plan_id": null, "start_subscription_at": "2025-05-05T22:42:05.490Z", "total_billing_intervals": null, "expires_at": null, "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cj5AmwBg2iu8xUvcs8DUG" } } } ``` ### 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`. ```shell Create Subscription Request curl https://finix.sandbox-payments-api.com/subscriptions \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USksBJMwkNUz5GyxPevL2yFY:71b641c1-861d-435b-9a9c-532760731c5e \ -X POST \ -d '{ "amount": 2900, "currency": "USD", "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N", "nickname": "Test Subscription", "billing_interval": "MONTHLY", "total_billing_intervals": 3, "subscription_details": { "collection_method": "BILL_AUTOMATICALLY" }, "buyer_details": { "identity_id": "ID2maTpthyAYJWnZ5kDD42Cd", "instrument_id": "PInE8utFwr4eoXdftZBQuxGw" } }' ``` ```json Create Subscription Response { "id": "subscription_cj5BAPDczRbbEZFEWQBkN", "created_at": "2025-01-11T00:35:26.30Z", "updated_at": "2025-01-11T00:35:26.30Z", "first_charge_at": "2025-01-11T00:35:25.00Z", "amount": 2900, "buyer_details": { "identity_id": "ID2maTpthyAYJWnZ5kDD42Cd", "instrument_id": "PInE8utFwr4eoXdftZBQuxGw", "requested_delivery_methods": [] }, "currency": "USD", "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N", "linked_type": "MERCHANT", "nickname": "Test Subscription", "billing_interval": "MONTHLY", "subscription_details": { "collection_method": "BILL_AUTOMATICALLY", "send_invoice": false, "send_receipt": false, "trial_details": null, "discount_phase_details": null }, "subscription_phase": "FIXED", "state": "ACTIVE", "subscription_plan_id": null, "start_subscription_at": "2025-01-11T00:00:00.000Z", "total_billing_intervals": 3, "expires_at": "2025-04-11T00:35:25.681Z", "tags": {}, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/subscriptions/subscription_cj5BAPDczRbbEZFEWQBkN" } } } ``` 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](/assets/in-person-payments-hero.e5459dcbeca77e85516f32268b4b577331dc807762e7ebd6b38e99b1cc2798b0.fec90461.svg) 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 a variety of different payment features to let you customize your payments integration: - [Use authorizations and captures](/guides/online-payments/payment-features/auth-and-captures) to create temporary holds before capturing full amounts later. - [Enable buyer charges](/guides/online-payments/payment-features/buyer-charges) to collect additional fees, such as convenience or service fees. - [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 Authentication](/guides/online-payments/fraud-and-risk/3d-secure-authentication) for an extra security layer when accepting card payments. - [Disable payment instruments](/guides/online-payments/fraud-and-risk/disabling-instruments) you know to be fraudulent. - [Integrate into Finix's fraud detection solution](/guides/online-payments/fraud-and-risk/fraud-detection) to mitigate chargeback risk. - [Handle declined payments](/guides/online-payments/fraud-and-risk/handling-declined-payments) to learn what to do when payments fail. - [Enable risk rules and card checks](/guides/online-payments/fraud-and-risk/risk-rules-card-checks) to verify card details before accepting payments. ### After the Payment After accepting an online payment, there are some final steps: - [Learn how you get paid from the payments you've processed](/guides/after-the-payment/payouts). - [Learn how to refund payments](/guides/after-the-payment/refunds). - [Learn what to do when a buyer reports a payment to their issuing bank](/guides/after-the-payment/disputes).