> ## 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 Deposit Transaction

> Creates a new deposit transaction for customer account funding. Supports various payment methods including cryptocurrencies, e-wallets, and BNPL services.

## Overview

The deposit endpoint creates a new transaction for customer account funding. It supports multiple payment methods including cryptocurrencies, e-wallets, and BNPL services.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.orsunpay.com/v1/payment/sale" \
    -H "x-api-key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 1000,
      "currency": "USD",
      "paymentMethod": "cr_clyv2goxb0000z8b8j5y6fl1j",
      "merchantId": "mr_clyv2goxb0000z8b8j5y6fl1j",
      "orderId": "transaction_123",
      "buyerId": "customer_123",
      "successUrl": "https://example.com/success",
      "failureUrl": "https://example.com/failure",
      "returnUrl": "https://example.com/return",
      "callbackUrl": "https://example.com/callback"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.orsunpay.com/v1/payment/sale", {
    method: "POST",
    headers: {
      "x-api-key": "your-api-key-here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 1000,
      currency: "USD",
      paymentMethod: "cr_clyv2goxb0000z8b8j5y6fl1j",
      merchantId: "mr_clyv2goxb0000z8b8j5y6fl1j",
      orderId: "transaction_123",
      buyerId: "customer_123",
      successUrl: "https://example.com/success",
      failureUrl: "https://example.com/failure",
      returnUrl: "https://example.com/return",
      callbackUrl: "https://example.com/callback",
    }),
  });

  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/sale',
      headers={
          'x-api-key': 'your-api-key-here',
          'Content-Type': 'application/json'
      },
      json={
          'amount': 1000,
          'currency': 'USD',
          'paymentMethod': 'cr_clyv2goxb0000z8b8j5y6fl1j',
          'merchantId': 'mr_clyv2goxb0000z8b8j5y6fl1j',
          'orderId': 'transaction_123',
          'buyerId': 'customer_123',
          'successUrl': 'https://example.com/success',
          'failureUrl': 'https://example.com/failure',
          'returnUrl': 'https://example.com/return',
          'callbackUrl': 'https://example.com/callback'
      }
  )

  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $data = [
      'amount' => 1000,
      'currency' => 'USD',
      'paymentMethod' => 'cr_clyv2goxb0000z8b8j5y6fl1j',
      'merchantId' => 'mr_clyv2goxb0000z8b8j5y6fl1j',
      'orderId' => 'transaction_123',
      'buyerId' => 'customer_123',
      'successUrl' => 'https://example.com/success',
      'failureUrl' => 'https://example.com/failure',
      'returnUrl' => 'https://example.com/return',
      'callbackUrl' => 'https://example.com/callback'
  ];

  $ch = curl_init('https://api.orsunpay.com/v1/payment/sale');
  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": 1000,
          "currency": "USD",
          "paymentMethod": "cr_clyv2goxb0000z8b8j5y6fl1j",
          "merchantId": "mr_clyv2goxb0000z8b8j5y6fl1j",
          "orderId": "transaction_123",
          "buyerId": "customer_123",
          "successUrl": "https://example.com/success",
          "failureUrl": "https://example.com/failure",
          "returnUrl": "https://example.com/return",
          "callbackUrl": "https://example.com/callback",
      }

      jsonData, _ := json.Marshal(data)

      req, _ := http.NewRequest("POST", "https://api.orsunpay.com/v1/payment/sale", 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/sale')
  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: 1000,
    currency: 'USD',
    paymentMethod: 'cr_clyv2goxb0000z8b8j5y6fl1j',
    merchantId: 'mr_clyv2goxb0000z8b8j5y6fl1j',
    orderId: 'transaction_123',
    buyerId: 'customer_123',
    successUrl: 'https://example.com/success',
    failureUrl: 'https://example.com/failure',
    returnUrl: 'https://example.com/return',
    callbackUrl: 'https://example.com/callback'
  }.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 CreateDeposit {
      public static void main(String[] args) throws Exception {
          String json = """
          {
              "amount": 1000,
              "currency": "USD",
              "paymentMethod": "cr_clyv2goxb0000z8b8j5y6fl1j",
              "merchantId": "mr_clyv2goxb0000z8b8j5y6fl1j",
              "orderId": "transaction_123",
              "buyerId": "customer_123",
              "successUrl": "https://example.com/success",
              "failureUrl": "https://example.com/failure",
              "returnUrl": "https://example.com/return",
              "callbackUrl": "https://example.com/callback"
          }
          """;

          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create("https://api.orsunpay.com/v1/payment/sale"))
              .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 = 1000,
              currency = "USD",
              paymentMethod = "cr_clyv2goxb0000z8b8j5y6fl1j",
              merchantId = "mr_clyv2goxb0000z8b8j5y6fl1j",
              orderId = "transaction_123",
              buyerId = "customer_123",
              successUrl = "https://example.com/success",
              failureUrl = "https://example.com/failure",
              returnUrl = "https://example.com/return",
              callbackUrl = "https://example.com/callback"
          };

          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/sale", content);

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

<ResponseExample>
  ```json Success with Redirect theme={null}
  {
    "status": true,
    "url": "https://payment-provider.com/pay/abc123",
    "transaction": {
      "id": "tx_clyv2goxb0000z8b8j5y6fl1j",
      "orderId": "transaction_123",
      "status": "PROCESSING",
      "action": "SALE",
      "amount": 1000,
      "currency": "USD",
      "createdAt": "2023-12-25T10:00:00.000Z"
    }
  }
  ```

  ```json Success Direct Payment theme={null}
  {
    "status": true,
    "transaction": {
      "id": "tx_direct_001",
      "orderId": "order_789",
      "status": "SUCCESS",
      "action": "SALE",
      "amount": 500,
      "currency": "USD",
      "createdAt": "2023-12-25T10:00:00.000Z"
    }
  }
  ```

  ```json Error Response theme={null}
  {
    "status": false,
    "error": "Invalid payment method"
  }
  ```
</ResponseExample>

## Payment Flow

1. **Create Transaction** - Call this endpoint to initiate a deposit
2. **Redirect Customer** - If `url` is provided, redirect customer to complete payment
3. **Handle Callback** - Process webhook notifications at your `callbackUrl`
4. **Redirect Customer** - Customer returns to `successUrl` or `failureUrl`

<Tip>
  Always handle webhook notifications for reliable payment status updates, as
  customers may not complete the redirect flow.
</Tip>

## Common Use Cases

### Basic Deposit

Perfect for simple payment processing with minimal customer data required.

### Deposit with Customer Information

Include customer details for enhanced fraud protection and compliance requirements.

### Recurring Payments

Use metadata field to store subscription or recurring payment information.

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


## OpenAPI

````yaml POST /payment/sale
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/sale:
    post:
      tags:
        - Payments
      summary: Create deposit transaction
      description: >-
        Creates a new deposit transaction for customer account funding. Supports
        various payment methods including cryptocurrencies, e-wallets, and BNPL
        services.
      operationId: createDeposit
      requestBody:
        description: Deposit transaction details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DepositRequest'
            examples:
              basic_deposit:
                summary: Basic deposit example
                value:
                  amount: 1000
                  currency: USD
                  paymentMethod: cr_clyv2goxb0000z8b8j5y6fl1j
                  merchantId: mr_clyv2goxb0000z8b8j5y6fl1j
                  orderId: transaction_123
                  buyerId: customer_123
                  successUrl: https://example.com/success
                  failureUrl: https://example.com/failure
                  returnUrl: https://example.com/return
                  callbackUrl: https://example.com/callback
              with_customer_info:
                summary: Deposit with customer information
                value:
                  amount: 2500
                  currency: EUR
                  paymentMethod: cr_ewallet_001
                  merchantId: mr_clyv2goxb0000z8b8j5y6fl1j
                  orderId: order_456
                  buyerId: customer_456
                  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
                    phone: '+1234567890'
                    address: 123 Main St
                    city: New York
                    country: US
                    zip: '10001'
                  locale: en-US
      responses:
        '201':
          description: Deposit transaction successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
              examples:
                success_with_redirect:
                  summary: Success with redirect URL
                  value:
                    status: true
                    url: https://payment-provider.com/pay/abc123
                    transaction:
                      id: tx_clyv2goxb0000z8b8j5y6fl1j
                      orderId: transaction_123
                      status: PROCESSING
                      action: SALE
                      amount: 1000
                      currency: USD
                      createdAt: '2023-12-25T10:00:00.000Z'
                success_direct:
                  summary: Success without redirect
                  value:
                    status: true
                    transaction:
                      id: tx_direct_001
                      orderId: order_789
                      status: SUCCESS
                      action: SALE
                      amount: 500
                      currency: USD
                      createdAt: '2023-12-25T10:00:00.000Z'
        '400':
          description: Invalid request data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_payment_method:
                  summary: Invalid payment method
                  value:
                    status: false
                    error: Invalid payment method
        '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:
    DepositRequest:
      type: object
      required:
        - amount
        - currency
        - paymentMethod
        - merchantId
        - orderId
        - buyerId
        - successUrl
        - failureUrl
        - returnUrl
        - callbackUrl
      properties:
        amount:
          type: integer
          description: Transaction amount in cents
          minimum: 1
          example: 1000
        currency:
          type: string
          description: Three-letter currency code (ISO 4217)
          pattern: ^[A-Z]{3}$
          example: USD
        paymentMethod:
          type: string
          description: Payment method identifier
          example: cr_clyv2goxb0000z8b8j5y6fl1j
        merchantId:
          type: string
          description: Merchant account identifier
          example: mr_clyv2goxb0000z8b8j5y6fl1j
        orderId:
          type: string
          description: Unique transaction identifier in your system
          example: transaction_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 payment
          example: https://example.com/success
        failureUrl:
          type: string
          format: uri
          description: URL to redirect customer after failed payment
          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 payment status notifications
          example: https://example.com/callback
        locale:
          type: string
          description: Language/locale in BCP 47 format
          example: en-US
        customer:
          $ref: '#/components/schemas/Customer'
        paymentMethodInput:
          type: object
          description: Additional payment method specific parameters
          additionalProperties: true
        metadata:
          type: object
          description: Additional metadata for the transaction
          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
    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'
    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'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for merchant authorization

````