Fiat Withdrawal

Step 1: Create an External Bank Account

Use the Create External Account API to register the destination bank account where you want to send the USD withdrawal.

Step 2: Create a Fiat Withdrawal

Use the Create Withdrawal API to initiate a fiat withdrawal from your 1Money account to an external bank account. Note that the status of the external bank account must be in active in order to initiate withdrawal.

Example cURL:

curl -X POST \
  'https://api.1money.network/v1/withdrawals' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalId": "WD-20251006-0001",
    "amount": "1000.00",
    "currency": "USD",
    "destinationAccount": {
      "accountNumber": "9876543210",
      "routingNumber": "021000021",
      "accountHolderName": "John Doe",
      "bankName": "Example Bank"
    },
    "description": "Monthly payout",
    "callbackUrl": "https://your-app.com/webhooks/withdrawal"
  }'

Sample Response:

{
  "withdrawalId": "wd_789xyz123abc",
  "externalId": "WD-20251006-0001",
  "amount": "1000.00",
  "currency": "USD",
  "status": "PENDING",
  "createdAt": "2025-10-06T14:50:00Z",
  "destinationAccount": {
    "accountNumber": "****3210",
    "bankName": "Example Bank",
    "accountHolderName": "John Doe"
  },
  "estimatedSettlementDate": "2025-10-08T14:50:00Z"
}

The withdrawal is now queued for processing. Use the returned withdrawalId for tracking.

Step 3: Set Up Webhook Tracking

Configure a webhook endpoint to receive real-time updates about your withdrawal status.

Webhook Registration: https://developer.1money.com/reference/list_subscriptions#/

Sample Webhook Payload (Received at Your Endpoint) When the withdrawal status changes, 1Money will POST to your webhook URL:

{
  "eventType": "withdrawal.status_changed",
  "timestamp": "2025-10-06T15:30:00Z",
  "data": {
    "withdrawalId": "wd_789xyz123abc",
    "externalId": "WD-20251006-0001",
    "status": "PROCESSING",
    "amount": "1000.00",
    "currency": "USD",
    "previousStatus": "PENDING",
    "updatedAt": "2025-10-06T15:30:00Z"
  }
}

Possible Status Values:

Status	Description
PENDING	Withdrawal created, awaiting processing
PROCESSING	Being processed by banking partner
COMPLETED	Successfully sent to destination account
FAILED	Withdrawal failed (see reason field)
CANCELLED	Withdrawal cancelled by user/system

Step 4: Retrieve Withdrawal Status (Alternative/Backup Method)

If webhook notifications are not received, you can manually check withdrawal status.

Retrieve by Withdrawal ID:

curl -X GET \
  'https://api.1money.network/v1/withdrawals/wd_789xyz123abc' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

Retrieve by External ID

curl -X GET \
  'https://api.1money.network/v1/withdrawals/external/WD-20251006-0001' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

Sample Response (Current Status)

{
  "withdrawalId": "wd_789xyz123abc",
  "externalId": "WD-20251006-0001",
  "amount": "1000.00",
  "currency": "USD",
  "status": "COMPLETED",
  "createdAt": "2025-10-06T14:50:00Z",
  "completedAt": "2025-10-06T16:45:00Z",
  "destinationAccount": {
    "accountNumber": "****3210",
    "bankName": "Example Bank",
    "accountHolderName": "John Doe"
  },
  "transactionReference": "TXN123456789",
  "fees": {
    "amount": "5.00",
    "currency": "USD"
  }
}

Step 5: Handle Failed Withdrawals

If a withdrawal fails, the webhook and API responses will include failure details.

Failed Withdrawal Response Example

{
  "withdrawalId": "wd_789xyz123abc",
  "externalId": "WD-20251006-0001",
  "status": "FAILED",
  "failureReason": "INSUFFICIENT_FUNDS",
  "failureMessage": "Account balance insufficient for withdrawal amount plus fees",
  "amount": "1000.00",
  "currency": "USD",
  "createdAt": "2025-10-06T14:50:00Z",
  "failedAt": "2025-10-06T15:30:00Z"
}

Common Failure Reasons:

Error Code	Description
INSUFFICIENT_FUNDS	Not enough balance in account
INVALID_ACCOUNT	Destination account details invalid
COMPLIANCE_HOLD	Withdrawal blocked by compliance rules
BANK_REJECTION	Rejected by destination bank
SYSTEM_ERROR	Technical error, contact support

Step 6: List Historical Withdrawals

Retrieve a list of past withdrawals for reporting and reconciliation.

List All Withdrawals

curl -X GET \
  'https://api.1money.network/v1/withdrawals?limit=50&offset=0&status=COMPLETED' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

Sample Response

{
  "withdrawals": [
    {
      "withdrawalId": "wd_789xyz123abc",
      "externalId": "WD-20251006-0001", 
      "amount": "1000.00",
      "currency": "USD",
      "status": "COMPLETED",
      "createdAt": "2025-10-06T14:50:00Z",
      "completedAt": "2025-10-06T16:45:00Z"
    },
    {
      "withdrawalId": "wd_456def789ghi",
      "externalId": "WD-20251005-0003",
      "amount": "500.00", 
      "currency": "USD",
      "status": "COMPLETED",
      "createdAt": "2025-10-05T10:20:00Z",
      "completedAt": "2025-10-05T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Error Handling

Always implement proper error handling for withdrawal operations:

Common HTTP Status Codes:

HTTP Status Code	Description
200 OK	Request successful
400 Bad Request	Invalid parameters
401 Unauthorized	Invalid API key
403 Forbidden	Insufficient permissions
404 Not Found	Withdrawal not found
409 Conflict	Duplicate external ID
422 Unprocessable Entity	Validation errors
500 Internal Server Error	System error

Best Practices

Always use unique externalId values to prevent duplicate withdrawals
Implement webhook verification to ensure events come from 1Money
Store webhook payloads for audit trails and debugging
Handle webhook retries gracefully (return 2xx status codes)
Use polling as backup if webhooks fail or are delayed
Validate withdrawal limits before creating withdrawals
Monitor failed withdrawals and implement retry logic for transient failures