Attributes

• METHOD TYPEE-wallet
• PAYMENTS
• PAYOUTS
• REFUNDS
• RECURRING

Introduction

Yape is a mobile payments platform developed by Banco de Crédito del Perú (BCP), one of Peru’s largest banks. It allows users to make instant payments and transfers using their smartphones. Yape is widely used for both personal and commercial transactions due to its convenience, speed, and low fees. A user can link bank accounts or debit cards to the application and make payments by scanning QR codes, entering phone numbers, or selecting contacts from the user’s phone. Yape has become a popular tool for facilitating cashless transactions in the Peruvian market.

Supported Countries

• Peru

Supported Currencies

• PEN

REST API

Payment (Deposit) Flow

Follow these steps to perform a payment using Nuvei REST API integration:

1. Generate a sessionToken

Press here for details.

2. Send a /payment Request

Perform the payment by sending a /payment request with its mandatory parameters including:

• userTokenId
• amount
• currency
• paymentOption.alternativePaymentMethod class containing:
  • paymentMethod: “apmgw_Yape“
• deviceDetails class containing: ipAddress
• billingAddress class containing: firstName, lastName, country, email
• userDetails class containing: firstName, lastName, country, email

Example /payment Request

POST to {{url}}/ppp/api/payment.do
{
    "sessionToken": "{{sessionTokenId}}",
    "merchantId": "{{merchantId}}",
    "merchantSiteId": "{{merchantSiteId}}",
    "userTokenId": "TEST1234SKKSKS",
    "paymentOption": {
        "alternativePaymentMethod": {
            "paymentMethod": "apmgw_Yape",
            "yape_personalId": "40009021"
        }
    },
    "currency": "PEN",
    "amount": "50",
    "deviceDetails": {},
    "device": {
        "type": "SMARTPHONE",
        "name": "string",
        "os": "",
        "browser": "string",
        "ipAddress": "string"
    },
    "billingAddress": {
        "firstName": "Bolson STG",
        "lastName": "Remesas",
        "email": "[email protected]",
        "phone": "918865511",
        "dateOfBirth": "1985-01-01",
        "address": "Peachtree Dunwoody Rd",
        "city": "Atlanta",
        "zip": "30328",
        "state": "GA",
        "country": "PE",
        "language": "en"
    },
    "userDetails": {
        "firstName": "Bolson STG",
        "lastName": "Remesas",
        "email": "[email protected]",
        "phone": "918865511",
        "dateOfBirth": "1985-01-01",
        "address": "Peachtree Dunwoody Rd",
        "city": "Atlanta",
        "zip": "30328",
        "state": "GA",
        "country": "PE",
        "language": "en"
    },
    "timeStamp": "{{timestamp}}",
    "checksum": "{{checksum}}",
    "merchantData": {
        "dynamicDescriptor": "dynamicDescriptor2222"
    },
    "dynamicDescriptor": {
        "merchantName": "dynamicDescriptor333333",
        "merchantPhone": "merchantPhone"
    }
}

Example /payment Response

{
    "internalRequestId": 1761204888308,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "1102398682906145682",
    "merchantSiteId": "228311",
    "version": "1.0",
    "sessionToken": "f266182a53ee4a909a04cd32c63700ff0111",
    "orderId": "263144111",
    "userTokenId": "TEST1234SKKSKS",
    "paymentOption": {
        "redirectUrl": "https://apmtest.gate2shop.com/ppp/resources/cdn/v1/payment-details-22193.html?methodName=yape&mode=numeric&language=es&paymentNumber=NY669613&agreement=20100047218&paymentAmount=50.00&currency=PEN&transactionId=2610000000669613&transactionStatus=PENDING&purchaseDate=2025-10-23T02%3A34%3A49Z&expirationDate=2025-10-24T23%3A59%3A59Z&description=dynamicDescriptor333333&buyerName=Bolson%20STG%20Remesas&[email protected]&buyerPhone=918865511&documentId=NY669613&personalId=40009021",
        "userPaymentOptionId": "230497586111",
        "card": {}
    },
    "transactionStatus": "REDIRECT"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to the URL provided in urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.

Payout (Withdrawal) Flow

After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided in urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

Example Request for {{url}}/ppp/api/createCashierUser.do

{
{
    "merchantSiteId": "{{merchantSiteId}}",
    "internalRequestId": 1759910234109,
    "merchantId": "{{merchantId}}",
    "status": "SUCCESS",
    "userTokenId": "testsecondmethod121",
    "errCode": 0,
    "clientRequestId": "{{clientRequestId}}",
    "reason": "",
    "timeStamp": "{{timestamp}}",
    "merchantId": "1102398682906145682",
    "firstName": "Bolson STG",
    "merchantSiteId": "228311",
    "lastName": "Remesas",
    "version": "1.0",
    "address": "some street",
    "clientRequestId": "20251008105713",
    "email": [email protected],
    "userId": 1267730111
    "zip":"3032",
}
    "city": "Atlanta",
    "countryCode": "PE",
    "phone":"51918865511",
    "dateOfBirth": "0001-01-01",
    "checksum": "{{checksum}}"
}

Example Request for {{url}}/ppp/api/addUPOAPM.do

{
    "merchantSiteId": "{{merchantSiteId}}",
    "merchantId": "{{merchantId}}",
    "merchantId": "{{merchantId}}",
    "userTokenId": "testsecondmethod121",
    "clientRequestId": "{{clientRequestId}}",
    "timeStamp": "{{timestamp}}",
    "paymentMethodName": "apmgw_Yape",
    "apmData": {
        "yape_identificationType": "DNI",
        "yape_personalId": "40009021",
        "yape_phone": "51918865511"
    },
    "checksum": "{{checksum}}"

Example Request for {{url}}/ppp/api/payout.do

{
{
    "merchantSiteId": "{{merchantSiteId}}",
    "internalRequestId": 1759910262864,
    "merchantId": "{{merchantId}}",
    "status": "SUCCESS",
    "userTokenId": "testsecondmethod121",
    "errCode": 0,
    "clientUniqueId": "12345",
    "reason": "",
    "amount": "211",
    "merchantId": "1102398682906145682",
    "currency": "PEN",
    "merchantSiteId": "228311",
    "userPaymentOption": {
    "version": "1.0",
        "userPaymentOptionId": "230485049111"
    "userTokenId": "testsecondmethod121",
    },
    "clientUniqueId": "12345",
    "deviceDetails": {
    "transactionStatus": "APPROVED",
        "ipAddress": "192.168.100.53"
    "paymentMethodErrorCode": "0",
    },
    "userPaymentOptionId": "230485049111",
    "timeStamp": "{{timestamp}}",
    "externalTransactionId": "2610000000642479",
    "checksum": "{{checksum}}"
    "transactionId": "2610000000000380731",
}
    "orderId": "231095111"
}

Web SDK

Follow these steps to perform a payment using Nuvei Web SDK integration.

1. Initiate a Session

Before you can submit payment using the client-side Nuvei Web SDK, you need to send the /openOrder API call.

2. Initialize the Web SDK

Instantiate the Web SDK with the sessionToken received from the server call to /openOrder.

3. Create an APM Payment

Send a createPayment() request with its mandatory parameters including:

• paymentOption.alternativePaymentMethod class containing:
  • paymentMethod: “apmgw_Yape“
• deviceDetails class containing: ipAddress
• billingAddress class containing: firstName, lastName, country, email
• userDetails class containing: firstName, lastName, country, email

Example createPayment() Request

sfc.createPayment({
  sessionToken: "<sessiontoken>",                                   
  paymentOption : {        
    alternativePaymentMethod: {
      paymentMethod: "apmgw_Yape"
  }},                     
  deviceDetails:{
    ipAddress:"<customer's IP address>"
  },
  billingAddress: {
    firstName: "John",
    lastName: "Smith",
    country: "US",
    email:"[email protected]"
  },   
  userDetails: {
    firstName: "John",
    lastName: "Smith",
    country: "US",
    email:"[email protected]"
  },      
}, function(res) {
      console.log(res);
});

After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided in urlDetails.notificationUrl, which Nuvei recommends including in the /openOrder request.

Withdrawal Flow

For information about the Withdrawal flow for WebSDK, see Withdrawal.

Payment Page

Example Payment Page Request

https://ppp-test.safecharge.com/ppp/purchase.do?merchant_id=5970183043540730700&merchant_site_id=238459&user_token=auto&user_token_id=TestYape&item_open_amount_1=false&item_min_amount_1=1&item_max_amount_1=410000&item_name_1=Cashier%20Test%20product&item_amount_1=10&item_quantity_1=1&item_discount_1=0&numberofitems=1&total_tax=0&discount=0&total_amount=10.00&currency=GBP&version=4.0.0&encoding=UTF-8&first_name=test&last_name=test&address1=test&city=test&zip=123456&country=GB&phone1=123456&email=TestYape%40gmail.com&time_stamp=&checksum=b7e44c3ac0fe5c94122f9af45bc54ce1&

After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to notify_url, which Nuvei recommends including in the request.

Simply Connect

To perform a payment using Nuvei Simply Connect integration:

1. Initiate a Session

Before submitting a Simply Connect payment request, you need to submit a server-side /openOrder API request.

2. Create an HTML Placeholder

Import the checkout.js library for building payment flows and create an HTML placeholder on your payment page for the Simply Connect UI element.

3. Submit a checkout() Request

Send a checkout() request with its mandatory input parameters, along with any other relevant parameters and customizations. For more information, see Quick Start to Simply Connect.

Fast Flow (Optional)

To offer customers the option to skip the Yape payment confirmation page for future payments, include in the checkout() request:

• savePm: “always“, “true“, or “force” – Fast flow requires a saved payment method. Other possible savePm values do not support fast flow.
• apmConfig class containing:
  • apmgw_Yape class containing:
    • fastFlow: true
• subMethod: [“ReferenceTransaction”,”AliasRegistration”,”Yape1Tap”] – Array of submethods that support fast flow.
  
  Yape subMethod: [“QuickRegistration”] does not support fast flow.

checkout ({...
    savePm: 'true',
    apmConfig: {
        apmgw_Yape: {
            fastFlow: true
        },
    },
    subMethod: ["ReferenceTransaction","AliasRegistration","Yape1Tap"],...
});

User Experience

Deposit (Third-party Provider)

1. In the cashier, the user selects ‘Yape’.
2. The user enters personal details.
   
3. The user enters an amount.
4. The user is directed to a provider page which displays a QR code and instructions.
   
5. The user completes the deposit by scanning the QR code.
   An instant notification is sent upon payment by the user.

Direct Deposit

1. In the cashier, the user selects Yape.
   
2. (optional) The user enters personal ID details (DNI).
   
3. The user enters an amount.
4. The user is redirected to a Nuvei page which displays the transaction reference number and instructions.
   
5. The user completes the deposit by scanning the QR code.
   An instant notification is sent upon payment by the user.

Withdrawal

1. In the cashier, the user selects Yape.
   
2. The user enters personal ID details (DNI), ID Type, and phone number.
   
3. The user enters a withdrawal amount.
4. The user submits the payout request.
5. The merchant processes the payout request.

Testing

For a third-party provider, approval/decline is done via the third-party back office. Manual approval is required.