If you still call
POST /api/v1/payin, that endpoint is deprecated. Use POST /api/v2/payin for all new integrations.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/v2/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.Payment experiences (v2)
Sendcountry in every request body (e.g. "PE"). All methods below use Checkout unless noted.
payment_method | Mode | payment_url | payment_information |
|---|---|---|---|
CASH_BANK, CASH_STORE, CASH_ALL | Checkout | β | β |
CARD | Checkout | β | β |
SPEI | Hybrid | β | β CLABE / transfer instructions |
ALL_METHODS | Checkout | β | β |
For SPEI, the API returns transfer instructions in
payment_information at creation time and a hosted payment_url (spei-payment) as fallback. All dates are UTC (Y-m-d H:i:s).Response fields by method
payment_method | Mode | payment_url | payment_information |
|---|---|---|---|
CASH_BANK, CASH_STORE, CASH_ALL, CARD, ALL_METHODS | Checkout | β
payments/main | Not returned |
SPEI | Hybrid | β
spei-payment | β
clabe_number, expiration_date (UTC) |
SPEI β Hybrid
curl --request POST 'https://api-empresas.uat.topup.com.co/production/api/v2/payin' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'Content-Type: application/json' \
--data-raw '{
"reference": "TXN-MX-SPEI-001",
"amount": 40.00,
"currency": "MXN",
"country": "MX",
"payment_method": "SPEI",
"description": "SPEI transfer",
"customer_data": {
"legal_doc": "CURP12345678901234",
"legal_doc_type": "INE",
"phone_code": "52",
"phone_number": "2223634886",
"email": "customer@example.com",
"full_name": "John Doe"
},
"ipn_url": "https://your-domain.com/webhook",
"redirect_url": "https://your-domain.com/success"
}'
{
"code": "01",
"status": "SUCCESS",
"message": "Operacion exitosa",
"data": {
"ticket": "Ciolt3HaJdQFLHS",
"date": "2025-10-15 15:44:57",
"payment_url": "https://link.uat.topup.com.co/spei-payment?s=Ciolt3HaJdQFLHS",
"payment_information": {
"clabe_number": "734180000090924227",
"expiration_date": "2026-06-02 06:09:50"
},
"transaction": {
"reference": "TXN-MX-SPEI-001",
"amount": 40.00,
"currency": "MXN",
"payment_method": "SPEI",
"redirect_url": "https://your-domain.com/success",
"ipn_url": "https://your-domain.com/webhook",
"description": "SPEI transfer"
}
}
}
CASH_BANK / CASH_STORE / CARD β Checkout
Mode: Checkout Β· You get:payment_url only (no payment_information).
{
"code": "01",
"status": "SUCCESS",
"message": "Operacion exitosa",
"data": {
"ticket": "mx-cash-ticket",
"date": "2025-10-15 15:44:57",
"payment_url": "https://link.uat.topup.com.co/payments/main?s=mx-cash-ticket",
"transaction": {
"reference": "TXN-MX-CASH-001",
"amount": 150.00,
"currency": "MXN",
"payment_method": "CASH_BANK",
"redirect_url": "https://your-domain.com/success",
"ipn_url": "https://your-domain.com/webhook",
"description": "Cash at bank"
}
}
}
Direct Integrations (Back to Back β deprecated)
This flow applied to PayIn v1 (
POST /api/v1/payin) with Direct SPEI activation enabled in the TumiPay backoffice. It is deprecated β use SPEI Hybrid (v2) with POST /api/v2/payin instead. No backoffice flag is required in v2.payment_method: "SPEI" and receive transfer instructions directly in the API response β without redirecting the customer to a hosted checkout page.
Direct SPEI mode had to be enabled by TumiPay before using this flow in production.
v1 vs v2 response shape
| Aspect | v1 (deprecated) | v2 (recommended) |
|---|---|---|
| Endpoint | POST /api/v1/payin | POST /api/v2/payin |
| Backoffice flag | Direct SPEI activation required | Not required |
| CLABE location | data.transaction.clabe_number | data.payment_information.clabe_number |
| Expiration | data.transaction.expiration_date | data.payment_information.expiration_date |
| Hosted fallback | payment_url often omitted | payment_url always returned (hybrid) |
Request example (v1 β 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 (v1 β 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"
}
}
}
| Field | Description |
|---|---|
clabe_number | CLABE to receive the customer bank transfer (inside data.transaction) |
expiration_date | Expiration timestamp for the transfer instructions |
In v1 direct SPEI,
payment_url was often omitted. The integration used clabe_number and expiration_date from data.transaction. In v2, use data.payment_information instead β see Payment experiences (v2).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 creation time in UTC (YYYY-MM-DD HH:MM:SS) |
payment_url | string | Secure payment URL for customer redirect (Checkout / Hybrid) |
payment_information | object | Provider instructions (Direct / Hybrid only β omitted in Checkout) |
transaction | object | Transaction details echo |
SPEI response fields (payment_information)
| Field | Description |
|---|---|
clabe_number | CLABE to receive the customer bank transfer |
expiration_date | Transfer deadline in UTC (Y-m-d H:i:s) |
Use
payment_information to render SPEI instructions in your UI. Optionally redirect the customer to payment_url for the hosted SPEI page.Examples
Request Example
cURL
curl --request POST 'https://api-empresas.uat.topup.com.co/production/api/v2/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"
}'
curl --request POST 'https://api-empresas.uat.topup.com.co/production/api/v2/payin' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'Content-Type: application/json' \
--data-raw '{
"reference": "TXN-MX-002",
"amount": 200.00,
"currency": "MXN",
"country": "MX",
"payment_method": "CASH_BANK",
"description": "Test Cash 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",
"customer_address": "Av. Insurgentes Sur 1602, Col. CrΓ©dito Constructor, CDMX"
},
"expiration_time": 720,
"ipn_url": "https://your-domain.com/webhook",
"redirect_url": "https://your-domain.com/payment/success"
}'
import axios from 'axios';
const makePayinRequest = async () => {
try {
const response = await axios.post('https://api-empresas.uat.topup.com.co/production/api/v2/payin', {
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'
}, {
headers: {
'Token-Top': 'your_auth_token',
'Authorization': 'Basic your_auth_key',
'Content-Type': 'application/json'
}
});
console.log(response.data);
} catch (error) {
console.error(error);
}
};
makePayinRequest();
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api-empresas.uat.topup.com.co/production/api/v2/payin',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"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"
}',
CURLOPT_HTTPHEADER => array(
'Token-Top: your_auth_token',
'Authorization: Basic your_auth_key',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.io.IOException;
public class PayinRequest {
public static void main(String[] args) throws IOException, InterruptedException {
HttpClient client = HttpClient.newHttpClient();
String json = "{ \"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\" }";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api-empresas.uat.topup.com.co/production/api/v2/payin"))
.header("Token-Top", "your_auth_token")
.header("Authorization", "Basic your_auth_key")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
package main
import (
"fmt"
"net/http"
"io/ioutil"
"strings"
)
func main() {
url := "https://api-empresas.uat.topup.com.co/production/api/v2/payin"
method := "POST"
payload := strings.NewReader(`{
"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"
}`)
client := &http.Client{}
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Token-Top", "your_auth_token")
req.Header.Add("Authorization", "Basic your_auth_key")
req.Header.Add("Content-Type", "application/json")
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
use reqwest::Client;
use serde_json::json;
async fn make_payin_request() -> Result<(), reqwest::Error> {
let client = Client::new();
let response = client.post("https://api-empresas.uat.topup.com.co/production/api/v2/payin")
.header("Token-Top", "your_auth_token")
.header("Authorization", "Basic your_auth_key")
.header("Content-Type", "application/json")
.json(&json!({
"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"
}))
.send()
.await?;
let response_json: serde_json::Value = response.json().await?;
println!("{:#?}", response_json);
Ok(())
}
Response Example
{
"code": "01",
"status": "SUCCESS",
"message": "Operacion exitosa",
"data": {
"ticket": "9CQtDGwb2OLRrz3",
"date": "2025-10-15 17:58:36",
"payment_url": "https://link.uat.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"
}
}
}