# Pay bank slip
In Brazil, bank slips, known as *Boleto Bancarios* or simply *Boletos* in Portuguese, are a popular payment method for various services, bills, and purchases. When a payment needs to be made, the recipient (such as a business or service provider) generates a Boleto with the necessary payment details, such as the recipent's information, the payment amount, due date, barcode, and other relevant information.
Pismo works with [BTG Pactual](https://www.btgpactual.us), [Celcoin](https://celcoin.com.br), and [Itaú](https://www.itau.com.br) to implement Boleto payments. In the future, Pismo may work with additional financial companies.
This endpoint generates the following events:
* [Authorization created](https://developers.pismo.io/events/docs/authorization-authorization-event-1) - This event contains bank slip information (beneficiary name and document number, digitable line, amount, payment date, interest/fine and discount (if any) in the `metadata` field.
* [Financial bank slip status changed](https://developers.pismo.io/events/docs/integrated-payments-bankslip-status-change-1) - Before clearing, a bank slip's status is `PAID`. After clearing, Pismo changes its status to `SETTLED`.
* [Integrated payments financial reconciliation](https://developers.pismo.io/events/docs/integrated-payments-financial-reconciliation-1)- This event is generated after the transaction has been cleared and accounts debited or credited. If `x-skip-reconciliation` is `true` or the provider is JD Consultores, this event is not generated.
See [Bank slips](doc:bank-slips) for more information.
**Important**: You need to call [Validate bank slip](ref:post-integrated-payments-api-v1-bankslips-validate) before calling this endpoint and pass the `external_authorization` field value if it is returned from that call here.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Banking - Integrated payments",
"version": "1.0",
"description": "API responsible for handling and processing integrated payments",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/"
},
"license": {
"name": "Copyright Pismo"
}
},
"servers": [
{
"url": "https://sandbox.pismolabs.io/integrated-payments",
"description": "Sandbox API server for testing"
}
],
"security": [
{
"BearerAuth": []
}
],
"tags": [
{
"name": "Bank slip",
"description": "Operations related to pay and get information about a bank slips"
}
],
"components": {
"parameters": {
"authorizationHeader": {
"name": "Authorization",
"in": "header",
"description": "Account token. Getting an account token requires you call the [Server login \nendpoint](https://developers.pismo.io/pismo-docs/reference/post-passport-v2-s2s-access-token) with an account ID. Tokens can expire \nquickly, which can result in an Unauthorized message. Enter this field under \n`AUTHENTICATION`.\n",
"required": true,
"schema": {
"type": "string"
},
"example": ""
},
"idempotencyKeyHeader": {
"name": "x-idempotency-key",
"in": "header",
"description": "Unique identifier (UUID) to ensure the operation remains idempotent, allowing for operation repitition without causing unintended effects or duplication. An idempotent operation is one that can be applied multiple times, yet the outcome remains the same. it ensures that network errors, retries, or failures can occur without introducing inconsistencies.\n",
"required": true,
"schema": {
"type": "string"
},
"example": "6a17f82d-7365-4451-a83d-09403f05c1ec"
}
},
"schemas": {
"bankslips.bankslipsPayRequest": {
"required": [
"account_id",
"amount"
],
"type": "object",
"properties": {
"account_id": {
"type": "integer",
"description": "Pismo Platform Account ID.",
"example": 7989342
},
"amount": {
"type": "number",
"description": "Amount to pay.",
"example": 100
},
"bankslip": {
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "integer",
"description": "bank slip type. (`1` = compensation form, `2` = dealership).
\nCompensation form refers to the method for processing the bank slip. Dealership (cedente) refers to the entity or individual that issues the bank slip.\n",
"enum": [
1,
2
],
"example": 1
},
"bar_code": {
"type": "string",
"description": "Bar code encoding bank slip information such as the bank code, currency code, check digit, due date, amount, and beneficiary information.\n",
"example": "22323423423423423"
},
"digitable_line": {
"type": "string",
"description": "Digitable line. On a Brazilian bank slip, the digitable line contains numerical payment information encoding details like the payment amount, due date, beneficiary information, and other transaction-specific data.",
"example": "23792374039002121400385000334004688970000050227"
},
"due_datetime": {
"type": "string",
"description": "Due datetime. ISO 8601 format - `yyyy-MM-ddTHH:mm:ss.SSSSSSSSSZ`.",
"format": "date-time",
"example": "2022-08-15T00:00:00.000Z"
},
"original_amount": {
"type": "number",
"description": "Original amount.",
"example": 100
}
},
"description": "Bank slip information"
},
"currency_code": {
"type": "string",
"description": "ISO 4217 currency code. Can be either numeric or alphabetic.",
"example": "BRL"
},
"external_authorization": {
"type": "string",
"description": "External authorization. Some providers return this value\nto the `/v1/bankslips/validate` endpoint. If returned, this value must\nbe passed on to a bank slip payment request.\nSome providers return this to a [Validate bank slip](https://developers.pismo.io/pismo-docs/reference/post-integrated-payments-api-v1-bankslips-validate) call. If returned, you **must** pass it in a [Pay bank slip](https://developers.pismo.io/pismo-docs/reference/post-integrated-payments-api-v1-bankslips-pay) endpoint call.\n",
"example": "123456"
}
}
},
"bankslips.bankslipsPayResponse": {
"type": "object",
"properties": {
"account_id": {
"type": "integer",
"description": "Pismo Platform Account ID.",
"example": 12434
},
"amount": {
"type": "number",
"description": "Amount paid.",
"example": 100
},
"authorization_id": {
"type": "integer",
"description": "Pismo Platform Account ID.",
"example": 12434
},
"bar_code": {
"type": "string",
"description": "Bar code encoding bank slip information such as the bank code, currency code, check digit, due date, amount, and beneficiary information.\n",
"example": "22323423423423423"
},
"currency_code": {
"type": "string",
"description": "ISO 4217 currency code. Can be either numeric or alphabetic.",
"example": "BRL"
},
"customer_name": {
"type": "string",
"description": "Customer name.",
"example": "Customer Name"
},
"digitable_line": {
"type": "string",
"description": "Digitable line. On a Brazilian bank slip, the digitable line contains numerical payment information encoding details like the payment amount, due date, beneficiary information, and other transaction-specific data.",
"example": "23792374039002121400385000334004688970000050227"
},
"due_datetime": {
"type": "string",
"description": "Due datetime. ISO 8601 format - `yyyy-MM-ddTHH:mm:ss.SSSSSSSSSZ`.",
"format": "date-time",
"example": "2021-05-25T00:00:00.000Z"
},
"external_id": {
"type": "string",
"description": "Client-generated ID for client tracking and monitoring.",
"example": "12434"
},
"payment_datetime": {
"type": "string",
"description": "Payment datetime.",
"format": "date-time",
"example": "2021-05-25T00:00:00.000Z"
},
"status": {
"type": "string",
"description": "Bank slip status. Possible values are `PAID`, `PROCESSING`, `SETTLED`, `ERROR`, and `TIMEOUT`.\n",
"example": "PROCESSING"
},
"additional_info": {
"type": "string",
"description": "Additional information about the bank slip payment, including provider-specific details.\n",
"example": "NumCtrl = 123456"
}
}
},
"domain.Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error type code.",
"example": "EIP0001"
},
"details": {
"type": "string",
"description": "Error details.",
"example": "Error details"
},
"message": {
"type": "string",
"description": "Error message describing the error.",
"example": "error"
}
}
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
},
"paths": {
"/v1/bankslips/pay": {
"post": {
"tags": [
"Bank slip"
],
"summary": "Pay bank slip",
"description": "In Brazil, bank slips, known as *Boleto Bancarios* or simply *Boletos* in Portuguese, are a popular payment method for various services, bills, and purchases. When a payment needs to be made, the recipient (such as a business or service provider) generates a Boleto with the necessary payment details, such as the recipent's information, the payment amount, due date, barcode, and other relevant information.\nPismo works with [BTG Pactual](https://www.btgpactual.us), [Celcoin](https://celcoin.com.br), and [Itaú](https://www.itau.com.br) to implement Boleto payments. In the future, Pismo may work with additional financial companies.\nThis endpoint generates the following events: \n* [Authorization created](https://developers.pismo.io/events/docs/authorization-authorization-event-1) - This event contains bank slip information (beneficiary name and document number, digitable line, amount, payment date, interest/fine and discount (if any) in the `metadata` field.\n* [Financial bank slip status changed](https://developers.pismo.io/events/docs/integrated-payments-bankslip-status-change-1) - Before clearing, a bank slip's status is `PAID`. After clearing, Pismo changes its status to `SETTLED`.\n* [Integrated payments financial reconciliation](https://developers.pismo.io/events/docs/integrated-payments-financial-reconciliation-1)- This event is generated after the transaction has been cleared and accounts debited or credited. If `x-skip-reconciliation` is `true` or the provider is JD Consultores, this event is not generated.
\nSee [Bank slips](https://developers.pismo.io/pismo-docs/docs/bank-slips) for more information.
\n**Important**: You need to call [Validate bank slip](https://developers.pismo.io/pismo-docs/reference/post-integrated-payments-api-v1-bankslips-validate) before calling this endpoint and pass the `external_authorization` field value if it is returned from that call here. \n",
"operationId": "post-integrated-payments-api-v1-bankslips-pay",
"parameters": [
{
"$ref": "#/components/parameters/authorizationHeader"
},
{
"$ref": "#/components/parameters/idempotencyKeyHeader"
}
],
"requestBody": {
"description": "Request Body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bankslips.bankslipsPayRequest"
}
}
},
"required": true
},
"responses": {
"202": {
"description": "Accepted",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bankslips.bankslipsPayResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIP0005": {
"summary": "Missing header",
"value": {
"code": "EIP0005",
"message": "Missing required header {x-tenant}"
}
},
"EIP0006": {
"summary": "Missing header",
"value": {
"code": "EIP0006",
"message": "Missing account-id header {x-account-id}"
}
},
"EIP0008": {
"summary": "Validation error",
"value": {
"code": "EIP0008",
"message": "Validation error"
}
},
"EIP0010": {
"summary": "Unmarshal error",
"value": {
"code": "EIP0010",
"message": "Unmarshal error"
}
},
"EIP0012": {
"summary": "Account not found",
"value": {
"code": "EIP0012",
"message": "Account not found"
}
},
"EIP0013": {
"summary": "Accounts - API returned 4xx error",
"value": {
"code": "EIP0013",
"message": "Accounts - API returned 4xx error"
}
},
"EIP0017": {
"summary": "IntlBankAccounts - API returned 4xx error",
"value": {
"code": "EIP0017",
"message": "IntlBankAccounts - API returned 4xx error"
}
},
"EIP0023": {
"summary": "Banking gateway API error",
"value": {
"code": "EPI0023",
"message": "Banking gateway API error - API returned 4xx error"
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIP0005": {
"summary": "Missing header",
"value": {
"code": "EIP0005",
"message": "Missing required header {x-tenant}"
}
},
"EIP0006": {
"summary": "Missing header",
"value": {
"code": "EIP0006",
"message": "Missing account-id header {x-account-id}"
}
},
"EIP0009": {
"summary": "Missing header",
"value": {
"code": "EIP0009",
"message": "Missing account-id header {x-idempotency-key}"
}
},
"EIP0030": {
"summary": "Account ID not found",
"value": {
"code": "EIP0030",
"message": "Entity's account ID does not match {x-account-id} header"
}
}
}
}
}
},
"409": {
"description": "Conflict",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIP0065": {
"summary": "Conflict",
"value": {
"code": "EIP0029",
"message": "BankingGatewayAPI returned 409 provider error"
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIP0004": {
"summary": "HTTP request error",
"value": {
"code": "EIP0004",
"message": "HTTP request error"
}
},
"EIP0007": {
"summary": "Internal error",
"value": {
"code": "EIP0007",
"message": "Internal error"
}
},
"EIP0011": {
"summary": "Accounts API timeout error",
"value": {
"code": "EIP0011",
"message": "Accounts API timeout error"
}
},
"EIP0015": {
"summary": "IntlBankAccounts API timeout error",
"value": {
"code": "EIP0015",
"message": "IntlBankAccounts API timeout error"
}
},
"EIP0019": {
"summary": "P2P API timeout error",
"value": {
"code": "EIP0015",
"message": "P2p - API timeout error"
}
},
"EIP0022": {
"summary": "BankingGatewayAPI API timeout error",
"value": {
"code": "EIP0022",
"message": "BankingGatewayAPI API timeout error"
}
},
"EIP0028": {
"summary": "Transaction database error",
"value": {
"code": "EIP0028",
"message": "Transacation database error"
}
},
"EIP0041": {
"summary": "Bank slip database error",
"value": {
"code": "EIP0041",
"message": "Bank slip database error"
}
},
"EIP0051": {
"summary": "Schedule conciliation error",
"value": {
"code": "EIP0053",
"message": "Schedule conciliation error"
}
},
"EIP0053": {
"summary": "Send integrity message error",
"value": {
"code": "EIP0053",
"message": "Send integrity message error"
}
},
"EIP0069": {
"summary": "P2P API - Failure to unmarshal error",
"value": {
"code": "EIP0069",
"message": "P2P API - Failed to unmarshal error response body"
}
}
}
}
}
},
"502": {
"description": "Bad Gateway",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIP0024": {
"summary": "Bad Gateway",
"value": {
"code": "EIP0024",
"message": "BankingGatewayAPI - API returned 5xx error"
}
}
}
}
}
},
"504": {
"description": "Gateway Timeout",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIP0002": {
"summary": "Gateway Timeout",
"value": {
"code": "EIP0002",
"message": "API request timeout"
}
}
}
}
}
}
}
}
}
}
}
```