# 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.

Endpoint: GET /payment_links
Version: 2022-02-01
Security: BasicAuth

## Header parameters:

  - `Finix-Version` (string)
    Specify the API version of your request. For more details, see Versioning.
    Example: "2022-02-01"

## 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)
    Filter where created_at is after the given date.

  - `created_at.lte` (string)
    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.

## Response 200 fields (application/json):

  - `_embedded` (object)

  - `_embedded.payment_links` (array)

  - `_embedded.payment_links.id` (string)
    The ID of the resource.

  - `_embedded.payment_links.created_at` (string)
    Timestamp of when the object was created.

  - `_embedded.payment_links.updated_at` (string)
    Timestamp of when the object was last updated.

  - `_embedded.payment_links.additional_details` (object)
    Object containing additional details.

  - `_embedded.payment_links.additional_details.collect_billing_address` (boolean)
    The collected billing address. Defaults to false.

  - `_embedded.payment_links.additional_details.collect_email` (boolean)
    The collected email address.

  - `_embedded.payment_links.additional_details.collect_name` (boolean)
    The collected name.

  - `_embedded.payment_links.additional_details.collect_shipping_address` (boolean)
    The collected shipping address.

  - `_embedded.payment_links.additional_details.expiration_in_minutes` (integer)
    The expiration in minutes. The maximum value is 1576800 minutes (3 years).

  - `_embedded.payment_links.additional_details.expired_session_url` (string)
    A URL to redirect the user if their session times out.

  - `_embedded.payment_links.additional_details.receipt_requested_delivery_methods` (array)
    A list of requested delivery methods. Each method specifies 
the type of delivery and the destination(s) where the receipt should be sent.

  - `_embedded.payment_links.additional_details.receipt_requested_delivery_methods.type` (string, required)
    The method of receipt delivery.
    Enum: "EMAIL", "SMS", "PRINT"

  - `_embedded.payment_links.additional_details.receipt_requested_delivery_methods.destinations` (array, required)
    A list of destination addresses or identifiers where the receipt should be sent.

  - `_embedded.payment_links.additional_details.send_receipt` (boolean)
    Whether to send the user a receipt.

  - `_embedded.payment_links.additional_details.statement_descriptor` (string,null)
    The description of the Merchant that appears on the buyer's bank or card statement.

  - `_embedded.payment_links.additional_details.success_return_url` (string)
    The redirect URL for a successful outcome.

  - `_embedded.payment_links.additional_details.terms_of_service_url` (string, required)
    Your Terms of Service URL.

  - `_embedded.payment_links.additional_details.unsuccessful_return_url` (string)
    The redirect URL for an unsuccessful outcome.

  - `_embedded.payment_links.additional_details.collect_phone` (boolean)
    The collected phone number.

  - `_embedded.payment_links.allowed_payment_methods` (array)
    The allowed payment methods.
    Enum: "APPLE_PAY", "BANK_ACCOUNT", "GOOGLE_PAY", "PAYMENT_CARD"

  - `_embedded.payment_links.amount_details` (object)
    Object containing amount details.

  - `_embedded.payment_links.amount_details.amount_breakdown` (object)
    The individual charges/fees that add up to the total amount. This field is required for the transaction to qualify for Level 2 or Level 3 processing.

  - `_embedded.payment_links.amount_details.amount_breakdown.additional_buyer_charges` (object,null)
    Additional charges incurred by the buyer. Only one charge can be applied per transaction (mutually exclusive).

The Merchant must be enabled for each surcharge via the [PUT /merchants](/api/merchants/updatemerchant) endpoint.

Supported charges by Payment Link type:

| Charge | FIXED | VARIABLE |
|---|---|---|
| surcharge_amount | Yes | Yes |
| convenience_amount | Yes* | No |
| rent_surcharge_amount | Yes | Yes |

*Not allowed if bank account is the only permitted payment method.

Tip: To have Finix calculate the surcharge automatically, pass surcharge_basis_points in the request and omit (or null) additional_buyer_charges. The response will reflect the calculated surcharge.

  - `_embedded.payment_links.amount_details.amount_breakdown.additional_buyer_charges.convenience_amount` (integer,null)
    A convenience fee to charge the buyer for the transaction. This object property is mutually exclusive.

  - `_embedded.payment_links.amount_details.amount_breakdown.additional_buyer_charges.rent_surcharge_amount` (integer,null)
    A rent surcharge to charge the buyer for the transaction. This object property is mutually exclusive.

  - `_embedded.payment_links.amount_details.amount_breakdown.additional_buyer_charges.surcharge_amount` (integer,null)
    A surcharge amount to charge the buyer for the transaction. This object property is mutually exclusive.

  - `_embedded.payment_links.amount_details.amount_breakdown.customs_duty_amount` (integer)
    The duty in cents on the total payment amount. This field is required for level 3 processing, and if provided, it must have a value of at least 0.

  - `_embedded.payment_links.amount_details.amount_breakdown.discount_amount` (integer)
    A reduction applied to the total amount. If Level 2/3 processing is enabled, this optional field must have a value of at least 0.

  - `_embedded.payment_links.amount_details.amount_breakdown.estimated_tax_amount` (integer)
    The estimated amount of tax applied to the order. This field is optional for Level 2 processing. In order for a transaction to qualify for Level 3 processing, this field must omitted or set to null.

  - `_embedded.payment_links.amount_details.amount_breakdown.subtotal_amount` (integer)
    The subtotal amount before any taxes, shipping, or additional charges are applied.

  - `_embedded.payment_links.amount_details.amount_breakdown.shipping_amount` (integer)
    The amount charged for shipping the items in the order. If Level 2/3 processing is enabled, this optional field must have a value of at least 0.

  - `_embedded.payment_links.amount_details.amount_breakdown.tax_exempt` (boolean)
    For tax exempt payments set to true. This field is used for Level 2/3 processing when enabled, but it is optional.

  - `_embedded.payment_links.amount_details.amount_breakdown.tip_amount` (integer)
    The tip amount included in the order total.

  - `_embedded.payment_links.amount_details.amount_type` (string)
    The supported enums are:

FIXED - A set amount that cannot be altered by the user. 
VARIABLE - Allows the user to set their own amount, provided it adheres to the minimum and maximum limits (min_amount and max_amount, respectively).
    Enum: "FIXED", "VARIABLE"

  - `_embedded.payment_links.amount_details.currency` (string)
    3-letter ISO code designating the currency of the Transfers (e.g. USD).

  - `_embedded.payment_links.amount_details.max_amount` (integer,null)
    Maximum amount allowed when the amount is VARIABLE.

  - `_embedded.payment_links.amount_details.min_amount` (integer,null)
    Minimum amount allowed when the amount is VARIABLE.

  - `_embedded.payment_links.amount_details.surcharge_basis_points` (integer,null)
    The surcharge amount in basis points to add to the transfer when a payment is submitted. 100 basis points = 1%.

- For USA merchants, must be greater than 0 and less than or equal to 300.
- For CAN merchants, must be greater than 0 and less than or equal to 240.
- If present, additional_buyer_charges must be null.

The surcharge applies only to credit card payments. The surcharge amount appears in the resulting Transfer and Transfer Attempt resources under additional_buyer_charges.surcharge_amount.
    Example: 200

  - `_embedded.payment_links.amount_details.total_amount` (integer)
    The total amount.

  - `_embedded.payment_links.application_id` (string)
    The ID of the Application that the Payment Link was created under.

  - `_embedded.payment_links.attempt_level_two_level_three_payment` (boolean)
    Setting this field to true enables Level 2/Level 3 data collection for card payments.

  - `_embedded.payment_links.branding` (object)

  - `_embedded.payment_links.branding.accent_color` (string, required)
    Hex code of the accent color.
    Example: "#F2F2F2"

  - `_embedded.payment_links.branding.brand_color` (string, required)
    Hex code of branding color.
    Example: "#F2F2F2"

  - `_embedded.payment_links.branding.button_font_color` (string,null)
    Hex code of the button font color.

  - `_embedded.payment_links.branding.icon` (string, required)
    URL for the icon of the payment link.

  - `_embedded.payment_links.branding.logo` (string, required)
    URL of the logo for the payment link.

  - `_embedded.payment_links.branding.logo_alternative_text` (string,null)
    Alternate text displayed if the logo image cannot display.

  - `_embedded.payment_links.buyer_details` (object)
    Object containing details about the buyer. This object is only used for SINGLE_USE payment links.

  - `_embedded.payment_links.buyer_details.customer_reference_number` (string)
    The customer reference for the purchase (max 17 characters). Required for Level 2 / Level 3 processing. 

For Visa, after April 17, 2026, this field no longer qualifies for lower interchange rates. You must pass level 3 data instead.

  - `_embedded.payment_links.buyer_details.first_name` (string)
    First name of the buyer.

  - `_embedded.payment_links.buyer_details.identity_id` (string)
    The Identity ID of the buyer.

  - `_embedded.payment_links.buyer_details.last_name` (string)
    Last name of the buyer.

  - `_embedded.payment_links.is_authorization` (boolean)
    When set to true, submitting the Payment Link creates an Authorization instead of a Transfer.

  - `_embedded.payment_links.is_multiple_use` (boolean)
    If set to true, the payment link can be used for multiple purchases.

  - `_embedded.payment_links.items` (array)
    An itemized list of products/services. This field is required for the transaction to qualify for Level 3 processing.

  - `_embedded.payment_links.items.description` (string)
    A item description. This field is required for the transaction to qualify for Level 3 processing.

  - `_embedded.payment_links.items.image_details` (object)
    Product/service image locations.

  - `_embedded.payment_links.items.image_details.primary_image_url` (string)
    The location of a item image.

  - `_embedded.payment_links.items.image_details.alternative_image_urls` (array)
    The locations of backup images if there is an issue with the primary image.

  - `_embedded.payment_links.items.item_details` (object)
    Additional details about the item. This object and all of its fields are required for the transaction to qualify for Level 3 processing.

  - `_embedded.payment_links.items.item_details.commodity_code` (string, required)
    Commodity code for the item.
    Example: "175-62-20"

  - `_embedded.payment_links.items.item_details.merchant_product_code` (string, required)
    Merchant's product code for the item.
    Example: "1149611"

  - `_embedded.payment_links.items.item_details.unit_of_measure` (string, required)
    Unit of measure for the item.
    Example: "BX"

  - `_embedded.payment_links.items.item_details.cost_per_unit` (integer, required)
    Cost per unit in cents.
    Example: 500

  - `_embedded.payment_links.items.name` (string)
    The item name.

  - `_embedded.payment_links.items.price_details` (object)
    Additional details about the price. This field is required for the transaction to qualify for Level 3 processing.

  - `_embedded.payment_links.items.price_details.amount_excluding_sales_tax` (integer)
    The amount excluding sales tax. This field is required for the transaction to qualify for Level 3 processing.

  - `_embedded.payment_links.items.price_details.sale_amount` (integer)
    The on-sale price of the item if it is different from the regular_amount.

  - `_embedded.payment_links.items.price_details.currency` (string)
    ISO 4217 3-letter currency code.
    Enum: "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYR", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "SSP", "STD", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "UYI", "UYU", "UZS", "VEF", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XOF", "XPD", "XPF", "XPT", "XSU", "XTS", "XUA", "XXX", "YER", "ZAR", "ZMW", "ZWL"

  - `_embedded.payment_links.items.price_details.price_type` (string)
    Whether the price is on-sale (PROMOTIONAL) or the normal price (REGULAR).
    Enum: "PROMOTIONAL", "REGULAR"

  - `_embedded.payment_links.items.price_details.regular_amount` (integer)
    The standard price of the item without any adjustments applied (e.g. discounts, taxes, sales). This field is required for the transaction to qualify for Level 3 processing.

  - `_embedded.payment_links.items.price_details.item_discount_amount` (integer)
    The item discount. If Level 2/3 processing is enabled, this optional field must have a value of at least 0.

  - `_embedded.payment_links.items.quantity` (integer)
    The item quantity. This field is required for the transaction to qualify for Level 3 processing.

  - `_embedded.payment_links.link_expires_at` (string)
    Timestamp of when the Payment Link will expire.

  - `_embedded.payment_links.link_url` (string)
    The URL of the Payment Link you can share with the buyer.

  - `_embedded.payment_links.merchant_id` (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 or DUMMY_V1.

  - `_embedded.payment_links.nickname` (string)
    Descriptor name of the payment link.

  - `_embedded.payment_links.payment_frequency` (string)
    Whether the Payment Link is one-time only or recurring. Currently, only ONE_TIME is supported.
    Enum: "ONE_TIME", "RECURRING"

  - `_embedded.payment_links.split_transfers` (array,null)
    An array used to detail how funds from the Transfer will split and the amount Merchants receive.

Rules:
- The combined amounts under split_transfers must be equal to the amount submitted in the parent Transfer.
- Merchants can be based in the United States or Canada.
- The amount type must be FIXED.

For more information, see:
- [Split Transactions](../../../../guides/online-payments/payment-features/split-transactions).

  - `_embedded.payment_links.split_transfers.merchant` (string)
    - The ID of the Merchant that will receive the specified amount under the split_transfers object.
- In Split Transactions, the merchants specified in the split_transfers object are the ancillary merchants.

  - `_embedded.payment_links.split_transfers.amount` (integer)
    - The amount of funds that get split and paid out to the specified Merchant.
- Must be less than or equal to the amount of the Transfer.

  - `_embedded.payment_links.split_transfers.fee` (integer)
    - A processing fee is deducted when the Merchant receives their payout, specified in cents.
- Must be less than or equal to the total amount being split for the designated Merchant. 
- By default, this fee is set to 0.

  - `_embedded.payment_links.split_transfers.tags` (object,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)

  - `_embedded.payment_links.state` (string)
    The state of the Payment Link.

  - `_embedded.payment_links.tags` (object,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)

  - `_embedded.payment_links._links` (object)

  - `_embedded.payment_links._links.self` (object)
    Link to the resource that was used in the request.

  - `_embedded.payment_links._links.self.href` (string)

  - `_links` (object)

  - `_links.self` (object)
    Link to the resource that was used in the request.

  - `_links.self.href` (string)

  - `_links.next` (object)
    Link to the next page of entries.

  - `_links.next.href` (string)

  - `page` (object)
    Details the page that's returned.

  - `page.limit` (integer)
    The number of entries to return.

  - `page.next_cursor` (string,null)
    The cursor to use for the next page of results.

## Response 401 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 403 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 404 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 406 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 422 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.