CCI/PHONE

CCI/PHONE are an essential aspect of modern payments in Peru, 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. CCI/PHONE are stored in a secure format and can be quickly accessed for various payment scenarios.

Types of CCI/PHONE

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

1. CCI: 20 to 22 numeric characters only

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

Payment Process Flow

The payment process begins when the user selects or enters a CCI/PHONE in their digital wallet, such as CCI, phone number. The wallet forwards this information to Depay, which validates the key and retrieves the necessary payment details. If the CCI/PHONE 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.

Retrieve preview to Pay with a CCI/PHONE

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

Similar to the "Retrieve QR Code Preview" endpoint, this endpoint allows users to retrieve the necessary information to initiate a payment via CCI/PHONE. 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 (CCI or phone number) used for payment.
amount*	Decimal	Amount value of the operation. The currency is automatically set to PEN 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.
tax_id_type*	String	User tax ID type, most commonly used DNI. (DNI, CUIT, CUIL)

Request Body Example

{
  "dict_key": "09900300039727500260",
  "external_reference": "5201M17",
  "notification_url": "https://payments.depay.us/payments/webhook/",
  "amount": 10,
  "user": {
    "full_name": "Joao Santos",
    "last_name": "Santos"
    "currency": "ARS",
    "account_number": "0009795493",
    "tax_id": "39053344705",
    "tax_id_type": "DNI"
  }
}

Response

200: OK

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

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":1,
        "local_currency":"PEN",
        "user_total_amount":416.57,
        "user_currency":"ARS"
    },
    "version":"2.0"
}

Callback behavior when dict_key is a phone number

When dict_key is a phone number, the callback returns an array of eligible wallet_id values. Each wallet_id represents a merchant wallet that can receive the payment. The merchant selects the destination wallet and instructs the application to route the payment accordingly (e.g., to the store/branch where the user is paying).

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).
wallets	Object	List of wallet options available for the merchant to receive a payment. Each item is a wallet record as defined below.
id	String	Unique identifier of the wallet in your platform. Use this value when selecting/routing the payment to a specific wallet. (UUIDV4)
brand	String	Wallet provider/brand name. Useful for UI display and provider-specific routing rules.
mobile	String	Mobile number linked to the wallet/account.
present	Boolean	Indicates support/intent for an in-person (“present”) flow (e.g., QR shown at a store).
directory	String	Network or bank directory code associated with the wallet/provider, used for payment routing. Country/network-specific.
participant_code	String	Financial institution/participant code used by the payment network for routing/settlement. May match directory depending on the scheme.
version	String	Version of the API you are woking with

Callback sent to Webhook

{
  "payment_type": "DICT_KEY",
  "external_reference": "0984267b-31c6-48be-9c0a-3f3610d64e36",
  "collector": {
    "name": null,
    "identification_number": null,
    "branch_office": null
  },
  "order": {
    "id": "cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "status": "CREATED",
    "local_total_amount": 100,
    "local_currency": "PEN",
    "user_total_amount": 41954.73,
    "user_currency": "ARS"
  },
  "wallets": [
    {
      "id": "7020cf30-2821-4883-a3f5-4f6cb173b99f",
      "brand": "YAPE",
      "mobile": "954528120",
      "present": true,
      "directory": "0901",
      "participant_code": "0901"
    },
    {
      "id": "74748340-0079-4ac5-b009-e58e9161c5eb",
      "brand": "PLIN",
      "mobile": "954528120",
      "present": true,
      "directory": "0902",
      "participant_code": "0902"
    },
    {
      "id": "1f63f95a-6205-4ef9-9d34-b23e878d2383",
      "brand": "FINANCIERA CONFIANZA",
      "mobile": "954528120",
      "present": true,
      "directory": "0903",
      "participant_code": "0099"
    }
  ],
  "version": "2.0"
}

Pay with a CCI/PHONE

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

This endpoint initiates a transaction process using a CCI/PHONE. It requires the key provided by the user, such as CCI or phone number. Upon receiving the CCI, 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 CCI/PHONE 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.
wallet_id*	String	UUIDV4 – Identifies the merchant’s wallet to receive the payment (only phone)

Request Body Example

{
    "order_id": "cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "status": "accepted",
    "notification_url": "https://payments.depay.us/payments/webhook/",
    "wallet_id": "8691cf30-2821-4883-a3f5-4f6cb173f99b"
}

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