SPEI - Payout

When performing a payout, the customer initiates a payout and then just waits for the funds to be credited to their account. The customer themself doesn't participate in the payout processing procedure.


Countries and regions	Mexico
Payment currencies	MXN
Payment amount limits	Contact your key account manager at Monetix for details. Also you can check the payment amount limits in your project by using Dashboard.
Payment processing time	Contact your key account manager at Monetix for details.
Currency conversion	On the Monetix side
Refund
Onboarding and access fee	Contact your key account manager at Monetix for details.

Operations support


	Interfaces
	Payment Page	Gate	Dashboard
Payout

You can check the payment amount limits in your project by using Dashboard. To check your payment amount limits, go to Dashboard, select the Projects section, and then click the Payment methods tab.

The following sections provide more information about the payment processing flow and the analysis of completed payments.

Payout by using Gate

General information

To perform a payout by using Gate with the SPEI payment method:

Send a request with all the required parameters and signature to the Monetix URL.
Accept the callback with the payout result from the payment platform.

The following picture provides the details of the payout processing flow in the SPEI payment method.

Figure 1. Payout processing flow when performing a payout by using Gate

The customer initiates a payout in your system.
Your system sends the payout request to the Monetix payment platform.
The payment platform sends you a response in which it acknowledges your request and provides the request validation result. (For more information about the response format, see Response structure.)
The payment platform processes the request and forwards it to the provider service.
The provider service informs the payment platform about the payout result.
The payment platform sends a callback with the payout result to your system.
Your system sends the payout result to the customer.

Request

This section provides the instructions on how to build the request for payout with the SPEI payment method.


HTTP request method	POST
Request body format	JSON
API endpoint	`/v2/payment/bank-transfer/spei/payout`
Full API endpoint specification	/v2/payment/bank-transfer/{payment_method}/payout

strictly required—the parameter must be in the initial request.

✱—the parameter may not be required in some cases. Contact your account manager at Monetix for details.

Object Object/Parameter Description

general
object
strictly required

project_id
integer
strictly required

Project ID you obtained from Monetix when integrating.

Example: 1234

payment_id
string
strictly required

Payment ID unique within your project.

Example: payment_47

signature
string
strictly required

Signature created after you've specified all the request parameters. For more information about signature generation, see Signature generation and verification.

customer
object
strictly required

id
string
strictly required

Unique ID of the customer within your project.

Example: customer_123

ip_address
string
strictly required

IP address of the customer's device.

Example: 198.51.100.47

first_name
string
strictly required

Customer's first name.

Example: John

last_name
string
strictly required

Customer's last name.

Example: Doe

email
string
strictly required

Customer's email.

Example: johndoe@example.com

identify
object
strictly required

doc_number
string
strictly required

Identity document number, only digits without spaces and punctuation. This number must correspond to the identity document type passed in the doc_type parameter. If you don't need to use doc_type parameter, set this parameter to the number of CURP (contains 18 digits).

Example: 123456789123456789

doc_type
string
strictly required✱

Identity document type.

Possible values:

CURP—when you pass an identity code, which is assigned to both citizens of Mexico and foreign citizens, who live in Mexico (Clave Única de Registro de Población), in the doc_number parameter. Consists of 18 symbols
RFC—when you pass a tax identification number in Mexico (Registro Federal de Contribuyentes) in the doc_number parameter. Consists of 13 symbols

Example: CURP

account
object
strictly required

number
string
strictly required

Payment details for payout performing. The type of provided payment details must correspond to the payment details type passed in type parameter. If you don't need to use type parameter, set this parameter to customer CLABE account number.

Example: 123456789012345678

type
string
strictly required✱

Payment details type.

Possible values:

CLABE—when you pass customer CLABE account number in the number parameter
PHONE—when you pass customer phone number in the number parameter
DEBIT—when you pass customer payment card number in the number parameter

Example: CLABE

bank_id
integer
strictly required✱

Customer's bank ID. For information on how to get the list of the supported banks IDs, see Banks available for payout.

Example: 1861

payment
object
strictly required

currency
string
strictly required

Code of the payment currency in the ISO-4217 alpha-3 format.

Example: MXN

amount
integer
strictly required

Payment amount in minor currency units without any decimal point or comma except for the cases when the currency doesn't have any minor currency units.

If the currency doesn't have any minor units (i.e. the number of digits for minor currency units is zero), set this parameter to the amount in the major currency units. To check whether the currency has any minor units, see Currency codes.

Example: 10,000.00 MXN must be sent as 1000000

You can also add any other optional parameters to the payout request, if necessary. For the list of all the parameters available in Gate, see API Reference.

Here is an example of the data from a request to initiate a payout with the SPEI payment method:

Figure 2. Example of the payout request body

{
    "general": {
        "project_id": 1234,
        "payment_id": "payment_47",
        "signature": "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO/RLUkDJrOcZzUCwX6R/ekpZhkIQg=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com",
        "identify": {
            "doc_number": "123456789123456789",
            "doc_type": "CURP"
        }
    },
    "account": {
        "number": "123456789012345678",
        "type": "CLABE",
        "bank_id": 1861
    },
    "payment": {
        "currency": "MXN",
        "amount": 1000000
    }
}

Callback

In the SPEI payment method, the payment platform returns the payout result in a callback. For the information about the callback structure, see Callbacks in Gate.

The following is an example of a callback body with the information about a successfully completed payout.

Figure 3. Example of the data from a successful payout callback

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "payout",
        "status": "success",
        "date": "2024-12-07T19:08:45+0000",
        "method": "spei",
        "sum": {
            "amount": 1000000,
            "currency": "MXN"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 47,
        "type": "payout",
        "status": "success",
        "date": "2024-12-07T19:08:45+0000",
        "created_date": "2024-12-07T19:08:05+0000",
        "request_id": "1a23456bc7890de",
        "sum_initial": {
            "amount": 1000000,
            "currency": "MXN"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "MXN"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-123",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4XrUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

The following is an example of a callback for a declined payout.

Figure 4. Example of the data from a declined payout callback

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "payout",
        "status": "decline",
        "date": "2024-12-07T19:08:45+0000",
        "method": "spei",
        "sum": {
            "amount": 1000000,
            "currency": "MXN"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 47,
        "type": "payout",
        "status": "decline",
        "date": "2024-12-07T19:08:45+0000",
        "created_date": "2024-12-07T19:08:05+0000",
        "request_id": "1a23456bc7890de",
        "sum_initial": {
            "amount": 1000000,
            "currency": "MXN"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "MXN"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-123",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4XrUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

Payout by using Dashboard

To make a payout through Dashboard, the merchant sends a request and receives a notification with the request processing result. There are two ways to initiate payouts through Dashboard:

single payout—you specify the currency and amount for a payout available for this method and fill in all the fields required for the selected payment method on the Dashboard pages.
as a part of a mass payment—all the parameters are specified in a CSV file. Refer to the Payouts by using Gate section for the parameters required by your payment method.

Information about completed payouts is available for viewing in the Payments and Manual Payments sections of Dashboard.

For more information about payout processing by using Dashboard, see Performing payouts.

Banks available for payout

Supported banks

In the SPEI payment method, payments are performed through the banks the payment method supports. For the payout to be performed, your request must contain the ID of the customer's bank in the account.bank_id parameter.

The table below lists the banks available for payout in the SPEI payment method.

Table 2. Banks available for payout
Bank	ID
Abc Capital	65621
Actinver	65591
Afirme	65481
Akala	72122
American Express Bank (Mexico)	71862
Arcus	66081
Asp Integra Opc	65981
Autofin	65551
Azteca2	66171
Bajio	65431
Banamex	1891
Banamex2	66131
Banco Azteca	1841
Banco Finterra	65721
Banco Inbursa	1821
Banco S3	65781
Bancomext	65361
Bancoppel	65611
Bancrea	65711
Banjercito	65381
Bank Of America	65491
Bank Of China	6577
Bankaool	65671
Banobras	65371
Banorte	1881
Banorte2	66161
Banregio	65451
Bansefi	65401
Bansi	65471
Banxico	65351
Barclays	65561
Bbase	65661
BBVA Bancomer	1871
Bbva Bancomer2	66141
BBVA Mexico	65421
Bmonex	65521
Caja Pop Mexica	66001
Caja Telefonist	66021
Cb Intercam	65881
Ci Bolsa	65891
Cibanco	65651
Codi Valida	66111
Compartamos	65571
Consubanco	65631
Credicapital	65951
Credit Suisse	65541
Cristobal Colon	66011
Deutsche Bank Mexico	71892
Donde	65701
Estructuradores del Mercado de Valores Casa de Bolsa	71942
Evercore Casa de Bolsa	72152
Finamex	65851
Fincomun	65901
Fomped	66061
Fondo Fira	66041
Gbm	65801
HDI Seguros	72102
Hipotecaria Fed	65411
HSBC Mexico	1811
Hsbc2	66151
Icbc	65731
Indeval	66101
Inmobiliario	65691
Intercam Banco	65601
Invercap	66051
Invex	65461
Jp Morgan	65511
Kuspit	65961
Libertad	65991
Masari	65811
Mifel	65441
Mizuho Bank	65761
Monexcb	65791
Mufg	65501
Multiva Banco	65581
Multiva Cbolsa	65841
Nafin	65391
Nu Mexico	65911
Nvio	66091
Pagatodo	65681
Profuturo	65871
Reforma	65921
Sabadell	65741
Santander MX	1851
Santander2	66121
Scotiabank Mexico	1861
Shinhan	65751
Stp	65931
Tactiv Cb	65941
Tesored	66071
Transfer	66031
Unagra	65971
Valmex	65861
Value	65821
Ve Por Mas	65531
Vector	65831
Volkswagen	65641

The table with the list of banks is provided for informational purposes only. It may change without notice. To get the current list of banks the SPEI payment method supports, send a request to the payment platform.

Request for the list of available banks

The list of banks may change that's why we recommend that you send the payment platform a request for the list of banks currently available in the SPEI payment method. The request format and structure should be the following:


HTTP request method	POST
Request body format	JSON
API endpoint	`/v2/info/banks/bank-transfer/spei/payout/list`
Full API endpoint specification	/v2/info/banks/{parentMethod}/{childMethod}/{operationType}/list

strictly required—parameter is required in the initial request.

Object Parameter Description

general
object
strictly required

project_id
integer
strictly required

Project ID you obtained when integrating with Monetix.

Example: 123

payment_id
string
strictly required

Payment ID unique within the project.

If the payment is not yet created, set this parameter to a unique value.

Example: payment_47

signature
string
strictly required

Signature created after you specify all the required parameters. For more information about, signature generation, see Signature generation and verification.

payment
object
strictly required

amount
integer
strictly required

Payment amount in minor currency units without any decimal point or comma except for the cases when the currency doesn't have any minor currency units.

Example: 10,000.00 MXN must be sent as 1000000

currency
string
strictly required

Code of the payout currency in the ISO-4217 alpha-3 format.

Example: MXN

You can also add any other optional parameters to the request, if necessary. For the list of all the parameters available in Gate, see API Reference.

Here is an example of the data from the request for the list of banks available in the SPEI payment method.

Figure 5. Example of the data from the request for the list of available banks

{
    "general": {
        "project_id": 200,
        "payment_id": "ORDER_155860015",
        "signature": "K6jll2ym+PtOb3ocZtr345st...=="
    },
    "payment": {
        "amount": 1000000,
        "currency": "MXN"
    }
}

Figure 6. Example of the response with the list of banks available in the payment method

[
    {
        "minAmount": 100, // Minimum payment amount allowed for the payment (in minor currency units)
        "maxAmount": 1000, // Maximum payment amount allowed for the payment (in minor currency units)
        "limitCurrency": "MXN", // Code of the currency used for the payment limits (minAmount and maxAmount) in the ISO-4217 alpha-3 format
        "id": 123, // Bank ID
        "abbr": "EXB", // Bank shortcut name (for internal use)
        "name": "Example Bank", // General bank name
        "nativeName": "Example Bank", // Native bank name
        "currencies": [ // Array with currencies supported by the bank
            {
                "id": 123, // Currency ID in the payment platform
                "alpha_3_4217": "MXN", // Alphabetic code of the payment currency in the ISO-4217 alpha-3 format
                "number_3_4217": "123", // Numeric code of the payment currency in the ISO-4217 alpha-3 format
                "currency_type": "fiat", // Type of the currency
                "exponent": 2 // Number of decimal places after decimal point
            }
        ]
    }
]