Skip to main content

​
Overview

The PayIn API for Peru enables customer deposit transactions through multiple payment methods including bank transfers, QR code payments, and PagoEfectivo cash vouchers. Transactions are processed in real-time with webhook notifications for status updates.

​
Key Features

  • Multiple Payment Methods: BANK_TRANSFER, QR, PAGOEFECTIVO
  • Currency: Peruvian Sol (PEN)
  • Real-time Processing: Immediate transaction validation and processing
  • Webhook Notifications: Asynchronous status updates via IPN
  • Secure Redirect Flow: Customer completes payment on secure hosted page

​
Quick Reference

ParameterValueDescription
EndpointPOST /api/v1/payinInitiate PayIn transaction
CurrencyPENPeruvian Sol
Country CodePEPeru
Auth RequiredYesToken-Top + Basic Auth

​
Request Parameters

​
Required Fields

FieldTypeDescriptionExample
referencestringUnique transaction identifier from your system"13cNPNGbX7meiMppXzVz7g781ysektqq5X"
amountfloatTransaction amount in PEN1.50 (= S/ 1.50 PEN)
currencystringThree-letter currency code (ISO 4217)"PEN"
countrystringTwo-letter country code (ISO 3166-1 alpha-2)"PE"
payment_methodstringPayment method identifier"BANK_TRANSFER", "QR", "PAGOEFECTIVO", "ALL_METHODS"
ipn_urlstringWebhook URL for transaction status updates"https://your-domain.com/webhook"
redirect_urlstringURL to redirect customer after payment"https://your-domain.com/payment/success"
customer_dataobjectCustomer information object (see below)-

​
Customer Data Object

FieldTypeRequiredDescriptionExample
legal_docstring✅Customer’s legal document number"12345678"
legal_doc_typestring✅Document type: DNI, RUC, CE, PPN"DNI"
phone_codestring✅Country calling code"51"
phone_numberstring✅Phone number without country code"987654321"
emailstring✅Customer email address"[email protected]"
full_namestring✅Customer full name"John Doe"

​
Optional Fields

FieldTypeDescriptionDefault
descriptionstringTransaction description-
expiration_timeintegerPayment link expiration in minutes720 (12 hours)

​
Response Structure

​
Success Response

FieldTypeDescription
codestringResponse code ("01" = success)
statusstringTransaction status ("SUCCESS")
messagestringDescription of the response
dataobjectTransaction data object

​
Data Object

FieldTypeDescription
ticketstringUnique transaction identifier (TumiPay ID)
datestringTransaction timestamp (YYYY-MM-DD HH:MM:SS)
payment_urlstringSecure payment URL for customer redirect
transactionobjectTransaction details echo

​
Examples

​
Request Example

cURL
curl --request POST 'https://api-empresas.staging.tumipay.co/production/api/v1/payin' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "reference": "13cNPNGbX7meiMppXzVz7g781ysektqq5X",
    "amount": 150,
    "currency": "PEN",
    "country": "PE",
    "payment_method": "ALL_METHODS",
    "description": "Test PayIn",
    "customer_data": {
        "legal_doc": "12345678",
        "legal_doc_type": "DNI",
        "phone_code": "51",
        "phone_number": "987654321",
        "email": "[email protected]",
        "full_name": "John Doe"
    },
    "expiration_time": 720,
    "ipn_url": "https://your-domain.com/webhook",
    "redirect_url": "https://your-domain.com/payment/success"
}'

​
Response Example

{
    "code": "01",
    "status": "SUCCESS",
    "message": "Operacion exitosa",
    "data": {
        "ticket": "8BNsCFva1NKPqy2",
        "date": "2025-10-15 17:58:36",
        "payment_url": "https://link.staging.tumipay.co/payments/main?s=8BNsCFva1NKPqy2",
        "transaction": {
            "reference": "13cNPNGbX7meiMppXzVz7g781ysektqq5X",
            "amount": 5000,
            "currency": "PEN",
            "payment_method": "ALL_METHODS",
            "redirect_url": "https://your-domain.com/payment/success",
            "ipn_url": "https://your-domain.com/webhook",
            "description": "Test PayIn"
        }
    }
}