Preview BRE-B beneficiary

The preview endpoint allows you to resolve a BRE-B key and obtain the associated holder's information before executing a payment. It is a read-only operation that does not generate any transaction or fund movement.

Best practice

Always preview the BRE-B key before creating a disbursement. This allows you to confirm the beneficiary with your user and reduce failed payments.

Endpoint

GET /v2/breb/keys/resolve/{keyValue}

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)
business-application-id	No	Business application identifier. Value: WOMPI_PAYOUTS

x-api-key: exMsrSQwTL2vgrIQ2RdNL5MOlmNfOt7taSyMgzlJ
user-principal-id: 63416484-e3e2-48ff-8f0d-20877cd0d161

Parameters

Path

Parameter	Type	Required	Description
keyValue	string	Yes	BRE-B key value to resolve

Query

Parameter	Type	Required	Description
keyType	string	No	BRE-B key type. If sent, the value format is validated against the specified type.

Possible keyType values:

Type	Expected format	Example
ALPHANUMERIC	@ + 5 to 20 alphanumeric characters	@JUANPEREZ
MAIL	Valid email	juan@email.com
PHONE	10 digits, starts with 3	3001234567
IDENTIFICATION	1 to 18 alphanumeric characters	1234567890
ESTABLISHMENT_CODE	8 digits	12345678

Successful response

HTTP 200 OK

{
  "status": 200,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "holderName": "JUA*** PER*** GAR***",
    "financialEntity": {
      "name": "BANCOLOMBIA",
      "code": "001"
    },
    "keyType": "ALPHANUMERIC",
    "keyValue": "@JUA***"
  }
}

Field	Description
holderName	Key holder name (masked for security)
financialEntity.name	Associated financial institution name
financialEntity.code	Financial institution code
keyType	Resolved key type
keyValue	Key value (masked)

Masked data

For security, the holder's data is returned partially masked. This is sufficient for your user to visually confirm the beneficiary before proceeding with the payment.

Examples by key type

Alphanumeric key

GET /v2/breb/keys/resolve/@JUANPEREZ?keyType=ALPHANUMERIC

Response:

{
  "status": 200,
  "meta": {
    "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "holderName": "JUA*** PER*** GAR***",
    "financialEntity": {
      "name": "BANCOLOMBIA",
      "code": "001"
    },
    "keyType": "ALPHANUMERIC",
    "keyValue": "@JUA***"
  }
}

Email key

GET /v2/breb/keys/resolve/juan@email.com?keyType=MAIL

Response:

{
  "status": 200,
  "meta": {
    "trace_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
  },
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "holderName": "JUA*** PER*** LON***",
    "financialEntity": {
      "name": "DAVIVIENDA",
      "code": "051"
    },
    "keyType": "MAIL",
    "keyValue": "jua***@ema***.com"
  }
}

Phone key

GET /v2/breb/keys/resolve/3001234567?keyType=PHONE

Response:

{
  "status": 200,
  "meta": {
    "trace_id": "c3d4e5f6-a7b8-9012-cdef-345678901234"
  },
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "holderName": "MAR*** GOM*** RUI***",
    "financialEntity": {
      "name": "NEQUI",
      "code": "507"
    },
    "keyType": "PHONE",
    "keyValue": "300***4567"
  }
}

Identification document key

GET /v2/breb/keys/resolve/1234567890?keyType=IDENTIFICATION

Response:

{
  "status": 200,
  "meta": {
    "trace_id": "d4e5f6a7-b8c9-0123-def4-567890123456"
  },
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "holderName": "CAR*** MEN*** SAL***",
    "financialEntity": {
      "name": "BANCO DE BOGOTA",
      "code": "001"
    },
    "keyType": "IDENTIFICATION",
    "keyValue": "123***7890"
  }
}

Establishment code key

GET /v2/breb/keys/resolve/12345678?keyType=ESTABLISHMENT_CODE

Response:

{
  "status": 200,
  "meta": {
    "trace_id": "e5f6a7b8-c9d0-1234-ef56-789012345678"
  },
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "holderName": "EMP*** TEC*** SAS***",
    "financialEntity": {
      "name": "BBVA COLOMBIA",
      "code": "013"
    },
    "keyType": "ESTABLISHMENT_CODE",
    "keyValue": "1234***8"
  }
}

Error responses

400 — Invalid key format

Returned when the key value does not match the expected format for the specified type.

{
  "status": 400,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "EXC_033",
  "message": "El valor de la llave BRE-B no tiene un formato válido.",
  "type": "Business"
}

Recommended action: Verify that the key value matches the expected format for its type. See the key types table above.

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 or does not have permissions.

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

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

404 — Key not found

Returned when the BRE-B key does not exist or is not active in the directory.

{
  "status": 404,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "EXC_034",
  "message": "La llave BRE-B no se encuentra activa o no está registrada.",
  "type": "Business"
}

Recommended action: Confirm with the beneficiary that the key is registered and active at their financial institution.

503 — Service unavailable

Returned when the BRE-B resolution service has connectivity issues.

{
  "status": 503,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "EXC_036",
  "message": "El servicio de resolución BRE-B no está disponible.",
  "type": "Technical"
}

503 — Timeout

Returned when key resolution exceeds the maximum wait time.

{
  "status": 503,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "EXC_037",
  "message": "Tiempo de espera agotado al resolver la llave BRE-B.",
  "type": "Technical"
}

Recommended action for 503 errors: Retry the request after a few seconds. If the problem persists, contact support.

Considerations

• Without keyType: If you don't send the keyType parameter, the system will try to determine the type automatically based on the value format. However, it is recommended to always send it to avoid ambiguities (for example, a 10-digit number could be a phone or a document).
• Masking: Returned data is partially hidden for security. It is not possible to obtain the holder's complete data through this endpoint.
• Rate limiting: This endpoint is subject to the same rate limits as the rest of the API.
• Idempotency: Being a read-only GET operation, it does not require an idempotency header.