Sandbox for BRE-B disbursements

The sandbox environment allows you to test the complete BRE-B disbursement flow without processing real payments. You can simulate key previews, disbursement creation and event reception, validating your integration before going to production.

Sandbox Base URL

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

Use sandbox keys in the headers of all requests:

x-api-key: {Sandbox_API_Key}
user-principal-id: {Sandbox_User_Principal_ID}

Getting sandbox keys

Sandbox keys are obtained from the Wompi dashboard:

1. Log in to your main account in the merchant dashboard.
2. Go to Development > Developers.
3. In the upper left, select Third-Party Payments.
4. Switch to Sandbox mode.

From sandbox mode you can:

• View and regenerate keys
• Configure event URL
• View the event verification secret

BRE-B test keys

In sandbox, the following BRE-B keys are available to simulate successful resolutions:

Successful resolutions (200 OK)

Type	Test value	Simulated holder	Institution
MAIL	ecolon@wompi.com	Joh*** Car*** Per*** Gom***	BANCOLOMBIA (007)
PHONE	3001234567	Mar*** Lop*** Rui***	BANCO POPULAR (002)
IDENTIFICATION	1020304050	And*** Fel*** Gar*** Rod***	BANCO POPULAR (002)
ALPHANUMERIC	@elias123	Eli*** Can*** Mor***	BANCO DAVIVIENDA (051)
ESTABLISHMENT_CODE	B00012345	Tie*** Wom***	BANCOLOMBIA (007)
IDENTIFICATION (NIT)	900123456	Acm*** Sol***	BANCO DAVIVIENDA (051)

Error simulation

Test value	Simulated error	Code
noexiste@test.com	Key not found (404)	EXC_034
12345	Invalid key format (400)	EXC_033
inactiva@test.com	Inactive key (400)	EXC_035
timeout@test.com	Service timeout (503)	EXC_037
error@test.com	Service unavailable (503)	EXC_036

info

Any BRE-B key different from those listed above will return an EXC_034 error (key not found) in sandbox.

Preview a key in sandbox

GET https://api.sandbox.payouts.wompi.co/v2/breb/keys/resolve/@elias123?keyType=ALPHANUMERIC

Headers:

x-api-key: {Sandbox_API_Key}
user-principal-id: {Sandbox_User_Principal_ID}

Response:

{
  "status": 200,
  "meta": {
    "trace_id": "76470560-65e8-11f1-a897-a36bb8b3a60b"
  },
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "holderName": "Eli*** Can*** Mor***",
    "financialEntity": {
      "name": "BANCO DAVIVIENDA",
      "code": "051"
    },
    "keyType": "ALPHANUMERIC",
    "keyValue": "@ELIAS123"
  }
}

Create a BRE-B disbursement in sandbox

Disbursement creation in sandbox works the same as in production, with the addition of the optional transactionStatus field to simulate the final transaction state.

Simulate transaction status

Add the transactionStatus field to the body to define the simulated result:

Value	Behavior
APPROVED	All batch transactions are approved (default value)
FAILED	All batch transactions fail

note

If transactionStatus is not sent, transactions default to approved (APPROVED).

Example: approved disbursement

{
  "reference": "sandbox-breb-001",
  "accountId": "84a339e8-c277-45bd-b652-50f0b689edf7",
  "paymentType": "PROVIDERS",
  "transactions": [
    {
      "amount": 150000,
      "name": "Test User",
      "email": "test@example.com",
      "key": "@elias123"
    }
  ]
}

Example: failed disbursement

{
  "reference": "sandbox-breb-002",
  "accountId": "84a339e8-c277-45bd-b652-50f0b689edf7",
  "paymentType": "PROVIDERS",
  "transactionStatus": "FAILED",
  "transactions": [
    {
      "amount": 150000,
      "name": "Test User",
      "email": "test@example.com",
      "key": "@elias123"
    }
  ]
}

Recharge balance in sandbox

To have available balance in the source account, you can recharge using the recharge endpoint available in sandbox.

📖 See how to recharge balance in sandbox

Events in sandbox

Events (webhooks) are triggered in sandbox the same way as in production. To receive them:

1. Configure the event URL in sandbox mode from the dashboard.
2. Create a BRE-B disbursement.
3. You will receive payout.updated and transaction.updated events at the configured URL.

Signature verification works the same as in production, using the sandbox secret visible in the dashboard.

Complete test flow

1. Get sandbox credentials from the dashboard (sandbox mode).
2. Recharge balance with POST /accounts/balance-recharge.
3. Preview key with GET /breb/keys/resolve/@TESTUSER.
4. Create disbursement with POST /payouts using the test key.
5. Receive event at the configured URL with the final status.
6. Query status with GET /payouts/{payoutId} to verify.

Differences between sandbox and production

Aspect	Sandbox	Production
BRE-B keys	Only the test keys listed above	Any active key in the BRE-B directory
Transaction status	Controllable with transactionStatus	Determined by actual processing
Account balance	Freely rechargeable	Real bank account balance
Processing time	Immediate	Subject to ACH cycles and bank schedules
Events	Triggered immediately	Triggered according to processing cycle
Real money	No money is moved	Real transfers are executed

Important

Although the sandbox replicates production behavior, minor differences may exist. Perform complete testing before going to production.