SPEI transaction

You can submit a SPEI transaction in these ways:

• Purchase (deposit): Create a pay-by-bank transaction with apmProvider set to Spei and intent set to Purchase. Redirect the shopper to fundingData.payByBank.redirectUrl so they can complete the transfer.
• Payout (withdrawal), new bank account: Create a pay-by-bank transaction with intent set to Payout and supply all three of bankAccountNumber, bankCode, and accountType. Don't also send gatewayTokenId. Capture fundingData.payByBank.gatewayTokenId from the response to reuse the destination later.
• Payout (withdrawal), stored bank account: Create a payout and supply gatewayTokenId from an earlier accepted payout instead of resending bank details.

SPEI supports MXN only and shoppers in Mexico (countryCode MX). Treat merchant webhooks as the authoritative final outcome. Don't treat the shopper's browser return from the hosted page as payment confirmation. Learn more about webhooks.

{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "SPEI-TXN-001",
  "merchantTransactionDate": "2024-01-27T08:51:02.826445+00:00",
  "transactionMethod": {
    "intent": "Purchase",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Spei",
      "language": "ES"
    }
  },
  "amounts": {
    "transaction": 100,
    "currencyCode": "MXN"
  },
  "shopper": {
    "id": "Shopper_MX_01",
    "firstName": "Juan",
    "lastName": "Garcia",
    "dateOfBirth": "1990-01-01",
    "email": "juan.garcia@example.com",
    "countryCode": "MX",
    "documentType": "TaxIdNumber",
    "documentNumber": "HEGJ850101ABC",
    "phoneNumber": "+5215555555555"
  }
}

If your request is successful, you'll receive a 200 response. fundingData.payByBank.apmProvider is always Spei. Optional fields under fundingData.payByBank are omitted when they have no value, rather than returned as null.

For a successful SPEI purchase initiation, expect a Pending state, a populated fundingData.payByBank.redirectUrl, plus paymentId and processorPaymentId when known. For a successful SPEI payout initiation, expect Pending with no redirectUrl, plus paymentId, processorPaymentId, and gatewayTokenId when each is stored. On payout, status is omitted until the status poll completes.

fundingData.payByBank.status is the raw, unmapped provider status. Use the top-level mapped state for the transaction outcome.

The final outcome is delivered by a SPEI merchant webhook (e.g., spei-transaction-order-executed). Learn more about webhooks.

Always use the systemTransactionId for later PXP API calls against the same transaction. Provider payment identifiers (providerTransactionId, fundingData.payByBank.paymentId, and fundingData.payByBank.processorPaymentId) are for reconciliation and support only. When both are present, providerTransactionId and fundingData.payByBank.processorPaymentId carry the same value.

{
  "state": "Pending",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "merchantTransactionDate": "2024-01-27T08:51:02.826Z",
  "merchantTransactionId": "SPEI-TXN-001",
  "providerTransactionId": "9a4c7e21-3f5d-4b8e-8a1c-2d3e4f5a6b7c",
  "fundingData": {
    "payByBank": {
      "apmProvider": "Spei",
      "redirectUrl": "https://hosted-payment-page.example/spei/...",
      "paymentId": "6f2b6d0a-8b1a-4e2b-9c3d-0a1b2c3d4e5f",
      "processorPaymentId": "9a4c7e21-3f5d-4b8e-8a1c-2d3e4f5a6b7c"
    }
  }
}