# Instruments

An instrument is a payment method reference. Money Out uses a source instrument
and a destination instrument.

This guide explains when to create and use instruments and includes the API
contracts needed to discover banks and manage beneficiaries.

## Instrument flow

| Step | Action | OpenAPI contract | Save |
|  --- | --- | --- | --- |
| 1 | Retrieve destination banks | [Retrieve SPEI participants](#retrieve-spei-participants) | Destination bank IDs. |
| 2 | Register a CLABE or debit-card beneficiary | [Register instrument](#register-instrument) | Destination instrument `id`. |
| 3 | List stored instruments | [List instruments](#list-instruments) | Existing beneficiary data. |
| 4 | Retrieve one instrument | [Retrieve instrument](#retrieve-instrument) | Instrument detail. |


## Source instrument

The usual source instrument comes from the Centralizing Account. See
[Accounts](/products/fincore/guides/accounts) and [Retrieve client accounts](/products/fincore/guides/accounts#retrieve-client-accounts)
operation.

## Destination instruments

Create a destination instrument before sending Money Out.

| Destination | OpenAPI contract | Use |
|  --- | --- | --- |
| CLABE | [Register instrument](#register-instrument) | Standard SPEI transfer to a bank account. |
| Debit card | [Register instrument](#register-instrument) | Debit-card Money Out when enabled for your integration. |
| Business Unit-owned instrument | [Register instrument](#register-instrument) | Use when the beneficiary is owned by a Business Unit. |


The OpenAPI schema contains the required fields and accepted enum values for each
instrument variant.

## Validation

Use [Penny Validation](/products/fincore/guides/penny-validation) when you need CEP ownership data
before sending production funds.

| Action | OpenAPI contract |
|  --- | --- |
| Validate destination ownership | [Create Penny Validation](/products/fincore/guides/penny-validation#create-penny-validation) |


Common validation errors are centralized in [Error catalog](/products/fincore/guides/error-catalog).

## Trusted instrument whitelist

Money Out transactions above **$500,000.00 MXN** are held for a manual operator
review before being sent to SPEI. If you pay the same trusted recipients
repeatedly, you can add their instruments to a whitelist so those transactions
skip that review.

The review threshold and the bypass apply to outbound SPEI payments. Whitelisting
changes only the review step; every other Money Out rule still applies.

### Requirements

All of these are checked when you add an instrument. A rule failure returns `400` with
`FAILED_PRECONDITION` and error code `20-E4120`.

| # | Requirement | Detail |
|  --- | --- | --- |
| 1 | Valid identifiers | `clientId` and `instrumentId` must be well-formed UUIDs. |
| 2 | Belongs to the client | The instrument must be registered and active under your client. |
| 3 | Limit not reached | Maximum of **10 active whitelisted instruments per client**, counted across all your instruments, not per instrument. |
| 4 | Minimum age | The instrument must have been created at least **72 hours** ago. |
| 5 | Transaction history | The instrument must already be the destination of at least **3 liquidated transactions**. |


### This operation is not idempotent

Adding an instrument that is already whitelisted returns `400` with
`Instrument in whitelist already exists.`, not a success response. Check for that
error instead of retrying blindly.

| Action | OpenAPI contract |
|  --- | --- |
| Add an instrument to the whitelist | [Add an instrument to the trusted whitelist](#add-an-instrument-to-the-trusted-whitelist) |


## API contracts

### Retrieve SPEI participants

Endpoint: `GET /v1/banks`

#### Headers

```json
{
  "type": "object",
  "required": [
    "Authorization"
  ],
  "properties": {
    "Authorization": {
      "type": "string",
      "description": "Bearer token returned by the authentication flow.",
      "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}
```

#### Request body

No request body.

#### Request example

#### 200 response body

```json
{
  "$ref": "#/components/schemas/BanksResponse",
  "components": {
    "schemas": {
      "Bank": {
        "type": "object",
        "description": "SPEI participant institution available for transfers.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Bank identifier used by Fincore APIs.",
            "example": "9d84b03a-28d1-4898-a69c-38824239e2b1"
          },
          "name": {
            "type": "string",
            "description": "Institution display name.",
            "example": "FINCO_PAY"
          },
          "token": {
            "type": "string",
            "description": "SPEI institution token used by the adapter.",
            "example": "734"
          },
          "BIM": {
            "type": "string",
            "description": "Bank identifier used by the SPEI participant catalog.",
            "example": "734"
          },
          "code": {
            "type": "string",
            "description": "Full institution code used for SPEI routing.",
            "example": "90734"
          },
          "bank_status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "INACTIVE"
            ],
            "description": "Whether the institution is available for routing.",
            "example": "ACTIVE"
          }
        }
      },
      "BanksResponse": {
        "type": "object",
        "description": "Paginated catalog response for SPEI participant institutions.",
        "required": [
          "total_banks",
          "page",
          "page_size",
          "banks"
        ],
        "properties": {
          "total_banks": {
            "type": "integer",
            "description": "Total number of institutions available in the catalog.",
            "example": 2
          },
          "page": {
            "type": "integer",
            "description": "Current page number.",
            "example": 1
          },
          "page_size": {
            "type": "integer",
            "description": "Number of institutions returned per page.",
            "example": 50
          },
          "banks": {
            "type": "array",
            "description": "SPEI participant institutions.",
            "items": {
              "$ref": "#/components/schemas/Bank"
            }
          }
        }
      }
    }
  }
}
```

#### Response example

```json 200 application/json
{
  "total_banks": 1,
  "page": 1,
  "page_size": 50,
  "banks": [
    {
      "id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
      "name": "FINCO_PAY",
      "token": "734",
      "BIM": "734",
      "code": "90734",
      "bank_status": "ACTIVE"
    }
  ]
}
```

```json 401 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 500 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

| Error | When it happens |
|  --- | --- |
| `401` | The bearer token is missing, expired, invalid, or not valid for the environment. |
| `500` | Unexpected server error. |


### Register instrument

Endpoint: `POST /v1/clients/{clientId}/instruments`

#### Headers

```json
{
  "type": "object",
  "required": [
    "Authorization"
  ],
  "properties": {
    "Authorization": {
      "type": "string",
      "description": "Bearer token returned by the authentication flow.",
      "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}
```

#### Path parameters

```json
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "format": "uuid",
      "description": "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.\n"
    }
  },
  "required": [
    "clientId"
  ]
}
```

#### Request body

```json
{
  "$ref": "#/components/schemas/RegisterInstrumentRequest",
  "components": {
    "schemas": {
      "InstrumentType": {
        "type": "string",
        "enum": [
          "RECEIVER",
          "SENDER_RECEIVER"
        ],
        "example": "RECEIVER"
      },
      "RegisterInstrumentBase": {
        "type": "object",
        "properties": {
          "source_bank_id": {
            "type": "string",
            "format": "uuid",
            "description": "Issuer/processing bank ID at Finco/Finch.",
            "example": "9d84b03a-28d1-4898-a69c-38824239e2b1"
          },
          "client_id": {
            "type": "string",
            "format": "uuid",
            "description": "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).\n",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "customer_id": {
            "type": "string",
            "format": "uuid",
            "description": "Optional customer UUID that will own the instrument. When provided, the instrument belongs to this customer.\n",
            "example": "bb1e8fde-e68e-48e9-a483-d32153c752c2"
          },
          "type": {
            "description": "Instrument usage type.",
            "$ref": "#/components/schemas/InstrumentType"
          },
          "rfc": {
            "type": "string",
            "maxLength": 13,
            "description": "RFC tax identifier of the account or card holder. If you don't have it, you can send \"ND\".\n",
            "example": "XAXX010101000"
          },
          "alias": {
            "type": "string",
            "description": "Human-friendly label for the instrument.",
            "example": "Supplier ABC"
          }
        },
        "required": [
          "source_bank_id",
          "client_id",
          "type",
          "rfc",
          "alias"
        ]
      },
      "DebitCardPayload": {
        "type": "object",
        "description": "Debit-card destination details for an instrument.",
        "properties": {
          "destination_bank_id": {
            "type": "string",
            "format": "uuid",
            "description": "Destination bank UUID for the debit-card issuer.",
            "example": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f"
          },
          "card_number": {
            "type": "string",
            "minLength": 16,
            "maxLength": 16,
            "pattern": "^[0-9]{16}$",
            "description": "Debit card number. Must contain exactly 16 digits.",
            "example": "5579072268574100"
          },
          "holder_name": {
            "type": "string",
            "maxLength": 40,
            "description": "Name of the debit-card holder.",
            "example": "John Smith"
          }
        },
        "required": [
          "destination_bank_id",
          "card_number",
          "holder_name"
        ]
      },
      "RegisterDebitCardRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/RegisterInstrumentBase"
          },
          {
            "type": "object",
            "properties": {
              "debit_card": {
                "$ref": "#/components/schemas/DebitCardPayload"
              }
            },
            "required": [
              "debit_card"
            ]
          }
        ]
      },
      "VirtualClabePayload": {
        "type": "object",
        "description": "CLABE destination details for an instrument.",
        "properties": {
          "destination_bank_id": {
            "type": "string",
            "format": "uuid",
            "description": "Destination bank UUID for the CLABE.",
            "example": "3054ff18-32a0-478d-b9fe-b5261f9a6e1f"
          },
          "account_number": {
            "type": "string",
            "description": "Account number without bank prefix. Usually 11 or 12 digits depending on the institution.",
            "pattern": "^[0-9]{10,12}$",
            "example": "006487113111"
          },
          "clabe_number": {
            "type": "string",
            "minLength": 18,
            "maxLength": 18,
            "pattern": "^[0-9]{18}$",
            "description": "CLABE number. Must contain exactly 18 digits.",
            "example": "002118006487113111"
          },
          "holder_name": {
            "type": "string",
            "maxLength": 40,
            "description": "Name of the CLABE account holder.",
            "example": "John Smith"
          }
        },
        "required": [
          "destination_bank_id",
          "account_number",
          "clabe_number",
          "holder_name"
        ]
      },
      "RegisterClabeRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/RegisterInstrumentBase"
          },
          {
            "type": "object",
            "properties": {
              "virtual_clabe": {
                "$ref": "#/components/schemas/VirtualClabePayload"
              }
            },
            "required": [
              "virtual_clabe"
            ]
          }
        ]
      },
      "RegisterInstrumentRequest": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/RegisterDebitCardRequest"
          },
          {
            "$ref": "#/components/schemas/RegisterClabeRequest"
          }
        ],
        "description": "Register exactly one destination payment method. Send either `debit_card` or `virtual_clabe`, never both.\n"
      }
    }
  }
}
```

#### Request example

```json Payload application/json
{
  "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"
  }
}
```

#### 200 response body

```json
{
  "$ref": "#/components/schemas/InstrumentResponse",
  "components": {
    "schemas": {
      "InstrumentType": {
        "type": "string",
        "enum": [
          "RECEIVER",
          "SENDER_RECEIVER"
        ],
        "example": "RECEIVER"
      },
      "InstrumentBaseResponse": {
        "type": "object",
        "description": "Common fields returned for every registered instrument.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Instrument UUID.",
            "example": "dd7f8d89-94dd-43ca-871b-720fde378b52"
          },
          "bankId": {
            "type": "string",
            "format": "uuid",
            "description": "Destination bank UUID associated with the instrument.",
            "example": "d3435bd9-998d-4e8a-9067-6b71d5fd3ac7"
          },
          "clientId": {
            "type": "string",
            "format": "uuid",
            "description": "Client UUID associated with the instrument.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "ownerId": {
            "type": "string",
            "format": "uuid",
            "description": "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.\n",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "alias": {
            "type": "string",
            "description": "Human-friendly label for the instrument.",
            "example": "Instrumento base"
          },
          "type": {
            "description": "Instrument usage type.",
            "$ref": "#/components/schemas/InstrumentType"
          },
          "audit": {
            "type": "object",
            "description": "Instrument lifecycle timestamps.",
            "properties": {
              "createdAt": {
                "type": "string",
                "description": "Timestamp when the instrument was created.",
                "example": "2025-05-19 19:03:51.084659-06:00"
              },
              "updatedAt": {
                "type": "string",
                "description": "Timestamp when the instrument was last updated.",
                "example": "2025-05-19 19:03:51.084668-06:00"
              },
              "deletedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Timestamp when the instrument was deleted, or null.",
                "example": null
              },
              "blockedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Timestamp when the instrument was blocked, or null.",
                "example": null
              }
            },
            "required": [
              "createdAt",
              "updatedAt",
              "deletedAt",
              "blockedAt"
            ]
          },
          "rfc": {
            "type": "string",
            "description": "RFC associated with the instrument holder.",
            "example": "XAXX010101000"
          },
          "customerId": {
            "type": "string",
            "format": "uuid",
            "description": "Customer who owns the instrument when applicable. Present when the instrument belongs to a customer; omitted for client-level instruments.\n",
            "example": "bb1e8fde-e68e-48e9-a483-d32153c752c2"
          }
        },
        "required": [
          "id",
          "bankId",
          "clientId",
          "ownerId",
          "alias",
          "type",
          "audit",
          "rfc"
        ]
      },
      "CardInstrumentDetail": {
        "type": "object",
        "description": "Debit-card instrument details returned by Fincore.",
        "properties": {
          "cardNumber": {
            "type": "string",
            "description": "Debit card number associated with the instrument.",
            "example": "5579072268574100"
          },
          "expirationDate": {
            "type": [
              "string",
              "null"
            ],
            "description": "Card expiration date when available; null otherwise.",
            "example": null
          },
          "holderName": {
            "type": "string",
            "description": "Debit-card holder name.",
            "example": "John Smith"
          }
        },
        "required": [
          "cardNumber",
          "holderName"
        ]
      },
      "ClabeInstrumentDetail": {
        "type": "object",
        "description": "CLABE instrument details returned by Fincore.",
        "properties": {
          "accountNumber": {
            "type": "string",
            "description": "Account number without bank prefix.",
            "example": "006487113111"
          },
          "clabeNumber": {
            "type": "string",
            "description": "Full 18-digit CLABE.",
            "example": "002118006487113111"
          },
          "holderName": {
            "type": "string",
            "description": "CLABE account holder name.",
            "example": "John Smith"
          }
        },
        "required": [
          "accountNumber",
          "clabeNumber",
          "holderName"
        ]
      },
      "InstrumentResponse": {
        "description": "Registered instrument returned by Fincore.",
        "allOf": [
          {
            "$ref": "#/components/schemas/InstrumentBaseResponse"
          },
          {
            "type": "object",
            "properties": {
              "instrumentDetail": {
                "description": "Payment method details. Card instruments return card fields; CLABE instruments return account and CLABE fields.",
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/CardInstrumentDetail"
                  },
                  {
                    "$ref": "#/components/schemas/ClabeInstrumentDetail"
                  }
                ]
              }
            },
            "required": [
              "instrumentDetail"
            ]
          }
        ]
      }
    }
  }
}
```

#### Response example

```json 200 application/json
{
  "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"
}
```

```json 400 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

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

```json 404 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 500 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

| Error | When it happens |
|  --- | --- |
| `400` | Required instrument fields are missing or malformed, or the instrument conflicts with an existing beneficiary. |
| `401` | The bearer token is missing, expired, invalid, or not valid for the environment. |
| `404` | Client, bank, or owner data was not found. |
| `500` | Unexpected server error. |


### List instruments

Endpoint: `GET /v1/clients/{clientId}/instruments`

#### Headers

```json
{
  "type": "object",
  "required": [
    "Authorization"
  ],
  "properties": {
    "Authorization": {
      "type": "string",
      "description": "Bearer token returned by the authentication flow.",
      "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}
```

#### Path parameters

```json
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "format": "uuid",
      "description": "Client identifier (UUID)."
    }
  },
  "required": [
    "clientId"
  ]
}
```

#### Query parameters

```json
{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "format": "uuid",
      "description": "Optional customer UUID. When provided, filters instruments for this customer only."
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "description": "Page number (1-based)."
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "description": "Number of items per page."
    },
    "instrument_number": {
      "type": "string",
      "description": "Optional CLABE or debit-card number filter."
    },
    "bank_id": {
      "type": "string",
      "format": "uuid",
      "description": "Optional destination bank UUID filter."
    },
    "instrument_name": {
      "type": "string",
      "description": "Optional holder-name filter."
    }
  }
}
```

#### Request body

No request body.

#### Request example

#### 200 response body

```json
{
  "$ref": "#/components/schemas/InstrumentsResponse",
  "components": {
    "schemas": {
      "InstrumentType": {
        "type": "string",
        "enum": [
          "RECEIVER",
          "SENDER_RECEIVER"
        ],
        "example": "RECEIVER"
      },
      "InstrumentBaseResponse": {
        "type": "object",
        "description": "Common fields returned for every registered instrument.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Instrument UUID.",
            "example": "dd7f8d89-94dd-43ca-871b-720fde378b52"
          },
          "bankId": {
            "type": "string",
            "format": "uuid",
            "description": "Destination bank UUID associated with the instrument.",
            "example": "d3435bd9-998d-4e8a-9067-6b71d5fd3ac7"
          },
          "clientId": {
            "type": "string",
            "format": "uuid",
            "description": "Client UUID associated with the instrument.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "ownerId": {
            "type": "string",
            "format": "uuid",
            "description": "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.\n",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "alias": {
            "type": "string",
            "description": "Human-friendly label for the instrument.",
            "example": "Instrumento base"
          },
          "type": {
            "description": "Instrument usage type.",
            "$ref": "#/components/schemas/InstrumentType"
          },
          "audit": {
            "type": "object",
            "description": "Instrument lifecycle timestamps.",
            "properties": {
              "createdAt": {
                "type": "string",
                "description": "Timestamp when the instrument was created.",
                "example": "2025-05-19 19:03:51.084659-06:00"
              },
              "updatedAt": {
                "type": "string",
                "description": "Timestamp when the instrument was last updated.",
                "example": "2025-05-19 19:03:51.084668-06:00"
              },
              "deletedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Timestamp when the instrument was deleted, or null.",
                "example": null
              },
              "blockedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Timestamp when the instrument was blocked, or null.",
                "example": null
              }
            },
            "required": [
              "createdAt",
              "updatedAt",
              "deletedAt",
              "blockedAt"
            ]
          },
          "rfc": {
            "type": "string",
            "description": "RFC associated with the instrument holder.",
            "example": "XAXX010101000"
          },
          "customerId": {
            "type": "string",
            "format": "uuid",
            "description": "Customer who owns the instrument when applicable. Present when the instrument belongs to a customer; omitted for client-level instruments.\n",
            "example": "bb1e8fde-e68e-48e9-a483-d32153c752c2"
          }
        },
        "required": [
          "id",
          "bankId",
          "clientId",
          "ownerId",
          "alias",
          "type",
          "audit",
          "rfc"
        ]
      },
      "CardInstrumentDetail": {
        "type": "object",
        "description": "Debit-card instrument details returned by Fincore.",
        "properties": {
          "cardNumber": {
            "type": "string",
            "description": "Debit card number associated with the instrument.",
            "example": "5579072268574100"
          },
          "expirationDate": {
            "type": [
              "string",
              "null"
            ],
            "description": "Card expiration date when available; null otherwise.",
            "example": null
          },
          "holderName": {
            "type": "string",
            "description": "Debit-card holder name.",
            "example": "John Smith"
          }
        },
        "required": [
          "cardNumber",
          "holderName"
        ]
      },
      "ClabeInstrumentDetail": {
        "type": "object",
        "description": "CLABE instrument details returned by Fincore.",
        "properties": {
          "accountNumber": {
            "type": "string",
            "description": "Account number without bank prefix.",
            "example": "006487113111"
          },
          "clabeNumber": {
            "type": "string",
            "description": "Full 18-digit CLABE.",
            "example": "002118006487113111"
          },
          "holderName": {
            "type": "string",
            "description": "CLABE account holder name.",
            "example": "John Smith"
          }
        },
        "required": [
          "accountNumber",
          "clabeNumber",
          "holderName"
        ]
      },
      "InstrumentResponse": {
        "description": "Registered instrument returned by Fincore.",
        "allOf": [
          {
            "$ref": "#/components/schemas/InstrumentBaseResponse"
          },
          {
            "type": "object",
            "properties": {
              "instrumentDetail": {
                "description": "Payment method details. Card instruments return card fields; CLABE instruments return account and CLABE fields.",
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/CardInstrumentDetail"
                  },
                  {
                    "$ref": "#/components/schemas/ClabeInstrumentDetail"
                  }
                ]
              }
            },
            "required": [
              "instrumentDetail"
            ]
          }
        ]
      },
      "InstrumentsResponse": {
        "type": "object",
        "description": "Paginated list of registered payment instruments.",
        "properties": {
          "data": {
            "type": "array",
            "description": "Registered instruments returned for the client and filters.",
            "items": {
              "$ref": "#/components/schemas/InstrumentResponse"
            }
          },
          "currentPage": {
            "type": "integer",
            "description": "Current page number.",
            "example": 1
          },
          "perPage": {
            "type": "integer",
            "description": "Number of instruments returned per page.",
            "example": 50
          },
          "totalItems": {
            "type": "integer",
            "description": "Total number of instruments matching the request.",
            "example": 17
          }
        },
        "required": [
          "data",
          "currentPage",
          "perPage",
          "totalItems"
        ]
      }
    }
  }
}
```

#### Response example

```json 200 application/json
{
  "data": [
    null
  ],
  "currentPage": 1,
  "perPage": 50,
  "totalItems": 17
}
```

```json 400 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

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

```json 404 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 500 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

| Error | When it happens |
|  --- | --- |
| `400` | Query parameters are malformed. |
| `401` | The bearer token is missing, expired, invalid, or not valid for the environment. |
| `404` | Instruments were not found for the supplied client. |
| `500` | Unexpected server error. |


### Retrieve instrument

Endpoint: `GET /v1/clients/{clientId}/instruments/{instrumentId}`

#### Headers

```json
{
  "type": "object",
  "required": [
    "Authorization"
  ],
  "properties": {
    "Authorization": {
      "type": "string",
      "description": "Bearer token returned by the authentication flow.",
      "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}
```

#### Path parameters

```json
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "format": "uuid",
      "description": "Client identifier (UUID)."
    },
    "instrumentId": {
      "type": "string",
      "format": "uuid",
      "description": "Instrument identifier (UUID)."
    }
  },
  "required": [
    "clientId",
    "instrumentId"
  ]
}
```

#### Request body

No request body.

#### Request example

#### 200 response body

```json
{
  "$ref": "#/components/schemas/InstrumentResponse",
  "components": {
    "schemas": {
      "InstrumentType": {
        "type": "string",
        "enum": [
          "RECEIVER",
          "SENDER_RECEIVER"
        ],
        "example": "RECEIVER"
      },
      "InstrumentBaseResponse": {
        "type": "object",
        "description": "Common fields returned for every registered instrument.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Instrument UUID.",
            "example": "dd7f8d89-94dd-43ca-871b-720fde378b52"
          },
          "bankId": {
            "type": "string",
            "format": "uuid",
            "description": "Destination bank UUID associated with the instrument.",
            "example": "d3435bd9-998d-4e8a-9067-6b71d5fd3ac7"
          },
          "clientId": {
            "type": "string",
            "format": "uuid",
            "description": "Client UUID associated with the instrument.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "ownerId": {
            "type": "string",
            "format": "uuid",
            "description": "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.\n",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "alias": {
            "type": "string",
            "description": "Human-friendly label for the instrument.",
            "example": "Instrumento base"
          },
          "type": {
            "description": "Instrument usage type.",
            "$ref": "#/components/schemas/InstrumentType"
          },
          "audit": {
            "type": "object",
            "description": "Instrument lifecycle timestamps.",
            "properties": {
              "createdAt": {
                "type": "string",
                "description": "Timestamp when the instrument was created.",
                "example": "2025-05-19 19:03:51.084659-06:00"
              },
              "updatedAt": {
                "type": "string",
                "description": "Timestamp when the instrument was last updated.",
                "example": "2025-05-19 19:03:51.084668-06:00"
              },
              "deletedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Timestamp when the instrument was deleted, or null.",
                "example": null
              },
              "blockedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Timestamp when the instrument was blocked, or null.",
                "example": null
              }
            },
            "required": [
              "createdAt",
              "updatedAt",
              "deletedAt",
              "blockedAt"
            ]
          },
          "rfc": {
            "type": "string",
            "description": "RFC associated with the instrument holder.",
            "example": "XAXX010101000"
          },
          "customerId": {
            "type": "string",
            "format": "uuid",
            "description": "Customer who owns the instrument when applicable. Present when the instrument belongs to a customer; omitted for client-level instruments.\n",
            "example": "bb1e8fde-e68e-48e9-a483-d32153c752c2"
          }
        },
        "required": [
          "id",
          "bankId",
          "clientId",
          "ownerId",
          "alias",
          "type",
          "audit",
          "rfc"
        ]
      },
      "CardInstrumentDetail": {
        "type": "object",
        "description": "Debit-card instrument details returned by Fincore.",
        "properties": {
          "cardNumber": {
            "type": "string",
            "description": "Debit card number associated with the instrument.",
            "example": "5579072268574100"
          },
          "expirationDate": {
            "type": [
              "string",
              "null"
            ],
            "description": "Card expiration date when available; null otherwise.",
            "example": null
          },
          "holderName": {
            "type": "string",
            "description": "Debit-card holder name.",
            "example": "John Smith"
          }
        },
        "required": [
          "cardNumber",
          "holderName"
        ]
      },
      "ClabeInstrumentDetail": {
        "type": "object",
        "description": "CLABE instrument details returned by Fincore.",
        "properties": {
          "accountNumber": {
            "type": "string",
            "description": "Account number without bank prefix.",
            "example": "006487113111"
          },
          "clabeNumber": {
            "type": "string",
            "description": "Full 18-digit CLABE.",
            "example": "002118006487113111"
          },
          "holderName": {
            "type": "string",
            "description": "CLABE account holder name.",
            "example": "John Smith"
          }
        },
        "required": [
          "accountNumber",
          "clabeNumber",
          "holderName"
        ]
      },
      "InstrumentResponse": {
        "description": "Registered instrument returned by Fincore.",
        "allOf": [
          {
            "$ref": "#/components/schemas/InstrumentBaseResponse"
          },
          {
            "type": "object",
            "properties": {
              "instrumentDetail": {
                "description": "Payment method details. Card instruments return card fields; CLABE instruments return account and CLABE fields.",
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/CardInstrumentDetail"
                  },
                  {
                    "$ref": "#/components/schemas/ClabeInstrumentDetail"
                  }
                ]
              }
            },
            "required": [
              "instrumentDetail"
            ]
          }
        ]
      }
    }
  }
}
```

#### Response example

```json 200 application/json
{
  "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": {},
  "rfc": "XAXX010101000",
  "customerId": "bb1e8fde-e68e-48e9-a483-d32153c752c2",
  "instrumentDetail": {}
}
```

```json 400 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

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

```json 404 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 500 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

| Error | When it happens |
|  --- | --- |
| `400` | Path parameters are malformed. |
| `401` | The bearer token is missing, expired, invalid, or not valid for the environment. |
| `404` | The instrument was not found for the supplied client. |
| `500` | Unexpected server error. |


### Add an instrument to the trusted whitelist

Endpoint: `POST /v1/clients/{clientId}/instruments/{instrumentId}/whitelist`

No request body is required. See
[Trusted instrument whitelist](#trusted-instrument-whitelist) for the
requirements enforced by this operation.

#### Headers

```json
{
  "type": "object",
  "required": [
    "Authorization"
  ],
  "properties": {
    "Authorization": {
      "type": "string",
      "description": "Bearer token returned by the authentication flow.",
      "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}
```

#### Path parameters

```json
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "format": "uuid",
      "description": "Client UUID that owns the instrument."
    },
    "instrumentId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the instrument to add to the whitelist."
    }
  },
  "required": [
    "clientId",
    "instrumentId"
  ]
}
```

#### Request body

No request body.

#### 200 response body

```json
{
  "$ref": "#/components/schemas/InstrumentWhitelistResponse",
  "components": {
    "schemas": {
      "InstrumentWhitelistResponse": {
        "type": "object",
        "description": "Whitelist entry created for a trusted instrument.",
        "required": [
          "id",
          "instrumentId",
          "clientId",
          "instrumentWhitelistStatus"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the whitelist entry.",
            "example": "8f14e45f-ceea-467a-9f0a-1b2c3d4e5f60"
          },
          "instrumentId": {
            "type": "string",
            "format": "uuid",
            "description": "Instrument that was added to the whitelist.",
            "example": "d3fdb481-2058-46c8-807d-4eaf866ae1ec"
          },
          "clientId": {
            "type": "string",
            "format": "uuid",
            "description": "Client that owns the whitelist entry.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "instrumentWhitelistStatus": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "INACTIVE",
              "BLOCKED",
              "EXPIRED",
              "DELETED",
              "CANCELLED"
            ],
            "description": "Lifecycle status of the whitelist entry. New entries are created as `ACTIVE`.",
            "example": "ACTIVE"
          },
          "audit": {
            "type": "object",
            "description": "Creation and update timestamps of the whitelist entry.",
            "properties": {
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "example": "2026-09-21T13:03:36.194761-06:00"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2026-09-21T13:03:36.194761-06:00"
              }
            }
          }
        }
      }
    }
  }
}
```

#### Response example

```json
{
  "id": "8f14e45f-ceea-467a-9f0a-1b2c3d4e5f60",
  "instrumentId": "d3fdb481-2058-46c8-807d-4eaf866ae1ec",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "instrumentWhitelistStatus": "ACTIVE",
  "audit": {
    "createdAt": "2026-09-21T13:03:36.194761-06:00",
    "updatedAt": "2026-09-21T13:03:36.194761-06:00"
  }
}
```

| Error | When it happens |
|  --- | --- |
| `400` | `clientId` or `instrumentId` is not a valid UUID, or a whitelist rule was not met: already whitelisted, 10-instrument limit reached, instrument less than 72 hours old, or fewer than 3 liquidated transactions. Rule failures use `FAILED_PRECONDITION` with error code `20-E4120`. |
| `401` | The bearer token is missing, expired, invalid, or not valid for the environment. |
| `404` | No active instrument was found for the supplied client. |
| `500` | Unexpected server error. |