Create your first batch

You can create payment batches in two ways: by sending the transaction details as a JSON in the request body, or by sending one of the supported file formats.

API Base URL

https://api.payouts.wompi.co/v1

Create a payment batch

The endpoint URL to manually create payment batches is:

POST /payouts

Headers

x-api-key: *******
user-principal-id: *******
idempotency-key: Rs122k1sas
Content-Type: application/json

• The user-principal-id and x-api-key headers are for authentication. More details on how to obtain them in Authentication Keys
• The idempotency-key header is used to ensure the payment is unique and to avoid duplication. It must be a key between 1 and 64 characters, can contain letters and numbers, and the only special character allowed is the hyphen (-). It must be unique and expires in 24 hours.
• The Content-Type header must be set to application/json specifying that the request body format is JSON.

Immediate payments

Below is an example of the request body:

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

• The accountId field must be taken from the response of the /accounts endpoint. Go to query accounts.
• The bankId field must be taken from the response of the /banks endpoint. Go to query banks.
• The value of amount must be a positive value and must be in cents. (for example, $10,000 COP is represented as 1000000).

Scheduled payments

To create scheduled payments, you can add the dispersionDatetime field, which is a string in the format YYYY-MM-DDTHH:mm.

info

The payment scheduling date must be at least the next day after the request is made, otherwise the payment will be rejected.

Example of the request body:

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

Recurring payments

To create recurring payments, you must add the dispersionDatetime field, which is a string in the format YYYY-MM-DDTHH:mm, and recurring, which is a JSON object that receives the following fields:

• interval: Payment interval. Can be: biweek, month.
• months: Number of months. Can be: 3, 6, 12.
• description: The description is optional.

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

Create a payment batch by sending a file

The endpoint URL to create payment batches by file is:

POST /payouts/file

Formats

You can create a payment batch using one of the following supported files:

Format	Code	Extension	Template	Example
Wompi	WOMPI	.csv	Template	Download
PAB Bancolombia	PAB	.txt	Converter	Download
SAP Bancolombia	SAP	.txt	Converter	Download
Disfon - Banco de Bogotá	DISFON	.txt		Download
FlexCube (FC) - Banco de Occidente	BANCO_OCCIDENTE_FC	.txt		Download
Plano Davivienda	DAVIVIENDA	.txt		Download

Headers

x-api-key: *******
user-principal-id: *******
idempotency-key: Rs122k1sas
Content-Type: multipart/form-data

• The user-principal-id and x-api-key headers are for authentication. More details on how to obtain them in Authentication Keys
• The idempotency-key header is used to ensure the payment is unique and to avoid duplication. It must be a key between 1 and 64 characters, can contain letters and numbers, and the only special character allowed is the hyphen (-). It must be unique and expires in 24 hours.
• The Content-Type header for file payments must be set to multipart/form-data

Immediate payments

The request body must be of type form-data with the fields:

• reference: Batch reference.
• file: Batch file.
• fileType: File type. It is the format code, see the formats table. E.g. BANCO_OCCIDENTE_FC
• accountId: Origin account id
• paymentType: Payment type. Can be: PAYROLL, PROVIDERS, OTHER.

Compressed files

To upload a compressed batch file, it must have the .gz extension and MIME type application/gzip. You must also add the following fields to the request:

• fileName: Name of the file with the original extension (before compression). For example, "plantilla-wompi.csv".
• fileMime: MIME of the original file (before compression). For example, "text/csv".

Scheduled payments

To create scheduled payments, you must additionally include the following field:

• dispersionDatetime: Field representing the date and time of dispersion in the format YYYY-MM-DDTHH:mm

info

The payment scheduling date must be at least the next day after the request is made, otherwise the payment will be rejected.

Recurring payments

To create recurring payments, you must add the following fields:

• dispersionDatetime: Field representing the date and time of dispersion in the format YYYY-MM-DDTHH:mm
• interval: Payment interval. Can be: biweek, month.
• months: Number of months. Can be: 3, 6, 12.
• description: The description is optional.