PayIn

Country-specific information for PayIn transactions in Mexico.

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, 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"
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, PP	"INE"
phone_code	string	✅	Country calling code	"52"
phone_number	string	✅	10-digit phone number without country code	"5512345678"
email	string	✅	Customer email address	"[e-mail]"
full_name	string	✅	Customer full name	"John Doe"
customer_address	string	✅ Required when payment_method is CASH	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 the CASH payment method.

---

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": "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": "[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": "9CQtDGwb2OLRrz3",
        "date": "2025-10-15 17:58:36",
        "payment_url": "https://link.staging.tumipay.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"
        }
    }
}