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 Accepted with the key in status PENDING.

  • A key in PENDING must not be considered ready for use. Clients must wait until the key transitions to ACTIVE or FAILED.

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

https://api.paas.sandbox.co.passportfintech.com/v1/keys

Method

POST

Headers

Content-Type: application/json, Authorization

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: ID, PHONE, EMAIL, ALPHA, BCODE

Yes

Type of key.

key_value

string

Varies by key_type

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: DYNAMIC or STATIC

No

DYNAMIC for usage of Dynamic Keys or STATIC for regular Bre-B Keys.

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 with 3.

  • 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 with 00.

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:

curl --location --request POST \
'https://api.paas.sandbox.co.passportfintech.com/v1/keys' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
"account_id": "6c23f053-0e1a-46b4-b902-97ba47e351bc",
"key": {
"key_type": "BCODE",
"key_value": "0016027228"
},
"display_name": "Pepito Silva"
}'

Explicit setting the parameter:

curl --location --request POST \
'https://api.paas.sandbox.co.passportfintech.com/v1/keys' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
"account_id": "6c23f053-0e1a-46b4-b902-97ba47e351bc",
"key": {
"key_type": "BCODE",
"key_value": "0016027228"
},
"display_name": "Pepito Silva",
"type": "DYNAMIC" //or STATIC for STATIC Bre-B Keys
}'

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

{
"status": "ACTIVE",
"key": {
"key_type": "BCODE",
"key_value": "0016027228"
},
"display_name": "Pepito Silva",
"account_id": "6c23f053-0e1a-46b4-b902-97ba47e351bc",
"created_at": "2025-10-09T10:42:39.710Z",
"updated_at": "2025-10-09T10:42:39.710Z",
"id": "3184cbfd-73bd-4910-bd03-f8461e724247",
"type": "DYNAMIC"
}

Dynamic Key Lifecycle

  1. Creation is requested. The merchant sends type: DYNAMIC. The key may become ACTIVE immediately or remain PENDING while Bre-B confirms registration.

  2. Registration is confirmed. Once the key becomes ACTIVE, it is ready for use, and the applicable creation fee is charged. If registration ends in FAILED, no creation fee is charged.

  3. A payment is received. The key is reserved for that payment while it is being processed.

  4. Additional payments are rejected. If another payment arrives while the first is being processed or has already settled, it is rejected with code B101 and the message Dynamic key already used.

  5. The payment settles, and the key is deleted. When the payment reaches SETTLED, automatic deletion begins. Once Bre-B confirms deletion, the key changes to CANCELLED, 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

ACTIVE

The key registration was confirmed and the key is ready for use.

FAILED

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

key.created

The key registration was confirmed. The key is now ACTIVE.

key.failed

The key registration was rejected. The key is now FAILED.

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:

  • PENDING The operation is still being processed.

  • ACTIVE The key registration was successful.

  • FAILED The 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

pending_operation

Identifies an operation currently being processed for the key.

failure_reason

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 with 202 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

400 Bad Request

Invalid Data

Required fields are missing or contain incorrect values.

401 Unauthorized

Expired or Invalid Token

The access token is invalid or has expired.

403 Forbidden

Access Denied

The request is not authorized to create a Key.

409 Conflict

ALREADY_EXISTS

The key is already registered to another Account or participant.

500 Internal Server Error

Server Error

An unexpected error occurred while creating the Key.

Important

A 202 Accepted response 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 200 and 202 as valid HTTP responses from key creation.

  • Do not assume that a successful POST /v1/keys means the key is immediately ACTIVE.

  • Support the PENDING and FAILED key statuses.

  • Support the pending_operation and failure_reason response fields.

  • Prefer the key.created and key.failed webhooks 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_EXISTS as 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 in FAILED does not generate a key-creation charge.