Zibal IPG

https://help.zibal.ir/ipg/
Admin
Zibal IPG is an internet payment gateway service offered by Zibal for facilitating online...
Tokens:4,309
Snippets:48
Trust Score:8.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Zibal Callback JSON Example

Source: https://help.zibal.ir/ipg

This is an example of the JSON payload received by the callback URL upon a transaction.

```json
{
  "success": "1",
  "trackId": "15966442233311",
  "orderId": "1234",
  "status": null,
  "cardNumber": "62741****44",
  "hashedCardNumber": "432DA439OSD345"
}
```

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

### Start Payment

Source: https://help.zibal.ir/ipg

Use this endpoint to display the payment page and initiate the payment process.

```APIDOC
## GET /start/{trackId}

### Description
Initiates the payment process by displaying the payment page for a given tracking ID.

### Method
GET

### Endpoint
/start/{trackId}

### Parameters
#### Path Parameters
- **trackId** (string) - Required - The tracking ID obtained from the payment request.
```

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

### Callback Example

Source: https://help.zibal.ir/ipg

Illustrates how Zibal sends payment information to the callback URL via query string parameters upon status change.

```url
https://yourcallbackurl.com/callback?trackId=9900&success=1&status=2&orderId=1
```

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

### Payment Request Response

Source: https://help.zibal.ir/ipg

Example of a successful response after initiating a payment request, containing tracking and result information.

```json
{
  "trackId": 15966442233311,
  "result": 100,
  "message": "success"
}
```

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

### Send Payment Request

Source: https://help.zibal.ir/ipg

Use this endpoint to send order information and register it in the Zibal system. It returns a `trackId` for payment tracking.

```shell
curl https://gateway.zibal.ir/v1/request \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "merchant": "zibal",
  "amount": 160000,
  "callbackUrl": "http://yourapiurl.com/callback.php",
  "description": "Hello World!",
  "orderId": "ZBL-7799",
  "mobile": "09123456789"
}'
```

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

### Integrate Zibal Trust Script in Next.js

Source: https://help.zibal.ir/ipg

For Next.js projects, use the `next/script` component to load the Zibal trust script. This ensures proper script handling within the Next.js environment.

```javascript
import Script from "next/script";

<div id='zibal'>
<Script src="https://zibal.ir/trust/scripts/zibal-trust-v4.js" type="text/javascript"/>
</div>

```

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

### Test Account Authentication

Source: https://help.zibal.ir/ipg

When using the test account for development and testing, include `merchant: zibal` in your authentication payload. This snippet shows the basic structure for authentication.

```json
{
  "merchant": "zibal",
  // OTHER FIELDS
}
```

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

### Request Payment

Source: https://help.zibal.ir/ipg

Use this endpoint to submit order information and register it in the Zibal system. It returns a `trackId` as the payment tracking identifier.

```APIDOC
## POST /v1/request

### Description
Submits order information to the Zibal system to register a payment.

### Method
POST

### Endpoint
https://gateway.zibal.ir/v1/request

### Parameters
#### Request Body
- **merchant** (string) - Required - Your Zibal merchant identifier.
- **amount** (integer) - Required - The payment amount in Rials.
- **callbackUrl** (string) - Required - The URL to redirect the user to after payment.
- **description** (string) - Optional - A description for the transaction.
- **mobileNumber** (string) - Optional - The user's mobile number.
- **orderId** (string) - Optional - Your unique order identifier.

### Request Example
```json
{
  "merchant": "zibal",
  "amount": 10000,
  "callbackUrl": "https://example.com/callback",
  "description": "Order #12345",
  "orderId": "order_abc123"
}
```

### Response
#### Success Response (200)
- **trackId** (integer) - The tracking ID for the payment transaction.
- **orderId** (string) - Your unique order identifier, if provided.

#### Response Example
```json
{
  "trackId": 123456789,
  "orderId": "order_abc123"
}
```
```

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

### Request Payment

Source: https://help.zibal.ir/ipg

Use this endpoint to submit order information and register it in the Zibal system. It returns a `trackId` as the payment tracking identifier.

```APIDOC
## POST /v1/request

### Description
Submits order information to Zibal to register a payment and returns a tracking ID.

### Method
POST

### Endpoint
https://gateway.zibal.ir/v1/request

### Parameters
#### Request Body
- **merchant** (string) - Required - Identifier for authentication. Use 'zibal' for testing.
- **amount** (integer) - Required - The total amount of the order in Rials.
- **callbackUrl** (string) - Required - The URL on the merchant's site where Zibal will send payment details.
- **allowedCards** (array of strings) - Optional - A list of 16-digit card numbers if the user should only pay with specific cards.
- **checkMobileWithCard** (boolean) - Optional - Whether to match the card number with the provided mobile number.
- **description** (string) - Optional - Description of the order, shown in reports.
- **feeMode** (integer) - Optional - Fee mode: `0` for deduction from transaction, `1` for deduction from the linked wallet (not supported in payment assistance).
- **mobile** (string) - Optional - User's mobile number. If provided, registered customer card numbers will appear for selection.
- **multiplexingInfos** (array of objects) - Optional - A list of settlement items.
  - **nationalCode** (string) - Optional - 10-digit national code. If provided, the cardholder's national code is matched against this; if they don't match, the transaction is blocked.
  - **orderId** (string) - Optional - Your unique order identifier, used in reports.
  - **percentMode** (integer) - Optional - Set to `1` if your settlement method is percentage-based (default is `0`).

### Request Example
```json
{
  "merchant": "zibal",
  "amount": 160000,
  "callbackUrl": "http://yourapiurl.com/callback.php",
  "description": "Hello World!",
  "orderId": "ZBL-7799",
  "mobile": "09123456789"
}
```

### Response
#### Success Response (200)
- **trackId** (integer) - The payment tracking identifier.
- **result** (integer) - Success code (100 for success).
- **message** (string) - Success message ('success').

#### Response Example
```json
{
  "trackId": 15966442233311,
  "result": 100,
  "message": "success"
}
```
```

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

### Payment Request

Source: https://help.zibal.ir/ipg

Initiates a payment transaction through the Zibal payment gateway. Requires merchant details, amount, callback URL, description, order ID, and optionally a mobile number.

```APIDOC
## POST /v1/request

### Description
Initiates a payment transaction through the Zibal payment gateway. Requires merchant details, amount, callback URL, description, order ID, and optionally a mobile number.

### Method
POST

### Endpoint
https://gateway.zibal.ir/v1/request

### Headers
- **Content-Type** (string) - application/json

### Request Body
- **merchant** (string) - Required - The merchant identifier.
- **amount** (integer) - Required - The transaction amount in Rials.
- **callbackUrl** (string) - Required - The URL to redirect to after the transaction.
- **description** (string) - Optional - A description for the transaction.
- **orderId** (string) - Required - A unique identifier for the order.
- **mobile** (string) - Optional - The customer's mobile number.

### Request Example
```json
{
  "merchant": "zibal",
  "amount": 160000,
  "callbackUrl": "http://yourapiurl.com/callback.php",
  "description": "Hello World!",
  "orderId": "ZBL-7799",
  "mobile": "09123456789"
}
```

### Response
#### Success Response (200)
- **trackId** (string) - The transaction tracking ID.
- **status** (integer) - The status code of the transaction.
- **orderId** (string) - The order ID associated with the transaction.
```

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

### Integrate Zibal Trust Badge in Dark Mode

Source: https://help.zibal.ir/ipg

Use this script to display the Zibal trust badge in dark mode, suitable for websites with a dark theme.

```html
<script src="https://zibal.ir/trust/scripts/zibal-trust-v4.js?theme=dark" type="text/javascript"></script>
```

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

### Inquire Payment

Source: https://help.zibal.ir/ipg

Use this endpoint to inquire about a payment and retrieve payment session reports.

```APIDOC
## POST /v1/inquiry

### Description
Retrieves payment session details and reports.

### Method
POST

### Endpoint
/v1/inquiry
```

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

### Verify Payment

Source: https://help.zibal.ir/ipg

Use this endpoint to confirm the success of a payment and end a payment session.

```APIDOC
## POST /v1/verify

### Description
Confirms a successful payment and terminates the payment session.

### Method
POST

### Endpoint
/v1/verify
```

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

### Integrate Zibal Trust Badge

Source: https://help.zibal.ir/ipg

Include this script in your website's footer to display the Zibal trust badge and inform customers about secure payment processing.

```html
<script src="https://zibal.ir/trust/scripts/zibal-trust-v4.js" type="text/javascript"></script>
```

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

### Zibal Payment Transaction Request (JSON Body)

Source: https://help.zibal.ir/ipg

This is the JSON body structure for initiating a payment transaction request to the Zibal gateway. Ensure all fields are correctly populated.

```json
{
"merchant": "zibal",
"amount": 160000,
"callbackUrl": "http://yourapiurl.com/callback.php",
"description": "Hello World!",
"orderId": "ZBL-7799",
"mobile": "09123456789"
}

```

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

### Display Zibal Trust Logo (HTML Only)

Source: https://help.zibal.ir/ipg

Use this HTML code to display the Zibal trust logo without any JavaScript. This is useful for static implementations where script execution is not desired.

```html
<div>
  <a href="https://gateway.zibal.ir/trustMe/{SiteName}" target="_blank" rel="noopener">
    <img style="max-width: 110px; height: auto;" src="https://zibal.ir/trust/assets/2.png" />
  </a>
</div>

```

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

### Zibal Trust Symbol (HTML)

Source: https://help.zibal.ir/ipg

Displays the Zibal trust symbol using plain HTML. This allows users to link to a verification page.

```APIDOC
## Display Zibal Trust Symbol (HTML)

### Description
Displays the Zibal trust symbol using plain HTML. This allows users to link to a verification page.

### HTML Structure
```html
<div>
  <a href="https://gateway.zibal.ir/trustMe/{SiteName}" target="_blank" rel="noopener">
    <img style="max-width: 110px; height: auto;" src="https://zibal.ir/trust/assets/2.png" />
  </a>
</div>
```

### Parameters
- **{SiteName}** (string) - Required - Your Zibal site name, to be included in the `href` attribute.
```

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

### Lazy Verify Payment

Source: https://help.zibal.ir/ipg

Used for the lazy payment method's verification process.

```APIDOC
## POST /verify (Lazy Method)

### Description
Verifies a payment within the lazy payment method flow.

### Method
POST

### Endpoint
/verify
```

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

### Display Zibal Trust Logo with Custom Dimensions

Source: https://help.zibal.ir/ipg

Use this HTML snippet to display the Zibal trust logo. Adjust the 'height' property in the CSS to control the logo's size.

```html
<html lang='en'>  <head>
  <meta charset='UTF-8'>
  <meta name='viewport' content='width=device-width, initial-scale=1'>
  <title>Document</title>
  <style>
    #zibal{
        margin: auto;
    }
    #zibal img{
      height: 200px!important;
    }
  </style>
</head>
<body>
  <div id='zibal'>
    <script src="https://zibal.ir/trust/scripts/zibal-trust-v4.js" type="text/javascript"></script>
  </div>
</body> 
</html> 

```

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

### Lazy Request Payment

Source: https://help.zibal.ir/ipg

Used for the lazy payment method, involving different parameters and responses compared to the standard method.

```APIDOC
## POST /request/lazy

### Description
Initiates a payment request using the lazy method. This method has different request and response parameters compared to the standard payment request.

### Method
POST

### Endpoint
/request/lazy
```
Tokens:
Raw