### GraphQL Query Example (Get Tickets)

Source: https://www.zarinpal.com/docs/apiDocs/guide

Demonstrates how to construct a GraphQL query to retrieve a list of tickets with specific fields.

```APIDOC
## Query: Get Tickets

### Description
This query retrieves a list of tickets, returning their IDs and statuses. You can specify parameters like `limit` and `offset` to paginate the results.

### Method
POST

### Endpoint
`https://next.zarinpal.com/api/v4/graphql`

### Parameters
#### Request Body
- **query** (string) - Required - The GraphQL query string.
  - Example: `query { Tickets(limit: 15, offset: 10) { id status } }`
- **variables** (object) - Optional - Variables for the query.

### Request Example
```json
{
  "query": "query { Tickets(limit: 15, offset: 10) { id status } }",
  "variables": null
}
```

### Response
#### Success Response (200)
- **data.Tickets** (array) - An array of ticket objects, each containing:
  - **id** (string) - The unique identifier for the ticket.
  - **status** (string) - The current status of the ticket.

#### Response Example
```json
{
  "data": {
    "Tickets": [
      {
        "id": "139805250316",
        "status": "CLOSED"
      },
      {
        "id": "139805250335",
        "status": "CLOSED"
      }
    ]
  }
}
```
```

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

### Authentication Guide

Source: https://www.zarinpal.com/docs/apiDocs/index

This section provides an overview of the authentication process required to obtain an Access Token for using the ZarinPal API. It directs users to a separate guide for detailed steps.

```APIDOC
## Authentication

### Description
This section explains the process of authenticating users to obtain an `{ACCESS_TOKEN}`. This token is necessary for making authenticated queries and mutations against the ZarinPal API. Detailed steps for the authentication process can be found in the linked 'Authentication Guide'.

### Method
(Covered in linked Authentication Guide)

### Endpoint
(Covered in linked Authentication Guide)

### Parameters
(Covered in linked Authentication Guide)

### Request Example
(Covered in linked Authentication Guide)

### Response
#### Success Response (Typically 200 OK with token)
- **access_token** (string) - The obtained access token.
- **token_type** (string) - The type of token (e.g., 'Bearer').
- **expires_in** (integer) - The token's expiration time in seconds.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```
```

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

### GraphQL Query Example

Source: https://www.zarinpal.com/docs/apiDocs/index

This example demonstrates how to send a GraphQL query to the ZarinPal API using cURL to retrieve application information. It includes the necessary headers for authorization and content type, along with the query payload.

```APIDOC
## POST /api/v4/graphql/

### Description
This endpoint allows you to send GraphQL queries to interact with the ZarinPal API. You can retrieve or modify data related to your authenticated account.

### Method
POST

### Endpoint
`https://next.zarinpal.com/api/v4/graphql/`

### Parameters
#### Query Parameters
None

#### Headers
- **Accept**: `application/json`
- **Authorization**: `Bearer {ACCESS_TOKEN}` (Replace {ACCESS_TOKEN} with your actual access token)

#### Request Body
- **query** (string) - Required - The GraphQL query string.
- **variables** (object) - Optional - Variables to be used with the GraphQL query.

### Request Example
```json
{
  "query": "query { Application { application, platform } }",
  "variables": null
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the result of the GraphQL query.
  - **Application** (object) - Information about the application.
    - **application** (string) - The application name.
    - **platform** (string) - The platform the application is on.

#### Response Example
```json
{
  "data": {
    "Application": {
      "application": "ZarinPal",
      "platform": "Web"
    }
  }
}
```
```

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

### GraphQL Mutation Example (Add Card)

Source: https://www.zarinpal.com/docs/apiDocs/guide

Illustrates how to use a GraphQL mutation to add a new card, specifying required parameters.

```APIDOC
## Mutation: Add Card

### Description
This mutation allows you to add a new card to your account. It requires the card number (pan) and expiration date. Upon successful addition, the ID of the newly created card is returned.

### Method
POST

### Endpoint
`https://next.zarinpal.com/api/v4/graphql`

### Parameters
#### Request Body
- **query** (string) - Required - The GraphQL mutation string.
  - Example: `mutation { CardAdd(pan: "1111222233334444", expired_at: "2020-02-05 00:00:00") { id } }`
- **variables** (object) - Optional - Variables for the mutation.

### Request Example
```json
{
  "query": "mutation { CardAdd(pan: \"1111222233334444\", expired_at: \"2020-02-05 00:00:00\") { id } }",
  "variables": null
}
```

### Response
#### Success Response (200)
- **data.CardAdd.id** (string) - The unique identifier of the newly added card.

#### Response Example
```json
{
  "data": {
    "CardAdd": {
      "id": "card_12345"
    }
  }
}
```
```

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

### Authentication Initialization (POST /api/oauth/initialize)

Source: https://www.zarinpal.com/docs/apiDocs/auth

Starts the authentication process by sending user credentials to Zarinpal to initiate the OTP (One-Time Password) process.

```APIDOC
## POST /api/oauth/initialize

### Description
Starts the authentication process by sending user credentials to Zarinpal to initiate the OTP (One-Time Password) process.

### Method
POST

### Endpoint
https://next.zarinpal.com/api/oauth/initialize

### Parameters
#### Request Body
- **username** (string) - Required - User's email address or mobile number.
- **channel** (string('ussd', 'sms')) - Optional (defaults to 'ussd') - The channel through which the OTP will be sent to the user.

### Request Example
```json
{
  "username": "09123456789",
  "channel": "ussd"
}
```

```json
{
  "username": "09123456789",
  "channel": "sms"
}
```

### Response
#### Success Response (200)
- **avatar** (string) - URL of the user's avatar (usually points to Gravatar).
- **channel** (string('ussd', 'sms')) - The channel via which the OTP is delivered to the user.
- **ussd_code** (string) - The USSD code the user needs to dial to receive their OTP. This will be an empty string if the channel is 'sms'.
- **waiting_time** (int) - The time in seconds before the user can request the OTP again.
- **otp_time_diff** (int) - @todo

#### Response Example
```json
{
  "avatar": "https:\/\/gravatar.com\/avatar\/{EMAIL_HASH}",
  "channel": "ussd",
  "ussd_code": "*733*4*97*2#",
  "waiting_time": 120,
  "otp_time_diff": 900
}
```
```

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

### Example Response for Invoice Status Query

Source: https://www.zarinpal.com/docs/apiDocs/query/invoice

This is an example JSON response received when querying invoice statuses without specifying a particular invoice ID. It returns a list of invoices, each with its details, status, and payment session information.

```json
{
  "data": {
    "Invoice": [
      {
        "id": "10010011749009",
        "description": "تست",
        "status": "PENDING",
        "sessions": [
          {
            "id": "346797285",
            "status": "INBANK",
            "amount": 16000,
            "payer_info": {
              "order_id": "1610127"
            }
          }
        ]
      },
      {
        "id": "10010011449005",
        "description": "تست",
        "status": "PENDING",
        "sessions": [
          {
            "id": "346780653",
            "status": "INBANK",
            "amount": 11000,
            "payer_info": {
              "order_id": "1110155"
            }
          }
        ]
      },
      {
        "id": "10010011149001",
        "description": "test InvoiceAdd",
        "status": "PENDING",
        "sessions": [
          {
            "id": "346755053",
            "status": "INBANK",
            "amount": 11000,
            "payer_info": {
              "order_id": "1110151"
            }
          }
        ]
      }
    ]
  }
}
```

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

### GraphQL Query Variables for InvoiceAdd

Source: https://www.zarinpal.com/docs/apiDocs/query/invoice

These are example query variables to be used with the `InvoiceAdd` mutation. They provide specific values for each parameter, demonstrating how to construct a request to create an identified payment invoice.

```json
{
  "terminal_id":"1915487",
  "amount":11000,
  "fee_type":"PAYER",
  "description":"test InvoiceAdd",
  "note":"",
  "callback_url":"https://example.com/callback",
  "payer_name":"علی علیپور",
  "payer_mobile":"09123456789",
  "payer_email":"info@test.com",
  "notify_type":"MOBILE"
}

```

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

### Revenue Share Creation Query Variables

Source: https://www.zarinpal.com/docs/apiDocs/query/payout

These are example query variables for the PayoutAdd GraphQL mutation. They demonstrate how to provide the necessary parameters like terminal ID, bank account ID, amount, description, and reconciliation parts to create a revenue share.

```json
{
  "terminal_id": "1915487",
  "bank_account_id": "249773",
  "amount": "100000",
  "description": "تست سرویس",
  "reconciliation_parts": "MULTI"
}
```

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

### Redirect to Zarinpal Payment Gateway

Source: https://www.zarinpal.com/docs/apiDocs/query/invoice

This section provides examples of URLs to redirect users to the Zarinpal payment gateway. One URL leads to the Zarinpal intermediary page displaying the invoice details, while the other directly initiates the bank payment process using the session order ID.

```html
https://zarinp.al/invoice/{{data.InvoiceAdd.id}}

```

```html
https://www.zarinpal.com/pg/StartPay/{{data.InvoiceAdd.sessions.*.payer_info.order_id}}/BMca

```

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

### Response Example for Transaction Verification Status

Source: https://www.zarinpal.com/docs/apiDocs/query/card-mobile-verified

This JSON response illustrates the structure received after querying the transaction verification status. It confirms the session details, including the `is_card_mobile_verified` field, which in this example is set to `true`, indicating successful identity verification for the transaction.

```json
{
  "data": {
    "Session": [
      {
        "session_tries": [
          {
            "session_id": "425368123",
            "status": "PAID",
            "rrn": "126018530297",
            "card_pan": "502229******1234",
            "is_card_mobile_verified": true
          }
        ]
      }
    ]
  }
}
```

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

### GraphQL Query Variables for Instant Refund

Source: https://www.zarinpal.com/docs/apiDocs/query/refund

These are example query variables for initiating an instant refund (CARD method) using the ZarinPal API. It includes the transaction session ID, the refund amount in Rials, a description, the 'CARD' method for immediate processing, and the reason for the refund, like 'CUSTOMER_REQUEST'.

```json
{
  "session_id": "385404123",
  "amount": 11000,
  "description": "تست سرویس",
  "method": "CARD" 
  "reason": "CUSTOMER_REQUEST"
}
```

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

### Zarinpal API Response Example

Source: https://www.zarinpal.com/docs/apiDocs/auth

This code snippet illustrates the structure of a successful response from the Zarinpal API when obtaining tokens. It includes token type, expiry duration, access token, and refresh token.

```json
{
  "token_type": "Bearer",
  "expires_in": 1296000,
  "access_token": "{ACCESS_TOKEN}",
  "refresh_token": "{REFRESH_TOKEN}"
}
```

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

### Get Bank Accounts

Source: https://www.zarinpal.com/docs/apiDocs/query/instantPayout

Retrieve a list of bank accounts associated with your user panel. This is required for setting up instant payouts.

```APIDOC
## Get Bank Accounts

### Description
Retrieves a list of bank accounts linked to the user's panel, including their ID, IBAN, and holder name. This information is necessary for the instant payout service.

### Method
GET

### Endpoint
/graphql

### Parameters
#### Query Parameters
- **limit** (Int) - Optional - Maximum number of bank accounts to retrieve.

### Request Example
```graphql
query {
  BankAccounts(limit: 200) {
    id
    iban
    holder_name
  }
}
```

### Response
#### Success Response (200)
- **BankAccounts** (Array[Object]) - A list of bank account objects.
  - **id** (String) - The unique identifier for the bank account.
  - **iban** (String) - The International Bank Account Number.
  - **holder_name** (String) - The name of the account holder.

#### Response Example
```json
{
  "data": {
    "BankAccounts": [
      {
        "id": "1234568",
        "iban": "IR123456789123456478945165",
        "holder_name": "علی علیپور"
      }
    ]
  }
}
```
```

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

### Check Instant Payout Status

Source: https://www.zarinpal.com/docs/apiDocs/query/instantPayout

Query the status of your instant payout requests. You can check the status of a specific payout by its ID or get a list of payouts for a given terminal ID.

```APIDOC
## Check Instant Payout Status

### Description
Retrieves the status and details of instant payouts. You can query by a specific payout `id` or by `terminal_id`.

### Method
GET

### Endpoint
/graphql

### Parameters
#### Query Parameters
- **id** (ID) - Optional - The unique identifier of the payout to check.
- **terminal_id** (ID) - Optional - The ID of the payment gateway terminal.

### Request Example
```graphql
query getInstantPayout($id: ID, $terminal_id: ID) {
  resource: InstantPayout(id: $id, terminal_id: $terminal_id) {
    id
    url_code
    status
    description
    amount
    fee
    reference_id
    reconciled_at
    created_at
    updated_at
  }
}
```

### Query Variables
```json
{
  "terminal_id": "1915487",
  "id": "22571"
}
```

### Response
#### Success Response (200)
- **resource** (Array[Object]) - A list of payout objects matching the query.
  - **id** (String) - The unique identifier for the payout.
  - **url_code** (String) - A code related to the payout process.
  - **status** (String) - The current status of the payout (`PAID`, `PENDING`, `IN_PROGRESS`, `REVERSED`, `REJECTED`).
  - **description** (String) - Additional descriptions about the payout status.
  - **amount** (Integer) - The amount that was processed for payout.
  - **fee** (Integer) - The fee charged for the payout.
  - **reference_id** (String) - The tracking number for the payout.
  - **reconciled_at** (String) - The timestamp when the payout request was registered.
  - **created_at** (String) - The timestamp when the payout was created.
  - **updated_at** (String) - The timestamp when the payout was last updated.

#### Response Example
```json
{
  "data": {
    "resource": [
      {
        "id": "22571",
        "url_code": "9bRqG",
        "status": "PAID",
        "description": null,
        "amount": 5000000,
        "fee": 35000,
        "reference_id": "140808300622833423",
        "reconciled_at": "2022-11-21T11:32:49+03:30",
        "created_at": "2022-11-21T11:32:32+03:30",
        "updated_at": "2022-11-21T11:32:51+03:30"
      }
    ]
  }
}
```
```

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

### GraphQL Query Variables for Delayed Refund

Source: https://www.zarinpal.com/docs/apiDocs/query/refund

These are example query variables for initiating a delayed refund (PAYA method) using the ZarinPal API. It specifies the transaction session ID, the refund amount in Rials, a description for the refund, the 'PAYA' method for delayed processing, and the reason for the refund, such as 'CUSTOMER_REQUEST'.

```json
{
  "session_id": "385404123",
  "amount": 11000,
  "description": "تست سرویس",
  "method": "PAYA" 
  "reason": "CUSTOMER_REQUEST"
}
```

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

### Get Bank Accounts

Source: https://www.zarinpal.com/docs/apiDocs/query/bankaccount

Retrieve a list of all bank accounts associated with your Zarinpal user panel.

```APIDOC
## GET /v2/accounts/bank

### Description
Retrieves a list of bank accounts added to your Zarinpal user panel.

### Method
GET

### Endpoint
/v2/accounts/bank

### Parameters
#### Query Parameters
None

### Request Example
```graphql
query getBankAccounts {
  resource: BankAccounts{
    id
    iban
    status
    is_legal
    holder_name
    type
    issuing_bank {
      name
      slug
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the list of bank accounts.
  - **resource** (array) - An array of bank account objects.
    - **id** (string) - The unique identifier for the bank account.
    - **iban** (string) - The International Bank Account Number.
    - **status** (string) - The current status of the bank account (e.g., ACTIVE, PENDING).
    - **is_legal** (boolean) - Indicates if the account is a legal entity account.
    - **holder_name** (string) - The name of the account holder.
    - **type** (string) - The type of the bank account (e.g., PERSONAL, SHARE).
    - **issuing_bank** (object) - Information about the issuing bank.
      - **name** (string) - The name of the issuing bank.
      - **slug** (string) - A short identifier for the issuing bank.

#### Response Example
```json
{
  "data": {
    "resource": [
      {
        "id": "402811",
        "iban": "IR123456789123456478945165",
        "status": "ACTIVE",
        "is_legal": false,
        "holder_name": "علی علیپور",
        "type": "PERSONAL",
        "issuing_bank": {
          "name": "بانک مهر ایران",
          "slug": "Mehr"
        }
      }
    ]
  }
}
```
```

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

### Get Terminal ID

Source: https://www.zarinpal.com/docs/apiDocs/query/invoice

Retrieve your Zarinpal terminal ID and associated domains. This is a prerequisite for using tokenized payment services.

```APIDOC
## Get Terminal ID

### Description
Retrieve your Zarinpal terminal ID and associated domains. This is a prerequisite for using tokenized payment services.

### Method
POST

### Endpoint
/query

### Parameters
#### Request Body
- **query** (String) - Required - GraphQL query to fetch terminals.

### Request Example
```graphql
query terminals {
  Terminals {
    id
    domain
  }
}
```

### Response
#### Success Response (200)
- **data** (Object) - Contains the list of terminals.
  - **Terminals** (Array) - List of terminal objects.
    - **id** (String) - The terminal ID.
    - **domain** (String) - The associated domain.

#### Response Example
```json
{
  "data": {
    "Terminals": [
      {
        "id": "1915487",
        "domain": "example.ir"
      },
      {
        "id": "191548856",
        "domain": "test.com"
      },
      {
        "id": "19154894",
        "domain": "test.example"
      }
    ]
  }
}
```
```

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

### Get Terminals

Source: https://www.zarinpal.com/docs/apiDocs/query/payout

Retrieve a list of your payment gateways (terminals) and their associated domains. This is required for creating payout requests.

```APIDOC
## GET Terminals

### Description
Retrieves a list of payment terminals (gateways) registered under your Zarinpal account, along with their associated domains. This information is necessary for initiating payout operations.

### Method
GET

### Endpoint
/graphql

### Parameters
There are no specific query parameters for this endpoint.

### Request Example
```graphql
query terminals {
  Terminals {
    id
    domain
  }
}
```

### Response
#### Success Response (200)
- **data.Terminals** (Array<Object>) - A list of terminal objects.
  - **id** (String) - The unique identifier for the terminal.
  - **domain** (String) - The domain associated with the terminal.

#### Response Example
```json
{
  "data": {
    "Terminals": [
      {
        "id": "1915487",
        "domain": "example.ir"
      }
    ]
  }
}
```
```

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

### ساختار پایه mutation GraphQL

Source: https://www.zarinpal.com/docs/apiDocs/guide

نمونه‌ای از ساختار پایه‌ای یک mutation GraphQL که برای تغییر اطلاعات در API استفاده می‌شود. با مشخص کردن نوع عملیات 'mutation' شروع می‌شود.

```graphql
mutation {

}

```

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

### کوئری GraphQL با پارامتر limit

Source: https://www.zarinpal.com/docs/apiDocs/guide

این کوئری GraphQL نحوه محدود کردن تعداد تیکت‌های بازگردانده شده به ۱۵ را با استفاده از پارامتر 'limit' نشان می‌دهد. برای کنترل حجم داده مفید است.

```graphql
query {
  Tickets(limit: 15) {
    id
    status
  }
}

```

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

### Get Bank Accounts

Source: https://www.zarinpal.com/docs/apiDocs/query/payout

Retrieve a list of bank accounts registered in your Zarinpal user panel. This is a prerequisite for creating payout requests.

```APIDOC
## GET BankAccounts

### Description
Retrieves a list of bank accounts associated with the user's Zarinpal account. This information is needed to specify the destination for payouts.

### Method
GET

### Endpoint
/graphql

### Parameters
#### Query Parameters
- **limit** (Int) - Optional - The maximum number of bank accounts to retrieve.

### Request Example
```graphql
query {
  BankAccounts(limit: 200) {
    id
    iban
    holder_name
  }
}
```

### Response
#### Success Response (200)
- **data.BankAccounts** (Array<Object>) - A list of bank account objects.
  - **id** (String) - The unique identifier for the bank account.
  - **iban** (String) - The IBAN of the bank account.
  - **holder_name** (String) - The name of the account holder.

#### Response Example
```json
{
  "data": {
    "BankAccounts": [
      {
        "id": "1234568",
        "iban": "IR123456789123456478945165",
        "holder_name": "علی علیپور"
      }
    ]
  }
}
```
```

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

### Create Instant Payout

Source: https://www.zarinpal.com/docs/apiDocs/query/instantPayout

Initiate an instant payout from your Zarinpal balance to a specified bank account. This service allows for 'on-demand' settlements.

```APIDOC
## Create Instant Payout

### Description
Creates an instant payout request. You need to provide the terminal ID, the bank account ID, and the amount in Rials. The payout can be instantaneous to Bank آینده accounts or processed via Paya/Satna for other banks. Available from 05:00 to 23:00.

### Method
POST

### Endpoint
/graphql

### Parameters
#### Request Body
- **terminal_id** (ID!) - Required - The ID of the payment gateway terminal for which this feature is enabled.
- **amount** (BigInteger!) - Required - The payout amount in Rials.
- **bank_account_id** (ID!) - Required - The ID of the bank account registered in your Zarinpal panel.

### Request Example
```graphql
mutation InstantPayoutAdd($terminal_id: ID!, $bank_account_id: ID!, $amount: BigInteger!) {
  resource: InstantPayoutAdd(terminal_id: $terminal_id, bank_account_id: $bank_account_id, amount: $amount) {
    id
    url_code
    status
    amount
    fee
    created_at
  }
}
```

### Query Variables
```json
{
  "terminal_id": "1915487",
  "bank_account_id": "353",
  "amount": "5000000"
}
```

### Response
#### Success Response (200)
- **resource** (Object) - Details of the created instant payout.
  - **id** (String) - The unique identifier for the payout.
  - **url_code** (String) - A code related to the payout process.
  - **status** (String) - The current status of the payout (e.g., "PENDING").
  - **amount** (Integer) - The amount that was requested for payout.
  - **fee** (Integer) - The fee charged for the payout.
  - **created_at** (String) - The timestamp when the payout was created.

#### Response Example
```json
{
  "data": {
    "resource": {
      "id": "22571",
      "url_code": "9bRqG",
      "status": "PENDING",
      "amount": 5000000,
      "fee": 35000,
      "created_at": "2022-11-21T11:32:32+03:30"
    }
  }
}
```
```

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

### کوئری GraphQL با پارامترهای limit و offset

Source: https://www.zarinpal.com/docs/apiDocs/guide

این کوئری GraphQL نحوه دریافت تیکت‌ها با تعیین حداکثر تعداد (limit: 15) و نادیده گرفتن ۱۰ تیکت اول (offset: 10) را نشان می‌دهد. برای صفحه‌بندی استفاده می‌شود.

```graphql
query {
  Tickets(limit: 15, offset: 10) {
    id
    status
  }
}

```

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

### Get Terminals

Source: https://www.zarinpal.com/docs/apiDocs/query/instantPayout

Retrieve a list of payment gateway terminals (Terminal IDs) associated with your account. These IDs are needed for various API operations, including instant payouts.

```APIDOC
## Get Terminals (Terminal ID)

### Description
Retrieves a list of payment gateway terminals associated with the user's account, including their ID and domain. This information is required for using services like instant payouts.

### Method
GET

### Endpoint
/graphql

### Parameters
N/A

### Request Example
```graphql
query terminals {
  Terminals {
    id
    domain
  }
}
```

### Response
#### Success Response (200)
- **Terminals** (Array[Object]) - A list of terminal objects.
  - **id** (String) - The unique identifier for the terminal.
  - **domain** (String) - The domain associated with the terminal.

#### Response Example
```json
{
  "data": {
    "Terminals": [
      {
        "id": "1915487",
        "domain": "example.ir"
      }
    ]
  }
}
```
```

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

### ارسال کوئری GraphQL با cURL

Source: https://www.zarinpal.com/docs/apiDocs/guide

این نمونه نحوه ارسال یک کوئری GraphQL به API زرین‌پال با استفاده از ابزار cURL را نشان می‌دهد. نیاز به توکن دسترسی و یک کوئری معتبر دارد.

```shell
$ curl 'https://next.zarinpal.com/api/v4/graphql/' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  --data-binary '{"query":"query { Application { application, platform } }","variables":null}'

```

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

### User Registration (POST /api/oauth/register)

Source: https://www.zarinpal.com/docs/apiDocs/auth

Initiates the user registration process by sending user details to Zarinpal. This endpoint is used to create a new user account.

```APIDOC
## POST /api/oauth/register

### Description
Initiates the user registration process by sending user details to Zarinpal. This endpoint is used to create a new user account.

### Method
POST

### Endpoint
https://next.zarinpal.com/api/oauth/register

### Parameters
#### Request Body
- **first_name** (string) - Required - User's first name.
- **last_name** (string) - Required - User's last name.
- **cell_number** (Integer) - Required - User's mobile phone number.

### Request Example
```json
{
  "first_name": "علی",
  "last_name": "علیپور",
  "cell_number": "09123456789"
}
```

### Response
#### Success Response (200)
- **user_id** (int) - The unique Zarinpal user ID.

#### Response Example
```json
{
  "user_id": 945298
}
```

*Note: If the user already exists, an error indicating the user's existence will be returned.*
```

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

### Search Transactions (GraphQL)

Source: https://www.zarinpal.com/docs/apiDocs/query/session

Allows searching for specific transactions using various parameters such as ID, reference ID, RRN, card PAN, email, mobile number, and description. This example shows a query with multiple search parameters.

```graphql
query Sessions($terminal_id: ID, $reference_id: String,$id: ID, $card_pan: String,
$description: String, $mobile: CellNumber, $email: String, $rrn: String) {
Session(terminal_id: $terminal_id, reference_id: $reference_id, id: $id,card_pan: $card_pan,
description: $description, mobile: $mobile, email: $email, rrn: $rrn) {
id
status
amount
description
created_at
}
}
```

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

### Fetch List of Payment Gateways (GraphQL)

Source: https://www.zarinpal.com/docs/apiDocs/query/terminal

Retrieves a list of all payment gateways associated with the merchant account, along with their detailed information. This query requires no input parameters.

```graphql
query{
Terminals {
id
status
preferred_bank_account_id
domain
support_phone
key
name
logo
created_at
updated_at
}
}
```

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

### Get Reconciliations by Terminal ID

Source: https://www.zarinpal.com/docs/apiDocs/query/reconciles

Retrieve a list of reconciliations for a specific terminal ID. This query requires the terminal ID and optionally accepts a filter for reconciliation status. The response includes details such as ID, status, amount, and dates.

```graphql
query getReconciles
 		($terminal_id: ID,
 	     $filter: ReconciliationStatusEnum,
         $id: ID, $reference_id: String){
          resource: Reconciliation(
            terminal_id: $terminal_id,
            filter: $filter, id: $id,
            reference_id: $reference_id) {
    id
    status
    amount
    payable_at
    reference_id
    reconciled_at
  }
}
```

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

### ساختار پایه کوئری GraphQL

Source: https://www.zarinpal.com/docs/apiDocs/guide

نمونه‌ای از ساختار پایه‌ای یک کوئری GraphQL که برای خواندن اطلاعات از API استفاده می‌شود. با مشخص کردن نوع عملیات 'query' شروع می‌شود.

```graphql
query {

}

```

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

### Get Terminal IDs (GraphQL)

Source: https://www.zarinpal.com/docs/apiDocs/query/payout

This GraphQL query fetches terminal IDs and their associated domains. Terminal IDs are necessary for activating and managing the revenue sharing feature for specific gateways. The response includes the ID and domain for each terminal.

```graphql
query terminals {
  Terminals {
    id
    domain
  }
}
```

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

### Initialize Zarinpal API Authentication Flow

Source: https://www.zarinpal.com/docs/apiDocs/auth

This snippet shows how to initiate the authentication process for a user. It involves a POST request with the user's username and desired channel (USSD or SMS) to the initialization endpoint. The response includes details like the USSD code or waiting time.

```shell
curl 'https://next.zarinpal.com/api/oauth/initialize' \
  -H 'Content-Type: application/json' \
  --data-binary '{"username":"09123456789","channel":"ussd"}'
```

```shell
curl -X POST \
  https://next.zarinpal.com/api/oauth/initialize \
  -H 'content-type: application/json' \
  -d '{"username":"09123456789","channel":"sms"}'
```

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

### Get Bank Account IDs (GraphQL)

Source: https://www.zarinpal.com/docs/apiDocs/query/payout

This GraphQL query retrieves a list of bank accounts associated with the user's Zarinpal account. It returns the account ID, IBAN, and holder's name. This information is crucial for setting up revenue sharing.

```graphql
query{
  BankAccounts(limit: 200) {
    id
    iban
    holder_name
  }
}
```

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

### Mutation GraphQL برای افزودن کارت

Source: https://www.zarinpal.com/docs/apiDocs/guide

این mutation GraphQL نحوه افزودن یک کارت جدید با پارامترهای 'pan' و 'expired_at' را نشان می‌دهد. در صورت موفقیت، 'id' کارت جدید را برمی‌گرداند.

```graphql
mutation {
  CardAdd(pan: "1111222233334444", expired_at: "2020-02-05 00:00:00") {
    id
  }
}

```

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

### نوشتن کوئری GraphQL در یک خط

Source: https://www.zarinpal.com/docs/apiDocs/guide

این نمونه نشان می‌دهد که چگونه می‌توان یک کوئری GraphQL را در یک خط با استفاده از کاما به جای کاراکتر خط جدید نوشت. برای سادگی و فشرده‌سازی کد مفید است.

```graphql
query { Tickets { id, status } }

```

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

### Query Variables for New Gateway Request

Source: https://www.zarinpal.com/docs/apiDocs/query/terminal

Provides the necessary variables to be sent with the `TerminalAdd` mutation for requesting a new payment gateway. These variables define the properties of the gateway to be created.

```json
{"mcc_id": "186", "bank_account_id": "545", "domain": "test.ir", "support_phone": "09123456789","name": "درگاه من"}
```

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

### Get Bank Account List - GraphQL

Source: https://www.zarinpal.com/docs/apiDocs/query/bankaccount

Retrieves a list of bank accounts associated with the user's Zarinpal panel. Requires a valid API authentication. Returns account details such as ID, IBAN, status, holder name, and issuing bank information.

```graphql
query getBankAccounts {
  resource: BankAccounts{
    id
    iban
    status
    is_legal
    holder_name
    type
    issuing_bank {
      name
      slug
    }
  }
}

```

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

### Create Instant Payout - GraphQL Mutation

Source: https://www.zarinpal.com/docs/apiDocs/query/instantPayout

Creates a new instant payout request. This mutation requires the terminal ID, bank account ID, and the amount in Rials. It returns details of the created payout, including its ID, status, and fee.

```graphql
mutation InstantPayoutAdd($terminal_id: ID!, $bank_account_id: ID!, $amount: BigInteger!) {
  resource: InstantPayoutAdd(terminal_id: $terminal_id, bank_account_id: $bank_account_id, amount: $amount) {
    id
    url_code
    status
    amount
    fee
    created_at
  }
}
```

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

### ZarinPal API Refund Response Example

Source: https://www.zarinpal.com/docs/apiDocs/query/refund

This JSON object represents a successful response from the ZarinPal API after initiating a refund request. It contains details about the processed refund, including the transaction ID ('id'), the refund amount ('refund_amount'), the time the refund was processed ('refund_time'), and its current status ('refund_status'). It also includes the original transaction amount and terminal information.

```json
{
  "data": {
    "resource": {
      "terminal_id": "1915487",
      "id": "386426364",
      "amount": 20000,
      "timeline": {
        "refund_amount": 20000,
        "refund_time": "2022-11-02T15:15:37+03:30",
        "refund_status": "PENDING"
      }
    }
  }
}
```

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

### Request New Payment Gateway (GraphQL)

Source: https://www.zarinpal.com/docs/apiDocs/query/terminal

Submits a request to create a new payment gateway. This mutation requires several parameters, including business category ID, bank account ID, domain, support phone number, and the desired gateway name. It returns details of the newly created gateway.

```graphql
mutation TerminalAdd(
           $mcc_id: ID!,
           $domain: String!,
           $support_phone: CellNumber!,
           $name: String!,
           $bank_account_id: ID!)
        {
TerminalAdd(
           mcc_id:$mcc_id,
           domain:$domain,
           support_phone:$support_phone,
           name:$name,
           bank_account_id:$bank_account_id)
{
 id
mcc_id
preferred_bank_account_id
domain
support_phone
key
name
status
logo
created_at
updated_at
deleted_at
}
}
```

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

### Register User for Zarinpal API Authentication

Source: https://www.zarinpal.com/docs/apiDocs/auth

This snippet demonstrates how to register a new user for Zarinpal API authentication. It requires a POST request with user details in JSON format to the registration endpoint. Successful registration returns a user ID.

```shell
curl 'https://next.zarinpal.com/api/oauth/register' \
  -H 'Content-Type: application/json' \
  --data-binary '{"first_name": "علی","last_name": "علیپور","cell_number":"09123456789"}'
```

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

### Create Revenue Share (GraphQL Mutation)

Source: https://www.zarinpal.com/docs/apiDocs/query/payout

This GraphQL mutation, PayoutAdd, is used to create a revenue sharing request. It requires the terminal ID, bank account ID, and amount, with optional fields for description and reconciliation parts. The mutation returns details of the created revenue share.

```graphql
mutation PayoutAdd($terminal_id: ID!, $bank_account_id: ID!, $amount: BigInteger!, $description: String, $reconciliation_parts: ReconciliationPartsEnum) {
  resource: PayoutAdd(terminal_id: $terminal_id, bank_account_id: $bank_account_id, amount: $amount, description: $description, reconciliation_parts: $reconciliation_parts) {
    reconciliation_parts
    id
    url_code
    description
    status
    amount
    percent
    created_at
    updated_at
  }
}
```

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

### List Payment Gateways

Source: https://www.zarinpal.com/docs/apiDocs/query/terminal

Retrieve a list of all payment gateways associated with your account, along with their details such as status, domain, and merchant key.

```APIDOC
## GET /Terminals

### Description
Retrieves a list of payment gateways and their details.

### Method
GET

### Endpoint
/Terminals

### Parameters
#### Query Parameters
* **id** (string) - Optional - The terminal ID of the Zarinpal payment gateway.
* **status** (string) - Optional - The status of the payment gateway (e.g., ACTIVE, PENDING).
* **preferred_bank_account_id** (string) - Optional - The ID of the bank account set for settlement.
* **domain** (string) - Optional - The domain of the payment gateway.
* **support_phone** (string) - Optional - The support phone number for the payment gateway.
* **key** (string) - Optional - The merchant code (key) of the payment gateway.
* **name** (string) - Optional - The name of the payment gateway.
* **logo** (string) - Optional - The logo URL of the payment gateway.
* **created_at** (string) - Optional - The creation date of the payment gateway.
* **updated_at** (string) - Optional - The last updated date of the payment gateway.

### Response
#### Success Response (200)
- **data** (object) - Contains the list of terminals.
  - **Terminals** (array) - A list of payment gateway objects.
    - **id** (string) - The terminal ID.
    - **status** (string) - The status of the gateway.
    - **preferred_bank_account_id** (string) - The preferred bank account ID for settlement.
    - **domain** (string) - The gateway's domain.
    - **support_phone** (string) - The support phone number.
    - **key** (string) - The merchant key.
    - **name** (string) - The name of the gateway.
    - **logo** (string) - The URL of the gateway's logo.
    - **created_at** (string) - The creation timestamp.
    - **updated_at** (string) - The last update timestamp.

### Request Example
```graphql
query {
  Terminals {
    id
    status
    preferred_bank_account_id
    domain
    support_phone
    key
    name
    logo
    created_at
    updated_at
  }
}
```

### Response Example
```json
{
  "data": {
    "Terminals": [
      {
        "id": "1915487",
        "status": "ACTIVE",
        "preferred_bank_account_id": "353",
        "domain": "example.com",
        "support_phone": "09123456798",
        "key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "name": "Ali Alipour",
        "logo": "https://test.example.com/1561651asdd5f1a2sd1",
        "created_at": "2022-07-17T15:26:43+04:30",
        "updated_at": "2022-12-12T11:24:12+03:30"
      }
    ]
  }
}
```
```