# Financial Instruments and External Cash Transactions API



<EndpointIndex
  names={[
  	'fetchFinancialInstrument',
  	'listFinancialInstruments',
  	'createFinancialInstrument',
  	'setFinancialInstrumentAsDefault',
  	'updateFinancialInstrument',
  	'fetchExternalCashTransaction',
  ]}
  titles={{
  	fetchFinancialInstrument: 'Fetch a Financial Instrument',
  	listFinancialInstruments: 'Fetch Financial Instruments for a Tenant',
  	createFinancialInstrument: 'Create a Financial Instrument',
  	setFinancialInstrumentAsDefault:
  		'Set the Default Financial Instrument for a Tenant',
  	updateFinancialInstrument: 'Update a Financial Instrument',
  	fetchExternalCashTransaction: 'Fetch an External Cash Transaction',
  }}
/>

Financial Instruments [#financial-instruments]

Fetch a Financial Instrument [#fetch-a-financial-instrument]

<ApiEndpoint name="fetchFinancialInstrument" title="Fetch a Financial Instrument" />

<ApiSchema name="FinancialInstrumentResponse" />

Fetch Financial Instruments for a Tenant [#fetch-financial-instruments-for-a-tenant]

<ApiEndpoint name="listFinancialInstruments" title="Fetch Financial Instruments for a Tenant" />

<ApiSchema name="FinancialInstrumentListResponse" />

Create a Financial Instrument [#create-a-financial-instrument]

<ApiEndpoint name="createFinancialInstrument" title="Create a Financial Instrument" />

<ApiSchema name="FinancialInstrumentCreateRequest" />

Set the Default Financial Instrument for a Tenant [#set-the-default-financial-instrument-for-a-tenant]

<ApiEndpoint name="setFinancialInstrumentAsDefault" title="Set the Default Financial Instrument for a Tenant" />

Update a Financial Instrument [#update-a-financial-instrument]

<ApiEndpoint name="updateFinancialInstrument" title="Update a Financial Instrument" />

External Cash Transactions [#external-cash-transactions]

Fetch an External Cash Transaction [#fetch-an-external-cash-transaction]

<ApiEndpoint name="fetchExternalCashTransaction" title="Fetch an External Cash Transaction" />

<ApiSchema name="ExternalCashTransactionResponse" />


## API Reference

GET /billing/{tenantLocator}/financialInstruments/{locator} — fetchFinancialInstrument
Tags: financial-instruments-controller
Permissions: read
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 FinancialInstrumentResponse — OK

GET /billing/{tenantLocator}/financialInstruments/list — listFinancialInstruments
Tags: financial-instruments-controller
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  offset (integer, query)
  count (integer, query)
  extended (boolean, query)
  account (ulid, query)
Responses:
  200 FinancialInstrumentListResponse — OK

POST /billing/{tenantLocator}/financialInstruments — createFinancialInstrument
Tags: financial-instruments-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
Request body (FinancialInstrumentCreateRequest):
Responses:
  200 FinancialInstrumentResponse — OK

POST /billing/{tenantLocator}/financialInstruments/{locator}/setAsDefault — setFinancialInstrumentAsDefault
Tags: financial-instruments-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
  value (boolean, query)
Responses:
  200 FinancialInstrumentResponse — OK

PATCH /billing/{tenantLocator}/financialInstruments/{locator} — updateFinancialInstrument
Tags: financial-instruments-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Request body (FinancialInstrumentCreateRequest):
Responses:
  200 FinancialInstrumentResponse — OK

GET /billing/{tenantLocator}/externalCashTransactions/{locator} — fetchExternalCashTransaction
Tags: external-cash-transaction-controller
Permissions: read
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 ExternalCashTransactionResponse — OK

FinancialInstrumentResponse
Properties:
  locator (ulid, required)
  externalIdentifier (string)
  institutionName (string)
  instrumentType (Enum checking | savings | creditCard | debitCard)
  defaultTransactionMethod (Enum ach | cash | eft | standard | wire)
  externalAccountNumber (string)
  accountLocator (ulid)
  nickname (string)
  expirationTime (datetime)
  isDefault (boolean, required)
  retryPlanName (string)

FinancialInstrumentListResponse
Properties:
  listCompleted (boolean, required)
  items (FinancialInstrumentResponse[], required)

FinancialInstrumentCreateRequest
Properties:
  externalIdentifier (string)
  institutionName (string)
  instrumentType (Enum checking | savings | creditCard | debitCard)
  defaultTransactionMethod (Enum ach | cash | eft | standard | wire)
  externalAccountNumber (string)
  accountLocator (ulid)
  nickname (string)
  expirationTime (datetime)
  retryPlanName (string)

ExternalCashTransactionResponse
Properties:
  locator (ulid, required)
  financialInstrumentLocator (ulid)
  transactionMethod (Enum ach | cash | eft | standard | wire, required)
  transactionNumber (string)