Transfer In

Transfer In collects payments directly from a customer's bank account, with no card. In Peru it runs on processors, the traditional bank-portal flow and Yape, through the same endpoints under /transfer/v1. Every integration starts by asking which processors the merchant has.

Endpoints

Endpoint	Method and path	Credential	Purpose	Used by
Get Transfer In configuration	`GET /transfer/v1/config`	Public	Start here. Lists the processors enabled for the merchant and, when applicable, the `supportedFlows` of each one	All
Get Bank List	`GET /transfer/v1/bankList`	Public	Supported banks (`code`, `name`)	Traditional
Request a Transfer In Token	`POST /transfer/v1/tokens`	Public	Creates a single-use token	All
Init Transaction	`POST /transfer/v1/init`	Private	Starts the transaction with the token	All
Get Status	`GET /transfer/v1/status/{token}`	Private	Final status of the transaction	All

Integration flow

Get the processors

Call Get Transfer In configuration with the Public-Merchant-Id credential. processors[] lists the processors enabled for the merchant. This is the starting point of every direct API integration.

Choose the processor

An entry without supportedFlows is the traditional processor. An entry with supportedFlows is a processor with payment flows (Yape), and you also choose the flow. If the merchant has several, use the supportedFlows of each entry to decide how to build each token.

Request the token

The body depends on the processor; see Processors at a glance below. Tokens are single-use.

Init the transaction

Send the token and repeat the same amount. The response depends on the processor: redirectUrl (traditional), or ticketNumber and consentId (Yape), plus deepLink with DEEPLINK.

Confirm the final status

Through the webhook or with Get Status.

Kajita and Kushki.js

These tools do not support the processor object: with them there is no processor query and tokenization follows the traditional process. Yape requires a direct API integration, where the token is requested from your backend.

Processors at a glance

Processors with payment flows, like Yape, are also referred to as APM (alternative payment methods).

	Traditional	Yape
Identified by	`config` entry without `supportedFlows`	`config` entry with `supportedFlows`
Token request	`amount`, `currency` and `callbackUrl` required; `bankId`, `userType`, `documentType`, `documentNumber`, `email` and `paymentDescription` optional. No `processor` object.	`amount`, `currency` and `processor: { name, flowType }`, copied verbatim from `config`; plus `phoneNumber` in `PUSH`.
Bank list	Optional: without `bankId`, the customer picks the bank at the bank portal	Not used
`init` response	`redirectUrl`	`deepLink` (`DEEPLINK`) or the push confirmation (`PUSH`), both with `ticketNumber` and `consentId`
Customer experience	Completes the payment at their bank's online portal	Approves the payment in the Yape app: direct redirection from mobile (`DEEPLINK`), or push notification from web or desktop (`PUSH`)
Currency	`PEN` or `USD`	`PEN`
Integration types	Direct API, Kajita, Kushki.js	Direct API only
Availability	General	Beta, on merchants with the processor enabled

The token is bound to the processor it was generated with, and Init Transaction validates it:

Generated token	Merchant's processor	Result
Without `processor`	Traditional	Continues; the response includes `redirectUrl`.
With Yape `processor`	Yape	Continues; the response includes `ticketNumber` and `consentId` (and `deepLink` with `DEEPLINK`).
With `processor`	Another processor	`422 E046`
Without `processor`	Yape	`422 E046`

Processor details

Traditional

Yape (Beta)

Token request fields

Field	Required	Description
`bankId`	No	Code of the destination bank. If omitted, the customer selects the bank at the bank portal.
`amount`	Yes	Payment amount breakdown (`subtotalIva`, `subtotalIva0`, `iva`).
`currency`	Yes	`PEN` or `USD`.
`callbackUrl`	Yes	URL where the customer returns after the payment, completed or abandoned.
`documentType`	No	Customer's document type.
`documentNumber`	No	Customer's document number. Required if `documentType` is provided.
`email`	No	Customer's email address.
`userType`	No	`0` = natural person, `1` = company.
`paymentDescription`	No	Free-text description shown to the customer at the bank portal.

{
  "bankId": "1022",
  "amount": { "subtotalIva": 0, "subtotalIva0": 150.00, "iva": 0 },
  "currency": "PEN",
  "callbackUrl": "https://yoursite.com/payment/return",
  "userType": "0",
  "documentType": "DNI",
  "documentNumber": "12345678",
  "email": "user@example.com",
  "paymentDescription": "Order #1234"
}

The init response returns the redirectUrl to send the customer to:

{
  "redirectUrl": "https://api.kushkipagos.com/transfer/v1/agent?token=...",
  "transactionReference": "28e6ac31-0af1-479a-9a6f-1a596bba6aea"
}

Currencies

Currency	Code
Peruvian Sol	`PEN`
US Dollar	`USD`

Document types

Value	Description
`DNI`	Documento Nacional de Identidad 🇵🇪
`CE`	Carné de Extranjería 🇵🇪
`PAS`	Pasaporte 🇵🇪
`RUC`	Registro Único de Contribuyentes 🇵🇪

User types

Value	Description
`0`	Natural person
`1`	Company

Init request fields

Field	Required	Description
`token`	Yes	Token returned by the token endpoint.
`amount`	Yes	Amount breakdown including `currency`. Must match the amount used to tokenize.
`expirationDate`	No	Expiration date and time of the transaction. Peru only.
`webhooks`	No	Array of URLs to notify when the transaction status changes.
`fullResponse`	No	`"v2"` returns the complete transaction details.
`metadata`	No	Custom key-value pairs for your own tracking.

{
  "token": "V0OzRB100000xhxQB8035251pHLBQsq5",
  "amount": { "subtotalIva": 0, "subtotalIva0": 150.00, "iva": 0, "currency": "PEN" },
  "fullResponse": "v2"
}

Statuses

Confirm the final result with Get Status (GET /transfer/v1/status/{token}). The webhook and the statuses are the same for every processor.

Status	Meaning
`approvedTransaction`	Payment completed successfully.
`declinedTransaction`	Payment rejected by the bank or by the processor.
`initializedTransaction`	Payment still pending.
`expiredTransaction`	Token or session expired without payment.

Webhooks

Include a webhooks array in the init request to receive status notifications in real time:

{
  "webhooks": ["https://yoursite.com/kushki/notify"]
}

Errors

Processor	Endpoint	HTTP	Code	When it happens	What to do
All	`GET /transfer/v1/config`	`500`	`E002`	Error querying the merchant configuration («Ha ocurrido un error inesperado.»).	Retry; contact support if it persists.
Yape	`POST /transfer/v1/tokens`	`400`	—	The body does not meet the contract: missing required field (including `phoneNumber` with `PUSH`), value outside the enum (`processor.name`, `processor.flowType`), or extra property inside `processor`.	Fix the body according to `config`.
All	`POST /transfer/v1/init`	`422`	`E046`	The token is not compatible with the resolved processor.	Regenerate the token for the right processor.
All	Any	`401`	—	Missing or invalid credential.	Check `Public-Merchant-Id` or `Private-Merchant-Id`, depending on the endpoint.

Yape-specific rejection codes are not documented yet.

Authentication and environments

Credentials are sent in a header; each endpoint uses one of them (see the Credential column above):

Header	Credential	Use
`Public-Merchant-Id`	Public	Configuration, bank list and tokenization. Safe for backends and, in the traditional flow, for client tools.
`Private-Merchant-Id`	Private	Init, status and cancellation. Never expose it in frontend code.

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints#

Integration flow#

Processors at a glance#

Processor details#

Currencies#

Document types#

User types#

Init request fields#

Statuses#

Webhooks#

Errors#

Authentication and environments#

Endpoints

Integration flow

Processors at a glance

Processor details

Currencies

Document types

User types

Init request fields

Statuses

Webhooks

Errors

Authentication and environments