Register an instrument for a client

POST /v1/clients/{clientId}/instruments

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

Registers an instrument owned by the specified client or by one of its customers. The request body must include exactly one payment method: debit_card or virtual_clabe. Use type = RECEIVER for recipients. Use type = SENDER_RECEIVER only for instruments that can both send and receive.

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) under which the instrument is being registered. The actual owner will be: - The client itself, if customer_id is omitted in the request body. - The customer specified in customer_id, if provided.

Request body application/json · required

One of RegisterDebitCardRequest

source_bank_id source_bank_id string (uuid) required

Issuer/processing bank ID at Finco/Finch.

client_id client_id string (uuid) required

Client UUID under which the instrument is being registered. The actual owner will be the client itself (if customer_id is omitted) or the customer specified in customer_id (if provided).

customer_id customer_id string (uuid)

Optional customer UUID that will own the instrument. When provided, the instrument belongs to this customer.

type type string required

Instrument usage type.

RECEIVER SENDER_RECEIVER

rfc rfc string required

RFC tax identifier of the account or card holder. If you don't have it, you can send "ND".

alias alias string required

Human-friendly label for the instrument.

debit_card debit_card object required

Debit-card destination details for an instrument.

destination_bank_id debit_card.destination_bank_id string (uuid) required

Destination bank UUID for the debit-card issuer.

card_number debit_card.card_number string required

Debit card number. Must contain exactly 16 digits.

holder_name debit_card.holder_name string required

Name of the debit-card holder.

One of RegisterClabeRequest

source_bank_id source_bank_id string (uuid) required

Issuer/processing bank ID at Finco/Finch.

client_id client_id string (uuid) required

Client UUID under which the instrument is being registered. The actual owner will be the client itself (if customer_id is omitted) or the customer specified in customer_id (if provided).

customer_id customer_id string (uuid)

Optional customer UUID that will own the instrument. When provided, the instrument belongs to this customer.

type type string required

Instrument usage type.

RECEIVER SENDER_RECEIVER

rfc rfc string required

RFC tax identifier of the account or card holder. If you don't have it, you can send "ND".

alias alias string required

Human-friendly label for the instrument.

virtual_clabe virtual_clabe object required

CLABE destination details for an instrument.

destination_bank_id virtual_clabe.destination_bank_id string (uuid) required

Destination bank UUID for the CLABE.

account_number virtual_clabe.account_number string required

Account number without bank prefix. Usually 11 or 12 digits depending on the institution.

clabe_number virtual_clabe.clabe_number string required

CLABE number. Must contain exactly 18 digits.

holder_name virtual_clabe.holder_name string required

Name of the CLABE account holder.

Responses

200 Instrument created application/json

id string (uuid) required

Instrument UUID.

bankId string (uuid) required

Destination bank UUID associated with the instrument.

clientId string (uuid) required

Client UUID associated with the instrument.

ownerId string (uuid) required

Identifier of the entity that owns this instrument (client or customer). When the instrument belongs to a customer, ownerId and customerId will be the same.

alias string required

Human-friendly label for the instrument.

type string required

Instrument usage type.

RECEIVER SENDER_RECEIVER

audit object required

Instrument lifecycle timestamps.

createdAt audit.createdAt string required

Timestamp when the instrument was created.

updatedAt audit.updatedAt string required

Timestamp when the instrument was last updated.

deletedAt audit.deletedAt string | null required

Timestamp when the instrument was deleted, or null.

blockedAt audit.blockedAt string | null required

Timestamp when the instrument was blocked, or null.

rfc string required

RFC associated with the instrument holder.

customerId string (uuid)

Customer who owns the instrument when applicable. Present when the instrument belongs to a customer; omitted for client-level instruments.

instrumentDetail CardInstrumentDetail | ClabeInstrumentDetail required

Payment method details. Card instruments return card fields; CLABE instruments return account and CLABE fields.

One of CardInstrumentDetail

Debit-card instrument details returned by Fincore.

cardNumber instrumentDetail.cardNumber string required

Debit card number associated with the instrument.

expirationDate instrumentDetail.expirationDate string | null

Card expiration date when available; null otherwise.

holderName instrumentDetail.holderName string required

Debit-card holder name.

One of ClabeInstrumentDetail

CLABE instrument details returned by Fincore.

accountNumber instrumentDetail.accountNumber string required

Account number without bank prefix.

clabeNumber instrumentDetail.clabeNumber string required

Full 18-digit CLABE.

holderName instrumentDetail.holderName string required

CLABE account holder name.

400 Instrument registration request is invalid. Possible causes: missing required fields, malformed UUIDs, invalid instrument type, invalid CLABE, invalid debit-card number, unsupported BIN, invalid holder name, or sending both virtual_clabe and debit_card. It also fails when the instrument conflicts with an existing beneficiary. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

401 Missing, expired, invalid, or environment-mismatched API key or bearer token. See Authentication. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

404 Client, customer, source bank, or destination bank was not found. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

500 Unexpected server error. See Error catalog before retrying non-idempotent operations. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

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}/instruments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "source_bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "customer_id": "bb1e8fde-e68e-48e9-a483-d32153c752c2",
  "type": "RECEIVER",
  "rfc": "XAXX010101000",
  "alias": "Tarjeta ABC123",
  "debit_card": {
    "destination_bank_id": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f",
    "card_number": "5579072268574100",
    "holder_name": "Pedro Navajas Dos"
  }
}'

const body = JSON.stringify({
  "source_bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "customer_id": "bb1e8fde-e68e-48e9-a483-d32153c752c2",
  "type": "RECEIVER",
  "rfc": "XAXX010101000",
  "alias": "Tarjeta ABC123",
  "debit_card": {
    "destination_bank_id": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f",
    "card_number": "5579072268574100",
    "holder_name": "Pedro Navajas Dos"
  }
});

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

import requests

payload = {
  "source_bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "customer_id": "bb1e8fde-e68e-48e9-a483-d32153c752c2",
  "type": "RECEIVER",
  "rfc": "XAXX010101000",
  "alias": "Tarjeta ABC123",
  "debit_card": {
    "destination_bank_id": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f",
    "card_number": "5579072268574100",
    "holder_name": "Pedro Navajas Dos"
  }
}

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

Request body examples

{
  "source_bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "customer_id": "bb1e8fde-e68e-48e9-a483-d32153c752c2",
  "type": "RECEIVER",
  "rfc": "XAXX010101000",
  "alias": "Tarjeta ABC123",
  "debit_card": {
    "destination_bank_id": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f",
    "card_number": "5579072268574100",
    "holder_name": "Pedro Navajas Dos"
  }
}

{
  "source_bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "type": "RECEIVER",
  "rfc": "XAXX010101000",
  "alias": "CLABE XYZ123",
  "virtual_clabe": {
    "destination_bank_id": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f",
    "account_number": "006487113111",
    "clabe_number": "002118006487113111",
    "holder_name": "Pedro Navajas Perez"
  }
}

Response

{
  "id": "dd7f8d89-94dd-43ca-871b-720fde378b52",
  "bankId": "d3435bd9-998d-4e8a-9067-6b71d5fd3ac7",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "alias": "Tarjeta con expiracion",
  "type": "RECEIVER",
  "instrumentDetail": {
    "cardNumber": "5579072268574100",
    "expirationDate": "None",
    "holderName": "Pedro Navajas Dos"
  },
  "audit": {
    "createdAt": "2025-05-19 19:03:51.084659-06:00",
    "updatedAt": "2025-05-19 19:03:51.084659-06:00",
    "deletedAt": "None",
    "blockedAt": "None"
  },
  "rfc": "XAXX010101000",
  "customerId": "bb1e8fde-e68e-48e9-a483-d32153c752c2"
}

{
  "id": "2e7e36f8-d3ba-48a0-872e-f093379d6a4f",
  "bankId": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "alias": "CLABE XYZ123",
  "type": "RECEIVER",
  "instrumentDetail": {
    "accountNumber": "006487113111",
    "clabeNumber": "002118006487113111",
    "holderName": "Pedro Navajas Perez"
  },
  "audit": {
    "createdAt": "2025-08-11 13:52:21.702839-06:00",
    "updatedAt": "2025-08-11 13:52:21.702839-06:00",
    "deletedAt": "None",
    "blockedAt": "None"
  },
  "rfc": "XAXX010101000"
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}

{
  "code": 16,
  "message": "API Error",
  "details": [
    {
      "reason": "UNAUTHORIZED",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Invalid Credentials",
        "http_code": "401"
      }
    }
  ]
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}