Instruments

Register an instrument for a client

Changed on Sep 26, 2026

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.

post/v1/clients/{clientId}/instruments

Request

Base URL
https://apicore.stg.finch.lat
Auth
HTTP bearer
TypeScript
https://skmtc.dev/monato/apis/fincore-api/docs/v1/clients/:clientId/instruments/post.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

clientIdstring 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

Example request

{
  "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": "Supplier ABC",
  "debit_card": {
    "destination_bank_id": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f",
    "card_number": "5579072268574100",
    "holder_name": "John Smith"
  }
}

Response

Instrument created

idstring uuid required

Instrument UUID.

bankIdstring uuid required

Destination bank UUID associated with the instrument.

clientIdstring uuid required

Client UUID associated with the instrument.

ownerIdstring 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.

aliasstring required

Human-friendly label for the instrument.

type'RECEIVER' | 'SENDER_RECEIVER' required

rfcstring required

RFC associated with the instrument holder.

customerIdstring uuid

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

Example 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": "Instrumento base",
  "type": "RECEIVER",
  "audit": {
    "createdAt": "2025-05-19 19:03:51.084659-06:00",
    "updatedAt": "2025-05-19 19:03:51.084668-06:00"
  },
  "rfc": "XAXX010101000",
  "customerId": "bb1e8fde-e68e-48e9-a483-d32153c752c2",
  "instrumentDetail": {
    "cardNumber": "5579072268574100",
    "holderName": "John Smith"
  }
}

Changes

Sep 26, 2026e22ef66945df Revision changes
- breaking
  for the path request parameter clientId, the format changed from no format to uuid
- breaking
  the ////// request property's minLength was increased from 0 to 18
- breaking
  the ////// request property's minLength was increased from 0 to 16
- breaking
  added the pattern ^[0-9]{10,12}$ to the request property //////
- breaking
  added the pattern ^[0-9]{16}$ to the request property //////
- breaking
  added the pattern ^[0-9]{18}$ to the request property //////
- breaking
  the //////// request property format changed from no format to uuid
- breaking
  the //////// request property format changed from no format to uuid
- breaking
  the //////// request property format changed from no format to uuid
- breaking
  the ////// request property format changed from no format to uuid
- breaking
  the //////// request property format changed from no format to uuid
- breaking
  the //////// request property format changed from no format to uuid
- breaking
  the //////// request property format changed from no format to uuid
- breaking
  the ////// request property format changed from no format to uuid
- warning
  the //////// request property's maxLength was set to 13
- warning
  the ////// request property's maxLength was set to 18
- warning
  the ////// request property's maxLength was set to 40
- warning
  the //////// request property's maxLength was set to 13
- warning
  the ////// request property's maxLength was set to 16
- warning
  the ////// request property's maxLength was set to 40
- warning
  added the new SENDER_RECEIVER enum value to the //// response property for the response status
- info
  api tag Instruments added
- info
  removed request discriminator
- info
  added the new SENDER_RECEIVER enum value to the request property ////////
- info
  added the new SENDER_RECEIVER enum value to the request property ////////
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status

Operation history