Skip to main content
POST
Account-to-Card Transfer (money out)

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

X-Idempotency-Key
string | null

Optional. A unique value you choose so a retry of the same transfer doesn't run twice. Sending the same key returns the original transfer.

Maximum string length: 120

Body

application/json

Platform request to initiate one debit-card transfer.

Direction is fixed by the endpoint path (/card-to-account for AFT, /account-to-card for OCT). The optional idempotency key is supplied via the X-Idempotency-Key HTTP header rather than the body — matching the rest of Finogate's API surface (Stripe / Square convention).

payment_type mirrors the rest of the payments API: transfer moves funds between the user's OWN wallet and OWN card (card-to-wallet on card-to-account, wallet-to-card on account-to-card). send (moving funds to a different party's card) is reserved and not yet supported.

wallet_id
string<uuid>
required

REQUIRED. The wallet to credit (card-to-account) or debit (account-to-card). The cardholder/owner is resolved from this wallet — mirroring the wallet-to-bank flow.

card_id
string<uuid>
required

UUID of the enrolled card to transact on

amount
required

Transfer amount in major units

Required range: x > 0
idempotency_key
string
required

Required. A unique value you pick per transfer (UUID recommended). Reusing the same key with an identical request returns the original transfer; reusing it with a different request is rejected. Passed in the body, matching the other wallet payment endpoints.

Required string length: 1 - 120
payment_type
enum<string>
required

Required. transfer moves funds between the user's own wallet and own card. send (to another party's card) is reserved and not yet supported.

Available options:
transfer,
send
Example:

"transfer"

currency
string
default:USD
Required string length: 3
user_id
string<uuid> | null

Optional safety cross-check. The owner is resolved from wallet_id; if user_id is supplied it must match that owner or the request is rejected.

from_hold
boolean
default:false

Account-to-card (money-out) only. When true, the transfer draws the amount from the wallet's frozen (held) balance instead of its available balance; the held balance must cover the amount or the request is rejected with insufficient_held_funds. Ignored on card-to-account (money-in), which has no wallet source to draw from — sending true there is rejected. Omit (or send false) for a normal transfer from available balance.

Example:

false

Response

Successful Response

Standard response wrapper for single-object responses and errors.

Generic over the payload type. A route that declares CommonResponse[SomeModel] gets the real data schema rendered in OpenAPI/Swagger; a bare CommonResponse leaves data untyped.

status_code
integer
required

HTTP status code for the response.

data
any
required

Payload or error details.

query_generated_time
integer
required

UTC timestamp (milliseconds since epoch) when response was generated.