Authentication

Every request must be authenticated. The method depends on the product, so check this table before you write your client.

Product	Method	What you send
Fincore	API key, then bearer token	`x-api-key` to get your `client_secret` and create a token. Then `Authorization: Bearer <token>` on every other call.
Direct Debit	API key	`x-api-key` header on every request. You create keys in the Portal.
Billpay	Bearer token	`Authorization: Bearer <api_key>`
Gift Cards	Bearer token	`Authorization: Bearer <token>`
Lottery	Bearer token	`Authorization: Bearer <token>`
Cash	HMAC signature	`X-Client-Id`, `X-Timestamp` and `X-Signature` on every request. See Sign requests with HMAC.

Fincore: create a bearer token

Fincore uses a three-step flow. Monato gives you a clientId and an x-api-key during onboarding.

Get your client secret. Call Retrieve client credentials with your x-api-key. Save client_secret from the response. Treat it like a password and never log it.
Create a token. Call Create authentication token with your x-api-key, client_id and client_secret. Save token from the response.
Call protected endpoints. Send Authorization: Bearer <token> on every other request. Use x-api-key only for steps 1 and 2.

Steps 1 and 2 give you a bearer token that is valid for 24 hours; expires_at tells you when it stops working. Send the token on every protected call.

curl https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/credentials \
  -H "x-api-key: $API_KEY"

curl -X POST https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/auth/credential-tokens \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "00000000-0000-4000-8000-000000000001",
    "client_secret": "your_client_secret_here"
  }'

{
  "id": "00000000-0000-4000-8000-000000000003",
  "client_id": "00000000-0000-4000-8000-000000000001",
  "client_credential_id": "00000000-0000-4000-8000-000000000002",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.fake-payload.fake-signature",
  "status": "ACTIVE",
  "expires_at": "2025-03-06 11:16:59.491631",
  "created_at": "2025-03-05 11:16:59.488685-06:00",
  "updated_at": "2025-03-05 11:16:59.488685-06:00",
  "deleted_at": null
}

The token is valid for 24 hours. Cache it and create a new one before it expires.

expires_at is Mexico City local time (UTC-6), but it is returned without an offset. created_at and updated_at include -06:00. Parse expires_at as UTC-6, or your expiry check will be off by six hours.

If a request returns 401 Unauthorized, check that it reached the right environment and includes Authorization: Bearer <token>. Then create a new token and retry once. If the new token also fails, check that the client, credential, token and environment match.

Direct Debit: API key

Create keys in the Monato Portal under Settings → API Keys. They are active as soon as you create them. You can create several keys per environment, for example one per service, so you can revoke one without affecting the others.

Direct Debit request

curl -X POST https://stg.directdebit.monato.com/charges \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ ... }'

Requests without a valid key get 401 Unauthorized.

Billpay, Gift Cards and Lottery: bearer token

The Monato team gives you the token. Send it in the Authorization header on every request.

Billpay request

curl https://dev-api.finco.lat/api/v1/client/account \
  -H "Authorization: Bearer your_api_key"

For Lottery, Monato also gives you a Payee ID. Lottery returns 401 when the token is invalid or expired.

Cash: HMAC signature

Cash signs every request with your api_secret. Send three headers:

Header	Value
`X-Client-Id`	Your `api_key` (32 characters).
`X-Timestamp`	Unix timestamp in seconds when you created the request.
`X-Signature`	Hex HMAC-SHA256 of `timestamp + "." + requestBody`, using your `api_secret` as the key.

A wrong X-Client-Id or a signature that does not match returns 401. See Sign requests with HMAC for code samples.

Webhooks use a separate mechanism

Webhooks go the other way, from Monato to you, so they are authenticated differently. Check every incoming call before you trust it. See Webhooks.

Keep credentials safe

Never put API keys or secrets in client-side code, public repositories or logs.
Store them in environment variables or a secrets manager.
Use separate keys for sandbox and production.
If a key may be compromised, rotate it right away. Direct Debit keys can be revoked and regenerated in the Portal.