DefPay API Documentation

# DefPay API Reference

**Base Environment URL:**
`https://api.defpay.online`

*(Note: Throughout this documentation, `{{BASE_URL}}` represents the base environment URL above)*

**🤖 For AI Agents & LLMs:**
You can access a raw markdown version of this documentation specifically optimized for AI consumption here: 
[https://api.defpay.online/docs/ai](https://api.defpay.online/docs/ai)

---

## 💳 Payment API Documentation

### 🔐 Authentication

All endpoints require the following header:

`api-token: <YOUR_API_TOKEN>`

---

## 📥 PAYIN: Initiate Payment

**Endpoint:**
`POST {{BASE_URL}}/api/payments/initiate`

**Request Headers:**

| Key | Value |
|---|---|
| api-token | your API token |

**Request Body (JSON):**

```json
{
  "amount": "101",
  "orderId": "ORDER12345",
  "customer_name": "customer",
  "customer_mobile": "9876543211",
  "customer_email": "demo@gmiail.com",
  "note": "wallet recharge"
}
```

**Success Response:**

```json
{
  "success": true,
  "message": "Payment initiated successfully",
  "data": {
    "success": true,
    "transaction_id": "CUST1750759089093opxzzeau2",
    "payment_url": "{{BASE_URL}}/payment?orderId=CUST1750759089093opxzzeau2",
    "order_id": "gdyty6456",
    "amount": "101",
    "gateway_type":"intent",
    "upiString": "upi://pay?pa=Intent-MORS82@mairtel&pn=MORSOFTTECHNOLOGYPRIVATELIMITED&mc=5691&tr=829522406250319125&cu=INR&am=101.0&mam=101.0&mode=01&purpose=00&orgId=000000",
    "timestamp": "2025-06-24T09:58:14.432Z"
  }
}
```

**Failure Response:**

```json
{
  "success": false,
  "message": "Something went wrong",
  "data": {
    "success": false,
    "error": {
      "message": "Duplicate Order Id",
      "code": "UNKNOWN_ERROR",
      "timestamp": "2025-06-24T11:37:25.300Z"
    }
  }
}
```

The `gateway_type` field can have one of the following values:

*   **intent** – Use the upiString to launch the UPI intent and open the user’s preferred payment application.
*   **webpage** – Redirect the user to the payment URL provided by the gateway.
*   **upi** – Use the upiString to initiate the payment. After the payment is completed, update the DefPay transaction status accordingly.

---

## 📤 PAYOUT: Initiate Payout

**Endpoint:**
`POST {{BASE_URL}}/api/payout/initiate`

**Request Headers:**

| Key | Value |
|---|---|
| api-token | your API token |

**Request Body (JSON):**

```json
{
  "payout_id": "PAYOUT12345",
  "amount": "100",
  "bank_name": "icici bank",
  "account_number": "1234567890",
  "ifsc_code": "ICIC0001234",
  "account_holder_name": "ravi"
}
```

**Response:**

```json
{
    "success": true,
    "message": "Payment initiated successfully",
    "data": {
        "status": true,
        "payout_id": "test76543534",
        "bankId": "TESTN45435434543543534",
        "bankStatus": "PENDING",
        "amount": "100",
        "message": "Transaction initiated Successfully",
        "timestamp": "2025-08-24T06:38:52.771Z"
    }
}
```

---

## 🔁 Webhook Events

Your system should listen for incoming webhook POSTs for both PAYIN and PAYOUT updates.

**PAYIN Webhook:**

```json
{
  "event_type": "PAYIN",
  "data": {
    "order_id": "HJU84747",
    "status": "success", // success or failed
    "amount": "100",
    "urn_number": "9876543210"
  }
}
```

**PAYOUT Webhook:**

```json
{
  "event_type": "PAYOUT",
  "data": {
    "payout_id": "HJU84747",
    "status": "success", // success or failed or processing
    "amount": "100",
    "bank_status": "pending",
    "message": "Payout successful",
    "txn_id": "TXN1234567890"
  }
}
```

---

## 🔁 Payment status check

### Check Payin Status by Order ID

**Endpoint:**
`GET {{BASE_URL}}/api/payments/status?order_id=ORDER12345`

```bash
curl -X GET "{{BASE_URL}}/api/payments/status?order_id=ORDER12345" \
  -H "api-token: your_api_token_here"
```

### Check Payout Status

**Endpoint:**
`GET {{BASE_URL}}/api/payout/status?payout_id=ORDER12345`

```bash
curl -X GET "{{BASE_URL}}/api/payout/status?payout_id=PAYOUT12345" \
  -H "api-token: your_api_token_here"
```