Create the payment a request-payload described
curl --request POST \
--url https://api-sandbox.finogates.com/v1/platform/payments/create-transaction \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"reference": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"idempotency_key": "<string>",
"wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"destination_wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"card_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"vba_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"payee_destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"payee_address_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"card_acquiring_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"destinations": [
{
"wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount": 1,
"role": "beneficiary"
}
],
"user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"metadata": {},
"payment_category": 1,
"notify_recipient": false,
"from_hold": false
}
'import requests
url = "https://api-sandbox.finogates.com/v1/platform/payments/create-transaction"
payload = {
"reference": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"idempotency_key": "<string>",
"wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"destination_wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"card_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"vba_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"payee_destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"payee_address_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"card_acquiring_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"destinations": [
{
"wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount": 1,
"role": "beneficiary"
}
],
"user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"metadata": {},
"payment_category": 1,
"notify_recipient": False,
"from_hold": False
}
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({
reference: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
idempotency_key: '<string>',
wallet_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
destination_wallet_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
bank_account_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
card_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
vba_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
payee_destination_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
payee_address_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
card_acquiring_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
destinations: [
{
wallet_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
amount: 1,
role: 'beneficiary'
}
],
user_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
metadata: {},
payment_category: 1,
notify_recipient: false,
from_hold: false
})
};
fetch('https://api-sandbox.finogates.com/v1/platform/payments/create-transaction', 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/payments/create-transaction",
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([
'reference' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'idempotency_key' => '<string>',
'wallet_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'destination_wallet_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'bank_account_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'card_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'vba_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'payee_destination_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'payee_address_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'card_acquiring_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'destinations' => [
[
'wallet_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'amount' => 1,
'role' => 'beneficiary'
]
],
'user_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'metadata' => [
],
'payment_category' => 1,
'notify_recipient' => false,
'from_hold' => false
]),
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/payments/create-transaction"
payload := strings.NewReader("{\n \"reference\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<string>\",\n \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"destination_wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"bank_account_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"card_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"vba_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"payee_destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"payee_address_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"card_acquiring_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"destinations\": [\n {\n \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 1,\n \"role\": \"beneficiary\"\n }\n ],\n \"user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"metadata\": {},\n \"payment_category\": 1,\n \"notify_recipient\": false,\n \"from_hold\": false\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/payments/create-transaction")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"reference\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<string>\",\n \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"destination_wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"bank_account_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"card_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"vba_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"payee_destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"payee_address_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"card_acquiring_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"destinations\": [\n {\n \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 1,\n \"role\": \"beneficiary\"\n }\n ],\n \"user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"metadata\": {},\n \"payment_category\": 1,\n \"notify_recipient\": false,\n \"from_hold\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.finogates.com/v1/platform/payments/create-transaction")
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 \"reference\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<string>\",\n \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"destination_wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"bank_account_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"card_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"vba_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"payee_destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"payee_address_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"card_acquiring_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"destinations\": [\n {\n \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 1,\n \"role\": \"beneficiary\"\n }\n ],\n \"user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"metadata\": {},\n \"payment_category\": 1,\n \"notify_recipient\": false,\n \"from_hold\": false\n}"
response = http.request(request)
puts response.read_body{
"status_code": 201,
"data": {
"payment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reference": "3f9c1b2a-9d84-4e15-8c26-0b7a5d3e1f90",
"status": "processing",
"source_type": "wallet",
"destination_type": "bank",
"payment_type": "send",
"amount": 250,
"currency": "USD",
"fee": 3,
"user_id": "00000000-0000-0000-0000-000000000001",
"wallet_id": "11111111-1111-1111-1111-111111111111",
"payee_destination_id": "22222222-2222-2222-2222-222222222222",
"created_at": "2026-09-11T10:05:00Z"
},
"query_generated_time": 1712847600000
}Create a Payment from a Request
Send the reference from request-payload and the ids it asked for. The
amount, the currency and the fee come off the reference — this call takes
none of them, and a body carrying amount or currency is refused with
field_not_allowed.
What is checked, in order:
- the reference is yours, unused and not past
expires_at(payment_request_expired,payment_request_consumed); - every field the request-payload marked required is present and nothing
outside its
fieldswas sent (payload_incomplete,field_not_allowed); - the objects you named carry what
requirementslisted (payload_incomplete— the response repeats thefieldsentries that are still short, so you can fix the object and try again with the same reference); - the terms still hold: if the route or our fee changed since the quote, the
answer is
payment_request_staleand you request a new payload.
Then the payment is created and, unless it is held for review, sent through.
A bank payout to a payee may be carried by a route that holds every payment
for review before it is submitted; such a payment answers pending_review.
That route pays payees only, never the user’s own bank: a reference pinned
to it and spent on bank_account_id is payment_request_stale, and a
payload asked with bank_account_id named is never pinned to it.
The response is the payment, kept to what you need: payment_id, the
reference, status, the movement and its payment_type (send or
transfer, derived by us), amount, currency, our fee (billed on the
invoice, never taken out of the amount), the user_id, the source and
destination ids by the movement’s own names, and — for a split —
destinations. Ids that do not apply to the movement are not sent.
GET /v1/platform/payments/{payment_id} still returns the fuller legacy
shape.
destinations[] — only when the request-payload reported
destinations_supported — credits several wallets from one payment; the leg
amounts must add up exactly to the amount on the reference, and it replaces
destination_wallet_id.
A card charged into a card-acquiring account may first need the cardholder to
authenticate: the answer is then a 422 card_verification_required carrying
three_ds_url, and the payment is created for the same reference once they
pass.
Supply a unique idempotency_key — a replay returns the payment as it stands
now. A reference creates at most one payment: using it again with another key
answers payment_request_consumed with the payment_id.
POST
/
v1
/
platform
/
payments
/
create-transaction
Create the payment a request-payload described
curl --request POST \
--url https://api-sandbox.finogates.com/v1/platform/payments/create-transaction \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"reference": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"idempotency_key": "<string>",
"wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"destination_wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"card_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"vba_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"payee_destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"payee_address_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"card_acquiring_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"destinations": [
{
"wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount": 1,
"role": "beneficiary"
}
],
"user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"metadata": {},
"payment_category": 1,
"notify_recipient": false,
"from_hold": false
}
'import requests
url = "https://api-sandbox.finogates.com/v1/platform/payments/create-transaction"
payload = {
"reference": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"idempotency_key": "<string>",
"wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"destination_wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"card_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"vba_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"payee_destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"payee_address_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"card_acquiring_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"destinations": [
{
"wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount": 1,
"role": "beneficiary"
}
],
"user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"metadata": {},
"payment_category": 1,
"notify_recipient": False,
"from_hold": False
}
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({
reference: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
idempotency_key: '<string>',
wallet_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
destination_wallet_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
bank_account_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
card_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
vba_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
payee_destination_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
payee_address_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
card_acquiring_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
destinations: [
{
wallet_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
amount: 1,
role: 'beneficiary'
}
],
user_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
metadata: {},
payment_category: 1,
notify_recipient: false,
from_hold: false
})
};
fetch('https://api-sandbox.finogates.com/v1/platform/payments/create-transaction', 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/payments/create-transaction",
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([
'reference' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'idempotency_key' => '<string>',
'wallet_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'destination_wallet_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'bank_account_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'card_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'vba_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'payee_destination_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'payee_address_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'card_acquiring_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'destinations' => [
[
'wallet_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'amount' => 1,
'role' => 'beneficiary'
]
],
'user_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'metadata' => [
],
'payment_category' => 1,
'notify_recipient' => false,
'from_hold' => false
]),
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/payments/create-transaction"
payload := strings.NewReader("{\n \"reference\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<string>\",\n \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"destination_wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"bank_account_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"card_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"vba_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"payee_destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"payee_address_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"card_acquiring_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"destinations\": [\n {\n \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 1,\n \"role\": \"beneficiary\"\n }\n ],\n \"user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"metadata\": {},\n \"payment_category\": 1,\n \"notify_recipient\": false,\n \"from_hold\": false\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/payments/create-transaction")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"reference\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<string>\",\n \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"destination_wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"bank_account_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"card_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"vba_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"payee_destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"payee_address_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"card_acquiring_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"destinations\": [\n {\n \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 1,\n \"role\": \"beneficiary\"\n }\n ],\n \"user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"metadata\": {},\n \"payment_category\": 1,\n \"notify_recipient\": false,\n \"from_hold\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.finogates.com/v1/platform/payments/create-transaction")
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 \"reference\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<string>\",\n \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"destination_wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"bank_account_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"card_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"vba_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"payee_destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"payee_address_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"card_acquiring_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"destinations\": [\n {\n \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 1,\n \"role\": \"beneficiary\"\n }\n ],\n \"user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"metadata\": {},\n \"payment_category\": 1,\n \"notify_recipient\": false,\n \"from_hold\": false\n}"
response = http.request(request)
puts response.read_body{
"status_code": 201,
"data": {
"payment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reference": "3f9c1b2a-9d84-4e15-8c26-0b7a5d3e1f90",
"status": "processing",
"source_type": "wallet",
"destination_type": "bank",
"payment_type": "send",
"amount": 250,
"currency": "USD",
"fee": 3,
"user_id": "00000000-0000-0000-0000-000000000001",
"wallet_id": "11111111-1111-1111-1111-111111111111",
"payee_destination_id": "22222222-2222-2222-2222-222222222222",
"created_at": "2026-09-11T10:05:00Z"
},
"query_generated_time": 1712847600000
}Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Body
application/json
Request body for POST /v1/platform/payments/create-transaction.
extra="allow" is deliberate: a body carrying amount, currency,
product_id or any other field this call does not take is refused by the
service with a coded field_not_allowed that says the value comes from the
request-payload — extra="forbid" would turn that into a generic 422
before the route ran.
The reference request-payload returned.
A unique value you pick for this payment. If the same request reaches us twice, the payment happens once.
Required string length:
1 - 120The wallet to debit.
The wallet to credit.
The user's linked bank account — the source of a deposit, or the user's own bank on a withdrawal.
The user's saved card.
The user's virtual bank account to move funds from.
The payee's bank destination to pay.
The payee's address in the destination country, when the request-payload marked it required — a payout abroad, or a bank payout whose route asks for it. Sent only together with payee_destination_id.
The card-acquiring account to deposit into; defaults to the oldest approved one.
Credit several wallets from this one payment. Only when the request-payload reported destinations_supported; replaces destination_wallet_id; the legs must add up exactly to the amount on the reference.
Show child attributes
Show child attributes
Safety cross-check against the wallet owner — and, for a card charged into a card-acquiring account, the payer being charged (required there).
Your own key-value notes, stored with the payment.
Optional. The payment category code to tag this payment with, recording what the payment was for. Omit it and the payment is created exactly as before, untagged. If you do send one it must be a code your platform can currently use, otherwise the request is rejected and no money moves. Fetch the codes from GET /v1/platform/catalog/payment-categories. Codes are issued separately in test and live, so read the list in each mode — the same number does not mean the same category across them.
Required range:
x > 0Example:
1
Ask us to notify the recipient (payee destinations).
Spend from the wallet's held funds (wallet sources).
Response
Payment created
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.