> ## 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.

# Saldo OnePay de otra empresa

> Registra el saldo de una empresa aliada como una cuenta, para dividir cobros hacia ella.

Si divides tus cobros con otra empresa que también usa OnePay —un marketplace repartiendo con sus
vendedores, una plataforma con sus comercios— el dinero puede caer directo en el saldo de esa
empresa, sin pasar por un banco.

Para eso registras su saldo **como una cuenta más de un cliente**. El banco es OnePay y, como número
de cuenta, va el identificador del saldo que la otra empresa te comparte —igual que te compartiría
el número de una cuenta bancaria.

<Info>
  El identificador del saldo lo obtiene la empresa aliada desde su panel, en **Saldos**. No es un
  dato que puedas consultar por API: te lo tiene que dar ella, como cualquier número de cuenta.
</Info>

## 1. Registra a la empresa aliada como cliente

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.onepay.la/v1/customers \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "first_name": "Aliado",
      "last_name": "SAS",
      "user_type": "company",
      "document_type": "NIT",
      "document_number": "900123456",
      "email": "tesoreria@aliado.com",
      "phone": "+573001112233"
    }'
  ```
</CodeGroup>

Guarda el `id` que devuelve: es el `customer_id` de los pasos siguientes.

<Note>
  Cuando `user_type` es `company`, el `document_type` debe ser `NIT` o `RUT`.
</Note>

## 2. Registra su saldo como cuenta

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.onepay.la/v1/accounts \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
      "bank_id": "9c479f02-6664-438d-83de-1103d7880896",
      "subtype": "WALLET",
      "account_number": "01935679-361b-7160-aeba-7651f0bd4181"
    }'
  ```
</CodeGroup>

<ParamField body="subtype" type="string" required placeholder="WALLET">
  `WALLET` identifica una cuenta de saldo OnePay.
</ParamField>

<ParamField body="bank_id" type="string" required placeholder="9c479f02-6664-438d-83de-1103d7880896">
  El identificador del banco **ONE BANK**. Es siempre el mismo y también lo devuelve
  [listar bancos](/client/accounts/list-banks).
</ParamField>

<ParamField body="account_number" type="string" required placeholder="01935679-361b-7160-aeba-7651f0bd4181">
  El identificador del saldo de la empresa aliada. Se acepta con guiones o sin ellos.
</ParamField>

Guarda el `id` de la cuenta: es el `account_id` del split.

### Qué se valida

El saldo destino tiene que existir, pertenecer a una empresa, estar en el mismo entorno que tu
llave y no ser uno tuyo. Si algo no cuadra, la respuesta es un `422` sobre `account_number`.

<Warning>
  Un identificador inexistente y uno de otro entorno devuelven el mismo mensaje a propósito, para
  que este campo no sirva para averiguar saldos ajenos probando identificadores. Si te rechaza uno
  que crees correcto, revisa primero que tu llave y el saldo sean ambos de pruebas o ambos de
  producción.
</Warning>

## 3. Divide el cobro

A partir de acá no hay nada especial: es el mismo split que harías hacia cualquier cliente con
cuenta bancaria.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.onepay.la/v1/payments \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 100000,
      "splits": [
        {
          "customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
          "account_id": "9e1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
          "split_type": "percentage",
          "split_value": 10,
          "description": "Comisión marketplace"
        }
      ]
    }'
  ```
</CodeGroup>

El registro de los pasos 1 y 2 se hace **una sola vez** por empresa aliada. Después reutilizas ese
par `customer_id` + `account_id` en todos los cobros.

## Cuándo se acredita

Cuando el cobro queda aprobado, el monto se transfiere del saldo de tu empresa al de la aliada. Es
un movimiento interno: llega al instante, sin pasar por un banco.

Si el cobro se vence, se rechaza o nunca se paga, el split no se ejecuta.

## Migrar desde `to_company_wallet`

<Warning>
  El campo `splits[].to_company_wallet` queda **obsoleto**. Si tu integración lo usa, migra al flujo
  de esta página.
</Warning>

Antes había que mandar el identificador del saldo ajeno **en cada cobro**:

```json theme={null}
{
  "splits": [
    {
      "to_company_wallet": true,
      "account_id": "01935679-361b-7160-aeba-7651f0bd4181",
      "split_type": "percentage",
      "split_value": 10,
      "description": "Comisión marketplace"
    }
  ]
}
```

Con el flujo nuevo ese identificador se registra una vez y desaparece del payload del cobro. Ambas
formas funcionan durante la transición; te avisaremos con antelación antes de retirar la anterior.