Request Structure

Overview

All transactions use the same base request format with operation-specific fields. This unified structure simplifies integration by providing a consistent API interface for both payments and withdrawals.

Common Fields

All requests to the /process/ endpoint must include these base fields:

Field	Type	Required	Description
`operation_type`	string	Yes	`"payment"` or `"withdrawal"`
`amount`	decimal	Yes	Transaction amount
`currency`	string	No	Currency code (default: `"MXN"`)
`customer`	object	Yes	Customer information
`customer.name`	string	Yes	Customer full name
`customer.email`	string	Yes	Customer email address
`client_reference`	string	No	Your reference identifier
`metadata`	object	No	Additional data for your records
`return_url`	string	No	URL for redirection after 3DS processing

Basic Request Structure

{
  "operation_type": "payment",
  "amount": 1000.50,
  "currency": "MXN",
  "customer": {
    "name": "John Doe",
    "email": "john.doe@email.com"
  },
  "payment_method": {
    "type": "CARD",
    "card_number": "9230-0892-4469-1474",
    "cardholder_name": "c05d89b2-299c-4f93-b49a-42be00d3b64b",
    "cvv": "d31f0da3-0ed3-4ad8-8b68-14c2669a99a7",
    "expiration_month": "e401a32e-4174-424f-9688-727005f6a80e",
    "expiration_year": "bd9ccc23-3d00-4109-9626-fc6581389063"
  },
  "client_reference": "order-12345",
  "metadata": {
    "customer_id": "cust_123",
    "order_id": "ord_456"
  },
  "return_url": "https://yoursite.com/payment/return"
}

Request Headers

All requests must include these headers:

Authorization: Token your_api_key
X-Signature-Transaction: calculated_hmac_signature
Content-Type: application/json

Payment Request Fields

When operation_type is "payment", include these additional fields:

Field	Type	Required	Description
`payment_method`	object	Yes	Payment method details
`payment_method.type`	string	Yes	Payment method type (`"CARD"`, `"SPEI"`, etc.)
`payment_method.token`	string	*	Tokenized card ID (for card payments)
`payment_method.card_number`	string	*	Card number (if not using token)
`payment_method.cvv`	string	*	Security code (for raw card data)
`payment_method.expiry_month`	string	*	Expiration month (for raw card data)
`payment_method.expiry_year`	string	*	Expiration year (for raw card data)
`payment_method.cardholder_name`	string	*	Cardholder name (for raw card data)

For card payments, you’ll need to provide either a token or the full card details.

Card Payment Examples

Below are some examples of card payment requests.

Using Tokenized Card (Recommended)

For tokenized card payments (payment_method.type: "CARD"), you’ll need to provide the token instead of the full card details:

{
  "operation_type": "payment",
  "amount": 150.00,
  "currency": "MXN",
  "customer": {
    "name": "Ana María Rodríguez",
    "email": "ana.rodriguez@email.com"
  },
  "payment_method": {
    "type": "CARD",
    "card_number": "9230-0892-4469-1474",
    "cardholder_name": "c05d89b2-299c-4f93-b49a-42be00d3b64b",
    "cvv": "d31f0da3-0ed3-4ad8-8b68-14c2669a99a7",
    "expiration_month": "e401a32e-4174-424f-9688-727005f6a80e",
    "expiration_year": "bd9ccc23-3d00-4109-9626-fc6581389063"
  },
  "client_reference": "order-789",
  "return_url": "https://mystore.com/payment/return"
}

SPEI Bank transfer

For SPEI transfers (payment_method.type: "SPEI"), only customer information is required:

{
  "operation_type": "payment",
  "amount": 500.00,
  "currency": "MXN",
  "customer": {
    "name": "Carlos Eduardo López",
    "email": "carlos.lopez@empresa.mx"
  },
  "payment_method": {
    "type": "SPEI"
  },
  "client_reference": "invoice-456"
}

OXXO Cash Payment

For OXXO payments (payment_method.type: "oxxopay"):

{
  "operation_type": "payment",
  "amount": 250.00,
  "currency": "MXN",
  "customer": {
    "name": "María Isabel Fernández",
    "email": "maria.fernandez@email.com"
  },
  "payment_method": {
    "type": "oxxopay"
  },
  "client_reference": "cash-payment-789"
}

Withdrawal Request Fields

When operation_type is "withdrawal", include these additional fields:

Field	Type	Required	Description
`transfer_method`	string	Yes	Transfer method (`"SPEI"` or `"DEBIT_CARD"`)
`beneficiary`	object	Yes	Beneficiary information
`reference`	string	No	Your withdrawal reference
`description`	string	No	Withdrawal description

The beneficiary object includes the following fields:

Field	Type	Required	Description
`beneficiary.account`	string	Yes	Account number or CLABE
`beneficiary.name`	string	Yes	Beneficiary full name
`beneficiary.rfc`	string	Yes	Mexican tax ID (RFC)
`beneficiary.institution`	string	Yes	Bank institution code
`beneficiary.email`	string	Yes	Beneficiary email

SPEI Withdrawal Example

{
  "operation_type": "withdrawal",
  "amount": 750.00,
  "currency": "MXN",
  "reference": "payout-001",
  "transfer_method": "SPEI",
  "description": "Commission payment",
  "beneficiary": {
    "account": "012345678901234567",
    "name": "Roberto Martínez García",
    "rfc": "MAGR850920XY1",
    "institution": "40012",
    "email": "roberto.martinez@email.com"
  }
}

Supported Payment Methods

The following payment methods are supported:

Method	Type Value	Description	Processing Time
Cards	`CARD`	Credit and debit cards	Instant
SPEI	`SPEI`	Mexican bank transfers	Real-time
OXXO	`OXXO`	Cash payments at OXXO stores	24-48 hours
Mercado Pago	`MERCADOPAGO`	Digital wallet	Instant
SafetyPay	`SAFETYPAY`	Alternative cash payment	24-48 hours

Supported Transfer MethodsYou can use either SPEI for same-day bank transfers, or Debit Card for instant direct deposits.

SPEI (SPEI): Bank account transfers, processed on the same day.
Debit Card (DEBIT_CARD): Direct card deposits, processed instantly.

Field Validation Rules

Amount & Currency

Field	Rules	Example
`amount`	0.01 - 15,000,000, up to 2 decimals	`1000.50`, `25.99`
`currency`	`MXN` (default), `USD`, uppercase	`MXN`, `USD`

Email & Names

Field	Rules	Example
`customer.email`	Valid email format	`user@domain.com`
`customer.name`	Required, any format	`John Doe`
`beneficiary.email`	Valid email format	`beneficiary@email.com`
`beneficiary.name`	Required, any format	`Roberto Martínez García`

Mexican Tax & Banking

Field	Rules	Example
`beneficiary.rfc`	12-13 alphanumeric, pattern: `^[A-Z&Ñ]{3,4}\\d{6}[A-Z\\d]{3}$`	`XAXX010101000`, `MAGR850920XY1`
`beneficiary.account`	18 digits: Bank(3) + Branch(3) + Account(11) + Check(1)	`012345678901234567`

Complete Request Examples

Check the following examples to see how to use the request body.

{
  "operation_type": "payment",
  "amount": 1500.00,
  "currency": "MXN",
  "customer": {
    "name": "Ana María González López",
    "email": "ana.gonzalez@empresa.mx"
  },
  "payment_method": {
    "type": "CARD",
    "card_number": "9230-0892-4469-1474",
    "cardholder_name": "c05d89b2-299c-4f93-b49a-42be00d3b64b",
    "cvv": "d31f0da3-0ed3-4ad8-8b68-14c2669a99a7",
    "expiration_month": "e401a32e-4174-424f-9688-727005f6a80e",
    "expiration_year": "bd9ccc23-3d00-4109-9626-fc6581389063"
  },
  "client_reference": "order-12345-premium",
  "metadata": {
    "customer_id": "cust_789",
    "order_id": "ord_12345",
    "store_location": "Mexico City",
    "sales_channel": "web"
  },
  "return_url": "https://mystore.com/payment/return?order=12345"
}

Request Size Limits

The request body size is limited to 10KB. Here’s a breakdown of the maximum size for each field:

Field	Maximum Size
Total request body	10KB
Customer name	255 characters
Customer email	320 characters
Client reference	255 characters
Description	500 characters
Metadata object	2KB

Best Practices

Here are some best practices to help you build reliable, secure, and robust requests.

Required Fields

Optional Fields

Data Quality

Security

Next Steps

Review Response Format for handling API responses
Learn about Payment Methods for specific implementation details
Check Error Handling for validation error management
Explore Card Tokenisation for secure card data handling

Getting Started

API Reference

Payment Processing

Integration

Regional Reference

Resources

Request Structure

Overview

Common Fields

Request Headers

Payment Request Fields

Card Payment Examples

Withdrawal Request Fields

Supported Payment Methods

Field Validation Rules

Complete Request Examples

Request Size Limits

Best Practices

Next Steps

Getting Started

API Reference

Payment Processing

Integration

Regional Reference

Resources

​Overview

​Common Fields

​Request Headers

​Payment Request Fields

​Card Payment Examples

​Withdrawal Request Fields

​Supported Payment Methods

​Field Validation Rules

​Complete Request Examples

​Request Size Limits

​Best Practices

​Next Steps

Overview

Common Fields

Request Headers

Payment Request Fields

Card Payment Examples

Withdrawal Request Fields

Supported Payment Methods

Field Validation Rules

Complete Request Examples

Request Size Limits

Best Practices

Next Steps