Withdraw from a card
curl --request POST \
--url https://api.cartevo.co/api/v1/cards/{id}/withdraw \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"amount": 2
}'import requests
url = "https://api.cartevo.co/api/v1/cards/{id}/withdraw"
payload = { "amount": 2 }
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({amount: 2})
};
fetch('https://api.cartevo.co/api/v1/cards/{id}/withdraw', 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.cartevo.co/api/v1/cards/{id}/withdraw",
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([
'amount' => 2
]),
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.cartevo.co/api/v1/cards/{id}/withdraw"
payload := strings.NewReader("{\n \"amount\": 2\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.cartevo.co/api/v1/cards/{id}/withdraw")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 2\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cartevo.co/api/v1/cards/{id}/withdraw")
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 \"amount\": 2\n}"
response = http.request(request)
puts response.read_bodyCards
Withdraw from Card
Move USD from a card back to your company USD wallet.
POST
/
cards
/
{id}
/
withdraw
Withdraw from a card
curl --request POST \
--url https://api.cartevo.co/api/v1/cards/{id}/withdraw \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"amount": 2
}'import requests
url = "https://api.cartevo.co/api/v1/cards/{id}/withdraw"
payload = { "amount": 2 }
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({amount: 2})
};
fetch('https://api.cartevo.co/api/v1/cards/{id}/withdraw', 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.cartevo.co/api/v1/cards/{id}/withdraw",
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([
'amount' => 2
]),
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.cartevo.co/api/v1/cards/{id}/withdraw"
payload := strings.NewReader("{\n \"amount\": 2\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.cartevo.co/api/v1/cards/{id}/withdraw")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 2\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cartevo.co/api/v1/cards/{id}/withdraw")
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 \"amount\": 2\n}"
response = http.request(request)
puts response.read_bodyOverview
POST /cards/{id}/withdraw moves USD from the specified card back to your company’s USD wallet. The card balance decreases immediately on success; the withdrawn funds are credited to the wallet.
When to use it
- Reclaim leftover funds before terminating a card.
- Move funds between cards by withdrawing from one and funding another.
- Recover funds when a customer returns an unused per-diem allowance.
POST /cards/{id}/fund.
Prerequisites
- Card status must be
ACTIVEorFROZEN(you can withdraw from a frozen card to recover funds before terminating it). - The card must belong to your company.
- The card balance must be ≥
amount.
Request
Headers
| Name | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <access_token> |
Content-Type | Yes | application/json |
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Card ID (UUID). |
Body
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
amount | number | Yes | ≥ 1. USD. | Amount to withdraw from the card to the company USD wallet. Minimum 1 USD. |
{
"amount": 30
}
Response
200 — Success
{
"success": true,
"statusCode": 200,
"message": "Card withdrawal successful",
"data": {
"transaction_id": "txn_nop678qrs234tuv901wxy567",
"card_id": "550e8400-e29b-41d4-a716-446655440000",
"amount": 30.0,
"currency": "USD",
"fee_amount": 0.0,
"card_balance_before": 150.0,
"card_balance_after": 120.0
}
}
| Field | Type | Description |
|---|---|---|
transaction_id | string | Cartevo transaction ID. Use for support and reconciliation. |
card_id | string | The card the funds came from. |
amount | number | Net amount credited back to the USD wallet. |
currency | string | Always USD. |
fee_amount | number | Withdrawal fee charged (typically 0). |
card_balance_before | number | Card balance before this call. |
card_balance_after | number | Card balance after this call. |
Error responses
| Status | message example | Trigger | Recommended action |
|---|---|---|---|
400 | "Insufficient card balance" | Card balance < amount. | Fetch the current balance and adjust. |
400 | "Amount must be at least 1" | amount < 1. | Fix the request. |
400 | "Card terminated" | Card status is TERMINATED. | Cannot withdraw — terminated cards have already had their balance refunded. |
404 | "Card not found" | id is invalid or belongs to another company. | Verify the card ID. |
5xx | "Withdrawal temporarily unavailable" | Upstream issuer transient error. | Retry with backoff. The webhook card.withdraw.failed is also emitted on permanent failure. |
Webhooks fired
card.withdraw— on success.card.withdraw.failed— on permanent failure (e.g. upstream rejected).transaction.withdrawal.completed— once the transaction settles.
Code examples
cURL
curl -X POST https://api.cartevo.co/api/v1/cards/550e8400-e29b-41d4-a716-446655440000/withdraw \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"amount": 30}'
Node.js (axios)
await axios.post(
`https://api.cartevo.co/api/v1/cards/${cardId}/withdraw`,
{ amount: 30 },
{ headers: { Authorization: `Bearer ${token}` } }
);
Related
POST /cards/{id}/fund— the reverse direction.POST /cards/{id}/terminate— terminating a card auto-refunds the remaining balance, so you don’t need to withdraw first.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Body
application/json
Amount in USD to withdraw from the card to the company USD wallet. Minimum 1 USD.
Required range:
x >= 1Response
Withdrawal successful