The purpose of this guide is to explain how to create a white label transaction in Peru step by step. Monnet has 3 payment methods available in Peru: Online (Internet Banking), Cash (Pay in cash) and Wallet (Digital Wallet).

Currently, the Monnet Payin API has 1 version:

📘
URL
API v3 (for JSON format with an url as response):
Certification:https://cert.monnetpayments.com/api-payin/v3/online-payments
Production: https://payin.api.monnetpayments.com/api-payin/v3/online-payments

V3: Create a Transaction

To create an online payment using Monnet Payments API, you must call the method online-payments as shown in the following example:

🚧
GENERAL IMPORTANT REMINDER:
All fields must be included on request no matter if they are required or optional. Also pay attention on payinCustomerName (fist name), payinCustomerLastName , payinCustomerEmail and payinCustomerPhone on each case. This four fields must NOT be sent with empty values on any case.

📘
For Card on file and One Shot:
Pay special attention to the following fields: payinProductoDescripcion, which must indicate the user experience (MOBILE or WEB) based on the channel; processorCode (optional), required when distinguishing between different processor configurations and which must contain the correct value, never empty or invalid; payinMerchantOperationNumber, which must be a valid value used to identify payments processed through Yape and required when requesting refunds; subscription.chargeType, required to differentiate the type of charge, considering that the same user may have both charge types enabled (ON_DEMAND and RECURRENT); and payinCustomerPhone, which must contain the customer's mobile phone number in a valid format. All of these fields must always contain valid, non-empty values.

Available Processors

Processor	ProcessorCode	Description
Yape OCP	Yape_on_file	Allows merchants to charge users after a one-time consent is stored. Best for recurring or on-demand payments without further user interaction
Yape OS	Yape_one_shot	Enables real-time push payment requests. Each transaction must be explicitly approved by the user in the Yape app. No stored consent

Creation - Online

Request

Field	Description
payinMerchantID	Integer (Required) Merchant Identifier for the Payin API.
payinAmount	Decimal (Required) The amount of the transaction. Use 2 decimals.
payinCurrency	String (Required, ISO-4217) The currency of the transaction Example PEN
payinMerchantOperationNumber	String (Required, max-lenght = 50) Reference number of the sale. This value is used to notify Merchants about a payment.
payinMethod	String (Required) Payment Method Identifier for the Payin API. EX: BankTransfer, Cash, Wallet.
payinVerification	String (Required) HASH SHA512 of: payinMerchantID+ payinMerchantOperationNumber+ payinAmount+ payinCurrency+ KeyMonnet
payinTransactionOKURL	String (Required) (max 250 chars) URL where the customer will be redirected from the online banking if payment was successful (Must be Https) (max 250 chars)
payinTransactionErrorURL	String (Required) URL where the customer will be redirected from the online banking if payment was wrong.(Must be Https)
payinExpirationTime	Integer (Required) Time in minutes to expire the token. Minimum Suggested: Online: 30 minutes Cash: 2 hours
payinLanguage	String (Required, ISO 639-1) Example: EN, ES, PT, DE, etc.
payinCustomerEmail	String (Required) Contains the customer's email
payinCustomerName	String (Required) Contains the customer's first name Max. 30 digit
payinCustomerLastName	String (Required) Contains the customer's last name. Max. 30 digit
payinCustomerTypeDocument	String (Required) Contains the customer's type of document. payinCustomerTypeDocument
payinCustomerDocument	String (Required) Contains the customer's document number
payinCustomerPhone	String (Required) Contains the customer's mobile number (9 digits)
payinCustomerAddress	String (Required) Customer information
payinCustomerCity	String (Required) Customer information
payinCustomerRegion	String (Required) Customer information (Default value is "Lima" unless different value is indicated by integration team)
payinCustomerCountry	String (Required) Customer information
payinCustomerZipCode	String (Required) Customer information
payinCustomerShippingName	String (Required) Customer information
payinCustomerShippingPhone	String (Required) Customer information
payinCustomerShippingAddress	String (Required) Customer information
payinCustomerShippingCity	String (Required) Customer information
payinCustomerShippingRegion	String (Required) Customer information
payinCustomerShippingCountry	String (Required) Customer information
payinCustomerShippingZipCode	String (Required) Customer information
payinRegularCustomer	String (Optional) Customer information
payinCustomerID	String (Optional) Customer information (PSPs must complete submerchant name mandatory)
payinDiscountCoupon	String (Requied) Customer information
payinFilterBy	String (Optional) Customer information
payinProductID	String (Required) Product information. Can not be empty, could send a default value i.e. "0"
payinProductDescription	String (Required) Product information. Can not be empty, could send a default value i.e. "0"
payinProductAmount	String (Required) Product information. Can not be empty, could send a default value i.e. "0"
payinDateTime	String (Required) Date of the transaction. Can not be empty, could send a default value i.e. current date
payinProductSku	String (Required) Product information. Can not be empty, could send a default value i.e. "0"
payinProductQuantity	String (Required) Product information. Can not be empty, could send a default value i.e. "0"
URLMonnet (For API v3)	String (Required) Value in cert environment: https://cert.monnetpayments.com/api-payin/v1/online-payments Value in prod environment: https://payin.api.monnetpayments.com/api-payin/v1/online-payments
typePost (For API v3)	String (Required) Value: json
processorCode	String (Optional) Allowed values: "Yape_on_file", "Yape_one_shot" Example:: Yape_on_file
subscription	Object (Condicional) Only apply for subcriptions workflow.
chargeType	String (Requiered) Part of subscription object Allowed values: ON_DEMAND/RECURRENT Example: ON_DEMAND

Sample request

Pay attention to the field name format — it must be in lowerCamelCase, as shown below:

data: {
  "payinMerchantID": "00",
  "payinAmount": "00.00",
  "payinCurrency": "PEN",
  "payinMerchantOperationNumber": "0000",
  "payinMethod": "BankTransfer",
  "payinVerification": "string",
  "payinCustomerName": "string",
  "payinCustomerLastName": "string",
  "payinCustomerEmail": "[email protected]",
  "payinCustomerPhone": "9862312321",
  "payinCustomerTypeDocument": "DNI",
  "payinCustomerDocument": "00000000",
  "payinRegularCustomer": "string",
  "payinCustomerID": "string",
  "payinDiscountCoupon": "string",
  "payinLanguage": "ES",
  "payinExpirationTime": "000",
  "payinDateTime": "YYYY-MM-DD",
  "payinTransactionOKURL": "https://test.com",
  "payinTransactionErrorURL": "https://test.com",
  "payinFilterBy": "string",
  "payinCustomerAddress": "string",
  "payinCustomerCity": "string",
  "payinCustomerRegion": "string",
  "payinCustomerCountry": "Peru",
  "payinCustomerZipCode": "0000",
  "payinCustomerShippingName": "string",
  "payinCustomerShippingPhone": "0000",
  "payinCustomerShippingAddress": "string",
  "payinCustomerShippingCity": "string",
  "payinCustomerShippingRegion": "string",
  "payinCustomerShippingCountry": "Peru",
  "payinCustomerShippingZipCode": "0000",
  "payinProductID": "0000",
  "payinProductDescription": "string",
  "payinProductAmount": "0000",
  "payinProductSku": "string",
  "payinProductQuantity": "0000",
  "URLMonnet": "https://cert.monnetpayments.com/api-payin/v1/online-payments",
  "typePost": "json"
}

Response

🚧
V3
For V3, the system will return in the response all the necessary information for the merchant to build and customize their own checkout experience. This includes the payment URL and the detailed instructions generated by our system, enabling the merchant to fully control the payment flow and presentation within their own environment.

{
    "url": "https://test.test",
    "payinErrorCode": "0000",
    "payinErrorMessage": "Successfull process"
    "payinTrxOperation": "MONTRX4214729724051762681",
    "experienceVoucher": {
        "paymentCode": "13238534",
        "status": "PENDIENTE_PAGO",
        "expiration": "2024-05-17 18:58:17",
        "merchant": "Monnet WU",
        "amount": "1.00",
        "currencyCode": "PEN",
        "currencyISO": "S/",
        "operationNumber": "42147297",
        "voucherConfig":"{\"bankList\":[{\"bankCode\":\"BCP\",\"nroOrder\":1,\"hexColor\":\"#002D74\",\"paymentMethodInstructions\":[{\"method\":\"BankTransfer\",\"instructions\":[{\"order\":1,\"value\":\"Ingresa a tu Banca Web o aplicación móvil del BCP\"},{\"order\":2,\"value\":\"Selecciona la opción \\\"Pago de Servicios\\\" y busca la empresa/institución \<strong\>Monnet Pagos\</strong\>.\"},{\"order\":3,\"value\":\"Elige el tipo de moneda del servicio e ingresa tu código de pago \<strong\>13238534\</strong\>\"},{\"order\":4,\"value\":\"Valida el monto a pagar y confírmalo\"}]}]},{\"bankCode\":\"IBK\",\"nroOrder\":2,\"hexColor\":\"#00A24F\",\"paymentMethodInstructions\":[{\"method\":\"BankTransfer\",\"instructions\":[{\"order\":1,\"value\":\"Ingresa a tu Banca Web o aplicación móvil de Interbank\"},{\"order\":2,\"value\":\"Elige la opción \\\"Operaciones\\\", luego \\\"Servicios\\\" y finalmente \\\"Instituciones\\\". Busca la empresa \<strong\>Monnet Pagos\</strong\>.\"},{\"order\":3,\"value\":\"Elige el tipo de moneda del servicio e ingresa tu código de pago \<strong\>13238534\</strong\>\"},{\"order\":4,\"value\":\"Selecciona la deuda a pagar y confírmalo\"}]}]},{\"bankCode\":\"BBVA\",\"nroOrder\":3,\"hexColor\":\"#002D74\",\"paymentMethodInstructions\":[{\"method\":\"BankTransfer\",\"instructions\":[{\"order\":1,\"value\":\"Ingresa a tu Banca Web o aplicación móvil del BBVA\"},{\"order\":2,\"value\":\"Selecciona la opción \\\"Pagar Servicio\\\" y elige \\\"Agregar servicio a pagar\\\".\"},{\"order\":3,\"value\":\"Busca el servicio \<strong\>Monnet pagos Soles o Monnet pagos Dolares\</strong\>, ingresa tu código \<strong\>13238534\</strong\>\"},{\"order\":4,\"value\":\"Valida el monto a pagar y confírmalo\"}]}]},{\"bankCode\":\"YAPE\",\"nroOrder\":4,\"hexColor\":\"#680177\",\"paymentMethodInstructions\":[{\"method\":\"BankTransfer\",\"instructions\":[{\"order\":1,\"value\":\"Ingresa a tu app YAPE y selecciona la opción \<strong\>\\\"Yapear servicios\\\"\</strong\>\"},{\"order\":2,\"value\":\"Elige categoría \<strong\>\\\"Compras por Internet\\\"\</strong\> y selecciona \<strong\>\\\"Monnet Pagos\\\"\</strong\>\"},{\"order\":3,\"value\":\"Ingresa el código de pago \<strong\>13238534\</strong\>\"},{\"order\":4,\"value\":\"Selecciona el recibo y ¡listo!\"}]}]}],\"instruction_payment_methods\":[\"BankTransfer\"]}"
    }
}

Request Yape OCP

data: {
  "payinMerchantID": "00",
  "payinAmount": "10.00",
  "payinCurrency": "PEN",
  "payinMerchantOperationNumber": "Merchant-20-00001",
  "payinMethod": "Wallet",
  "payinVerification": "string",
  "payinCustomerName": "string",
  "payinCustomerLastName": "string",
  "payinCustomerEmail": "[email protected]",
  "payinCustomerPhone": "9862312321",
  "payinCustomerTypeDocument": "DNI",
  "payinCustomerDocument": "00000000",
  "payinRegularCustomer": "string",
  "payinCustomerID": "string",
  "payinDiscountCoupon": "string",
  "payinLanguage": "ES",
  "payinExpirationTime": "000",
  "payinDateTime": "YYYY-MM-DD",
  "payinTransactionOKURL": "https://test.com",
  "payinTransactionErrorURL": "https://test.com",
  "payinFilterBy": "string",
  "payinCustomerAddress": "string",
  "payinCustomerCity": "string",
  "payinCustomerRegion": "string",
  "payinCustomerCountry": "Peru",
  "payinCustomerZipCode": "0000",
  "payinCustomerShippingName": "string",
  "payinCustomerShippingPhone": "0000",
  "payinCustomerShippingAddress": "string",
  "payinCustomerShippingCity": "string",
  "payinCustomerShippingRegion": "string",
  "payinCustomerShippingCountry": "Peru",
  "payinCustomerShippingZipCode": "0000",
  "payinProductID": "0000",
  "payinProductDescription": "MOBILE",
  "payinProductAmount": "0000",
  "payinProductSku": "string",
  "payinProductQuantity": "0000",
  "URLMonnet": "https://cert.monnetpayments.com/api-payin/v1/online-payments",
  "typePost": "json",
  "processorCode":"Yape_on_file",
  "subscription":
  {
		chargeType:"ON_DEMAND"
	}
}

🚧
V3
For the Yape On File integration, in On_Demand or RECURRENTmode, the system will process the payment request and return a response indicating the result of the operation. The response will either be successful or contain error details, allowing the merchant to manage the confirmation flow, notifications, and payment experience according to their own processes.

Response Yape OCP

{
    "payinErrorCode": "0000",
    "payinErrorMessage": "Successfull process",
    "payinTrxOperation": "MONTRX4214729724051762681"
}

Request Yape one Shot

data: {
  "payinMerchantID": "00",
  "payinAmount": "10.00",
  "payinCurrency": "PEN",
  "payinMerchantOperationNumber": "Merchant-20-00001",
  "payinMethod": "Wallet",
  "payinVerification": "string",
  "payinCustomerName": "string",
  "payinCustomerLastName": "string",
  "payinCustomerEmail": "[email protected]",
  "payinCustomerPhone": "9862312321",
  "payinCustomerTypeDocument": "DNI",
  "payinCustomerDocument": "00000000",
  "payinRegularCustomer": "string",
  "payinCustomerID": "string",
  "payinDiscountCoupon": "string",
  "payinLanguage": "ES",
  "payinExpirationTime": "000",
  "payinDateTime": "YYYY-MM-DD",
  "payinTransactionOKURL": "https://test.com",
  "payinTransactionErrorURL": "https://test.com",
  "payinFilterBy": "string",
  "payinCustomerAddress": "string",
  "payinCustomerCity": "string",
  "payinCustomerRegion": "string",
  "payinCustomerCountry": "Peru",
  "payinCustomerZipCode": "0000",
  "payinCustomerShippingName": "string",
  "payinCustomerShippingPhone": "0000",
  "payinCustomerShippingAddress": "string",
  "payinCustomerShippingCity": "string",
  "payinCustomerShippingRegion": "string",
  "payinCustomerShippingCountry": "Peru",
  "payinCustomerShippingZipCode": "0000",
  "payinProductID": "0000",
  "payinProductDescription": "MOBILE",
  "payinProductAmount": "0000",
  "payinProductSku": "string",
  "payinProductQuantity": "0000",
  "URLMonnet": "https://cert.monnetpayments.com/api-payin/v1/online-payments",
  "typePost": "json",
  "processorCode":"Yape_one_shot,
}

🚧
V3
For the Yape One Shot integration, available in MOBILE and WEB experiences, the system will process the payment request and return a response indicating whether the operation was successful or if it contains error details. Depending on the selected experience:
MOBILE: The payment flow will be triggered via a deep link to the Yape app, requiring the user to authenticate and confirm the transaction.
WEB: The payment flow will be initiated from Yape app, allowing the user to complete the transaction inside.

Response Yape One Shot

{
  "payinErrorCode": "0000",
  "payinErrorMessage": "Successfull process",
  "payinTrxOperation": "MONTRX4214729724051762681",
  "deepLinks": [
    {
      "processor": "YapeOS",
      "processoCode": "Yape_one_shot",
      "deepLink": "https://www.yape.com.pe/app/checkout/oneshot/token123",
      "order": 1
    }
  ]
}

Experiencia One Shot

📘
User Experience by Platform
Mobile Experience:
Redirect the user to the processor’s app using the URL (deeplink) provided in the response.
Web Experience:
Display clear instructions to the user so they can complete the payment manually from their processor’s app.

Payment

🚧
payinMerchantOperationNumber
The payinMerchantOperationNumber returned in the response is the unique identifier for the transaction inside of Monnet's system. It is not needed to complete the payment, so it shouldn't be shown to the shopper because it may confuse him.

The following table describes the fields that our system will send to the merchant for creating the payment experience:

Field	Description	Example
paymentCode	Payment code	13238164
status	Payment status	PENDING_PAYMENT
expiration	Expiration date and time	2024-05-17 18:05:11
merchant	Merchant name	Monnet WU
amount	Payment amount	1.00
currencyCode	Currency code	PEN
currencyISO	ISO currency code	S/
operationNumber	Operation number	42144822
voucherConfig	Voucher configuration	See details below

VoucherConfig Details

Field	Description	Example
bankList / CashList/ WalletList	List of available banks,cash and wallets	See details below
instruction_payment_methods	Available payment methods	["BankTransfer"]

BankList Details

BankCode	Instruction 1	Instruction 2	Instruction 3	Instruction 4
BCP	Access your BCP web banking or mobile app	Select "Payment of Services" and search for the company/institution Monnet Pagos.	Choose the currency type and enter your payment code 13238164	Validate the amount to be paid and confirm
IBK	Access your Interbank web banking or mobile app	Select "Operations", then "Services", and finally "Institutions". Search for the company Monnet Pagos	Choose the currency type and enter your payment code 13238164	Select the debt to be paid and confirm
BBVA	Access your BBVA web banking or mobile app	Select "Pay Service" and choose "Add service to pay".	Search for the service Monnet pagos Soles or Monnet pagos Dólares, enter your code 13238164	Validate the amount to be paid and confirm
YAPE	Access your YAPE app and select the option "Yapear services"	Choose category "Internet Purchases" and select "Monnet Pagos"	Enter the payment code 13238164	Select the receipt and you're done!

CashList Details

BankCode	Instruction 1	Instruction 2	Instruction 3	Instruction 4
BCP	Go to a BCP agent and indicate you want to pay for the service Monnet Pagos	Indicate the service currency	Provide your payment code 13246792	Provide the total amount to be paid and complete the payment
IBK	Go to an Interbank agent and indicate you want to pay for the service Monnet Pagos	Indicate the service currency	Provide your payment code 13246792	Provide the total amount to be paid and complete the payment
BBVA	Go to a BBVA agent and indicate you want to pay for the service Monnet Pagos	Indicate the service currency.	Provide your payment code 13246792	Provide the total amount to be paid and complete the payment
KSNT	Go to a KASNET agent and indicate you want to pay for the service Monnet Pagos	Provide the Monnet Agent Code 220158	Provide your payment code 13246792	Provide the total amount to be paid and complete the payment
TAMBO	Go to a TAMBO store and indicate you want to pay for the service Monnet Pagos	Indicate the currency (Payment in soles or Payment in dollars)	Provide your payment code 13246792	Provide the total amount to be paid and complete the payment

WalletList Details

BankCode	Instruction 1	Instruction 2	Instruction 3	Instruction 4
YAPE	Access your YAPE app and select the option "Yapear services"	Choose category "Internet Purchases" and select "Monnet Pagos"	Enter the payment code 13238164	Select the receipt and you're done

White Label

📘
URL

V3: Create a Transaction

🚧

GENERAL IMPORTANT REMINDER:

📘

For Card on file and One Shot:

Available Processors

Creation - Online

Request

Sample request

Response

🚧
V3

Request Yape OCP

🚧
V3

Response Yape OCP

Request Yape one Shot

🚧
V3

Response Yape One Shot

Experiencia One Shot

📘
User Experience by Platform

Payment

🚧
payinMerchantOperationNumber

📘URL

V3: Create a Transaction

🚧

GENERAL IMPORTANT REMINDER:

📘

For Card on file and One Shot:

Available Processors

Creation - Online

Request

Sample request

Response

🚧V3

Request Yape OCP

🚧V3

Response Yape OCP

Request Yape one Shot

🚧V3

Response Yape One Shot

Experiencia One Shot

📘User Experience by Platform

Payment

🚧payinMerchantOperationNumber

📘
URL

🚧
V3

🚧
V3

🚧
V3

📘
User Experience by Platform

🚧
payinMerchantOperationNumber