🇲🇽Mexico

Check the requirements and validations made over the cashouts on Mexico

Required fields

Field	Format	Description
login	String	Cashouts login
pass	String	Cashouts pass
external_id	String (max length: 100)	Transaction's ID on your end
document_id	Length between 7 and 18 inclusive. CURP / RFC / IFE / PASS	Beneficiary's document ID
country	MX	The country codes are in ISO 3166-1 alpha-2 format.
currency	MXN / USD	The currencies are in ISO 4217 format.
amount	Number with up to 2 decimals	Cashout amount
bank_code	See bank codes	Code specifying the beneficiary's bank. Only mandatory if the bank_account is a debit card
bank_account	See validations below	Beneficiary's bank account
beneficiary_name	String (max length: 100)	Beneficiary's name
beneficiary_lastname	String (max length: 100)	Beneficiary's last name

Cashouts to debit cards

In Mexico, we accept cashouts to be sent directly to debit cards.

Note that specifically those cashouts, must be sent through a different endpoint URL:

• STG endpoint for Debit Cards: https://cc-api-stg.directa24.com/v3/cashout

• PROD endpoint for Debit Cards: Email [email protected] with your cashout API Key

The bank accounts in Mexico are in CLABE format (numeric) and have 18 digits (without dashes). Therefore one way to detect that a bank account specified by the customer is a debit card is by checking with the luhn algorithm if it is a valid card number and/or with a regex for each brand, like the example below.

public static final String SENSIBLE_DATA_PATTERN = new StringBuilder("(?:(?<visa>4[0-9]{12}(?:[0-9]{3})?)")
      .append("|(?<mastercard>5[1-5][0-9]{14})")
      .append("|(?<discover>6(?:011|5[0-9]{2})[0-9]{12})")
      .append("|(?<amex>3[47][0-9]{13})")
      .append("|(?<diners>3(?:0[0-5]|[68][0-9])?[0-9]{11})")
      .append("|(?<jcb>(?:2131|1800|35[0-9]{3})[0-9]{11}))")
      .toString();

private boolean validateCreditCard(CashoutRequestDto request) {
   final String bankAccount = request.getBank_account();
   if (StringUtils.isEmpty(bankAccount) || !LuhnCheckDigit.LUHN_CHECK_DIGIT.isValid(bankAccount) || 
      bankAccount.matches(Constants.SENSIBLE_DATA_PATTERN)) {
      return false;
   }
   return true;
}

If true, send the request through the cc-api endpoint, if false send it through the normal endpoint. The integration and requirements remains exactly the same, only changing the error message returned in case of invalid bank account and that we validate the bank_account sent to be a valid credit card number using the Luhn Algorithm.

Ensure to match debit card cashouts with correct URL.

Sending a debit card number through the non-cc endpoint will make the request to fail with the following error:

{
    "code": 300,
    "message": "bank_account: Invalid bank account, it shouldn't be a credit card"
}

Also, you may receive the following error if an invalid bank_account is sent to the cc-api endpoint:

{
    "code": 300,
    "message": "bankAccount: invalid credit card number"
}

bank_account validations

Below you will find the format and value validations that we perform on the bank_account parameter.

Bank name	Bank code	Format	Example
All	-	CLABE: 18 digits long, applies verifier algorithm.	021790064060296642
All	-	Debit cards: 15-16 digits long, applies verifier algorithm. Can only be sent through the Cashout to Debit Cards Endpoint.	5344867217683750
Todito	10000	10 digits long.	2682883311
Kiosko	10008	Empty string	-

CLABE validation algorithm

Click here for more information about CLABE format.

Since the first three digits of the CLABE are the bank code, it is not mandatory to send the bank_code field.

Java

Mexico CLABE validation algorithm in Java

public final class Validations {
    static int CLABE_LENGTH = 18;
    
    private static boolean validateClabeLength(String bankAccount) {
        return bankAccount.length() == CLABE_LENGTH;
    }
    
    private static boolean validateClabe(String clabe) {
        if (!validateClabeLength(clabe)) {
            return false;
        } else {
            int sum = 0;
            String clabeWithoutCd = clabe.substring(0, 17);
            Integer[] array = new Integer[]{3, 7, 1};
    
            int checkDigitToVerify;
            for(checkDigitToVerify = 0; checkDigitToVerify < clabeWithoutCd.length(); ++checkDigitToVerify) {
                int digit = clabeWithoutCd.charAt(checkDigitToVerify);
                sum += digit * array[checkDigitToVerify % 3] % 10;
            }
    
            checkDigitToVerify = (10 - sum % 10) % 10;
            int checkDigit = Integer.parseInt(clabe.substring(17));
            return checkDigitToVerify == checkDigit;
        }
    }
}

Example request

{
    "login": "xxxxxxxx",
    "pass": "xxxxxxxx",
    "external_id": "30000000001",
    "country": "MX",
    "currency": "MXN",
    "amount": 100,
    "document_id": "848392783",
    "bank_account": "021790064060296642",
    "beneficiary_name": "User",
    "beneficiary_lastname": "Test",
    "notification_url": "https://webhook.site/url",
    "type": "json"
}

Bank codes

Cashouts to Debit Cards

Notice that the bank_code for Mexico is only mandatory if the bank_account length is between 15 and 16 (debit card). In that case, use the Cashout to Debit Cards endpoint URL: https://cc-api-stg.directa24.com/v3/cashout

Bank code retrieval via API

For the full and most up-to-date list of banks and its codes, please check this endpoint Get bank codes

Bank	Code
BANAMEX	002
BANCOMEXT	006
BANOBRAS	009
BBVA BANCOMER	012
SANTANDER	014
BANJERCITO	019
HSBC	021
BAJIO	030
IXE	032
INBURSA	036
INTERACCIONES	037
MIFEL	042
SCOTIABANK	044
BANREGIO	058
INVEX	059
BANSI	060
AFIRME	062
BANORTE	072
THE ROYAL BANK	102
AMERICAN EXPRESS	103
BAMSA	106
TOKYO	108
JP MORGAN	110
BMONEX	112
VE POR MAS	113
ING	116
DEUTSCHE	124
CREDIT SUISSE	126
AZTECA	127
AUTOFIN	128
BARCLAYS	129
COMPARTAMOS	130
BANCO FAMSA	131
BMULTIVA	132
ACTINVER	133
WALMART	134
NAFIN	135
INTERBANCO	136
BANCOPPEL	137
ABC CAPITAL	138
UBS BANK	139
CONSUBANCO	140
VOLKSWAGEN	141
CIBANCO	143
BBASE	145
BANKAOOL	147
PAGATODO	148
INMOBILIARIO	150
DONDE	151
BANCREA	152
BANCO COVALTO	154
SABADELL	156
BANSEFI	166
HIPOTECARIA FEDERAL	168
MONEXCB	600
GBM	601
MASARI	602
VALUE	605
ESTRUCTURADORES	606
TIBER	607
VECTOR	608
B&B	610
MERRILL LYNCH	615
FINAMEX	616
VALMEX	617
UNICA	618
MAPFRE	619
PROFUTURO	620
CB ACTINVER	621
OACTIN	622
SKANDIA VIDA	623
CBDEUTSCHE	626
ZURICH	627
ZURICHVI	628
SU CASITA	629
CB INTERCAM	630
CI BOLSA	631
BULLTICK CB	632
STERLING	633
FINCOMUN	634
HDI SEGUROS	636
ORDER	637
NUBANK	638
CB JPMORGAN	640
REFORMA	642
STP	646
TELECOMM	647
EVERCORE	648
SKANDIA OPERADORA	649
SEGMTY	651
ASEA	652
KUSPIT	653
SOFIEXPRESS	655
UNAGRA	656
OPCIONES EMPRESARIALES DEL NOROESTE	659
LIBERTAD	670
MERCADO PAGO W	722
CLS	901
INDEVAL	902
Todito	10000
Kiosko	10008

Handling payout status exceptions in Mexico

For payouts processed in Mexico, it's important to know how to handle exceptional cases where an initial "Completed" status is not the final one.

Although this is not the common flow, a payout can occasionally appear as "Completed" for a few seconds before the processor issues the final, "Rejected" status. In addition to this, there are rare corner cases where a beneficiary's bank may return a payment days later, which will also lead to the status being updated to "Rejected."

To ensure your system is robust enough to handle these exceptions, please configure it to always accept a "Rejected" status as the authoritative and final state for a transaction, even if a "Completed" notice was received first.