Money Out to Debit Card

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Debit cards have a CLABE associated with them, but sometimes you will only have the debit card number (16 digits) and not the associated CLABE. You can send a SPEI transaction directly to a debit card. To do this, you must first register an Instrument with the card's details.

Create an Instrument

Endpoint:
POST /v1/clients/{{clientId}}/instruments

Request
Path parameters:

• clientId: c2d1d1e3-3340-4170-980e-e9269bbbc551

Query Parameters: none
Request Body:

{
  "source_bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "client_id": "{{clientId}}",
  "customer_id": "{{customerId}}",
  "type": "RECEIVER",
  "rfc": "XAXX010101000",
  "alias": "Tarjeta de Debito A",
  "debit_card": {
    "destination_bank_id": "d3435bd9-998d-4e8a-9067-6b71d5fd3ac7",
    "card_number": "5579072268574100",
    "holder_name": "Pedro Navajas Dos"
  }
}

Notes:

• holder_name must have a maxLength of 40 characters.
• If you don’t have the RFC for the card holder, you can send ND.

In this example we are using the bank_id for Banamex, you can use the /v1/banks endpoint to search for other Banks.

Field notes

• customer_id (string, optional)

  • If provided, the instrument will be owned by this customer.

  • If omitted, the instrument belongs to the client itself.

• type (string, required)

  • For debit card instruments, only RECEIVER is supported.

• rfc (string, required)

  • Tax identifier of the card holder. If you don’t have it, you can send ND.

Response
Status Code: 200 OK
Response Body:

{
  "id": "dd7f8d89-94dd-43ca-871b-720fde378b52",
  "bankId": "d3435bd9-998d-4e8a-9067-6b71d5fd3ac7",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "alias": "Tarjeta con expiracion",
  "type": "RECEIVER",
  "instrumentDetail": {
    "cardNumber": "5579072268574100",
    "expirationDate": "None",
    "holderName": "Pedro Navajas Dos"
  },
  "audit": {
    "createdAt": "2025-05-19 19:03:51.084659-06:00",
    "updatedAt": "2025-05-19 19:03:51.084659-06:00",
    "deletedAt": "None",
    "blockedAt": "None"
  },
  "rfc": "XAXX010101000",
  "customerId": "bb1e8fde-e68e-48e9-a483-d32153c752c2"
}

Response field notes

• customerId (string, optional) – Present when the instrument belongs to a customer. Omitted for client-level instruments.

Money Out

With the instrument associated to the recipient's Debit Card, and the default Instrument associated with your Centralizing Account, we have all the required data to initiate Money Out transactions.

This endpoint supports Idempotency via the Idempotency-Key header (TTL: 24 hours).
Reuse the same key with the exact same body for safe retries.
See Guides → Idempotency for details and code snippets.

Endpoint
POST /v1/transactions/money_out

Request
Path parameters: none
Query Parameters: none
Headers:
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: <uuid-v5> (optional but recommended).
Request Body:

{
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "source_instrument_id":  "709448c3-7cbf-454d-a87e-feb23801269a",
  "destination_instrument_id":"dd7f8d89-94dd-43ca-871b-720fde378b52",
  "transaction_request": {
    "external_reference":"7654329",
    "description":"lorem ipsum dolor sit amet",
    "amount":"1.95",
    "currency":"MXN"
  }
}

The value for source_instrument_id is your default instrument
The value for destination_instrument_id is from the previous request

Response
Status Code: 200 OK
Response Body:

{
 "id": "16811ee8-1ef9-4dd4-8d84-9c2df89cf302",
 "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1",
 "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
 "externalReference": "1234567",
 "trackingId": "20250306FINCHVLIKQ5SKUM",
 "description": "lorem ipsum dolor sit amet",
 "amount": "1.95",
 "currency": "MXN",
 "category": "DEBIT_TRANS",
 "subCategory": "SPEI_DEBIT",
 "transactionStatus": "INITIALIZED",
 "audit": {
  "createdAt": "2025-03-06 11:57:55.408000-06:00",
  "updatedAt": "2025-03-06 11:57:55.408000-06:00",
  "deletedAt": "None",
  "blockedAt": "None"
 }
}

Idempotency — common outcomes

• Invalid key format (not UUID v5) → 400 Bad Request
• Key–body mismatch (same key, different body) → 409 Conflict
• Duplicate while first is in-flight → 409 Conflict (“operation … in progress”)
• Identical retry (same key + same body within 24h) → 200 OK (same payload, served from cache)