Finix documentation
      Nothing Found
  • Documentation
  • API Reference
  • Log In
  • Sign Up
    Finix documentation
  • Documentation
  • API Reference
  • Log In
  • Sign Up
    Finix API Reference
    Authentication
    Sandbox and Live Endpoints
    Errors
    Idempotency Requests
    Tags
    Query Parameters
    Versioning
    Main Resources
    Authorizations
    Compliance Forms
    Devices
    Disputes
    Fees
    Fee Profiles
    Files
    Identities
    Merchants
    Onboarding Forms
    Payment Instruments
    Settlements
    Settlement Queue Entries
    Split Transfers
    Transfers
    Users
    Webhooks
    Low-Code / No-Code Resources
    Checkout Forms
    Payment Links
      get
      List Payment Links
      post
      Create a Payment Link
      get
      Fetch a Payment Link
      put
      Update a Payment Link
    Payout Links
    Receipts
    Subscriptions
    Subscription Plans
    Transfer Attempts
    Payout Resources
    Balances
    Balance Adjustments
    Core PayFac Resources
    Application Profiles
    Applications
    Balance Transfers
    Merchant Profiles
    Payout Profiles
    Review Queue Items
    Verifications

Payment Links

  • List Payment Links     —    GET /payment_links
  • Create a Payment Link     —    POST /payment_links
  • Fetch a Payment Link     —    GET /payment_links/{id}

Payment Links create individual links you can send to buyers to complete a transaction. You can share these links on different platforms such as web pages, email, text, or QR codes.

Related Guides: Payment Links

List Payment Links

Retrieve a list of previously created Payment Links.

Related guides: Payment Links.

For details on how to query endpoints using the available parameters, see Query Parameters.

Request
query Parameters
state
string

The state of the payment link.

Enum: "ACTIVE" "EXPIRED" "COMPLETED" "DEACTIVATED"
application_id
string

The ID of the Application that the Payment Link was created under.

created_at.gte
string <date-time>

Filter where created_at is after the given date.

created_at.lte
string <date-time>

Filter where created_at is before the given date.

merchant_id
string

The ID of the Merchant the payment is getting created under.

updated_at.gte
string

Filter where updated_at is after the given date.

updated_at.lte
string

Filter where updated_at is before the given date.

header Parameters
Finix-Version
string
Default: 2018-01-01

Specify the API version of your request. For more details, see Versioning.

Example: 2022-02-01
Responses
200

Example response

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

422

Invalid field

get/payment_links
Request samples
  • curl
curl "https://finix.sandbox-payments-api.com/payment_links" \
-H "Finix-Version: 2022-02-01" \
-u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda
Response samples
  • 200
  • 401
  • 404
  • 406
  • 422
application/json
{
  • "_embedded": {
    • "payment_links": [
      • {
        • "id": "payment_link_ceBaS82SqvsTeg84MDVaF",
        • "created_at": "2024-08-26T23:44:03.41Z",
        • "updated_at": "2024-08-26T23:44:03.58Z",
        • "additional_details": {
          • "collect_name": "true",
          • "collect_email": "true",
          • "collect_phone": "false",
          • "collect_billing_address": "false",
          • "collect_shipping_address": "false",
          • "success_return_url": "https://mybasketball-leaguexyz.com/success",
          • "unsuccessful_return_url": "https://mybasketball-leaguexyz.com/failure",
          • "expired_session_url": "https://mybasketball-leaguexyz.com/expired",
          • "terms_of_service_url": "https://mybasketball-leaguexyz.com/terms",
          • "expiration_in_minutes": "1576800",
          • "send_receipt": "true",
          • "receipt_requested_delivery_methods": [
            • {
              • "type": "EMAIL",
              • "destinations": [
                • "abc@test.com"
                ]
              },
            • {
              • "type": "SMS",
              • "destinations": [
                • "2348765431"
                ]
              }
            ]
          },
        • "allowed_payment_methods": [
          • "BANK_ACCOUNT",
          • "PAYMENT_CARD"
          ],
        • "amount_details": {
          • "amount_type": "FIXED",
          • "total_amount": "7500",
          • "currency": "USD",
          • "min_amount": null,
          • "max_amount": null,
          • "amount_breakdown": null
          },
        • "application_id": "AP32VuKPGvgg4qEVo54qazAD",
        • "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",
          • "logo_alternative_text": null,
          • "button_font_color": null
          },
        • "buyer_details": null,
        • "is_multiple_use": "true",
        • "items": [
          • {
            • "image_details": {
              • "primary_image_url": "https://shop.momofuku.com/cdn/shop/articles/Holidays_2021_Table_Spread_3.jpg?v=1636317855",
              • "alternative_image_urls": null
              },
            • "description": null,
            • "price_details": {
              • "sale_amount": "7500",
              • "currency": "USD",
              • "price_type": null,
              • "regular_amount": "0"
              },
            • "name": "Holiday Dinner Contribution",
            • "quantity": "1"
            }
          ],
        • "link_expires_at": "2027-08-26T23:44:03.338674Z",
        • "link_url": "https://link.sandbox-payments-checkout.com/1zxlKh",
        • "merchant_id": "MUaC9hbNvRwBoCJzqrjWk69N",
        • "nickname": "Basketball League Holiday Dinner 2",
        • "payment_frequency": "ONE_TIME",
        • "state": "ACTIVE",
        • "tags": null
        },
      • {
        • "id": "payment_link_ceBaKV1D76peSvQt1bPYp",
        • "created_at": "2024-08-26T23:42:39.20Z",
        • "updated_at": "2024-08-26T23:42:39.34Z",
        • "additional_details": {
          • "collect_name": "true",
          • "collect_email": "true",
          • "collect_phone": "false",
          • "collect_billing_address": "false",
          • "collect_shipping_address": "false",
          • "success_return_url": "https://mybasketball-leaguexyz.com/success",
          • "unsuccessful_return_url": "https://mybasketball-leaguexyz.com/failure",
          • "expired_session_url": "https://mybasketball-leaguexyz.com/expired",
          • "terms_of_service_url": "https://mybasketball-leaguexyz.com/terms",
          • "expiration_in_minutes": "1576800",
          • "send_receipt": "true",
          • "receipt_requested_delivery_methods": [
            • {
              • "type": "EMAIL",
              • "destinations": [
                • "abc@test.com"
                ]
              },
            • {
              • "type": "SMS",
              • "destinations": [
                • "2348765431"
                ]
              }
            ]
          },
        • "allowed_payment_methods": [
          • "BANK_ACCOUNT",
          • "PAYMENT_CARD"
          ],
        • "amount_details": {
          • "amount_type": "FIXED",
          • "total_amount": "7500",
          • "currency": "USD",
          • "min_amount": null,
          • "max_amount": null,
          • "amount_breakdown": null
          },
        • "application_id": "AP32VuKPGvgg4qEVo54qazAD",
        • "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",
          • "logo_alternative_text": null,
          • "button_font_color": null
          },
        • "buyer_details": null,
        • "is_multiple_use": "true",
        • "items": [
          • {
            • "image_details": {
              • "primary_image_url": "https://shop.momofuku.com/cdn/shop/articles/Holidays_2021_Table_Spread_3.jpg?v=1636317855",
              • "alternative_image_urls": null
              },
            • "description": null,
            • "price_details": {
              • "sale_amount": "7500",
              • "currency": "USD",
              • "price_type": null,
              • "regular_amount": "0"
              },
            • "name": "Holiday Dinner Contribution",
            • "quantity": "1"
            }
          ],
        • "link_expires_at": "2027-08-26T23:42:39.156853Z",
        • "link_url": "https://link.sandbox-payments-checkout.com/xzpZ2A",
        • "merchant_id": "MUaC9hbNvRwBoCJzqrjWk69N",
        • "nickname": "Basketball League Holiday Dinner 2",
        • "payment_frequency": "ONE_TIME",
        • "state": "ACTIVE",
        • "tags": null
        }
      ]
    },
  • "_links": {
    • "self": {
      • "href": "https://finix.sandbox-payments-api.com/payment_links"
      },
    • "next": {
      • "href": "https://finix.sandbox-payments-api.com/payment_links?after_cursor=payment_link_c7ADJ9PLbidXLX17iLGSZ"
      }
    },
  • "page": {
    • "limit": "100",
    • "next_cursor": "payment_link_c7ADJ9PLbidXLX17iLGSZ"
    }
}

Create a Payment Link

Create a Payment Link to help a buyer submit a payment.

Related guides: Payment Links.

Request
header Parameters
Finix-Version
string
Default: 2018-01-01

Specify the API version of your request. For more details, see Versioning.

Example: 2022-02-01
Request Body schema: application/json
merchant_id
required
string

The id of the Merchant the payment is getting created under. Currently, only Merchants on the following processors can use Payment Links: FINIX_V1, LITLE_V1, DUMMY_V1,

payment_frequency
required
string

Whether the Payment Link is single-use or recurring. Currently, only ONE_TIME is supported.

Enum: "ONE_TIME" "RECURRING"
is_multiple_use
boolean

If set to true, the payment link can be used for multiple purchases.

allowed_payment_methods
required
Array of strings

Payment methods allowed on the payment link.

nickname
required
string

Descriptor name of the payment link.

required
Array of objects

Details the items or services used in the payment link.

object

Object containing details about the buyer. This object is only used for SINGLE_USE payment links.

object

Object containing details about the amount getting charged by the payment link.

object

Object containing branding details for the payment link.

object

Object containing additional details that can be accepted from the buyer using the payment link.

object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)
Responses
200

Example response

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

422

Invalid field

post/payment_links
Request samples
  • curl
Response samples 
  • 200
  • 401
  • 404
  • 406
  • 422
application/json
{
  • "id": "payment_link_ciL8rqqShe8SdssbmfTnA",
  • "created_at": "2025-01-01T06:15:26.097859Z",
  • "updated_at": "2025-01-01T06:15:26.097859Z",
  • "application_id": "APc9vhYcPsRuTSpKD9KpMtPe",
  • "merchant_id": "MU7noQ1wdgdAeAfymw2rfBMq",
  • "payment_frequency": "ONE_TIME",
  • "is_multiple_use": false,
  • "allowed_payment_methods": [
    • "BANK_ACCOUNT",
    • "PAYMENT_CARD"
    ],
  • "nickname": "Basketball League Holiday Dinner 2",
  • "items": [
    • {
      • "image_details": {
        • "primary_image_url": "https://shop.momofuku.com/cdn/shop/articles/Holidays_2021_Table_Spread_3.jpg?v=1636317855",
        • "alternative_image_urls": [ ]
        },
      • "description": null,
      • "price_details": {
        • "sale_amount": 7500,
        • "currency": "USD",
        • "price_type": null,
        • "regular_amount": 0
        },
      • "name": "Holiday Dinner Contribution",
      • "quantity": 1
      }
    ],
  • "buyer_details": null,
  • "amount_details": {
    • "amount_type": "FIXED",
    • "total_amount": 7500,
    • "currency": "USD",
    • "min_amount": null,
    • "max_amount": null,
    • "amount_breakdown": null
    },
  • "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",
    • "logo_alternative_text": null,
    • "button_font_color": null
    },
  • "additional_details": {
    • "collect_name": true,
    • "collect_email": true,
    • "collect_phone": false,
    • "collect_billing_address": false,
    • "collect_shipping_address": false,
    • "success_return_url": "https://mybasketball-leaguexyz.com/success",
    • "unsuccessful_return_url": "https://mybasketball-leaguexyz.com/failure",
    • "expired_session_url": "https://mybasketball-leaguexyz.com/expired",
    • "terms_of_service_url": "https://mybasketball-leaguexyz.com/terms",
    • "expiration_in_minutes": 1576800,
    • "send_receipt": true,
    • "receipt_requested_delivery_methods": [
      • {
        • "type": "EMAIL",
        • "destinations": [
          • "abc@test.com"
          ]
        },
      • {
        • "type": "SMS",
        • "destinations": [
          • "2348765431"
          ]
        }
      ]
    },
  • "state": "ACTIVE",
  • "tags": { },
  • "link_url": "https://link.sandbox-payments-checkout.com/2Ze8WI",
  • "link_expires_at": "2028-01-01T06:15:26.044257Z",
  • "_links": {
    • "self": {
      • "href": "https://finix.sandbox-payments-api.com/payment_links/payment_link_ciL8rqqShe8SdssbmfTnA"
      }
    }
}
Fetch a Payment Link
Retrieve the details of a previously created Payment Link.


Request 
path Parameters
payment_link_id
required
string
The ID of the Payment Link.


 
header Parameters
Finix-Version
string
 Default:  2018-01-01
Specify the API version of your request. For more details, see Versioning.


 
 Example:  2022-02-01
Responses 
200
Example response


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


422
Invalid field


get/payment_links/{payment_link_id}
Request samples 
  • curl
curl "https://finix.sandbox-payments-api.com/payment_links/payment_link_ciACu5E9CqjqTmPq4k5WT" \
-H "Finix-Version: 2022-02-01" \
-u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda

Response samples 
  • 200
  • 401
  • 404
  • 406
  • 422
application/json
{
  • "id": "payment_link_ciL8rqqShe8SdssbmfTnA",
  • "created_at": "2025-01-01T06:15:26.097859Z",
  • "updated_at": "2025-01-01T06:15:26.097859Z",
  • "application_id": "APc9vhYcPsRuTSpKD9KpMtPe",
  • "merchant_id": "MU7noQ1wdgdAeAfymw2rfBMq",
  • "payment_frequency": "ONE_TIME",
  • "is_multiple_use": false,
  • "allowed_payment_methods": [
    • "BANK_ACCOUNT",
    • "PAYMENT_CARD"
    ],
  • "nickname": "Basketball League Holiday Dinner 2",
  • "items": [
    • {
      • "image_details": {
        • "primary_image_url": "https://shop.momofuku.com/cdn/shop/articles/Holidays_2021_Table_Spread_3.jpg?v=1636317855",
        • "alternative_image_urls": [ ]
        },
      • "description": null,
      • "price_details": {
        • "sale_amount": 7500,
        • "currency": "USD",
        • "price_type": null,
        • "regular_amount": 0
        },
      • "name": "Holiday Dinner Contribution",
      • "quantity": 1
      }
    ],
  • "buyer_details": null,
  • "amount_details": {
    • "amount_type": "FIXED",
    • "total_amount": 7500,
    • "currency": "USD",
    • "min_amount": null,
    • "max_amount": null,
    • "amount_breakdown": null
    },
  • "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",
    • "logo_alternative_text": null,
    • "button_font_color": null
    },
  • "additional_details": {
    • "collect_name": true,
    • "collect_email": true,
    • "collect_phone": false,
    • "collect_billing_address": false,
    • "collect_shipping_address": false,
    • "success_return_url": "https://mybasketball-leaguexyz.com/success",
    • "unsuccessful_return_url": "https://mybasketball-leaguexyz.com/failure",
    • "expired_session_url": "https://mybasketball-leaguexyz.com/expired",
    • "terms_of_service_url": "https://mybasketball-leaguexyz.com/terms",
    • "expiration_in_minutes": 1576800,
    • "send_receipt": true,
    • "receipt_requested_delivery_methods": [
      • {
        • "type": "EMAIL",
        • "destinations": [
          • "abc@test.com"
          ]
        },
      • {
        • "type": "SMS",
        • "destinations": [
          • "2348765431"
          ]
        }
      ]
    },
  • "state": "ACTIVE",
  • "tags": { },
  • "link_url": "https://link.sandbox-payments-checkout.com/2Ze8WI",
  • "link_expires_at": "2028-01-01T06:15:26.044257Z",
  • "_links": {
    • "self": {
      • "href": "https://finix.sandbox-payments-api.com/payment_links/payment_link_ciL8rqqShe8SdssbmfTnA"
      }
    }
}
Update a Payment Link
Update an existing Payment Link resource, commonly used for:


    

  • Adding or updating tags and nickname
    • 

  • Toggling the payment link's state between ACTIVE and DEACTIVATED
    • 

  • Modifying allowed_payment_methods for an ACTIVE payment link
    • 

  • Modifying buyer_details for an ACTIVE single-use payment link
    • 



The only fields that can be updated for COMPLETED, EXPIRED, or DEACTIVATED payment links are nickname and tags.


Request 
path Parameters
payment_link_id
required
string
The ID of the Payment Link.


 
header Parameters
Finix-Version
string
 Default:  2018-01-01
Specify the API version of your request. For more details, see Versioning.


 
 Example:  2022-02-01
Request Body schema: application/json
One of:
allowed_payment_methods
Array of strings
Payment methods allowed on the Payment Link. Acceptable values for array items are:


    

  • BANK_ACCOUNT
    • 

  • PAYMENT_CARD
    • 



 
nickname
string
A human-readable name for the resource.


 
state
string
The state of the Payment Link.


 Enum: "ACTIVE" "DEACTIVATED"  
object or null
Include up to 50 key: value pairs to annotate requests with custom metadata.


    

  • Maximum character length for individual keys is 40.
    • 

  • Maximum character length for individual values is 500.
(For example, order_number: 25, item_type: produce, department: sales)
    • 



 
Responses 
200
Response examples for a request to update a Payment Link.


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


422
Invalid field


put/payment_links/{payment_link_id}
Request samples 
  • curl
Response samples 
  • 200
  • 401
  • 403
  • 404
  • 422
application/json
{
  • "id": "payment_link_ciL8rqqShe8SdssbmfTnA",
  • "created_at": "2025-01-01T06:15:26.097859Z",
  • "updated_at": "2025-01-01T06:19:00.724691Z",
  • "application_id": "APc9vhYcPsRuTSpKD9KpMtPe",
  • "merchant_id": "MU7noQ1wdgdAeAfymw2rfBMq",
  • "payment_frequency": "ONE_TIME",
  • "is_multiple_use": false,
  • "allowed_payment_methods": [
    • "BANK_ACCOUNT",
    • "PAYMENT_CARD"
    ],
  • "nickname": "Rental Payment – Apartment 101",
  • "items": [
    • {
      • "image_details": {
        • "primary_image_url": "https://shop.momofuku.com/cdn/shop/articles/Holidays_2021_Table_Spread_3.jpg?v=1636317855",
        • "alternative_image_urls": [ ]
        },
      • "description": null,
      • "price_details": {
        • "sale_amount": 7500,
        • "currency": "USD",
        • "price_type": null,
        • "regular_amount": 0
        },
      • "name": "Holiday Dinner Contribution",
      • "quantity": 1
      }
    ],
  • "buyer_details": {
    • "identity_id": "IDmj1yA97RS4rMjiQgvK3Vio",
    • "first_name": "John",
    • "last_name": "Adams"
    },
  • "amount_details": {
    • "amount_type": "FIXED",
    • "total_amount": 7500,
    • "currency": "USD",
    • "min_amount": null,
    • "max_amount": null,
    • "amount_breakdown": null
    },
  • "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",
    • "logo_alternative_text": null,
    • "button_font_color": null
    },
  • "additional_details": {
    • "collect_name": true,
    • "collect_email": true,
    • "collect_phone": false,
    • "collect_billing_address": false,
    • "collect_shipping_address": false,
    • "success_return_url": "https://mybasketball-leaguexyz.com/success",
    • "unsuccessful_return_url": "https://mybasketball-leaguexyz.com/failure",
    • "expired_session_url": "https://mybasketball-leaguexyz.com/expired",
    • "terms_of_service_url": "https://mybasketball-leaguexyz.com/terms",
    • "expiration_in_minutes": 1576800,
    • "send_receipt": true,
    • "receipt_requested_delivery_methods": [
      • {
        • "type": "EMAIL",
        • "destinations": [
          • "abc@test.com"
          ]
        },
      • {
        • "type": "SMS",
        • "destinations": [
          • "2348765431"
          ]
        }
      ]
    },
  • "state": "ACTIVE",
  • "tags": {
    • "order": "94752"
    },
  • "link_url": "https://link.sandbox-payments-checkout.com/2Ze8WI",
  • "link_expires_at": "2028-01-01T06:15:26.044257Z",
  • "_links": {
    • "self": {
      • "href": "https://finix.sandbox-payments-api.com/payment_links/payment_link_ciL8rqqShe8SdssbmfTnA"
      }
    }
}
RESOURCES
  • Finix Home
  • Finix Support
  • Privacy Policy
  • Cookie Policy
  • PCI DSS Compliant
SOCIAL MEDIA
  • Linkedin
  • Twitter
Copyright © Finix 2016 - 2024. All right reserved.