Pagos mediante archivo (PayOut)

Te damos la bienvenida a la guía de Pagos mediante Archivo de Orkestral.

Sigue las instrucciones a continuación para preparar, validar y cargar archivos con múltiples pagos de salida (PayOuts) mediante PIX o transferencia bancaria.

Objetivo

Orientar a los clientes sobre cómo realizar pagos por lotes a través del portal de Orkestral, incluyendo:

• la preparación del archivo;
• el uso de las plantillas disponibles;
• la carga a través del portal;
• la corrección de errores de validación;
• el seguimiento de las transacciones procesadas.

Descripción general

La función Pagos mediante Archivo permite enviar varios PayOuts en una sola operación.

Cada fila del archivo representa un pago independiente. Después de la carga:

• Orkestral valida la estructura y el contenido de todas las filas;
• el archivo válido se acepta para su procesamiento;
• cada fila se transforma en una transacción PayOut;
• el pago se envía al PSP indicado en la fila;
• el resultado se puede consultar en el Informe de Transacciones.

Hay dos plantillas disponibles:

• PIX;
• Transferencia Bancaria.

:::warning Importante

El mensaje “¡Archivo enviado correctamente!” confirma que el archivo fue validado y aceptado. No significa que todos los pagos ya se hayan completado.

:::

Antes de comenzar

Para utilizar esta función, es necesario:

• tener una cuenta activa en Orkestral;
• estar vinculado al comercio responsable de los pagos;
• tener acceso a Informes > Carga de payout;
• tener un PSP de PayOut contratado, activo y con credenciales válidas;
• disponer de saldo y límites suficientes en el PSP;
• tener los datos correctos de los beneficiarios;
• utilizar la plantilla correspondiente al tipo de pago.

El PSP y la moneda indicados en el archivo deben estar habilitados para el comercio.

Formatos y límites

Característica	Regla
Formatos aceptados	.csv, .xls y .xlsx
Tamaño	Menor que 15 MB
Archivos por carga	Un archivo
Tipos de pago	PIX o transferencia bancaria
Encabezado	Debe estar en la primera fila
Contenido mínimo	Encabezado y al menos una fila de pago
Archivos Excel	Solo se procesa la primera hoja
Archivos CSV	Deben utilizar una coma como separador

Para archivos CSV, se recomienda utilizar la codificación UTF-8.

La plataforma no publica un límite de filas. Para cargas muy grandes, consulta con Orkestral cuál es el volumen recomendado.

Reglas importantes

• Utiliza la plantilla disponible en la propia pantalla.
• No cambies el nombre, elimines, agregues ni reordenes las columnas.
• No mezcles pagos PIX y transferencias bancarias en el mismo archivo.
• No dejes filas vacías entre los pagos.
• No utilices celdas combinadas.
• No utilices fórmulas en las celdas.
• No envíes archivos protegidos por contraseña o cifrados.
• Introduce los importes como números enteros, sin símbolos monetarios ni separadores.
• Mantén los documentos, cuentas y claves sin formato cuando la plantilla requiera solamente números.
• No incluyas contraseñas, tokens ni otras credenciales en el archivo.

Descargar la plantilla

1. Accede a la plataforma de Orkestral.
2. En el menú lateral, abre Informes.
3. Selecciona Carga de payout.
4. Busca las instrucciones que aparecen al inicio de la página.
5. Selecciona:
   • plantilla de PIX; o
   • plantilla de transferencia bancaria.
6. Guarda una copia de la plantilla.
7. Completa solamente las filas destinadas a los pagos.

La plantilla proporcionada por la plataforma debe utilizarse como referencia principal para el diseño del archivo.

Archivo de PIX

El archivo de PIX debe contener exactamente el siguiente encabezado:

AMOUNT,CURRENCY,NAME,LAST NAME,DOCUMENT,DOCUMENT TYPE,PIX KEY,PSP

Columnas del archivo de PIX

Columna	Obligatoria	Descripción
AMOUNT	Sí	Importe del pago en centavos, como número entero mayor que cero. Por ejemplo, 1000 representa BRL 10,00
CURRENCY	Sí	Código de la moneda en mayúsculas. En el flujo PIX actual, utiliza BRL
NAME	Sí	Nombre del beneficiario
LAST NAME	Sí	Apellido del beneficiario
DOCUMENT	Sí	Documento del beneficiario que contiene solamente números
DOCUMENT TYPE	Sí	Tipo de documento habilitado para la integración. El flujo confirmado actualmente utiliza CPF
PIX KEY	Sí	Clave PIX del beneficiario
PSP	Sí	PSP responsable del pago. En el flujo PIX actual, utiliza WEPAYMENTS

La clave PIX debe estar activa y ser reconocida por el PSP. El formato de la clave puede ser un documento, teléfono, correo electrónico o clave aleatoria.

Ejemplo de PIX

AMOUNT,CURRENCY,NAME,LAST NAME,DOCUMENT,DOCUMENT TYPE,PIX KEY,PSP
1000,BRL,Joao,Silva,51584112808,CPF,42362893855,WEPAYMENTS

El ejemplo es solamente ilustrativo. Utiliza datos válidos del beneficiario y la configuración disponible para tu comercio.

Archivo de Transferencia Bancaria

El archivo de transferencia bancaria debe contener exactamente el siguiente encabezado:

AMOUNT,CURRENCY,NAME,LAST NAME,EMAIL,DATE OF BIRTH,DOCUMENT,DOCUMENT TYPE,BANK NAME,BANK CODE,AGENCY CODE,AGENCY DIGIT,ACCOUNT NUMBER,ACCOUNT DIGIT,ACCOUNT TYPE,PSP

Columnas del archivo de transferencia

Columna	Obligatoria	Descripción
AMOUNT	Sí	Importe del pago en centavos, como número entero mayor que cero
CURRENCY	Sí	Código de la moneda habilitada para el PSP, en mayúsculas. Ejemplo: COP
NAME	Sí	Nombre del beneficiario
LAST NAME	Sí	Apellido del beneficiario
EMAIL	Sí	Correo electrónico válido del beneficiario
DATE OF BIRTH	Sí	Fecha de nacimiento del beneficiario
DOCUMENT	Sí	Número de documento del beneficiario
DOCUMENT TYPE	Sí	Tipo de documento aceptado por el PSP y el país de la operación. Ejemplos confirmados actualmente: CC, TI, DNI y CI
BANK NAME	Sí	Nombre del banco según el catálogo aceptado por Orkestral
BANK CODE	Sí	Código numérico del banco
AGENCY CODE	Sí	Código numérico de la sucursal
AGENCY DIGIT	Sí	Dígito numérico de la sucursal
ACCOUNT NUMBER	Sí	Número de cuenta del beneficiario
ACCOUNT DIGIT	Sí	Dígito numérico de la cuenta
ACCOUNT TYPE	Sí	Tipo de cuenta según el PSP
PSP	Sí	PSP responsable del pago. Utiliza el PSP configurado para el comercio, como KUSHKI o PAYVALIDA

Formatos de fecha aceptados

El campo DATE OF BIRTH acepta:

• dd/MM/yyyy, por ejemplo 25/10/1990;
• yyyy-MM-dd, por ejemplo 1990-10-25;
• yyyyMMdd, por ejemplo 19901025;
• una fecha nativa de Excel.

Tipos de cuenta

Los valores varían según el PSP.

Para Kushki, se pueden utilizar:

• CC;
• CA;
• CB;
• TD;
• NC;
• CV;
• DE;
• CM.

Para Payvalida, se pueden utilizar:

• AHORRO;
• CORRIENTE;
• MONETARIA.

Utiliza solamente un tipo de cuenta compatible con el PSP, el país y el banco del beneficiario.

Ejemplo de transferencia bancaria

AMOUNT,CURRENCY,NAME,LAST NAME,EMAIL,DATE OF BIRTH,DOCUMENT,DOCUMENT TYPE,BANK NAME,BANK CODE,AGENCY CODE,AGENCY DIGIT,ACCOUNT NUMBER,ACCOUNT DIGIT,ACCOUNT TYPE,PSP
1000,COP,Ana,Souza,ana.souza@example.com,1990-10-25,43750860,CC,BANCO DE OCCIDENTE,1,1,7,987654321,0,CORRIENTE,PAYVALIDA

El ejemplo es solamente ilustrativo. Los datos bancarios, el tipo de cuenta, la moneda y el PSP deben coincidir con la configuración del comercio.

Enviar el archivo

1. Accede a la plataforma de Orkestral.
2. En el menú lateral, abre Informes.
3. Selecciona Carga de payout.
4. En Selecciona el tipo de transacción, elige:
   • PIX; o
   • Transferencia Bancaria.
5. Arrastra el archivo al área indicada o haz clic para seleccionarlo.
6. Confirma que se muestre el nombre del archivo.
7. Selecciona Importar.
8. Espera la validación.

nota

La plataforma identifica el tipo de pago mediante el encabezado del archivo. Por lo tanto, seleccionar una pestaña no corrige un archivo completado con la plantilla incorrecta.

Validación del archivo

Antes de aceptar el archivo, Orkestral valida todas las filas.

Si hay algún error de estructura o de datos:

• se rechazará el archivo completo;
• no se colocará ningún pago en la cola;
• los errores se agruparán por categoría;
• la pantalla mostrará las celdas que deben corregirse.

Una referencia como A2 indica:

• columna A;
• fila 2.

Después de corregir el archivo, selecciona Volver, elígelo nuevamente y realiza una nueva carga.

Errores estructurales

Mensaje	Posible causa	Cómo corregir
Selecciona un archivo para cargar	No se seleccionó ningún archivo	Selecciona un archivo antes de elegir Importar
El archivo debe tener menos de 15 MB	El archivo supera el límite	Divide el contenido en archivos más pequeños
Este archivo no contiene datos	Archivo vacío o sin pagos	Incluye el encabezado y al menos una fila
Archivo no válido. Utiliza la plantilla como base	Encabezado incorrecto o estructura incompatible	Crea una nueva copia desde la plantilla
Faltan columnas obligatorias	Se eliminó una o más columnas	Restaura todas las columnas de la plantilla
Formato no compatible	Extensión diferente de CSV, XLS o XLSX	Guarda el archivo en un formato permitido

Errores de datos

Código técnico	Mensaje mostrado	Cómo corregir
INVALID_NUMBER	Número no válido	Introduce solamente un valor numérico válido
BLANK_STRING	Celda vacía	Completa el campo obligatorio
INVALID_CURRENCY	Moneda incorrecta	Utiliza la moneda habilitada para el PSP
INVALID_NUMBER_OR_BLANK_STRING	Número no válido o celda vacía	Completa el campo sin caracteres incompatibles
INVALID_PSP	PSP incorrecto	Utiliza el nombre del PSP configurado
INVALID_EMAIL	Correo electrónico no válido	Corrige el formato del correo electrónico
INVALID_DATE_OF_BIRTH	Fecha de nacimiento no válida	Utiliza uno de los formatos aceptados
INVALID_ACCOUNT_TYPE	Tipo de cuenta no válido	Utiliza un tipo compatible con el PSP
INVALID_BANK	Banco no válido	Utiliza el nombre de un banco reconocido por la plataforma
INVALID_DOCUMENT_TYPE	Tipo de documento no válido	Utiliza un tipo compatible con el país y el PSP
FILE_ERROR	Error en el archivo enviado	Verifica la cantidad, el orden y el contenido de las columnas

Procesamiento de los pagos

Después de que el archivo es aceptado, el procesamiento ocurre de forma asíncrona:

Archivo enviado
      ↓
Validación completada
      ↓
Archivo aceptado para procesamiento
      ↓
Creación de un PayOut por fila
      ↓
Envío al PSP indicado
      ↓
Actualización en el Informe de Transacciones

Cada fila recibe su propio identificador de transacción.

El PSP indicado en la columna PSP se utiliza directamente. Este flujo no utiliza el Flujo de Pago para seleccionar otro proveedor y no cuenta con fallback automático entre PSPs.

Un error en una fila no impide necesariamente que se procesen las demás. Por eso, un archivo puede generar pagos completados y pagos con error.

Seguimiento de los pagos

Después de aceptar el archivo, la plataforma redirige al usuario al Informe de Transacciones.

Para realizar el seguimiento de los pagos:

1. Accede a Informes > Transacciones.
2. En el filtro Tipo de transacción, selecciona PayOut.
3. Utiliza la fecha, el PSP, la moneda o el estado para localizar las transacciones.
4. Abre los detalles de cada pago.

Estados de PayOut

Estado	Significado
Procesando	El PSP recibió la solicitud, pero el resultado final todavía está pendiente
Completo	El pago fue liquidado. El estado detallado puede aparecer como Retirado
Fallido	El pago fue rechazado o se produjo un error durante el procesamiento

El PSP puede actualizar el estado posteriormente.

info

Actualmente, el portal no muestra un identificador de lote ni una pantalla pública con el estado general del archivo. El seguimiento se realiza mediante las transacciones individuales.

Corrección y reenvío

Archivo rechazado durante la validación

Si el archivo no muestra el mensaje de carga exitosa:

1. Corrige todas las celdas indicadas.
2. Guarda el archivo.
3. Vuelve a la pantalla de carga.
4. Envía nuevamente el archivo completo.

Como el archivo fue rechazado, ningún PayOut fue colocado en la cola.

Archivo ya aceptado

peligro

No envíes nuevamente el archivo completo sin consultar primero el Informe de Transacciones. Una nueva carga genera nuevos identificadores y puede duplicar pagos que ya se hayan ejecutado.

Si solamente fallan algunas filas:

1. Identifica las transacciones que ya se crearon.
2. Confirma qué pagos no se completaron.
3. Crea un nuevo archivo que contenga solamente los pagos que realmente necesitan otro intento.
4. Si tienes dudas, contacta al soporte de Orkestral antes del reenvío.

Buenas prácticas de seguridad

Los archivos pueden contener documentos y datos bancarios de los beneficiarios.

• Restringe el acceso a los archivos.
• No envíes los archivos mediante canales públicos o no autorizados.
• No incluyas datos bancarios en logs.
• No incluyas contraseñas, tokens ni credenciales del PSP.
• Almacena los archivos solamente durante el tiempo necesario.
• Elimina las copias locales cuando ya no sean necesarias.
• Confirma el origen y la integridad de los datos antes de la carga.
• Utiliza solamente dispositivos y redes de confianza.
• Mantén los procedimientos alineados con las normas de protección de datos aplicables.

Preguntas frecuentes

¿El mensaje “Archivo enviado correctamente” significa que todos los pagos se completaron?

No. Confirma que el archivo fue validado y aceptado. Los pagos se procesan posteriormente.

¿Puedo mezclar PIX y transferencias bancarias en el mismo archivo?

No. Utiliza un archivo y una plantilla para cada tipo de pago.

¿Puedo cambiar el orden o el nombre de las columnas?

No. El encabezado debe permanecer exactamente igual al de la plantilla.

¿Puedo volver a enviar un archivo aceptado?

Solamente después de confirmar qué transacciones ya se crearon. El reenvío del archivo completo puede generar pagos duplicados.

¿Dónde puedo consultar el resultado?

En Informes > Transacciones, utilizando el filtro PayOut.