Solicitar dispersión

curl --request POST \
  --url https://api.onepay.la/v1/balances \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency: <x-idempotency>' \
  --data '
{
  "amount": 123,
  "account_id": "<string>",
  "external_id": "<string>"
}
'

import requests

url = "https://api.onepay.la/v1/balances"

payload = {
    "amount": 123,
    "account_id": "<string>",
    "external_id": "<string>"
}
headers = {
    "x-idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({amount: 123, account_id: '<string>', external_id: '<string>'})
};

fetch('https://api.onepay.la/v1/balances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.onepay.la/v1/balances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 123,
    'account_id' => '<string>',
    'external_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-idempotency: <x-idempotency>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.onepay.la/v1/balances"

	payload := strings.NewReader("{\n  \"amount\": 123,\n  \"account_id\": \"<string>\",\n  \"external_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.onepay.la/v1/balances")
  .header("x-idempotency", "<x-idempotency>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 123,\n  \"account_id\": \"<string>\",\n  \"external_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.onepay.la/v1/balances")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-idempotency"] = '<x-idempotency>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 123,\n  \"account_id\": \"<string>\",\n  \"external_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
   "id":"9d44ce43-a227-4566-b107-5a6bc01cbcdf",
   "customer_id":"9b3f1a20-6d51-4a7e-9f2c-1c9f0e4d7b11",
   "account_id":"84cc072e-90e8-33cf-9305-098095fed32f",
   "is_test":false,
   "amount":500000,
   "status":"to_process",
   "scheduled_at":null,
   "created_at":"2026-08-19T14:32:10.000000Z",
   "external_id":"TESORERIA-2026-08-19",
   "description":"Envío de fondos OnePay a cuenta.",
   "reference":"Deposito a cuenta propia",
   "method":"ACH",
   "discount_to_destination":false
}

{
  "message": "Tu saldo está vacío, necesitas depositar fondos para continuar con la operación.",
  "code": 10500,
  "code_name": "balance_is_empty"
}

{
  "message": "No tienes fondos suficientes para hacer está operación.",
  "code": 10501,
  "code_name": "insufficient_funds"
}

{
  "message": "No se encontró una cuenta bancaria registrada. Debes registrar una cuenta bancaria antes de solicitar una dispersión de balance.",
  "code": 10809,
  "code_name": "company_account_not_found"
}

{
  "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"
}

POST

balances

Solicitar dispersión

curl --request POST \
  --url https://api.onepay.la/v1/balances \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency: <x-idempotency>' \
  --data '
{
  "amount": 123,
  "account_id": "<string>",
  "external_id": "<string>"
}
'

import requests

url = "https://api.onepay.la/v1/balances"

payload = {
    "amount": 123,
    "account_id": "<string>",
    "external_id": "<string>"
}
headers = {
    "x-idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({amount: 123, account_id: '<string>', external_id: '<string>'})
};

fetch('https://api.onepay.la/v1/balances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.onepay.la/v1/balances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 123,
    'account_id' => '<string>',
    'external_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-idempotency: <x-idempotency>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.onepay.la/v1/balances"

	payload := strings.NewReader("{\n  \"amount\": 123,\n  \"account_id\": \"<string>\",\n  \"external_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.onepay.la/v1/balances")
  .header("x-idempotency", "<x-idempotency>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 123,\n  \"account_id\": \"<string>\",\n  \"external_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.onepay.la/v1/balances")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-idempotency"] = '<x-idempotency>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 123,\n  \"account_id\": \"<string>\",\n  \"external_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
   "id":"9d44ce43-a227-4566-b107-5a6bc01cbcdf",
   "customer_id":"9b3f1a20-6d51-4a7e-9f2c-1c9f0e4d7b11",
   "account_id":"84cc072e-90e8-33cf-9305-098095fed32f",
   "is_test":false,
   "amount":500000,
   "status":"to_process",
   "scheduled_at":null,
   "created_at":"2026-08-19T14:32:10.000000Z",
   "external_id":"TESORERIA-2026-08-19",
   "description":"Envío de fondos OnePay a cuenta.",
   "reference":"Deposito a cuenta propia",
   "method":"ACH",
   "discount_to_destination":false
}

{
  "message": "Tu saldo está vacío, necesitas depositar fondos para continuar con la operación.",
  "code": 10500,
  "code_name": "balance_is_empty"
}

{
  "message": "No tienes fondos suficientes para hacer está operación.",
  "code": 10501,
  "code_name": "insufficient_funds"
}

{
  "message": "No se encontró una cuenta bancaria registrada. Debes registrar una cuenta bancaria antes de solicitar una dispersión de balance.",
  "code": 10809,
  "code_name": "company_account_not_found"
}

{
  "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"
}

Dispersa el balance de tu cuenta OnePay a una cuenta bancaria registrada de tu empresa.

Cambio de contrato (agosto de 2026). Este endpoint respondía 204 No Content. Ahora responde 201 con la dispersión creada, para que tengas el id con el que casar los webhooks cashout.*. Si tu integración valida el status exacto 204, actualízala antes de la fecha de despliegue.

Ambos parámetros son opcionales:

Si no envías amount, se dispersa el balance completo.
Si no envías account_id, se usa la cuenta bancaria principal (fundable) de tu empresa.

La cuenta bancaria debe pertenecer directamente a tu empresa. Cuentas de tipo PSE no son elegibles como cuenta principal. Si envías un account_id que pertenece a un cliente o invitado, recibirás un error company_account_not_found.

Headers

string

required

Token único para garantizar la idempotencia de la petición

Body

number

Monto a dispersar en pesos (COP). Mínimo $10.000. Si no se envía, se dispersa el balance completo.

string

ID de la cuenta bancaria destino. Debe pertenecer a tu empresa (no a un cliente o invitado). Si no se envía, se usa la cuenta principal. Aprende a registrar cuentas.

string

Identificador propio de la dispersión, máximo 100 caracteres. Se devuelve en la respuesta y en todos los webhooks cashout.* de esta dispersión, para que puedas cruzarla contra tu sistema.

Ejemplos de uso

Balance completo
Monto específico
Cuenta específica
Con external_id

curl https://api.onepay.la/v1/balances \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json"

curl https://api.onepay.la/v1/balances \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 500000}'

curl https://api.onepay.la/v1/balances \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 500000, "account_id": "84cc072e-90e8-33cf-9305-098095fed32f"}'

curl https://api.onepay.la/v1/balances \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 500000, "external_id": "TESORERIA-2026-08-19"}'

Response

La respuesta es la línea de dispersión creada, con las mismas llaves que viajan después en los webhooks cashout.*. Guarda el id (o envía tu propio external_id) para poder casar esos eventos con la solicitud que hiciste.

string

Identificador único de la dispersión. Es el mismo id que llega en los webhooks cashout.*.

string

En esta dispersión es el ID de tu empresa, porque el dinero va a una cuenta propia y no a un cliente. En POST /cashouts en cambio es el cliente beneficiario.

string

Cuenta bancaria de tu empresa a la que se envió el dinero.

number

Monto dispersado en pesos (COP), no en centavos.

string

Estado inicial de la dispersión (normalmente to_process). Su evolución llega por webhook.

boolean

true si la dispersión se creó con una llave de pruebas (sk_test_xxx).

date | null

Fecha de programación. En esta dispersión siempre llega null: se procesa de inmediato.

string

Concepto de la operación. En dispersiones a cuenta propia siempre es Envío de fondos OnePay a cuenta..

boolean

true si las comisiones se descuentan del monto que llega a la cuenta destino.

string

Canal utilizado (ACH, TURBO).

string | null

El external_id que enviaste. Llega null si no lo enviaste.

string

Referencia interna de la operación. En dispersiones a cuenta propia siempre es Deposito a cuenta propia.

date

Fecha de creación del registro.

Errores

Código	Nombre	HTTP	Descripción
10500	`balance_is_empty`	401	El saldo está vacío
10501	`insufficient_funds`	401	El monto solicitado supera el balance disponible
10809	`company_account_not_found`	422	No se encontró cuenta bancaria o no pertenece a tu empresa

{
   "id":"9d44ce43-a227-4566-b107-5a6bc01cbcdf",
   "customer_id":"9b3f1a20-6d51-4a7e-9f2c-1c9f0e4d7b11",
   "account_id":"84cc072e-90e8-33cf-9305-098095fed32f",
   "is_test":false,
   "amount":500000,
   "status":"to_process",
   "scheduled_at":null,
   "created_at":"2026-08-19T14:32:10.000000Z",
   "external_id":"TESORERIA-2026-08-19",
   "description":"Envío de fondos OnePay a cuenta.",
   "reference":"Deposito a cuenta propia",
   "method":"ACH",
   "discount_to_destination":false
}

{
  "message": "Tu saldo está vacío, necesitas depositar fondos para continuar con la operación.",
  "code": 10500,
  "code_name": "balance_is_empty"
}

{
  "message": "No tienes fondos suficientes para hacer está operación.",
  "code": 10501,
  "code_name": "insufficient_funds"
}

{
  "message": "No se encontró una cuenta bancaria registrada. Debes registrar una cuenta bancaria antes de solicitar una dispersión de balance.",
  "code": 10809,
  "code_name": "company_account_not_found"
}

{
  "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"
}

API

Empresas

Métodos de pago

Recaudo

Productos

Facturación

Balances

Webhooks

Fintech as a service

Solicitar dispersión

Headers

Body

Ejemplos de uso

Response

Errores

​Headers

​Body

​Ejemplos de uso

​Response

​Errores

Headers

Body

Ejemplos de uso

Response

Errores