Skip to main content
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
}'

​
Overview

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.
For the reverse direction (wallet → card), see POST /cards/{id}/fund.

​
Prerequisites

  • Card status must be ACTIVE or FROZEN (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

NameRequiredDescription
AuthorizationYesBearer <access_token>
Content-TypeYesapplication/json

​
Path parameters

NameTypeDescription
idstringCard ID (UUID).

​
Body

FieldTypeRequiredConstraintsDescription
amountnumberYes≥ 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
  }
}
FieldTypeDescription
transaction_idstringCartevo transaction ID. Use for support and reconciliation.
card_idstringThe card the funds came from.
amountnumberNet amount credited back to the USD wallet.
currencystringAlways USD.
fee_amountnumberWithdrawal fee charged (typically 0).
card_balance_beforenumberCard balance before this call.
card_balance_afternumberCard balance after this call.

​
Error responses

Statusmessage exampleTriggerRecommended 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

​
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}` } }
);

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string<uuid>
required

Body

application/json
​
amount
number
required

Amount in USD to withdraw from the card to the company USD wallet. Minimum 1 USD.

Required range: x >= 1

Response

Withdrawal successful