Skip to content

Create A Payment Link

HTTP Request

Note

If you want to use the paymentIntentInfo parameter, please contact the account manager to configure it.
The parameter installmentPlanId will be deprecated. Please use paymentIntentInfo.installmentPlanId to pass it.

POST /v2/cashier/payment-link/

Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Body
{
    "orderId": "my-order-id-001",
    "amount": 9999,
    "currency": "BRL",
    "country": "BR",
    "allowPaymentMethods": [
        "CREDIT_CARD",
        "PIX",
        "BANK_TRANSFER_BR",
        "BOLETO"
    ],
    "name": "buyer name",
    "email": "liquido-test@gmail.com",
    "phone": "+5511999999999",
    "documentId": "51234567890",
    "billingAddress": {
        "zipCode": "04849333",
        "state": "SP",
        "city": "sao paulo",
        "district": "Jardim Gaivotas",
        "street": "Rua 9 de setembro",
        "number": "15",
        "complement": "casa",
        "country": "BR"
    },
    "shippingAddress": {
      "name": "name",
      "countryCode": "BR",
      "province": "province/state",
      "city": "city",
      "postalCode": "04849334",
      "line1": "Address Info",
      "line2": "Address Info"
    },
    "paymentOptions": {
        "boleto": {
            "fine": {
                "value": 0.02,
                "type": "RATE",
                "startDate": 1764039600
            },
            "dueDate": 1763953200
        }
    },
    "callbackUrl": "https://your-domain/callback/",
    "redirectUrl": "https://your-domain/checkout-page",
    "installmentPlanId": "Outdated",
    "description": "this is a test payment",
    "needCollectAddress": true,
    "paymentIntentInfo": {
        "installmentPlanId": "a22f9260-c78e-48f3-1234-9f1d59505295",
        "taxPlanId":"277a8f61-0d28-49ae-1234-cbd229130c0e",
        "targetCurrency":"BRL"
    },
    "paymentDocumentUrl": "https://liquido-payment-link.s3.ap-southeast-1.amazonaws.com/payment-link/liquido/20240604-002.png",
    "metadata": {
        "key1": "value1",
        "key2": "value2",
        ...
    },
    "subMerchantId": "UUID",
    "expiresAt": 1764941153
}
Content-Type: application/json
{
    "paymentLink": "https://buy.liquido.com/{{linkId}}",
    "linkId": "{{linkId}}"
}

{
    "code": 400,
    "message": "Minimum amount of Boleto is 5BRL.",
    "data": {
        "errorMessage": "Minimum amount of Boleto is 5BRL."
    }
}

Supported Payment Methods

Payment Method Country Limit Important Note
CREDIT_CARD BR, MX, CO
PIX BR
BOLETO BR >= 5BRL
BANK_TRANSFER_BR BR
BANK_TRANSFER_MX MX
OXXO MX
PAY_CASH MX, PE <= 20,000 MXN or <= 3,500 PEN
PSE CO >= 1000 COP name, phone and email are required.
EFECTY CO >= 1,000 COP or <= 5,000,000 COP name, phone and email are required.
NEQUI CO >= 2000 COP name, phone and email are required.
WEB_PAY CL >= 1 CLP email and description are required.
KHIPU CL >= 1 CLP email and description are required.
MACH CL >= 1 CLP email and description are required.
HITES CL >= 1 CLP email and description are required.
FINTOC CL >= 1 CLP email and description are required.
SERVIFACIL CL >= 1 CLP email and description are required.
BANK_TRANSFER_PE PE >= 10 PEN name, phone and email are required.
WALLET PE >= 10 PEN name, phone and email are required.

Request Headers Parameters

Key Value
Authorization "Bearer" + " " + {{access_token}}
x-api-key {{api_key}}

Request Body Parameters

Parameter Required Type Description
orderId String Unique order id in merchant system.
amount Long The transfer amount, The minimum settlement granularity of the current currency, such as 100=1BRL. Amount must be a multiple of 100 when currency is COP.
country String Country code
currency String The currency code of the transferred fund
allowPaymentMethods List Declare which payment methods are included in the payment link, not null. The order of payment methods display should be consistent with the order from allowPayMethods. Supported Payment Methods see here
name String User full name(less than or equal to 50 characters). If you previously collected customer's name ahead of the payment process, you can pass a customer’s name into payment link. This information will autofill the payment form.
email String Less than or equal to 64 characters. If you previously collected customer's email ahead of the payment process, you can pass a customer’s email into payment link. This information will be used for risk control
phone String Mobile phone number, must start with country calling codes, such as "+55". If you previously collected customer's phone ahead of the payment process, you can pass it into payment link. This information will be used for risk control
documentId String Resident ID number, such as CPF/CNPJ in Brazil. Does not contain separator characters.
billingAddress Address Object Billing address info. If you previously collected customer's billing address ahead of the payment process, you can pass it into payment link. This information will autofill the Boleto payment form
shippingAddress JSON Shipping address info. If you previously collected customer’s shipping address ahead of the payment process and you set ‘needCollectAddress’ to ‘true’, you can pass the shipping address into payment link. This information will autofill the payment form.
paymentOptions JSON Additional attributes for some payment methods – currently, only the fine for Boleto is supported.
callbackUrl String When the payment link status changed. liquido will send a post http request to the callback url. details see here
redirectUrl String When the payment completed. payment link will redirect to redirectUrl if it is not null.
installmentPlanId String Only required for create a credit card payment with installments.(deprecated)
description String Description of payment
needCollectAddress Boolean True or false. If you need the payment link to help to collect customer’s shipping address, you can set ‘true’ so customer can fulfill the shipping address in the payment link.
paymentIntentInfo PaymentIntentInfo Object Intent to pay. If there are requirements for installment, exchange, tax, etc., you can pass in the corresponding parameters. (This function requires contacting account manager for configuration before it can be used)
paymentDocumentUrl String The document URL for the payment. Filling this field if you have an uploaded document link, and it will be displayed in the payment link page. (This function requires contacting account manager for configuration before it can be used. If you need to upload your document to the Liquido server, please contact account manager too.)
metadata JSON The merchant reserved field accepts key-value pairs where both keys and values are strings only.
subMerchantId String The sub merchant ID. Required for PSPs.
expiresAt Long Payment link expiration time, second-level timestamp. default 7 days. If the payment link is not settled and accessed after expiration, it will redirect to an error page.

BillingAddress Object Parameters

Parameter Required Type Description
zipCode String zip code. such as CEP in Brazil
state String state. should be abbreviation, such as SP in Brazil
city String city name.
district String district name.
street String street name.
number String street number.
complement String complement info.
country String country code.

ShippingAddress Object Parameters

Parameter Required Type Description
name String Shipping name, required when object is provided.
countryCode String Country code, required when object is provided.
province String Province, required when object is provided.
city String City, required when object is provided.
postalCode String Postal code, required when object is provided.
line1 String Address details, required when object is provided.
line2 String Address details, required when object is provided.

paymentOptions Object Parameters

Parameter Required Type Description
boleto JSON Options related to BOLETO payments.

boleto Object Parameters

Parameter Required Type Description
fine JSON Configuration related to penalty interest for overdue BOLETO payments. Please contact your account manager before using this function
dueDate Long The final date for completing payment to avoid late fees. Unix timestamp in seconds, will be processed to the precision of a day in BR timezone, should be greater than the current date in BR timezone and less than or equal to the payment deadline. e.g., 1763953200 corresponds to 2025-11-24(BR timezone)
This is required when the fine (for Boleto) is applied.

fine Object Parameters

Parameter Required Type Description
type String The fine calculation type, currently supported enumeration value "RATE", indicates that the fine is calculated as a percentage of the transaction amount.
startDate Long BOLETO penalty interest effective date. Unix timestamp in seconds, will be processed to the precision of a day in BR timezone, should be greater than the due date. e.g., 1764039600 corresponds to 2025-11-25(BR timezone)
value Double The rate of the fine, a decimal value, e.g., 0.02 = 2%

PaymentIntentInfo Object Parameters

Parameter Required Type Description
installmentPlanId String Installment Plan ID
taxPlanId String Tax Plan ID
targetCurrency String Local currency is required to use the currency exchange function.

Response Body Parameters

Parameter Type Description
paymentLink String the payment link which hosted in liquido.
linkId String unique id of the payment link in liquido.
Back to top