Wallet → Wallet (internal transfer)

curl --request POST \
  --url https://api-sandbox.finogates.com/v1/platform/payments/wallet-to-wallet \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "amount": 123,
  "idempotency_key": "<string>",
  "user_id": "b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4",
  "currency": "USD",
  "metadata": {},
  "destination_wallet_id": "c3d4e5f6-a7b8-9012-3456-7890abcdef01",
  "destination_payee_id": "c8d9e0f1-a2b3-4567-89ab-cdef01234567",
  "notify_recipient": false
}
'

import requests

url = "https://api-sandbox.finogates.com/v1/platform/payments/wallet-to-wallet"

payload = {
    "wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "amount": 123,
    "idempotency_key": "<string>",
    "user_id": "b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4",
    "currency": "USD",
    "metadata": {},
    "destination_wallet_id": "c3d4e5f6-a7b8-9012-3456-7890abcdef01",
    "destination_payee_id": "c8d9e0f1-a2b3-4567-89ab-cdef01234567",
    "notify_recipient": 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({
    wallet_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    amount: 123,
    idempotency_key: '<string>',
    user_id: 'b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4',
    currency: 'USD',
    metadata: {},
    destination_wallet_id: 'c3d4e5f6-a7b8-9012-3456-7890abcdef01',
    destination_payee_id: 'c8d9e0f1-a2b3-4567-89ab-cdef01234567',
    notify_recipient: false
  })
};

fetch('https://api-sandbox.finogates.com/v1/platform/payments/wallet-to-wallet', 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/wallet-to-wallet",
  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([
    'wallet_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'amount' => 123,
    'idempotency_key' => '<string>',
    'user_id' => 'b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4',
    'currency' => 'USD',
    'metadata' => [
        
    ],
    'destination_wallet_id' => 'c3d4e5f6-a7b8-9012-3456-7890abcdef01',
    'destination_payee_id' => 'c8d9e0f1-a2b3-4567-89ab-cdef01234567',
    'notify_recipient' => 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/wallet-to-wallet"

	payload := strings.NewReader("{\n  \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount\": 123,\n  \"idempotency_key\": \"<string>\",\n  \"user_id\": \"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4\",\n  \"currency\": \"USD\",\n  \"metadata\": {},\n  \"destination_wallet_id\": \"c3d4e5f6-a7b8-9012-3456-7890abcdef01\",\n  \"destination_payee_id\": \"c8d9e0f1-a2b3-4567-89ab-cdef01234567\",\n  \"notify_recipient\": 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/wallet-to-wallet")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount\": 123,\n  \"idempotency_key\": \"<string>\",\n  \"user_id\": \"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4\",\n  \"currency\": \"USD\",\n  \"metadata\": {},\n  \"destination_wallet_id\": \"c3d4e5f6-a7b8-9012-3456-7890abcdef01\",\n  \"destination_payee_id\": \"c8d9e0f1-a2b3-4567-89ab-cdef01234567\",\n  \"notify_recipient\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.finogates.com/v1/platform/payments/wallet-to-wallet")

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  \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount\": 123,\n  \"idempotency_key\": \"<string>\",\n  \"user_id\": \"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4\",\n  \"currency\": \"USD\",\n  \"metadata\": {},\n  \"destination_wallet_id\": \"c3d4e5f6-a7b8-9012-3456-7890abcdef01\",\n  \"destination_payee_id\": \"c8d9e0f1-a2b3-4567-89ab-cdef01234567\",\n  \"notify_recipient\": false\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>"
    }
  ]
}

Wallet to Wallet (Internal Transfer)

Move money from one wallet to another on your platform. A transfer payment — no external rail or provider.

Address the destination one of two ways (send exactly one):

destination_wallet_id — a wallet UUID you already know. The server resolves the owning user from the wallet.
destination_payee_id — a payee addressed by email. Funds route to the matching user’s wallet, or to a held inbound-only wallet (a ghost recipient is provisioned) until that person is added — see recipient_status in the response (existing vs pending_claim).

POST

platform

payments

wallet-to-wallet

Wallet → Wallet (internal transfer)

curl --request POST \
  --url https://api-sandbox.finogates.com/v1/platform/payments/wallet-to-wallet \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "amount": 123,
  "idempotency_key": "<string>",
  "user_id": "b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4",
  "currency": "USD",
  "metadata": {},
  "destination_wallet_id": "c3d4e5f6-a7b8-9012-3456-7890abcdef01",
  "destination_payee_id": "c8d9e0f1-a2b3-4567-89ab-cdef01234567",
  "notify_recipient": false
}
'

import requests

url = "https://api-sandbox.finogates.com/v1/platform/payments/wallet-to-wallet"

payload = {
    "wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "amount": 123,
    "idempotency_key": "<string>",
    "user_id": "b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4",
    "currency": "USD",
    "metadata": {},
    "destination_wallet_id": "c3d4e5f6-a7b8-9012-3456-7890abcdef01",
    "destination_payee_id": "c8d9e0f1-a2b3-4567-89ab-cdef01234567",
    "notify_recipient": 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({
    wallet_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    amount: 123,
    idempotency_key: '<string>',
    user_id: 'b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4',
    currency: 'USD',
    metadata: {},
    destination_wallet_id: 'c3d4e5f6-a7b8-9012-3456-7890abcdef01',
    destination_payee_id: 'c8d9e0f1-a2b3-4567-89ab-cdef01234567',
    notify_recipient: false
  })
};

fetch('https://api-sandbox.finogates.com/v1/platform/payments/wallet-to-wallet', 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/wallet-to-wallet",
  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([
    'wallet_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'amount' => 123,
    'idempotency_key' => '<string>',
    'user_id' => 'b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4',
    'currency' => 'USD',
    'metadata' => [
        
    ],
    'destination_wallet_id' => 'c3d4e5f6-a7b8-9012-3456-7890abcdef01',
    'destination_payee_id' => 'c8d9e0f1-a2b3-4567-89ab-cdef01234567',
    'notify_recipient' => 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/wallet-to-wallet"

	payload := strings.NewReader("{\n  \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount\": 123,\n  \"idempotency_key\": \"<string>\",\n  \"user_id\": \"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4\",\n  \"currency\": \"USD\",\n  \"metadata\": {},\n  \"destination_wallet_id\": \"c3d4e5f6-a7b8-9012-3456-7890abcdef01\",\n  \"destination_payee_id\": \"c8d9e0f1-a2b3-4567-89ab-cdef01234567\",\n  \"notify_recipient\": 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/wallet-to-wallet")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount\": 123,\n  \"idempotency_key\": \"<string>\",\n  \"user_id\": \"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4\",\n  \"currency\": \"USD\",\n  \"metadata\": {},\n  \"destination_wallet_id\": \"c3d4e5f6-a7b8-9012-3456-7890abcdef01\",\n  \"destination_payee_id\": \"c8d9e0f1-a2b3-4567-89ab-cdef01234567\",\n  \"notify_recipient\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.finogates.com/v1/platform/payments/wallet-to-wallet")

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  \"wallet_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount\": 123,\n  \"idempotency_key\": \"<string>\",\n  \"user_id\": \"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4\",\n  \"currency\": \"USD\",\n  \"metadata\": {},\n  \"destination_wallet_id\": \"c3d4e5f6-a7b8-9012-3456-7890abcdef01\",\n  \"destination_payee_id\": \"c8d9e0f1-a2b3-4567-89ab-cdef01234567\",\n  \"notify_recipient\": false\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

Authorization

string

header

required

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

Body

application/json

Move funds to another wallet on your platform (intent_type=transfer).

Address the destination one of two ways — send exactly one:

destination_wallet_id — a wallet UUID you already know.
destination_payee_id — a payee (addressed by email). Funds route to the matching user's wallet, or to a held inbound-only wallet (a ghost recipient is provisioned) until that person is added — see recipient_status in the response.

wallet_id

string<uuid>

required

Source wallet UUID — the tenant's master wallet or one of the user's wallets. Server validates tenant ownership and currency and resolves the owner from it.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

amount

number

required

Amount in major currency units (e.g. dollars).

Example:

100.5

idempotency_key

string

required

Unique key to ensure idempotent payment creation.

Required string length: 1 - 120

Example:

"pay_req_20260604_abc123"

user_id

string<uuid> | null

Optional safety cross-check — when sent, must match the owner of wallet_id.

Example:

"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4"

currency

string

default:USD

ISO 4217 currency code.

Required string length: 3

Example:

"USD"

metadata

Metadata · object

Arbitrary key-value metadata to attach to the payment.

Example:

{ "order_id": "ORD-12345" }

destination_wallet_id

string<uuid> | null

Destination wallet UUID to credit. Server validates tenant ownership and currency and resolves the owner from it. Mutually exclusive with destination_payee_id — send one.

Example:

"c3d4e5f6-a7b8-9012-3456-7890abcdef01"

destination_payee_id

string<uuid> | null

UUID of the payee to send to. The payee must have an email; funds route to the matching user's wallet, or a held inbound-only wallet until that person is added. Mutually exclusive with destination_wallet_id — send one.

Example:

"c8d9e0f1-a2b3-4567-89ab-cdef01234567"

notify_recipient

boolean

default:false

Payee transfers only. Records a preference to notify the recipient that funds arrived. Outbound notification delivery is not yet active.

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.

Wallet to Bank (Payout)List Payments

Auth

Users

Payees

Verification

Bank Accounts

Card Processing

Digital Assets

International

Pending Applications

Wallets

Payments

Catalog

Webhooks

Phone Numbers

Sms

Calls

Listings

Embed Tokens

Wallet to Wallet (Internal Transfer)

Authorizations

Body

Response