Wallet & funding

Your prepaid MXN balance: fund via SPEI, card, or PayPal and review every transaction.

The wallet (monedero) is your prepaid balance in Mexican pesos: every label is debited from it at the quoted price. Fund it by SPEI transfer to your dedicated CLABE, by card, or with PayPal.

Endpoints

Fund via SPEI (recommended)

Every organization gets a dedicated CLABE: any SPEI transfer to that account is credited to your wallet automatically, with no manual reconciliation.

curl -X POST https://api.sendit.mx/v1/wallet/funding-instructions \
  -H "Authorization: Bearer <jwt>"

{
  "success": true,
  "data": {
    "id": "clxfund123abc",
    "type": "mx_bank_transfer",
    "clabe": "646180111812345678",
    "bankName": "STP",
    "bankCode": "646",
    "status": "ACTIVE",
    "createdAt": "2026-07-17T01:00:00.000Z"
  }
}

The endpoint is idempotent: calling it again returns the same CLABE. Share it with your finance team and fund by SPEI from any bank. The credit shows up within minutes as a CREDIT transaction.

Fund with a card

curl -X POST https://api.sendit.mx/v1/wallet/fund/card \
  -H "Authorization: Bearer <jwt>" \
  -H "Idempotency-Key: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500 }'

{
  "success": true,
  "data": {
    "paymentIntentId": "pi_3QyAbc123xyz",
    "clientSecret": "pi_3QyAbc123xyz_secret_def456",
    "amount": 500,
    "currency": "MXN",
    "publishableKey": "pk_test_xxxxx"
  }
}

Body parameters

Use the clientSecret with Stripe.js on your frontend to collect the card and complete 3D Secure. Once confirmed, the wallet is credited automatically.

PayPal funding works the same via POST /v1/wallet/fund/paypal (accepts an optional returnUrl for the post-approval redirect).

Check the payment status

GET /v1/wallet/fund/pi_3QyAbc123xyz/status

{
  "success": true,
  "data": {
    "paymentIntentId": "pi_3QyAbc123xyz",
    "status": "succeeded",
    "amount": 500,
    "currency": "MXN",
    "paymentMethodType": "card",
    "walletCredited": true
  }
}

When status is succeeded and walletCredited is true, the balance already reflects the funding.

Fund with OXXO (cash)

To pay in cash, use POST /v1/wallet/fund/oxxo. It generates a voucher with a barcode: show or print it and pay at any OXXO store. The voucher expires in 3 days. The wallet is credited once OXXO confirms payment, so treat it as pending until then. Check it through /v1/wallet/fund/:paymentIntentId/status.

Body parameters

curl -X POST https://api.sendit.mx/v1/wallet/fund/oxxo \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500 }'

{
  "success": true,
  "data": {
    "paymentIntentId": "pi_3Oxxo123xyz",
    "hostedVoucherUrl": "https://payments.stripe.com/oxxo/voucher/...",
    "expiresAfter": 1800000000,
    "amount": 500,
    "currency": "MXN"
  }
}

hostedVoucherUrl is the printable voucher. expiresAfter is a Unix timestamp in seconds. The balance updates after the cash payment clears. Until then the transaction stays pending.

Check your balance

GET /v1/wallet/balance

{
  "success": true,
  "data": {
    "id": "clxwallet123",
    "balance": "1500.00",
    "currency": "MXN",
    "lowBalanceThreshold": "100.00",
    "lowBalanceAlertSent": false,
    "hasFundingSource": true
  }
}

Amounts are decimal strings. Never do floating-point arithmetic on money.

With a sk_test_ key this endpoint returns the test balance. See Test mode.

Set the low-balance alert

PATCH /v1/wallet/settings sets the balance at which you want a warning. It requires the ADMIN role or higher, and the wallet:write scope if you use an API key.

curl -X PATCH https://api.sendit.mx/v1/wallet/settings \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "lowBalanceThreshold": 500 }'

Send null to turn the alert off.

Movements summary

For “income vs. expenses” cards without paging through every transaction, GET /v1/wallet/summary aggregates the window you ask for. Both date params are optional (from inclusive, to exclusive):

GET /v1/wallet/summary?from=2026-07-01&to=2026-08-01

{
  "success": true,
  "data": {
    "income": "1050.00",
    "expenses": "730.50",
    "net": "314.50",
    "adjustments": "-5.00",
    "transactionCount": 7,
    "currency": "MXN",
    "byType": {
      "CREDIT": { "count": 2, "amount": "1000.00" },
      "REFUND": { "count": 1, "amount": "50.00" },
      "DEBIT": { "count": 3, "amount": "-730.50" },
      "ADJUSTMENT": { "count": 1, "amount": "-5.00" }
    }
  }
}

income sums credits and refunds. expenses is the magnitude of the debits, which are stored negative. All amounts are decimal strings.

The summary respects the mode of the request. With ?livemode=false it aggregates test movements.

Review your transactions

GET /v1/wallet/transactions?type=CREDIT&page=1&limit=20

{
  "success": true,
  "data": [
    {
      "id": "clxtx_spei_456",
      "type": "CREDIT",
      "amount": "1000.00",
      "currency": "MXN",
      "balanceAfter": "2500.00",
      "description": "Depósito vía transferencia bancaria SPEI",
      "referenceType": "stripe_bank_transfer",
      "status": "COMPLETED",
      "createdAt": "2026-07-17T10:00:00.000Z"
    },
    {
      "id": "clxtx_label_789",
      "type": "DEBIT",
      "amount": "326.82",
      "currency": "MXN",
      "balanceAfter": "1500.00",
      "description": "Compra de guía DHL Express Nacional",
      "referenceType": "label_purchase",
      "referenceId": "clxq1w2e3r4t5y6u7i8o9p0a",
      "metadata": { "carrierCode": "DHL" },
      "status": "COMPLETED",
      "createdAt": "2026-07-17T09:00:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 143, "totalPages": 8 }
}

Card, PayPal, and OXXO fundings share the stripe_payment_intent reference type. To tell them apart, read metadata.funding_method. It holds card, paypal, or oxxo.

Every transaction carries balanceAfter. The history is a complete, auditable statement.

Handle errors