SPEI (Mexico)

SPEI (Sistema de Pagos Electrónicos Interbancarios) is the real-time gross settlement system operated by Banco de México. It enables instant interbank transfers in Mexican pesos (MXN) between any of the 90+ member institutions, 24 hours a day, 7 days a week.

mcp2p exposes SPEI as three MCP tools. Enable the rail by including "spei" in your rails array when calling createMcp2pServer.

Overview

  • Settlement time: Typically under 20 seconds. Final in real time.
  • Operating hours: 24/7/365.
  • Currency: Mexican peso (MXN). Amounts in centavos (minor units).
  • Routing: Via 18-digit CLABE (Clave Bancaria Estandarizada).
  • Limits: No statutory per-transfer cap for corporate accounts; your license tier may impose its own limit.

Available tools

spei_send_payment

2FA required

Initiate a SPEI interbank transfer to a CLABE account. Requires 2FA authorization.

ParameterTypeRequiredDescription
clabestringYes18-digit CLABE account number
amountnumberYesAmount in centavos (minor units). E.g. 50000 = MXN 500.00
conceptstringYesTransfer concept or description (max 40 chars)
recipientNamestringYesFull name of the recipient account holder
verificationCodestringNo6-digit OTP from Twilio Verify. Omit on first call to trigger SMS.

spei_check_status

No 2FA

Check the current status of a SPEI transaction by its tracking key (clave de rastreo).

ParameterTypeRequiredDescription
trackingKeystringYesSPEI tracking key (clave de rastreo) returned by spei_send_payment

spei_request_refund

2FA required

Request a refund for a completed SPEI transfer. Requires 2FA authorization.

ParameterTypeRequiredDescription
trackingKeystringYesTracking key of the original transaction
reasonstringYesReason for the refund request
verificationCodestringNo6-digit OTP. Omit on first call to trigger SMS.

CLABE validation rules

CLABE (Clave Bancaria Estandarizada) is the 18-digit account identifier used in all SPEI transfers. The SDK validates every CLABE before dispatching a transfer:

  • Length: Exactly 18 digits. No hyphens, spaces, or letters.
  • Bank code: First 3 digits must match a registered BANXICO institution code (90+ institutions supported).
  • City code: Digits 4–6 must be a valid city/plaza code for the issuing bank.
  • Check digit: The 18th digit is verified using the BANXICO weighted modulus-10 algorithm with weights [3, 7, 1, 3, 7, 1, 3, 7, 1, 3, 7, 1, 3, 7, 1, 3, 7].
Validation runs locally in the SDK before any network request. If the CLABE is invalid, the tool returns an error immediately with code SPEI_INVALID_CLABE. No SMS is sent and no charge occurs.

Code example

The following shows the full conversational 2FA flow from the SDK's perspective. In practice, the AI client handles the conversation turns automatically.

// User: "Send 500 MXN to CLABE 014027000005555558, concept: Invoice #42"

// ── Turn 1: AI calls tool without verification code ──────────────────────────
// Tool call: spei_send_payment
// {
//   clabe: "014027000005555558",
//   amount: 50000,          // 500 MXN in centavos
//   concept: "Invoice #42",
//   recipientName: "Empresa Demo SA de CV"
// }
//
// SDK response:
// {
//   status: "2fa_required",
//   message: "Verification code sent via SMS. Please provide the code."
// }

// ── AI tells user: "Please enter the code you received" ──────────────────────

// ── Turn 2: User replies "The code is 847291" ─────────────────────────────────
// Tool call: spei_send_payment (same params + verificationCode)
// {
//   clabe: "014027000005555558",
//   amount: 50000,
//   concept: "Invoice #42",
//   recipientName: "Empresa Demo SA de CV",
//   verificationCode: "847291"
// }
//
// SDK response:
// {
//   status: "success",
//   trackingKey: "2024012614574900000012345678",
//   amount: 50000,
//   currency: "MXN",
//   settledAt: "2024-01-26T14:57:52Z"
// }

Error codes

CodeDescription
SPEI_INVALID_CLABECLABE fails checksum or length validation
SPEI_UNKNOWN_BANKBank code extracted from CLABE is not recognized
SPEI_LIMIT_EXCEEDEDTransfer amount exceeds the allowed limit for this license tier
SPEI_INSUFFICIENT_FUNDSSource account has insufficient balance
SPEI_RECIPIENT_REJECTEDReceiving bank rejected the transfer
SPEI_TIMEOUTTransfer timed out waiting for BANXICO confirmation

For the full error code reference including license and 2FA errors, see Error Codes.

Next steps