curl --request POST \
--url https://api-sandbox.finogates.com/v1/platform/payment-methods/cards/connect \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"return_url": "<string>",
"entity_type": "personal",
"ip_address": "<string>",
"date_of_birth": "<string>",
"phone": "<string>",
"address1": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>"
}
'import requests
url = "https://api-sandbox.finogates.com/v1/platform/payment-methods/cards/connect"
payload = {
"user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"return_url": "<string>",
"entity_type": "personal",
"ip_address": "<string>",
"date_of_birth": "<string>",
"phone": "<string>",
"address1": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
user_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
return_url: '<string>',
entity_type: 'personal',
ip_address: '<string>',
date_of_birth: '<string>',
phone: '<string>',
address1: '<string>',
city: '<string>',
state: '<string>',
postal_code: '<string>'
})
};
fetch('https://api-sandbox.finogates.com/v1/platform/payment-methods/cards/connect', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.finogates.com/v1/platform/payment-methods/cards/connect",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'user_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'return_url' => '<string>',
'entity_type' => 'personal',
'ip_address' => '<string>',
'date_of_birth' => '<string>',
'phone' => '<string>',
'address1' => '<string>',
'city' => '<string>',
'state' => '<string>',
'postal_code' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.finogates.com/v1/platform/payment-methods/cards/connect"
payload := strings.NewReader("{\n \"user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"return_url\": \"<string>\",\n \"entity_type\": \"personal\",\n \"ip_address\": \"<string>\",\n \"date_of_birth\": \"<string>\",\n \"phone\": \"<string>\",\n \"address1\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.finogates.com/v1/platform/payment-methods/cards/connect")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"return_url\": \"<string>\",\n \"entity_type\": \"personal\",\n \"ip_address\": \"<string>\",\n \"date_of_birth\": \"<string>\",\n \"phone\": \"<string>\",\n \"address1\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.finogates.com/v1/platform/payment-methods/cards/connect")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"return_url\": \"<string>\",\n \"entity_type\": \"personal\",\n \"ip_address\": \"<string>\",\n \"date_of_birth\": \"<string>\",\n \"phone\": \"<string>\",\n \"address1\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"status_code": 123,
"data": "<unknown>",
"query_generated_time": 123
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Mint a Card-Connect URL
Returns a one-time URL the platform redirects its end-user to. The user fills the hosted card form and is bounced back to Finogate’s landing page, which posts the resulting code+state to /connect/callback. The tenant must hold active AFT or OCT capability before this endpoint will mint a URL.
curl --request POST \
--url https://api-sandbox.finogates.com/v1/platform/payment-methods/cards/connect \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"return_url": "<string>",
"entity_type": "personal",
"ip_address": "<string>",
"date_of_birth": "<string>",
"phone": "<string>",
"address1": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>"
}
'import requests
url = "https://api-sandbox.finogates.com/v1/platform/payment-methods/cards/connect"
payload = {
"user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"return_url": "<string>",
"entity_type": "personal",
"ip_address": "<string>",
"date_of_birth": "<string>",
"phone": "<string>",
"address1": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
user_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
return_url: '<string>',
entity_type: 'personal',
ip_address: '<string>',
date_of_birth: '<string>',
phone: '<string>',
address1: '<string>',
city: '<string>',
state: '<string>',
postal_code: '<string>'
})
};
fetch('https://api-sandbox.finogates.com/v1/platform/payment-methods/cards/connect', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.finogates.com/v1/platform/payment-methods/cards/connect",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'user_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'return_url' => '<string>',
'entity_type' => 'personal',
'ip_address' => '<string>',
'date_of_birth' => '<string>',
'phone' => '<string>',
'address1' => '<string>',
'city' => '<string>',
'state' => '<string>',
'postal_code' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.finogates.com/v1/platform/payment-methods/cards/connect"
payload := strings.NewReader("{\n \"user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"return_url\": \"<string>\",\n \"entity_type\": \"personal\",\n \"ip_address\": \"<string>\",\n \"date_of_birth\": \"<string>\",\n \"phone\": \"<string>\",\n \"address1\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.finogates.com/v1/platform/payment-methods/cards/connect")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"return_url\": \"<string>\",\n \"entity_type\": \"personal\",\n \"ip_address\": \"<string>\",\n \"date_of_birth\": \"<string>\",\n \"phone\": \"<string>\",\n \"address1\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.finogates.com/v1/platform/payment-methods/cards/connect")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"return_url\": \"<string>\",\n \"entity_type\": \"personal\",\n \"ip_address\": \"<string>\",\n \"date_of_birth\": \"<string>\",\n \"phone\": \"<string>\",\n \"address1\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"status_code": 123,
"data": "<unknown>",
"query_generated_time": 123
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Body
Mint a one-time hosted card-add URL for one of the platform's users.
Where the end-user lands after we finish handling the callback. Must be present in the tenant's redirect-URL allow-list.
1 - 2083Onboarding track for this user: personal (individual, KYC) or business (merchant/company, KYB ~24-48h review). Defaults to personal.
personal, business 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.
3 - 45End-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.
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.
32End-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.
255End-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.
128End-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.
64End-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.
16Response
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.

