Execute a withdrawal
curl --request POST \
--url https://api.xentfi.com/v1/offramp/withdrawals \
--header 'Content-Type: application/json' \
--header 'apiKey: <api-key>' \
--header 'orgId: <api-key>' \
--data '
{
"sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"paymentMethod": "bank_transfer",
"paymentMethodData": {
"bankCode": 58,
"accountNumber": 123456789,
"accountHolderFirstName": "Ada",
"accountHolderLastName": "Obi"
}
}
'const options = {
method: 'POST',
headers: {apiKey: '<api-key>', orgId: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
sessionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
reference: '<string>',
paymentMethod: 'bank_transfer',
paymentMethodData: {
bankCode: 58,
accountNumber: 123456789,
accountHolderFirstName: 'Ada',
accountHolderLastName: 'Obi'
}
})
};
fetch('https://api.xentfi.com/v1/offramp/withdrawals', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.xentfi.com/v1/offramp/withdrawals"
payload = {
"sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"paymentMethod": "bank_transfer",
"paymentMethodData": {
"bankCode": 58,
"accountNumber": 123456789,
"accountHolderFirstName": "Ada",
"accountHolderLastName": "Obi"
}
}
headers = {
"apiKey": "<api-key>",
"orgId": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.xentfi.com/v1/offramp/withdrawals"
payload := strings.NewReader("{\n \"sessionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"reference\": \"<string>\",\n \"paymentMethod\": \"bank_transfer\",\n \"paymentMethodData\": {\n \"bankCode\": 58,\n \"accountNumber\": 123456789,\n \"accountHolderFirstName\": \"Ada\",\n \"accountHolderLastName\": \"Obi\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("apiKey", "<api-key>")
req.Header.Add("orgId", "<api-key>")
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))
}const options = {
method: 'POST',
headers: {apiKey: '<api-key>', orgId: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
sessionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
reference: '<string>',
paymentMethod: 'bank_transfer',
paymentMethodData: {
bankCode: 58,
accountNumber: 123456789,
accountHolderFirstName: 'Ada',
accountHolderLastName: 'Obi'
}
})
};
fetch('https://api.xentfi.com/v1/offramp/withdrawals', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"status": "initiated",
"walletId": "<string>",
"assetId": "<string>",
"customerId": "<string>",
"currency": "<string>",
"paymentMethod": "<string>",
"sourceAmount": "<string>",
"fiatAmount": "<string>",
"rate": "<string>",
"fee": "<string>",
"recipient": {},
"transactionHash": "<string>",
"failureReason": "<string>",
"failureStage": "provider_setup",
"refundDetailsRequired": true,
"note": "<string>",
"metadata": {},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"completedAt": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Wallet not found",
"timestamp": "2023-11-07T05:31:56Z",
"requestId": "<string>"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Wallet not found",
"timestamp": "2023-11-07T05:31:56Z",
"requestId": "<string>"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Wallet not found",
"timestamp": "2023-11-07T05:31:56Z",
"requestId": "<string>"
}
}Off-ramp
Execute a withdrawal
Converts stablecoins held in your managed wallet to fiat and pays out to the bank account.
In one call we: validate paymentMethodData; set up the payout with the provider (the recipient’s account name is verified before any funds move); check the rate against your quote (rejects if it moved beyond tolerance); then send the stablecoin from your wallet. The response is funds_sent; everything after is asynchronous.
Idempotent: retrying with the same reference and sessionId returns the same withdrawal and never sends twice. A reference reused with a different quote returns 409. A quote can be used once.
Failure before funds move (name mismatch, rate moved, provider rejection) leaves the withdrawal failed with failureStage; nothing is debited. Webhook events: offramp.created, offramp.funds_sent, offramp.processing, offramp.completed, offramp.failed, offramp.refund_required, offramp.refunded.
Flow: GET /currencies → GET /assets → GET /payment-methods (render the JSON Schema; for NGN/GHS get bankCodes from GET /banks) → POST /quotes (rate lock, ~2 min) → POST /withdrawals → track via offramp.* webhooks or GET /withdrawals/{id}.
Routing is automatic: NGN/GHS are paid out through our local African corridor; USD (wire/ACH) and EUR (SEPA) through our global corridor. USD/EUR payouts require an onboarded customerId (see Customer Onboarding).
POST
/
v1
/
offramp
/
withdrawals
Execute a withdrawal
curl --request POST \
--url https://api.xentfi.com/v1/offramp/withdrawals \
--header 'Content-Type: application/json' \
--header 'apiKey: <api-key>' \
--header 'orgId: <api-key>' \
--data '
{
"sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"paymentMethod": "bank_transfer",
"paymentMethodData": {
"bankCode": 58,
"accountNumber": 123456789,
"accountHolderFirstName": "Ada",
"accountHolderLastName": "Obi"
}
}
'const options = {
method: 'POST',
headers: {apiKey: '<api-key>', orgId: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
sessionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
reference: '<string>',
paymentMethod: 'bank_transfer',
paymentMethodData: {
bankCode: 58,
accountNumber: 123456789,
accountHolderFirstName: 'Ada',
accountHolderLastName: 'Obi'
}
})
};
fetch('https://api.xentfi.com/v1/offramp/withdrawals', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.xentfi.com/v1/offramp/withdrawals"
payload = {
"sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"paymentMethod": "bank_transfer",
"paymentMethodData": {
"bankCode": 58,
"accountNumber": 123456789,
"accountHolderFirstName": "Ada",
"accountHolderLastName": "Obi"
}
}
headers = {
"apiKey": "<api-key>",
"orgId": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.xentfi.com/v1/offramp/withdrawals"
payload := strings.NewReader("{\n \"sessionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"reference\": \"<string>\",\n \"paymentMethod\": \"bank_transfer\",\n \"paymentMethodData\": {\n \"bankCode\": 58,\n \"accountNumber\": 123456789,\n \"accountHolderFirstName\": \"Ada\",\n \"accountHolderLastName\": \"Obi\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("apiKey", "<api-key>")
req.Header.Add("orgId", "<api-key>")
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))
}const options = {
method: 'POST',
headers: {apiKey: '<api-key>', orgId: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
sessionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
reference: '<string>',
paymentMethod: 'bank_transfer',
paymentMethodData: {
bankCode: 58,
accountNumber: 123456789,
accountHolderFirstName: 'Ada',
accountHolderLastName: 'Obi'
}
})
};
fetch('https://api.xentfi.com/v1/offramp/withdrawals', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"status": "initiated",
"walletId": "<string>",
"assetId": "<string>",
"customerId": "<string>",
"currency": "<string>",
"paymentMethod": "<string>",
"sourceAmount": "<string>",
"fiatAmount": "<string>",
"rate": "<string>",
"fee": "<string>",
"recipient": {},
"transactionHash": "<string>",
"failureReason": "<string>",
"failureStage": "provider_setup",
"refundDetailsRequired": true,
"note": "<string>",
"metadata": {},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"completedAt": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Wallet not found",
"timestamp": "2023-11-07T05:31:56Z",
"requestId": "<string>"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Wallet not found",
"timestamp": "2023-11-07T05:31:56Z",
"requestId": "<string>"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Wallet not found",
"timestamp": "2023-11-07T05:31:56Z",
"requestId": "<string>"
}
}Body
application/json
Your unique idempotency reference
Pattern:
^[A-Za-z0-9_-]{8,64}$Example:
"bank_transfer"
Validated against the payment method's schema
Example:
{
"bankCode": 58,
"accountNumber": 123456789,
"accountHolderFirstName": "Ada",
"accountHolderLastName": "Obi"
}
Required for USD/EUR — an onboarded customer
Response
Withdrawal accepted and funded
Show child attributes
Show child attributes