Skip to content

Boleto

Boleto Payment

Create A Boleto Payment.

HTTP Request

POST /v1/payments/charges/boleto

Request Headers

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Key Value
Authorization "bearer" + " " + {{access_token}}
x-api-key {{api_key}}

Request Body

Request Body
{
    "idempotencyKey": "0bd88f8a-2c7e-4b95-903f-8da45d0e6129",
    "amount": 10000,
    "currency": "BRL",
    "country": "BR",
    "paymentMethod": "BOLETO",
    "paymentFlow": "DIRECT",
    "payer": {
        "name": "Cliente - Isabela",
        "document": {
            "documentId": "51364124025",
            "type": "CPF"
        },
        "email": "testeemail@gmail.com",
        "phone": "+555058149876",
        "billingAddress": {  
            "zipCode": "04849333",
            "state": "SP",
            "city": "sao paulo",
            "district": "Jardim Gaivotas",
            "street": "Rua 9 de setembro",
            "number": "15",
            "complement": "casa",
            "country": "BR"
        }
    },
    "orderInfo": {  
        "orderId": "test-order-id",  
        "shippingInfo": { 
            "name": "shipping test name",  
            "phone": "+555058149876",  
            "email": "thiago@example.com",
            "address": { 
                "street": "street name",
                "number": "building number",
                "complement": "unit, apt, etc.",
                "district": "district, neighborhood, etc.",
                "city": "city name",
                "state": "state, state code",
                "zipCode": "zip code, postal code",
                "country": "BR"
            }
        }
    },
    "paymentTerm": {
        "paymentDeadline": 1671194415,
        "fine": {
            "modifierType": "FIXED_AMOUNT",
            "value": 100,
            "startTime": 1671108015
        },
        "interest": {
            "interestType": "RATE_PER_DAY",
            "value": 0.001,
            "interestLevyStartTime": 1670935215,
            "interestApplicationStartTime": 1671108015
        }
    },
    "description": "this is a test pay",
    "callbackUrl": "https://api.client.com/callback/"
}
Parameter Required Type Description
idempotencyKey String Unique key to ensure idempotent requests. given by the merchant in their system.
amount Long The transfer amount.The minimum settlement granularity of the current currency, such as 100=1BRL
country String country code
currency String The currency code of the transferred fund
paymentMethod String payment method, enum value as BOLETO
paymentFlow String payment flow, enum value as DIRECT or REDIRECT
payer JSON payer info
orderInfo JSON order info
riskData JSON risk control info, if PSP, please add sub-merchant here, example as "customProperties":{"merchantId":"1527558812935028000","merchantName":"LIQUIDO PTE. LTD."}
payerAddress JSON Billing address info. deprecated. The billingAddress field of payer object should be used instead
paymentTerm JSON payment term info, such as payment expired date
description String description of payment
callbackUrl String URL where Liquido will send notifications associated to changes to this payment. will receive a post request.

Response Body

Content-Type: application/json
{
    "transferStatusCode": 200,
    "transferErrorMsg": "",
    "idempotencyKey": "0bd88f8a-2c7e-4b95-903f-8da45d0e6129",
    "referenceId": "0bd88f8a-2c7e-4b95-903f-8da45d0e6129",
    "paymentMethod": "BOLETO",
    "amount": 10000,
    "currency": "BRL",
    "finalAmount": 10000,
    "finalCurrency": "BRL",
    "country": "BR",
    "createTime": "2022-12-08 08:02:14 UTC",
    "scheduledTime": "2022-12-08 08:02:15 UTC",
    "payer": {
        "name": "Cliente - Isabela",
        "document": {
            "documentId": "51364124025",
            "type": "CPF"
        },
        "email": "testeemail@gmail.com",
        "phone": "+555058149876",
        "billingAddress": {
            "street": "Rua 9 de setembro",
            "number": "15",
            "complement": "casa",
            "district": "Jardim Gaivotas",
            "city": "sao paulo",
            "state": "SP",
            "zipCode": "04849333",
            "country": "BR"
        }
    },
    "transferStatus": "IN_PROGRESS",
    "description": "this is a test",
    "callbackUrl": "https://api.liquido.com/v1/cashier/callback/",
    "transferDetails": {
        "boleto": {
            "barcode": "33299919800000100000001110725354807300286435",
            "digitalLine": "33290001151072535480673002864350991980000010000",
            "paymentTerm": {
                "paymentDeadline": 1671194415,
                "fine": {
                    "modifierType": "FIXED_AMOUNT",
                    "value": 100,
                    "startTime": 1671073200
                },
                "interest": {
                    "value": 0.001,
                    "interestLevyStartTime": 1670900400,
                    "interestApplicationStartTime": 1671073200,
                    "interestType": "RATE_PER_DAY"
                }
            }
        }
    }
}
Parameter Type Description
transferStatus String Transfer status, SETTLED, IN_PROGRESS, FAILED
transferStatusCode int Transfer status code, 200 transaction SETTLED or IN_PROGRESS, other FAILED
transferErrorMsg String Transfer error message if failed
referenceId String Unique key to payment ticket, generated by Liquido.
idempotencyKey String Unique key to ensure idempotent requests. given by the merchant in their system
amount Long The transfer amount
country String country code
currency String The currency code of the transferred fund
finalAmount String The final amount that is used for creating the charge order. EX: for charge orders with FX conversion, this field represents the converted amount from the original requested amount.
finalCurrency String The currency code of the finalAmount.
paymentMethod String payment method, enum value as BOLETO
paymentFlow String payment flow, enum value as DIRECT or REDIRECT
payer JSON payer info
transferDetails JSON transaction details info
description String description of payment
callbackUrl String URL where Liquido will send notifications associated to changes to this payment. will receive a post request.
createdDate String Payment ticket created time
scheduledTime String Payment ticket scheduled time
finalStatusTime String Transfer final status update time, final status include SETTLED, FAILED

Notification / Callback

Content-Type: application/json
{
    "eventType": "CHARGE_SUCCEEDED",
    "data":  {
        "chargeDetails": {
            "transferStatusCode": 200,
            "transferErrorMsg": "",
            "idempotencyKey": "0bd88f8a-2c7e-4b95-903f-8da45d0e6129",
            "referenceId": "0bd88f8a-2c7e-4b95-903f-8da45d0e6129",
            "paymentMethod": "BOLETO",
            "amount": 10000,
            "currency": "BRL",
            "finalAmount": 10000,
            "finalCurrency": "BRL",
            "country": "BR",
            "createTime": "2022-12-08 08:02:14 UTC",
            "scheduledTime": "2022-12-08 08:02:15 UTC",
            "finalStatusTime": "2022-12-08 08:47:02 UTC",
            "payer": {
                "name": "Cliente - Isabela",
                "document": {
                    "documentId": "51364124025",
                    "type": "CPF"
                },
                "email": "testeemail@gmail.com",
                "phone": "+555058149876",
                "billingAddress": {
                    "street": "Rua 9 de setembro",
                    "number": "15",
                    "complement": "casa",
                    "district": "Jardim Gaivotas",
                    "city": "sao paulo",
                    "state": "SP",
                    "zipCode": "04849333",
                    "country": "BR"
                }
            },
            "transferStatus": "SETTLED",
            "description": "this is a test",
            "callbackUrl": "https://api.liquido.com/v1/cashier/callback/",
            "transferDetails": {
                "boleto": {
                    "barcode": "33299919800000100000001110725354807300286435",
                    "digitalLine": "33290001151072535480673002864350991980000010000",
                    "paymentTerm": {
                        "paymentDeadline": 1671194415,
                        "fine": {
                            "modifierType": "FIXED_AMOUNT",
                            "value": 100,
                            "startTime": 1671073200
                        },
                        "interest": {
                            "value": 0.001,
                            "interestLevyStartTime": 1670900400,
                            "interestApplicationStartTime": 1671073200,
                            "interestType": "RATE_PER_DAY"
                        }
                    }
                }
            }
        }
    }
}

Object Parameters

Payer

Parameter Required Type Description
name String fullname(Input specification: Only a combination of uppercase and lowercase letters, numbers and spaces is allowed. Spanish and Portuguese letters, and other special characters are not allowed).
email String email.
phone String Mobile Phone number.
document JSON CPF or CNPJ is required in Brazil.
billingAddress JSON Billing address info.

Document

Parameter Required Type Description
documentId String identity number
type String enum of CPF or CNPJ

OrderInfo

Parameter Required Type Description
orderId String order identity number
shippingInfo JSON shipping info

ShippingInfo

Parameter Required Type Description
name String shipping name
phone String phone number
email String email address
address JSON the same as billingAddress

RiskData

Parameter Required Type Description
ipAddress String Cardholder's full name.

Address

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.

PaymentTerm

Parameter Required Type Description
paymentDeadline Long timestamp of seconds, payment dead line should within 5years
fine JSON The payment fine info.
interest JSON The payment interest info.

Fine

Parameter Required Type Description
modifierType String The type of fine. RATE or FIXED_AMOUNT
value Double/Long The value of fine according to modifierType. Double if type is RATE, long (amount in cents) if type is FIXED_AMOUNT.
Fine amount calculation:
1. If modifierType is RATE, amount * value is the amount of the fine.
2. If modifierType is FIXED_AMOUNT, value is the amount of the fine.
3. If the user pays the ticket after startTime, fine will be applied.
startTime Long timestamp of seconds, is the time that fine starts to apply.
NOTE:
1. startTime needs to be less than paymentDeadline.
2. If interest is enabled, must be startTime=interestApplicationStartTime.
3. startTime should be at lease 1 day after timestamp of now. now + 86400 <= startTime.
4. startTime might be delayed if it's weekends or Brazil national holidays.
5. It will be automatically converted to start of the day Brazil time. Example: 2022-11-24T20:09:32-03:00 (1669331372) will be converted to 2022-11-24T00:00:00-03:00 (1669258800)

Interest

Parameter Required Type Description
interestType String The type of interest. RATE_PER_DAY or FIXED_AMOUNT_PER_DAY
value Double/Long The value of interest according to interestType. Double if type is RATE_PER_DAY, long (amount in cents) if type is FIXED_AMOUNT_PER_DAY.
Interest amount calculation:
1. If interestType is RATE_PER_DAY, amount * value is the amount of the interest to pay for each day after interestLevyStartTime.
2. If interestType is FIXED_AMOUNT_PER_DAY, value is the amount of the interest to pay for each day after interestLevyStartTime.
3. If the user pays the ticket before interestLevyStartTime, no interest.
4. If the user pays the ticket after interestLevyStartTime but before interestApplicationStartTime, no interest.
5. If the user pays the ticket after interestApplicationStartTime, interest will be applied.
interestLevyStartTime Long timestamp of seconds, is the time that interest starts to accumulate.
NOTE:
1. interestLevyStartTime needs to be less than paymentDeadline.
2. interestLevyStartTime should be at lease 1 day after timestamp of now. now + 86400 <= interestLevyStartTime.
3. interestLevyStartTime might be delayed if it's weekends or Brazil national holidays.
4. It will be automatically converted to start of the day Brazil time. Example: 2022-11-24T20:09:32-03:00 (1669331372) will be converted to 2022-11-24T00:00:00-03:00 (1669258800)
interestApplicationStartTime Long timestamp of seconds, is the time that interest starts to apply.
NOTE:
1. interestApplicationStartTime needs to be less than paymentDeadline.
2. If fine is enabled, must be startTime=interestApplicationStartTime.
3. interestApplicationStartTime should be at lease 1 day after interestLevyStartTime. interestLevyStartTime + 86400 <= interestApplicationStartTime.
4. interestApplicationStartTime might be delayed if it's weekends or Brazil national holidays.
5. It will be automatically converted to start of the day Brazil time. Example: 2022-11-24T20:09:32-03:00 (1669331372) will be converted to 2022-11-24T00:00:00-03:00 (1669258800)

TransferDetails

Parameter Type Description
boleto JSON boleto detail info

Boleto

Parameter Type Description
barcode String barcode
digitalLine String digitalLine
paymentTerm JSON payment term info, such as payment expired date

PaymentTerm(Response)

Parameter Type Description
paymentDeadline Long timestamp of seconds, payment dead line
fine JSON The payment fine info.
interest JSON The payment interest info.

Fine(Response)

Parameter Type Description
modifierType String The type of fine. RATE or FIXED_AMOUNT
value Double/Long The value of fine according to modifierType. Double if type is RATE, long (amount in cents) if type is FIXED_AMOUNT.
startTime Long timestamp of seconds, is the time that fine starts to apply.
It was automatically converted to start of the day Brazil time. Example: 2022-11-24T20:09:32-03:00 (1669331372) will be converted to 2022-11-24T00:00:00-03:00 (1669258800)

Interest(Response)

Parameter Type Description
interestType String The type of interest. RATE_PER_DAY or FIXED_AMOUNT_PER_DAY
value Double/Long The value of interest according to interestType. Double if type is RATE_PER_DAY, long (amount in cents) if type is FIXED_AMOUNT_PER_DAY.
interestLevyStartTime Long timestamp of seconds, is the time that interest starts to accumulate.
It was automatically converted to start of the day Brazil time. Example: 2022-11-24T20:09:32-03:00 (1669331372) will be converted to 2022-11-24T00:00:00-03:00 (1669258800)
interestApplicationStartTime Long timestamp of seconds, is the time that interest starts to apply.
It was automatically converted to start of the day Brazil time. Example: 2022-11-24T20:09:32-03:00 (1669331372) will be converted to 2022-11-24T00:00:00-03:00 (1669258800)

Transfer Status

Parameter Description
IN_PROGRESS The transaction of this method has started, but no transactions have been processed yet.
SETTLED The funds of the transaction of this payment have been transferred to the store.
REFUNDING The transaction of this payment is refunding.
REFUNDED The transaction of this payment method has been refunded.
FAILED There was an error while processing the transaction of this payment. This status is followed by a message with more details about the error.

Notification Event Type

CHARGE_SUCCEEDED,
CHARGE_FAILED,
CHARGE_CHARGED_BACK,
CHARGE_REFUND_SUCCEEDED,
CHARGE_REFUND_FAILED;

Boleto Receipt PDF

A receipt PDF can be downloaded after created a payment.

HTTP Request

GET /v1/payments/files/boleto/pdf/{idempotency_key}

Request Parameters

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

Response Body Parameters

Parameter Required Type Description
path String A PDF file link for receipt

PDF Example

voucher

Back to top