Body
Create Boleto
Boleto is a popular Brazilian payment method where customers receive a bank slip that can be paid online or in person. With Juspay, merchants can generate and manage Boletos seamlessly. Payments typically take 1–3 business days to settle, and Juspay provides automated notifications upon settlement to ensure smooth payment tracking.
This API allows merchants to create a new Boleto issued through partner banks.
Through this API, merchants can define all boleto attributes, including payer information, due date, amount, and penalty configurations such as fines (multa) or interest (juros) for late payments.
Request
Response
API Endpoints
Sandbox Link
POST
https://api.sandbox.juspay.io/txns
Production Link
POST
https://api.juspay.io/txns
Authorization Header
Basic Auth
*
Base64 Encoded Username:Password
Required
Consists of two parts.
Username: API Key obtained from Juspay dashboard
Password: Empty string
Example:- Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg==
Headers
Content-Type
String
application/x-www-form-urlencoded
Request Schema: application/json
Basic Parameters
order.order_id
*
String
Required
Unique Identifier for the order. Should be Alphanumeric with character length less than 21.
Example:-
order_id: order2511202511
order.amount
*
Double
Required
Amount that the customer has to pay. Will accept stringified double or integer values with upto two decimal places. For example, "100.15" and "100" are valid input but "100.1532" is not valid.
order.customer_id
String
It is the ID with which merchant refers to a customer object. This id is used to access the stored payment methods, allow EMI transactions and setup subscriptions.
In case of guest login it should be an empty string.
Example:-
customer_id: cth_nWnncgUWCqKEkadA
order.customer_email
String
Email address of the customer. If the backend gateway requires it, then you must send this value.
Example:-
test@gmail.com
order.customer_phone
String
Mobile number or fixed line number of the customer. If the backend gateway requires it, then you must send this value.
Example:-
9999999912
order.currency
String
ISO string of the currency. Accepted values are BRL, EUR, USD, GBP, HKD. Default value: BRL
order.return_url
String
A fully qualified URL which the customer will be redirected after payment completion. It is also required to provide the control back to SDK after the completion of transaction. This URL shouldn't contain any query parameters or Ip address. This URL takes higher precedence over the common return URL configured in your account settings.
Example:-
https://shop.merchant.com
merchant_id
*
String
Required
ID of the merchant_account that you hold with us.
payment_method_type
*
String
Required
Depending on type of payment to be processed. For Boleto, it will be OTC.
payment_method
*
Required
This should be passed as BOLETO.
Other possible values: CARDS, PIX.
redirect_after_payment
Boolean
Optional
This is a boolean variable and accepts true/false. We recommend that you set this to true and use the redirection flow. If set to true, then the user is redirected to the return_url configured for the order. If set to false, then the user will be stopped at the response page from the gateway. Your client should be able to read the page/title to infer that the user has completed the transaction.
identity_credentials
*
Object
Mandatory
This field should be used to pass cpf or cnpj values in the json format.
cpf
*
String
Mandatory
Brazilian identity number without punctuation
sdk_params
*
Bool
Mandatory
This will be set to true if you are not using the SDK flow.
gateway_id
*
String
Mandatory
Gateway ID provided by Juspay.
order.metadata.boletoInfo
*
String
Mandatory
drawer_guarantor
Object
person
Object
person_name
String
Name of the Guarantor
Example:- Antônio Coutinho
person_type
Object
person_type_code
String
Type of person:
• F – Individual (Pessoa Física)
• J – Legal entity (Pessoa Jurídica)
Example:- J
tax_id
String
Individual or company taxpayer identification number (CPF/CNPJ).
Example:- 12345678901
document_type_code
*
Number
Required
Code that identifies the type of document represented by the boleto, according to FEBRABAN standards.
Common value: 01 – Duplicata Mercantil (Commercial Invoice).
Other possible codes may include:
• 02 – Nota Promissória
• 12 – Recibo
• 17 – Cédula de Crédito Bancário.
Example:- 01
acceptance_code
*
String
Required
Indicates whether the payer formally accepted the document.
Possible values:
• A – Accepted (Aceite): the payer acknowledges and accepts the terms of the document before payment.
• N – Not accepted (Não Aceite): the payer has not provided prior acceptance; the document is considered payable without formal acknowledgment.
In most boleto integrations, use N unless your operation requires formal acceptance from the payer.
Example:- N
order.metadata.add_on_amount_rules
*
Array
Mandatory
Defines additional fee rules that apply to an order, such as late fees, fines, or interest.
This structure allows the merchant to specify conditional charges that may be applied after the payment due date, depending on the payment method or rule type.
payment_method_type
String
High-level payment method type to which the rule applies (e.g., "OTC", "CARD", "WALLET").
Example:- OTC
fee_description
String
Explanation of the fee rule (e.g., "Late fees" or "Penalty charges").
Example:- Late fees
fee
String
Total fee amount applicable at PMT level. Usually "0.00" if fees are broken down in nested structures.
Example:- 0.00
sub_details
Array
payment_method
String
The specific payment method for which the fee applies (e.g., "BOLETO", "PIX").
Example:- BOLETO
fee
String
Aggregated fee amount at PM level, usually "0.00" if detailed breakdowns are defined in fee_details.
Example:- 0.00
fee_details
Array
List of fee components such as fines or interest that may apply under specific conditions.
value
String
The value of the fee to be applied (e.g., "1.00"). it could be value or percentage.
Example:- 1.00
metric_type
String
Possible values: VALUE | PERCENTAGE
Example:- PERCENTAGE
effective_from
String
Due date - Date from which this fee becomes applicable.
Example:- 2025-12-01
fee_type
String
Possible values: FINE, INTEREST, etc.
Example:- FINE
frequency
*
String
Mandatory
Possible values: DAILY | MONTHLY | ANNUAL | ONE_TIME
order.billing_address_line1
String
Optional
Example:- Girija Building
order.billing_address_line2
String
Optional
Example:- Temple Road
order.billing_address_line3
String
Optional
Example:- 8th Block
order.billing_address_city
String
Optional
Example:- city
order.billing_address_state
String
Optional
Example:- SP
order.billing_address_postal_code
String
Optional
Example:- 560095
order.billing_address_country_code_iso
String
Optional
Example:- BR
order.customer_first_name
String
Optional
order.customer_last_name
String
Optional
format
String
Optional
Example:- JSON
200 : Success
Response Body
payment
*
Object
Required
sdk_params
*
Object
Required
tag
*
String
Required
Example:- ACQUIRER_PARAMS
contents
*
array
Required
acquirer_info
*
Array
Required
barCodeData
String
Example:- 34195128200000000101096406291863100536964000
acquirer_name
String
Example:- BOLETO
payment_code
String
Example:- 34191096440629186310505369640007512820000000010
boleto_template_info
Object
document_reference_number
String
Example:- 64062918
bank_name
String
Example:- Banco Itaú S.A.
bank_code
String
Example:- 341-7
due_date
String
Example:- 2025-12-01
expiry_date
String
Example:- 2025-12-20
issue_date
String
Example:- 2025-11-25
wallet_code
String
Example:- 109
document_amount
String
Example:- 00000000000000010
document_number
String
Example:- 64062918
payment_instrument
String
Example:- OTC
authentication
*
Object
Required
method
*
String
Required
Example:- GET
url
*
String
Required
Example:- https://api.sandbox.juspay.io/v2/pay/start/creditas/mozsBx48RGofH78v6Za?cardIssuerBankName%3DBOLETO%26cardType%3DOTC%26paymentMethod%3DBOLETO%26paymentMethodType%3DOTC
status
*
String
Required
Example:- PENDING_VBV
txn_uuid
String
Example:- mozsBx48RGofH78v6Za
offer_details
Object
offers
Array
order_id
*
String
Required
Example:- order2511202512
txn_id
*
String
Required
Example:- creditas-order2511202512-1
400 : Invalid Input data
Response Body
status
String
error
error_message
*
String
Mandatory
error_code
*
String
Mandatory
Have questions?
- Need help? Contact support
- LLM? Read llms.txt