Zarinpal

https://www.zarinpal.com/docs
Admin
Zarinpal is an online payment gateway providing secure and easy-to-use payment processing solutions...
Tokens:108,543
Snippets:424
Trust Score:10
Update:7 months ago
Show doc for...
Tokens:
Raw
### GraphQL Query with Parameters

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

Demonstrates how to pass parameters to a GraphQL query to filter or limit the results. This example shows how to use 'limit' and 'offset' parameters with the 'Tickets' query to control the number of tickets returned and the starting point of the results.

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

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

### Example Query Variables for Revenue Sharing

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

These are example variables to be used with the `PayoutAdd` GraphQL mutation. They demonstrate how to provide the necessary parameters like terminal ID, bank account ID, amount, and description for creating a revenue sharing request.

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

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

### Example GraphQL Response for Invoice Status

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

This is an example JSON response received when querying for invoice statuses without specifying a particular invoice ID. It lists multiple invoices, each with their status, description, and details of their payment sessions.

```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 Mutation for Adding a Card

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

Shows how to perform a data modification operation (mutation) using GraphQL. This example demonstrates the 'CardAdd' mutation, which requires parameters like 'pan' and 'expired_at'. It also shows how to specify the fields you want to receive back upon successful execution of the mutation.

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

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

### GraphQL Queries

Source: https://www.zarinpal.com/docs/howToUse

Queries are used to fetch data from the API without making any changes. They start with the 'query' keyword and specify the desired fields.

```APIDOC
## GraphQL Queries

### Description
Queries are used to retrieve data. You define the type of operation as 'query' and specify the fields you want to retrieve.

### Method
POST

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

### Request Body
- **query** (string) - Required - The GraphQL query string.

### Request Example (Fetching Tickets)
```json
{
  "query": "query { Tickets { id, status } }"
}
```

### Request Example (Fetching Tickets with Limit and Offset)
```json
{
  "query": "query { Tickets(limit: 15, offset: 10) { id, status } }"
}
```

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

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

### GraphQL Query for List of Objects

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

A GraphQL query example to fetch a list of 'Ticket' objects. The schema indicates that the 'Tickets' field will return a non-nullable list of non-nullable 'Ticket' objects.

```graphql
query {
  Tickets: [Ticket!]
}
```

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

### Get Bank Accounts

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

Retrieve a list of registered bank accounts associated with the user's panel. This is a prerequisite for setting up instant payouts.

```APIDOC
## GET /websites/zarinpal/bank_accounts

### Description
Retrieves a list of bank accounts registered in the user's Zarinpal panel, including their IDs, IBANs, and account holder names.

### Method
GET

### Endpoint
/websites/zarinpal/bank_accounts

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

### Response
#### Success Response (200)
- **data.BankAccounts** (Array) - An array 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": "علی علیپور"
      }
    ]
  }
}
```
```

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

### افزودن مخزن Maven به settings.gradle

Source: https://www.zarinpal.com/docs/sdk/android/installation

این کد مخزن Maven jitpack.io را به تنظیمات Gradle پروژه شما اضافه می‌کند. این مخزن برای دریافت کتابخانه‌های شخص ثالث مانند Android SDK زرین‌پال ضروری است. این بخش باید در فایل settings.gradle پروژه شما قرار گیرد.

```gradle
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        ... 
        maven { url = uri("https://jitpack.io") }
        }
    }
```

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

### GraphQL Mutations

Source: https://www.zarinpal.com/docs/howToUse

Mutations are used to modify data on the server. They start with the 'mutation' keyword and specify the operation and any required parameters.

```APIDOC
## GraphQL Mutations

### Description
Mutations are used to create, update, or delete data. They start with the 'mutation' keyword and specify the operation and its arguments.

### Method
POST

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

### Request Body
- **query** (string) - Required - The GraphQL mutation string.

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

### Response Example (CardAdd)
```json
{
  "data": {
    "CardAdd": {
      "id": "some_card_id"
    }
  }
}
```
```

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

### افزودن وابستگی کتابخانه Android SDK زرین‌پال به build.gradle

Source: https://www.zarinpal.com/docs/sdk/android/installation

این کد وابستگی کتابخانه Android SDK زرین‌پال را به فایل build.gradle پروژه شما اضافه می‌کند. این کار امکان استفاده از قابلیت‌های زرین‌پال در برنامه اندرویدی شما را فراهم می‌آورد. اطمینان حاصل کنید که minSdkVersion پروژه شما 24 یا بالاتر است.

```gradle
dependencies {
		implementation("com.github.ZarinPal:Android-SDK-Kotlin:v.1.1.2")
}
```

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

### Query Variables for Instant Zarinpal Refund (CARD)

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

Example query variables for initiating an instant refund via Zarinpal's service. The 'method' is set to 'CARD', ensuring the refund is processed immediately. Requires transaction ID, amount, description, and reason.

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

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

### GraphQL Query for List of Scalar Values

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

A GraphQL query example to fetch a list of integers. The schema specifies that the 'Numbers' field will return a list where each element is a non-nullable integer.

```graphql
query {
  Numbers: [Int!]
}
```

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

### Configure Zarinpal PHP SDK with Merchant ID and Access Token

Source: https://www.zarinpal.com/docs/sdk/php/configuration

This snippet demonstrates how to initialize the Zarinpal SDK in PHP. It includes setting the merchant ID, access token, sandbox mode, and configuring HTTP client plugins for handling payment requests and verifications. Ensure you replace the placeholder values with your actual credentials.

```php
<?php

use ZarinPal\Sdk\Options;
use ZarinPal\Sdk\ZarinPal;
use ZarinPal\Sdk\ClientBuilder;
use Http\Client\Common\Plugin\HeaderDefaultsPlugin;

$clientBuilder = new ClientBuilder();
$clientBuilder->addPlugin(new HeaderDefaultsPlugin([
    'Accept' => 'application/json',
]));

$options = new Options([
    'client_builder' => $clientBuilder,
    'merchant_id'    => 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    'access_token'   => 'your-access-token-here',
    'sandbox'        => false,
]);

$zarinpal = new ZarinPal($options);


```

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

### GraphQL Query with Limit Parameter

Source: https://www.zarinpal.com/docs/howToUse

Shows how to use the 'limit' parameter within a GraphQL query to control the maximum number of items returned. This example limits the 'Tickets' query to 15 results.

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

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

### GraphQL Query Structure with Operation Name

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

Shows how to define a GraphQL query with a specific operation name. This is useful for debugging and when you have multiple operations in a single request. The example uses 'Tickets' as the operation name.

```graphql
query {
  Tickets {

  }
}
```

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

### Create ZarinPal Payment Request and Redirect (Kotlin)

Source: https://www.zarinpal.com/docs/sdk/android/method/request

This Kotlin code snippet demonstrates how to create a new payment request using the ZarinPal SDK. It sends payment details like amount, description, and callback URL, and then uses the received authority to generate a redirect URL for the user to complete the payment.

```kotlin
import com.example.zarinpal.Zarinpal
import com.example.zarinpal.data.remote.dto.create.CreatePaymentDataResponse
import com.example.zarinpal.data.remote.dto.create.CreatePaymentRequest

val request = CreatePaymentRequest(
                amount = 20000,
                callbackUrl = "https://yourwebsite.com/callback",
                description = "test"
            )

CoroutineScope(Dispatchers.IO).launch {
  try{
    val response = 
          zarinPal.createPayment(request, redirectUrl = {  paymentGatewayUri, status ->
              if (status == 100)
              Log.v("ZP_Log",paymentGatewayUri)
          })
     Log.v("ZP_Log","$response")
  } catch (ex: Exception) {
    ex.printStackTrace()
  }
}

```

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

### POST /createPayment

Source: https://www.zarinpal.com/docs/sdk/android/method/request

Creates a new payment request and returns an authority code to redirect the user to the payment gateway.

```APIDOC
## POST /createPayment

### Description
Creates a new payment request and returns an authority code to redirect the user to the payment gateway. This method is used to send payment-related information and obtain an `authority` for redirecting the user to the payment page.

### Method
POST

### Endpoint
/createPayment

### Parameters
#### Request Body
- **amount** (Integer) - Required - The payment amount in Rials. Minimum amount is 10000 Rials.
- **description** (String) - Required - Description of the transaction, such as order number or product name.
- **callback_url** (String) - Required - The return URL after successful or failed payment.
- **mobile** (String) - Optional - User's mobile number.
- **email** (String) - Optional - User's email address.
- **referrer_id** (String) - Optional - Referrer ID.
- **currency** (String) - Optional - The currency unit for the transaction. Default is `IRR` (Rial), other option is `IRT` (Toman).
- **cardPan** (String) - Optional - The bank card number the user will pay with.
- **wages** (Array) - Optional - An array containing profit sharing information. Each element includes `iban` (IBAN), `amount` (amount), and `description` (description).

### Request Example
```json
{
  "amount": 20000,
  "description": "test",
  "callbackUrl": "https://yourwebsite.com/callback"
}
```

### Response
#### Success Response (200)
- **authority** (String) - The authority code obtained from ZarinPal.
- **redirectUrl** (String) - The final payment URL to redirect the user to.

#### Response Example
```json
{
  "authority": "some_authority_code",
  "redirectUrl": "https://www.zarinpal.com/pg/StartPay/some_authority_code"
}
```
```

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

### Get Payout Status

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

Check the status of previously created instant payouts. You can query for a specific payout by its ID or get a list based on the terminal ID.

```APIDOC
## GET /websites/zarinpal/instant_payouts

### Description
Retrieves the status of instant payouts. You can fetch details for a specific payout using its ID or retrieve payouts associated with a terminal ID.

### Method
GET

### Endpoint
/websites/zarinpal/instant_payouts

### Query Parameters
- **terminal_id** (ID) - Optional - The ID of the payment gateway.
- **id** (ID) - Optional - The unique identifier of a specific payout transaction.

### Response
#### Success Response (200)
- **data.resource** (Array) - An array of payout objects.
  - **id** (String) - The unique identifier for the payout.
  - **url_code** (String) - A code associated with the payout.
  - **status** (String) - The status of the payout (e.g., PAID, PENDING, IN_PROGRESS, REVERSED, REJECTED).
  - **description** (String) - Additional details or description for the payout.
  - **amount** (Int) - The amount of the payout in Rials.
  - **fee** (Int) - The fee charged for the payout.
  - **reference_id** (String) - A reference number for the transaction.
  - **reconciled_at** (String) - The timestamp when the 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"
      }
    ]
  }
}
```
```

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

### Query Variables for Labeled Payment Creation

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

This JSON object provides example variables for the `InvoiceAdd` GraphQL mutation. It includes values for terminal ID, amount, fee type, description, payer details, and notification preferences. These variables are essential for successfully creating a labeled payment.

```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"
}
```

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

### Zarinpal unVerified API Response Example

Source: https://www.zarinpal.com/docs/paymentGateway/otherMethods/unVerified

This is an example of the JSON response returned by the Zarinpal unVerified API. It includes a success code, a message, and a list of unverified transaction authorities with their details.

```json
{
  "data": {
    "code": "100",
    "message": "Success",
    "authorities": [
      {
        "authority": "A0000000000000000000000000000wwOGYpd",
        "amount": 50500,
        "callback_url": "https://test.com/vpay",
        "referer": "https://example.com/test-form/",
        "date": "2020-07-01 17:33:25"
      },
      {
        "authority": "A00000000000000000000000000207296508",
        "amount": 50500,
        "callback_url": "https://test.com/vpay",
        "referer": "https://example.com/test-form/",
        "date": "2020-07-01 18:58:32"
      },
      {
        "authority": "A00000000000000000000000000206875420",
        "amount": 11100,
        "callback_url": "zarin_link",
        "referer": "/",
        "date": "2020-06-27 10:22:02"
      }
    ]
  }
}
```

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

### Example Zarinpal Refund Response

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

This is an example of the response received from Zarinpal after a refund request is processed. It includes the transaction ID, amount, terminal information, and a timeline detailing the refund amount, time, and status.

```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"
      }
    }
  }
}
```

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

### Configure ZarinPal Node.js SDK with Merchant ID and Access Token

Source: https://www.zarinpal.com/docs/sdk/nodejs/configuration

Initialize the ZarinPal Node.js SDK by providing your merchant ID, setting the sandbox mode (true for testing, false for production), and optionally including an access token for advanced operations like refunds and transaction management. The merchant ID is obtained from the ZarinPal gateway settings, and the access token from active sessions.

```javascript
import { ZarinPal } from 'zarinpal-node-sdk';

const zarinpal = new ZarinPal({
  merchantId: 'your-merchant-id',
  sandbox: true,
  accessToken: 'your-access-token',
});

```

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

### Initialization API

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

Initiates the authentication process for a user. This endpoint requires the user's username and an optional channel for receiving the OTP.

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

### Description
Initiates the authentication process by sending an OTP to the user via the specified channel.

### Method
POST

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

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **username** (string) - Required - User's email address or mobile number.
- **channel** (string('ussd', 'sms')) - Optional - The channel to receive the OTP (defaults to 'ussd').

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

### Response
#### Success Response (200)
- **avatar** (string) - URL of the user's avatar.
- **channel** (string('ussd', 'sms')) - The channel used for OTP delivery.
- **ussd_code** (string) - The USSD code to dial for OTP (empty if channel is 'sms').
- **waiting_time** (integer) - Time in seconds before the user can request OTP again.
- **otp_time_diff** (integer) - Time difference for OTP validity.

#### 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
}
```
```

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

### Basic GraphQL Query Structure

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

Illustrates the fundamental structure of a GraphQL query. It shows how to define a 'query' operation and specify the fields you want to retrieve from a given type, such as 'Tickets'. This basic structure is the foundation for more complex queries.

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

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

### Get Bank Accounts

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

Retrieve a list of bank accounts added to your Zarinpal user panel.

```APIDOC
## GET /websites/zarinpal/bankAccounts

### Description
Retrieves a list of bank accounts associated with the user's Zarinpal account.

### Method
GET

### Endpoint
/websites/zarinpal/bankAccounts

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **resource** (array) - A list 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's 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 unique slug 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"
        }
      }
    ]
  }
}
```
```

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

### POST /pg/v4/payment/request.json

Source: https://www.zarinpal.com/docs/paymentGateway/connectToGateway

Submit transaction details to initiate a payment request. This is the first step in the payment process.

```APIDOC
## POST /pg/v4/payment/request.json

### Description
Initiates a payment request by sending transaction details to Zarinpal.

### Method
POST

### Endpoint
`https://payment.zarinpal.com/pg/v4/payment/request.json`

### Parameters
#### Request Body
- **merchant_id** (String) - Required - Your unique 36-character merchant ID.
- **amount** (Integer) - Required - The transaction amount.
- **currency** (String) - Optional - The currency unit (e.g., 'IRR' for Rial, 'IRT' for Toman).
- **description** (String) - Required - A description of the transaction.
- **callback_url** (String) - Required - The URL to redirect the customer to after payment.
- **referrer_id** (String) - Optional - A referrer ID.
- **metadata** (Object) - Optional - Additional metadata.
  - **mobile** (String) - Optional - Buyer's mobile number.
  - **email** (String) - Optional - Buyer's email address.
  - **order_id** (String) - Optional - Order ID.

### Request Example
```json
{
  "merchant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "amount": 1100,
  "currency": "IRR",
  "description": "Transaction description.",
  "callback_url": "http://example.com/verify",
  "referrer_id": "xxxx",
  "metadata": {
    "mobile": "09121234567",
    "email": "info.test@example.com",
    "order_id": "12345"
  }
}
```

### Response
#### Success Response (200)
- **data** (Object) - Contains transaction details.
  - **code** (Integer) - Response code (100 for success).
  - **message** (String) - Response message ('Success').
  - **authority** (String) - A unique authority code for the transaction.
  - **fee_type** (String) - The type of fee applied ('Merchant').
  - **fee** (Integer) - The transaction fee amount.
- **errors** (Array) - An array of errors, empty if successful.

#### Response Example
```json
{
  "data": {
    "code": 100,
    "message": "Success",
    "authority": "A0000000000000000000000000000wwOGYpd",
    "fee_type": "Merchant",
    "fee": 100
  },
  "errors": []
}
```
```

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

### Query Variables for Normal Zarinpal Refund (PAYA)

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

Example query variables for initiating a normal refund via Zarinpal's service. The 'method' is set to 'PAYA', indicating the refund will be processed in the next PAYA cycle. Requires transaction ID, amount, description, and reason.

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

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

### 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 the identified payment service.

```APIDOC
## GET /query terminals

### Description
Retrieves a list of available terminals and their associated domains.

### Method
GET

### Endpoint
`/query terminals`

### Parameters
#### Query Parameters
None

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

### Response
#### Success Response (200)
- **data** (object) - Contains the list of terminals.
  - **Terminals** (array) - A 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"
      }
    ]
  }
}
```
```
Tokens:
Raw