> 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/documentation/products/dispersion-de-pagos.md).

# Dispersión de Pagos

## Webhook de Notificacion de estado final:

Una vez que se detecte que la transacción ha completado el proceso operativo (autorizada, expirada, denegada o fallida), el estado de la transacción será notificado al comercio a través de una URL webhook mediante una petición POST.

Por lo tanto, el comercio debe proporcionar un endpoint público HTTPS que acepte parámetros usando HTTP POST.

Los siguientes campos del cuerpo y cabaceras de la solicitud deben ser preparados y expuestos por el comercio en su webhook POST:

**Headers:**

<table><thead><tr><th width="279">Field</th><th width="128">Data Type</th><th width="143">Condition</th><th>Description</th></tr></thead><tbody><tr><td>x-signature</td><td>String</td><td>Mandatorio</td><td>Generación de firma de según la siguiente especificación: <a href="https://app.gitbook.com/o/83gIUIYTCm8MuWTqkip6/s/XK5LUrzl1Q87Hje8ayDc/~/changes/75/readme/documentation/gettings-started/configuracion#autenticacion-hmac-sha256-unificada">https://app.gitbook.com/o/83gIUIYTCm8MuWTqkip6/s/XK5LUrzl1Q87Hje8ayDc/~/changes/75/readme/documentation/gettings-started/configuracion#autenticacion-hmac-sha256-unificada</a></td></tr><tr><td>x-timestamp</td><td>String</td><td>Mandatorio</td><td>Fecha y hora actual en que se envía la notificación</td></tr></tbody></table>

**Body:**

<table><thead><tr><th width="279">Field</th><th width="128">Data Type</th><th width="143">Condition</th><th>Description</th></tr></thead><tbody><tr><td>product</td><td>String</td><td>Mandatorio</td><td>Constante "payout"</td></tr><tr><td>identifier</td><td>String</td><td>Mandatorio</td><td>Identificador de la operacion de Streampayments</td></tr><tr><td>externalIdentifier</td><td>String</td><td>Mandatorio</td><td>ID de la operación del comercio.</td></tr><tr><td>amount</td><td>String</td><td>Mandatorio</td><td>Monto de la transacción.</td></tr><tr><td>currency</td><td>String</td><td>Mandatorio</td><td><p>Moneda de la transacción </p><p>(ISO Alpha 3).</p></td></tr><tr><td>statusCode</td><td>String</td><td>Mandatorio</td><td>Código del estado de la transacción.</td></tr><tr><td>statusDescription</td><td>String</td><td>Mandatorio</td><td>Descripción del estado de la transacción.</td></tr><tr><td>errorDetails</td><td>Object</td><td>Opcional</td><td>Detalle del error.</td></tr><tr><td>errorDetails.code</td><td>String</td><td>Opcional</td><td>Código del error.</td></tr><tr><td>errorDetails.message</td><td>String</td><td>Opcional</td><td>Mensaje del error.</td></tr><tr><td>metaData</td><td>List&#x3C;Object></td><td>Opcional</td><td>Información metadata.</td></tr></tbody></table>

**Campos del Objeto metadata:**

<table><thead><tr><th width="155">Field</th><th width="128">Data Type</th><th width="143">Condition</th><th>Description</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>Mandatorio</td><td>Código del atributo</td></tr><tr><td>value</td><td>String</td><td>Mandatorio</td><td>Valor del atributo</td></tr></tbody></table>

### **Formato de Notificación**

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "product": "payout",
    "identifier": "_Om8R8UeR4LSrjcMVqZr4",
    "externalIdentifier": "2012031",
    "amount": "100.00",
    "currency": "PEN",
    "statusCode": "3000",
    "statusDescription": "AUTHORIZED"
}
</code></pre>

#### **Diagrama de Estados PAYOUT** <a href="#diagrama-de-estados-payout" id="diagrama-de-estados-payout"></a>

<figure><img src="/files/vr646YLaZ3WOSt7fYmiq" alt=""><figcaption></figcaption></figure>

#### **Estados de Transacción PAYOUT** <a href="#estados-de-transaccion-payout" id="estados-de-transaccion-payout"></a>

| Código | Estado       | Descripción                                    |
| ------ | ------------ | ---------------------------------------------- |
| 1000   | `PENDING`    | Transacción recibida y en validación           |
| 1100   | `CANCELLED`  | Transacción cancelada                          |
| 1200   | `REJECTED`   | Transacción rechazada por validaciones         |
| 2200   | `PROCESSING` | Transacción aprobada, en proceso bancario      |
| 3000   | `AUTHORIZED` | Transferencia exitosa                          |
| 4000   | `DENIED`     | Transferencia rechazada por entidad financiera |

***

### Catálogo de Errores PAYOUT <a href="#catalogo-de-errores-payout" id="catalogo-de-errores-payout"></a>

#### **Códigos de Error en la notificación** <a href="#codigos-de-error-con-http-status" id="codigos-de-error-con-http-status"></a>

| Código de error | Descripción                     |
| --------------- | ------------------------------- |
| E001            | Incorrect account data          |
| E002            | Invalid amount                  |
| E003            | Missing required data           |
| E004            | Duplicate transaction           |
| E005            | Authentication error            |
| E006            | Invalid request format          |
| E007            | Account not available           |
| E008            | Operation not allowed           |
| E009            | Beneficiary not found           |
| E010            | Service temporarily unavailable |
| E011            | Internal system error           |
| E012            | Timeout occurred                |
| E013            | Insufficient balance            |
| E014            | Fraud rules rejection           |

#### **Códigos de Error al crear dispersion** <a href="#codigos-de-error-con-http-status" id="codigos-de-error-con-http-status"></a>

| Código Error      | HTTP Status | Descripción                                                | Solución                                                       |
| ----------------- | ----------- | ---------------------------------------------------------- | -------------------------------------------------------------- |
| `API-PAYOUT-0001` | `400`       | Error de solicitud inválida - Datos de entrada incorrectos | Verificar formato y completitud de todos los campos requeridos |
| `API-PAYOUT-0002` | `401`       | No autorizado - Credenciales o firma inválida              | Verificar generación de firma HMAC y credenciales API          |
| `API-PAYOUT-0003` | `400`       | Desembolso no encontrado                                   | Verificar que el transactionId sea válido y exista             |
| `API-PAYOUT-0099` | `500`       | Error interno del servidor                                 | Reintentar la solicitud más tarde                              |

#### **Errores de Validación de Datos** <a href="#errores-de-validacion-de-datos" id="errores-de-validacion-de-datos"></a>

<table><thead><tr><th>Descripción</th><th>Campo Afectado</th><th>Solución</th><th data-hidden>Error</th></tr></thead><tbody><tr><td>Payout already exists</td><td>transactionId</td><td>Enviar un identificador de transacción único que no haya sido utilizado previamente</td><td></td></tr><tr><td>Processing type configuration not found</td><td><code>recipientType</code></td><td>Usar solo <code>BANK</code> o <code>WALLET</code></td><td><code>PROCESSING_TYPE_NOT_FOUND</code></td></tr><tr><td>Institution not supported</td><td><code>bankCode</code>/<code>walletCode</code></td><td>Usar códigos del catálogo de instituciones</td><td><code>UNSUPPORTED_INSTITUTION</code></td></tr><tr><td>Phone number cannot be empty</td><td><code>recipientPhone</code></td><td>Proporcionar teléfono para transferencias WALLET</td><td><code>EMPTY_PHONE_NUMBER</code></td></tr><tr><td>Interbank account number cannot be empty</td><td><code>recipientAccount</code></td><td>Proporcionar CCI de 20 dígitos para transferencias BANK</td><td><code>EMPTY_CCI_NUMBER</code></td></tr><tr><td>Account type not supported</td><td><code>recipientType</code></td><td>Usar <code>BANK</code> para CCI o <code>WALLET</code> para billeteras</td><td><code>UNSUPPORTED_ACCOUNT_TYPE</code></td></tr><tr><td>Account number does not meet the format</td><td><code>recipientAccount</code></td><td>CCI debe tener exactamente 20 dígitos numéricos</td><td><code>INVALID_ACCOUNT_NUMBER_FORMAT</code></td></tr><tr><td>Currency not supported</td><td><code>currencyCode</code></td><td>Usar únicamente <code>PEN</code></td><td><code>UNSUPPORTED_CURRENCY</code></td></tr><tr><td>Amount does not meet the currency format</td><td><code>amount</code></td><td>Formato: "123.45" (máximo 2 decimales)</td><td><code>INVALID_AMOUNT_FORMAT</code></td></tr><tr><td>Document type not supported</td><td><code>documentType</code></td><td>Usar códigos del catálogo de tipos de documento</td><td><code>UNSUPPORTED_DOCUMENT_TYPE</code></td></tr><tr><td>Document number does not meet the format</td><td><code>documentNumber</code></td><td>DNI: 8 dígitos, CE: 12 caracteres alfanuméricos</td><td><code>INVALID_DOCUMENT_NUMBER_FORMAT</code></td></tr><tr><td>Disbursement processor not configured</td><td>Configuración</td><td>Contactar soporte para configurar procesador</td><td><code>UNSUPPORTED_PROCESSOR</code></td></tr></tbody></table>

***

### &#x20;Catálogos de Referencia PAYOUT <a href="#catalogos-de-referencia-payout" id="catalogos-de-referencia-payout"></a>

### **Tipos de Transferencia** <a href="#catalogos-de-referencia-payout" id="catalogos-de-referencia-payout"></a>

| Código   | Descripción            | Uso                   |
| -------- | ---------------------- | --------------------- |
| `BANK`   | Transferencia Bancaria | Para cuentas CCI      |
| `WALLET` | Billetera Digital      | Para YAPE, PLIN, etc. |

### **Tipos de cuenta** <a href="#catalogos-de-referencia-payout" id="catalogos-de-referencia-payout"></a>

| Código | Descripción       |
| ------ | ----------------- |
| AT001  | Cuenta de ahorros |
| AT002  | Cuenta corriente  |


---

# 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/documentation/products/dispersion-de-pagos.md?ask=<question>
```

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.