PayIn - Tumipay API

Overview

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

Key Features

Multiple Payment Methods: CARD, CASH_BANK, CASH_STORE, CASH_ALL, SPEI, OXXO
Currency: Mexican Peso (MXN)
Real-time Processing: Immediate transaction validation and processing
Webhook Notifications: Asynchronous status updates via IPN
Secure Redirect Flow: Customer completes payment on a secure hosted page

Quick Reference

Parameter	Value	Description
Endpoint	`POST /api/v1/payin`	Initiate PayIn transaction
Currency	`MXN`	Mexican Peso
Country Code	`MX`	Mexico
Auth Required	Yes	Token-Top + Basic Auth

Request Parameters

Required Fields

Field	Type	Description	Example
`reference`	string	Unique transaction identifier from your system	`"TXN-MX-001"`
`amount`	float	Transaction amount in MXN	`150.00` (= MX$ 150.00)
`currency`	string	Three-letter currency code (ISO 4217)	`"MXN"`
`country`	string	Two-letter country code (ISO 3166-1 alpha-2)	`"MX"`
`payment_method`	string	Payment method identifier	`"ALL_METHODS"`, `"CARD"`, `"SPEI"`, `"OXXO"`, `"CASH_BANK"`, `"CASH_STORE"`, `"CASH_ALL"`
`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	`"CURP12345678901234"`
`legal_doc_type`	string	✅	Document type: `CURP`, `RFC`, `INE`, `PPN`	`"INE"`
`phone_code`	string	✅	Country calling code	`"52"`
`phone_number`	string	✅	10-digit phone number without country code	`"5512345678"`
`email`	string	✅	Customer email address	`"johndoe@email.com"`
`full_name`	string	✅	Customer full name	`"John Doe"`
`customer_address`	string	✅ Required when `payment_method` is `CASH_BANK` or `CASH_STORE`	Customer’s full address for cash delivery	`"Av. Insurgentes Sur 1602, CDMX"`

Optional Fields

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

The customer_address field is required when using CASH_BANK or CASH_STORE.

CASH_ALL displays a hosted form showing only the available cash options (CASH_BANK, CASH_STORE). The customer selects their preferred channel on that page.

Direct Integrations (Back to Back)

SPEI Direct Activation

When the Direct SPEI activation is enabled for your merchant account in the TumiPay backoffice, you can create a PayIn transaction with payment_method: "SPEI" and return transfer instructions directly in the API response. This direct mode is intended for merchants that implement their own user experience and need to display the beneficiary CLABE and expiration date without redirecting the customer to a hosted checkout page.

Direct SPEI mode must be enabled by TumiPay before using this flow in production.

Request Example (SPEI Direct)

{
    "reference": "TXN-MX-SPEI-001",
    "amount": 40.00,
    "currency": "MXN",
    "country": "MX",
    "payment_method": "SPEI",
    "description": "SPEI direct activation test",
    "redirect_url": "https://tumipay.co/",
    "ipn_url": "https://your-domain.com/webhook",
    "customer_data": {
        "legal_doc": "CURP12345678901234",
        "legal_doc_type": "INE",
        "phone_code": "52",
        "phone_number": "2223634886",
        "email": "customer@example.com",
        "full_name": "John Doe",
        "address": "Av. Insurgentes Sur 1602, CDMX"
    }
}

Response Example (SPEI Direct)

{
    "code": "01",
    "status": "SUCCESS",
    "message": "Operacion exitosa",
    "data": {
        "ticket": "Ciolt3HaJdQFLHS",
        "date": "2026-06-01 13:09:49",
        "transaction": {
            "reference": "3pFBNpRHdXdqNcq2S1QxyQbhQZXVaq",
            "amount": 40.00,
            "currency": "MXN",
            "payment_method": "SPEI",
            "ipn_url": "https://your-domain.com/webhook",
            "description": "SPEI direct activation test",
            "clabe_number": "734180000090924227",
            "expiration_date": "2026-06-02T06:09:50"
        }
    }
}

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

SPEI Direct Response Fields

When Direct SPEI activation is enabled, the transaction object also includes:

Field	Type	Description
`clabe_number`	string	CLABE to receive the customer bank transfer
`expiration_date`	string	Expiration timestamp for the transfer instructions

For direct SPEI transactions, payment_url may be omitted and the integration should use clabe_number and expiration_date from data.transaction.

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": "TXN-MX-001",
    "amount": 150.00,
    "currency": "MXN",
    "country": "MX",
    "payment_method": "ALL_METHODS",
    "description": "Test PayIn Mexico",
    "customer_data": {
        "legal_doc": "CURP12345678901234",
        "legal_doc_type": "INE",
        "phone_code": "52",
        "phone_number": "5512345678",
        "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": "9CQtDGwb2OLRrz3",
        "date": "2025-10-15 17:58:36",
        "payment_url": "https://link.staging.topup.com.co/payments/main?s=9CQtDGwb2OLRrz3",
        "transaction": {
            "reference": "TXN-MX-001",
            "amount": 150.00,
            "currency": "MXN",
            "payment_method": "ALL_METHODS",
            "redirect_url": "https://your-domain.com/payment/success",
            "ipn_url": "https://your-domain.com/webhook",
            "description": "Test PayIn Mexico"
        }
    }
}

​Overview

​Key Features

​Quick Reference

​Request Parameters

​Required Fields

​Customer Data Object

​Optional Fields

​Direct Integrations (Back to Back)

​SPEI Direct Activation

​Request Example (SPEI Direct)

​Response Example (SPEI Direct)

​Response Structure

​Success Response

​Data Object

​SPEI Direct Response Fields

​Examples

​Request Example

​Response Example

Overview

Key Features

Quick Reference

Request Parameters

Required Fields

Customer Data Object

Optional Fields

Direct Integrations (Back to Back)

SPEI Direct Activation

Request Example (SPEI Direct)

Response Example (SPEI Direct)

Response Structure

Success Response

Data Object

SPEI Direct Response Fields

Examples

Request Example

Response Example