Verify Mexican accounts

Account verification confirms a Mexican destination account identified by a standardized Mexican bank account number (CLABE), a 16-digit debit card number, or a 10-digit mobile phone number. Fintoc sends a 0.01 MXN micro-deposit from your account balance to the destination. When the verification completes, Fintoc returns the account holder’s information.

Create an account verification

An account verification creates a 0.01 MXN Transfer from your root Account to retrieve the target account holder’s information. Because this call moves money from your account, you must sign the request with a JSON Web Signature (JWS). See setting up JWS keys.

curl --request POST \
     --url https://api.fintoc.com/v2/account_verifications \
     --header 'Authorization: YOUR_TEST_SECRET_API_KEY' \
     --header 'Fintoc-JWS-Signature: YOUR_JWS_SIGNATURE' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "account_number": "000000000000000000"
}
'

const verification = await fintoc.v2.accountVerifications.create({
  account_number: '000000000000000000',
});

verification = client.v2.account_verifications.create(
    account_number="000000000000000000"
)

When you request an account verification, the API returns an account_verification object with a pending status. The holder_id and holder_name fields are null in this initial response. Fintoc populates these fields once the verification succeeds. The response looks like this:

{
  "id": "accv_a1b2c3d4e5f6g7h8",
  "object": "account_verification",
  "status": "pending",
  "reason": null,
  "transfer_id": "tr_a1b2c3d4e5f6g7h8",
  "counterparty": {
    "account_number": "000000000000000000",
    "holder_id": null,
    "holder_name": null,
    "account_type": "clabe",
    "institution": {
      "id": "mx_banco_bbva",
      "name": "BBVA Mexico",
      "country": "mx"
    }
  },
  "mode": "test",
  "receipt_url": null,
  "transaction_date": null
}

Verify a debit card or mobile phone number

A CLABE encodes its bank, but a debit card or mobile phone number does not. To verify one, add the bank’s five-digit institution_id from the Banco de México institution list. If you omit institution_id, the API returns a 400 Bad Request error.

curl --request POST \
     --url https://api.fintoc.com/v2/account_verifications \
     --header 'Authorization: YOUR_TEST_SECRET_API_KEY' \
     --header 'Fintoc-JWS-Signature: YOUR_JWS_SIGNATURE' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "account_number": "4111111111111111",
  "institution_id": "40012"
}
'

const verification = await fintoc.v2.accountVerifications.create({
  account_number: '4111111111111111',
  institution_id: '40012',
});

verification = client.v2.account_verifications.create(
    account_number="4111111111111111",
    institution_id="40012"
)

The API returns the same account_verification object, with account_type set to debit_card or mobile. The response looks like this:

{
  "id": "accv_a1b2c3d4e5f6g7h8",
  "object": "account_verification",
  "status": "pending",
  "reason": null,
  "transfer_id": "tr_a1b2c3d4e5f6g7h8",
  "counterparty": {
    "account_number": "4111111111111111",
    "holder_id": null,
    "holder_name": null,
    "account_type": "debit_card",
    "institution": {
      "id": "40012",
      "name": "BBVA Mexico",
      "country": "mx"
    }
  },
  "mode": "test",
  "receipt_url": null,
  "transaction_date": null
}

For card numbers, account verification supports debit cards only, not credit cards.

Monitor verification status

When Fintoc retrieves the transfer and account holder information, it sends an account_verification.succeeded webhook. This event includes the account holder’s information in an account_verification object with a succeeded status. The event looks like this:

{
  "id": "evt_a4xK32BanKWYn",
  "type": "account_verification.succeeded",
  "object": "event",
  "mode": "test",
  "created_at": "2020-04-17T00:00:00.000Z",
  "data": {
    "account_verification_id": "accv_a1b2c3d4e5f6g7h8",
    "object": "account_verification",
    "status": "succeeded",
    "reason": null,
    "transfer_id": "tr_a1b2c3d4e5f6g7h8",
    "counterparty": {
      "account_number": "000000000000000000",
      "holder_id": "000000000",
      "holder_name": "Test Customer 1",
      "account_type": "clabe",
      "institution": {
        "id": "mx_banco_bbva",
        "name": "BBVA Mexico",
        "country": "mx"
      }
    },
    "mode": "test",
    "receipt_url": "https://www.banxico.org.mx/cep/",
    "transaction_date": "2020-04-17T00:00:00.000Z"
  }
}

If Fintoc cannot retrieve the information, you receive an account_verification.failed webhook with a reason field explaining why the verification failed. For more on receiving webhooks with Fintoc, see the webhooks guide.

​Create an account verification

​Verify a debit card or mobile phone number

​Monitor verification status

Create an account verification

Verify a debit card or mobile phone number

Monitor verification status