Skip to main content
POST
Get a Link for the User to Add a Card

Authorizations

Authorization
string
header
required

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

Body

application/json

Request body for POST /v1/platform/card/add-card.

Mints a one-time hosted add-card page for the end user. The optional metadata rides as a native JSON object in the request body.

user_id
string<uuid>
required

The end-user the card is being added for. Must be an end_user belonging to the calling tenant.

card_holder_id
string<uuid>
required

Required. The Finogate user the card belongs to. Use this when user_id is the card-processing merchant owner and many of your end customers add cards under that one merchant — each card is tagged with its holder so you can list a single holder's cards. Must be a user of the calling tenant.

card_processing_id
string<uuid> | null

Optional. Pins the card to a specific approved card-processing merchant account (the id returned by GET /v1/platform/card-processing/users/{user_id}). Omit to use the user's deterministically selected default merchant.

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.