Accept Yape payments

🚧 Early Release — Beta

This product is in early access. Parameters, response structures and behaviors may change without prior notice. Do not use this version in production without first coordinating with the Kushki integrations team.

Accept payments approved in the Yape app, by redirection or push notification

Yape is one of the APM (alternative payment methods) processors in Peru: instead of redirecting the payer to their online banking, the payment is approved directly in the Yape app, either by direct redirection to the app (DEEPLINK, when the payer buys from mobile) or through a push notification to the payer's Yape number (PUSH, when buying from web or desktop).

Which processors your merchant has is answered by the configuration endpoint (GET /transfer/v1/config) — the full model is in How do APM payments work?. Existing bank transfer integrations do not change: they keep following their bank transfer guide.

Important

Available exclusively for Peru, in soles (PEN), with the Yape processor configured in your MID. To enable it, contact your account executive.

What your customer's payment experience looks like

The experience changes depending on the channel your customer buys from.

From mobile (DEEPLINK)

From web or desktop (PUSH)

The payer buys from their phone, taps Pay with Yape and the Yape app opens directly, where they approve the payment.

Operation details

Parameter	Detail
Currency	PEN
Integration type	100% API — the token is requested from your backend. Kajita and Kushki.js do not support this flow yet.
Additional required field	The `processor` object (`name` + `flowType`) in the token body
Available flows	`DEEPLINK` (mobile) · `PUSH` (web / desktop)
Extra field for the PUSH flow	`phoneNumber` — the payer's mobile number associated with their Yape account
Init result	`deepLink` to redirect the payer (`DEEPLINK`) · send confirmation with `ticketNumber` and `consentId` (`PUSH`)
Bank list query	Not required for this flow

1. Check your processors

This step is optional if Yape is your only processor, but always recommended: it will be the rule as more processors and flows are enabled. Before tokenizing, call Get Transfer In configuration (GET /transfer/v1/config) with your public credential. The Yape entry comes with supportedFlows: copy its name and the chosen flow type into the token's processor object.

{
  "processors": [
    {
      "name": "Yape Processor",
      "currency": "PEN",
      "supportedFlows": [
        { "type": "DEEPLINK", "name": "Deeplink", "description": "Mobile: redirección directa a la app de Yape" },
        { "type": "PUSH", "name": "Push", "description": "Web / Desktop: notificación push al número Yape del pagador" }
      ]
    }
  ]
}

2. Choose the flow according to the payer's channel

`flowType`	Channel	How it works	Additional field
`DEEPLINK`	Mobile	The payer is redirected directly to the Yape app, installed on their phone, to approve the payment.	—
`PUSH`	Web / Desktop	The payer enters their mobile number at your checkout and Yape sends a push notification to their app, where they approve the purchase from the Aprobar compras ("Approve purchases") option.	`phoneNumber` required.

3. Create the token

Make the token request using the same endpoint as the traditional flow (POST /transfer/v1/tokens, with your public credential). Include the processor object with the name and flowType properties, copied exactly from the processor query response.

Required fields

Field	Type	Description
`amount.subtotalIva0`	number	Transaction amount without taxes
`amount.subtotalIva`	number	Taxable amount of the transaction
`amount.iva`	number	VAT value (0 if not applicable)
`currency`	string	Currency. Must be `"PEN"`
`processor.name`	string	Must be `"Yape Processor"`, exactly as returned by the processor query — no short aliases
`processor.flowType`	string	`"DEEPLINK"` or `"PUSH"`. It has no default value: choose according to the payer's channel
`phoneNumber`	string	Only with `flowType: "PUSH"`. The payer's mobile number associated with their Yape account; it is the destination of the push notification

The processor object does not allow additional properties: any other property returns 400.

Optional fields

callbackUrl · documentType · documentNumber · paymentDescription · email

Example with the PUSH flow:

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 54.56,
    "iva": 10
  },
  "currency": "PEN",
  "processor": {
    "name": "Yape Processor",
    "flowType": "PUSH"
  },
  "phoneNumber": "938530546"
}

Example with the DEEPLINK flow:

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 54.56,
    "iva": 10
  },
  "currency": "PEN",
  "processor": {
    "name": "Yape Processor",
    "flowType": "DEEPLINK"
  }
}

4. Initialize the transaction

With the obtained token, call Init Transaction (POST /transfer/v1/init) with your private credential (Private-Merchant-Id), repeating the same amount as the token. The body is the same as the traditional flow; what changes is the response, depending on the flowType you used to generate the token.

{
  "token": "{{token}}",
  "amount": { "subtotalIva": 0, "subtotalIva0": 54.56, "iva": 10 },
  "fullResponse": "v2"
}

The token is bound to the processor it was generated with: if it does not match the processor configured for your merchant, the response is 422 E046. In that case, check the processor query and regenerate the token with the correct processor.

`201` response — `PUSH` flow

Yape sends the push notification to the phoneNumber you sent in the token. The response confirms it was sent; the payer approves the payment from the Yape app.

{
  "ticketNumber": "9748463867065188",
  "consentId": "4d09b123-84c4-4363-955e-70ac1e58d8e6",
  "transactionReference": "d0d07647-3866-4f95-8cbd-87d46ce08658",
  "details": {
    "status": "initializedTransaction",
    "amount": { "currency": "PEN", "iva": 10, "subtotalIva": 0, "subtotalIva0": 54.56 },
    "created": 1789747994247,
    "description": "-",
    "merchantId": "20000000100000000001",
    "merchantName": "COMERCIO DEMO PERU"
  }
}

`201` response — `DEEPLINK` flow

The response also includes deepLink. Redirect the payer to that URL exactly as received, without modifying its parameters: in the mobile browser it opens the Yape app, where they approve the payment.

{
  "ticketNumber": "9748582884405310",
  "consentId": "ec9cd71c-63e7-4c58-9860-7589c587adc0",
  "transactionReference": "4ff5221b-8ad8-4728-b35f-cc9d45315f54",
  "deepLink": "https://www.yape.com.pe/app/checkout/oneshotpayment?origin=deeplink-externo&consentId=ec9cd71c-63e7-4c58-9860-7589c587adc0&partnerCode=PEX022",
  "details": {
    "status": "initializedTransaction",
    "amount": { "currency": "PEN", "iva": 10, "subtotalIva": 0, "subtotalIva0": 54.56 },
    "created": 1789748578782,
    "description": "-",
    "merchantId": "20000000100000000001",
    "merchantName": "COMERCIO DEMO PERU"
  }
}

Field	Flow	Description
`ticketNumber`	`PUSH`, `DEEPLINK`	Ticket number of the transaction in Kushki.
`consentId`	`PUSH`, `DEEPLINK`	Identifier (UUID) of the payment consent in Yape. It allows you to correlate the payer's approval.
`deepLink`	`DEEPLINK`	Link to the Yape checkout. Use it exactly as received.
`transactionReference`	Both	Identifier of the transaction in Kushki. Use it to correlate the webhook with your order.
`details`	Both	Only with `fullResponse: "v2"`: status, amount, creation date and merchant data.

Flow	What you do with the response
`PUSH`	Ask the payer to approve the notification they received in their Yape app.
`DEEPLINK`	Redirect the payer to the `deepLink`.

5. Wait for the payment result

The payer approves (or not) the payment in the Yape app. The final status — approved, declined or expired — reaches you through the webhook configured for your merchant; you can also query it with Get Status (GET /transfer/v1/status/{token}). Use transactionReference to correlate the notification with your order.

6. Errors

When operating with the multiprocessor flow you may receive API errors when querying processors, tokenizing, or initializing the transaction. The error response fields are code and message.

Endpoint	HTTP	Code	When does it happen?	What should the merchant do?
`GET /transfer/v1/config`	`500`	`E002`	Error querying the merchant configuration. Message: «Ha ocurrido un error inesperado.»	Retry; if it persists, contact support.
`POST /transfer/v1/tokens`	`400`	—	The body does not meet the contract: missing required field (including `phoneNumber` in Yape `PUSH`), value outside the enumeration (`processor.name`, `processor.flowType`) or a property not allowed inside `processor`.	Fix the body according to the processor query and the contract of the chosen flow.
`POST /transfer/v1/init`	`422`	`E046`	The token is not compatible with the resolved processor (e.g., a token with `processor` and a merchant with another processor, or a traditional token and a merchant with Yape).	Check the processor query and regenerate the token with the correct processor.
All	`401`	—	Invalid or missing public or private credential.	Check your credentials.

Yape rejections. When Yape declines a transaction, it returns code 006 with the message "Transacción declinada" (Declined transaction). It is the only rejection code and is returned in every case, so it does not identify the reason.

Receive bank transfers

Traditional bank transfer integration

What your customer's payment experience looks like#

Operation details#

1. Check your processors#

2. Choose the flow according to the payer's channel#

3. Create the token#

4. Initialize the transaction#

201 response — PUSH flow#

201 response — DEEPLINK flow#

5. Wait for the payment result#

6. Errors#

Related articles#

What your customer's payment experience looks like

Operation details

1. Check your processors

2. Choose the flow according to the payer's channel

3. Create the token

4. Initialize the transaction

`201` response — `PUSH` flow

`201` response — `DEEPLINK` flow

5. Wait for the payment result

6. Errors

Related articles