Crear un pago PayOUT

PayOUT permite que un merchant envíe pagos a beneficiarios mediante Orkestral. La plataforma valida la solicitud, envía el pago al Proveedor de Servicios de Pago (PSP) informado y acompaña la transacción hasta su estado final.

Antes de comenzar

Necesitas:

• una cuenta activa en Orkestral;
• un PSP compatible con PayOUT registrado y configurado;
• un token OAuth/JWT;
• el UUID del merchant (merchantId);
• una URL HTTPS pública para recibir notificaciones;
• validar la identificación y los datos bancarios del beneficiario.

Ambientes

Ambiente	URL base
QAS	https://api-qas.orkestralpay.com.br

Solicita al equipo de Orkestral la URL y las credenciales de producción. No reutilices tokens, credenciales de PSP ni datos de beneficiarios entre ambientes.

Autenticación

Envía el token y la dirección IP de origen en los headers:

Authorization: Bearer <access_token>
Content-Type: application/json
IP: <dirección_ip_de_origen>

Conserva los tokens y las credenciales únicamente en servicios backend. Nunca los expongas en el frontend, repositorios o logs.

Endpoint

POST /transaction/payout/{merchantId}

El campo psp selecciona el proveedor. A diferencia de PayIN, esta selección no se realiza mediante un flujo de pago.

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
transaction_id	UUID	Sí	Identificador único definido por el merchant.
amount	entero	Sí	Valor positivo en la unidad menor. Ej.: 100 = 1,00.
currency	string	Sí	Código de moneda en mayúsculas.
name	string	Sí	Nombre del beneficiario.
last_name	string	Sí	Apellido del beneficiario.
email	string	Condicional	Correo del beneficiario, requerido por algunos PSP.
birth_date	string	Condicional	Fecha de nacimiento en formato AAAA-MM-DD.
document	string	Sí	Número de documento del beneficiario.
document_type	string	Sí	Tipo de documento aceptado por el país y el PSP.
bank_name	string	Condicional	Nombre del banco.
bank_code	string	Condicional	Código del banco.
agency_code	entero	Condicional	Código de la sucursal.
agency_digit	entero	Condicional	Dígito de la sucursal.
account_code	string	Condicional	Número de cuenta.
account_digit	string	Condicional	Dígito de la cuenta.
account_type	string	Condicional	Tipo de cuenta aceptado por el PSP.
psp	string	Sí	Kushki, Payvalida, WePayments o PayU.
pix_key	string	Condicional	Clave PIX. Al informarla, el pago se procesa como PIX.

Los campos condicionales dependen del PSP, el país y el método. Confirma el catálogo de bancos habilitado para tu contrato antes de enviar un pago.

Transferencia bancaria

Para crear una transferencia, omite pix_key y envía los datos bancarios requeridos por el PSP:

curl --request POST \
  --url "https://api-qas.orkestralpay.com.br/transaction/payout/<merchantId>" \
  --header "Authorization: Bearer <access_token>" \
  --header "Content-Type: application/json" \
  --header "IP: 192.0.2.10" \
  --data '{
    "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
    "amount": 10000,
    "currency": "COP",
    "name": "María",
    "last_name": "García",
    "email": "maria.garcia@example.com",
    "birth_date": "1990-01-01",
    "document": "123456789",
    "document_type": "CC",
    "bank_name": "BANCOLOMBIA",
    "bank_code": "000007",
    "agency_code": 1234,
    "agency_digit": 5,
    "account_code": "987654321",
    "account_digit": "0",
    "account_type": "CA",
    "psp": "Kushki"
  }'

Reemplaza identificadores, datos del beneficiario, banco, IP y credenciales con los valores de tu ambiente.

PIX

PayOUT mediante PIX está disponible con WePayments. Envía una pix_key válida; los campos bancarios pueden omitirse:

{
  "transaction_id": "123e4567-e89b-12d3-a456-426614174001",
  "amount": 10000,
  "currency": "BRL",
  "name": "João",
  "last_name": "Silva",
  "email": "joao.silva@example.com",
  "document": "52998224725",
  "document_type": "CPF",
  "psp": "WePayments",
  "pix_key": "joao.silva@example.com"
}

precaución

No envíes una clave PIX de producción durante las pruebas. Utiliza solamente beneficiarios y claves proporcionados para QAS.

Reglas por PSP

PSP	Países y monedas de referencia	Documentos principales	Método y reglas principales
Kushki	CO/COP, CL/CLP o UF, EC/USD, PE/PEN o USD, MX/MXN	CC, NIT, CE, TI, PP, RUC, CURP, RFC, RUT, DNI, PAS, CI	Transferencia; requiere banco, cuenta y tipo de cuenta compatibles con el país.
Payvalida	CO/COP, GT/GTQ, PE/PEN	CO: CC, CE, PS, TI; GT: DPI; PE: DNI, CE	Transferencia; requiere email, banco, número y tipo de cuenta.
WePayments	BR/BRL	CPF, CNPJ	PIX o transferencia; el documento debe ser válido. La transferencia requiere todos los datos bancarios.
PayU	CO/COP	Tipos aceptados por el contrato PayU	Transferencia; requiere birth_date, bank_code, account_code y account_type.

Tipos de cuenta

PSP	Valores
Kushki	CC, CA, CB, TD, NC, CV, DE, CM, según el país
Payvalida	Colombia y Perú: Ahorro, Corriente; Guatemala: Ahorro, Monetaria
WePayments	Usa el valor habilitado en el contrato, como CHECKING o SAVINGS; confirma el catálogo con el equipo de Orkestral
PayU	Usa el tipo de cuenta aceptado por la configuración PayU del merchant

Para Kushki en Perú, las cuentas del banco 002 usan 13 dígitos para CC y 14 para CA; las cuentas de otros bancos usan 20 dígitos. Para PayU, bank_code debe ser un código bancario colombiano habilitado. Solicita al equipo de Orkestral el catálogo vigente cuando un banco no esté disponible en el ambiente.

Glosario

Cómo completar y probar los datos bancarios

El valor de bank_code no tiene el mismo formato para todos los PSP. Envíalo como string para conservar los ceros a la izquierda.

Kushki

Orkestral envía bank_code a Kushki como BankId. El identificador cambia según el país; no reutilices un código de otro país solo porque los dígitos sean similares.

En Colombia, la referencia del PSP usa seis dígitos. Algunos códigos útiles para QAS son:

bank_code	Institución
000001	Banco de Bogotá
000002	Banco Popular
000007	Bancolombia
000013	BBVA Colombia
000051	Davivienda
000052	Banco AV Villas
000507	Nequi

En Perú, BankId también determina la longitud de account_code:

BankId	account_type	Longitud de account_code
002	CC	13 dígitos
002	CA	14 dígitos
Distinto de 002	Cualquier tipo aceptado	20 dígitos

aviso

El BankId peruano 002 no es el código colombiano 000002 (Banco Popular). El país, la moneda, el documento, el banco, el tipo y la longitud de la cuenta deben pertenecer al mismo escenario de prueba.

Payvalida

Para Payvalida, bank_code recibe el nombre de la institución según el catálogo del país, no un código numérico de Kushki. Usa la grafía exacta devuelta para el merchant. La referencia incluye:

• Perú: BBVA CONTINENTAL, INTERBANK, BCP y SCOTIABANK PERU;
• Guatemala: BAM, BANCO AZTECA, BANCO DE AMERICA CENTRAL, BANCO DE ANTIGUA, BANCO DE CREDITO, BANCO DE DESARROLLO RURAL, BANCO DE GUATEMALA, BANCO DE LOS TRABAJADORES, BANCO FICOHSA, BANCO GYT CONTINENTAL, BANCO INDUSTRIAL, BANCO INMOBILIARIO, BANCO INTERNACIONAL, BANCO INV, BANCO PROMERICA DE GUATEMALA, BANCO PROMERICA, CITIBANK SUCURSAL GUATEMALA, CREDITO HIPOTECARIO NACIONAL y VIVIBANCO;
• Colombia: usa el nombre exacto habilitado en el catálogo del merchant, por ejemplo BANCOLOMBIA, BANCO DE BOGOTA, DAVIVIENDA, NEQUI o BBVA.

Combina el banco con el tipo de cuenta del país: Ahorro o Corriente para Colombia y Perú; Ahorro o Monetaria para Guatemala.

:::tip Lista mínima para QAS

1. Confirma el país, la moneda y el PSP configurados para el merchant.
2. Obtén bank_code del catálogo del mismo ambiente y consérvalo como string.
3. Selecciona un document_type y un account_type aceptados en el país.
4. Para Kushki en Perú, ajusta account_code según el BankId antes de enviar la solicitud.
5. Usa un nuevo transaction_id en cada escenario y acompáñalo hasta un estado final.

:::

El significado de una abreviatura depende del campo en el que se envía. Por ejemplo, CC significa documento de identidad en document_type, pero cuenta corriente en account_type.

Tipos de documento

Abreviatura	Significado
CC	Documento de identidad
NIT	Número de identificación tributaria de Colombia
CE	Cédula de extranjería de Colombia o Perú
TI	Tarjeta de identidad de Colombia
PP	Pasaporte
RUC	Registro tributario de Ecuador o Perú
CURP	Clave Única de Registro de Población de México
RFC	Registro Federal de Contribuyentes de México
RUT	Rol Único Tributario de Chile
DNI	Documento Nacional de Identidad de Perú
PAS	Pasaporte de Perú o Ecuador
CI	Cédula de identidad de Ecuador
PS	Pasaporte, según la nomenclatura de Payvalida en Colombia
DPI	Documento Personal de Identificación de Guatemala
CPF	Registro de Personas Físicas de Brasil
CNPJ	Registro Nacional de Personas Jurídicas de Brasil

Tipos de cuenta Kushki

Abreviatura	Significado
CC	Cuenta corriente en Colombia, Chile y Perú
CA	Cuenta de ahorros en Colombia, Chile y Perú
CB	Cuenta CLABE, solo en México
TD	Tarjeta de débito, solo en México
NC	Número de celular, solo en México
CV	Cuenta vista en Chile
DE	Depósito electrónico en Colombia
CM	Cuenta maestra en Perú

info

Las combinaciones disponibles dependen del contrato y de las credenciales del merchant. Una moneda incluida en la tabla no está necesariamente habilitada para todas las cuentas.

Respuesta exitosa

Una solicitud aceptada devuelve 200 OK. Los campos opcionales dependen del PSP:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "amount": 10000,
  "currency": "COP",
  "payment_method": "TRANSFER",
  "status": "WAITING_PSP_PAYMENT",
  "custom_code": "123e4567-e89b-12d3-a456-426614174000",
  "created_date": "2026-07-31T15:00:00",
  "country": "CO",
  "psp_information": {
    "psp_id": "<psp_uuid>",
    "psp_name": "Kushki"
  },
  "psp_transaction_identification": "<psp_transaction_id>"
}

Guarda id y psp_transaction_identification para la conciliación. El estado WAITING_PSP_PAYMENT indica que el PSP recibió la solicitud; no confirma que el beneficiario ya haya recibido los fondos.

Estados de PayOUT

Estado	Significado
WAITING_PSP_PAYMENT	El pago fue enviado y espera la confirmación del PSP.
SETTLED	El PSP confirmó la liquidación.
DENIED	El PSP rechazó el pago.
ERROR	Ocurrió una falla de validación, configuración o procesamiento.

Webhooks

Registra la URL de Notificación del merchant para recibir cambios de estado. Orkestral envía una solicitud PATCH a la URL registrada:

PATCH <url_de_notificación>
Content-Type: application/json
IP: <dirección_del_servicio_notificador>

{
  "status": {
    "paymentStatusId": 6,
    "name": "SETTLED"
  },
  "message": "Pago liquidado"
}

Devuelve un HTTP 2xx rápidamente y procesa las notificaciones de forma idempotente. El header IP no es una firma criptográfica y no debe ser el único mecanismo para autenticar el origen.

Consulta Clave Secreta y URL de Notificación para configurar y proteger el endpoint.

Tratamiento de errores

HTTP	Situación común	Acción recomendada
400	Campo inválido o combinación no admitida	Corrige el payload antes de repetir.
401	Token ausente, inválido o vencido	Obtén un token válido.
403	Credencial sin acceso	Revisa los permisos del merchant.
404	Merchant, PSP o configuración inexistente	Revisa el ambiente y los registros.
409	transaction_id ya utilizado	Concilia la solicitud original.
422	Regla de negocio o credencial PSP inválida	Revisa moneda, beneficiario, banco y configuración.
5xx	Falla temporal	Consulta la transacción antes de repetir y usa backoff.

No repitas un PayOUT con otro transaction_id después de un timeout o error 5xx sin confirmar si la primera solicitud fue procesada. Una repetición incorrecta puede generar un pago duplicado.

Seguridad y buenas prácticas

• Valida beneficiario, documento, banco, cuenta, moneda y valor;
• Usa un transaction_id único y consérvalo para la conciliación;
• Restringe tokens y credenciales a los servicios backend;
• No registres tokens, documentos completos, cuentas ni claves PIX en logs;
• Usa TLS y certificados HTTPS válidos;
• Trata la respuesta inicial como asíncrona y espera el estado final;
• Valida y procesa los webhooks de forma idempotente;
• Separa los datos y credenciales de QAS y producción.