openapi: 3.2.0 info: title: Cfx Labs Cash API version: '@VERSION@' contact: name: API Owner url: api.cfxlabs.net email: api@cfxlabs.com license: name: Licence tbd url: http://tbd.html termsOfService: http://cfxlabs.com/terms/ description: 'Operations tagged Cash across 2 of this provider''s published API definitions: cash-deposit-simulator-api.json, deposit-api.json. Each path carries the servers of the definition it was published in.' servers: - url: https://api.dev.cfx.to description: Customer Sandbox - url: https://api.cfx.to description: Production security: - ApiKeyAuth: [] ApiSecretAuth: [] tags: - name: Cash paths: /v1/deposit/cash/simulate/{id}/scan: post: summary: Simulate Cash Deposit Barcode Scan (Auth) tags: - Cash description: Simulates the scanning of a cash deposit barcode (Auth step). Returns a confirmationId for use with commit or void. Only available in non-production environments. For floating quotes (no amount set), amount is required. For non-floating quotes, amount must not be provided. requestBody: required: true content: application/json: schema: type: object properties: sourceAmount: type: number description: The deposit amount to simulate. Required for floating quotes (no amount set). Must not be provided for non-floating quotes. parameters: - schema: type: string in: path name: id required: true - schema: type: string in: header name: Idempotency-Key required: false responses: '200': description: Default Response content: application/json: schema: type: object required: - confirmationId - requestId properties: confirmationId: type: string description: Confirmation ID from the auth response requestId: type: string description: Request ID from the auth request, needed for void operations '400': description: Default Response content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INVALID_REQUEST - INVALID_QUOTE_TYPE - INVALID_QUOTE_STATUS - BARCODE_NOT_ELIGIBLE - AMOUNT_NOT_ALLOWED - AMOUNT_REQUIRED - INVALID_BARCODE_STATUS description: '- `INVALID_REQUEST`: The service cannot understand the request - `INVALID_QUOTE_TYPE`: The deposit request is not a cash deposit - `INVALID_QUOTE_STATUS`: The deposit quote is in a terminal status (expired or rejected) - `BARCODE_NOT_ELIGIBLE`: The barcode is in a terminal state and cannot be simulated - `AMOUNT_NOT_ALLOWED`: Amount was provided but the quote already has a fixed amount - `AMOUNT_REQUIRED`: Amount is required for floating quotes (no amount set on the quote) - `INVALID_BARCODE_STATUS`: The barcode is not in the expected state for this operation' message: type: string errors: type: array items: type: object properties: {} additionalProperties: true '401': description: The access to this resource has been denied content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED message: type: string title: UNAUTHORIZED description: The access to this resource has been denied '403': description: The credentials are valid but the caller is not permitted to transact content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - FORBIDDEN message: type: string title: FORBIDDEN description: The credentials are valid but the caller is not permitted to transact '404': description: The resource was not found content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - NOT_FOUND message: type: string title: NOT_FOUND description: The resource was not found '409': description: A duplicate request with this idempotency key is already in progress content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - IDEMPOTENCY_IN_PROGRESS message: type: string title: IDEMPOTENCY_IN_PROGRESS description: A duplicate request with this idempotency key is already in progress '422': description: Another request with this idempotency key was made using a different body content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - IDEMPOTENCY_KEY_REUSED message: type: string title: IDEMPOTENCY_KEY_REUSED description: Another request with this idempotency key was made using a different body default: description: Catch-all error response for any unexpected internal errors content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INTERNAL message: type: string enum: - An unexpected internal error has occurred title: INTERNAL description: Catch-all error response for any unexpected internal errors operationId: postV1DepositCashSimulateByIdScan x-operation-id-source: derived servers: - url: https://api.dev.cfx.to description: Customer Sandbox /v1/deposit/cash/simulate/{id}/commit: post: summary: Simulate Cash Deposit Barcode Commit (AuthCommit) tags: - Cash description: Commits a previously scanned cash deposit barcode (AuthCommit step). Requires the confirmationId from the scan step. Only available in non-production environments. requestBody: required: true content: application/json: schema: type: object required: - confirmationId properties: confirmationId: type: string description: Confirmation ID from the scan step parameters: - schema: type: string in: path name: id required: true - schema: type: string in: header name: Idempotency-Key required: false responses: '200': description: Default Response content: application/json: schema: type: object required: - success properties: success: type: boolean enum: - true '400': description: Default Response content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INVALID_REQUEST - INVALID_QUOTE_TYPE - INVALID_QUOTE_STATUS - BARCODE_NOT_ELIGIBLE - INVALID_BARCODE_STATUS description: '- `INVALID_REQUEST`: The service cannot understand the request - `INVALID_QUOTE_TYPE`: The deposit request is not a cash deposit - `INVALID_QUOTE_STATUS`: The deposit quote is in a terminal status (expired or rejected) - `BARCODE_NOT_ELIGIBLE`: The barcode is in a terminal state and cannot be simulated - `INVALID_BARCODE_STATUS`: The barcode is not in the expected state for this operation' message: type: string errors: type: array items: type: object properties: {} additionalProperties: true '401': description: The access to this resource has been denied content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED message: type: string title: UNAUTHORIZED description: The access to this resource has been denied '403': description: The credentials are valid but the caller is not permitted to transact content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - FORBIDDEN message: type: string title: FORBIDDEN description: The credentials are valid but the caller is not permitted to transact '404': description: The resource was not found content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - NOT_FOUND message: type: string title: NOT_FOUND description: The resource was not found '409': description: A duplicate request with this idempotency key is already in progress content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - IDEMPOTENCY_IN_PROGRESS message: type: string title: IDEMPOTENCY_IN_PROGRESS description: A duplicate request with this idempotency key is already in progress '422': description: Another request with this idempotency key was made using a different body content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - IDEMPOTENCY_KEY_REUSED message: type: string title: IDEMPOTENCY_KEY_REUSED description: Another request with this idempotency key was made using a different body default: description: Catch-all error response for any unexpected internal errors content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INTERNAL message: type: string enum: - An unexpected internal error has occurred title: INTERNAL description: Catch-all error response for any unexpected internal errors operationId: postV1DepositCashSimulateByIdCommit x-operation-id-source: derived servers: - url: https://api.dev.cfx.to description: Customer Sandbox /v1/deposit/cash/simulate/{id}/void: post: summary: Simulate Cash Deposit Barcode Void (AuthVoid) tags: - Cash description: Voids a previously scanned cash deposit barcode (AuthVoid step). Requires the originalRequestId from the scan step. Only available in non-production environments. requestBody: required: true content: application/json: schema: type: object required: - originalRequestId properties: originalRequestId: type: string description: Request ID from the scan step parameters: - schema: type: string in: path name: id required: true - schema: type: string in: header name: Idempotency-Key required: false responses: '200': description: Default Response content: application/json: schema: type: object required: - success properties: success: type: boolean enum: - true '400': description: Default Response content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INVALID_REQUEST - INVALID_QUOTE_TYPE - INVALID_QUOTE_STATUS - BARCODE_NOT_ELIGIBLE - INVALID_BARCODE_STATUS description: '- `INVALID_REQUEST`: The service cannot understand the request - `INVALID_QUOTE_TYPE`: The deposit request is not a cash deposit - `INVALID_QUOTE_STATUS`: The deposit quote is in a terminal status (expired or rejected) - `BARCODE_NOT_ELIGIBLE`: The barcode is in a terminal state and cannot be simulated - `INVALID_BARCODE_STATUS`: The barcode is not in the expected state for this operation' message: type: string errors: type: array items: type: object properties: {} additionalProperties: true '401': description: The access to this resource has been denied content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED message: type: string title: UNAUTHORIZED description: The access to this resource has been denied '403': description: The credentials are valid but the caller is not permitted to transact content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - FORBIDDEN message: type: string title: FORBIDDEN description: The credentials are valid but the caller is not permitted to transact '404': description: The resource was not found content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - NOT_FOUND message: type: string title: NOT_FOUND description: The resource was not found '409': description: A duplicate request with this idempotency key is already in progress content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - IDEMPOTENCY_IN_PROGRESS message: type: string title: IDEMPOTENCY_IN_PROGRESS description: A duplicate request with this idempotency key is already in progress '422': description: Another request with this idempotency key was made using a different body content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - IDEMPOTENCY_KEY_REUSED message: type: string title: IDEMPOTENCY_KEY_REUSED description: Another request with this idempotency key was made using a different body default: description: Catch-all error response for any unexpected internal errors content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INTERNAL message: type: string enum: - An unexpected internal error has occurred title: INTERNAL description: Catch-all error response for any unexpected internal errors operationId: postV1DepositCashSimulateByIdVoid x-operation-id-source: derived servers: - url: https://api.dev.cfx.to description: Customer Sandbox /v1/deposit/cash/retailer: get: summary: Get Cash Deposit Retailers tags: - Cash description: Retrieve the list of retailers within the CFX Network that will accept cash deposits. responses: '200': description: Default Response content: application/json: schema: type: object required: - results properties: results: type: array items: type: object required: - id - name - logo properties: id: type: string description: 'Identifier for a CFX Network retailer, as issued by the retailer network. **Not unique across this list.** Retailers that share a parent brand share an id — Office Max and Office Depot are both `10977` — so two entries can differ only by `name` and `slug`. Key retailers by `slug` if you need a stable per-entry identity; `id` is what Create expects in `retailerId` and selects the brand, not the specific entry.' example: '10831' name: type: string description: Name of the CFX Network retailer example: Walgreens enabled: type: boolean description: Flag indicating whether the retailer is currently enabled slug: type: string description: URL slug for the CFX Network retailer example: walmart providerName: type: string description: Short name associated with the CFX Network retailer providerDescription: type: string description: Description of the CFX Network retailer logo: type: object required: - png - webp properties: png: type: string description: PNG logo URL for the CFX Network retailer example: https://static.cfx.to/retailer-logos/2481.png webp: type: string description: WebP logo URL for the CFX Network retailer example: https://static.cfx.to/retailer-logos/2481.webp description: CDN URLs for the retailer's logo image '400': description: The service cannot understand the request content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INVALID_REQUEST message: type: string errors: type: array items: type: object properties: {} additionalProperties: true title: INVALID_REQUEST description: The service cannot understand the request '401': description: The access to this resource has been denied content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED message: type: string title: UNAUTHORIZED description: The access to this resource has been denied '403': description: The credentials are valid but the caller is not permitted to transact content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - FORBIDDEN message: type: string title: FORBIDDEN description: The credentials are valid but the caller is not permitted to transact default: description: Catch-all error response for any unexpected internal errors content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INTERNAL message: type: string enum: - An unexpected internal error has occurred title: INTERNAL description: Catch-all error response for any unexpected internal errors operationId: getV1DepositCashRetailer x-operation-id-source: derived servers: - url: https://api.dev.cfx.to description: Customer Sandbox - url: https://api.cfx.to description: Production /v1/deposit/cash/location: get: summary: Search Cash Deposit Locations tags: - Cash description: 'Search for nearest cash deposit locations based on a provided zipcode or latitude and longitude pair. This endpoint will expect either a single zipcode query parameter or both the latitude and longitude parameters to be populated.' parameters: - schema: type: string example: '43212' in: query name: zipcode required: true description: Zipcode for a physical CFX Network location - schema: type: string example: '39.98814300' in: query name: latitude required: true description: Latitude of the retailer location - schema: type: string example: '-83.04643600' in: query name: longitude required: true description: Longitude of the retailer location - schema: type: number example: 1 in: query name: page required: false description: Page Number, (defaults to 1) - schema: type: number example: 50 in: query name: pageSize required: false description: Page Size, (defaults to the max of 50) responses: '200': description: Default Response content: application/json: schema: type: object required: - page - pageSize - results properties: page: type: number pageSize: type: number results: type: array items: type: object required: - zipcode - latitude - longitude - city - state - address - phone - retailerName - retailerId - locationId properties: zipcode: type: string description: Zipcode for a physical CFX Network location example: '43212' latitude: type: string description: Latitude of the retailer location example: '39.98814300' longitude: type: string description: Longitude of the retailer location example: '-83.04643600' city: type: string description: City of the retailer location example: Columbus state: type: string description: State of the retailer example: OH address: type: string description: Address of the retailer example: 1495 W 5th Ave phone: type: string description: Phone number of the retailer example: '+1144867159' retailerName: type: string description: Retailer name example: CVS retailerId: type: string description: Unique ID for the retailer example: '10831' locationId: type: string description: Unique ID for the retailer location example: CVS6147 '400': description: The service cannot understand the request content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INVALID_REQUEST message: type: string errors: type: array items: type: object properties: {} additionalProperties: true title: INVALID_REQUEST description: The service cannot understand the request '401': description: The access to this resource has been denied content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED message: type: string title: UNAUTHORIZED description: The access to this resource has been denied '403': description: The credentials are valid but the caller is not permitted to transact content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - FORBIDDEN message: type: string title: FORBIDDEN description: The credentials are valid but the caller is not permitted to transact default: description: Catch-all error response for any unexpected internal errors content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INTERNAL message: type: string enum: - An unexpected internal error has occurred title: INTERNAL description: Catch-all error response for any unexpected internal errors operationId: getV1DepositCashLocation x-operation-id-source: derived servers: - url: https://api.dev.cfx.to description: Customer Sandbox - url: https://api.cfx.to description: Production /v1/deposit/cash: get: summary: Search Cash Deposit Request tags: - Cash description: 'Search cash deposits requests for a given `identityId`. The `identityId` query parameter is mandatory. Deposits can be further filtered by populating the `status` and `reference` parameters. `reference` is an exact, case-sensitive match on a single value — not a prefix or substring search. References are not unique, so more than one request may share one. **This endpoint is not paginated and returns at most 50 results.** There is no page, cursor or total parameter, results are not ordered, and a search matching more than 50 requests is truncated with no indication in the response. Always filter by `reference` or `status` alongside `identityId` when the identity may have a long history. Results are read from the primary database, so a request is visible here as soon as its Create call returns. There is no eventual-consistency delay to wait out. Search is intended for reconciliation and diagnostics; use the `Idempotency-Key` header on Create to prevent duplicates. Note that cash deposits requests will result in the creation of a Deposit once the user has presented the barcode and successfully made payment at a retailer.' parameters: - schema: type: string example: id_VfsdSMtd8UdgxCgTnz0tm in: query name: identityId required: true description: Filter by Identity ID - schema: type: string in: query name: reference required: false description: Filter by reference - schema: type: string examples: CREATED: value: CREATED CREATED,PENDING: value: CREATED,PENDING in: query name: status required: false description: Filter by status responses: '200': description: Default Response content: application/json: schema: type: object required: - results properties: results: type: array items: type: object required: - id - reference - wallet - updatedAt - createdAt - identityId - expiresAt - barcodeNumber - retailerId - retailerName - status properties: id: type: string description: Unique identifier for a deposit request, can be either the request ID, or the deposit ID example: cshdprq_2e3LyTbcILYHDs5vQqOwl reference: type: string description: "A unique identifier of the deposit request in the caller's system.\n\n This is useful to correlate the id in the caller's system with the id returned by the API." example: DR-123456789 wallet: type: object required: - address - blockchain properties: address: type: string description: Blockchain address or account blockchain: type: string description: The blockchain wallet where funds are to be deposited depositId: type: string description: Unique identifier of the associated Deposit deviceIpAddress: type: string description: IP address of the device creating the deposit request example: 123.123.123.123 deviceLocation: type: object required: - source - lat - long properties: source: type: string description: The source data for the location capture enum: - ip example: ip lat: type: number description: Latitude of the device example: 37.851 long: type: number description: Longitude of the device example: -96.822 description: Location of the device submitting transacting with the CFX network updatedAt: type: string description: Datetime the deposit request was last updated example: '2023-10-23T06:20:04.366+00:00' createdAt: type: string description: Datetime the deposit request was created example: '2023-10-23T06:20:04.366+00:00' identityId: type: string description: Identity ID associated with the deposit request example: id_VfsdSMtd8UdgxCgTnz0tm quote: type: object required: - amountIn - amountOut - fees properties: amountIn: type: object required: - amount - currency properties: amount: type: number description: Amount of the nominated currency currency: enum: - USD - AUD - HKD - JPY - MXN - NZD - SGD - SEK - CHF - CAD - GBP - CZK - DKK - EUR type: string description: Amount of the nominated currency description: Amount associated with this deposit amountOut: type: object required: - amount - currency properties: amount: type: number description: Amount of the nominated currency currency: enum: - USDC - MOVEUSD type: string description: Amount of the nominated currency description: Amount associated with this deposit fees: type: array items: type: object required: - fee - type properties: fee: type: object required: - amount - currency properties: amount: type: number description: Amount of the nominated currency currency: enum: - USDC - MOVEUSD type: string description: Amount of the nominated currency description: Amount associated with this deposit type: enum: - CFX_FIXED_FEE - CFX_VARIABLE_FEE - PROVIDER_FIXED_FEE - PROVIDER_VARIABLE_FEE - CUSTOMER_FIXED_FEE - CUSTOMER_VARIABLE_FEE type: string description: Fees associated with a deposit description: Quote for the deposit expiresAt: type: string description: Datetime the cash deposit barcode will expire, as returned by the retailer network. The lifetime is set by the network and is not a fixed interval — read this value rather than deriving it from createdAt. Authorisation at the retailer is decided by the network's own view of the barcode, so treat expiresAt as indicative of validity rather than the definitive cut-off. example: '2023-10-23T06:20:04.366+00:00' barcodeNumber: type: string description: Barcode number for the cash deposit example: '830324006611181360006329048375' retailerId: type: string description: Unique ID for the retailer example: '10831' retailerName: type: string description: Name of the cash deposit retailer example: Walgreens status: enum: - CREATED - PENDING - EXPIRED - CANCELLED - CONSUMED - VOIDED - DECLINED type: string metadata: type: object additionalProperties: {} '400': description: Default Response content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INVALID_REQUEST - INVALID_STATUS description: '- `INVALID_REQUEST`: The service cannot understand the request - `INVALID_STATUS`: An invalid status value was provided as a query parameter' message: type: string errors: type: array items: type: object properties: {} additionalProperties: true '401': description: The access to this resource has been denied content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED message: type: string title: UNAUTHORIZED description: The access to this resource has been denied '403': description: The credentials are valid but the caller is not permitted to transact content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - FORBIDDEN message: type: string title: FORBIDDEN description: The credentials are valid but the caller is not permitted to transact default: description: Catch-all error response for any unexpected internal errors content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INTERNAL message: type: string enum: - An unexpected internal error has occurred title: INTERNAL description: Catch-all error response for any unexpected internal errors operationId: getV1DepositCash x-operation-id-source: derived post: summary: Create Cash Deposit Request tags: - Cash description: 'Create a cash deposit request to enable a nominated identity to subsequently deposit cash at a specified retailer. This endpoint triggers a workflow which orchestrates the deposit of funds at a nominated retailer. To initiate the workflow this endpoint requires: - `retailerId` of the retailer where the deposit will be made. - `identityId` of the end user making the deposit. - A `wallet` specifying the blockchain address where deposited funds will be transferred. - A `deviceLocation` with the user''s latitude and longitude coordinates. Optionally, an `amount` (source currency) or `amountOut` (target currency) can be specified to lock the deposit to a specific value. If neither is provided, the POS will accept any amount. Only one of `amount` or `amountOut` may be specified. The endpoint will return generated deposit request details with a `barcodeNumber` which can then be rendered and presented by the user at the retailer. This barcode will allow the retailer to correlate the user''s visit with the registered cash deposit. When notification of a successful payment arrives from the retailer, a Deposit entry is created within our systems. ### Concurrent barcodes **Creating a request can retire an existing one.** The retailer network caps how many barcodes one identity may hold at once. When a create would exceed that cap, the network retires the identity''s oldest live barcode and this endpoint returns `200` for the new one — the retired barcode moves to `CANCELLED` and will not scan. The cap is the network''s, not ours: it is not configurable here, no error is returned, and nothing in this response names the barcode that was retired. So do not treat a barcode as live because Create once returned it. Re-read `status` with Get before presenting one, and prefer reusing an outstanding barcode over creating another for the same identity. ### Idempotency Send an `Idempotency-Key` header. Within **24 hours**, a repeat of the same key with an identical body replays the original response without re-running the request, so no second barcode is generated. The key is scoped to your customer account, the HTTP method and the request path, and the request body is hashed into it. - `409 IDEMPOTENCY_IN_PROGRESS` — the first request is still executing. Back off and retry the same request unchanged. - `422 IDEMPOTENCY_KEY_REUSED` — the key was sent with a different body. Do not retry; correct the key derivation. If the response is lost, retry the same POST with the same key and the same body rather than querying first. Reusing a `reference` with a new `Idempotency-Key` does **not** deduplicate — only the key does.' requestBody: required: true content: application/json: schema: type: object required: - identityId - user - reference - wallet - deviceLocation - retailerId properties: identityId: type: string description: Identity ID associated with the deposit request example: id_VfsdSMtd8UdgxCgTnz0tm user: type: object required: - firstName - lastName properties: firstName: type: string description: Identity first name example: Robert lastName: type: string description: Identity last name example: Smith address: type: string zipcode: type: string amount: type: object required: - amount - currency properties: amount: type: number description: Amount of the nominated currency currency: type: string description: Amount of the nominated currency enum: - USD description: Amount of the deposit. If this is specified the POS will reject any amount that does not match this value, if not specified the POS will accept any amount, and the amount will be resolved at the time of deposit amountOut: type: object required: - amount - currency properties: amount: type: number description: Amount of the nominated currency currency: enum: - USDC - MOVEUSD type: string description: Amount of the nominated currency description: The amount out of the deposit. If this is specified then the quote returned will factor in all fees and the amount out will be the amount the user receives. The same considerations for the amount field apply here targetCurrency: enum: - MOVEUSD type: string default: MOVEUSD description: The desired currency to receive in the provided wallet reference: type: string description: "A unique identifier of the deposit request in the caller's system.\n\n This is useful to correlate the id in the caller's system with the id returned by the API." example: DR-123456789 wallet: type: object required: - address - blockchain properties: address: type: string description: Blockchain address or account blockchain: type: string description: The blockchain wallet where funds are to be deposited deviceIpAddress: type: string description: IP address of the device creating the deposit request example: 123.123.123.123 deviceLocation: type: object required: - source - lat - long properties: source: type: string description: The source data for the location capture enum: - ip example: ip lat: type: number description: Latitude of the device example: 37.851 long: type: number description: Longitude of the device example: -96.822 retailerId: type: string description: Unique ID for the retailer example: '10831' metadata: type: object additionalProperties: {} parameters: - schema: type: string in: header name: Idempotency-Key required: false responses: '200': description: Default Response content: application/json: schema: type: object required: - id - reference - wallet - updatedAt - createdAt - identityId - expiresAt - barcodeNumber - retailerId - retailerName - status properties: id: type: string description: Unique identifier for a deposit request, can be either the request ID, or the deposit ID example: cshdprq_2e3LyTbcILYHDs5vQqOwl reference: type: string description: "A unique identifier of the deposit request in the caller's system.\n\n This is useful to correlate the id in the caller's system with the id returned by the API." example: DR-123456789 wallet: type: object required: - address - blockchain properties: address: type: string description: Blockchain address or account blockchain: type: string description: The blockchain wallet where funds are to be deposited depositId: type: string description: Unique identifier of the associated Deposit deviceIpAddress: type: string description: IP address of the device creating the deposit request example: 123.123.123.123 deviceLocation: type: object required: - source - lat - long properties: source: type: string description: The source data for the location capture enum: - ip example: ip lat: type: number description: Latitude of the device example: 37.851 long: type: number description: Longitude of the device example: -96.822 description: Location of the device submitting transacting with the CFX network updatedAt: type: string description: Datetime the deposit request was last updated example: '2023-10-23T06:20:04.366+00:00' createdAt: type: string description: Datetime the deposit request was created example: '2023-10-23T06:20:04.366+00:00' identityId: type: string description: Identity ID associated with the deposit request example: id_VfsdSMtd8UdgxCgTnz0tm quote: type: object required: - amountIn - amountOut - fees properties: amountIn: type: object required: - amount - currency properties: amount: type: number description: Amount of the nominated currency currency: enum: - USD - AUD - HKD - JPY - MXN - NZD - SGD - SEK - CHF - CAD - GBP - CZK - DKK - EUR type: string description: Amount of the nominated currency description: Amount associated with this deposit amountOut: type: object required: - amount - currency properties: amount: type: number description: Amount of the nominated currency currency: enum: - USDC - MOVEUSD type: string description: Amount of the nominated currency description: Amount associated with this deposit fees: type: array items: type: object required: - fee - type properties: fee: type: object required: - amount - currency properties: amount: type: number description: Amount of the nominated currency currency: enum: - USDC - MOVEUSD type: string description: Amount of the nominated currency description: Amount associated with this deposit type: enum: - CFX_FIXED_FEE - CFX_VARIABLE_FEE - PROVIDER_FIXED_FEE - PROVIDER_VARIABLE_FEE - CUSTOMER_FIXED_FEE - CUSTOMER_VARIABLE_FEE type: string description: Fees associated with a deposit description: Quote for the deposit expiresAt: type: string description: Datetime the cash deposit barcode will expire, as returned by the retailer network. The lifetime is set by the network and is not a fixed interval — read this value rather than deriving it from createdAt. Authorisation at the retailer is decided by the network's own view of the barcode, so treat expiresAt as indicative of validity rather than the definitive cut-off. example: '2023-10-23T06:20:04.366+00:00' barcodeNumber: type: string description: Barcode number for the cash deposit example: '830324006611181360006329048375' retailerId: type: string description: Unique ID for the retailer example: '10831' retailerName: type: string description: Name of the cash deposit retailer example: Walgreens status: enum: - CREATED - PENDING - EXPIRED - CANCELLED - CONSUMED - VOIDED - DECLINED type: string metadata: type: object additionalProperties: {} '400': description: Default Response content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INVALID_REQUEST - INVALID_AMOUNT - INVALID_LOCATION - INVALID_ENTITY_ID - UNSUPPORTED_PHONE_COUNTRY - PRODUCT_INACTIVE - ENTITY_NOT_FOUND - LIMIT_EXCEEDED - NO_COUNTRY description: '- `INVALID_REQUEST`: The service cannot understand the request - `INVALID_AMOUNT`: Only one of amount or amountOut can be provided, not both - `INVALID_LOCATION`: Could not determine zipcode from the provided deviceLocation, or the resolved location is outside the US - `INVALID_ENTITY_ID`: Active Identity not found for the provided entity ID - `UNSUPPORTED_PHONE_COUNTRY`: Only US phone numbers are supported - `PRODUCT_INACTIVE`: The cash deposit product is not active for this entity - `ENTITY_NOT_FOUND`: The entity was not found - `LIMIT_EXCEEDED`: The deposit amount exceeds a configured transaction or periodic limit. `limit` names the one that rejected the request, and is `null` when the ceiling came from the retailer network rather than from your configured limits. `GET /v1/deposit/usage` returns every ceiling and its current consumption. - `NO_COUNTRY`: Could not determine the country for the provided entity' message: type: string errors: type: array items: type: object properties: {} additionalProperties: true limit: anyOf: - type: object required: - window - type - value properties: window: enum: - TRANSACTION - 24H - 7D - 30D - CALENDAR_MONTH type: string description: The period the limit is measured over. `TRANSACTION` is per-request; the rest are rolling windows ending now, except `CALENDAR_MONTH` which resets on the 1st (UTC). type: enum: - MIN_USD - MAX_USD - MAX_COUNT type: string description: What is being capped. `MIN_USD` / `MAX_USD` bound a USD amount, `MAX_COUNT` bounds a number of transactions. value: type: string description: The ceiling itself, as a decimal string. USD for `MIN_USD` / `MAX_USD`, an integer count for `MAX_COUNT`. usage: type: string description: Consumption of the window before this request, as a decimal string in the same unit as `value`. Absent on `TRANSACTION`, which has no window to accumulate. - type: 'null' description: The limit that rejected the request. Matches a row of `GET /v1/deposit/usage`. '401': description: The access to this resource has been denied content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED message: type: string title: UNAUTHORIZED description: The access to this resource has been denied '403': description: The credentials are valid but the caller is not permitted to transact content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - FORBIDDEN message: type: string title: FORBIDDEN description: The credentials are valid but the caller is not permitted to transact '409': description: A duplicate request with this idempotency key is already in progress content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - IDEMPOTENCY_IN_PROGRESS message: type: string title: IDEMPOTENCY_IN_PROGRESS description: A duplicate request with this idempotency key is already in progress '422': description: Another request with this idempotency key was made using a different body content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - IDEMPOTENCY_KEY_REUSED message: type: string title: IDEMPOTENCY_KEY_REUSED description: Another request with this idempotency key was made using a different body default: description: Catch-all error response for any unexpected internal errors content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INTERNAL message: type: string enum: - An unexpected internal error has occurred title: INTERNAL description: Catch-all error response for any unexpected internal errors operationId: postV1DepositCash x-operation-id-source: derived servers: - url: https://api.dev.cfx.to description: Customer Sandbox - url: https://api.cfx.to description: Production /v1/deposit/cash/{id}: get: summary: Get Cash Deposit Request tags: - Cash description: Retrieve a previously submitted cash deposit request. parameters: - schema: type: string examples: cshdprq_2e3LyTbcILYHDs5vQqOwl: value: cshdprq_2e3LyTbcILYHDs5vQqOwl dp_FiZcY1MGfgB4XjIWsKgtT: value: dp_FiZcY1MGfgB4XjIWsKgtT in: path name: id required: true description: Unique identifier for a deposit request, can be either the request ID, or the deposit ID responses: '200': description: Default Response content: application/json: schema: type: object required: - id - reference - wallet - updatedAt - createdAt - identityId - expiresAt - barcodeNumber - retailerId - retailerName - user - status properties: id: type: string description: Unique identifier for a deposit request, can be either the request ID, or the deposit ID example: cshdprq_2e3LyTbcILYHDs5vQqOwl reference: type: string description: "A unique identifier of the deposit request in the caller's system.\n\n This is useful to correlate the id in the caller's system with the id returned by the API." example: DR-123456789 wallet: type: object required: - address - blockchain properties: address: type: string description: Blockchain address or account blockchain: type: string description: The blockchain wallet where funds are to be deposited depositId: type: string description: Unique identifier of the associated Deposit deviceIpAddress: type: string description: IP address of the device creating the deposit request example: 123.123.123.123 deviceLocation: type: object required: - source - lat - long properties: source: type: string description: The source data for the location capture enum: - ip example: ip lat: type: number description: Latitude of the device example: 37.851 long: type: number description: Longitude of the device example: -96.822 description: Location of the device submitting transacting with the CFX network updatedAt: type: string description: Datetime the deposit request was last updated example: '2023-10-23T06:20:04.366+00:00' createdAt: type: string description: Datetime the deposit request was created example: '2023-10-23T06:20:04.366+00:00' identityId: type: string description: Identity ID associated with the deposit request example: id_VfsdSMtd8UdgxCgTnz0tm quote: type: object required: - amountIn - amountOut - fees properties: amountIn: type: object required: - amount - currency properties: amount: type: number description: Amount of the nominated currency currency: enum: - USD - AUD - HKD - JPY - MXN - NZD - SGD - SEK - CHF - CAD - GBP - CZK - DKK - EUR type: string description: Amount of the nominated currency description: Amount associated with this deposit amountOut: type: object required: - amount - currency properties: amount: type: number description: Amount of the nominated currency currency: enum: - USDC - MOVEUSD type: string description: Amount of the nominated currency description: Amount associated with this deposit fees: type: array items: type: object required: - fee - type properties: fee: type: object required: - amount - currency properties: amount: type: number description: Amount of the nominated currency currency: enum: - USDC - MOVEUSD type: string description: Amount of the nominated currency description: Amount associated with this deposit type: enum: - CFX_FIXED_FEE - CFX_VARIABLE_FEE - PROVIDER_FIXED_FEE - PROVIDER_VARIABLE_FEE - CUSTOMER_FIXED_FEE - CUSTOMER_VARIABLE_FEE type: string description: Fees associated with a deposit description: Quote for the deposit expiresAt: type: string description: Datetime the cash deposit barcode will expire, as returned by the retailer network. The lifetime is set by the network and is not a fixed interval — read this value rather than deriving it from createdAt. Authorisation at the retailer is decided by the network's own view of the barcode, so treat expiresAt as indicative of validity rather than the definitive cut-off. example: '2023-10-23T06:20:04.366+00:00' barcodeNumber: type: string description: Barcode number for the cash deposit example: '830324006611181360006329048375' retailerId: type: string description: Unique ID for the retailer example: '10831' retailerName: type: string description: Name of the cash deposit retailer example: Walgreens user: type: object required: - firstName - lastName - zipcode properties: firstName: type: string description: Identity first name example: Robert lastName: type: string description: Identity last name example: Smith zipcode: type: string description: Identity residence zip code example: '90210' address: type: string status: enum: - CREATED - PENDING - EXPIRED - CANCELLED - CONSUMED - VOIDED - DECLINED type: string metadata: type: object additionalProperties: {} '400': description: The service cannot understand the request content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INVALID_REQUEST message: type: string errors: type: array items: type: object properties: {} additionalProperties: true title: INVALID_REQUEST description: The service cannot understand the request '401': description: The access to this resource has been denied content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED message: type: string title: UNAUTHORIZED description: The access to this resource has been denied '403': description: The credentials are valid but the caller is not permitted to transact content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - FORBIDDEN message: type: string title: FORBIDDEN description: The credentials are valid but the caller is not permitted to transact '404': description: The resource was not found content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - NOT_FOUND message: type: string title: NOT_FOUND description: The resource was not found default: description: Catch-all error response for any unexpected internal errors content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INTERNAL message: type: string enum: - An unexpected internal error has occurred title: INTERNAL description: Catch-all error response for any unexpected internal errors operationId: getV1DepositCashById x-operation-id-source: derived servers: - url: https://api.dev.cfx.to description: Customer Sandbox - url: https://api.cfx.to description: Production /v1/deposit/cash/{id}/cancel: post: summary: Cancel Cash Deposit Request tags: - Cash description: '**This endpoint is currently a no-op and cancels nothing.** It returns `200` with the supplied `id` for any request, in any state. It does not validate that the deposit exists, does not check its status, does not cancel the barcode with the retailer network, and does not change any stored state. A `200` response is not confirmation that a cancellation occurred. There is no way for *you* to release a barcode early. A barcode you hold stays live until it is presented at a retailer, the network expires it at `expiresAt`, or the retailer network retires it to make room for a newer one — see Create. Because that last case is outside your control, never assume a barcode is still live: re-read its `status` with Get before relying on it.' parameters: - schema: type: string examples: cshdprq_2e3LyTbcILYHDs5vQqOwl: value: cshdprq_2e3LyTbcILYHDs5vQqOwl dp_FiZcY1MGfgB4XjIWsKgtT: value: dp_FiZcY1MGfgB4XjIWsKgtT in: path name: id required: true description: Unique identifier for a deposit request, can be either the request ID, or the deposit ID - schema: type: string in: header name: Idempotency-Key required: false responses: '200': description: Default Response content: application/json: schema: type: object required: - id properties: id: type: string description: Unique identifier for a deposit request, can be either the request ID, or the deposit ID example: cshdprq_2e3LyTbcILYHDs5vQqOwl '400': description: The service cannot understand the request content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INVALID_REQUEST message: type: string errors: type: array items: type: object properties: {} additionalProperties: true title: INVALID_REQUEST description: The service cannot understand the request '401': description: The access to this resource has been denied content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED message: type: string title: UNAUTHORIZED description: The access to this resource has been denied '403': description: The credentials are valid but the caller is not permitted to transact content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - FORBIDDEN message: type: string title: FORBIDDEN description: The credentials are valid but the caller is not permitted to transact '409': description: A duplicate request with this idempotency key is already in progress content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - IDEMPOTENCY_IN_PROGRESS message: type: string title: IDEMPOTENCY_IN_PROGRESS description: A duplicate request with this idempotency key is already in progress '422': description: Another request with this idempotency key was made using a different body content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - IDEMPOTENCY_KEY_REUSED message: type: string title: IDEMPOTENCY_KEY_REUSED description: Another request with this idempotency key was made using a different body default: description: Catch-all error response for any unexpected internal errors content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INTERNAL message: type: string enum: - An unexpected internal error has occurred title: INTERNAL description: Catch-all error response for any unexpected internal errors operationId: postV1DepositCashByIdCancel x-operation-id-source: derived servers: - url: https://api.dev.cfx.to description: Customer Sandbox - url: https://api.cfx.to description: Production components: securitySchemes: ApiKeyAuth: name: x-api-key type: apiKey in: header ApiSecretAuth: name: x-api-secret type: apiKey in: header externalDocs: description: Find out more about CFX url: https://www.cfxlabs.com/ x-refined-from: - cash-deposit-simulator-api.json - deposit-api.json