Create Withdrawal

Create a new withdrawal transaction to send funds to your customer.

POST/v1/withdraw

Creates a new withdrawal transaction to transfer funds to a customer's bank account.

Description

Use this endpoint to create a withdrawal (payout) request. The funds will be transferred to the customer's bank account specified in the request. You'll receive a callback when the transaction status changes.

IP Whitelist Required

Withdrawal requests are only accepted from whitelisted IP addresses. Make sure your server IP is registered with WiaPay before making withdrawal requests.

Request Body Parameters

Name	Type	Required	Description
`processId`	string	Required	Unique transaction ID in your system
`amount`	number	Required	Withdrawal amount (positive number)
`bankId`	string	Optional	Bank ID from available-banks endpoint
`accountName`	string	Required	Recipient's bank account holder name
`iban`	string	Required	Recipient's IBAN number
`userId`	string	Required	Customer ID in your system
`userName`	string	Required	Customer username
`name`	string	Required	Customer full name

Request Example

cURL

curl -X POST "https://<service_name>.api.wiapay.co/v1/withdraw" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_abc123..." \
  -H "X-Signature: a1b2c3d4e5f6..." \
  -H "X-Timestamp: 1705320000" \
  -d '{
    "processId": "WITHDRAW-12345",
    "amount": 5000,
    "bankId": "5fe0f093bb4f0b001b5ea63d",
    "accountName": "AHMET YILMAZ",
    "iban": "TR330006100519786457841326",
    "userId": "user-123",
    "userName": "ahmetyilmaz",
    "name": "Ahmet Yilmaz"
  }'

JavaScript

const createWithdrawal = async () => {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const body = {
    processId: 'WITHDRAW-12345',
    amount: 5000,
    bankId: '5fe0f093bb4f0b001b5ea63d',
    accountName: 'AHMET YILMAZ',
    iban: 'TR330006100519786457841326',
    userId: 'user-123',
    userName: 'ahmetyilmaz',
    name: 'Ahmet Yilmaz'
  };

  const signature = generateSignature(
    API_SECRET,
    timestamp,
    'POST',
    '/v1/withdraw',
    JSON.stringify(body)
  );

  const response = await fetch(
    'https://<service_name>.api.wiapay.co/v1/withdraw',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY,
        'X-Signature': signature,
        'X-Timestamp': timestamp
      },
      body: JSON.stringify(body)
    }
  );

  const data = await response.json();
  console.log('Withdrawal created:', data);
};

Response

Success Response (201 Created)

{
  "success": true,
  "data": {
    "transactionId": "674xyz789abc123456789012",
    "processId": "WITHDRAW-12345",
    "amount": 5000,
    "currency": "TRY",
    "status": "pending",
    "createdAt": "2024-01-15T12:00:00.000Z"
  },
  "timestamp": 1705320000
}

Response Fields

Field	Type	Description
`transactionId`	string	WiaPay internal transaction ID (MongoDB ObjectId)
`processId`	string	Your transaction ID (displayed in frontend)
`amount`	number	Withdrawal amount
`currency`	string	Currency code
`status`	string	Transaction status (pending, processing, completed, failed)
`createdAt`	string	Transaction creation time (ISO 8601)

Transaction Status Flow

pending

Withdrawal request created and queued for processing.

processing

Bank transfer is being processed.

completed

Funds have been successfully transferred to the recipient.

failed

Transfer failed. Check failureReason in the callback for details.

IBAN Format

Turkish IBANs must be 26 characters long and start with "TR".
TR330006100519786457841326

Error Responses

400 Bad Request - Validation Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "processId and amount are required"
  },
  "timestamp": 1705320000
}

400 Bad Request - Invalid IBAN

{
  "success": false,
  "error": {
    "code": "INVALID_IBAN",
    "message": "Invalid IBAN format"
  },
  "timestamp": 1705320000
}

403 Forbidden - IP Not Authorized

{
  "success": false,
  "error": {
    "code": "IP_NOT_WHITELISTED",
    "message": "Your IP address is not authorized for withdrawal requests"
  },
  "timestamp": 1705320000
}

400 Bad Request - Insufficient Balance

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance for this withdrawal"
  },
  "timestamp": 1705320000
}