Crear dispersión

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

import requests

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

payload = {
    "amount": 123,
    "account_id": "<string>",
    "customer_id": "<string>",
    "description": "<string>",
    "reference": "<string>",
    "external_id": "<string>",
    "currency": "<string>",
    "method": "<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>',
    customer_id: '<string>',
    description: '<string>',
    reference: '<string>',
    external_id: '<string>',
    currency: '<string>',
    method: '<string>'
  })
};

fetch('https://api.onepay.la/v1/cashouts', 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/cashouts",
  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>',
    'customer_id' => '<string>',
    'description' => '<string>',
    'reference' => '<string>',
    'external_id' => '<string>',
    'currency' => '<string>',
    'method' => '<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/cashouts"

	payload := strings.NewReader("{\n  \"amount\": 123,\n  \"account_id\": \"<string>\",\n  \"customer_id\": \"<string>\",\n  \"description\": \"<string>\",\n  \"reference\": \"<string>\",\n  \"external_id\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"method\": \"<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/cashouts")
  .header("x-idempotency", "<x-idempotency>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 123,\n  \"account_id\": \"<string>\",\n  \"customer_id\": \"<string>\",\n  \"description\": \"<string>\",\n  \"reference\": \"<string>\",\n  \"external_id\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"method\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"customer_id\": \"<string>\",\n  \"description\": \"<string>\",\n  \"reference\": \"<string>\",\n  \"external_id\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"method\": \"<string>\"\n}"

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

{
   "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,
   "processed_at":null,
   "created_at":"2024-10-17T18:07:18.000000Z",
   "external_id":null,
   "description":"Pago de nómina",
   "reference":"NOM-2026-07",
   "method":"ACH",
   "discount_to_destination":false
}

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

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

{
  "message": "Ya existe una transferencia con este external_id. Solo se puede volver a usar si la anterior falló o se canceló.",
  "code": 41015,
  "code_name": "duplicate_external_id"
}

POST

cashouts

Crear dispersión

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

import requests

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

payload = {
    "amount": 123,
    "account_id": "<string>",
    "customer_id": "<string>",
    "description": "<string>",
    "reference": "<string>",
    "external_id": "<string>",
    "currency": "<string>",
    "method": "<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>',
    customer_id: '<string>',
    description: '<string>',
    reference: '<string>',
    external_id: '<string>',
    currency: '<string>',
    method: '<string>'
  })
};

fetch('https://api.onepay.la/v1/cashouts', 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/cashouts",
  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>',
    'customer_id' => '<string>',
    'description' => '<string>',
    'reference' => '<string>',
    'external_id' => '<string>',
    'currency' => '<string>',
    'method' => '<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/cashouts"

	payload := strings.NewReader("{\n  \"amount\": 123,\n  \"account_id\": \"<string>\",\n  \"customer_id\": \"<string>\",\n  \"description\": \"<string>\",\n  \"reference\": \"<string>\",\n  \"external_id\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"method\": \"<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/cashouts")
  .header("x-idempotency", "<x-idempotency>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 123,\n  \"account_id\": \"<string>\",\n  \"customer_id\": \"<string>\",\n  \"description\": \"<string>\",\n  \"reference\": \"<string>\",\n  \"external_id\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"method\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"customer_id\": \"<string>\",\n  \"description\": \"<string>\",\n  \"reference\": \"<string>\",\n  \"external_id\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"method\": \"<string>\"\n}"

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

{
   "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,
   "processed_at":null,
   "created_at":"2024-10-17T18:07:18.000000Z",
   "external_id":null,
   "description":"Pago de nómina",
   "reference":"NOM-2026-07",
   "method":"ACH",
   "discount_to_destination":false
}

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

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

{
  "message": "Ya existe una transferencia con este external_id. Solo se puede volver a usar si la anterior falló o se canceló.",
  "code": 41015,
  "code_name": "duplicate_external_id"
}

Headers

string

required

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

Body

number

required

Monto de la dispersión en unidades mayores de la moneda, no en centavos. Enviar 100000 dispersa $100.000 COP.

string

required

ID de la cuenta bancaria registrada. Aprende a registrar cuentas.

string

required

ID del cliente beneficiario. Crea primero el cliente.

string

Descripción de la dispersión (entre 10 y 100 caracteres). Alimenta el título que viaja al banco destino y se devuelve en la respuesta y en los webhooks cashout.*.

string

Referencia propia para conciliar (máx. 50 caracteres). Si no la envías, se usa el valor de description como referencia.

string

Concepto de la dispersión, entre 10 y 100 caracteres. Es el texto que viaja al banco como descripción de la transferencia; si lo omites se envía Transferencia de fondos.

Si no envías reference, la descripción también se guarda como referencia. Es el comportamiento histórico del endpoint y se mantiene por compatibilidad.

string

Identificador externo de la dispersión, máximo 100 caracteres. Es el único de los tres que se devuelve en la respuesta.

Si usas el external_id como número de crédito, factura u otro identificador que no se puede pagar dos veces, pide a OnePay activar la unicidad del external_id en tu cuenta. Con ella activa, una dispersión con un external_id que ya tiene otra dispersión de tu empresa en el mismo entorno se rechaza con el error 41015 duplicate_external_id. Las dispersiones failed y cancelled no cuentan: puedes reintentar un desembolso rechazado con el mismo external_id. Las archivadas sí cuentan.

string

required

Moneda de la dispersión.

string

required

Método de dispersión:

ACH: transferencia bancaria estándar. Es el único método que admite scheduled_at.
TURBO: transferencia en tiempo real.
BREB: se envía únicamente por Bre-B, a la llave que el destinatario tenga asociada a la cuenta. Si la cuenta no tiene una llave Bre-B activa o Bre-B rechaza el envío, la dispersión queda en failed y el saldo se devuelve: no se reintenta por otro método. El monto máximo es de 10.000.000 COP por dispersión; por encima, la solicitud se rechaza con un error de validación. También se acepta BRE-B, que es como la respuesta devuelve este método. Si Bre-B no responde en el momento del envío, la dispersión no falla: sigue pendiente y se reintenta por Bre-B durante un máximo de 3 horas.

Ejemplos de uso

curl
JavaScript
Python

curl https://api.onepay.la/v1/cashouts \
  -X POST \
  -H "Authorization: Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi" \
  -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 julio",
    "reference": "FACT-2026-001",
    "method": "ACH",
    "external_id": "PAYROLL-2391"
  }'

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 julio',
  reference: 'FACT-2026-001',
  method: 'ACH',
  external_id: 'PAYROLL-2391'
};

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

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 julio",
    "reference": "FACT-2026-001",
    "method": "ACH",
    "external_id": "PAYROLL-2391"
}

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

Response

string

Identificador único de la dispersión.

string

Cliente beneficiario.

string

Cuenta bancaria donde se enviará el dinero.

number

Monto en unidades mayores de la moneda, no en centavos.

string

Moneda de la dispersión.

string

Estado actual (pending, processing, processed, failed).

string

Canal utilizado (ACH, TURBO, BRE-B). Una dispersión creada con BREB se devuelve como BRE-B.

date

Fecha de programación si existe.

date | null

Fecha en que la dispersión fue procesada. null mientras no se procese.

string

Identificador externo que enviaste en la creación.

string | null

Descripción que enviaste en la creación.

string | null

Referencia de conciliación. Si no enviaste reference, aquí llega el valor de description.

date

Fecha de creación del registro.

{
   "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,
   "processed_at":null,
   "created_at":"2024-10-17T18:07:18.000000Z",
   "external_id":null,
   "description":"Pago de nómina",
   "reference":"NOM-2026-07",
   "method":"ACH",
   "discount_to_destination":false
}

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

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

{
  "message": "Ya existe una transferencia con este external_id. Solo se puede volver a usar si la anterior falló o se canceló.",
  "code": 41015,
  "code_name": "duplicate_external_id"
}

API

Empresas

Métodos de pago

Recaudo

Productos

Facturación

Balances

Webhooks

Fintech as a service

Crear dispersión

Headers

Body

Ejemplos de uso

Response

​Headers

​Body

​Ejemplos de uso

​Response

Headers

Body

Ejemplos de uso

Response