# MD for: https://www.mercadopago.com.pe/developers/pt/docs/checkout-api-orders/payment-integration/websites/yape.md

\# Yape With Mercado Pago's Checkout API, you can offer payments with \*\*Yape\*\*. With this payment method, the buyer generates a one-time password (OTP) directly in the Yape application, which the integrator converts into a secure token to complete the transaction, with no external redirect and no need for a physical card. Unlike deferred payment methods, \*\*Yape is processed synchronously when the order is created in automatic mode\*\*, which means the order creation response already includes the final payment result, confirming the transaction in real time. If you already have the \[development environment\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/development-environment) set up and want to offer Yape as a payment method, follow the steps below. > NOTE > > Remember: before setting up the payment methods, choose the way you will process your transactions. The processing mode, whether \*\*manual or automatic\*\*, will be defined at the time of order creation, using the \`processing\_mode\` parameter. For more information, visit the section \[Integration Model\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/integration-model).   
\> For Yape payments, the chosen order processing mode directly affects how to proceed if you need to \[cancel the payment\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-integration/websites/yape#bookmark\_cancel\_payment). :::::AccordionComponent{title="Add payment form" pill="client-side"} To receive payments, add a form to the frontend that captures the phone number and the OTP that the buyer generates in the Yape application. If you already have a development that includes your own payment form, make sure to include Yape among the payment options you want to offer, as shown below, and continue to the \[Create Yape token\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-integration/websites/yape#bookmark\_create\_yape\_token) step. If you do not have a payment form yet, add the template below to your project and include the Yape identifier as an option to be offered. | Payment method | \`payment\_method\_id\` | |:---:|:---:| | Yape | \`yape\` | \`\`\`html 

Phone number 

OTP 

Pay with Yape 

\`\`\` ::::: :::::AccordionComponent{title="Create Yape token" pill="client-side"} The Yape token is created from the phone number and the OTP (One-Time Password) sent in the request, increasing security during the payment flow. Once the token is used in a given purchase, it is discarded, requiring the creation of a new one for future purchases. You can create it with MercadoPago.js or through a direct API call. ::::TabsComponent :::TabComponent{title="MercadoPago.js"} With MercadoPago.js already added and initialized as described in \[Configure development environment\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/development-environment), capture the form data and create the token with the \`mp.yape\` method. \`\`\`javascript const form = document.getElementById("form-checkout"); form.addEventListener("submit", async (event) => { event.preventDefault(); const otp = document.getElementById("form-checkout\_\_payerOTP").value; const phoneNumber = document.getElementById("form-checkout\_\_payerPhone").value; const yape = mp.yape({ otp, phoneNumber }); const yapeToken = await yape.create(); // Send yapeToken.id to your server to create the order. }); \`\`\` In this flow, MercadoPago.js generates the \`requestId\` automatically. ::: :::TabComponent{title="API"} Alternatively, send a request with your :toolTipComponent\[test Public Key\]{content="Public key of the application created in Mercado Pago, used in the frontend. You can access it through Your integrations > Integration data > Tests > Test credentials."} and the parameters listed below to the :TagComponent{tag="POST" text="/platforms/pci/yape/v1/payment" href="https://api.mercadopago.com/platforms/pci/yape/v1/payment?public\_key={{YOUR\_PUBLIC\_KEY}}" color="green"} endpoint. \`\`\`curl curl --location --request POST 'https://api.mercadopago.com/platforms/pci/yape/v1/payment?public\_key={{YOUR\_PUBLIC\_KEY}}' \\ --header 'Content-Type: application/json' \\ --data-raw '{ "phoneNumber": "111111111", "otp": "123456", "requestId": "aaaaaaaa-bbbb-1ccc-8ddd-eeeeeeeeeeee" }' \`\`\` | Parameter | Type | Description | Required | |---|---|---|---| | \`public\_key\` | Query param. String | Your :toolTipComponent\[test Public Key\]{content="Public key of the application created in Mercado Pago, used in the frontend. You can access it through Your integrations > Integration data > Tests > Test credentials."}, sent in the request URL. | Required | | \`phoneNumber\` | Body. String | Phone number of the person responsible for managing the Yape application and generating the OTP. | Required | | \`otp\` | Body. String | 6-digit OTP generated in the Yape application. | Required | | \`requestId\` | Body. String | Unique identifier that you must generate for each tokenization request. We recommend using UUID v4 format. | Required | If successful, you will receive a response with the data of the generated token. The \`id\` returned in the response is the token that must be sent to your server to create the order. \`\`\`json { "live\_mode": true, "luhn\_validation": null, "require\_esc": null, "cloned": false, "cardholder": { "identification": { "number": null, "type": null, "subtype": null }, "name": "yape" }, "security\_code\_id": 8069792005119486812, "security\_code\_length": 6, "card\_number\_length": 9, "expiration\_month": 8, "expiration\_year": 2026, "card\_present\_id": null, "card\_id": null, "client\_id": 7775327892346559, "present": null, "id": "45d013f72bf42717a1625f4c508fc20f", "card\_number\_id": "FFTSHQTOSJTXGFVFGJKCBAIVOUISTFZBDRTQWLYJ", "creation\_date": null, "due\_date": null, "last\_modified\_date": null, "product\_id": null, "trust\_level": "unknown", "public\_key": "YOUR\_PUBLIC\_KEY", "site\_id": "MPE", "status": "active", "transaction\_id": null, "trunc\_card\_number": null, "used\_date": null, "bin": "111111", "version": 0, "client\_header": null, "first\_six\_digits": "111111", "last\_four\_digits": "1111" } \`\`\` > WARNING > > Generate a new token for each payment attempt, as it expires after the first use. ::: :::: ::::: :::::AccordionComponent{title="Submit payment" pill="server-side"} The payment must be submitted by creating an order that contains the associated payment transaction. > NOTE > > Yape is processed synchronously when the order is created in automatic mode, which means the order creation response already includes the final payment result. Even so, we recommend setting up \[Order topic notifications\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/notifications) to keep your system in sync with any later updates, such as refunds, and also \[Chargebacks topic notifications\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-management/chargebacks/notifications) for possible payment chargebacks. To do this, send a request with your :toolTipComponent\[test Access Token\]{content="Private key of the application created in Mercado Pago, used in the backend. Access it at Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the \`APP\_USR\` prefix."} and the parameters listed below to the :TagComponent{tag="POST" text="/v1/orders" href="/developers/en/reference/online-payments/checkout-api/create-order/post" color="green"} endpoint. \`\`\`curl curl --location --request POST 'https://api.mercadopago.com/v1/orders' \\ --header 'Content-Type: application/json' \\ --header 'Authorization: Bearer {{YOUR\_ACCESS\_TOKEN}}' \\ --header 'X-Idempotency-Key: {{SOME\_UNIQUE\_VALUE}}' \\ --data-raw '{ "type": "online", "external\_reference": "ext\_ref\_1234", "processing\_mode": "automatic", "total\_amount": "100.00", "payer": { "email": "test\_user\_pe@testuser.com", "entity\_type": "individual", "identification": { "type": "DNI", "number": "12345678" }, "phone": { "area\_code": "51", "number": "987654321" } }, "transactions": { "payments": \[ { "amount": "100.00", "payment\_method": { "id": "yape", "type": "debit\_card", "token": "{{YOUR\_YAPE\_TOKEN}}" } } \] } }' \`\`\` > NOTE > > Order creation is subject to per-client request limits. If you receive a \`429 Too Many Requests\` error, wait the time indicated in the \`Retry-After\` response header before retrying. See \[Possible errors\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-management/integration-errors) for more details. See in the table below the descriptions of the parameters that are required in the request and of those that, although optional, have some particularity worth highlighting. | Parameter | Type | Description | Required | |---|---|---|---| | \`Authorization\` | Header | Refers to your private key, the :toolTipComponent\[test Access Token\]{content="Private key of the application created in Mercado Pago, used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the \`APP\_USR\` prefix."}. | Required | | \`X-Idempotency-Key\` | Header | Idempotency key. This key ensures that each request is processed only once, avoiding duplicates. Use a unique value in the request \`header\`, such as a UUID V4 or a random string. | Required | | \`processing\_mode\` | Body. String | Order processing mode. The possible values are:   
  
 \- \`automatic\`: to create and process the order in automatic mode.   
  
 \- \`manual\`: to create the order and process it later.   
  
 For more information, visit the section \[Integration Model\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/integration-model). | Required | | \`total\_amount\` | Body. String | Total transaction amount. Must be greater than 0\. The maximum amount per transaction may be S/ 500, S/ 900, or S/ 2,000, depending on the limit configured in the Yape application. | Required | | \`payer.email\` | Body. String | Buyer's email. | Required | | \`payer.identification.type\` | Body. String | Buyer's document type. For Peru: \`DNI\`, among others. | Optional | | \`payer.identification.number\` | Body. String | Buyer's identification number. | Optional | | \`payer.phone.area\_code\` | Body. String | Buyer's phone area code. For Peru, use \`51\`. | Required | | \`payer.phone.number\` | Body. String | Buyer's phone number associated with Yape. | Required | | \`transactions.payments.payment\_method.id\` | Body. String | Payment method identifier. The value must be \`yape\`. | Required | | \`transactions.payments.payment\_method.type\` | Body. String | Payment method type. The value must be \`debit\_card\`. | Required | | \`transactions.payments.payment\_method.token\` | Body. String | Yape token generated in the \[previous step\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-integration/websites/yape#bookmark\_create\_yape\_token) and single-use. Generate a new token for each payment attempt. | Required | > SUCCESS\_MESSAGE > > To learn in detail about all the parameters sent and returned in this request, see our :TagComponent{tag="API" text="API Reference" href="/developers/en/reference/online-payments/checkout-api/overview" color="accent"}. Also, if you receive an error when submitting the payment, see our \[error list\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-management/integration-errors) for more information. After successfully creating the order, you will receive a response with \`status: processed\` and \`status\_detail: accredited\`, indicating that the payment was approved. \`\`\`json { "id": "ORDPE01EXAMPLEPE1234NCAKKBF68N64S", "type": "online", "processing\_mode": "automatic", "external\_reference": "ext\_ref\_1234", "total\_amount": "100.00", "total\_paid\_amount": "100.00", "country\_code": "PER", "user\_id": "1234567890", "status": "processed", "status\_detail": "accredited", "capture\_mode": "automatic\_async", "currency": "PEN", "created\_date": "2026-07-29T21:03:42.252Z", "last\_updated\_date": "2026-07-29T21:03:43.985Z", "integration\_data": { "application\_id": "1234567890123456" }, "transactions": { "payments": \[ { "id": "PAYPE01EXAMPLEPE1234BSAR5ZWXX5YZG", "reference\_id": "1234567890", "amount": "100.00", "paid\_amount": "100.00", "status": "processed", "status\_detail": "accredited", "payment\_method": { "id": "yape", "type": "debit\_card" } } \] } } \`\`\` Since \*\*Yape is processed synchronously when the order is created in automatic mode\*\*, there is no buyer redirect. Among the returned parameters, the following are highlighted in the table below. | Parameter | Type | Description | |---|---|---| | \`transactions.payments.status\` | String | Returns the transaction status. In this case, it returns \`processed\` to indicate the payment was processed, or \`failed\` if it was rejected. | | \`transactions.payments.status\_detail\` | String | Transaction status detail. In this case, the value obtained is \`accredited\`, indicating the payment was approved. | | \`transactions.payments.paid\_amount\` | String | Amount effectively paid in the transaction. | > WARNING > > If you have created the order in manual mode, remember that payment processing requires an additional step, sending a request to the :TagComponent{tag="POST" text="Process order" href="/developers/en/reference/online-payments/checkout-api/process-order/post" color="green"} endpoint. ::::: :::::AccordionComponent{title="Cancel payment" pill="server-side"} Depending on the mode in which the order is created (\*\*automatic\*\* or \*\*manual\*\*), a Yape payment can be processed in two different ways and, consequently, so can its cancellation. See below how to proceed in each situation: - \*\*Automatic mode\*\*: the \*\*order is created in automatic mode and the Yape payment is processed synchronously\*\* (\`status=processed\`). As a result, the order creation response already returns the final payment result, and it is not possible to cancel it once approved (\`status\_detail=accredited\`). In this case, \*\*you will need to carry out a refund process\*\* through a request to the :TagComponent{tag="POST" text="/v1/orders/{order\_id}/refund" href="/developers/en/reference/online-payments/checkout-api/refund-order/post" color="green"} endpoint.   
  
\- \*\*Manual mode\*\*: the \*\*order is created in manual mode and payment processing requires an additional step\*\* (\`status=action\_required\`) at the :TagComponent{tag="POST" text="Process order" href="/developers/en/reference/online-payments/checkout-api/process-order/post" color="green"} endpoint. In this case, \*\*before processing the payment you will be able to cancel it\*\* through a request to the :TagComponent{tag="POST" text="/v1/orders/{order\_id}/cancel" href="/developers/en/reference/online-payments/checkout-api/cancel-order/post" color="green"} endpoint. For more information, see the \[Refunds and cancellations\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-management/refunds-cancellations) section. :::::