> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orsunpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Withdrawal Transaction

> Creates a new transaction for withdrawing funds to customers. Supports various withdrawal methods including bank transfers, e-wallets, and cryptocurrencies.

## Overview

The withdrawal endpoint creates a new transaction for withdrawing funds to customers. It supports multiple payout methods including bank transfers, e-wallets, and cryptocurrencies.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.orsunpay.com/v1/payment/payout" \
    -H "x-api-key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 5000,
      "currency": "USD",
      "paymentMethod": "bank_transfer_001",
      "merchantId": "mr_clyv2goxb0000z8b8j5y6fl1j",
      "orderId": "payout_123",
      "buyerId": "customer_123",
      "successUrl": "https://example.com/success",
      "failureUrl": "https://example.com/failure",
      "returnUrl": "https://example.com/return",
      "callbackUrl": "https://example.com/callback",
      "customer": {
        "email": "john.doe@example.com",
        "firstName": "John",
        "lastName": "Doe"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.orsunpay.com/v1/payment/payout", {
    method: "POST",
    headers: {
      "x-api-key": "your-api-key-here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 5000,
      currency: "USD",
      paymentMethod: "bank_transfer_001",
      merchantId: "mr_clyv2goxb0000z8b8j5y6fl1j",
      orderId: "payout_123",
      buyerId: "customer_123",
      successUrl: "https://example.com/success",
      failureUrl: "https://example.com/failure",
      returnUrl: "https://example.com/return",
      callbackUrl: "https://example.com/callback",
      customer: {
        email: "john.doe@example.com",
        firstName: "John",
        lastName: "Doe",
      },
    }),
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests
  import json

  response = requests.post(
      'https://api.orsunpay.com/v1/payment/payout',
      headers={
          'x-api-key': 'your-api-key-here',
          'Content-Type': 'application/json'
      },
      json={
          'amount': 5000,
          'currency': 'USD',
          'paymentMethod': 'bank_transfer_001',
          'merchantId': 'mr_clyv2goxb0000z8b8j5y6fl1j',
          'orderId': 'payout_123',
          'buyerId': 'customer_123',
          'successUrl': 'https://example.com/success',
          'failureUrl': 'https://example.com/failure',
          'returnUrl': 'https://example.com/return',
          'callbackUrl': 'https://example.com/callback',
          'customer': {
              'email': 'john.doe@example.com',
              'firstName': 'John',
              'lastName': 'Doe'
          }
      }
  )

  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $data = [
      'amount' => 5000,
      'currency' => 'USD',
      'paymentMethod' => 'bank_transfer_001',
      'merchantId' => 'mr_clyv2goxb0000z8b8j5y6fl1j',
      'orderId' => 'payout_123',
      'buyerId' => 'customer_123',
      'successUrl' => 'https://example.com/success',
      'failureUrl' => 'https://example.com/failure',
      'returnUrl' => 'https://example.com/return',
      'callbackUrl' => 'https://example.com/callback',
      'customer' => [
          'email' => 'john.doe@example.com',
          'firstName' => 'John',
          'lastName' => 'Doe'
      ]
  ];

  $ch = curl_init('https://api.orsunpay.com/v1/payment/payout');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'x-api-key: your-api-key-here',
      'Content-Type: application/json',
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  echo $response;
  ?>
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      data := map[string]interface{}{
          "amount": 5000,
          "currency": "USD",
          "paymentMethod": "bank_transfer_001",
          "merchantId": "mr_clyv2goxb0000z8b8j5y6fl1j",
          "orderId": "payout_123",
          "buyerId": "customer_123",
          "successUrl": "https://example.com/success",
          "failureUrl": "https://example.com/failure",
          "returnUrl": "https://example.com/return",
          "callbackUrl": "https://example.com/callback",
          "customer": map[string]string{
              "email": "john.doe@example.com",
              "firstName": "John",
              "lastName": "Doe",
          },
      }

      jsonData, _ := json.Marshal(data)

      req, _ := http.NewRequest("POST", "https://api.orsunpay.com/v1/payment/payout", bytes.NewBuffer(jsonData))
      req.Header.Set("x-api-key", "your-api-key-here")
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      var result map[string]interface{}
      json.NewDecoder(resp.Body).Decode(&result)
      fmt.Println(result)
  }
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'

  uri = URI('https://api.orsunpay.com/v1/payment/payout')
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request['x-api-key'] = 'your-api-key-here'
  request['Content-Type'] = 'application/json'
  request.body = {
    amount: 5000,
    currency: 'USD',
    paymentMethod: 'bank_transfer_001',
    merchantId: 'mr_clyv2goxb0000z8b8j5y6fl1j',
    orderId: 'payout_123',
    buyerId: 'customer_123',
    successUrl: 'https://example.com/success',
    failureUrl: 'https://example.com/failure',
    returnUrl: 'https://example.com/return',
    callbackUrl: 'https://example.com/callback',
    customer: {
      email: 'john.doe@example.com',
      firstName: 'John',
      lastName: 'Doe'
    }
  }.to_json

  response = http.request(request)
  puts response.body
  ```

  ```java Java theme={null}
  import java.io.*;
  import java.net.http.*;
  import java.net.URI;

  public class CreateWithdrawal {
      public static void main(String[] args) throws Exception {
          String json = """
          {
              "amount": 5000,
              "currency": "USD",
              "paymentMethod": "bank_transfer_001",
              "merchantId": "mr_clyv2goxb0000z8b8j5y6fl1j",
              "orderId": "payout_123",
              "buyerId": "customer_123",
              "successUrl": "https://example.com/success",
              "failureUrl": "https://example.com/failure",
              "returnUrl": "https://example.com/return",
              "callbackUrl": "https://example.com/callback",
              "customer": {
                  "email": "john.doe@example.com",
                  "firstName": "John",
                  "lastName": "Doe"
              }
          }
          """;

          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create("https://api.orsunpay.com/v1/payment/payout"))
              .header("x-api-key", "your-api-key-here")
              .header("Content-Type", "application/json")
              .POST(HttpRequest.BodyPublishers.ofString(json))
              .build();

          HttpClient client = HttpClient.newHttpClient();
          HttpResponse<String> response = client.send(request,
              HttpResponse.BodyHandlers.ofString());

          System.out.println(response.body());
      }
  }
  ```

  ```csharp C# theme={null}
  using System;
  using System.Net.Http;
  using System.Text;
  using System.Threading.Tasks;
  using Newtonsoft.Json;

  class Program
  {
      private static readonly HttpClient client = new HttpClient();

      static async Task Main()
      {
          var data = new
          {
              amount = 5000,
              currency = "USD",
              paymentMethod = "bank_transfer_001",
              merchantId = "mr_clyv2goxb0000z8b8j5y6fl1j",
              orderId = "payout_123",
              buyerId = "customer_123",
              successUrl = "https://example.com/success",
              failureUrl = "https://example.com/failure",
              returnUrl = "https://example.com/return",
              callbackUrl = "https://example.com/callback",
              customer = new
              {
                  email = "john.doe@example.com",
                  firstName = "John",
                  lastName = "Doe"
              }
          };

          string json = JsonConvert.SerializeObject(data);
          var content = new StringContent(json, Encoding.UTF8, "application/json");

          client.DefaultRequestHeaders.Add("x-api-key", "your-api-key-here");

          HttpResponseMessage response = await client.PostAsync(
              "https://api.orsunpay.com/v1/payment/payout", content);

          string responseBody = await response.Content.ReadAsStringAsync();
          Console.WriteLine(responseBody);
      }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "status": true,
    "transaction": {
      "id": "tx_payout_001",
      "orderId": "payout_123",
      "status": "PROCESSING",
      "action": "PAYOUT",
      "amount": 5000,
      "currency": "USD",
      "createdAt": "2023-12-25T10:00:00.000Z"
    }
  }
  ```

  ```json Error Response - Insufficient Balance theme={null}
  {
    "status": false,
    "error": "Insufficient balance"
  }
  ```

  ```json Error Response - KYC Required theme={null}
  {
    "status": false,
    "error": "KYC verification required"
  }
  ```
</ResponseExample>

## Withdrawal Flow

1. **Verify Balance** - Ensure customer has sufficient funds
2. **Create Withdrawal** - Call this endpoint to initiate a payout
3. **Additional Verification** - Some methods may require additional customer verification
4. **Processing** - Withdrawal is processed by the payment provider
5. **Completion** - Funds are transferred to customer's account
6. **Webhook Notification** - Receive status updates via webhook

## Processing Times

| Method             | Typical Processing Time |
| ------------------ | ----------------------- |
| Bank Transfer      | 1-3 business days       |
| E-wallets          | Minutes to hours        |
| Cryptocurrency     | 10-60 minutes           |
| International Wire | 3-5 business days       |

<Warning>
  Withdrawal processing times may vary based on the payment provider,
  destination country, and verification requirements.
</Warning>

## Common Use Cases

### Standard Bank Withdrawal

Most common withdrawal method with standard processing times and KYC requirements.

### Cryptocurrency Payout

Fast withdrawals for crypto-enabled customers with wallet address verification.

### E-wallet Transfer

Quick transfers to digital wallets like PayPal, Skrill, or Neteller.

## Important Considerations

### KYC Requirements

* Customer identity verification may be required
* Higher amounts typically require additional documentation
* Some jurisdictions have specific compliance requirements

### Daily Limits

* Withdrawal limits may apply per customer
* Limits can be increased with enhanced verification
* Business accounts may have higher limits

### Anti-Money Laundering (AML)

* Large transactions may require additional screening
* Suspicious activity may trigger manual review
* Source of funds verification may be required

<Tip>
  Always implement webhook handling for accurate withdrawal status tracking, as
  processing times can vary significantly.
</Tip>

<Warning>
  Ensure your webhook endpoint can handle duplicate notifications and implement
  proper idempotency checks for withdrawal processing.
</Warning>


## OpenAPI

````yaml POST /payment/payout
openapi: 3.1.0
info:
  title: Payment Gateway API
  description: Comprehensive payment gateway API for processing deposits and withdrawals
  version: 1.0.0
  contact:
    name: API Support
    email: api-support@orsunpay.com
servers:
  - url: https://api.orsunpay.com/v1
    description: Production server
  - url: https://api-sandbox.orsunpay.com/v1
    description: Sandbox server
security:
  - ApiKeyAuth: []
paths:
  /payment/payout:
    post:
      tags:
        - Payments
      summary: Create withdrawal transaction
      description: >-
        Creates a new transaction for withdrawing funds to customers. Supports
        various withdrawal methods including bank transfers, e-wallets, and
        cryptocurrencies.
      operationId: createWithdrawal
      requestBody:
        description: Withdrawal transaction details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawalRequest'
            examples:
              basic_withdrawal:
                summary: Basic withdrawal example
                value:
                  amount: 5000
                  currency: USD
                  paymentMethod: bank_transfer_001
                  merchantId: mr_clyv2goxb0000z8b8j5y6fl1j
                  orderId: payout_123
                  buyerId: customer_123
                  successUrl: https://example.com/success
                  failureUrl: https://example.com/failure
                  returnUrl: https://example.com/return
                  callbackUrl: https://example.com/callback
                  customer:
                    email: john.doe@example.com
                    firstName: John
                    lastName: Doe
              crypto_withdrawal:
                summary: Cryptocurrency withdrawal
                value:
                  amount: 10000
                  currency: USD
                  paymentMethod: crypto_btc_001
                  merchantId: mr_clyv2goxb0000z8b8j5y6fl1j
                  orderId: crypto_payout_456
                  buyerId: customer_crypto_789
                  successUrl: https://example.com/success
                  failureUrl: https://example.com/failure
                  returnUrl: https://example.com/return
                  callbackUrl: https://example.com/callback
                  customer:
                    email: crypto.user@example.com
                    firstName: Alice
                    lastName: Smith
                    phone: '+1987654321'
                  paymentMethodInput:
                    walletAddress: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
      responses:
        '201':
          description: Withdrawal transaction successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
              examples:
                success_withdrawal:
                  summary: Successful withdrawal creation
                  value:
                    status: true
                    transaction:
                      id: tx_payout_001
                      orderId: payout_123
                      status: PROCESSING
                      action: PAYOUT
                      amount: 5000
                      currency: USD
                      createdAt: '2023-12-25T10:00:00.000Z'
        '400':
          description: Invalid request data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                insufficient_balance:
                  summary: Insufficient balance
                  value:
                    status: false
                    error: Insufficient balance
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    WithdrawalRequest:
      type: object
      required:
        - amount
        - currency
        - paymentMethod
        - merchantId
        - orderId
        - buyerId
        - successUrl
        - failureUrl
        - returnUrl
        - callbackUrl
        - customer
      properties:
        amount:
          type: integer
          description: Withdrawal amount in cents
          minimum: 1
          example: 5000
        currency:
          type: string
          description: Three-letter currency code (ISO 4217)
          pattern: ^[A-Z]{3}$
          example: USD
        paymentMethod:
          type: string
          description: Payout method identifier
          example: bank_transfer_001
        merchantId:
          type: string
          description: Merchant account identifier
          example: mr_clyv2goxb0000z8b8j5y6fl1j
        orderId:
          type: string
          description: Unique withdrawal identifier in your system
          example: payout_123
        buyerId:
          type: string
          description: Customer identifier in your system
          example: customer_123
        successUrl:
          type: string
          format: uri
          description: URL to redirect customer after successful withdrawal initiation
          example: https://example.com/success
        failureUrl:
          type: string
          format: uri
          description: URL to redirect customer after failed withdrawal
          example: https://example.com/failure
        returnUrl:
          type: string
          format: uri
          description: URL to redirect customer when returning to your site
          example: https://example.com/return
        callbackUrl:
          type: string
          format: uri
          description: Webhook URL for withdrawal status notifications
          example: https://example.com/callback
        customer:
          $ref: '#/components/schemas/CustomerRequired'
        locale:
          type: string
          description: Language/locale in BCP 47 format
          example: en-US
        paymentMethodInput:
          type: object
          description: Additional payout method specific parameters
          additionalProperties: true
        metadata:
          type: object
          description: Additional metadata for the withdrawal
          additionalProperties: true
    PaymentResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: boolean
          description: Indicates if the request was successful
          example: true
        url:
          type: string
          format: uri
          description: Redirect URL for payment completion (if required)
          example: https://payment-provider.com/pay/abc123
        transaction:
          $ref: '#/components/schemas/Transaction'
        error:
          type: string
          description: Error message if the request failed
          example: Payment method not available
    ErrorResponse:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: boolean
          description: Request status (always false for errors)
          example: false
        error:
          type: string
          description: Error message describing what went wrong
          example: Invalid payment method
    UnauthorizedError:
      type: object
      properties:
        message:
          type: string
          description: Error message
          example: Invalid API key
    CustomerRequired:
      allOf:
        - $ref: '#/components/schemas/Customer'
      required:
        - email
        - firstName
        - lastName
    Transaction:
      type: object
      properties:
        id:
          type: string
          description: Unique transaction identifier
          example: tx_clyv2goxb0000z8b8j5y6fl1j
        orderId:
          type: string
          description: Your order/payout identifier
          example: transaction_123
        status:
          type: string
          enum:
            - CREATED
            - WAIT_APPROVE
            - PROCESSING
            - CANCELED
            - DECLINED
            - SUCCESS
            - EXPIRED
          description: Transaction status
          example: PROCESSING
        action:
          type: string
          enum:
            - SALE
            - PAYOUT
            - AUTHORIZE
            - REFUND
            - CHARGEBACK
          description: Transaction action type
          example: SALE
        amount:
          type: integer
          description: Transaction amount in cents
          example: 1000
        currency:
          type: string
          description: Transaction currency
          example: USD
        createdAt:
          type: string
          format: date-time
          description: Transaction creation timestamp
          example: '2023-12-25T10:00:00.000Z'
    Customer:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Customer email address
          example: john.doe@example.com
        phone:
          type: string
          description: Customer phone number
          example: '+1234567890'
        firstName:
          type: string
          description: Customer first name
          example: John
        lastName:
          type: string
          description: Customer last name
          example: Doe
        address:
          type: string
          description: Customer address
          example: 123 Main St
        address2:
          type: string
          description: Customer address line 2
          example: Apt 1
        city:
          type: string
          description: Customer city
          example: New York
        country:
          type: string
          description: Customer country code
          example: US
        state:
          type: string
          description: Customer state/province
          example: NY
        zip:
          type: string
          description: Customer postal code
          example: '10001'
        ip:
          type: string
          description: Customer IP address
          example: 192.168.1.1
        userAgent:
          type: string
          description: Customer user agent string
          example: Mozilla/5.0...
        dob:
          type: string
          format: date
          description: Customer date of birth
          example: '1990-01-01'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for merchant authorization

````