Skip to content

Get sandbox access

Fincore · API reference · Instruments

Tokenize a card

POST /v1/clients/{clientId}/card-tokens

Base URL https://apicore.stg.finch.lat · operationId tokenizeCard

Exchanges a card number encrypted on your side for a token. Register the token as a destination with registerInstrument (card_token) and send it Money Out without storing or sending the card number again.

The body is a compact JWE (RFC 7516) with alg = RSA-OAEP-256, enc = A256GCM and the kid in the protected header, encrypted with the public key Monato delivers for your environment. The plaintext is the JSON described in TokenizerJwePayload. Any undeclared field (for example a CVV) rejects the whole request with 400.

Every call creates a new token, even when the card was tokenized before. Responses carry Cache-Control: no-store.

Authorization

bearerAuth Bearer token

JWT bearer token created from client credentials. Use the Authentication guide to generate a token before calling protected endpoints.

Path parameters

clientId string (uuid) required

Client identifier (UUID). Use the client of the bearer token.

Request body application/jose · required

Responses

201 Token created. application/json

token_id string (uuid) required

Opaque card token. Store it instead of the card number.

first_6 string required

First six digits of the card (BIN).

last_4 string required

Last four digits of the card.

400 SCHEMA_VALIDATION_ERROR: malformed JWE, unknown kid, or a payload that breaks TokenizerJwePayload (including an invalid card number or a tenant_id that is not yours). It deliberately does not say which check failed; fix the request and do not retry it as is. IAT_OUT_OF_WINDOW: iat is outside the accepted window; check your clock and build a new JWE. application/json

code string required

Generic error code.

SCHEMA_VALIDATION_ERROR IAT_OUT_OF_WINDOW UNAUTHORIZED NONCE_REPLAY INTERNAL_ERROR

message string required

Human-readable message, in Spanish.

401 The bearer token is missing, expired or invalid. Renew it. application/json

code string required

Generic error code.

SCHEMA_VALIDATION_ERROR IAT_OUT_OF_WINDOW UNAUTHORIZED NONCE_REPLAY INTERNAL_ERROR

message string required

Human-readable message, in Spanish.

409 The nonce was already used. Build a new JWE with a new nonce. application/json

code string required

Generic error code.

SCHEMA_VALIDATION_ERROR IAT_OUT_OF_WINDOW UNAUTHORIZED NONCE_REPLAY INTERNAL_ERROR

message string required

Human-readable message, in Spanish.

415 Content-Type is not application/jose. application/json

code string required

Generic error code.

SCHEMA_VALIDATION_ERROR IAT_OUT_OF_WINDOW UNAUTHORIZED NONCE_REPLAY INTERNAL_ERROR

message string required

Human-readable message, in Spanish.

500 Unexpected server error. application/json

code string required

Generic error code.

SCHEMA_VALIDATION_ERROR IAT_OUT_OF_WINDOW UNAUTHORIZED NONCE_REPLAY INTERNAL_ERROR

message string required

Human-readable message, in Spanish.

503 Temporary failure. Retry with backoff and a new JWE (new nonce and iat). application/json

code string required

Generic error code.

SCHEMA_VALIDATION_ERROR IAT_OUT_OF_WINDOW UNAUTHORIZED NONCE_REPLAY INTERNAL_ERROR

message string required

Human-readable message, in Spanish.

This request is in the Monato · Fincore Postman collection, folder Instruments.Download collection

Request

curl -X POST "https://apicore.stg.finch.lat/v1/clients/{clientId}/card-tokens" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/jose" \
  --data 'eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoic3RnLXYxIn0.<encrypted_key>.<iv>.<ciphertext>.<tag>'

const body = "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoic3RnLXYxIn0.<encrypted_key>.<iv>.<ciphertext>.<tag>";

const res = await fetch("https://apicore.stg.finch.lat/v1/clients/{clientId}/card-tokens", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/jose",
  },
  body,
});
const data = await res.json();

import requests

payload = "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoic3RnLXYxIn0.<encrypted_key>.<iv>.<ciphertext>.<tag>"

res = requests.post(
    "https://apicore.stg.finch.lat/v1/clients/{clientId}/card-tokens",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/jose",
    },
    data=payload,
)
data = res.json()

Response

{
  "token_id": "9f1b2c3d-4e5f-4a6b-8c7d-1234567890ab",
  "first_6": "411111",
  "last_4": "1111"
}

{
  "code": "SCHEMA_VALIDATION_ERROR",
  "message": "La petición no cumple el formato esperado."
}

{
  "code": "IAT_OUT_OF_WINDOW",
  "message": "La petición está fuera de la ventana de tiempo permitida."
}

{
  "code": "UNAUTHORIZED",
  "message": "No autenticado."
}

{
  "code": "NONCE_REPLAY",
  "message": "Esta petición ya fue procesada."
}

{
  "code": "SCHEMA_VALIDATION_ERROR",
  "message": "La petición no cumple el formato esperado."
}

{
  "code": "INTERNAL_ERROR",
  "message": "Error interno."
}

{
  "code": "INTERNAL_ERROR",
  "message": "Servicio no disponible temporalmente."
}