Verify a Payout Alias

Use this endpoint to look up a payout alias before you send a payout. It returns the alias's status and a masked view of the registered owner, so you can confirm the alias is active and resolves to the expected recipient. This is a read-only lookup. It does not create a transaction and does not reserve funds.

Calling this endpoint is optional. You can still send a payout directly through Send funds via Bank Transfer without verifying the alias first. Checking it beforehand reduces failed payouts caused by an inactive or unregistered alias.

ℹ️
Currently available for Colombia only. countryISOCode only accepts CO, and aliasClassification only accepts Breb (Colombia's Bre-B instant payment system). Support for additional countries and alias classifications may be added in the future.

Before you begin

Ensure you have:

Valid API credentials (access token).
The alias you want to verify, along with its classification.

Endpoint

POST https://api.stage.localpayment.com/api/payment/alias-detail

Full parameter and schema details are also available in the Get Alias Detail API reference.

Required headers

Content-Type: application/json
Authorization: Bearer <your_access_token>

Request body

Field	Description	Required
`countryISOCode`	Country of the alias, in ISO 3166-1 alpha-2 format. Currently only `CO` (Colombia) is supported.	Yes
`aliasClassification`	Classification of the alias. Currently only `Breb` (a Colombia Bre-B key) is supported.	Yes
`aliasValue`	The alias to verify (phone number, document, email, merchant code, or alphanumeric key).	Yes

ℹ️
countryISOCode takes the 2-letter code (CO), not the 3-letter code (COL) used by most other Localpayment endpoints. This matches the live API and should not be "corrected" in your integration.

Example request

curl --request POST \
  --url 'https://api.stage.localpayment.com/api/payment/alias-detail' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --data '{
    "countryISOCode": "CO",
    "aliasClassification": "Breb",
    "aliasValue": "3668933567"
  }'

Handle the response

Successful response

{
  "aliasType": "PHONE",
  "aliasValue": "3668933567",
  "bankName": "KAMIN S.A",
  "firstName": "John",
  "idType": "CC",
  "idValue": "******0695",
  "lastName": "Do**",
  "status": "ACTIVE"
}

Response fields and masking

Localpayment masks personal data in the response. Only the fields below are returned, and only in this masked form.

Field	Description	Masking applied
`firstName`	Registered first name of the alias owner.	None.
`lastName`	Registered last name of the alias owner.	First 2 letters shown, rest masked (`Doe` becomes `Do**`).
`status`	Current status of the alias (for example, `ACTIVE`).	None.
`idType`	Type of the owner's identity document (see Supported Document Types).	None.
`idValue`	The owner's identity document number.	Only the last 4 digits shown, rest masked (`20304050` becomes `****4050`).
`aliasType`	Classification of the alias that was resolved. For Colombia Bre-B keys: identity document, merchant code, cellphone number, email address, or alphanumeric key.	None.
`aliasValue`	The alias you queried, echoed back.	None.
`bankName`	Name of the bank where the alias is registered.	None.

Error handling

Scenario	HTTP status	Message
The alias does not resolve to a registered owner or is inactive.	`400 Bad Request`	`{"error": "DICE error: Keys not found or inactive", "errorCode": "408"}`
The country or classification combination is not supported.	`422 Unprocessable Entity`	`{"error": "Service not available for Breb in COL"}`
The access token is missing, invalid, or expired.	`401 Unauthorized`	Standard authentication error.

Always handle these cases in your integration instead of assuming every lookup succeeds. For general guidance on interpreting HTTP status codes and error response structure across the Localpayment API, see Error Handling.

Demo

Try the lookup with a sample alias to see how the masked result appears. The demo reflects the current scope: Colombia only.

Verify a Payout Alias

POST /api/payment/alias-detail

Colombia onlyAlias (aliasValue)

Sample data for illustration. Does not call the live Localpayment API.

Next steps

Send funds via Bank Transfer

Send a payout using the alias you verified.

Colombia

Review supported banks, document types, and payout methods for Colombia.