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.

Payment Links are links you can send to buyers to complete a transaction. You can share these links on web pages, email, text, QR codes, and more.

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 USksBJMwkNUz5GyxPevL2yFY:71b641c1-861d-435b-9a9c-532760731c5e

Response samples

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. 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. Create a Payment Link to help a buyer submit a payment.

Related guides: Payment Links.

Request

header Parameters

Accept	string Default: application/hal+json
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

curl https://finix.sandbox-payments-api.com/payment_links \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -u USksBJMwkNUz5GyxPevL2yFY:71b641c1-861d-435b-9a9c-532760731c5e \
  -X POST \
  -d '{
    "merchant_id": "MUaC9hbNvRwBoCJzqrjWk69N",
    "application_id": "AP32VuKPGvgg4qEVo54qazAD",
    "payment_frequency": "ONE_TIME",
    "is_multiple_use": true,
    "allowed_payment_methods": [
        "PAYMENT_CARD",
        "BANK_ACCOUNT"
    ],
    "nickname": "Basketball League Holiday Dinner 2",
    "items": [
        {
            "name": "Holiday Dinner Contribution",
            "quantity": "1",
            "image_details": {
                "primary_image_url": "https://shop.momofuku.com/cdn/shop/articles/Holidays_2021_Table_Spread_3.jpg?v=1636317855"
            },
            "price_details": {
                "sale_amount": 7500,
                "currency": "USD"
            }
        }
    ],
    "amount_details": {
        "amount_type": "FIXED",
        "total_amount": 7500,
        "currency": "USD"
    },
    "additional_details": {
        "collect_name": true,
        "collect_email": true,
        "collect_phone": false,
        "collect_billing_address": false,
        "collect_shipping_address": false,
        "expiration_in_minutes": 1576800,
        "terms_of_service_url": "https://mybasketball-leaguexyz.com/terms",
        "success_return_url": "https://mybasketball-leaguexyz.com/success",
        "unsuccessful_return_url": "https://mybasketball-leaguexyz.com/failure",
        "expired_session_url": "https://mybasketball-leaguexyz.com/expired",
        "send_receipt": true,
        "receipt_requested_delivery_methods": [
            {
                "type": "EMAIL",
                "destinations": [
                    "abc@test.com"
                ]
            },
            {
                "type": "SMS",
                "destinations": [
                    "2348765431"
                ]
            }
        ]
    },
    "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"
    }
}'

Response samples

application/json

{"id": "payment_link_ceBaS82SqvsTeg84MDVaF",
"created_at": "2024-08-26T23:44:03.414715Z",
"updated_at": "2024-08-26T23:44:03.414715Z",
"application_id": "AP32VuKPGvgg4qEVo54qazAD",
"merchant_id": "MUaC9hbNvRwBoCJzqrjWk69N",
"payment_frequency": "ONE_TIME",
"is_multiple_use": "true",
"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": null
},
"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": null,
"link_url": "https://link.sandbox-payments-checkout.com/1zxlKh",
"link_expires_at": "2027-08-26T23:44:03.338674Z",
"_links": {"self": {"href": "https://finix.sandbox-payments-api.com/payment_links/payment_link_ceBaS82SqvsTeg84MDVaF"
}
}
}

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_ceBaS82SqvsTeg84MDVaF" \
-H "Finix-Version: 2022-02-01" \
-u USksBJMwkNUz5GyxPevL2yFY:71b641c1-861d-435b-9a9c-532760731c5e

Response samples

application/json

{"id": "payment_link_ceBaS82SqvsTeg84MDVaF",
"created_at": "2024-08-26T23:44:03.414715Z",
"updated_at": "2024-08-26T23:44:03.414715Z",
"application_id": "AP32VuKPGvgg4qEVo54qazAD",
"merchant_id": "MUaC9hbNvRwBoCJzqrjWk69N",
"payment_frequency": "ONE_TIME",
"is_multiple_use": "true",
"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": null
},
"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": null,
"link_url": "https://link.sandbox-payments-checkout.com/1zxlKh",
"link_expires_at": "2027-08-26T23:44:03.338674Z",
"_links": {"self": {"href": "https://finix.sandbox-payments-api.com/payment_links/payment_link_ceBaS82SqvsTeg84MDVaF"
}
}
}

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 payments 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

application/json

{"id": "payment_link_cheA4ir7TupbweCRcXBCS",
"created_at": "2024-11-15T11:51:37.434473Z",
"updated_at": "2024-11-15T11:54:11.88596Z",
"application_id": "AP32VuKPGvgg4qEVo54qazAD",
"merchant_id": "MUaC9hbNvRwBoCJzqrjWk69N",
"payment_frequency": "ONE_TIME",
"is_multiple_use": true,
"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": 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": {"order": "94752"
},
"link_url": "https://link.sandbox-payments-checkout.com/plZgsM",
"link_expires_at": "2027-11-15T11:51:37.389552Z",
"_links": {"self": {"href": "https://finix.sandbox-payments-api.com/payment_links/payment_link_cheA4ir7TupbweCRcXBCS"
}
}
}