SPEI CLABE per Customer

Once activated for your Shop, this tool will allow you to leverage the power of our Customer Management Module to accept SPEI payments through two different flows:

The traditional flow where you create a transaction in our system and then receive notifications for its status updates
The Direct deposit flow, where a Customer will be able to make deposits directly into their Virtual Account, and you will receive notifications of the transaction creation and its status.

The first thing you will need to do to start using the SPEI CLABE per customer model is to send us the two URLs needed for notifications:

Virtual Account Payment Notification Url: This is where you will receive the webhooks related to transfers made into a Virtual Account
Default Customer Events Notification Url: This is where you will receive the webhooks related to changes made in the Customer Management Module.

As explained in the Customer Management Module page, when the Customer initiates a Transaction for the first time a Customer entity will be created in the system. This requires that the Transaction request includes a valid CURP (personalId) or a uniqueCustomerIdentifier. Here is an example of a Transaction request:

{
  "paymentMethodTagName": "SPEI",
  "amount": "10000",
  "currency": "MXN",
  "description": "Payment Test",
  "testMode": true,
  "trackingId": "10010000A100031",
  "language": "ES",
  "notificationUrl": "https://payment-form.payretailers.com/notification",
  "returnUrl": "https://payment-form.payretailers.com/return",
  "customer": {
    "uniqueCustomerIdentifier": "PERM850515MDFPRD32",
    "personalId":"PERM850515MDFPRD32",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "country": "MX",
    "city": "Ciudad de México",
    "zip": "06010",
    "address": "República de Perú 177",
    "phone": "5299999999999",
    "deviceId": null,
    "ip": "150.125.18.159"
  }
}

When that happens you will receive a notification that looks like this sent to your Default Customer Events Notification Url:

{
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "eventType": "CUSTOMER_CREATED",
  "entityId": "CUST123456",
  "entityType": "CUSTOMER",
  "timestamp": "2025-04-02T15:30:00Z"
}

After this Customer entity is created, the CLABE shown in the checkout page will be the Customer's unique CLABE, associated to their own newly created virtual account. The customer will then be able to make direct deposits into this account without going through the steps to create a new transaction.

When a Customer makes a direct deposit into their virtual account, you will receiver a webhook notification sent to your Virtual Account Payment Notification Url. These webhooks will look the same as the normal notifications for Transaction status updates, but will include the parameter "type": "virtual_account_payment" and "uniqueCustomerIdentifier":"string" (the second one in the Customer object).

Virtual Account Payment Webhook:

{
    "uid": "asdasda-6972-4efe-bb4d-4d2075e2c864",
    "type": "virtual_account_payment",
    "status": "APPROVED",
    "message": null,
    "trackingId": "1111111-6972-4efe-bb4d-aaaaaa",
    "amount": 2000,
    "currency": "MXN",
    "amountChanged": false,
    "originalAmount": 0,
    "newCouponAmount": null,
    "newCouponCurrency": null,
    "description": "string",
    "cardNumber": null,
    "createdAt": "2025-04-02T14:27:51.102778Z",
    "updatedAt": "2025-04-02T14:27:51.102778Z",
    "customer": {
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "country": "MX",
        "city": "string",
        "zip": "",
        "address": "string",
        "phone": "string",
        "deviceId": "",
        "ip": "string",
        "personalId": "string",
        "uniqueCustomerIdentifier":"string"
      },
    "billing": {
        "currency": "MXN",
        "amount": 2000
      },
    "paymentMethod": {
        "id": "string",
        "name": "string",
        "type": "string"
      },
    "payer": {
        "payerName": "string",
        "name": "string",
        "lastName": "string",
        "personalId": "string",
        "payoutAccountTypeCode": "string",
        "accountused": "string",
        "accountNumber": "string",
        "accountAgencyNumber": "string",
        "bankTrackingID": "string",
        "bankName": "string",
        "maskCardNumber": "string"
      }
}

Once this solution is implemented there will be some new error messages that you will need to contemplate. Please check our error messages section in our Transaction Error Messages section in our API reference.