Crea tu primer lote
Puedes crear lotes de pago de dos maneras, enviando el detalle de las transacciones como un JSON en el cuerpo de la solicitud, o enviando uno de los formatos de archivos que soportamos.
https://api.payouts.wompi.co/v1
Crear un lote de pago
La URL del endpoint para crear lotes de pagos manual es:
POST /payouts
Cabeceras (Headers)
x-api-key: *******
user-principal-id: *******
idempotency-key: Rs122k1sas
Content-Type: application/json
- Los headers
user-principal-idyx-api-keyson para la autenticación. Mas detalles de como obtenerlos en Llaves de autenticación - El header
idempotency-keyse usa para garantizar que el pago sea único y evitar duplicidad. Debe ser una llave que tenga de 1 a 64 caracteres, puede contener letras y números, el único caracter especial permitido dentro de la llave es el guion (-). Debe ser unico y expira en 24 horas. - El header
Content-Typedebe ir con el valorapplication/jsonespecificando que el formato del cuerpo de la petición.
Pagos inmediatos
A continuación se muestra un ejemplo del cuerpo de una petición:
{
"reference": "payment-reference",
"accountId": "account-id",
"paymentType": "PAYROLL",
"transactions": [
{
"legalIdType": "CC",
"legalId": "1000000000",
"bankId": "00000000-0000-0000-0000-000000000000",
"accountType": "AHORROS",
"accountNumber": "00000000",
"name": "John Doe",
"email": "email@example.com",
"amount": 1000000,
"reference": "custom-transaction-reference"
}
]
}
- El campo
accountIdse debe extraer de la respuesta del endpoint/accounts. Ir a consultar cuentas. - El campo
bankIdse debe extraer de la respuesta del endpoint/banks. Ir a consultar bancos. - El valor de
amountdebe ser un valor positivo y debe ir en centavos. (por ejemplo, $10,000 COP se representa como 1000000).
Pagos programados
Para crear pagos programados, puedes agregar el campo dispersionDatetime el cual es un string con el formato YYYY-MM-DDTHH:mm.
La fecha de programación del pago debe ser minimo al siguiente día en que se genere la petición, de lo contrario el pago es rechazado.
Ejemplo del cuerpo de la petición:
{
"reference": "referencia-api",
"accountId": "account-id",
"paymentType": "PAYROLL",
"dispersionDatetime": "2024-10-15T19:01",
"transactions": [
{
"legalIdType": "CC",
"legalId": "1000000000",
"bankId": "00000000-0000-0000-0000-000000000000",
"accountType": "AHORROS",
"accountNumber": "00000000",
"name": "John Doe",
"email": "email@example.com",
"amount": 1000,
"reference": "custom-transaction-reference"
}
]
}
Pagos recurrentes
Para crear pagos recurrentes debes agregar los campos dispersionDatetime el cual es un string con el formato YYYY-MM-DDTHH:mm y recurring el cual es un objeto json que recibe los siguientes campos:
interval: Intervalo del pago. Puede ser:biweek,month.months: Meses en número. Puede ser:3,6,12.description: La descripción es opcional.
{
"reference": "referencia-api",
"accountId": "account-id",
"paymentType": "PAYROLL",
"dispersionDatetime": "2024-10-15T19:01",
"recurring": {
"interval": "biweek",
"months": 3,
"description": "optional description"
},
"transactions": [
{
"legalIdType": "CC",
"legalId": "1000000000",
"bankId": "00000000-0000-0000-0000-000000000000",
"accountType": "AHORROS",
"accountNumber": "00000000",
"name": "John Doe",
"email": "email@example.com",
"amount": 1000,
"reference": "custom-transaction-reference"
}
]
}
Crear un lote de pago enviando un archivo
La URL del endpoint para crear lotes de pagos por archivo es:
POST /payouts/file
Formatos
Puedes crear un lote de pago usando uno de los siguientes archivos que soportamos:
| Formato | Código | Extensión | Plantilla | Ejemplo |
|---|---|---|---|---|
| Wompi | WOMPI | .csv | Plantilla | Descargar |
| PAB Bancolombia | PAB | .txt | Conversor | Descargar |
| SAP Bancolombia | SAP | .txt | Conversor | Descargar |
| Disfon - Banco de Bogotá | DISFON | .txt | Descargar | |
| FlexCube (FC) - Banco de Occidente | BANCO_OCCIDENTE_FC | .txt | Descargar | |
| Plano Davivienda | DAVIVIENDA | .txt | Descargar |
Cabeceras (Headers)
x-api-key: *******
user-principal-id: *******
idempotency-key: Rs122k1sas
Content-Type: multipart/form-data
- Los headers
user-principal-idyx-api-keyson para la autenticación. Mas detalles de como obtenerlos en Llaves de autenticación - El header
idempotency-keyse usa para garantizar que el pago sea único y evitar duplicidad. Debe ser una llave que tenga de 1 a 64 caracteres, puede contener letras y números, el único caracter especial permitido dentro de la llave es el guion (-). Debe ser unico y expira en 24 horas. - El header
Content-Typepara los pagos por archivo debe ir con el valormultipart/form-data
Pagos inmediatos
El cuerpo de la petición debe ser del tipo form-data con los campos:
reference: Referencia del lote.file: Archivo del lote.fileType: Tipo de archivo. Es el código del formato, ver tabla de formatos. Ej.BANCO_OCCIDENTE_FCaccountId: Id de la cuenta origenpaymentType: Tipo de pago. Puede ser:PAYROLL,PROVIDERS,OTHER.
Para subir un archivo de lote comprimido, este debe tener la extensión .gz y el MIME application/gzip. También se deben adicionar los siguientes campos a la petición:
fileName: Nombre del archivo y con la extensión original (antes de comprimirse). Por ejemplo, "plantilla-wompi.csv".fileMime: MIME del archivo original (antes de comprimirse). Por ejemplo, "text/csv".
Pagos programados
Para crear pagos programados se debe adicional el siguiente campo:
dispersionDatetime: Campo que representa la hora y fecha de dispersión con el formatoYYYY-MM-DDTHH:mm
La fecha de programación del pago debe ser minimo al siguiente día en que se genere la petición, de lo contrario el pago es rechazado.
Pagos recurrentes
Para crear pagos recurrentes debes agregar los siguientes campos:
dispersionDatetime: Campo que representa la hora y fecha de dispersión con el formatoYYYY-MM-DDTHH:mminterval: Intervalo del pago. Puede ser:biweek,month.months: Meses en número. Puede ser:3,6,12.description: La descripción es opcional.
