> For the complete documentation index, see [llms.txt](https://docs.skypaybd.top/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skypaybd.top/integration-and-api/create-payment.md).

# Create Payment

The **Create Payment** endpoint initiates a transaction session within the SkyPay Core Engine. SkyPay supports two operational modes:

1. **Version 1 (Hosted Checkout)**: Returns a secure checkout URL where customers complete payment on a responsive, hosted UI.
2. **Version 2 (Headless API)**: Returns payment credentials (MFS numbers, QR code assets, crypto wallet addresses, exchange rates) directly in JSON, enabling custom native in-app or chatbot payment screens.

***

## 1. Version 1 — Hosted Checkout Gateway (`/api/payment/create`)

Hosted checkout is ideal for web platforms, content management systems, and e-commerce stores (such as WooCommerce, WHMCS, and custom web portals) requiring minimal integration effort.

### Endpoint Details

* **URL**: `https://core.skypaybd.top/api/payment/create`
* **Method**: `POST` (or `GET`)
* **Headers**:
  * `BRAND-KEY`: `<your_active_brand_key>` (Required)
  * `Content-Type`: `application/json`
  * `Accept`: `application/json`

### Request Parameters

| Parameter     | Type            | Required | Default               | Aliases                              | Description & Constraints                                                                     |
| ------------- | --------------- | -------- | --------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------- |
| `amount`      | Float / Numeric | **Yes**  | —                     | —                                    | Bill amount in BDT. Constraints: Minimum `1.00`, Maximum `1,000,000.00`.                      |
| `success_url` | String (URL)    | **Yes**  | —                     | —                                    | Absolute HTTPS URL where the customer is redirected upon successful payment execution.        |
| `cancel_url`  | String (URL)    | **Yes**  | —                     | —                                    | Absolute HTTPS URL where the customer is redirected if the transaction is cancelled or fails. |
| `webhook_url` | String (URL)    | No       | Brand Default         | —                                    | Publicly accessible server URL for asynchronous IPN payment notifications.                    |
| `cus_name`    | String          | No       | `"Default Name"`      | `customer_name`, `c_name`, `name`    | Customer's full name. Displayed on hosted invoice.                                            |
| `cus_email`   | String          | No       | `"default@gmail.com"` | `customer_email`, `c_email`, `email` | Customer's email address for billing receipts.                                                |
| `meta_data`   | Object / JSON   | No       | `null`                | `metadata`                           | Arbitrary JSON object or valid JSON string stored and echoed back in callbacks.               |
| `return_type` | String          | No       | `"GET"`               | —                                    | Redirection HTTP method (`GET` appends query strings to return URLs).                         |

### Request Example (cURL)

```bash
curl -X POST "https://core.skypaybd.top/api/payment/create" \
  -H "BRAND-KEY: your_active_brand_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500.00,
    "cus_name": "Rahim Ahmed",
    "cus_email": "rahim@example.com",
    "success_url": "https://merchant.com/payment/success",
    "cancel_url": "https://merchant.com/payment/cancel",
    "webhook_url": "https://merchant.com/api/payment-webhook",
    "meta_data": {
      "order_id": "ORD-99120",
      "user_id": 4821
    }
  }'
```

### Success Response (HTTP 200 OK)

```json
{
  "status": true,
  "message": "Payment URL generated successfully.",
  "payment_url": "https://core.skypaybd.top/api/execute/f7b3a9c2d1e0f8"
}
```

### Hosted Checkout Redirection Lifecycle

Once the `payment_url` is obtained, redirect the customer's browser. After payment completion, cancellation, or expiration, SkyPay redirects the user back to your site with parameters appended:

#### 1. On Success / Settlement (`success_url`):

```http
GET https://merchant.com/payment/success?paymentMethod=bkash&transactionId=BLM37A9B1X&paymentAmount=1500.00&paymentFee=0.00&status=completed
```

#### 2. On Bank / Manual Review (`success_url`):

```http
GET https://merchant.com/payment/success?paymentMethod=bank&transactionId=FILE_OR_TRX&paymentAmount=1500.00&paymentFee=0.00&status=pending
```

#### 3. On Cancellation / Expiration (`cancel_url`):

```http
GET https://merchant.com/payment/cancel?paymentMethod=bkash&transactionId=TRX_INIT_ID&paymentAmount=1500.00&paymentFee=0.00&status=failed
```

***

## 2. Version 2 — Headless In-App API (`/api/v2/payment/create`)

The Headless API enables merchant applications (Flutter, React Native, iOS, Android, Telegram Bots, and Single-Page Apps) to build custom payment UI screens natively without redirecting customers out of the app.

### Endpoint Details

* **URL**: `https://core.skypaybd.top/api/v2/payment/create`
* **Method**: `POST`
* **Headers**:
  * `BRAND-KEY`: `<your_active_brand_key>` (Required)
  * `Content-Type`: `application/json`
  * `Accept`: `application/json`

### Request Parameters

| Parameter   | Type    | Required | Description & Constraints                             |
| ----------- | ------- | -------- | ----------------------------------------------------- |
| `cus_name`  | String  | **Yes**  | Customer's full name or username.                     |
| `amount`    | Numeric | **Yes**  | Bill amount in BDT. Must be greater than `0.00`.      |
| `meta_data` | Object  | No       | Key-value dictionary stored with the payment session. |

### Request Example (cURL)

```bash
curl -X POST "https://core.skypaybd.top/api/v2/payment/create" \
  -H "BRAND-KEY: your_active_brand_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cus_name": "Tanvir Hasan",
    "amount": 2400,
    "meta_data": {
      "invoice_no": "INV-7731",
      "telegram_chat_id": 98127419
    }
  }'
```

### Success Response (HTTP 200 OK)

```json
{
  "status": true,
  "id": "ids_98fbc102e4aa",
  "brand": {
    "name": "SkyPay Official Store",
    "mobile": "+88017XXXXXXXX",
    "whatsapp": "+88017XXXXXXXX",
    "email": "support@skypaybd.top"
  },
  "methods": [
    {
      "name": "bkash",
      "active_payments": {
        "personal": true,
        "agent": false,
        "payment": true
      },
      "personal": "017XXXXXXXX",
      "agent": "",
      "payment": "017XXXXXXXX"
    },
    {
      "name": "nagad",
      "active_payments": {
        "personal": true,
        "agent": false
      },
      "personal": "018XXXXXXXX",
      "agent": ""
    },
    {
      "name": "banglaqr",
      "active_payments": {
        "qr": true
      },
      "qr_image": "https://core.skypaybd.top/uploads/qr/bangla_qr_sample.png"
    },
    {
      "name": "binance",
      "active_payments": {
        "personal": true,
        "merchant": false
      },
      "personal": "498217342",
      "currency": "USDT",
      "dollar_rate": 125.0,
      "amount_usdt": 19.2
    },
    {
      "name": "bep20",
      "active_payments": {
        "transfer": true
      },
      "network": "BNB Smart Chain (BEP20)",
      "currency": "USDT",
      "receiver_address": "0x51c7263b8be9238318e8df3c921312389102488a",
      "dollar_rate": 125.0,
      "amount_usdt": 19.2
    }
  ]
}
```

### Response Schema Breakdown

* **`id`**: Unique session token used in subsequent verification calls (`/api/v2/payment/verify`).
* **`brand`**: Merchant public profile metadata to display on custom receipt headers.
* **`methods`**: Dynamic array of currently available payment rails:
  * **`bkash` / `nagad`**: Returns active account numbers and accepted transaction types (`personal`, `agent`, `payment`).
  * **`banglaqr`**: Returns the `qr_image` URL that customers scan using any Bangladeshi banking or MFS app.
  * **`binance`**: Returns the merchant Binance Pay UID (`personal`), converted `amount_usdt`, and active `dollar_rate`.
  * **`bep20`**: Returns the designated BEP20 `receiver_address`, network name, converted `amount_usdt`, and active `dollar_rate`.

***

## 3. Validation & Failure Responses

If the request payload contains missing or invalid parameters, SkyPay returns descriptive HTTP 400 or HTTP 422 error payloads.

### Missing Required Fields (HTTP 400 Bad Request)

```json
{
  "status": false,
  "message": "The cus_name and amount fields are required."
}
```

### Amount Out of Range (HTTP 422 Unprocessable Entity)

```json
{
  "status": false,
  "message": "The amount must be between 1 and 1000000."
}
```

### Missing Return URL on Hosted v1 (HTTP 422)

```json
{
  "status": false,
  "message": "The success_url field is required."
}
```

***

## 4. Multi-Language Implementation Examples

### Node.js (Axios)

```javascript
const axios = require('axios');

async function createHeadlessPayment(customerName, amountInBdt, meta = {}) {
  const url = 'https://core.skypaybd.top/api/v2/payment/create';
  const response = await axios.post(url, {
    cus_name: customerName,
    amount: amountInBdt,
    meta_data: meta
  }, {
    headers: {
      'BRAND-KEY': process.env.SKYPAY_BRAND_KEY,
      'Content-Type': 'application/json'
    }
  });

  return response.data;
}
```

### Python (Requests)

```python
import os
import requests

def create_headless_session(customer_name: str, amount_bdt: float, metadata: dict = None):
    url = "https://core.skypaybd.top/api/v2/payment/create"
    headers = {
        "BRAND-KEY": os.getenv("SKYPAY_BRAND_KEY"),
        "Content-Type": "application/json"
    }
    payload = {
        "cus_name": customer_name,
        "amount": amount_bdt,
        "meta_data": metadata or {}
    }
    
    response = requests.post(url, json=payload, headers=headers, timeout=10)
    response.raise_for_status()
    return response.json()
```

### PHP (Guzzle HTTP)

```php
<?php
use GuzzleHttp\Client;

function createHostedSession($amount, $successUrl, $cancelUrl, $brandKey, $metaData = []) {
    $client = new Client(['base_uri' => 'https://core.skypaybd.top/']);
    
    $response = $client->post('api/payment/create', [
        'headers' => [
            'BRAND-KEY'    => $brandKey,
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'amount'      => $amount,
            'success_url' => $successUrl,
            'cancel_url'  => $cancelUrl,
            'meta_data'   => $metaData
        ]
    ]);
    
    return json_decode($response->getBody(), true);
}
```

***

## 5. Next Steps

After initializing a session, the merchant system must verify customer payments upon completion:

* [← Previous: Authentication](/integration-and-api/authentication.md)
* [Next: Verify Payment →](/integration-and-api/verify-payment.md)