Merchants
Transfer Pending Funds
Move fiat balance from one merchant’s Pending Fund account to another merchant within the VelaFi platform instantly and without a bank transfer.
POST
/
v2
/
merchant
/
transfer
Transfer Pending Funds
curl --request POST \
--url https://api-test.velafi.com/v2/merchant/transfer \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"clientId": "<string>",
"fromMerchantId": 123,
"toMerchantId": 123,
"fiat": "<string>",
"paymentId": 123,
"fiatAmount": 123
}
'import requests
url = "https://api-test.velafi.com/v2/merchant/transfer"
payload = {
"clientId": "<string>",
"fromMerchantId": 123,
"toMerchantId": 123,
"fiat": "<string>",
"paymentId": 123,
"fiatAmount": 123
}
headers = {
"X-BH-TOKEN": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
clientId: '<string>',
fromMerchantId: 123,
toMerchantId: 123,
fiat: '<string>',
paymentId: 123,
fiatAmount: 123
})
};
fetch('https://api-test.velafi.com/v2/merchant/transfer', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/merchant/transfer")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"clientId\": \"<string>\",\n \"fromMerchantId\": 123,\n \"toMerchantId\": 123,\n \"fiat\": \"<string>\",\n \"paymentId\": 123,\n \"fiatAmount\": 123\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"clientId": "<string>",
"fromId": 123,
"toId": 123,
"fiat": "<string>",
"fiatAmount": "<string>",
"totalFiatAmount": "<string>",
"fee": "<string>",
"createTime": 123
}
}Use this endpoint to transfer fiat funds between two merchant accounts inside the VelaFi system. The transfer is internal and does not require a bank transaction. Both the sending and receiving merchants must have active accounts for the specified
fiat and paymentId combination. Use the Transfer Fee endpoint first to check applicable costs before initiating the transfer.
All requests must include the
X-BH-TOKEN header and Content-Type: application/json. The clientId is used for idempotency — duplicate clientId values return the original result.Endpoint
POST https://api.velafi.com/v2/merchant/transfer
Request Parameters
string
required
Your unique identifier for this transfer. Used for deduplication and tracing.
number
required
ID of the merchant sending the funds.
number
required
ID of the merchant receiving the funds.
string
required
Fiat currency to transfer. Supported values:
MXN, ARS, COP, BRL, PEN.number
required
Payment channel ID matching the fiat currency:
105or72— MXN63— ARS68— COP90— BRL95— PEN
number
required
Amount to transfer in the specified fiat currency.
Response Fields
number
HTTP-style response code.
200 indicates success.string
Human-readable status message, e.g.
SUCCESS.object
Show data fields
Show data fields
string
Your client-supplied identifier echoed back.
number
Funding Records ID on the sender’s account (debit entry).
number
Funding Records ID on the recipient’s account (credit entry).
string
Fiat currency of the transfer.
string
Net amount transferred.
string
Total amount deducted from the sender (fiatAmount + fee).
string
Fee charged for this transfer.
number
Unix timestamp (milliseconds) when the transfer was created.
Examples
- MXN
- ARS
- COP / BRL / PEN
cURL
curl -X POST https://api.velafi.com/v2/merchant/transfer \
-H "X-BH-TOKEN: YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"clientId": "transfer-mxn-001",
"fromMerchantId": 434,
"toMerchantId": 5,
"fiat": "MXN",
"paymentId": 105,
"fiatAmount": 10
}'
Response
{
"code": 200,
"msg": "SUCCESS",
"data": {
"clientId": "transfer-mxn-001",
"fromId": 521006138624569344,
"toId": 521006138641346560,
"fiat": "MXN",
"fiatAmount": "10",
"totalFiatAmount": "10",
"fee": "0",
"createTime": 1746694343261
}
}
Request body
{
"clientId": "transfer-ars-001",
"fromMerchantId": 434,
"toMerchantId": 5,
"fiat": "ARS",
"paymentId": 63,
"fiatAmount": 10
}
Response
{
"code": 200,
"msg": "SUCCESS",
"data": {
"clientId": "transfer-ars-001",
"fromId": 521006138624569345,
"toId": 521006138641346561,
"fiat": "ARS",
"fiatAmount": "10",
"totalFiatAmount": "10",
"fee": "0",
"createTime": 1746694343261
}
}
COP Request body
{
"clientId": "transfer-cop-001",
"fromMerchantId": 15127301,
"toMerchantId": 15127302,
"fiat": "COP",
"paymentId": 68,
"fiatAmount": 10
}
BRL Request body
{
"clientId": "transfer-brl-001",
"fromMerchantId": 15127301,
"toMerchantId": 15127302,
"fiat": "BRL",
"paymentId": 90,
"fiatAmount": 10
}
PEN Request body
{
"clientId": "transfer-pen-001",
"fromMerchantId": 15127301,
"toMerchantId": 15127302,
"fiat": "PEN",
"paymentId": 95,
"fiatAmount": 10
}
Use the
fromId and toId values to look up the corresponding entries in the Funding Records endpoint for full audit trail.Was this page helpful?
⌘I
Transfer Pending Funds
curl --request POST \
--url https://api-test.velafi.com/v2/merchant/transfer \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"clientId": "<string>",
"fromMerchantId": 123,
"toMerchantId": 123,
"fiat": "<string>",
"paymentId": 123,
"fiatAmount": 123
}
'import requests
url = "https://api-test.velafi.com/v2/merchant/transfer"
payload = {
"clientId": "<string>",
"fromMerchantId": 123,
"toMerchantId": 123,
"fiat": "<string>",
"paymentId": 123,
"fiatAmount": 123
}
headers = {
"X-BH-TOKEN": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
clientId: '<string>',
fromMerchantId: 123,
toMerchantId: 123,
fiat: '<string>',
paymentId: 123,
fiatAmount: 123
})
};
fetch('https://api-test.velafi.com/v2/merchant/transfer', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/merchant/transfer")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"clientId\": \"<string>\",\n \"fromMerchantId\": 123,\n \"toMerchantId\": 123,\n \"fiat\": \"<string>\",\n \"paymentId\": 123,\n \"fiatAmount\": 123\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"clientId": "<string>",
"fromId": 123,
"toId": 123,
"fiat": "<string>",
"fiatAmount": "<string>",
"totalFiatAmount": "<string>",
"fee": "<string>",
"createTime": 123
}
}