# Perform cash-out
Perform an external transfer, using a provider to process the outgoing account resources.
This endpoint generates the following events:
* [Transfer-out created](https://developers.pismo.io/events/docs/integrated-payments-transfer-out-created-1) - Cash-out event.
* [Financial transaction status updated](https://developers.pismo.io/events/docs/integrated-payments-transaction-status-change-1) - Cash out status change. Status becomes `SETTLED` after clearing and accounts have been credited and debited.
* [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.
# 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": "Transfer",
"description": "Operations related to transfer cashin and cashout"
}
],
"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": ""
},
"skipReconciliationHeader": {
"name": "x-skip-reconciliation",
"in": "header",
"description": "If `true`, the reconciliation process is skipped and the Integrated payments financial reconciliation event is not generated. Default is `false`.
\nThe financial reconciliation process compares the transaction made on Pismo with the same transaction made on the provider side (i.e., BTG or Celcoin).\n",
"schema": {
"type": "boolean"
},
"example": true
},
"xSignatureHeader": {
"name": "X-Signature",
"in": "header",
"description": "This header is designed for clients working with a third‑party provider that requires certain transactions to include a certified digital signature for added security. It is optional and should be used only if your provider requires signature validation. When included, our APIs forward the header to the provider, which verifies the signature and approves or rejects the transaction based on its authenticity.\n",
"required": false,
"schema": {
"type": "string"
},
"example": "5903AB76A8BC52E2CBD04E83042C32F26A23F022;s0k/tU3m+iAvWfrori8+TdhWqUn0jAAKvq/hyNuAEfxSE;20250909"
},
"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": {
"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"
}
}
},
"transfers.Account": {
"required": [
"identification",
"type"
],
"type": "object",
"properties": {
"bank": {
"$ref": "#/components/schemas/transfers.Bank"
},
"identification": {
"type": "string",
"description": "Account identification. Unique account identifier, for example a bank account number.",
"example": "98765432"
},
"type": {
"type": "string",
"description": "Account type.",
"example": "CC"
}
}
},
"transfers.Bank": {
"required": [
"branch",
"code",
"identification"
],
"type": "object",
"properties": {
"branch": {
"type": "string",
"description": "Bank branch.",
"example": "0011"
},
"code": {
"type": "string",
"description": "Alternative bank identifier, for example, in brazil is COMPE.",
"example": "30306294"
},
"identification": {
"type": "string",
"description": "Bank identification. The main bank identifier, for example, in brazil is ISPB.",
"example": "30306294"
}
}
},
"transfers.Client": {
"required": [
"identification",
"name",
"type"
],
"type": "object",
"properties": {
"account": {
"$ref": "#/components/schemas/transfers.Account"
},
"identification": {
"type": "string",
"description": "Identification. Document number or another unique identifier.",
"example": "12345678900"
},
"name": {
"description": "Full name.",
"type": "string",
"example": "John Doe"
},
"type": {
"type": "string",
"description": "Type required by provider; for example: F = Legal person.\n",
"example": "F"
}
}
},
"transfers.TransfersCashOutRequest": {
"required": [
"account_id",
"amount",
"processing_code"
],
"type": "object",
"properties": {
"account_id": {
"description": "Pismo Platform client ID.",
"type": "integer",
"example": 415424
},
"amount": {
"type": "number",
"description": "Dot-separated transfer amount in decimals.",
"example": 101.11
},
"currency_code": {
"type": "string",
"description": "ISO 4217 currency code. Can be either numeric or alphabetic.",
"example": "BRL"
},
"processing_code": {
"type": "string",
"description": "Transfer processing code. Used to identify the type of transfer.",
"example": "876578435"
},
"creditor": {
"$ref": "#/components/schemas/transfers.Client"
}
}
},
"transfers.TransfersCashOutResponse": {
"type": "object",
"properties": {
"correlation_id": {
"description": "Correlation ID.",
"type": "string"
},
"external_id": {
"description": "External ID of the provider.",
"type": "string"
}
}
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
},
"paths": {
"/v1/transfers/cashout": {
"post": {
"tags": [
"Transfer"
],
"summary": "Perform cash-out",
"description": "Perform an external transfer, using a provider to process the outgoing account resources.\nThis endpoint generates the following events:\n* [Transfer-out created](https://developers.pismo.io/events/docs/integrated-payments-transfer-out-created-1) - Cash-out event.\n* [Financial transaction status updated](https://developers.pismo.io/events/docs/integrated-payments-transaction-status-change-1) - Cash out status change. Status becomes `SETTLED` after clearing and accounts have been credited and debited.\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.\n",
"operationId": "post-integrated-payments-api-v1-bankslips-cashout",
"parameters": [
{
"$ref": "#/components/parameters/authorizationHeader"
},
{
"$ref": "#/components/parameters/idempotencyKeyHeader"
},
{
"$ref": "#/components/parameters/skipReconciliationHeader"
},
{
"$ref": "#/components/parameters/xSignatureHeader"
}
],
"requestBody": {
"description": "Request Body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/transfers.TransfersCashOutRequest"
}
}
},
"required": true
},
"responses": {
"202": {
"description": "Response Body",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/transfers.TransfersCashOutResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIP0003": {
"summary": "Bad Request",
"value": {
"code": "EIP0003",
"message": "Bad Request"
}
},
"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"
}
},
"EIP0016": {
"summary": "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"
}
},
"EIP0020": {
"summary": "P2p - API returned 4xx error",
"value": {
"code": "EIP0020",
"message": "P2p - 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 tenant header",
"value": {
"code": "EIP0005",
"message": "Missing required header {x-tenant}"
}
},
"EIP0006": {
"summary": "Invalid account header",
"value": {
"code": "EIP0006",
"message": "Invalid account id header {x-account-id}"
}
},
"EIP0009": {
"summary": "Missing idempotency header",
"value": {
"code": "EIP0009",
"message": "Missing required header {x-idempotency-key}"
}
},
"EIP0030": {
"summary": "Entity's account id does not match x-account-id header",
"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": {
"EIP0029": {
"summary": "Account blocked or cancelled",
"value": {
"code": "EIP0029",
"message": "Account blocked or cancelled"
}
},
"EIP0031": {
"summary": "Idempotency header already exists",
"value": {
"code": "EIP0031",
"message": "{x-idempotency-key} already exists"
}
},
"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"
}
},
"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"
}
},
"EIP0022": {
"summary": "BankingGatewayAPI API timeout error",
"value": {
"code": "EIP0022",
"message": "BankingGatewayAPI API timeout error"
}
}
}
}
}
}
}
}
}
}
}
```