DICT Key Payments

DICT Keys are an essential aspect of modern payments, offering flexibility and security by using unique identifiers like phone numbers or emails to facilitate transactions. This method simplifies the payment process, reducing friction for users by enabling transfers without needing a QR code. DICT Keys are stored in a secure format and can be quickly accessed for various payment scenarios.

Types of DICT Keys

DICT Keys are unique identifiers used in Pix payments to facilitate transactions without needing QR codes. The following types are supported:

1. CPF: Brazilian individual taxpayer registry number, not formatted, and 11 numeric characters only.

2. CNPJ: Brazilian company registration number, not formatted, and 14 numeric characters only

3. Email: Standard email format.

4. Phone Number: International format with country code, including the '+' prefix. e.g "+55..."

5. UUID: Universally unique identifier version 4, in the format of xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Payment Process Flow

The payment process begins when the user selects or enters a DICT Key in their digital wallet, such as CPF, CNPJ, phone number, or email. The wallet forwards this information to Depay, which validates the key and retrieves the necessary payment details. If the DICT Key is valid, Depay sends the payment information back to the wallet.

The wallet then presents this information to the user for confirmation. Once confirmed, the wallet forwards the authorized transaction details back to Depay, which processes the payment. Finally, Depay communicates the payment status to the wallet, notifying the user of the successful completion or any issues encountered during the transaction. This ensures a secure and transparent process for the user.

Payment Process Flow

Statuses of an Order

Key	Description
CREATED	The order has been created.
PROCESSING	The payment was accepted and is being processed.
COMPLETED	The payment was successfully completed.
CANCELED	The preview was not accepted by the user or it expired.
REFUNDED	The order has been refunded.
PARTIALLY_REFUNDED	The order was partially refunded.
REJECTED	The payment has been rejected by the destination bank account.
FAILED	The payment failed due to an unexepcted error.

Validate DICT Key

POST https://stage.api.payments.depay.us/v2/payments/validations/dictkey

Endpoint used to validate Dict Keys. It returns the user information associated with a Dict Key.

Headers

Name	Type	Description
Authorization*	String	Bearer Token
idempotency-key	String	An idempotent identifier provided by the client to ensure that a request is processed only once.

Request Body

Name	Type	Description
dict_key*	String	The DICT Key (CPF, CNPJ, email, phone number, UUID v4) used for payment.

Request Body Example

{
    "dict_key": "8f27d7dc-aa2a-42a8-9f4c-7998dfef5202"
}

Response

200: OK

{
    "name": "dict_key user",
    "accountNumber": "1111111111",
    "identificationNumber": "11111111111111",
    "mcc": "CHECKING",
    "branchOffice": "0000",
    "category": "CHECKING",
    "postalCode": null,
    "bank": "User's Bank",
    "terminal": null
}

400: Bad Request

400: Bad Request

401: Unauthorized Permission Denied

409: Conflict Error

Retrieve preview to Pay with a DICT Key

POST https://stage.api.payments.depay.us/v2/payments/previews/dictkey

Similar to the "Retrieve QR Code Preview" endpoint, this endpoint allows users to retrieve the necessary information to initiate a payment via DICT Keys. After the transaction details are retrieved, a preview is generated for the user to review and confirm before completing the payment.

Headers

Name	Type	Description
Authorization*	String	Bearer Token
idempotency-key	String	An idempotent identifier provided by the client to ensure that a request is processed only once.

Request Body

Name	Type	Description
dict_key*	String	The DICT Key (CPF, CNPJ, email, phone number, UUID v4) used for payment.
amount*	Decimal	Amount value of the operation. The currency is automatically set to BRL by the server.
external_reference*	String	The user-defined identifier used to link and track the payment. Length (max): 100.
notification_url*	String	The provided URL is a POST endpoint where payment information will be received. Length (max): 250.
user*	String	User information
full_name*	String	User name and surname
currency*	String	Represents the default currency the user will use to make the payment. It must be provided in ISO 4217 format
account_number*	String	User account from which the user wishes to make the payment
tax_id*	String	User tax identification number. Length (max): 50.

Request Body Example

{
  "dict_key": "8f27d7dc-aa2a-42a8-9f4c-7998dfef5202",
  "external_reference": "5201M17",
  "notification_url": "https://payments.depay.us/payments/webhook/",
  "amount": 10,
  "user": {
    "full_name": "Joao Santos",
    "currency": "BRL",
    "account_number": "0009795493",
    "tax_id": "39053344705"
  }
}

Response

200: OK

{
      "status": "success",
      "external_reference": "e8a7a740-6f47-11ec-90d6-0242ac120003",
      "message": "Preview is being processed.",
      "local_currency": "ARS"     
}

400: Bad Request

400: Bad Request

401: Unauthorized Permission Denied

409: Conflict Error

Preview Callback Response

This response will be sent to the callback (notification_url). There are two possible responses: one for the open_amount QR code, which asks for the amount, and another for the closed_amount QR code, which sends the preview directly.

Name	Type	Description
payment_type	String	Payment Type (always "DICT_KEY")
external_reference	String	This is the reference sent in the request, allowing the requester to internally identify the payment being performed. Length (max): 100.
collector	Object	Information object about the merchant (seller). This information is only available for successful read cases.
name	String	Name of the merchant.
identification_number	String	Unique Tax Identification Code of the administrator.
branch_office	String	Internal merchant or branch office number. Can be empty.
order	Object	Information object about the order to be paid. This information is only available for successful read cases.
id	String	Identifier of the order. This data is necessary when initiating the payment of this QR.
local_total_amount	Decimal	The total amount in the currency of the QR code's country. If it is an open amount QR (status: open_amount), the value will be null.
local_currency	String	Currency of the QR code's country. (ISO 4217 format).
user_total_amount	Decimal	The local_total_amount is converted into the user's currency. If it is an open amount QR (status: open_amount), the value will be null.
user_currency	String	User's currency (ISO 4217 format).
version	String	Version of the API you are woking with

Callback Body Example

{
    "payment_type":"DICT_KEY",
    "external_reference":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "collector":
    {
        "name":"DEPAY MARKET",
        "identification_number":"20314691769",
        "branch_office":""
    },
    "order":
    {
        "id":"cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
        "status":"CREATED",
        "local_total_amount":22,
        "local_currency":"BRL",
        "user_total_amount":366,
        "user_currency":"ARS"
    },
    "version":"2.0"
}

Pay with a DICT Key

POSThttps://stage.api.payments.depay.us/v2/payments

This endpoint initiates a transaction process using a DICT Key. It requires the key provided by the user, such as CPF, CNPJ, email, phone number, or UUID. Upon receiving the DICT Key, the system processes the transaction. In some cases, the final payment result may be available immediately. However, if additional processing time is needed, the final result can be retrieved either via a webhook that notifies the DICT Key payment event or by querying the operation status directly to confirm the payment outcome.

Headers

Name	Type	Description
Authorization*	String	Bearer Token
idempotency-key	String	An idempotent identifier provided by the client to ensure that a request is processed only once.

Request Body

Name	Type	Description
order_id*	String	Order identifier. This field corresponds to the id field within the order object retrieved from the QR information retrieval endpoint. Required.
status*	String	This field is the value of the user's decision. The accepted values are 'accepted' or 'rejected'
notification_url*	String	The URL where notifications about QR payments events will be sent. Required. Length (max): 250.

Request Body Example

{
    "order_id": "cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "status": "accepted",
    "notification_url": "https://payments.depay.us/payments/webhook/"
}

Response

201: OK Successful operation

{
    "status": "PROCESSING",
    "message": "Payment in process"
}

401: Unauthorized Permission denied

404: Not Found

Name	Type	Description
order_id	String	Identifier of the order. This data is necessary when initiating the payment of this QR.
external_reference	String	This is the reference sent in the QR preview request, allowing the requester to internally identify the payment. Length (max): 100.
external_reference_id	String	This is the reference sent in the QR preview request, allowing the requester to internally identify the payment. Length (max): 100.
status	String	A key that indicates the current status of the order.
date	String	Date and time when the notification is created. Format: YYYY-MM-DDTHH:MM:SSZ (ISO 8601).
payment_date	String or Null	Date and time when the payment was processed. Format: YYYY-MM-DDTHH:MM:SSZ (ISO 8601).
merchant_identification_number	String	Unique identifier assigned to the merchant by the payment processor.
merchant_name	String	Display name of the merchant associated with the transaction.
error_code	String or Null	Error code returned in case the payment fails. Null if the transaction was successful.

Callback Body Example - Payment PROCESSING

{
    "order_id":"cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "external_reference":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "external_reference_id":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "status":"PROCESSING",
    "date":"2025-05-30T11:14:25.115Z",
    "payment_date":null,
    "merchant_identification_number":"11111111111",
    "merchant_name":"MERCHANT01",
    "error_code":null
}

Callback Body Example - Payment CANCELED

{
    "order_id":"cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "external_reference":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "external_reference_id":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "status":"CANCELED",
    "date":"2025-05-30T11:14:25.115Z",
    "payment_date":null,
    "merchant_identification_number":"111111111",
    "merchant_name":"MERCHANT01",
    "error_code":"Order expired"
}

Callback Body Example - Payment REJECTED

{
    "order_id":"cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "external_reference":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "external_reference_id":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "status":"REJECTED",
    "date":"2025-05-30T11:14:25.115Z",
    "payment_date":null,
    "merchant_identification_number":"20322678275",
    "merchant_name":"MERCHANT01",
    "error_code":"VENCIDO | 0200 - AVISO ENVIADO"
}

Callback Body Example - Payment FAILED

{
    "order_id":"cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "external_reference":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "external_reference_id":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "status":"FAILED",
    "date":"2025-05-29T13:16:30.452Z",
    "payment_date":null,
    "merchant_identification_number":"111111111111",
    "merchant_name":"MERCHANT01",
    "error_code":"ACCOUNT_BLOCKED The specified account is blocked."
}

Callback Body Example - Payment COMPLETED

{
    "order_id":"cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "external_reference":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "external_reference_id":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "status":"COMPLETED",
    "date":"2025-05-30T11:14:25.115Z",
    "payment_date":"2025-05-30T11:14:25.115Z",
    "merchant_identification_number":"20322678275",
    "merchant_name":"MERCHANT01",
    "error_code":null
}

Order Refund

The refund can be either partial or full, as specified in the request. Depay will send updates regarding the refund status — such as whether it was successful or rejected — to the notification_url previously provided in the body of the Payment Request. The refunded amount will be credited to your pre-funded account to ensure uninterrupted service.

Status	Description	Is Final
REFUNDED	The refund has been successfully completed.	Yes
PARTIALLY_REFUNDED	The partial refund has been successfully completed.	No

Headers

Name	Type	Description
idempotency-key	String	An idempotent identifier provided to ensure that a request is processed only once.

Webhook Notification

This notification will be sent to notification_url.

Name	Type	Description
order_id	String	Order identifier. This field corresponds to the id field within the order object retrieved from the QR information retrieval endpoint.
external_reference	String	This is the reference sent in the QR preview request, allowing the requester to internally identify the payment. Length (max): 100.
status	String	A key that indicates the current status of the preview.
date	String	Date and time when the notification is created. Format: YYYY-MM-DDTHH:MM:SSZ (ISO 8601).
payment_date	String	Date and time when the payment was processed. Format: YYYY-MM-DDTHH:MM:SSZ (ISO 8601).
merchant_identification_number	String	Unique identifier assigned to the merchant by the payment processor.
merchart_name	String	Display name of the merchant associated with the transaction.
error_code	String or null	Error code returned in case the payment fails. Null if the transaction was successful.
amount	Number	Transaction amount to be paid by the user.
currency	String	ISO 4217 currency code representing the transaction currency (e.g., USD, EUR, BRL).

Notification Body Example

{
    "order_id":"cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "external_reference":"12345678-1234-1234-1234-123456789876",
    "status":"REFUNDED",
    "date":"2025-05-26T15:30:56.842Z",
    "payment_date":"2025-05-26T15:30:56.842Z",
    "merchant_identification_number":"321664897",
    "merchant_name":"Depay",
    "error_code":null,
    "amount":0.2,
    "currency":"BRL"
}

Get Payment Status

GET https://stage.api.payments.depay.us/v2/payments/{order_id}/status

Allows users to inquire about the current status of their payments.

Headers

Name	Type	Description
Authorization*	String	Bearer Token

Query Parameters

Name	Type	Description
order_id*	String	Order identifier. This field corresponds to the id field within the order object retrieved from the QR information retrieval endpoint. Required.

Response

200: OK Successful operation

{
    "id":"cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "status": "COMPLETED",
    "creation_date": "2025-03-21T14:15:06.657Z",
    "update_date": "2025-03-21T14:20:00.000Z",
    "local_amount": "7.0000",
    "local_currency": "BRL",
    "user_amount": "1637.3605",
    "user_currency": "ARS",
    "external_reference": "123123123",
    "merchant_identification_number": "12345678987",
    "merchant_name": "John Doe",
    "statuses":[
        {
            "status": "CREATED",
            "created_at": "2025-03-21 20:01:30.948423"
        },
        {
             "status": "WAITING_AMOUNT",
            "created_at": "2025-03-21 20:01:50.567650"
        },
        {
             "status": "COMPLETED",
            "created_at": "2025-03-21 20:02:00.343641"
        }
    ]
}

401: Unauthorized Premission Denied

404: Not Found