Boleto (Brazil)

Boleto Bancario is a voucher/cash-based payment method used exclusively in Brazil.

Create a Boleto

POST https://api.stage.localpayment.com /api/payin

Headers

Name	Type	Description
Authorization*	string	Mandatory. JWT token in format Bearer eyJ0... . For more information about authentication, please refer to Authentication

Request Body

Name	Type	Description
paymentMethod*	OBJECT	Manatory. Payment method details
paymentMethod.type*	string	Mandatory. Cash
paymentMethod.code*	string	Mandatory. method code 1302
externalId*	string	Mandatory. An ID that is meaningful to you and your system. It must be unique and alphanumeric, no characters allowed.
country	string	Mandatory. Your end user's country (i.e. country in which the payment will be processed), in ISO format. BRA
amount	number	Mandatory. Amount to charge to your end user. Must be sent with 2 decimal places, separated by a dot.
currency	string	Mandatory. BRL
accountNumber*	string	Mandatory. Your Localpayment account number in which the amount will be credited.
conceptCode	string	Mandatory. Choose the suitable concept code from our Concept Code List. Based on our experience, the most usual are 0039 (remittances) and 0040 (corporate payments).
comment	string	Optional. A comment related to the transaction. It should be something meaningful to your business.
merchant*	OBJECT	Mandatory. Party Object. Information related to the merchant.
merchant.type*	string	Mandatory. Possible values: COMPANY, INDIVIDUAL
merchant.name*	string	Mandatory. merchant name
merchant.lastname*	string	Optional for INDIVIDUAL merchat.type / Ignored for COMPANY.
document	OBJECT	Optional. Party Object. Valid identity document.
document.type	string	Optional. Document type: CNPJ for COMPANY,CPF for INDIVIDUAL
document.id	string	Optional. Identity document id. Usually numbers or combination of numbers and letters.
birthdate	string	Optional. Individual birthdate / company incorporation date. ISO 8601 format (YYYY-MM-DD)
nationality	string	Optional
address	OBJECT	Optional
address.street	string	Optional
address.number	string	Optional
address.city	string	Optional
address.state	string	Optional
address.country	string	Optional
address.zipCode	string	Optional
address.comment	string	Optional
payer	OBJECT	Mandatory. Party Object. Information related to the payer.
type	string	Mandatory. Possible values: COMPANY, INDIVIDUAL
name	string	Mandatory. COMPANY, INDIVIDUAL name
lastname	string	Mandatory only for INDIVIDUAL type / Ignored for COMPANY,
document	OBJECT	Mandatory. Party Object. Valid identity document.
type	string	Mandatory. Document type: CNPJ for COMPANY,CPF for INDIVIDUAL
id	string	Mandatory. Identity document id. Usually numbers or combination of numbers and letters.
email	string	Mandatory
phone	OBJECT	Optional.Party Object.
countryCode	string	Optional
areaCode	string	Optional
number	string	Optional
birthdate	string	Optional. Individual birthdate / company incorporation date. ISO 8601 format (YYYY-MM-DD)
nationality	string	Optional
address	OBJECT	Mandatory.Party Object. Contact address
street	string	Mandatory
number	string	Mandatory
city	string	Optional
state	string	Optional
country	string	Mandatory
zipCode	string	Optional. Zip code / Postal code
comment	string	Optional
userReference	string	Optional. Username or Id in your platform.
intermediaries	string	Optional. Array of Party objects. It represents others parties in the payment chain because of the end user is not your direct customer. Take into account the array sequence: your client should be the first element, the client of your client should be the second and so on, until there are no more intermediaries.
commercialData	OBJECT	Optional. Party Object. Extra information related to the goods or services traded.
invoice		Optional. Invoice reference
items	array	Optional. List of sold items
items.id	string	Optional. Item Id
items.tittle	string	Optional. Item title
items.description	string	Optional. Item description
items.pictureUrl	string	Optional. URL pointing to an item picture
items.categoryId	string	Optional. Item category Id
items.quantity	number	Optional. Item quantity
items.unitPrice	number	Optional. Unit price
shipments	array	Optional. List of shipping addresses
shipments.street	string	Optional. Shipping street
shipments.number	string	Optional. Shipping Number street
shipments.city	string	Optional. Shipping City
shipments.state	string	Optional. Shipping State/Province
shipments.country	string	Optional. Shipping country
shipments.zipCode	string	Optional.
shipments.comment	string	Optional.
device	OBJECT	Optional. Party Object.
device.deviceId	string	Optional. Android / iPhone device ID. Can be blank for other device types such as PC / Mac.
device.ip	string	Optional. Device IP address
device.browser	string	Optional. Browser
metaData	OBJECT	Optional. Party Object. Unstructured object to record any metadata meaningful to you.

Examples: Boleto payin request

Below are examples for creating a payment Boleto through our API.

A Boleto expires by default within 7 days of the creation date, however, through the LP API, any cash payment order that is in "IN PROGRESS" status can be cancelled. If you require another expiration date, it can be configured between 1 and 7 days.

JSON: Mandatory OBJECTS

{
    "paymentMethod": {
        "type": "Cash",
        "code": "1302",
        "flow": "DIRECT"
    },
    "externalId": "{{externalId}}",
    "country": "BRA",
    "amount": 10,
    "currency": "BRL",
    "accountNumber": "{{YourAccountNumber}}",
    "conceptCode": "0036",
    "comment": "BOLETO Test",
    "merchant": {
        "type": "COMPANY",
        "name": "Your Merchant"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "Your name",
        "lastname": "Your lastname",
        "document": {
            "id": "111.111.111-63",
            "type": "CPF"
        },
        "email": "[e-mail]",
        "address": {
            "street": "your street",
            "number": "2850",
            "country": "BRA",
        },
    },
}'

JSON: Complete body request

{
    "paymentMethod": {
        "type": "Cash",
        "code": "1302",
        "flow": "DIRECT"
    },
    "externalId": "{{externalId}}",
    "country": "BRA",
    "amount": 10,
    "currency": "BRL",
    "accountNumber": "{{YourAccountNumber}}",
    "conceptCode": "0036",
    "comment": "BOLETO Test",
    "merchant": {
        "type": "COMPANY",
        "name": "Your Merchant"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "your name",
        "lastname": "your lastmane",
        "document": {
            "id": "111.111.111-63",
            "type": "CPF"
        },
        "email": "[e-mail]",
        "address": {
            "street": "Your street",
            "number": "2850",
            "country": "BRA",
        },
    },
    "userReference": "abcdef1"
    },
    "intermediaries": [],
    "commercialData": {
        "invoice": "",
        "items": [
            {
                "id": "",
                "title": "",
                "description": "",
                "pictureUrl": "",
                "categoryId": "",
                "quantity": "0",
                "unitPrice": "0.0"
            }
        ],
        "shipments": [
            {
                "street": "",
                "number": "",
                "city": "",
                "state": "",
                "contry": "",
                "zipCode": "",
                "comment": ""
            }
        ]
    },
    "device": {
        "deviceId": "",
        "ip": "",
        "browser": ""
    },
    "metaData": {}
}
	

Examples: Cash payin response

Status OK

{
    "transactionType": "PayIn",
    "externalId": "{{externalId}}",
    "internalId": "{{internalId}}",
    "paymentMethod": {
        "type": "Cash",
        "code": "1302",
        "flow": "DIRECT"
    },
    "country": "BRA",
    "currency": "BRL",
    "amount": 10.0,
    "accountNumber": "{{YourAccountNumber}}"",
    "confirmed": {
        "currency": "BRL",
        "amount": 10.0,
        "fxQuote": 1.0
    },
    "payment": {
        "currency": "BRL",
        "fxQuote": 1.0,
        "financingFee": 0.0,
        "amount": 10.0
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "BRL",
        "fxSource": 5.648969,
        "fxQuote": 1.0,
        "amount": 0.0,
        "account": "{{YourAccountNumber}}"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "The payin is pending the confirmation"
    },
    "ticket": {
        "image": "https://api.stage.localpayment.com/api/images/1610/34191.75124 59106.973130 03315.920003 3 98350000001000",
        "barcode": "34191.75124 59106.973130 03315.920003 3 98350000001000"
    },
    "merchant": {
        "type": "COMPANY",
        "name": "Your Merchant"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "Your name",
        "lastname": "Your lastname",
        "document": {
            "type": "CPF",
            "id": "111.111.111-63"
        },
        "email": "[e-mail]",
        "address": {
            "street": "street",
            "number": "2850",
            "country": "BRA"
        }
    },
    "intermediaries": [],
    "date": {
        "creationDate": "2024-09-02T14:23:51.7+00:00",
        "processedDate": "2024-09-02T14:23:53.9142924",
        "expirationDate": "2024-09-09T14:23:52.1290741"
    },
    "errors": []
}

Bad Request

{
    "externalId": "1234567891200000000",
    "internalId": "21f7fa2a-c675-4a83-8e83-2598bb1f6ce6",
    "status": {
        "code": "300",
        "description": "REJECTED"
    },
    "errors": [
        {
            "code": "300",
            "detail": "Invalid param + [paymentMethod.code] + doesn´t exists for PAYMENT_METHOD_TYPE Cash"
        }
    ]
}

How to create a Boleto?

To generate a Bank Ticket, the Payin response data that you must select and add to the ticket are: the “image”, the “barcode” and the “expiration date”.

Example: Elements to create a Boleto

Elements necessary to create a Boleto in Brazil

"ticket": {
        "image": "https://api.stage.localpayment.com/api/images/1610/34191.75124 59106.973130 03315.920003 3 98350000001000",
        "barcode": "34191.75124 59106.973130 03315.920003 3 98350000001000"
    },

How to pay a cash payment ticket?

Payment for a Ticket can be made by reading the "ticket.image" or by entering the "ticket.barcode".

The payment can be made by reading the barcode image or informing the Ticket ID

34191.75124 59106.973130 03315.920003 3 98350000001000

Check the Payin Status Codes

Payin