PayIn - Tumipay API

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)

Send country 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.staging.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.staging.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.staging.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.

When Direct SPEI activation was enabled for your merchant account, you could create a PayIn with 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.staging.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.staging.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.staging.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.staging.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.staging.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.staging.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.staging.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.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

​Payment experiences (v2)

​Response fields by method

​SPEI — Hybrid

​CASH_BANK / CASH_STORE / CARD — Checkout

​Direct Integrations (Back to Back — deprecated)

​v1 vs v2 response shape

​Request example (v1 — SPEI direct)

​Response example (v1 — SPEI direct)

​Response Structure

​Success Response

​Data Object

​SPEI response fields (payment_information)

​Examples

​Request Example

​Response Example

Overview

Key Features

Quick Reference

Request Parameters

Required Fields

Customer Data Object

Optional Fields

Payment experiences (v2)

Response fields by method

SPEI — Hybrid

CASH_BANK / CASH_STORE / CARD — Checkout

Direct Integrations (Back to Back — deprecated)

v1 vs v2 response shape

Request example (v1 — SPEI direct)

Response example (v1 — SPEI direct)

Response Structure

Success Response

Data Object

SPEI response fields (`payment_information`)

Examples

Request Example

Response Example