> For the complete documentation index, see [llms.txt](https://readme.streampayments.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://readme.streampayments.io/readme/api-reference/payout-api.md).
# Payout API
API para gestión de pagos y desembolsos. Todos los endpoints requieren autenticación mediante headers de seguridad (x-api-key, x-api-secret, x-signature, x-timestamp).
## Obtener un pago
> Obtiene la información detallada de un pago específico utilizando el ID de transacción.\
> \
> \*\*Autenticación requerida:\*\*\
> \- x-api-key: Clave API del comerciante\
> \- x-api-secret: Secreto API del comerciante\
> \- x-signature: Firma HMAC-SHA256 calculada con: apiKey-apiSecret-timestamp-transactionId\
> \- x-timestamp: Timestamp de la solicitud\
> \
> \*\*Información retornada:\*\*\
> \- Estado actual del pago\
> \- Montos y moneda\
> \- Fechas de creación y procesamiento\
> \- Detalles del destinatario\
> \- Información de rastreo
```json
{"openapi":"3.0.1","info":{"title":"Payout API","version":"1.0"},"tags":[{"name":"Payout API","description":"API para gestión de pagos y desembolsos. Todos los endpoints requieren autenticación mediante headers de seguridad (x-api-key, x-api-secret, x-signature, x-timestamp)."}],"servers":[{"url":"https://dev.api.outflow.streampayments.io/spay-connect","description":"Generated server url"}],"security":[{"PayoutSecurity":[]}],"components":{"securitySchemes":{"PayoutSecurity":{"type":"apiKey","description":"Headers de seguridad requeridos: x-api-key, x-api-secret, x-signature, x-timestamp","name":"x-api-key","in":"header"}},"schemas":{"PayoutResponse":{"type":"object","properties":{"payoutId":{"type":"string"},"merchantCode":{"type":"string"},"currencyCode":{"type":"string"},"countryCode":{"type":"string"},"transactionId":{"type":"string"},"description":{"type":"string"},"amount":{"type":"string"},"chargeType":{"type":"string"},"referenceId":{"type":"string"},"extraInfo":{"type":"string"},"receiver":{"$ref":"#/components/schemas/Receiver"},"receivingBank":{"$ref":"#/components/schemas/ReceivingBank"},"processingData":{"$ref":"#/components/schemas/ProcessBank"},"chargeTypeId":{"type":"string"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"status":{"type":"string"},"statusAt":{"type":"string"},"creationAt":{"type":"string"},"updateAt":{"type":"string"},"payoutGroupId":{"type":"integer","format":"int32"}}},"Receiver":{"type":"object","properties":{"name":{"type":"string"},"lastName":{"type":"string"},"documentNumber":{"type":"string"},"documentType":{"type":"string"},"phoneNumber":{"type":"string"},"email":{"type":"string"},"userName":{"type":"string"},"customId":{"type":"string"}}},"ReceivingBank":{"type":"object","properties":{"bankCode":{"type":"string"},"accountNumber":{"type":"string"},"accountNumberCci":{"type":"string"},"accountType":{"type":"string"}}},"ProcessBank":{"type":"object","properties":{"code":{"type":"string"},"description":{"type":"string"},"extraInformation":{"type":"string"}}}}},"paths":{"/api/v1/payout":{"get":{"tags":["Payout API"],"summary":"Obtener un pago","description":"Obtiene la información detallada de un pago específico utilizando el ID de transacción.\n\n**Autenticación requerida:**\n- x-api-key: Clave API del comerciante\n- x-api-secret: Secreto API del comerciante\n- x-signature: Firma HMAC-SHA256 calculada con: apiKey-apiSecret-timestamp-transactionId\n- x-timestamp: Timestamp de la solicitud\n\n**Información retornada:**\n- Estado actual del pago\n- Montos y moneda\n- Fechas de creación y procesamiento\n- Detalles del destinatario\n- Información de rastreo\n","operationId":"getPayoutByTransaction","parameters":[{"name":"transactionId","in":"query","description":"Identificador único de la transacción. Debe ser un string alfanumérico. Este valor se usa para calcular la firma HMAC-SHA256.","required":true,"schema":{"pattern":"^[A-Za-z0-9]+$","type":"string"}}],"responses":{"200":{"description":"Pago encontrado exitosamente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutResponse"}}}},"401":{"description":"No autorizado. Puede ocurrir por:\n- Headers de seguridad faltantes\n- Credenciales inválidas\n- Firma HMAC-SHA256 incorrecta\n","content":{"application/json":{}}},"404":{"description":"Pago no encontrado con el ID de transacción proporcionado para el comerciante autenticado","content":{"application/json":{}}},"500":{"description":"Error interno del servidor","content":{"application/json":{}}}}}}}}
```
## Crear un pago
> Crea un nuevo pago o desembolso.\
> \
> \*\*Autenticación requerida:\*\*\
> \- x-api-key: Clave API del comerciante\
> \- x-api-secret: Secreto API del comerciante\
> \- x-signature: Firma HMAC-SHA256 calculada con: apiKey-apiSecret-timestamp-transactionId-currencyCode-amount\
> \- x-timestamp: Timestamp de la solicitud\
> \
> \*\*Proceso:\*\*\
> 1\. Validación de headers de seguridad en SecurityInterceptor\
> 2\. Generación de token OAuth2 con servicio de seguridad\
> 3\. Validación de firma HMAC-SHA256\
> 4\. Validación de datos de entrada\
> 5\. Procesamiento asíncrono del desembolso
```json
{"openapi":"3.0.1","info":{"title":"Payout API","version":"1.0"},"tags":[{"name":"Payout API","description":"API para gestión de pagos y desembolsos. Todos los endpoints requieren autenticación mediante headers de seguridad (x-api-key, x-api-secret, x-signature, x-timestamp)."}],"servers":[{"url":"https://dev.api.outflow.streampayments.io/spay-connect","description":"Generated server url"}],"security":[{"PayoutSecurity":[]}],"components":{"securitySchemes":{"PayoutSecurity":{"type":"apiKey","description":"Headers de seguridad requeridos: x-api-key, x-api-secret, x-signature, x-timestamp","name":"x-api-key","in":"header"}},"schemas":{"DisburseRequestDto":{"required":["amount","currencyCode","description","receiver","receivingInstitution","transactionId","transferType"],"type":"object","properties":{"currencyCode":{"pattern":"[A-Z]{3}","type":"string","description":"Código ISO 4217 de la moneda (3 letras)"},"transactionId":{"maxLength":50,"minLength":1,"type":"string","description":"Identificador único de la transacción. Alfanumérico de 1 a 50 caracteres"},"description":{"maxLength":100,"minLength":1,"type":"string","description":"Descripción del pago. De 1 a 100 caracteres"},"amount":{"type":"string","description":"Monto del pago en formato string numérico"},"transferType":{"pattern":"WALLET|BANK","type":"string","description":"Tipo de transferencia (p.ej. WALLET, BANK)"},"receiver":{"$ref":"#/components/schemas/ReceiverDto"},"receivingInstitution":{"$ref":"#/components/schemas/ReceivingInstitutionDto"},"extraInformation":{"$ref":"#/components/schemas/ExtraInformationDto"}},"description":"DTO para solicitar un desembolso de pago"},"ReceiverDto":{"required":["documentNumber","documentType","email","lastName","name"],"type":"object","properties":{"name":{"maxLength":50,"minLength":1,"type":"string","description":"Nombre del receptor"},"lastName":{"maxLength":50,"minLength":1,"type":"string","description":"Apellido del receptor"},"userName":{"maxLength":30,"minLength":0,"type":"string","description":"Nombre de usuario del receptor"},"email":{"type":"string","description":"Correo electrónico del receptor"},"documentNumber":{"type":"string","description":"Número de documento del receptor"},"documentType":{"pattern":"DT\\d{2}","type":"string","description":"Tipo de documento del receptor"},"customId":{"maxLength":30,"minLength":0,"type":"string","description":"Identificador personalizado del receptor"}},"description":"DTO con información del receptor del desembolso"},"ReceivingInstitutionDto":{"required":["institutionCode"],"type":"object","properties":{"institutionCode":{"type":"string","description":"Código de la institución que procesa el pago"},"accountType":{"pattern":"AT001|AT002","type":"string","description":"Tipo de cuenta para transferencias propias (AT001=Cuenta de ahorros, AT002=Cuenta corriente)"},"accountNumber":{"pattern":"\\d+","type":"string","description":"Número de cuenta para transferencias bancarias propias"},"cciNumber":{"pattern":"\\d{20}","type":"string","description":"Número de CCI para pagos interbancarios"},"phoneNumber":{"pattern":"\\d{9}","type":"string","description":"Número de teléfono para pagos por WALLET"}},"description":" DTO con información de la institución receptora del pago.\n Para CCI: institutionCode + cciNumber.\n Para WALLET: institutionCode + phoneNumber.\n Para cuentas propias: accountNumber + accountType + institutionCode.\n"},"ExtraInformationDto":{"type":"object","properties":{"referenceId":{"maxLength":20,"minLength":0,"type":"string","description":"Identificador de referencia externo asociado al pago"},"extraInfo":{"maxLength":100,"minLength":0,"type":"string","description":"Información adicional personalizada para el desembolso"}},"description":"DTO con información adicional opcional para el desembolso"},"CreatePayoutResponse":{"type":"object","properties":{"merchantCode":{"type":"string"},"currencyCode":{"type":"string"},"countryCode":{"type":"string"},"transactionId":{"type":"string"},"amount":{"type":"string"},"createdDate":{"type":"string"},"msgDescription":{"type":"string"},"payout_id":{"type":"string"}}}}},"paths":{"/api/v1/payout":{"post":{"tags":["Payout API"],"summary":"Crear un pago","description":"Crea un nuevo pago o desembolso.\n\n**Autenticación requerida:**\n- x-api-key: Clave API del comerciante\n- x-api-secret: Secreto API del comerciante\n- x-signature: Firma HMAC-SHA256 calculada con: apiKey-apiSecret-timestamp-transactionId-currencyCode-amount\n- x-timestamp: Timestamp de la solicitud\n\n**Proceso:**\n1. Validación de headers de seguridad en SecurityInterceptor\n2. Generación de token OAuth2 con servicio de seguridad\n3. Validación de firma HMAC-SHA256\n4. Validación de datos de entrada\n5. Procesamiento asíncrono del desembolso\n","operationId":"createPayout","requestBody":{"description":"Datos del desembolso incluyendo:\n- transactionId: ID único de la transacción (usado para firma)\n- amount: Monto del pago (usado para firma)\n- currencyCode: Código de moneda ISO 4217 (usado para firma)\n- recipientAccount: Cuenta del destinatario\n- description: Descripción del pago\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisburseRequestDto"}}},"required":true},"responses":{"200":{"description":"Pago creado exitosamente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePayoutResponse"}}}},"400":{"description":"Datos de entrada inválidos. Error en validación de campos requeridos o formatos incorrectos.","content":{"application/json":{}}},"401":{"description":"No autorizado. Puede ocurrir por:\n- Headers de seguridad faltantes (x-api-key, x-api-secret, x-signature)\n- Credenciales inválidas en el servicio de seguridad\n- Token de acceso no generado o inválido\n- Firma HMAC-SHA256 incorrecta\n","content":{"application/json":{}}},"500":{"description":"Error interno del servidor. Error en el servicio de seguridad o procesamiento del pago.","content":{"application/json":{}}}}}}}}
```
## Obtener balance de cuenta
> Obtiene el balance actual de la cuenta del comerciante autenticado.\
> \
> \*\*Autenticación requerida:\*\*\
> \- x-api-key: Clave API del comerciante\
> \- x-api-secret: Secreto API del comerciante\
> \- x-signature: Firma HMAC-SHA256 calculada con: apiKey-apiSecret-timestamp-currencyCode (si se proporciona)\
> \- x-timestamp: Timestamp de la solicitud\
> \
> \*\*Comportamiento:\*\*\
> \- Si se especifica currencyCode: retorna balance para esa moneda específica\
> \- Sin currencyCode: retorna balances de todas las monedas disponibles para el comerciante\
> \
> \*\*Información retornada:\*\*\
> \- Balance disponible para desembolsos\
> \- Balance pendiente (en procesamiento)\
> \- Balance total\
> \- Ultima actualización
```json
{"openapi":"3.0.1","info":{"title":"Payout API","version":"1.0"},"tags":[{"name":"Payout API","description":"API para gestión de pagos y desembolsos. Todos los endpoints requieren autenticación mediante headers de seguridad (x-api-key, x-api-secret, x-signature, x-timestamp)."}],"servers":[{"url":"https://dev.api.outflow.streampayments.io/spay-connect","description":"Generated server url"}],"security":[{"PayoutSecurity":[]}],"components":{"securitySchemes":{"PayoutSecurity":{"type":"apiKey","description":"Headers de seguridad requeridos: x-api-key, x-api-secret, x-signature, x-timestamp","name":"x-api-key","in":"header"}},"schemas":{"AccountBalanceResponseDto":{"type":"object","properties":{"merchantCode":{"type":"string","description":"Código de la entidad"},"countryCode":{"type":"string","description":"Código del país ISO 3166-1 alpha-2"},"currencyCode":{"type":"string","description":"Código ISO 4217 de la moneda"},"accountType":{"type":"string","description":"Tipo de saldo. SINGLE: fondeo a una única cuenta; MULTIPLE: manejo de saldo por banco"},"accountingBalance":{"type":"number","description":"Saldo contable total"},"availableBalance":{"type":"number","description":"Saldo disponible"},"bankBalances":{"type":"object","properties":{"institutionCode":{"type":"string","description":"Código del banco"},"accountingBalance":{"type":"number","description":"Saldo contable de este banco"},"availableBalance":{"type":"number","description":"Saldo disponible de este banco"}},"description":"Saldo por banco"}},"description":"DTO de respuesta con el saldo de la cuenta"}}},"paths":{"/api/v1/balance":{"get":{"tags":["Payout API"],"summary":"Obtener balance de cuenta","description":"Obtiene el balance actual de la cuenta del comerciante autenticado.\n\n**Autenticación requerida:**\n- x-api-key: Clave API del comerciante\n- x-api-secret: Secreto API del comerciante\n- x-signature: Firma HMAC-SHA256 calculada con: apiKey-apiSecret-timestamp-currencyCode (si se proporciona)\n- x-timestamp: Timestamp de la solicitud\n\n**Comportamiento:**\n- Si se especifica currencyCode: retorna balance para esa moneda específica\n- Sin currencyCode: retorna balances de todas las monedas disponibles para el comerciante\n\n**Información retornada:**\n- Balance disponible para desembolsos\n- Balance pendiente (en procesamiento)\n- Balance total\n- Ultima actualización\n","operationId":"getAccountBalance","parameters":[{"name":"currencyCode","in":"query","description":"Código de moneda ISO 4217 (3 caracteres).\n- Si se especifica: filtra balance por esa moneda\n- Si no se especifica: retorna todas las monedas disponibles\n- Este valor se incluye en el cálculo de la firma HMAC-SHA256\n","required":false,"schema":{"maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$","type":"string"}}],"responses":{"200":{"description":"Balance obtenido exitosamente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountBalanceResponseDto"}}}},"401":{"description":"No autorizado. Puede ocurrir por:\n- Headers de seguridad faltantes (x-api-key, x-api-secret, x-signature)\n- Credenciales inválidas en el servicio de seguridad\n- Firma HMAC-SHA256 incorrecta\n","content":{"application/json":{}}},"500":{"description":"Error interno del servidor. Error en el servicio de balance o comunicación con servicios externos.","content":{"application/json":{}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://readme.streampayments.io/readme/api-reference/payout-api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.