PayIn

Country-specific information for PayIn transactions in Peru.

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

Parameter	Value	Description
Endpoint	POST /api/v1/payin	Initiate PayIn transaction
Currency	PEN	Peruvian Sol
Country Code	PE	Peru
Auth Required	Yes	Token-Top + Basic Auth

---

Request Parameters

Required Fields

Field	Type	Description	Example
reference	string	Unique transaction identifier from your system	"13cNPNGbX7meiMppXzVz7g781ysektqq5X"
amount	float	Transaction amount in PEN	1.50 (= S/ 1.50 PEN)
currency	string	Three-letter currency code (ISO 4217)	"PEN"
country	string	Two-letter country code (ISO 3166-1 alpha-2)	"PE"
payment_method	string	Payment method identifier	"ALL_METHODS","CARD"
ipn_url	string	Webhook URL for transaction status updates	"https://your-domain.com/webhook"
redirect_url	string	URL to redirect customer after payment	"https://your-domain.com/payment/success"
customer_data	object	Customer information object (see below)	-

Customer Data Object

Field	Type	Required	Description	Example
legal_doc	string	✅	Customer’s legal document number	"12345678"
legal_doc_type	string	✅	Document type: DNI, RUC, CE, PPN	"DNI"
phone_code	string	✅	Country calling code	"51"
phone_number	string	✅	Phone number without country code	"987654321"
email	string	✅	Customer email address	"[e-mail]"
full_name	string	✅	Customer full name	"John Doe"

Optional Fields

Field	Type	Description	Default
description	string	Transaction description	-
expiration_time	integer	Payment link expiration in minutes	720 (12 hours)

---

Response Structure

Success Response

Field	Type	Description
code	string	Response code ("01" = success)
status	string	Transaction status ("SUCCESS")
message	string	Description of the response
data	object	Transaction data object

Data Object

Field	Type	Description
ticket	string	Unique transaction identifier (TumiPay ID)
date	string	Transaction timestamp (YYYY-MM-DD HH:MM:SS)
payment_url	string	Secure payment URL for customer redirect
transaction	object	Transaction details echo

---

Examples

Request Example

cURL

shellscript

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": "[e-mail]",
        "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"
        }
    }
}