Peru

The necessary information for Peru is presented below in order to carry out a correct payout.

Mandatory parameters

Field

Description

country

String (Required- Lenght: 3 characters)

ISO 3166-1-alpha-3. In the case of Peru: PER

amount

Integer (Required max-lenght = 10 digits)

The amount of the transaction. The 2 last digits will be consider as decimal. Ex: 100000 equals "one thousand"

currency

String (Required- Lenght: 3 digits)

The currency of the payroll. ISO-4217. In the case of PER: PEN o USD You can see the explication on Currencies

orderId

String (Required- Max Lenght: 20 characters)

Merchant transaction code. This ID must be unique per transaction.

description

String (Optional - Max Lenght: 50 characters)

For customer use. This is the name that will appear in the payment reference for transfers to YAPE (037) and it´s mandatory.

beneficiary.name

String (Required)

Name of the Beneficiary

beneficiary.lastName

String (Required)

Last name of the Beneficiary

beneficiary.email

String (Optional- Max Lenght: 50 characters)

Beneficiary's email. It is mandatory if account type is "Card". Do not send a dummy value.

beneficiary.document.type

Integer (Required)

Contains the beneficiary's document type. You must enter the parameter as indicated in "Document Validations"

beneficiary.document.number

String (Required)

Contains the beneficiary's document number. You can see how many digits must it have in "Document Validations"

destination.bankAccount.bankCode

String (Optional - Lenght: 3 characters)

Code of the receiving bank or financial institution as indicated in "Bank List". It is mandatory if account type is "Cellphone Number (4)".

destination.bankAccount.accountType

Integer (Required) Type of Account of the beneficiary to pay. You must enter the numeric code.

destination.bankAccount.accountNumber

Integer (Optional) Beneficiary's account number. In the case of account type is "Cellphone Number"(4), the merchant have to send the phone number. Ex: 948474375

destination.bankAccount.cci

Integer (Required - Lenght: 20 digits)

"Codigo de Cuenta Interbancaria (CCI)". Interbanking number account.

subMerchantInfo.code

String (Required only for PSP) Submerchant Identifier

subMerchantInfo.name

String (Required only for PSP) Submerchant Name. This is the name that will appear in the payment reference for transfers to YAPE (037) and it´s mandatory.

subMerchantInfo.url

String (Required only for PSP) Submerchant URL

TimeoutURL

String (Required only for AccountType "Card")

The URL of the merchant's application used to redirect the user in the event of a timeout during the payment process."

merchantLogo

String (Optional)

URL of the merchant’s logo to be displayed on the webpayment form (AccountType "Card"). Including a logo is highly recommended for branding purposes. Suggested dimensions: 187x40px.

expirationTime

String (Optional)

The duration of the tokenization session (AccountType "Card") in minutes (Min 5 min - Max 30 min). After this time elapses, the session will expire and the process must be restarted.

New Feature:

Email Notification to the Beneficiary

It is now possible to automatically send emails to the beneficiary with the outcome of the Payout (success or rejected).

Requirements:

Request the activation of "Email notifications to the user" through your account manager.
Include the beneficiary.email parameter in each transaction. If this field is missing, the email will not be sent.

IMPORTANT

For Account Type "Cellphone Number" the only currency available is "PEN"
For Account Type "Cellphone Number" it's mandatory the parameter "bankCode"
For Account Type "Cellphone Number", the maximum amount allowed is 500 PEN. However, if the wallet is Yape, the maximum amount allowed is 3,500 PEN. For other Account Types, the maximum amount allowed is 30,000 PEN.
We offer payments to real-time entities and non-real-time entities, applying the appropriate treatment in each case.
Real-time payments: The CCI (destination.bankAccount.cci) is a mandatory field.
Non-real-time payments: These are processed as interbanking transfers, subject to the applicable processing times indicated in the SLA.

IMPORTANT

Card Pushpayment (Available from Q3 2025)

This is a new payout method which enables real-time fund transfers to VISA credit, debit, or prepaid cards. This solution operates under the OCT (Original Credit Transfer) standard, allowing for secure and direct payments to cards. To use this service, a specific configuration must be requested and coordinated in advance with your account manager.

To use Card Pushpayment service, merchants must consume the dedicated Create Card Pushpayment endpoint (Review our documentation), which is exclusively intended for accountType = 5 (Card). ⚠️ Do not use the Create Payout endpoint for this type of transaction.

Key implementation considerations:

The "Create Card Pushpayment" endpoint responds with an HTML template that must be embedded by the merchant within an iFrame. This template renders the payment form where the user inputs their card information.
The parameter Account Type must be sent with the value 5 (Card).
The parameter email is mandatory and must belong to the cardholder. Do not send dummy or placeholder data.
The parameters bankCode , bankAccount.cci and bankAccount.accountNumber are optional.
The Card on File functionality is enabled by default. It allows storing the user's card for future withdrawals, eliminating the need to re-register the card for each transaction. This feature can be disabled if needed, in which case the card registration will be required for every transaction.

Request Example

Payout example for Bank Transfer

{
	"country": "PER",
	"amount": 100000,
	"currency": "PEN",
	"orderId": "R123456",
	"description": "FreeTextFreeTextFreeTextFreeText",
	"beneficiary": {
		"name": "Sergio",
		"lastName": "test",
		"email": "[email protected]",
		"document": {
			"type": 1,
			"number": "12345678"
		}
	},
	"destination": {
		"bankAccount": {
			"bankCode": "002",
			"accountType": "1",
			"cci": "00243000584290204477"
		}
	}
}

Payout example for Cellphone Number (Wallets)

{
	"country": "PER",
	"amount": 100000,
	"currency": "PEN",
	"orderId": "R123456",
	"description": "FreeTextFreeTextFreeTextFreeText",
	"beneficiary": {
		"name": "Sergio",
		"lastName": "test",
		"email": "[email protected]",
		"document": {
			"type": 1,
			"number": "12345678"
		}
	},
	"destination": {
		"bankAccount": {
			"bankCode": "037",
			"accountType": "4",
			"accountNumber": "938267873"
		}
	}
}

Card Pushpayment example

{
  "country": "PER",
  "amount": 50001,
  "currency": "PEN",
  "orderId": `XYZ12345`,
  "beneficiary": {
    "name": "Juan",
    "lastName": "Prueba",
    "email": "[email protected]",
    "document": {
      "type": 4,
      "number": "20629932888"
    }
  },
  "destination": {
    "bankAccount": {
      "accountType": 5,
    }
  },
  "timeoutUrl": "https://www.test.com",
  "merchantLogo": "https://www.test.com",
  "expirationTime": "03"
}

Time Outs

In the case of receiving a Time Out as a response from this API we recommend resending the payout again after 30 seconds using the same orderId.

This way we will check if the payout was processed and avoid double payments.

Document Validations

Parameter

ID Type

Lenght

DNI

8 digits

PAS

7 - 12 digits

8 - 12 digits

RUC

11 digits

Account Type

Parameter

Type

Current Account

Savings Account

Cellphone Number (Wallets)

Card (Exclusive for "Create Card Pushpayment" endpoint)

In the "Account Type - Cellphone Number" field, the corresponding cellphone number must be entered to process the payout correctly.
The payout can be made not only to wallets (Yape, Plin, Bim) but also to financial entities (Bank List) associated with the cellphone number. For example, a cellphone number could have 3 entities associated: "Yape", "Plin" and "Banco Pichincha".

Account Number Information

Bank

Description

Banco BBVA (001)

Field “accountNumber” must contain 18 or 20 digits EX: 001106660100012345 (18 digits) EX: 00110666010001234512 (20 digits)

Banco de Credito (002)

Field “accountNumber” must contain: - 13 digits for Current or Master Account - 14 digits for Savings Account

Interbank (003)

Field “accountNumber” must contain 13 digits

Scotiabank (004)

Field “accountNumber” must contain 10 digits 0037651234 (10 digits: 3 agency + 7 account)

For any other bank or financial institution

A 20-digit CCI interbank account code must be entered. Example: 00219400254640654321 (20 digits)

Wallets (Yape,Plin, Bim, CCE directory)

Field “accountNumber” must contain 9 digits and start with "9".

Bank List

Below are the entities we support according to the processing time (real-time or batch).

Last updated 1 month ago