Accept Yape payments

October 16, 2026

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

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.

What your customer’s payment experience looks like

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

From mobile (DEEPLINK)

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

From web or desktop (PUSH)

The payer enters their mobile number at your checkout and receives a push notification in the Yape app, where they approve the purchase from Aprobar compras (“Approve purchases”).

Operation details

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

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

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"
  }
}

curl -X POST "https://api-uat.kushkipagos.com/transfer/v1/tokens" \
  -H "Public-Merchant-Id: <your public credential>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": { "subtotalIva": 0, "subtotalIva0": 54.56, "iva": 10 },
    "currency": "PEN",
    "processor": { "name": "Yape Processor", "flowType": "PUSH" },
    "phoneNumber": "938530546"
  }'

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"
  }
}

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.

Yape-specific rejection codes are not documented yet.

Bank transfer errors are in Error codes for transfers.

Related articles