> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Unload Card
> Withdraw remaining balance from a card back to your business wallet. POST /cards/{cardId}/unload.
## Overview
Withdraw funds from a card back to your business wallet. An unloading fee may apply based on your pricing configuration.
## Path Parameters
| Parameter | Type | Description |
| --------- | ------ | -------------------------- |
| `cardId` | string | The unique card identifier |
## Request Body
| Field | Type | Required | Description |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `amount` | number | Yes | Amount to unload in USD |
| `reference` | string | No | Your unique reference for this operation. Defaults to cardId if not provided. Returned in webhooks for easy reconciliation. |
## Example Usage
```php PHP theme={null}
25.00,
'reference' => 'withdraw-67890' // Optional: your unique reference
];
$ch = curl_init("https://api.fyatu.com/api/v3/cards/{$cardId}/unload");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $accessToken,
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode($data)
]);
$response = curl_exec($ch);
$result = json_decode($response, true);
if ($result['success']) {
echo "Unloaded: $" . $result['data']['amountUnloaded'] . "\n";
echo "Reference: " . $result['data']['reference'] . "\n";
}
```
```javascript Node.js theme={null}
const cardId = 'crd_8f3a2b1c4d5e6f7890abcdef12345678';
const response = await fetch(`https://api.fyatu.com/api/v3/cards/${cardId}/unload`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: 25.00,
reference: 'withdraw-67890' // Optional: your unique reference
})
});
const result = await response.json();
if (result.success) {
console.log('Unloaded: $' + result.data.amountUnloaded);
console.log('Reference: ' + result.data.reference);
}
```
## Error Responses
| Status | Error Code | Description |
| ------ | --------------------------- | -------------------------------------------------------- |
| 400 | `CARD_NOT_ACTIVE` | Card is not active (frozen, suspended, or terminated) |
| 400 | `INSUFFICIENT_CARD_BALANCE` | Card balance is lower than the requested unload amount |
| 400 | `CARD_FROZEN` | Card is frozen at bank partner (auto-syncs local status) |
| 400 | `CARD_TERMINATED` | Card has been terminated (auto-syncs local status) |
| 500 | `BALANCE_CHECK_FAILED` | Failed to verify card balance |
| 500 | `UNLOAD_FAILED` | Failed to unload card at the bank partner |
The funds are credited to your business wallet immediately after successful unloading. Use the [Get Pricing](/v3/api-reference/account/pricing) endpoint to check if unloading fees apply.
## OpenAPI
````yaml v3/openapi.json POST /cards/{cardId}/unload
openapi: 3.1.0
info:
title: FYATU API v3
description: >-
FYATU API v3 with JWT authentication for Collections, Payouts, and Card
Issuing.
version: 3.0.0
contact:
name: FYATU Support
url: https://fyatu.com
email: support@fyatu.com
servers:
- url: https://api.fyatu.com/api/v3
description: Production
security: []
tags:
- name: Authentication
description: JWT token management endpoints
- name: Account
description: Business account, wallet, and address management
- name: Collections
description: Accept payments from customers via checkout sessions
- name: Refunds
description: Issue refunds for completed collections
- name: Payouts
description: Send money to Fyatu account holders
- name: Cardholders
description: Cardholder management for card issuing programs
- name: Cards
description: Issue, fund, freeze, and manage virtual cards
- name: Webhooks
description: Webhook configuration and management
paths:
/cards/{cardId}/unload:
post:
tags:
- Cards
summary: Unload Card
description: Withdraw funds from a card back to your business wallet.
operationId: unloadCard
parameters:
- name: cardId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UnloadCardRequest'
example:
amount: 25
reference: withdraw-67890
responses:
'200':
description: Funds unloaded successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CardUnloadResponse'
example:
success: true
status: 200
message: Card unloaded successfully
data:
cardId: crd_8f3a2b1c4d5e6f7890abcdef12345678
amountUnloaded: 25
fee: 0.25
amountCredited: 24.75
reference: withdraw-67890
meta:
requestId: req_a1b2c3d4e5f6
timestamp: '2026-01-17T10:00:00+00:00'
'400':
description: Card cannot be unloaded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
card_not_active:
summary: Card is not active
value:
success: false
status: 400
message: 'Card is not active. Current status: FROZEN'
error:
code: CARD_NOT_ACTIVE
insufficient_card_balance:
summary: Insufficient card balance
value:
success: false
status: 400
message: 'Insufficient card balance. Available: $20.00'
error:
code: INSUFFICIENT_CARD_BALANCE
card_frozen:
summary: Card is frozen at bank partner
value:
success: false
status: 400
message: Card is frozen
error:
code: CARD_FROZEN
card_terminated:
summary: Card has been terminated
value:
success: false
status: 400
message: Card has been terminated
error:
code: CARD_TERMINATED
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
description: Bank partner failed to unload card
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
status: 500
message: Bank partner failed to unload card
error:
code: UNLOAD_FAILED
security:
- BearerAuth: []
components:
schemas:
UnloadCardRequest:
type: object
required:
- amount
properties:
amount:
type: number
description: Amount to unload in USD
reference:
type: string
maxLength: 100
description: >-
Your unique reference for this operation. Defaults to cardId if not
provided.
CardUnloadResponse:
type: object
properties:
success:
type: boolean
example: true
status:
type: integer
example: 200
message:
type: string
data:
type: object
properties:
cardId:
type: string
description: The card ID
amountUnloaded:
type: number
description: Amount unloaded from the card
fee:
type: number
description: Unloading fee charged
amountCredited:
type: number
description: Net amount credited to wallet after fee
reference:
type: string
description: Your external reference for this transaction
meta:
$ref: '#/components/schemas/Meta'
ErrorResponse:
type: object
properties:
success:
type: boolean
example: false
status:
type: integer
example: 401
message:
type: string
example: Invalid credentials
error:
$ref: '#/components/schemas/Error'
meta:
$ref: '#/components/schemas/Meta'
Meta:
type: object
properties:
requestId:
type: string
description: Unique request ID for tracking
example: req_abc123def456
timestamp:
type: string
format: date-time
description: ISO 8601 timestamp of the response
Error:
type: object
properties:
code:
type: string
description: Error code for programmatic handling
example: AUTH_INVALID_CREDENTIALS
details:
type: array
items:
$ref: '#/components/schemas/ValidationError'
description: Validation error details (for VALIDATION_ERROR)
ValidationError:
type: object
properties:
field:
type: string
description: Field that failed validation
example: appId
message:
type: string
description: Validation error message
example: AppId is required
responses:
Unauthorized:
description: Authentication required or token invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
status: 401
message: Unable to identify business
error:
code: AUTH_TOKEN_INVALID
meta:
requestId: req_abc123
timestamp: '2026-01-05T10:30:00+00:00'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
status: 404
message: Wallet not found
error:
code: RESOURCE_NOT_FOUND
meta:
requestId: req_abc123
timestamp: '2026-01-05T10:30:00+00:00'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT access token obtained from /auth/token
````