Skip to main content

KYC - MXN (Fiat)

To operate MXN fiat (Mexican Peso) with Avenia, the user must complete MXN KYC in addition to standard identity verification.

info

KYC Level 1 must be completed and approved before you can request MXN KYC. Complete Level 1 first using the KYC Level 1 guide.

You can request MXN KYC from the Avenia dashboard or via the API described below.

The status lifecycle of an MXN KYC attempt is the same as for KYC Level 1 (for example PENDING, PROCESSING, COMPLETED, with result APPROVED or REJECTED). Track progress with List All KYC Attempts and Get KYC Attempt by ID in the KYC Level 1 guide. If webhooks are enabled for your account, you will receive the same KYC event types as for other KYC flows.

info

MXN KYC is processed through Avenia's MXN fiat rail. When approval completes, the user's MXN rail is unlocked and they can create MXN payins / payouts via the Operations endpoints.

Request MXN KYC via API​

Use this endpoint to start an MXN KYC request programmatically. No request body is required.

HTTP POST Request​

https://api.sandbox.avenia.io:10952/v2/kyc/mxn/api

Query parameters​

ParameterTypeRequiredDescription
subAccountIdstringNoWhen requesting MXN KYC for a subaccount, pass the subaccount ID as a query parameter.

cURL Example (main account)​

curl -X POST "https://api.sandbox.avenia.io:10952/v2/kyc/mxn/api" \
     -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

cURL Example (subaccount)​

curl -X POST "https://api.sandbox.avenia.io:10952/v2/kyc/mxn/api?subAccountId=1ee0a663-922b-4389-9f84-074ccff7085d" \
     -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
tip

For subaccounts, the same subAccountId query parameter pattern applies when listing or fetching KYC attempts for that user.

Response​

201 Created with a JSON body identifying the KYC attempt. Poll the attempt via the Level 1 endpoints to watch the status transition to COMPLETED / APPROVED.

Confirming approval​

Once the attempt is approved, mxnUnlocked flips to true on the account metadata endpoint:

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/metadata" \
     -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
{
  "brlUnlocked": true,
  "usdUnlocked": false,
  "eurUnlocked": false,
  "arsUnlocked": false,
  "copUnlocked": false,
  "mxnUnlocked": true,
  "swiftUsdUnlocked": false
}

See About Login — Metadata for the full response shape.

Common Errors​

ErrorHTTPCause
complete basic kyc first400KYC Level 1 is not approved yet for this user. Finish Level 1 before requesting MXN KYC.
mxn kyc already approved400The MXN rail is already unlocked for this user — the request is a no-op.
missing required document: identification document400The user's Level 1 submission has no usable identification document on file. Re-upload the identity document in Level 1, then retry.

Scenarios​

The endpoint is idempotent per user and adapts to the current fiat-rail KYC state:

Current state for this userWhat happens on POST /v2/kyc/mxn/api
No fiat-rail KYC yetA new fiat-rail profile is created, your Level 1 KYC documents are submitted, and a new KYC attempt is returned. You will receive KYC-STARTED → KYC-PROCESSING → KYC-COMPLETED webhooks.
Fiat-rail KYC already approved (e.g. user previously passed for COP or ARS)Skips the re-verification round-trip, enables the MXN rail immediately, and emits the full KYC-STARTED → KYC-PROCESSING → KYC-COMPLETED (APPROVED) webhook lifecycle so the client experience is identical.
Fiat-rail KYC pending (still awaiting verification)Registers the MXN currency as part of the in-flight workflow and returns the attempt ID. Approval webhooks fire when verification finishes.