Create BRE-B disbursement

The disbursement creation endpoint allows you to send payments to beneficiaries identified by their BRE-B key, without needing to know traditional banking details (bank, account type, account number). It also supports mixed batches where BRE-B transactions and bank transactions are combined in a single request.

Best practice

Before creating a BRE-B disbursement, use the preview endpoint to resolve the key and confirm the beneficiary with your user. This reduces failed payments.

Endpoint

POST /v2/payouts

Base URL

Production:

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

Sandbox:

https://api.sandbox.payouts.wompi.co/v2

Headers

Header	Required	Description
x-api-key	Yes	Merchant API Key for authentication
user-principal-id	Yes	Unique user identifier (UUID)
idempotency-key	Yes	Unique key to prevent duplicate payments. Only letters, numbers and hyphens. Maximum 64 characters. Expires in 24 hours.
Content-Type	Yes	application/json
business-application-id	No	Business application identifier. Value: WOMPI_PAYOUTS

x-api-key: exMsrSQwTL2vgrIQ2RdNL5MOlmNfOt7taSyMgzlJ
user-principal-id: 63416484-e3e2-48ff-8f0d-20877cd0d161
idempotency-key: payout-breb-unique-key-001
Content-Type: application/json

Request body

Batch fields

Field	Type	Required	Description
reference	string	Yes	Unique payment batch reference
accountId	string	Yes	Source account ID. Obtain from GET /accounts endpoint
paymentType	string	Yes	Payment type: PAYROLL, PROVIDERS, OTHER
transactions	array	Yes	List of transactions in the batch (minimum 1)
dispersionDatetime	string	No	Scheduled date in YYYY-MM-DDTHH:mm format. If not sent, payment is immediate
recurring	object	No	Recurrence configuration (see Recurring payments)

BRE-B transaction fields

To send a payment using a BRE-B key, use the key field instead of traditional banking fields.

Field	Type	Required	Description
key	string	Yes	Beneficiary's BRE-B key. When this field is sent, bankId, accountType and accountNumber are not required
amount	integer	Yes	Amount in cents (COP). Must be positive. E.g.: $1,000 = 100000
name	string	Yes	Beneficiary name
email	string	Yes	Beneficiary email address
legalIdType	string	No	Document type: CC, CE, NIT, PP, TI, DNI
legalId	string	No	Beneficiary document number
phone	string	No	Beneficiary phone number
description	string	No	Payment description
personType	string	No	Person type: NATURAL, JURIDICA
reference	string	No	Individual transaction reference. Maximum 40 characters, only letters, numbers and hyphens

Difference from bank payment

In a traditional bank payment, you send bankId, accountType, accountNumber, legalIdType and legalId. With BRE-B, the key field replaces the banking data. The system resolves the key and routes the payment automatically.

Immediate payments

Example of an immediate disbursement with BRE-B key:

{
  "reference": "payout-breb-001",
  "accountId": "84a339e8-c277-45bd-b652-50f0b689edf7",
  "paymentType": "PROVIDERS",
  "transactions": [
    {
      "amount": 150000,
      "name": "Juan Perez",
      "email": "juan@example.com",
      "key": "@juanperez"
    }
  ]
}

Example with multiple BRE-B transactions

{
  "reference": "payout-breb-002",
  "accountId": "84a339e8-c277-45bd-b652-50f0b689edf7",
  "paymentType": "PAYROLL",
  "transactions": [
    {
      "amount": 250000,
      "name": "Juan Perez",
      "email": "juan@example.com",
      "key": "@juanperez"
    },
    {
      "amount": 180000,
      "name": "Maria Lopez",
      "email": "maria@example.com",
      "key": "maria@email.com"
    },
    {
      "amount": 320000,
      "name": "Carlos Gomez",
      "email": "carlos@example.com",
      "key": "3001234567"
    }
  ]
}

Mixed batch example (BRE-B + bank account)

You can combine BRE-B and bank transactions in the same batch:

{
  "reference": "payout-mixed-001",
  "accountId": "84a339e8-c277-45bd-b652-50f0b689edf7",
  "paymentType": "PROVIDERS",
  "transactions": [
    {
      "amount": 150000,
      "name": "Juan Perez",
      "email": "juan@example.com",
      "key": "@juanperez"
    },
    {
      "amount": 250000,
      "name": "Carlos Gomez",
      "email": "carlos@example.com",
      "legalIdType": "CC",
      "legalId": "1234567890",
      "bankId": "9183a03b-cd82-451a-a6c7-6a9ab406a477",
      "accountType": "AHORROS",
      "accountNumber": "9876543210"
    }
  ]
}

Scheduled payments

To schedule a payment for a future date, add the dispersionDatetime field:

{
  "reference": "payout-breb-scheduled-001",
  "accountId": "84a339e8-c277-45bd-b652-50f0b689edf7",
  "paymentType": "PROVIDERS",
  "dispersionDatetime": "2025-07-15T10:00",
  "transactions": [
    {
      "amount": 500000,
      "name": "Juan Perez",
      "email": "juan@example.com",
      "key": "@juanperez"
    }
  ]
}

info

The scheduled date must be at least the next day after the request. Otherwise, the payment is rejected.

Recurring payments

To create recurring payments, add dispersionDatetime and the recurring object:

Field	Type	Required	Description
recurring.interval	string	Yes	Interval: biweek (biweekly), month (monthly)
recurring.months	integer	Yes	Duration in months: 3, 6, 12
recurring.description	string	No	Recurrence description

{
  "reference": "payout-breb-recurring-001",
  "accountId": "84a339e8-c277-45bd-b652-50f0b689edf7",
  "paymentType": "PAYROLL",
  "dispersionDatetime": "2025-07-15T10:00",
  "recurring": {
    "interval": "month",
    "months": 6,
    "description": "Monthly payment to provider"
  },
  "transactions": [
    {
      "amount": 350000,
      "name": "Juan Perez",
      "email": "juan@example.com",
      "key": "@juanperez"
    }
  ]
}

Successful response

HTTP 201 Created

{
  "status": 201,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "payoutId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transactions": 3,
    "success": 3,
    "failed": 0
  }
}

Field	Description
data.payoutId	Unique identifier for the created batch (UUID)
data.transactions	Total transactions sent in the batch
data.success	Transactions accepted for processing
data.failed	Transactions rejected by validation

Error responses

400 — Validation error

Returned when required fields are missing or have an invalid format.

{
  "status": 400,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "400",
  "message": [
    "reference must be a string",
    "reference should not be empty"
  ],
  "data": {
    "message": [
      "reference must be a string",
      "reference should not be empty"
    ],
    "error": "Bad Request",
    "statusCode": 400
  }
}

Invalid idempotency key

{
  "status": 400,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "400",
  "message": [
    "The key can only contain letters, numbers, and hyphens"
  ],
  "data": {
    "message": [
      "The key can only contain letters, numbers, and hyphens"
    ],
    "error": "Bad Request",
    "statusCode": 400
  }
}

Recommended action: Verify that all required fields are present and correctly formatted. The idempotency-key only accepts letters, numbers and hyphens.

401 — Unauthorized

Returned when the x-api-key is invalid or was not provided.

{
  "message": "Unauthorized"
}

Recommended action: Verify that you are sending the correct x-api-key in the headers.

403 — Forbidden

Returned when the payer is not registered, does not have permissions or does not have an active product.

{
  "status": 403,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "403",
  "message": "Payer not found",
  "data": {
    "message": "Payer not found",
    "error": "Forbidden",
    "statusCode": 403
  }
}

Possible messages:

• Payer not found — The user-principal-id does not correspond to a registered payer
• Customer is employed and not allowed — The client does not have disbursement permissions
• Payer not have active product — The payer does not have the Third-Party Payments product active

Recommended action: Verify that the user-principal-id corresponds to an active payer with the Third-Party Payments product enabled.

409 — Duplicate idempotency

Returned when the idempotency-key has already been processed.

{
  "status": 409,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "EXC_032",
  "message": "La llave de idempotencia ya fue procesada.",
  "type": "Business"
}

Recommended action: Use a new idempotency-key. Each key expires in 24 hours and cannot be reused within that period.

500 — Internal error

Returned when an unexpected server error occurs.

{
  "status": 500,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "EXC_001",
  "message": "Se presentó error interno procesando la solicitud."
}

Recommended action: Retry the request. If the error persists, contact support with the trace_id.

Supported BRE-B key types

Type	Format	Example key
Alphanumeric	@ + 5 to 20 alphanumeric characters	@JUANPEREZ
Email	Valid email	juan@email.com
Phone	10 digits, starts with 3	3001234567
Identification document	1 to 18 alphanumeric characters	1234567890
Establishment code	8 digits	12345678

Considerations

• Idempotency: Each request must include a unique idempotency-key. If the same key is sent within 24 hours, a 409 error is returned.
• Amounts in cents: The amount field is expressed in COP cents. For example, $10,000 COP is represented as 1000000.
• Mixed batches: A single batch can contain BRE-B transactions (with key) and bank transactions (with bankId + accountType + accountNumber).
• Key validation: The system resolves the BRE-B key when processing the transaction. If the key is not valid or not active, the individual transaction will be rejected.
• Limits: The same transactional limits apply as for bank disbursements. Check GET /limits.
• Source account: The accountId must correspond to an active payer account. Check GET /accounts.