Skip to main content
POST
Mint a card-connect URL

Authorizations

Authorization
string
header
required

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

Body

application/json

Mint a one-time hosted card-add URL for one of the platform's users.

user_id
string<uuid>
required
return_url
string<uri>
required

Where the end-user lands after we finish handling the callback. Must be present in the tenant's redirect-URL allow-list.

Required string length: 1 - 2083
entity_type
enum<string>
default:personal

Onboarding track for this user: personal (individual, KYC) or business (merchant/company, KYB ~24-48h review). Defaults to personal.

Available options:
personal,
business
ip_address
string | null

End-user's IP address as observed by your application. Used as a fraud signal by the card processor. If omitted, we fall back to the IP your server is calling Finogate from — which is the integrator's server, not the cardholder, so passing this explicitly is strongly recommended.

Required string length: 3 - 45
date_of_birth
string | null

End-user date of birth in ISO 8601 format YYYY-MM-DD (e.g. 1990-01-31). Required when the user has not completed KYC. Ignored when the user has approved KYC on file — in that case the verified DOB from the KYC record is used regardless of what is supplied here.

phone
string | null

End-user phone number. Required when the user has not completed KYC and Finogate has no phone on file for them. Ignored when the user has approved KYC on file — the verified phone from the KYC record is used regardless of what is supplied here.

Maximum string length: 32
address1
string | null

End-user street address (line 1). Required when the user has not completed KYC and Finogate has no address on file for them. Ignored when the user has approved KYC on file — the verified address from the KYC record is used regardless of what is supplied here.

Maximum string length: 255
city
string | null

End-user city. Required when the user has not completed KYC and Finogate has no city on file for them. Ignored when the user has approved KYC on file — the verified city from the KYC record is used regardless of what is supplied here.

Maximum string length: 128
state
string | null

End-user state (USPS 2-letter code for US addresses). Required when the user has not completed KYC and Finogate has no state on file for them. Ignored when the user has approved KYC on file — the verified state from the KYC record is used regardless of what is supplied here.

Maximum string length: 64
postal_code
string | null

End-user postal (ZIP) code. Required when the user has not completed KYC and Finogate has no postal code on file for them. Ignored when the user has approved KYC on file — the verified postal code from the KYC record is used regardless of what is supplied here.

Maximum string length: 16

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.