# Create Payment

`POST /api/payments/create`

Create a balance-recharge payment for your account. You receive a hosted payment URL — send your payer there, and after payment the payer is redirected to **your** custom success page.

Requirement: the hostname of your `success_url` (and `cancel_url`, if used) must be **registered on our side** before use (contact support to allowlist your domain, e.g. `shop.example.com`). Requests with unregistered hosts are rejected with `422`.

## Request Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| amount | number | Yes | Amount in BDT. Minimum 20. |
| success_url | string | Yes | HTTPS URL on an allowlisted host. Payer is sent here after payment. |
| cancel_url | string | No | HTTPS URL on an allowlisted host. Payer is sent here if they cancel. |

## Request Example

```bash
curl -X POST https://api.awajdigital.com/api/payments/create \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "success_url": "https://shop.example.com/payment/success",
    "cancel_url": "https://shop.example.com/payment/cancel"
  }'
```

```javascript
// Browser JavaScript (Fetch API)
const response = await fetch('https://api.awajdigital.com/api/payments/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_token_here',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 500,
    success_url: 'https://shop.example.com/payment/success',
    cancel_url: 'https://shop.example.com/payment/cancel'
  })
});

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

```javascript
// Node.js with axios
const axios = require('axios');

async function createPayment() {
  try {
    const response = await axios.post('https://api.awajdigital.com/api/payments/create', {
      amount: 500,
      success_url: 'https://shop.example.com/payment/success',
      cancel_url: 'https://shop.example.com/payment/cancel'
    }, {
      headers: {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

createPayment();
```

```python
# Python with requests
import requests

def create_payment():
    url = 'https://api.awajdigital.com/api/payments/create'
    headers = {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    }
    data = {
        'amount': 500,
        'success_url': 'https://shop.example.com/payment/success',
        'cancel_url': 'https://shop.example.com/payment/cancel'
    }

    try:
        response = requests.post(url, json=data, headers=headers)
        print(response.json())
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

create_payment()
```

```php
<?php
// PHP with cURL
$url = 'https://api.awajdigital.com/api/payments/create';
$token = 'your_api_token_here';

$data = [
    'amount' => 500,
    'success_url' => 'https://shop.example.com/payment/success',
    'cancel_url' => 'https://shop.example.com/payment/cancel'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Accept: application/json',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

$result = json_decode($response, true);
print_r($result);
?>
```

## Success Response Example

```json
{
  "success": true,
  "payment_url": "https://pay.example.com/checkout/9f8b7c6d-...",
  "invoice_id": "9f8b7c6d-..."
}
```

Redirect your payer to `payment_url`. After payment, the flow is:

1. The payment gateway returns the payer to **our** server first (this guarantees the balance is credited even if the webhook is missed).
2. We immediately redirect the payer to your `success_url` with two query parameters appended:
   - `invoice_id` — the payment reference
   - `status` — `completed` or `pending`

:::caution[Confirm before delivering]
The `success_url` redirect alone is **not** proof of payment — anyone can type that URL. Always confirm with the [Get Payment Status](/api-docs/payments/status) endpoint before delivering your service.
:::

## Error Responses

| Status | Description |
| --- | --- |
| 401 | Missing or invalid access token |
| 403 | Payment API not enabled for your account |
| 422 | Validation failed (amount < 20, non-https URL, non-allowlisted host) |
| 502 | Gateway error — payment could not be created |