> For the complete documentation index, see [llms.txt](https://docs.pagsmile.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pagsmile.com/reference/payin/submit-a-payin/brazil/boleto.md).

# Boleto

This endpoint allows you to submit a payin by Boleto in Brazil.

<mark style="color:green;">`POST`</mark> `https://gateway-test.pagsmile.com/trade/pay`&#x20;

{% hint style="info" %}
The generated Boleto is valid for 3 days.
{% endhint %}

#### Headers

| Name            | Type   | Required | Description                                               |
| --------------- | ------ | -------- | --------------------------------------------------------- |
| `Content-Type`  | string | Yes      | Fixed value: `application/json; charset=UTF-8`.           |
| `Authorization` | string | Yes      | Basic authentication using `Base64(app_id:security_key)`. |

#### Request Body

<table><thead><tr><th width="155.3515625">Name</th><th width="97.19921875">Type</th><th width="99.94921875">Required</th><th width="246.34765625">Constraints</th><th>Description</th></tr></thead><tbody><tr><td><code>app_id</code></td><td>string</td><td>Yes</td><td>Use the App ID assigned by Pagsmile.</td><td>Merchant application ID.</td></tr><tr><td><code>region</code></td><td>string</td><td>Conditional</td><td>Fixed value: <code>BRA</code>. Required when using a Global app.</td><td>ISO 3166-1 alpha-3 country code for Brazil.</td></tr><tr><td><code>out_trade_no</code></td><td>string</td><td>Yes</td><td>Maximum length: 64 characters. Must be unique for the merchant application.</td><td>Merchant order number.</td></tr><tr><td><code>method</code></td><td>string</td><td>Yes</td><td>Fixed value: <code>Boleto</code>.</td><td>Payment method.</td></tr><tr><td><code>order_amount</code></td><td>decimal</td><td>Yes</td><td>Minimum amount: <code>20 BRL</code> in the sandbox environment and <code>2 BRL</code> in the production environment. Supports up to 2 decimal places.</td><td>Payment amount in BRL.</td></tr><tr><td><code>order_currency</code></td><td>string</td><td>Yes</td><td>Fixed value: <code>BRL</code>.</td><td>Payment currency.</td></tr><tr><td><code>subject</code></td><td>string</td><td>Yes</td><td>Maximum length: 128 characters.</td><td>Payment subject or order title.</td></tr><tr><td><code>content</code></td><td>string</td><td>Yes</td><td>Maximum length: 255 characters.</td><td>Payment description displayed on the Boleto.</td></tr><tr><td><code>notify_url</code></td><td>string</td><td>Yes</td><td>Must be a valid URL. HTTPS is recommended.</td><td>Merchant endpoint that receives asynchronous payment notifications.</td></tr><tr><td><code>return_url</code></td><td>string</td><td>No</td><td>Must be a valid URL. HTTPS is recommended.</td><td>URL to which the customer is redirected after the payment flow.</td></tr><tr><td><code>buyer_id</code></td><td>string</td><td>Yes</td><td>Maximum length: 128 characters.</td><td>Merchant-side customer ID.</td></tr><tr><td><code>timestamp</code></td><td>string</td><td>Yes</td><td>Format: <code>yyyy-MM-dd HH:mm:ss</code>. Maximum length: 19 characters.</td><td>Time at which the request is sent.</td></tr><tr><td><code>timeout_express</code></td><td>string</td><td>No</td><td>Supported formats: <code>&#x3C;number>m</code> (minutes), <code>&#x3C;number>h</code> (hours), <code>&#x3C;number>d</code> (days), or <code>1c</code> (end of the current day). A number without a unit is treated as minutes. Default: <code>90m</code>. Minimum: <code>1m</code>. Maximum: <code>15d</code>.</td><td>Controls how long the order may remain in the initial stage before it is submitted for processing. It does not change the 3-day validity period of the generated Boleto.</td></tr><tr><td><code>customer.identify.type</code></td><td>string</td><td>Yes</td><td>One of: <code>CPF</code>, <code>CNPJ</code>.</td><td>Customer identification type.</td></tr><tr><td><code>customer.identify.number</code></td><td>string</td><td>Yes</td><td><code>CPF</code>: 11 digits. <code>CNPJ</code>: 14 digits. Maximum API length: 64 characters.</td><td>Customer identification number.</td></tr><tr><td><code>customer.name</code></td><td>string</td><td>Yes</td><td>—</td><td>Customer's full name.</td></tr><tr><td><code>customer.email</code></td><td>string</td><td>Yes</td><td>Maximum length: 64 characters. Must be a valid email address.</td><td>Customer's email address.</td></tr><tr><td><code>customer.phone</code></td><td>string</td><td>No</td><td>—</td><td>Customer's phone number.</td></tr><tr><td><code>address.zip_code</code></td><td>string</td><td>Yes</td><td>8 digits.</td><td>Customer's Brazilian postal code (CEP).</td></tr></tbody></table>

#### Responses

{% tabs %}
{% tab title="200: Submit successfully" %}

```json
{
  "code": "10000",
  "msg": "Success",
  "prepay_id": "eHBz***0a",
  "trade_no": "2026***36",
  "out_trade_no": "out_t***66",
  "web_url": "",
  "barcode": "197***4055",
  "bank_code": "19790***0",
  "pay_url": "https://checkout-test.pagsmile.com/checkout?prepay_id=eHB***170a",
  "trade_status": "PROCESSING"
}
```

{% endtab %}

{% tab title="400: Duplicate out\_trade\_no" %}

```json
{
  "code": "40002",
  "msg": "Business Failed",
  "sub_code": "duplicate-out_trade_no",
  "sub_msg": "out_trade_no is duplicate"
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**User payment tips**

* Present the returned `bank_code` to the customer as the numeric payment code.
* Use `barcode` to generate a scannable barcode and make payment easier.
* Redirect the customer to the complete `pay_url` returned for the transaction. Providing a downloadable copy of the Boleto can help mobile customers complete the payment later without keeping the browser open.
  {% endhint %}

### Example&#x20;

```json
{
  "app_id": "161***24",
  "region": "BRA",
  "out_trade_no": "out_t***66",
  "method": "Boleto",
  "order_amount": "20",
  "order_currency": "BRL",
  "subject": "Diana test",
  "content": "trade pay test content",
  "notify_url": "https://merchant.example.com/payment/notify",
  "return_url": "https://www.merchant.example.com",
  "buyer_id": "buyer_22_041302",
  "timestamp": "2026-09-28 13:38:19",
  "timeout_express": "15d",
  "customer": {
    "identify": {
      "type": "CPF",
      "number": "11*******86"
    },
    "name": "User Name",
    "email": "customer@example.com"
  },
  "address": {
    "zip_code": "38082365"
  }
}
```

{% hint style="warning" %}
A response with `code=10000` confirms that the Boleto was created. `trade_status=PROCESSING` does not mean that the payment has been completed. Use payment notifications or the Payin Detail API to determine the final payment status before delivering goods or services.
{% endhint %}

### Third-party CPF/CNPJ validators

* [Go: brdoc](https://github.com/paemuri/brdoc)
* [JavaScript: cpf-cnpj-validator](https://www.npmjs.com/package/cpf-cnpj-validator)
* [Online CPF validator](https://4app.net/tools/validator/document/cpf_validator)