Create Key
Overview
This endpoint creates a new Bre-B. It registers a linkage between a Merchant, its Account, and a specific payment key for use in payment routing and QR code generation.
Key creation may be processed synchronously or asynchronously:
If the key is created immediately, the API returns the key data with status
ACTIVE.If Bre-B (the DICE) is still processing the registration, the API returns
202 Acceptedwith the key in statusPENDING.A key in
PENDINGmust not be considered ready for use. Clients must wait until the key transitions toACTIVEorFAILED.
The final status can be obtained by retrieving the key through GET /v1/keys/{id} or by subscribing to the corresponding key webhook events.
Dynamic Keys Feature
A dynamic key is a single-use Bre-B key. It can receive one successful payment and is automatically deleted once that payment settles.
For example, a merchant can create a key for a specific order. The customer pays using that key, and the key is deleted once the payment settles.
The feature is controlled by the parameter"type in the request body. If the parameter is not present, It will function as a normal Bre-B by default, more details in the sections below.
Endpoint Details
Definition | Description |
|---|---|
Endpoint | |
Method | POST |
Headers |
|
Authentication | Access Token (Bearer Token) |
Information
A Key can only be created after the Merchant (Link a Merchant) has been onboarded and has an Account with the Sponsor Bank.
Request Body
Parameter | Type | Constraints | Required | Description |
|---|---|---|---|---|
account_id | string | UUID | Yes | Unique identifier of the account to associate the key with. |
key_type | string | ENUM: | Yes | Type of key. |
key_value | string | Varies by | Yes | The actual key to be registered. |
display_name | string | 64 characters | No | Name displayed during key resolution to help identify the payee. By default it will show the merchant legal name. |
type | string | ENUM: | No |
If the parameter is missing, the STATIC key will be used. |
Accepted Key Types
ID: Document Number: up to 18 alphanumeric characters. Hyphens, spaces, and special characters are not allowed.PHONE: Mobile Phone Number: 10 digits and must start with3.EMAIL: Email: up to 92 characters, with a maximum of 30 characters before@and 61 characters after it.ALPHA: Alphanumeric Key: between 6 and 21 characters, containing letters and/or numbers and starting with@.BCODE: Commercial Entity Number: 10 numeric characters starting with00.
Relationship between Bre-B Keys and Accounts
The relationship between Bre-B Keys and Accounts is 1, meaning that one Account may have multiple Bre-B Keys associated with it.
Example Request
With the parameter not present:
Explicit setting the parameter:
Response
Key creation can be completed immediately or remain in progress.
Immediate Processing
If Bre-B confirms the key during the request, the API returns a successful response and the key has status: ACTIVE - In this status the key is ready for usage.
Example Response: Active Key
Dynamic Key Lifecycle
Creation is requested. The merchant sends
type: DYNAMIC. The key may becomeACTIVEimmediately or remainPENDINGwhile Bre-B confirms registration.Registration is confirmed. Once the key becomes
ACTIVE, it is ready for use, and the applicable creation fee is charged. If registration ends inFAILED, no creation fee is charged.A payment is received. The key is reserved for that payment while it is being processed.
Additional payments are rejected. If another payment arrives while the first is being processed or has already settled, it is rejected with code
B101and the messageDynamic key already used.The payment settles, and the key is deleted. When the payment reaches
SETTLED, automatic deletion begins. Once Bre-B confirms deletion, the key changes toCANCELLED, and its value becomes available for reuse.
If the first payment is rejected, the key is not consumed: it remains active and can receive another payment.
Payment rejection and key-registration rejection are separate processes. A creation that ends in FAILED does not produce an active key.
Asynchronous Processing: 202 Accepted
If Bre-B has not completed the registration when the request is processed, the API returns:
202 Accepted
The returned key has status:
PENDING
A 202 Accepted response means that the request has been successfully accepted for processing. It does not mean that the key registration has been completed.
Clients must wait for the key to transition to one of the following final states:
Status | Meaning |
|---|---|
| The key registration was confirmed and the key is ready for use. |
| The key registration was rejected by Bre-B. |
Asynchronous Key Creation Flow
After receiving a key in PENDING status, clients can determine the final result using either webhooks or polling.
Option 1: Webhooks
Clients can subscribe to:
Event | Description |
|---|---|
| The key registration was confirmed. The key is now |
| The key registration was rejected. The key is now |
The webhook payload contains the same key representation available through the Retrieve Key endpoint.
Webhook subscriptions are event-specific. Clients must explicitly subscribe to the key.* events they want to receive.
Option 2: Retrieve the Key
Clients that do not use webhooks can retrieve the key using:
GET /v1/keys/{id}
If the returned status is:
PENDINGThe operation is still being processed.ACTIVEThe key registration was successful.FAILEDThe registration was rejected.
Clients performing polling should use an appropriate delay and backoff strategy rather than continuously querying the endpoint.
New Response Fields
The Key response can now contain the following additional fields:
Field | Description |
|---|---|
| Identifies an operation currently being processed for the key. |
| Contains the reason provided when Bre-B rejects an operation. |
For a rejected creation, the key transitions to FAILED and failure_reason contains the reason for the rejection.
A FAILED key is final and cannot be activated. If the issue can be corrected, the same key may be submitted again. A new key record with a new id will be created.
Idempotent Retries
Key creation can be safely retried.
If the same key is submitted again for the same Account:
If the existing registration is still
PENDING, the API returns the existing key with202 Accepted.If the registration has already been resolved, the API returns the existing key with
200 OK.
Clients should therefore not treat retries of the same key for the same Account as duplicate-key errors.
If the key is already registered to another Account or another participant, the API returns 409 Conflict with ALREADY_EXISTS.
Common Errors and Handling
HTTP Status Code | Meaning | Description |
|---|---|---|
| Invalid Data | Required fields are missing or contain incorrect values. |
| Expired or Invalid Token | The access token is invalid or has expired. |
| Access Denied | The request is not authorized to create a Key. |
|
| The key is already registered to another Account or participant. |
| Server Error | An unexpected error occurred while creating the Key. |
Important
A
202 Acceptedresponse is not an error. It indicates that key registration is still being processed.
Using the Key After Creation
Do not assume that a newly created key is immediately available for use.
Before using a key in subsequent operations, verify that:
status = ACTIVE
In particular, QR Codes can only be created using an ACTIVE key.
A QR Code creation request using a key that is PENDING, FAILED, or suspended will be rejected because the key is not in the required state.
Best Practices
Accept both
200and202as valid HTTP responses from key creation.Do not assume that a successful
POST /v1/keysmeans the key is immediatelyACTIVE.Support the
PENDINGandFAILEDkey statuses.Support the
pending_operationandfailure_reasonresponse fields.Prefer the
key.createdandkey.failedwebhooks for asynchronous status updates.If webhooks are not used, poll
GET /v1/keys/{id}with an appropriate delay and backoff strategy.Do not generate QR Codes until the key reaches
ACTIVE.Safely retry key creation when the result of a previous request is unknown.
Treat
409 ALREADY_EXISTSas a permanent conflict when the key belongs to another Account or participant.
Billing
Key creation is charged only after the key registration is confirmed and the key becomes
ACTIVE. A creation that finishes inFAILEDdoes not generate a key-creation charge.