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,
"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"
}
Crear dispersión
Endpoint para registrar una dispersión en el sistema de OnePay.
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,
"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"
}
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.
string
required
Moneda de la dispersión.
string
required
Método de dispersión.
Ejemplos de uso
- curl
- JavaScript
- Python
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 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_xxx',
'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_xxx",
"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).date
Fecha de programación si existe.
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,
"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"
}
Was this page helpful?
⌘I