Create Deposit

Create a new deposit transaction for your customer.

POST/v1/deposit

Creates a new deposit transaction and returns a checkout URL for the customer.

Description

Use this endpoint to create a new deposit transaction. After creating the transaction, redirect your customer to the checkout URL where they can complete the payment.

Important

Transactions expire after 30 minutes. Make sure your customer completes the payment before the expiration time.

Request Body

Name	Type	Required	Description
`processId`	string	Required	Your unique transaction identifier (max 50 characters)
`amount`	number	Required	Transaction amount in the smallest currency unit
`currency`	string	Optional	Currency code (default: TRY)
`bankCode`	string	Optional	Bank code from available-banks endpoint
`customer.id`	string	Required	Your customer's unique identifier
`customer.name`	string	Required	Customer's full name
`customer.username`	string	Required	Customer's username
`callbackUrl`	string	Optional	URL to receive transaction status updates (overrides site default)
`metadata`	object	Optional	Additional data to attach to the transaction

Request Example

cURL

curl -X POST "https://<service_name>.api.wiapay.co/v1/deposit" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_abc123..." \
  -H "X-Signature: a1b2c3d4e5f6..." \
  -H "X-Timestamp: 1705320000" \
  -d '{
    "processId": "ORDER-12345",
    "amount": 1000,
    "currency": "TRY",
    "bankCode": "5fe0f093bb4f0b001b5ea63d",
    "customer": {
      "id": "user-123",
      "name": "Ahmet Yilmaz",
      "username": "ahmetyilmaz"
    }
  }'

JavaScript

const createDeposit = async () => {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const body = {
    processId: 'ORDER-12345',
    amount: 1000,
    currency: 'TRY',
    bankCode: '5fe0f093bb4f0b001b5ea63d',
    customer: {
      id: 'user-123',
      name: 'Ahmet Yilmaz',
      username: 'ahmetyilmaz'
    }
  };

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

  const response = await fetch(
    'https://<service_name>.api.wiapay.co/v1/deposit',
    {
      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();

  if (data.success) {
    // Redirect customer to checkout
    window.location.href = data.data.checkoutUrl;
  }
};

Response

Success Response (201 Created)

{
  "success": true,
  "data": {
    "transactionId": "674abc123def456789012345",
    "processId": "ORDER-12345",
    "amount": 1000,
    "currency": "TRY",
    "status": "pending",
    "assignedAccount": {
      "bankName": "Ziraat Bankasi",
      "accountName": "WIAPAY ODEME HIZMETLERI",
      "iban": "TR12 0001 0012 3456 7890 1234 56"
    },
    "checkoutUrl": "https://pay.wiapay.co/pay/674abc123def456789012345?token=...",
    "expiresAt": "2024-01-15T12:30:00.000Z",
    "createdAt": "2024-01-15T12:00:00.000Z"
  },
  "timestamp": 1705320000
}

Response Fields

Field	Type	Description
`transactionId`	string	WiaPay's unique transaction identifier
`processId`	string	Your transaction identifier (echoed back)
`amount`	number	Confirmed transaction amount
`currency`	string	Transaction currency
`status`	string	Current transaction status
`assignedAccount`	object	Bank account details for the deposit (if assigned)
`checkoutUrl`	string	URL to redirect customer for payment
`expiresAt`	string	Transaction expiration timestamp
`createdAt`	string	Transaction creation timestamp

Transaction Flow

Create Transaction

Create a deposit transaction using this API endpoint

Redirect Customer

Redirect your customer to the checkout URL from the response

Customer Makes Payment

Customer completes the payment on the checkout page

Payment Confirmed

You receive a callback with the final transaction status

Error Responses

400 Bad Request - Validation Error

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

400 Bad Request - Duplicate Transaction

{
  "success": false,
  "error": {
    "code": "DUPLICATE_TRANSACTION",
    "message": "Transaction with this processId already exists"
  },
  "timestamp": 1705320000
}

400 Bad Request - Amount Out of Range

{
  "success": false,
  "error": {
    "code": "AMOUNT_OUT_OF_RANGE",
    "message": "Amount must be between 100 and 50000 TRY for this bank"
  },
  "timestamp": 1705320000
}