### GET /callback

Source: https://idpay.ir/web-service/v1.1/index

After a successful payment, the user is redirected to the merchant's callback URL. Transaction details are sent as query parameters using the GET method.

```APIDOC
## GET /callback

### Description
This endpoint is the callback URL provided by the merchant. After a successful payment, transaction details are sent to this URL as query parameters using the GET method.

### Method
GET

### Endpoint
/callback

### Parameters
#### Path Parameters
None

#### Query Parameters
- **status** (number) - Required - The transaction status.
- **track_id** (number) - Required - The IdPay tracking ID.
- **id** (string) - Required - The unique transaction ID received during transaction creation.
- **order_id** (string) - Required - The merchant's order number sent during transaction creation.

### Request Example
```
GET /callback?status=1&track_id=123456789&id=txn_abc123xyz&order_id=order_98765
```

### Response
#### Success Response (200)
This endpoint typically does not return a JSON response. It's a redirect to the merchant's site.

#### Response Example
(Redirect to merchant's callback URL)
```

--------------------------------

### استعلام وضعیت تراکنش با Go

Source: https://idpay.ir/web-service/v1.1/index

این کد نحوه استعلام آخرین وضعیت یک تراکنش را با استفاده از زبان Go و پکیج‌های استاندارد http و json نشان می‌دهد. درخواست POST با داده‌های JSON و هدرهای لازم ساخته و ارسال می‌شود.

```go
url := "https://api.idpay.ir/v1.1/payment/inquiry"

data := map[string]string{
  "id":       "d2e353189823079e1e4181772cff5292",
  "order_id": "101",
}

payload, _ := json.Marshal(data)

req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))

req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-KEY", "6a7f99eb-7c20-4412-a972-6dfb7cd253a4")
req.Header.Set("X-SANDBOX", "1")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)

fmt.Println(string(body))
```

--------------------------------

### استعلام وضعیت تراکنش با Node.js

Source: https://idpay.ir/web-service/v1.1/index

این کد نحوه استعلام آخرین وضعیت یک تراکنش را با استفاده از Node.js و کتابخانه 'request' نشان می‌دهد. درخواست POST با پارامترها و هدرهای لازم پیکربندی شده است.

```javascript
var request = require('request');

var options = {
  method: 'POST',
  url: 'https://api.idpay.ir/v1.1/payment/inquiry',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': '6a7f99eb-7c20-4412-a972-6dfb7cd253a4',
    'X-SANDBOX': 1,
  },
  body: {
    'id': 'd2e353189823079e1e4181772cff5292',
    'order_id': '101',
  },
  json: true,
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```

--------------------------------

### دریافت لیست تراکنش ها با Go

Source: https://idpay.ir/web-service/v1.1/index

این کد نحوه فراخوانی API برای دریافت لیست تراکنش ها با استفاده از زبان Go را نشان می دهد. از پکیج های استاندارد http و encoding/json برای ساخت و ارسال درخواست استفاده می شود. پارامترها به صورت JSON در بدنه درخواست ارسال می شوند.

```go
url := "https://api.idpay.ir/v1.1/payment/transactions?page=0&page_size=5"

data := map[string]interface{}{
  "id": "e22952579725883bbad9f8fa429134bf",
  "order_id": 101,
  "amount": 10000,
  "status": []string{"100"},
  "track_id": "27384837",
  "payment_card_no": "636214******5409",
  "payment_hashed_card_no": "B913D97F01CE42601181135DF3D0F81DA9E98E61BE3E3AB4436E6345D6AB0AEA",
  "payment_date": map[string]int{"min": 1600005000, "max": 1600006000},
  "settlement_date": map[string]int{"min": 1600005746, "max": 1600006000}
}

payload, _ := json.Marshal(data)

req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))

req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-KEY", "6a7f99eb-7c20-4412-a972-6dfb7cd253a4")
req.Header.Set("X-SANDBOX", "0")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)

fmt.Println(string(body))


```

--------------------------------

### نمونه پاسخ خطا در ایجاد تراکنش

Source: https://idpay.ir/web-service/v1.1/index

این نمونه JSON نشان‌دهنده پاسخ خطا در صورت بروز مشکل هنگام ایجاد تراکنش از طریق API idpay.ir است. در این مثال، خطای مربوط به خالی بودن فیلد 'order_id' با کد خطا 32 و پیام 'شماره سفارش `order_id` نباید خالی باشد.' نمایش داده شده است.

```json
{
  "error_code": 32,
  "error_message": "شماره سفارش `order_id` نباید خالی باشد."
}
```

--------------------------------

### ایجاد تراکنش با Node.js

Source: https://idpay.ir/web-service/v1.1/index

این کد نحوه ایجاد یک تراکنش جدید با استفاده از Node.js و کتابخانه 'request' را نشان می‌دهد. یک شیء 'options' حاوی متد درخواست (POST)، URL، هدرها و بدنه درخواست (شامل جزئیات تراکنش) تعریف می‌شود. سپس درخواست به API idpay.ir ارسال شده و پاسخ در کنسول چاپ می‌شود.

```javascript
var request = require('request');

var options = {
  method: 'POST',
  url: 'https://api.idpay.ir/v1.1/payment',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': '6a7f99eb-7c20-4412-a972-6dfb7cd253a4',
    'X-SANDBOX': 1,
  },
  body: {
    'order_id': '101',
    'amount': 10000,
    'name': 'قاسم رادمان',
    'phone': '09382198592',
    'mail': 'my@site.com',
    'desc': 'توضیحات پرداخت کننده',
    'callback': 'https://example.com/callback',
  },
  json: true,
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```

--------------------------------

### ایجاد تراکنش با Go

Source: https://idpay.ir/web-service/v1.1/index

این کد نحوه ایجاد یک تراکنش جدید با استفاده از زبان برنامه‌نویسی Go را نمایش می‌دهد. با استفاده از پکیج‌های استاندارد http و encoding/json، یک درخواست POST به API idpay.ir ساخته و ارسال می‌شود. اطلاعات تراکنش در یک map تعریف شده و سپس به صورت JSON کدگذاری می‌شود. هدرهای لازم برای احراز هویت و تعیین نوع محتوا نیز تنظیم می‌گردند.

```go
url := "https://api.idpay.ir/v1.1/payment"

data := map[string]string{
  "order_id": "101",
  "amount":   "10000",
  "name":     "قاسم رادمان",
  "phone":    "09382198592",
  "mail":     "my@site.com",
  "desc":     "توضیحات پرداخت کننده",
  "callback": "https://example.com/callback",
}

payload, _ := json.Marshal(data)

req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))

req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-KEY", "6a7f99eb-7c20-4412-a972-6dfb7cd253a4")
req.Header.Set("X-SANDBOX", "1")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)

fmt.Println(string(body))
```

--------------------------------

### استعلام وضعیت تراکنش با curl

Source: https://idpay.ir/web-service/v1.1/index

این کد نحوه استعلام آخرین وضعیت یک تراکنش را با استفاده از ابزار curl نشان می‌دهد. این درخواست POST به همراه هدرهای لازم و پارامترهای تراکنش ارسال می‌شود.

```shell
curl -X POST https://api.idpay.ir/v1.1/payment/inquiry \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: 6a7f99eb-7c20-4412-a972-6dfb7cd253a4' \
  -H 'X-SANDBOX: 1' \
  -d '{
  "id": "d2e353189823079e1e4181772cff5292",
  "order_id": "101"
}'
```

--------------------------------

### تایید تراکنش با Node.js

Source: https://idpay.ir/web-service/v1.1/index

نمونه کد Node.js با استفاده از کتابخانه 'request' برای تایید تراکنش. این کد درخواست POST را با هدرهای لازم و بدنه JSON به API آیدی پی ارسال می‌کند و پاسخ را در کنسول چاپ می‌کند.

```javascript
var request = require('request');

var options = {
  method: 'POST',
  url: 'https://api.idpay.ir/v1.1/payment/verify',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': '6a7f99eb-7c20-4412-a972-6dfb7cd253a4',
    'X-SANDBOX': 1,
  },
  body: {
    'id': 'd2e353189823079e1e4181772cff5292',
    'order_id': '101',
  },
  json: true,
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```

--------------------------------

### تایید تراکنش با Go

Source: https://idpay.ir/web-service/v1.1/index

نمونه کد Go برای تایید تراکنش با استفاده از پکیج‌های استاندارد `net/http` و `encoding/json`. این کد یک درخواست POST به API آیدی پی ارسال می‌کند و پاسخ را پردازش می‌کند.

```go
url := "https://api.idpay.ir/v1.1/payment/verify"

data := map[string]string{
  "id":       "d2e353189823079e1e4181772cff5292",
  "order_id": "101",
}

payload, _ := json.Marshal(data)

req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))

req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-KEY", "6a7f99eb-7c20-4412-a972-6dfb7cd253a4")
req.Header.Set("X-SANDBOX", "1")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)

fmt.Println(string(body))
```

--------------------------------

### ایجاد تراکنش با curl

Source: https://idpay.ir/web-service/v1.1/index

این کد نحوه ایجاد یک تراکنش جدید با استفاده از ابزار خط فرمان curl را نشان می‌دهد. این درخواست POST به API idpay.ir ارسال می‌شود و شامل اطلاعات تراکنش مانند order_id، amount و callback است. هدرهای لازم برای احراز هویت و تعیین نوع محتوا نیز در این درخواست گنجانده شده‌اند.

```shell
curl -X POST https://api.idpay.ir/v1.1/payment \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: 6a7f99eb-7c20-4412-a972-6dfb7cd253a4' \
  -H 'X-SANDBOX: 1' \
  -d '{
  "order_id": 101,
  "amount": 10000,
  "name": "قاسم رادمان",
  "phone": "09382198592",
  "mail": "my@site.com",
  "desc": "توضیحات پرداخت کننده",
  "callback": "https://example.com/callback"
}'
```

--------------------------------

### POST /callback

Source: https://idpay.ir/web-service/v1.1/index

After a successful payment, the user is redirected to the merchant's callback URL. Transaction details are sent using the POST method.

```APIDOC
## POST /callback

### Description
This endpoint is the callback URL provided by the merchant. After a successful payment, transaction details are sent to this URL using the POST method.

### Method
POST

### Endpoint
/callback

### Parameters
#### Query Parameters
None

#### Request Body
- **status** (number) - Required - The transaction status.
- **track_id** (number) - Required - The IdPay tracking ID.
- **id** (string) - Required - The unique transaction ID received during transaction creation.
- **order_id** (string) - Required - The merchant's order number sent during transaction creation.
- **amount** (number) - Required - The amount registered during transaction creation.
- **card_no** (string) - Required - The payer's card number in the format `123456******1234`.
- **hashed_card_no** (string) - Required - The SHA256 hashed card number of the payer.
- **date** (timestamp) - Required - The timestamp of the transaction payment.

### Request Example
```json
{
  "status": 1,
  "track_id": 123456789,
  "id": "txn_abc123xyz",
  "order_id": "order_98765",
  "amount": 10000,
  "card_no": "123456******1234",
  "hashed_card_no": "a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef",
  "date": 1678886400
}
```

### Response
#### Success Response (200)
This endpoint typically does not return a JSON response. It's a redirect to the merchant's site.

#### Response Example
(Redirect to merchant's callback URL)
```

--------------------------------

### استعلام وضعیت تراکنش با PHP

Source: https://idpay.ir/web-service/v1.1/index

این کد نحوه استعلام آخرین وضعیت یک تراکنش را با استفاده از زبان PHP و کتابخانه cURL نشان می‌دهد. پارامترهای تراکنش و هدرهای لازم برای درخواست POST تنظیم می‌شوند.

```php
<?php
$params = array(
  'id' => 'd2e353189823079e1e4181772cff5292',
  'order_id' => '101',
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.idpay.ir/v1.1/payment/inquiry');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'Content-Type: application/json',
  'X-API-KEY: 6a7f99eb-7c20-4412-a972-6dfb7cd253a4',
  'X-SANDBOX: 1',
));

$result = curl_exec($ch);
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

var_dump($httpcode);
var_dump($result);

?>
```

--------------------------------

### دریافت لیست تراکنش ها با curl

Source: https://idpay.ir/web-service/v1.1/index

این کد نحوه فراخوانی API برای دریافت لیست تراکنش ها با استفاده از ابزار curl را نشان می دهد. این روش برای تست سریع و اسکریپت نویسی مفید است. پارامترهای صفحه بندی و فیلترها در بدنه درخواست ارسال می شوند.

```shell
curl -X POST https://api.idpay.ir/v1.1/payment/transactions?page=0&page_size=25 \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: 6a7f99eb-7c20-4412-a972-6dfb7cd253a4' \
  -H 'X-SANDBOX: 0' \
  -d '{
  "id": "e22952579725883bbad9f8fa429134bf",
  "order_id": 101,
  "amount": 10000,
  "status": ["100"],
  "track_id": "27384837",
  "payment_card_no": "636214******5409",
  "payment_hashed_card_no": "B913D97F01CE42601181135DF3D0F81DA9E98E61BE3E3AB4436E6345D6AB0AEA",
  "payment_date": {"min": 1600005000, "max": 1600006000},
  "settlement_date": {"min": 1600005746, "max": 1600006000}
}'
```

--------------------------------

### ایجاد تراکنش با PHP

Source: https://idpay.ir/web-service/v1.1/index

این کد نحوه ایجاد یک تراکنش جدید با استفاده از زبان برنامه‌نویسی PHP را نمایش می‌دهد. با استفاده از cURL، یک درخواست POST به API idpay.ir ارسال می‌شود. پارامترهای تراکنش در قالب یک آرایه تعریف شده و سپس به صورت JSON کدگذاری می‌شوند. هدرهای لازم برای احراز هویت و تعیین نوع محتوا نیز تنظیم می‌گردند.

```php
<?php
$params = array(
  'order_id' => '101',
  'amount' => 10000,
  'name' => 'قاسم رادمان',
  'phone' => '09382198592',
  'mail' => 'my@site.com',
  'desc' => 'توضیحات پرداخت کننده',
  'callback' => 'https://example.com/callback',
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.idpay.ir/v1.1/payment');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'Content-Type: application/json',
  'X-API-KEY: 6a7f99eb-7c20-4412-a972-6dfb7cd253a4',
  'X-SANDBOX: 1'
));

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

var_dump($result);

?>
```

--------------------------------

### نمونه پاسخ موفق ایجاد تراکنش

Source: https://idpay.ir/web-service/v1.1/index

این نمونه JSON نشان‌دهنده پاسخ موفق پس از ایجاد یک تراکنش جدید از طریق API idpay.ir است. در صورت موفقیت‌آمیز بودن عملیات، یک شناسه منحصر به فرد تراکنش (id) و یک لینک پرداخت (link) به همراه کد وضعیت 201 Created بازگردانده می‌شود.

```json
{
  "id": "d2e353189823079e1e4181772cff5292",
  "link": "https://idpay.ir/p/ws-sandbox/d2e353189823079e1e4181772cff5292"
}
```

--------------------------------

### دریافت لیست تراکنش ها با JavaScript (Fetch API)

Source: https://idpay.ir/web-service/v1.1/index

این کد نحوه فراخوانی API برای دریافت لیست تراکنش ها با استفاده از JavaScript و Fetch API را نشان می دهد. این روش برای برنامه های وب مدرن و سمت کلاینت مناسب است. درخواست POST با هدرهای لازم و بدنه JSON ارسال می شود.

```javascript
var body = {
  "id": "e22952579725883bbad9f8fa429134bf",
  "order_id": 101,
  "amount": 10000,
  "status": ["100"],
  "track_id": "27384837",
  "payment_card_no": "636214******5409",
  "payment_hashed_card_no": "B913D97F01CE42601181135DF3D0F81DA9E98E61BE3E3AB4436E6345D6AB0AEA",
  "payment_date": {"min": 1600005000, "max": 1600006000},
  "settlement_date": {"min": 1600005746, "max": 1600006000}
}

fetch("https://api.idpay.ir/v1.1/payment/transactions?page=0&page_size=5", {
  "headers": {
    'Content-Type': 'application/json',
    'X-API-KEY': '6a7f99eb-7c20-4412-a972-6dfb7cd253a4',
    'X-SANDBOX': 0
  },
  "body": JSON.stringify(body),
  "method": 'POST'
})
.then(e => e.json())
.then(e => {
    console.log(e)
})


```

--------------------------------

### POST /v1.1/payment

Source: https://idpay.ir/web-service/v1.1/index

Creates a new payment transaction. This endpoint allows you to initiate a payment process by providing necessary details such as order ID, amount, and callback URL.

```APIDOC
## POST /v1.1/payment

### Description
Creates a new payment transaction. This endpoint allows you to initiate a payment process by providing necessary details such as order ID, amount, and callback URL.

### Method
POST

### Endpoint
https://api.idpay.ir/v1.1/payment

### Parameters
#### Headers
- **Content-Type** (string) - Required - `application/json`
- **X-API-KEY** (string) - Required - Your API key
- **X-SANDBOX** (integer) - Optional - Set to `1` for sandbox environment

#### Request Body
- **order_id** (string) - Required - Maximum 50 characters. Your unique order ID.
- **amount** (number) - Required - Between 1,000 and 500,000,000 Rials.
- **name** (string) - Optional - Maximum 255 characters. Payer's name.
- **phone** (string) - Optional - 11 characters. Payer's mobile number (e.g., 09382198592).
- **mail** (string) - Optional - Maximum 255 characters. Payer's email address.
- **desc** (string) - Optional - Maximum 255 characters. Transaction description.
- **callback** (string) - Required - Maximum 2048 characters. The URL to redirect the user to after payment.

### Request Example
```json
{
  "order_id": "101",
  "amount": 10000,
  "name": "قاسم رادمان",
  "phone": "09382198592",
  "mail": "my@site.com",
  "desc": "توضیحات پرداخت کننده",
  "callback": "https://example.com/callback"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - Unique transaction ID.
- **link** (string) - Payment link for the user.

#### Response Example (Success)
```json
{
  "id": "d2e353189823079e1e4181772cff5292",
  "link": "https://idpay.ir/p/ws-sandbox/d2e353189823079e1e4181772cff5292"
}
```

#### Error Response (e.g., 406)
- **error_code** (integer) - The error code.
- **error_message** (string) - A message describing the error.

#### Response Example (Error)
```json
{
  "error_code": 32,
  "error_message": "شماره سفارش `order_id` نباید خالی باشد."
}
```
```

--------------------------------

### دریافت لیست تراکنش ها با PHP

Source: https://idpay.ir/web-service/v1.1/index

این کد نحوه فراخوانی API برای دریافت لیست تراکنش ها با استفاده از زبان PHP را نشان می دهد. از کتابخانه cURL برای ارسال درخواست POST استفاده می شود. پارامترهای صفحه بندی و فیلترها در بدنه درخواست JSON ارسال می شوند.

```php
<?php
$params = array(
  "id" => "e22952579725883bbad9f8fa429134bf",
  "order_id" => 101,
  "amount" => 10000,
  "status" => ["100"],
  "track_id" => "27384837",
  "payment_card_no" => "636214******5409",
  "payment_hashed_card_no" => "B913D97F01CE42601181135DF3D0F81DA9E98E61BE3E3AB4436E6345D6AB0AEA",
  "payment_date" => ["min" => 1600005000, "max" => 1600006000],
  "settlement_date" => ["min" => 1600005746, "max" => 1600006000]
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.idpay.ir/v1.1/payment/transactions?page=0&page_size=5');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'Content-Type: application/json',
  'X-API-KEY: 6a7f99eb-7c20-4412-a972-6dfb7cd253a4',
  'X-SANDBOX: 0'
));

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

var_dump($result);


```

--------------------------------

### تایید تراکنش با curl

Source: https://idpay.ir/web-service/v1.1/index

نمونه درخواست تایید تراکنش با استفاده از ابزار curl. این درخواست شامل کلید API، شناسه تراکنش و شناسه سفارش است و برای ارسال داده‌ها از فرمت JSON استفاده می‌کند.

```curl
curl -X POST https://api.idpay.ir/v1.1/payment/verify \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: 6a7f99eb-7c20-4412-a972-6dfb7cd253a4' \
  -H 'X-SANDBOX: 1' \
  -d '{
  "id": "d2e353189823079e1e4181772cff5292",
  "order_id": "101"
}'
```

--------------------------------

### Error Handling

Source: https://idpay.ir/web-service/v1.1/index

This section details the error codes returned by the API, including their corresponding HTTP status codes and descriptive messages, to help developers handle potential issues.

```APIDOC
## API Error Codes

### Description
Provides a list of error codes that may be returned by the API, along with their HTTP status codes and explanations.

### Error List

| Status | Error Code | Description |
|---|---|---|
| 500 | -1 | Unexpected error |
| 403 | 11 | User is blocked. |
| 403 | 12 | API Key not found. |
| 403 | 13 | Your request was sent from {ip}. This IP does not match the IPs registered with the web service. |
| 403 | 14 | Your web service is under review or not yet approved. |
| 500 | 15 | The requested service is unavailable. |
| 403 | 21 | The bank account connected to the web service is not verified. |
| 404 | 22 | Web service not found. |
| 401 | 23 | Web service validation failed. |
| 403 | 24 | The bank account associated with this web service has been deactivated. |
| 406 | 31 | Transaction ID `id` cannot be empty. |
| 406 | 32 | Order ID `order_id` cannot be empty. |
| 406 | 33 | Amount `amount` cannot be empty. |
| 406 | 34 | Amount `amount` must be greater than {min-amount} Rials. |
| 406 | 35 | Amount `amount` must be less than {max-amount} Rials. |
| 406 | 36 | Amount `amount` exceeds the allowed limit. |
| 406 | 37 | Callback URL `callback` cannot be empty. |
| 406 | 38 | Your request was sent from the domain {domain}. The domain of the callback URL does not match the registered address in the web service. |
| 406 | 39 | Callback URL is invalid. |
| 406 | 41 | Transaction status filter must be an array (list) of allowed statuses as documented. |
| 406 | 42 | Payment date filter must be an array containing `min` and `max` elements of type timestamp. |
| 406 | 43 | Settlement date filter must be an array containing `min` and `max` elements of type timestamp. |
| 406 | 44 | Transaction filter is invalid. |
| 405 | 51 | Transaction creation failed. |
| 400 | 52 | Query returned no results. |
| 405 | 53 | Payment confirmation is not possible. |
| 405 | 54 | The time limit for payment confirmation has expired. |

### Example Error Response (Status 406)
```json
{
  "error_code": 41,
  "error_message": "Transaction status filter must be an array (list) of allowed statuses as documented."
}
```
```

--------------------------------

### POST /payment/verify

Source: https://idpay.ir/web-service/v1.1/index

After receiving the transaction information and validating it, the merchant must confirm the transaction to complete the payment systemically and prevent refunds to the payer.

```APIDOC
## POST /payment/verify

### Description
Confirms a transaction after the payment has been completed to prevent refunds.

### Method
POST

### Endpoint
`https://api.idpay.ir/v1.1/payment/verify`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **id** (string) - Required - The unique transaction ID received during the transaction creation phase.
- **order_id** (string) - Required - The merchant's order number sent during the transaction creation phase.

### Request Example
```json
{
  "id": "d2e353189823079e1e4181772cff5292",
  "order_id": "101"
}
```

### Response
#### Success Response (200)
- **status** (number) - Transaction status.
- **track_id** (number) - IDPay tracking code.
- **id** (string) - The unique transaction ID.
- **order_id** (string) - The merchant's order number.
- **amount** (number) - The amount registered during transaction creation.
- **date** (timestamp) - The time of transaction creation.
- **payment** (object) - Transaction payment information.
  - **track_id** (string) - Payment tracking code.
  - **amount** (number) - Payable amount.
  - **card_no** (string) - Payer's card number in the format `123456******1234`.
  - **hashed_card_no** (string) - Hashed card number using SHA256 algorithm.
  - **date** (timestamp) - The time of transaction payment.
- **verify** (object) - Transaction verification information.
  - **date** (timestamp) - The time of transaction verification.

#### Response Example
```json
{
  "status": 100,
  "track_id": 10012,
  "id": "d2e353189823079e1e4181772cff5292",
  "order_id": "101",
  "amount": 10000,
  "date": "1546288200",
  "payment": {
    "track_id": "888001",
    "amount": 10000,
    "card_no": "123456******1234",
    "hashed_card_no": "E59FA6241C94B8836E3D03120DF33E80FD988888BBA0A122240C2E7D23B48295",
    "date": "1546288500"
  },
  "verify": {
    "date": "1546288800"
  }
}
```

#### Error Response (e.g., 406)
- **error_code** (number) - Error code.
- **error_message** (string) - Error message.

#### Error Response Example
```json
{
  "error_code": 32,
  "error_message": "شماره سفارش `order_id` نباید خالی باشد."
}
```

### Notes
To prevent double spending, merchants must store unique IDs received from IDPay API (like `id` and `track_id`) in their database and ensure their uniqueness. Customers might save a payment receipt and reuse it for another purchase. The responsibility of checking and identifying double spending lies entirely with the merchant.
```

--------------------------------

### تایید تراکنش با PHP

Source: https://idpay.ir/web-service/v1.1/index

نمونه کد PHP برای تایید تراکنش از طریق API آیدی پی. این کد از cURL برای ارسال درخواست POST به همراه هدرهای لازم و داده‌های JSON استفاده می‌کند و نتیجه را نمایش می‌دهد.

```php
<?php
$params = array(
  'id' => 'd2e353189823079e1e4181772cff5292',
  'order_id' => '101',
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.idpay.ir/v1.1/payment/verify');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'Content-Type: application/json',
  'X-API-KEY: 6a7f99eb-7c20-4412-a972-6dfb7cd253a4',
  'X-SANDBOX: 1',
));

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

var_dump($result);

?>
```

--------------------------------

### Transaction Details and Status

Source: https://idpay.ir/web-service/v1.1/index

This section outlines the structure of a transaction object, detailing fields such as payer information, payment details, verification status, and settlement information. It also provides a mapping of transaction status codes to their meanings.

```APIDOC
## Transaction Object Structure

### Description
Provides detailed information about a financial transaction, including payer, payment, verification, and settlement data.

### Fields
- **status** (number) - The status code of the transaction.
- **track_id** (number) - The IdPay transaction tracking ID.
- **id** (string) - The unique transaction ID received during creation.
- **order_id** (string) - The merchant's order ID sent during transaction creation.
- **amount** (number) - The amount recorded during transaction creation.
- **wage** (object) - Transaction commission information.
  - **by** (string) - Indicates whether the commission is received from the merchant (`payee`) or the payer (`payer`).
  - **type** (string) - The type of transaction commission: `amount` (fixed amount), `percent` (percentage), `stair` (tiered).
  - **amount** (number) - The commission amount.
- **date** (timestamp) - The timestamp of transaction creation.
- **payer** (object) - Information about the transaction payer.
  - **name** (string) - Payer's name.
  - **phone** (string) - Payer's mobile phone number.
  - **mail** (string) - Payer's email address.
  - **desc** (string) - Payer's description.
- **payment** (object) - Transaction payment details.
  - **track_id** (string) - Payment tracking ID.
  - **amount** (number) - The payable amount.
  - **card_no** (string) - Payer's card number formatted as `123456******1234`.
  - **hashed_card_no** (string) - The payer's hashed card number using SHA256 algorithm.
  - **date** (timestamp) - The timestamp of the transaction payment.
- **verify** (object) - Transaction verification details.
  - **date** (timestamp) - The timestamp of transaction verification.
- **settlement** (object) - Transaction settlement details.
  - **account** (object) - Bank account details where the transaction amount was settled.
    - **id** (string) - Account ID.
    - **iban** (string) - Account IBAN.
    - **number** (string) - Account number.
    - **bank** (object) - Bank information.
      - **id** (string) - Bank ID.
      - **title** (string) - Bank name.
  - **wallet** (object) - IdPay wallet details where the transaction amount was settled.
  - **track_id** (number) - Settlement tracking ID.
  - **amount** (number) - The settlable amount.
  - **date** (timestamp) - The timestamp of the transaction settlement to the merchant's bank account.

### Transaction Status Codes

| Status Code | Description |
|---|---|
| 1 | Payment not completed |
| 2 | Payment failed |
| 3 | Error occurred |
| 4 | Blocked |
| 5 | Returned to payer |
| 6 | System returned |
| 7 | Payment cancelled |
| 8 | Redirected to payment gateway |
| 10 | Pending payment confirmation |
| 100 | Payment confirmed |
| 101 | Payment already confirmed |
| 200 | Settled to recipient |
```