---
updatedAt: 2026-06-13T01:37:16.000Z
---
Fetch the complete documentation index at: https://developers.pismo.io/pismo-docs/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.
# Validate bank slip
Validate bank slip with provider partner.
You need to call this endpoint before calling [Pay bank slip](ref:post-integrated-payments-api-v1-bankslips-pay). If this endpoint returns an `external_authorization` field value, you must pass it in the Pay bank slip call.
For this endpoint, either `bar_code` or `digitable_line` **must** be passed.
# 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": ""
}
},
"schemas": {
"bankslips.bankslipsValidateRequest": {
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"type": "integer",
"description": "Banslip 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.",
"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": "20890001091000001090980008176705191030000002000"
}
}
},
"bankslips.bankslipsValidateResponse": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"description": "Amount to pay.",
"example": 10
},
"assignor": {
"type": "string",
"description": "The name of the receiver bank.",
"example": "BANCO ITAU S.A."
},
"bar_code": {
"type": "string",
"description": "Bar code.",
"example": "22323423423423423"
},
"beneficiary_document_number": {
"type": "string",
"description": "A government document number, such as a CPF (Brazil) - Cadastro de Pessoas Fisicas (Indiviual Taxpayer Registry) number, CNPJ (Brazil) - Cadastro Nacional de Pessoa Juridica (National Registry of Legal Entities) number - unique ID for legal entities, such as companies and organizations.\n",
"example": "123456789"
},
"beneficiary_name": {
"type": "string",
"description": "Beneficiary name.",
"example": "Beneficiary 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": "34192374039002121400385000334004688970000050227"
},
"discount_value": {
"type": "number",
"description": "Discount value.",
"example": 0
},
"due_date": {
"type": "string",
"format": "datetime",
"description": "Due datetime. ISO 8601 format - `yyyy-MM-ddTHH:mm:ss.SSSSSSSSSZ`.",
"example": "2022-08-15T00:00:00.000Z"
},
"external_authorization": {
"type": "string",
"description": "Some 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](ref:post-integrated-payments-api-v1-bankslips-pay) endpoint call.\nIf returned, this value must be passed on to a bank slip payment request.\n",
"example": "123"
},
"fine_value": {
"type": "number",
"description": "Fine value.",
"example": 0
},
"interest_value": {
"type": "number",
"description": "Interest value.",
"example": 0
},
"limit_date": {
"type": "string",
"description": "Limit datetime to pay. ISO 8601 format - `yyyy-MM-ddTHH:mm:ss.SSSSSSSSSZ`.",
"format": "date",
"example": "2022-08-15T00:00:00.000Z"
},
"max_value": {
"type": "number",
"description": "Maximum value.",
"example": 10
},
"min_value": {
"type": "number",
"description": "Minimum value.",
"example": 10
},
"original_value": {
"type": "number",
"description": "Original value.",
"example": 10
},
"payer_document_number": {
"type": "string",
"description": "A government document number, such as a CPF (Brazil) - Cadastro de Pessoas Fisicas (Indiviual Taxpayer Registry) number, CNPJ (Brazil) - Cadastro Nacional de Pessoa Juridica (National Registry of Legal Entities) number - unique ID for legal entities, such as companies and organizations.",
"example": "923456789"
},
"payer_name": {
"type": "string",
"description": "Payer's name.",
"example": "Payer's name"
},
"settle_date": {
"type": "string",
"format": "date",
"description": "Settlement date. ISO 8601 format - `yyyy-MM-ddTHH:mm:ss.SSSSSSSSSZ`.",
"example": "2022-08-15T00:00:00.000Z"
},
"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",
"example": 1
}
}
},
"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/validate": {
"post": {
"tags": [
"Bank slip"
],
"summary": "Validate bank slip",
"description": "Validate bank slip with provider partner.
\nYou need to call this endpoint before calling [Pay bank slip](https://developers.pismo.io/pismo-docs/reference/post-integrated-payments-api-v1-bankslips-pay). If this endpoint returns an `external_authorization` field value, you must pass it in the Pay bank slip call.
\nFor this endpoint, either `bar_code` or `digitable_line` **must** be passed.\n",
"operationId": "post-integrated-payments-api-v1-bankslips-validate",
"parameters": [
{
"$ref": "#/components/parameters/authorizationHeader"
}
],
"requestBody": {
"description": "Request Body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bankslips.bankslipsValidateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Response Body",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bankslips.bankslipsValidateResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIP0008": {
"summary": "Validation error",
"value": {
"code": "EIP0008",
"message": "Validation error"
}
},
"EIP0010": {
"summary": "Unmarshal error",
"value": {
"code": "EIP0010",
"message": "Unmarshal error"
}
},
"EIP0023": {
"summary": "Banking gateway API error",
"value": {
"code": "EIP0023",
"message": "BankingGatewayAPI - 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": "Invalid account ID header",
"value": {
"code": "EIP0006",
"message": "Invalid account id header: 'x-account-id'"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIP0049": {
"summary": "Convert barcode to digitable line failure",
"value": {
"code": "EIP0049",
"message": "Convert barcode to digitable line failed"
}
}
}
}
}
},
"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": "BankingGatewayAPI - Provider error",
"value": {
"code": "EIP0065",
"message": "BankingGatewayAPI - API 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"
}
},
"EIP0022": {
"summary": "BankingGatewayAPI API timeout error",
"value": {
"code": "EIP0022",
"message": "BankingGatewayAPI - API timeout error"
}
},
"EIP0070": {
"summary": "BankingGateway API - Failed to unmarshal error response",
"value": {
"code": "EIP0070",
"message": "BankingGateway 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": "BankingGatewayAPI - API returned 5xx error",
"value": {
"code": "EIP0024",
"message": "BankingGatewayAPI - API returned 5xx error"
}
}
}
}
}
}
}
}
}
}
}
```