Merchants
Claim Pending Funds
Withdraw available balance from a merchant’s Pending Fund account to a registered payment method and receive a trackable transaction ID.
POST
/
v2
/
merchant
/
claimfunds
Claim Pending Funds
curl --request POST \
--url https://api-test.velafi.com/v2/merchant/claimfunds \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"merchantId": 123,
"fiat": "<string>",
"amount": 123,
"userPaymentId": 123,
"clientId": "<string>"
}
'import requests
url = "https://api-test.velafi.com/v2/merchant/claimfunds"
payload = {
"merchantId": 123,
"fiat": "<string>",
"amount": 123,
"userPaymentId": 123,
"clientId": "<string>"
}
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({
merchantId: 123,
fiat: '<string>',
amount: 123,
userPaymentId: 123,
clientId: '<string>'
})
};
fetch('https://api-test.velafi.com/v2/merchant/claimfunds', 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/claimfunds")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"merchantId\": 123,\n \"fiat\": \"<string>\",\n \"amount\": 123,\n \"userPaymentId\": 123,\n \"clientId\": \"<string>\"\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"txId": 123,
"merchantId": 123,
"clientId": "<string>",
"fiat": "<string>",
"totalAmount": 123,
"amount": 123,
"fee": 123,
"userPaymentId": 123,
"createTime": "<string>"
}
}Use this endpoint to initiate a withdrawal from a merchant’s Pending Fund account. Specify the merchant, fiat currency, amount, and the target payment method ID (obtainable from
GET /v2/payments). VelaFi returns a txId you can use to track the withdrawal through the Funding Records endpoint. A fee may apply depending on the withdrawal channel.
All requests must include the
X-BH-TOKEN header and Content-Type: application/json. Currently supported currencies are MXN and ARS.Endpoint
POST https://api.velafi.com/v2/merchant/claimfunds
Request Parameters
number
required
The ID of the merchant making the withdrawal.
string
required
Fiat currency to withdraw. Currently supported:
MXN, ARS.number
required
Amount to withdraw in the specified fiat currency.
number
required
ID of the user’s registered payment method to receive the funds. Obtain via
GET /v2/payments.string
Your own unique identifier for this withdrawal, used for idempotency and tracking.
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
number
Unique ID for this withdrawal transaction.
number
ID of the merchant that initiated the withdrawal.
string
Your client-supplied identifier for this transaction.
string
Fiat currency of the withdrawal.
number
Total amount deducted from the Pending Fund balance (amount + fee).
number
Net amount delivered to the payment method.
number
Fee charged for this withdrawal.
number
ID of the payment method receiving the funds.
string
Unix timestamp (milliseconds) when the withdrawal was created.
Example
cURL
curl -X POST https://api.velafi.com/v2/merchant/claimfunds \
-H "X-BH-TOKEN: YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"merchantId": 3,
"clientId": "withdraw-2024-001",
"fiat": "MXN",
"amount": 20.00,
"userPaymentId": 91
}'
Response
{
"code": 200,
"msg": "SUCCESS",
"data": {
"txId": 1123123123,
"merchantId": 3,
"clientId": "withdraw-2024-001",
"fiat": "MXN",
"totalAmount": 22.00,
"amount": 20.00,
"fee": 2.00,
"userPaymentId": 91,
"createTime": "1737452292000"
}
}
Always supply a unique
clientId per withdrawal request. If a duplicate clientId is detected, the API returns the original transaction instead of creating a new one.Was this page helpful?
⌘I
Claim Pending Funds
curl --request POST \
--url https://api-test.velafi.com/v2/merchant/claimfunds \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"merchantId": 123,
"fiat": "<string>",
"amount": 123,
"userPaymentId": 123,
"clientId": "<string>"
}
'import requests
url = "https://api-test.velafi.com/v2/merchant/claimfunds"
payload = {
"merchantId": 123,
"fiat": "<string>",
"amount": 123,
"userPaymentId": 123,
"clientId": "<string>"
}
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({
merchantId: 123,
fiat: '<string>',
amount: 123,
userPaymentId: 123,
clientId: '<string>'
})
};
fetch('https://api-test.velafi.com/v2/merchant/claimfunds', 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/claimfunds")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"merchantId\": 123,\n \"fiat\": \"<string>\",\n \"amount\": 123,\n \"userPaymentId\": 123,\n \"clientId\": \"<string>\"\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"txId": 123,
"merchantId": 123,
"clientId": "<string>",
"fiat": "<string>",
"totalAmount": 123,
"amount": 123,
"fee": 123,
"userPaymentId": 123,
"createTime": "<string>"
}
}