CCI/PHONE (Perú)
CCI/PHONE are an essential aspect of modern payments in Peru, offering flexibility and security by using unique identifiers like phone number or CCI (Código de Cuenta Interbancaria) 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 payments to facilitate transactions without needing QR codes. The following types are supported:
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.
Statuses of an Order
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
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
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
dict_key*
String
Identifier to validate. Can be a CCI or a phone number with country code
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.
local_country
String
Optional field, country where the recipient is from. It must be provided in ISO 3166-1 alpha-2 format (e.g., "PE" for Perú). Default value is BR.
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.
For phone number payments, collector information can be retrieved from the Validate Wallet endpoint.
Response
CCI/Phone Response
status
string
Indicates the result of the request processing.
external_reference
string
Unique identifier assigned by the client to track the operation.
message
string
Message describing the current processing state.
local_currency
string
Currency code used for the transaction, expressed in ISO 4217 format.
collector
object
Object containing information about the merchant or collector receiving the payment.
name
string
Legal or commercial name of the collector.
identification_number
string
Tax or identification number of the collector.
identification_type
string
Type of identification document associated with the collector.
branch_office
string
Identifier of the collector’s branch office, if applicable.
account_id
string
Account identifier where the funds will be credited.
account_type
string
Type of account associated with the collector.
mcc
string
Merchant Category Code (MCC) that classifies the collector’s business activity.
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.
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 behavior when dict_key is a phone number
dict_key is a phone numberWhen 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).
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).
walletId
String
Wallet record identifier. Must be sent as wallet_record_id in wallet validation
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
Validate CCI or Phone
Validates a CCI or a phone number (including country code) and returns the user information associated with the provided identifier.
POST https://stage.api.payments.depay.us/v2/payments/validations/dictkey
Headers
Authorization*
String
Bearer token
idempotency-key
String
Idempotent identifier to ensure the request is processed only once
Request Body
dict_key*
String
Identifier to validate. Can be a CCI or a phone number with country code
Response
CCI Response Fields
name
String
Account holder’s name
accountNumber
String
Bank account number
identificationNumber
String
Tax identification number
mcc
String
Merchant Category Code or account type
branchOffice
String
Branch office code
category
String
Account category (e.g. CHECKING, SAVINGS)
postalCode
String / Null
Postal code
bank
String
Bank name
terminal
String / Null
Terminal identifier
Phone Response Fields
name
String
Account holder’s name
accountNumber
String
Bank account number
identificationNumber
String
Tax identification number
mcc
String
Merchant Category Code or account type
branchOffice
String
Branch office code
category
String
Account category (e.g. CHECKING, SAVINGS)
postalCode
String / Null
Postal code
bank
String
Bank name
terminal
String / Null
Terminal identifier
walletId
String
Wallet record identifier. Must be sent as wallet_record_id in wallet validation
wallets
Object
List of wallets associated with the phone number
id
String
Wallet identifier (use as selected_wallet_id)
contactNumber
String
Phone number
entityCode
String
Bank entity code
directoryCode
String
Wallet directory code
bankName
String
Wallet or bank name (YAPE, PLIN, BCP, etc.)
Validate Wallet (Phone Only)
POSThttps://stage.api.payments.depay.us/v2/validations/wallet
Required only when the identifier is a phone number. Validates the wallet selected by the user and returns full account information.
Headers
Authorization*
String
Bearer Token
idempotency-key
String
Idempotent identifier
Request Body
wallet_record_id*
String
walletId received from phone validation
selected_wallet_id*
String
Wallet id selected by the user
local_country*
String
ISO 3166-1 alpha-2 country code (e.g. PE)
name
String
Account holder’s name
accountNumber
String
Bank account number
identificationNumber
String
Tax identification number
mcc
String
Merchant Category Code or account type
branchOffice
String
Branch office code
category
String
Account category
postalCode
String/Null
Postal code
bank
String
Bank name
terminal
String/Null
Terminal identifier
wallet_name
String
Selected wallet name (Yape, Plin, etc.)
Validation Flow Summary
CCI Flow
Call /payments/validations/dictkey with the CCI.
Receive complete account information.
Proceed to payment preview.
Phone Flow
Call /payments/validations/dictkey with the phone number.
Receive walletId and available wallets.
Present wallets to the user.
Call /payments/validations/wallet with (Optional):
wallet_record_id
selected_wallet_id
local_country
Receive complete account information.
Proceed to payment preview.
NOTES
Phone validation always requires the additional wallet validation step.
CCI validation is resolved in a single request.
Idempotency is strongly recommended for all validation calls.
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 a CCI or phone number. Once the CCI is received, the system starts processing the transaction. The final result is always sent asynchronously via a webhook that notifies the CCI/PHONE payment event. Additionally, the client may query the operation status directly to confirm the payment outcome if needed.
Headers
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
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)
Response
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.
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.
REFUNDED
The refund has been successfully completed.
Yes
PARTIALLY_REFUNDED
The partial refund has been successfully completed.
No
Headers
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.
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).
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
Authorization*
String
Bearer Token
Query Parameters
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
Last updated