> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear dispersión

> Endpoint para registrar una dispersión en el sistema de OnePay.

### Headers

<ParamField header="x-idempotency" type="string" required placeholder="Token único para garantizar la idempotencia de la petición">
  Token único para garantizar la idempotencia de la petición
</ParamField>

### Body

<ParamField body="amount" type="number" required placeholder="100000">
  Monto de la dispersión.
</ParamField>

<ParamField body="account_id" type="string" required placeholder="9d0ac58c-2226-4f1c-b305-15e6dc3b47f6">
  ID de la cuenta bancaria registrada. [Aprende a registrar cuentas](/client/accounts/create).
</ParamField>

<ParamField body="customer_id" type="string" required placeholder="9dd4158b-0e45-42bc-b56f-a4c1f856814d">
  ID del cliente beneficiario. [Crea primero el cliente](/client/customers/create).
</ParamField>

<ParamField body="description" type="string" placeholder="Dispersión de prueba">
  Descripción de la dispersión.
</ParamField>

<ParamField body="external_id" type="string" placeholder="Identificador externo de la dispersión.">
  Identificador externo de la dispersión.
</ParamField>

<ParamField body="currency" required type="string" placeholder="COP">
  Moneda de la dispersión.
</ParamField>

<ParamField body="method" required type="string" placeholder="ACH, TURBO">
  Método de dispersión.
</ParamField>

### Ejemplos de uso

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://api.onepay.la/v1/cashouts \
      -X POST \
      -H "Authorization: Bearer sk_test_xxx" \
      -H "Content-Type: application/json" \
      -H "x-idempotency: cashout-001" \
      -d '{
        "amount": 1000000,
        "currency": "COP",
        "customer_id": "9b7c5f38-b2b5-4b0d-8e4c-458192e88eae",
        "account_id": "9d0ac58c-2226-4f1c-b305-15e6dc3b47f6",
        "description": "Pago de nómina",
        "method": "ACH",
        "external_id": "PAYROLL-2391"
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```ts theme={null}
    const payload = {
      amount: 1000000,
      currency: 'COP',
      customer_id: '9b7c5f38-b2b5-4b0d-8e4c-458192e88eae',
      account_id: '9d0ac58c-2226-4f1c-b305-15e6dc3b47f6',
      description: 'Pago de nómina',
      method: 'ACH',
      external_id: 'PAYROLL-2391'
    };

    await fetch('https://api.onepay.la/v1/cashouts', {
      method: 'POST',
      headers: {
        Authorization: 'Bearer sk_test_xxx',
        'Content-Type': 'application/json',
        'x-idempotency': 'cashout-001'
      },
      body: JSON.stringify(payload)
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    payload = {
        "amount": 1000000,
        "currency": "COP",
        "customer_id": "9b7c5f38-b2b5-4b0d-8e4c-458192e88eae",
        "account_id": "9d0ac58c-2226-4f1c-b305-15e6dc3b47f6",
        "description": "Pago de nómina",
        "method": "ACH",
        "external_id": "PAYROLL-2391"
    }

    response = requests.post(
        "https://api.onepay.la/v1/cashouts",
        headers={
            "Authorization": "Bearer sk_test_xxx",
            "x-idempotency": "cashout-001"
        },
        json=payload,
        timeout=15
    )
    response.raise_for_status()
    print(response.json())
    ```
  </Tab>
</Tabs>

### Response

<ResponseField name="id" type="string">
  Identificador único de la dispersión.
</ResponseField>

<ResponseField name="customer_id" type="string">
  Cliente beneficiario.
</ResponseField>

<ResponseField name="account_id" type="string">
  Cuenta bancaria donde se enviará el dinero.
</ResponseField>

<ResponseField name="amount" type="number">
  Monto en centavos.
</ResponseField>

<ResponseField name="currency" type="string">
  Moneda de la dispersión.
</ResponseField>

<ResponseField name="status" type="string">
  Estado actual (`pending`, `processing`, `processed`, `failed`).
</ResponseField>

<ResponseField name="method" type="string">
  Canal utilizado (`ACH`, `TURBO`).
</ResponseField>

<ResponseField name="scheduled_at" type="date">
  Fecha de programación si existe.
</ResponseField>

<ResponseField name="external_id" type="string">
  Referencia propia que enviaste en la creación.
</ResponseField>

<ResponseField name="created_at" type="date">
  Fecha de creación del registro.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
     "id":"9d44ce43-a227-4566-b107-5a6bc01cbcdf",
     "customer_id":"9b7c5f38-b2b5-4b0d-8e4c-458192e88eae",
     "account_id":"9d0ac58c-2226-4f1c-b305-15e6dc3b47f6",
     "is_test":false,
     "amount":1000,
     "status":"processed",
     "scheduled_at":null,
     "created_at":"2024-10-17T18:07:18.000000Z",
     "external_id":null,
     "method":"ACH"
  }
  ```

  ```json 422 theme={null}
  {
     "message":"El campo customer id es obligatorio. (y 4 errores más)",
     "code":10001,
     "code_name":"validation_error",
     "errors":{
        "customer_id":[
           "El campo customer id es obligatorio."
        ],
        "account_id":[
           "El campo account id es obligatorio."
        ],
        "amount":[
           "El campo cantidad es obligatorio."
        ],
        "currency":[
           "El campo currency es obligatorio."
        ],
        "method":[
           "El campo method es obligatorio."
        ]
     }
  }
  ```

  ```json 409 theme={null}
  {
    "message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
    "code": 10003,
    "code_name": "idempotency_error"
  }
  ```
</ResponseExample>