Skip to main content
POST
/
cards
/
{id}
/
fund
Fund a card
curl --request POST \
  --url https://api.cartevo.co/api/v1/cards/{id}/fund \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 2
}'

​
Overview

POST /cards/{id}/fund moves USD from your company’s USD wallet onto the specified card. The card balance increases immediately on success, and the cardholder can use the funds for online payments.

​
When to use it

  • Top up a card before the cardholder makes a purchase.
  • Move savings/payroll/per-diem funds onto an active card.
For the reverse direction (card → wallet), see POST /cards/{id}/withdraw.

​
Prerequisites

  • Card status must be ACTIVE (not PENDING, FROZEN, SUSPENDED, TERMINATED, or FAILED).
  • The card must belong to your company.
  • The company USD wallet must have enough balance to cover amount plus any funding fees configured on your account.

​
Request

​
Headers

NameRequiredDescription
AuthorizationYesBearer <access_token>
Content-TypeYesapplication/json

​
Path parameters

NameTypeDescription
idstringCard ID (UUID).

​
Body

FieldTypeRequiredConstraintsDescription
amountnumberYes≥ 1. USD.Amount to move from the USD wallet onto the card.
{
  "amount": 50
}
Idempotency: This endpoint does not currently accept an idempotency key. To avoid double-funding on network retries, store the resulting transaction_id after the first call returns and check before retrying.

​
Response

​
200 — Success

{
  "success": true,
  "statusCode": 200,
  "message": "Card funded successfully",
  "data": {
    "transaction_id": "txn_5b7c9d2e4f6a8b1c3d5e7f9a",
    "card_id": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 50.0,
    "currency": "USD",
    "fee_amount": 0.0,
    "card_balance_before": 100.0,
    "card_balance_after": 150.0
  }
}
FieldTypeDescription
transaction_idstringCartevo transaction ID. Use for support and reconciliation.
card_idstringThe funded card.
amountnumberNet amount added to the card.
currencystringAlways USD.
fee_amountnumberFunding fee charged to the wallet (typically 0).
card_balance_beforenumberCard balance before this call.
card_balance_afternumberCard balance after this call.

​
Error responses

Statusmessage exampleTriggerRecommended action
400"Insufficient wallet balance"USD wallet balance < amount + fee.Top up the USD wallet, then retry.
400"Card not active"Card status is not ACTIVE.Unfreeze the card or check it is not terminated.
400"Amount must be at least 1"amount < 1.Fix the request.
404"Card not found"id is invalid or belongs to another company.Verify the card ID.
5xx"Funding temporarily unavailable"Upstream issuer transient error.Retry with exponential backoff. Check the card balance before retrying to avoid double-funding.

​
Webhooks fired

​
Code examples

cURL
curl -X POST https://api.cartevo.co/api/v1/cards/550e8400-e29b-41d4-a716-446655440000/fund \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50}'
Node.js (axios)
await axios.post(
  `https://api.cartevo.co/api/v1/cards/${cardId}/fund`,
  { amount: 50 },
  { headers: { Authorization: `Bearer ${token}` } }
);
Python (requests)
requests.post(
    f"https://api.cartevo.co/api/v1/cards/{card_id}/fund",
    headers={"Authorization": f"Bearer {token}"},
    json={"amount": 50},
).raise_for_status()

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
Required range: x >= 1

Response

Card funded successfully