PayIn - Tumipay API

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	`"johndoe@email.com"`
`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

curl --request POST 'https://api-empresas.staging.topup.com.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": "johndoe@email.com",
        "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.topup.com.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"
        }
    }
}

QR Code Direct Flow

El flujo QR directo está disponible exclusivamente para Perú (country: "PE") con payment_method: "QR". Requiere que el comercio tenga habilitado el parámetro ExperienciaQrCode en la configuración de TumiPay. Contacta al equipo de integraciones para activarlo.

A diferencia del flujo tradicional (que devuelve un payment_url para redirigir al cliente a una página de pago), el flujo QR directo genera el código QR en el momento de crear la transacción y lo devuelve en la respuesta como una imagen en base64. El comercio es responsable de renderizarlo y mostrárselo al cliente.

¿Cómo funciona?

Merchant                   TumiPay API              StreamPayments
   |                            |                         |
   |-- POST /api/v1/payin ----→ |                         |
   |   payment_method: "QR"     |                         |
   |   country: "PE"            |-- Create QR Order ----→ |
   |                            |                         |
   |                            |←-- qrCode (string) ---- |
   |                            |                         |
   |                            | [normalize to base64]   |
   |                            |                         |
   |←-- 200 OK (qr_code_base64) |                         |
   |                            |                         |
   | [display QR to customer]   |                         |
   |                            |                         |
   |              Customer scans QR with bank app         |
   |                            |                         |
   |                            |←-- Payment confirmed -- |
   |                            |                         |
   |←-- Webhook (ipn_url) ----- |                         |

Límites de monto para QR

Límite	Valor por defecto	Descripción
Monto máximo por transacción (Perú)	S/ 500 PEN	Límite del proveedor QR para Perú. Se devuelve `QR_AMOUNT_LIMIT_EXCEEDED` si se supera.

Si el monto supera el límite máximo configurado para QR en Perú, el sistema devuelve HTTP 422 con error: "QR_AMOUNT_LIMIT_EXCEEDED" antes de crear la transacción.

Request (QR directo)

El request es idéntico al flujo estándar. El único cambio es payment_method: "QR":

cURL

curl --request POST 'https://api-empresas.staging.topup.com.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": "unique-ref-qr-001",
    "amount": 50,
    "currency": "PEN",
    "country": "PE",
    "payment_method": "QR",
    "description": "Pago QR directo",
    "customer_data": {
        "legal_doc": "12345678",
        "legal_doc_type": "DNI",
        "phone_code": "51",
        "phone_number": "987654321",
        "email": "johndoe@email.com",
        "full_name": "John Doe"
    },
    "expiration_time": 30,
    "ipn_url": "https://your-domain.com/webhook",
    "redirect_url": "https://your-domain.com/payment/success"
}'

Response (QR directo)

La respuesta incluye todos los campos estándar más el campo qr_code_base_64 dentro de data.

Campo	Tipo	Descripción
`code`	string	`"01"` = éxito, `"00"` = error
`status`	string	`"SUCCESS"` o `"ERROR"`
`message`	string	Descripción de la respuesta
`data.ticket`	string	Identificador único de la transacción (UUID de TumiPay)
`data.date`	string	Fecha y hora de creación (`YYYY-MM-DD HH:MM:SS`)
`data.payment_url`	string	URL de la página de pago (disponible como fallback)
`data.qr_code_base_64`	string	Imagen QR en base64 (PNG). Muéstrala directamente en un `<img>` con prefijo `data:image/png;base64,`
`data.transaction`	object	Echo de los datos de la transacción enviados en el request

{
    "code": "01",
    "status": "SUCCESS",
    "message": "Operacion exitosa",
    "data": {
        "ticket": "3f7a9b2c-1d4e-5f6a-7b8c-9d0e1f2a3b4c",
        "date": "2026-05-11 14:30:00",
        "payment_url": "https://link.staging.topup.com.co/payments/main?s=3f7a9b2c-1d4e-5f6a-7b8c-9d0e1f2a3b4c",
        "qr_code_base_64": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51AAAA...",
        "transaction": {
            "reference": "unique-ref-qr-001",
            "amount": 50,
            "currency": "PEN",
            "payment_method": "QR",
            "redirect_url": "https://your-domain.com/payment/success",
            "ipn_url": "https://your-domain.com/webhook",
            "description": "Pago QR directo"
        }
    }
}

Renderizar el QR

Con el valor de qr_code_base_64 puedes mostrar directamente el QR al cliente sin necesidad de procesar la imagen:

<!-- HTML -->
<img src="data:image/png;base64,{{ qr_code_base_64 }}" alt="Escanea para pagar" />

// React / TypeScript
<img src={`data:image/png;base64,${data.qr_code_base_64}`} alt="Escanea para pagar" />

Errores específicos del flujo QR

HTTP	`code`	`error`	Descripción
422	`"00"`	`QR_AMOUNT_LIMIT_EXCEEDED`	El monto supera el límite máximo permitido para QR en Perú
400	`"00"`	`TRANSACTION_IN_PROGRESS`	Ya existe una transacción activa para ese email/monto
200	`"00"`	—	Error al generar el QR con el proveedor (reintenta)

Notificación por webhook

Al igual que el flujo estándar, cuando el cliente escanea y completa el pago, TumiPay envía una notificación a ipn_url. Consulta la documentación de webhooks para ver la estructura del payload.

​Overview

​Key Features

​Quick Reference

​Request Parameters

​Required Fields

​Customer Data Object

​Optional Fields

​Response Structure

​Success Response

​Data Object

​Examples

​Request Example

​Response Example

​QR Code Direct Flow

​¿Cómo funciona?

​Límites de monto para QR

​Request (QR directo)

​Response (QR directo)

​Renderizar el QR

​Errores específicos del flujo QR

​Notificación por webhook

Overview

Key Features

Quick Reference

Request Parameters

Required Fields

Customer Data Object

Optional Fields

Response Structure

Success Response

Data Object

Examples

Request Example

Response Example

QR Code Direct Flow

¿Cómo funciona?

Límites de monto para QR

Request (QR directo)

Response (QR directo)

Renderizar el QR

Errores específicos del flujo QR

Notificación por webhook