# Issue bank slip
Create a bank slip and issue it to the provider. See [Bank slips](doc:bank-slips) for more information.
This endpoint generates the [Bank slip issuance registered](https://developers.pismo.io/events/docs/integrated-payments-bankslip-issue-register-1) event.
# 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 issuance",
"description": "Operations related to issue and cancel issued bank slips"
}
],
"components": {
"parameters": {
"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_issue.IssueDebtor": {
"type": "object",
"properties": {
"city": {
"description": "City where the debtor resides.",
"type": "string",
"example": "New York"
},
"complement": {
"description": "Additional address.",
"type": "string",
"example": "Complement"
},
"document_number": {
"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",
"type": "string",
"example": "00000000000"
},
"name": {
"description": "Debtor's full name.",
"example": "John Doe",
"type": "string"
},
"neighborhood": {
"description": "Neighborhood name where the debtor resides.",
"type": "string",
"example": "Neighborhood"
},
"number": {
"description": "Street number.",
"type": "string",
"example": "123"
},
"state": {
"description": "The name of the state.",
"type": "string",
"example": "UF"
},
"street": {
"description": "The name of the street where the debtor resides.",
"type": "string",
"example": "Street"
},
"zip_code": {
"description": "Zip code.",
"type": "string",
"example": "00000000"
}
}
},
"bankslips_issue.IssueDiscount": {
"type": "object",
"properties": {
"amount": {
"description": "Discounted amount to be applied to the bank slip amount if paid before or on the deadline.",
"type": "number",
"example": 10
},
"deadline": {
"description": "Discount deadline.",
"type": "string",
"example": "2024-09-25T00:00:00.000Z"
},
"type": {
"description": "Fixed bank slip type",
"type": "string",
"example": "fixed"
}
}
},
"bankslips_issue.IssueInstructions": {
"required": [
"fine",
"interest"
],
"type": "object",
"properties": {
"fine": {
"description": "Fine to be applied to the bank slip amount if overdue.",
"type": "number",
"example": 5
},
"interest": {
"description": "Interest to be applied to the bank slips amount when overdue.",
"type": "number",
"example": 10
},
"discount": {
"$ref": "#/components/schemas/bankslips_issue.IssueDiscount"
}
}
},
"bankslips_issue.IssueRequest": {
"required": [
"amount",
"due_date"
],
"type": "object",
"properties": {
"amount": {
"description": "bank slip amount.",
"type": "number",
"example": 100
},
"due_date": {
"description": "bank slip payment due date.",
"type": "string",
"format": "date",
"example": "2024-07-25T00:00:00.000Z"
},
"debtor": {
"$ref": "#/components/schemas/bankslips_issue.IssueDebtor"
},
"description": {
"description": "Description about the bank slip.",
"type": "string",
"example": "Long description."
},
"instructions": {
"$ref": "#/components/schemas/bankslips_issue.IssueInstructions"
},
"maximum_amount": {
"description": "Maximum amount accepted when paying the bank slip.",
"type": "number",
"example": 100
},
"minimum_amount": {
"description": "Minimum amount accepted when paying the bank slip.",
"type": "number",
"example": 10
},
"over_due_date": {
"description": "Last day to accept bank slip payments. After this date, the bank slip is not paid.",
"type": "string",
"format": "date",
"example": "2024-08-25T00:00:00.000Z"
},
"pix_key": {
"description": "PIX key related to the bank slip.",
"type": "string",
"example": "pixkey@pix.com.br"
},
"issuer": {
"description": "The name of the provider that issues the bank slip.",
"type": "string",
"example": "PISMO"
},
"transaction_id": {
"description": "Transaction ID related to the bank slip issue. This is the ID that links the bank slip to the specific transaction performed in the payments API. It can be used for tracking, reconciliation, and reference purposes when managing bank slips and their associated transactions.",
"type": "string",
"example": "550e8400-e29b-41d4-a716-446655440000"
}
}
},
"bankslips_issue.IssueResponse": {
"type": "object",
"properties": {
"client_request_id": {
"description": "Unique identifier of the request controlled by the client.",
"type": "string",
"example": "6d6bdd2c-9980-4cf1-87ff-c99dc9ce6ef4456"
},
"external_id": {
"description": "Unique identifier of the request controlled by the provider.",
"type": "string",
"example": "6d6bdd2c-9980-4cf1-87ff-c99dc9ce6ef4123"
},
"status": {
"description": "bank slip status. Possible values are `CREATED`, `CANCELLED`, `REGISTERED`, and `ERROR`.",
"type": "string",
"example": "CREATED"
}
}
},
"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-issue": {
"post": {
"tags": [
"Bank slip issuance"
],
"operationId": "post-integrated-payments-api-v1-bankslips-issue",
"summary": "Issue bank slip",
"description": "Create a bank slip and issue it to the provider. See [Bank slips](https://developers.pismo.io/pismo-docs/docs/bank-slips) for more information.
\nThis endpoint generates the [Bank slip issuance registered](https://developers.pismo.io/events/docs/integrated-payments-bankslip-issue-register-1) event.\n",
"parameters": [
{
"$ref": "#/components/parameters/idempotencyKeyHeader"
}
],
"requestBody": {
"description": "Request Body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bankslips_issue.IssueRequest"
}
}
},
"required": true
},
"responses": {
"202": {
"description": "Accepted",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bankslips_issue.IssueResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIP0010": {
"summary": "Unmarshal error",
"value": {
"code": "EIP0010",
"message": "Unmarshal error"
}
},
"EIP0012": {
"summary": "Account not found",
"value": {
"code": "EIP0012",
"message": "Account not found"
}
},
"EIP0016": {
"summary": "IntlBankAccounts - API Account not found",
"value": {
"code": "EIP0016",
"message": "IntlBankAccounts - API Account not found"
}
},
"EIP0017": {
"summary": "IntlBankAccounts - API returned 4xx error",
"value": {
"code": "EIP0017",
"message": "IntlBankAccounts - API returned 4xx error"
}
},
"EIP0023": {
"summary": "BankingGatewayAPI - API returned 4xx error",
"value": {
"code": "EIP0023",
"message": "BankingGatewayAPI - API returned 4xx error"
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIP0005": {
"summary": "Missing required header x-tenant",
"value": {
"code": "EIP0005",
"message": "Missing required header {x-tenant}"
}
},
"EIP0006": {
"summary": "Invalid account ID header x-account-id",
"value": {
"code": "EIP0006",
"message": "Invalid account ID header {x-account-id}"
}
},
"EIP0009": {
"summary": "Missing required header x-idempotency-key",
"value": {
"code": "EIP0005",
"message": "Missing required header {x-idempotency-key}"
}
},
"EIP0029": {
"summary": "Account blocked or canceled",
"value": {
"code": "EIP0029",
"message": "Account blocked or canceled"
}
}
}
}
}
},
"409": {
"description": "Conflict",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIP0065": {
"summary": "BankingGatewayAPI returned 409 provider error",
"value": {
"code": "EIP0029",
"message": "BankingGatewayAPI returned 409 provider error"
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIP0015": {
"summary": "IntlBankAccounts - API timeout error",
"value": {
"code": "EIP0015",
"message": "IntlBankAccounts - API timeout error"
}
},
"EIP0014": {
"summary": "Accounts - API returned 5xx error",
"value": {
"code": "EIP0014",
"message": "Accounts - API returned 5xx error"
}
},
"EIP0007": {
"summary": "Internal error",
"value": {
"code": "EIP0007",
"message": "Internal error"
}
},
"EIP0004": {
"summary": "HTTP request error",
"value": {
"code": "EIP0004",
"message": "HTTP request error"
}
},
"EIP0011": {
"summary": "Accounts API timeout error",
"value": {
"code": "EIP0011",
"message": "Accounts API timeout error"
}
},
"EIP0028": {
"summary": "Transaction database error",
"value": {
"code": "EIP0028",
"message": "Transaction database error"
}
},
"EIP0022": {
"summary": "BankingGatewayAPI - API timeout error",
"value": {
"code": "EIP0022",
"message": "BankingGatewayAPI - API timeout error"
}
}
}
}
}
},
"502": {
"description": "Bad Gateway",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIP0018": {
"summary": "IntlBankAccounts - API returned 5xx error",
"value": {
"code": "EIP0018",
"message": "IntlBankAccounts - API returned 5xx error"
}
},
"EIP0024": {
"summary": "BankingGatewayAPI - API returned 5xx error",
"value": {
"code": "EIP0024",
"message": "BankingGatewayAPI - API returned 5xx error"
}
}
}
}
}
}
}
}
}
}
}
```