/api/v1/withdrawals write:withdrawal Pulls one or more of your cards back out of the warehouse, either shipped to you (method "ship") or picked up (method "pickup"). Supports grouping multiple cards into a single withdrawal. Cards must be free to withdraw: a card committed to an in-flight order, or already on another withdrawal, returns 409 — cancel the order first if you intend to withdraw a card that is already being fulfilled. A withdrawal.requested event is written to your activity log on success.
POST /api/v1/withdrawals write These inputs are shared across all docs pages, so an id entered here carries over.
{
"unique_ids": [
"CARD-EXAMPLE-1"
],
"method": "ship",
"destination": {
"name": "Demo Buyer",
"street1": "1 Market St",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
},
"idempotency_key": "docs-withdrawal-CARD-EXAMPLE-1"
}Not run yet. Press Run to make a live call against https://service.rip.fun (through this demo's server-side proxy; the API key never reaches the browser).
curl -X POST 'https://service.rip.fun/api/v1/withdrawals' \
-H 'X-API-Key: rip_…' \
-H 'Content-Type: application/json' \
-d '{"unique_ids":["CARD-EXAMPLE-1"],"method":"ship","destination":{"name":"Demo Buyer","street1":"1 Market St","city":"San Francisco","state":"CA","zip":"94105","country":"US"},"idempotency_key":"docs-withdrawal-CARD-EXAMPLE-1"}' | Field | Type | Required | Description |
|---|---|---|---|
unique_ids | string[] | yes | Cards to withdraw (or provide a single unique_id string instead) |
method | "ship" | "pickup" | yes | Matched exactly, case-sensitive — "PICKUP" is rejected, not interpreted |
destination | object | — | Required when method = "ship". Free-form JSON and NOT validated — send the standard address shape so the warehouse can act on it without a follow-up |
note | string | — | Up to 512 chars |
idempotency_key | string | — | Up to 128 chars; a replay returns the original withdrawal with 201 |
data)| Field | Description |
|---|---|
withdrawal.id / status / method | Status is "REQUESTED" on create; lifecycle REQUESTED → ACKNOWLEDGED → IN_TRANSIT → COMPLETED | CANCELLED — poll GET /withdrawals/:id |
withdrawal.destination / note / idempotency_key / api_key_id | What you submitted + the key that wrote it |
withdrawal.requested_at / created_at / updated_at | Timestamps |
card_count | Distinct cards in this request |
| Status | Code | When |
|---|---|---|
| 400 | invalid input | empty unique_ids, unrecognized method, or method "ship" with no destination |
| 404 | card(s) not found | one or more cards not part of your account (the message names them) |
| 409 | card(s) unavailable | one or more cards not available for withdrawal — the message names them with their current status |
| 409 | CARD_ALREADY_WITHDRAWING | a card is already on a withdrawal that has not completed or been cancelled |
| 400 | invalid_pagination | unique_ids has more than 500 entries |
See Errors for the response envelope and the full code list.