Creating Payment Links using the API
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

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.
Whether the payment amount is fixed or variable.
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.

Real-Time Updates with Webhooks

To get real-time updates on payment link events, integrate webhooks.

Single-use Payment Link

Request

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_type": "FIXED",
      "total_amount": 7500,
      "currency": "USD"
    },
    "additional_details": {
      "terms_of_service_url": "https://mybasketball-leaguexyz.com/terms"
    },
    "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"
    }
  }'

Response

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"
    }
  }
}

Multi-use Payment Link

Request

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": true,
    "allowed_payment_methods": [
      "PAYMENT_CARD",
      "BANK_ACCOUNT"
    ],
    "amount_details": {
      "amount_type": "FIXED",
      "total_amount": 7500,
      "currency": "USD"
    },
    "additional_details": {
      "terms_of_service_url": "https://mybasketball-leaguexyz.com/terms"
    },
    "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"
    }
  }'

Response

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"
    }
  }
}

Level 2 Processing

You can enable Level 2 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

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,
        "tax_exempt": true
      },
      "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,
    "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"
    }
  }'

Response

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, 
      "subtotal_amount": null,
      "shipping_amount": null,
      "estimated_tax_amount": 429, 
      "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, 
  "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", 
    "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"
    }
  }
}

Level 3 Processing

You can enable 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

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,
        "shipping_amount": 995,
        "customs_duty_amount": 10,
        "tax_exempt": true
      },
      "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,
    "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"
    },
     "items": [
      {
        "name": "Holiday Dinner Contribution",
        "description": "Your personal contribution to the holiday dinner.",
        "quantity": "1",
        "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": {
          "commodity_code": "175-62-20",
          "merchant_product_code": "1149611",
          "unit_of_measure": "BX",
          "cost_per_unit": 500
        },
        "price_details": {
          "amount_excluding_sales_tax": 5000,
          "currency": "USD",
          "item_discount_amount": 1000,
          "price_type": "PROMOTIONAL",
          "regular_amount": 5000,
          "sale_amount": 7500
        }
      }
    ]
  }'

Response

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, 
      "subtotal_amount": 3994,
      "shipping_amount": 995, 
      "estimated_tax_amount": null, 
      "discount_amount": 1000, 
      "tip_amount": null,
      "customs_duty_amount": 10, 
      "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, 
  "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", 
    "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.", 
      "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", 
        "merchant_product_code": "1149611", 
        "unit_of_measure": "BX", 
        "cost_per_unit": 500
      },
      "name": "Holiday Dinner Contribution",
      "price_details": {
        "sale_amount": 7500,
        "currency": "USD",
        "price_type": "PROMOTIONAL",
        "regular_amount": 5000, 
        "amount_excluding_sales_tax": 5000, 
        "item_discount_amount": 1000
      },
      "quantity": 1
    }
  ],
  "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"
    }
  }
}

Successful Payments

When a buyer successfully submits a payment using a payment link, the state of the payment link updates to COMPLETED.

Creating Payment Links using the APICopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from ClaudeConnect to CursorInstall MCP server on CursorConnect to VS CodeInstall MCP server on VS Code

Single-use Payment Link

Request

Response

Multi-use Payment Link

Request

Response

Level 2 Processing

Request

Response

Level 3 Processing

Request

Response

Successful Payments

Was this helpful?