# Creating Payment Links using the API To create a `Payment Link`, include: - The `Merchant` ID. The payment link will be associated with the `Merchant`. - Whether the payment link is [single or multiple-use](/low-code-no-code/payment-links/how-payment-links-work#payment-link-types). - Whether the payment amount is [fixed or variable](/low-code-no-code/payment-links/how-payment-links-work#amount-types). - A list of products/services. - Any additional URLs (A Terms of Service URL is required). - Allowed payment methods. At this time, only approved merchants with one of the following processors can create payment links: - `DUMMY_V1` - `LITLE_V1` - `FINIX_V1` To find detailed API information and example requests, check out our [Payment Links API Reference](/api/payment-links/createpaymentlink). Real-Time Updates with Webhooks To get real-time updates on payment link events, integrate [webhooks](/additional-resources/developers/webhooks/webhook-events#payment-link-created). ## Single-use Payment Link ### Request Example API Definition ### Response Example Payment Link - Single-Use ```json Payment Link - Single-Use { "id": "payment_link_ctZKsR5TUXLC4NULE95Y6", "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": null, "receipt_requested_delivery_methods": [], "send_receipt": false, "success_return_url": null, "terms_of_service_url": "https://mybasketball-leaguexyz.com/terms", "unsuccessful_return_url": null }, "allowed_payment_methods": [ "BANK_ACCOUNT", "PAYMENT_CARD" ], "amount_details": { "amount_breakdown": null, "amount_type": "FIXED", "currency": "USD", "max_amount": null, "min_amount": null, "total_amount": 7500 }, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "attempt_level_two_level_three_payment": false, "branding": { "accent_color": "#f3eeee", "brand_color": "#111823", "button_font_color": "#111823", "icon": "https://s3.amazonaws.com/customer-uploaded-assets-prod/11-16-2023-04_16_27_2022-04-28-22_56_33-finix-icon-v2.png_0feefc6d-06fe-4c50-a5e4-91dfeb183482", "logo": "https://s3.amazonaws.com/customer-uploaded-assets-prod/11-16-2023-04_16_27_2022-04-28-22_56_33-finix-logo-v2.png_0feefc6d-06fe-4c50-a5e4-91dfeb183482", "logo_alternative_text": null }, "buyer_details": null, "created_at": "2025-11-10T19:20:10.851928Z", "is_authorization": false, "is_multiple_use": false, "items": [], "link_expires_at": "2025-11-17T19:20:10.825665Z", "link_url": "https://link.sandbox-payments-checkout.com/iAh12H", "merchant_id": "MU7noQ1wdgdAeAfymw2rfBMq", "nickname": null, "payment_frequency": "ONE_TIME", "split_transfers": [], "state": "ACTIVE", "tags": {}, "updated_at": "2025-11-10T19:20:10.851928Z", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_links/payment_link_ctZKsR5TUXLC4NULE95Y6" } } } ``` API Definition ## Multi-use Payment Link ### Request Example API Definition #### Response Example Payment Link - Multi-Use ```json Payment Link - Multi-Use { "id": "payment_link_ctZKJBuMdQJRmrbLKtabZ", "additional_details": { "collect_billing_address": false, "collect_email": true, "collect_name": true, "collect_phone": false, "collect_shipping_address": false, "expiration_in_minutes": 1576800, "expired_session_url": null, "receipt_requested_delivery_methods": [], "send_receipt": false, "success_return_url": null, "terms_of_service_url": "https://mybasketball-leaguexyz.com/terms", "unsuccessful_return_url": null }, "allowed_payment_methods": [ "BANK_ACCOUNT", "PAYMENT_CARD" ], "amount_details": { "amount_breakdown": null, "amount_type": "FIXED", "currency": "USD", "max_amount": null, "min_amount": null, "total_amount": 7500 }, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "attempt_level_two_level_three_payment": false, "branding": { "accent_color": "#f3eeee", "brand_color": "#111823", "button_font_color": "#111823", "icon": "https://s3.amazonaws.com/customer-uploaded-assets-prod/11-16-2023-04_16_27_2022-04-28-22_56_33-finix-icon-v2.png_0feefc6d-06fe-4c50-a5e4-91dfeb183482", "logo": "https://s3.amazonaws.com/customer-uploaded-assets-prod/11-16-2023-04_16_27_2022-04-28-22_56_33-finix-logo-v2.png_0feefc6d-06fe-4c50-a5e4-91dfeb183482", "logo_alternative_text": null }, "buyer_details": null, "created_at": "2025-11-10T19:23:44.732243Z", "is_authorization": false, "is_multiple_use": true, "items": [], "link_expires_at": "2028-11-09T19:23:44.70264Z", "link_url": "https://link.sandbox-payments-checkout.com/irHFxX", "merchant_id": "MU7noQ1wdgdAeAfymw2rfBMq", "nickname": null, "payment_frequency": "ONE_TIME", "split_transfers": [], "state": "ACTIVE", "tags": {}, "updated_at": "2025-11-10T19:23:44.732243Z", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_links/payment_link_ctZKJBuMdQJRmrbLKtabZ" } } } ``` API Definition ## Level 2 Processing You can enable [Level 2 processing](/guides/online-payments/payment-features/level-2-level-3-processing) for payment links by setting the `attempt_level_two_level_three_payment` field to `true`. Refer to the following table to understand which fields you need to include to create a `Payment Link` with Level 2 processing. | **Field** | **Optional / Required** | **Description** | | --- | --- | --- | | `attempt_level_two_level_three_payment` | Required | When set to `true`, enables Level 2/Level 3 data collection for card payments. | | `buyer_details.customer_reference_number` | Required | The customer reference for the purchase (max 17 characters). | | `amount_breakdown.tax_exempt` | Optional | When set to `true`, the transaction is declared as tax exempt. | | `amount_breakdown.estimated_tax_amount` | Optional | The estimated amount of tax applied to the order. | ### Request Example ```shell curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/payment_links \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "merchant_id": "MU7noQ1wdgdAeAfymw2rfBMq", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "payment_frequency": "ONE_TIME", "is_multiple_use": false, "allowed_payment_methods": [ "PAYMENT_CARD", "BANK_ACCOUNT" ], "amount_details": { "amount_breakdown": { "estimated_tax_amount": 429, // [!code highlight] "tax_exempt": true // [!code highlight] }, "amount_type": "FIXED", "total_amount": 429, "currency": "USD" }, "additional_details": { "terms_of_service_url": "https://mybasketball-leaguexyz.com/terms" }, "attempt_level_two_level_three_payment": true, // [!code highlight] "branding": { "brand_color": "#111823", "accent_color": "#f3eeee", "logo": "https://s3.amazonaws.com/customer-uploaded-assets-prod/11-16-2023-04_16_27_2022-04-28-22_56_33-finix-logo-v2.png_0feefc6d-06fe-4c50-a5e4-91dfeb183482", "icon": "https://s3.amazonaws.com/customer-uploaded-assets-prod/11-16-2023-04_16_27_2022-04-28-22_56_33-finix-icon-v2.png_0feefc6d-06fe-4c50-a5e4-91dfeb183482", "button_font_color": "#111823" }, "buyer_details": { "customer_reference_number": "321xyz" // [!code highlight] } }' ``` API Definition ### Response Example Payment Link - Level 2 Processing ```json Payment Link - Level 2 Processing { "id": "payment_link_cvcCVsW6VWVhhZ13DWCLk", "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": null, "receipt_requested_delivery_methods": [], "send_receipt": false, "success_return_url": null, "terms_of_service_url": "https://mybasketball-leaguexyz.com/terms", "unsuccessful_return_url": null }, "allowed_payment_methods": [ "BANK_ACCOUNT", "PAYMENT_CARD" ], "amount_details": { "amount_breakdown": { "tax_exempt": true, // [!code highlight] "subtotal_amount": null, "shipping_amount": null, "estimated_tax_amount": 429, // [!code highlight] "discount_amount": null, "tip_amount": null, "customs_duty_amount": null, "additional_buyer_charges": null }, "amount_type": "FIXED", "currency": "USD", "max_amount": null, "min_amount": null, "total_amount": 429 }, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "attempt_level_two_level_three_payment": true, // [!code highlight] "branding": { "accent_color": "#f3eeee", "brand_color": "#111823", "button_font_color": "#111823", "icon": "https://s3.amazonaws.com/customer-uploaded-assets-prod/11-16-2023-04_16_27_2022-04-28-22_56_33-finix-icon-v2.png_0feefc6d-06fe-4c50-a5e4-91dfeb183482", "logo": "https://s3.amazonaws.com/customer-uploaded-assets-prod/11-16-2023-04_16_27_2022-04-28-22_56_33-finix-logo-v2.png_0feefc6d-06fe-4c50-a5e4-91dfeb183482", "logo_alternative_text": null }, "buyer_details": { "customer_reference_number": "321xyz", // [!code highlight] "first_name": null, "identity_id": null, "last_name": null }, "created_at": "2025-12-17T17:15:59.631583Z", "is_authorization": false, "is_multiple_use": false, "items": [], "link_expires_at": "2025-12-24T17:15:59.599071Z", "link_url": "https://link.sandbox-payments-checkout.com/XmXvyY", "merchant_id": "MU7noQ1wdgdAeAfymw2rfBMq", "nickname": null, "payment_frequency": "ONE_TIME", "split_transfers": [], "state": "ACTIVE", "tags": {}, "updated_at": "2025-12-17T17:15:59.631583Z", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_links/payment_link_cvcCVsW6VWVhhZ13DWCLk" } } } ``` API Definition ## Level 3 Processing You can enable [Level 3 processing](/guides/online-payments/payment-features/level-2-level-3-processing) for payment links by setting the `attempt_level_two_level_three_payment` field to `true`. Refer to the following table to understand which fields you need to include to process a payment link with Level 3 processing. In order for a transaction to qualify for Level 3 processing, the `amount_details.amount_breakdown.estimated_tax_amount` field must omitted or set to `null`. | **Field** | **Optional / Required** | **Description** | | --- | --- | --- | | `attempt_level_two_level_three_payment` | Required | When set to `true`, enables Level 2/Level 3 data collection for card payments. | | `amount_details.amount_breakdown.customs_duty_amount` | Optional | The duty in cents on the total purchase amount for the order. This field is optional for Level 3 processing, but its value must be at least `0`. | | `amount_details.amount_breakdown.discount_amount` | Optional | The amount in cents of the discount for the order. This field is optional for Level 3 processing, but its value must be at least `0`. | | `amount_details.amount_breakdown.shipping_amount` | Optional | The shipping cost in cents for the order. This field is optional for Level 3 processing, but its value must be at least `0`. | | `amount_details.amount_breakdown.tax_exempt` | Optional | When set to `true`, the transaction is declared as tax exempt. | | `buyer_details.customer_reference_number` | Required | The customer reference for the purchase (max 17 characters). | | `items.quantity` | Required | The item quantity. | | `items.description` | Required | An item description. | | `items.item_details.commodity_code` | Required | Commodity code for the item. | | `items.item_details.merchant_product_code` | Required | Merchant's product code for the item. | | `items.item_details.unit_of_measure` | Required | Unit of measure for the item. | | `items.item_details.cost_per_unit` | Required | Cost per unit in cents. | | `items.price_details.amount_excluding_sales_tax` | Required | The amount excluding sales tax. | | `items.price_details.item_discount_amount` | Optional | The item discount amount in cents. This field is optional for Level 3 processing, but its value must be at least `0`. | | `items.price_details.regular_amount` | Required | The standard price of the item without any adjustments applied (e.g. discounts, taxes, sales). | ### Request Example ```shell curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/payment_links \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "merchant_id": "MU7noQ1wdgdAeAfymw2rfBMq", "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "payment_frequency": "ONE_TIME", "is_multiple_use": false, "allowed_payment_methods": [ "PAYMENT_CARD", "BANK_ACCOUNT" ], "amount_details": { "amount_breakdown": { "subtotal_amount": 3994, "discount_amount": 1000, // [!code highlight] "shipping_amount": 995, // [!code highlight] "customs_duty_amount": 10, // [!code highlight] "tax_exempt": true // [!code highlight] }, "amount_type": "FIXED", "total_amount": 3999, "currency": "USD" }, "additional_details": { "terms_of_service_url": "https://mybasketball-leaguexyz.com/terms" }, "attempt_level_two_level_three_payment": true, // [!code highlight] "branding": { "brand_color": "#111823", "accent_color": "#f3eeee", "logo": "https://s3.amazonaws.com/customer-uploaded-assets-prod/11-16-2023-04_16_27_2022-04-28-22_56_33-finix-logo-v2.png_0feefc6d-06fe-4c50-a5e4-91dfeb183482", "icon": "https://s3.amazonaws.com/customer-uploaded-assets-prod/11-16-2023-04_16_27_2022-04-28-22_56_33-finix-icon-v2.png_0feefc6d-06fe-4c50-a5e4-91dfeb183482", "button_font_color": "#111823" }, "buyer_details": { "customer_reference_number": "321xyz" // [!code highlight] }, "items": [ { "name": "Holiday Dinner Contribution", "description": "Your personal contribution to the holiday dinner.", // [!code highlight] "quantity": "1", // [!code highlight] "image_details": { "primary_image_url": "https://images.unsplash.com/photo-1608835149345-b4d77bc490ae?q=80&w=3272&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" }, "item_details": { // [!code highlight] "commodity_code": "175-62-20", // [!code highlight] "merchant_product_code": "1149611", // [!code highlight] "unit_of_measure": "BX", // [!code highlight] "cost_per_unit": 500 // [!code highlight] }, // [!code highlight] "price_details": { "amount_excluding_sales_tax": 5000, // [!code highlight] "currency": "USD", "item_discount_amount": 1000, "price_type": "PROMOTIONAL", "regular_amount": 5000, // [!code highlight] "sale_amount": 7500 } } ] }' ``` API Definition ### Response Example Payment Link - Level 3 Processing ```json Payment Link - Level 3 Processing { "id": "payment_link_cvcCyRyxTyURbGLwwxnGh", "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": null, "receipt_requested_delivery_methods": [], "send_receipt": false, "success_return_url": null, "terms_of_service_url": "https://mybasketball-leaguexyz.com/terms", "unsuccessful_return_url": null }, "allowed_payment_methods": [ "BANK_ACCOUNT", "PAYMENT_CARD" ], "amount_details": { "amount_breakdown": { "tax_exempt": true, // [!code highlight] "subtotal_amount": 3994, "shipping_amount": 995, // [!code highlight] "estimated_tax_amount": null, // [!code highlight] "discount_amount": 1000, // [!code highlight] "tip_amount": null, "customs_duty_amount": 10, // [!code highlight] "additional_buyer_charges": null }, "amount_type": "FIXED", "currency": "USD", "max_amount": null, "min_amount": null, "total_amount": 3999 }, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "attempt_level_two_level_three_payment": true, // [!code highlight] "branding": { "accent_color": "#f3eeee", "brand_color": "#111823", "button_font_color": "#111823", "icon": "https://s3.amazonaws.com/customer-uploaded-assets-prod/11-16-2023-04_16_27_2022-04-28-22_56_33-finix-icon-v2.png_0feefc6d-06fe-4c50-a5e4-91dfeb183482", "logo": "https://s3.amazonaws.com/customer-uploaded-assets-prod/11-16-2023-04_16_27_2022-04-28-22_56_33-finix-logo-v2.png_0feefc6d-06fe-4c50-a5e4-91dfeb183482", "logo_alternative_text": null }, "buyer_details": { "customer_reference_number": "321xyz", // [!code highlight] "first_name": null, "identity_id": null, "last_name": null }, "created_at": "2025-12-17T17:11:20.034555Z", "is_authorization": false, "is_multiple_use": false, "items": [ { "description": "Your personal contribution to the holiday dinner.", // [!code highlight] "image_details": { "primary_image_url": "https://images.unsplash.com/photo-1608835149345-b4d77bc490ae?q=80&w=3272&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D", "alternative_image_urls": [] }, "item_details": { "commodity_code": "175-62-20", // [!code highlight] "merchant_product_code": "1149611", // [!code highlight] "unit_of_measure": "BX", // [!code highlight] "cost_per_unit": 500 // [!code highlight] }, "name": "Holiday Dinner Contribution", "price_details": { "sale_amount": 7500, "currency": "USD", "price_type": "PROMOTIONAL", "regular_amount": 5000, // [!code highlight] "amount_excluding_sales_tax": 5000, // [!code highlight] "item_discount_amount": 1000 // [!code highlight] }, "quantity": 1 // [!code highlight] } ], "link_expires_at": "2025-12-24T17:11:20.002213Z", "link_url": "https://link.sandbox-payments-checkout.com/mxgK6U", "merchant_id": "MU7noQ1wdgdAeAfymw2rfBMq", "nickname": null, "payment_frequency": "ONE_TIME", "split_transfers": [], "state": "ACTIVE", "tags": {}, "updated_at": "2025-12-17T17:11:20.034555Z", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_links/payment_link_cvcCyRyxTyURbGLwwxnGh" } } } ``` API Definition ## Successful Payments When a buyer successfully submits a payment using a payment link, the `state` of the payment link updates to `COMPLETED`.