# API Reference Guide

## Authentication

All Paykun APIs requires MerchantId & AccessToken headers to be present for authentication purpose, Same can be found from merchant dashboard. Some APIs also requires you to add a  signature in the request body for the purpose of ensuring authenticity.

See How to generate [Access Token & Encryption Key](/technical-guide/api-encryption-key-guide.md).

See How [signature generation and verification work](/technical-guide/signature-generation-and-verification.md).

## Get Transaction Status

<mark style="color:blue;">`GET`</mark> `https://api.paykun.com/v1/merchant/transaction/{transaction_id}`

This endpoint allows you to get transaction status with many more details

#### Path Parameters

| Name            | Type   | Description                                              |
| --------------- | ------ | -------------------------------------------------------- |
| transaction\_id | string | Transaction id for which you want to retrieve the status |

#### Headers

| Name        | Type   | Description       |
| ----------- | ------ | ----------------- |
| MerchantId  | string | Your merchant ID  |
| AccessToken | string | Your Access Token |

{% tabs %}
{% tab title="200 Transaction Details Successfully Retrieved." %}

```
{
    "status": true,
    "data": {
        "message": "Record retrieved successfully",
        "transaction": {
            "payment_id": "88253-41453-72735-05390",
            "merchant_email": "merchantemail@gmail.com",
            "merchant_id": "01234567890123",
            "status": "Success",
            "status_flag": 1,
            "payment_mode": "WALLET",
            "order": {
                "order_id": "15707057419885",
                "product_name": "Product Name",
                "gross_amount": 11,
                "gateway_fee": 0.22,
                "tax": 0.04
            },
            "customer": {
                "name": "Customer Name",
                "email_id": "test@gmail.com",
                "mobile_no": "0213456789"
            },
            "shipping": {
                "address": null,
                "city": null,
                "state": null,
                "country": null,
                "pincode": null
            },
            "billing": {
                "address": null,
                "city": null,
                "state": null,
                "country": null,
                "pincode": null
            },
            "custom_field_1": null,
            "custom_field_2": null,
            "custom_field_3": null,
            "custom_field_4": null,
            "custom_field_5": null,
            "date": "1581769083",
            "signature": "e08bf1fcaf01d5fa4198de47d08a0158a9526b9e341e8a53bb8d3373b9268861f0bc0c363e60371e0f723558296f23ec43de8aceafd833498d2cf94bf8032b64"
        }
    }
}
```

{% endtab %}

{% tab title="400 Transaction with provided ID does not exist" %}

```
{
    "status": false,
    "errors": {
        "errorMessage": "Record does not exist",
        "errorCode": "dataNotFound",
        "href": "http://api.paykun.com/#error_codes"
    }
}
```

{% endtab %}
{% endtabs %}

## Get Order Details

<mark style="color:blue;">`GET`</mark> `https://api.paykun.com/v1/merchant/orders/{order_id}`

Retrieve transaction list using order id, as this may return multiple transactions you can provide filters to narrow down search results.

#### Path Parameters

| Name      | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| order\_id | string | Your Order ID for which you want to retrieve transaction list |

#### Query Parameters

| Name            | Type    | Description                                                                                                   |
| --------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| signature       | string  | Generate signature for all query parameters available in URL                                                  |
| page\_number    | integer | No of a page that you want to receive                                                                         |
| limit           | integer | How many records you want to retrieve in one request, At a time you can get maximum of 100 records            |
| status          | string  | Status of the transaction that you want to retrieve, it can be any valid status. For example, Success, Failed |
| start\_date     | string  | If you want to retrieve record between specific time range, then provide a start date                         |
| end\_date       | string  | If you want to retrieve record between specific time range, then provide an end date                          |
| customer\_email | string  | If you want to retrieve a record for any particular customer then provide customer email                      |

#### Headers

| Name        | Type   | Description       |
| ----------- | ------ | ----------------- |
| MerchantId  | string | Your merchant ID  |
| AccessToken | string | Your Access Token |

{% tabs %}
{% tab title="200 On success API call you will get the following response, this endpoint provides a record in pagination, so you will get pagination data like current page number, last page number, is last page. use this data to retrieve the next pages." %}

```
{
    "status": true,
    "data": {
        "message": "Record retrieved successfully",
        "total_orders": 1,
        "is_last": true,
        "current_item_count": 1,
        "current_page": 1,
        "last_page": 1,
        "orders": [
            {
                "req_id": "99850-39895-28080-59252",
                "product_name": "Membership Fee",
                "gross_amount": 1700,
                "status": "Success",
                "status_flag": 0,
                "customer_name": "Customer Name",
                "customer_email_id": "test@gmail.com",
                "customer_mo_no": "1234567890",
                "shipping_address": null,
                "shipping_city": null,
                "shipping_state": null,
                "shipping_country": null,
                "shipping_pincode": null,
                "billing_address": null,
                "billing_city": null,
                "billing_state": null,
                "billing_country": null,
                "billing_pincode": null,
                "order_id": "0000000030",
                "custom_field_1": null,
                "custom_field_2": null,
                "custom_field_3": null,
                "custom_field_4": null,
                "custom_field_5": null,
                "timestamp": "02/04/2019 10:40:35 AM",
                "timestamp_original": "2019-04-02 05:10:35"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="400 This error will be returned when the required field is not provided or in case of other validation error" %}

```
{
    "status": false,
    "errors": [
        {
            "field": "page_number",
            "errorMessage": "Please provide page number",
            "errorCode": "validationError",
            "href": "http://api.paykun.com/#error_codes"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Refund Transaction

<mark style="color:green;">`POST`</mark> `https://api.paykun.com/v1/merchant/transaction/{transaction_id}/refund`

Refund transaction using the transaction ID

#### Headers

| Name        | Type   | Description       |
| ----------- | ------ | ----------------- |
| MerchantId  | string | Your Merchant ID  |
| AccessToken | string | Your Access Token |

#### Request Body

| Name           | Type   | Description                                                         |
| -------------- | ------ | ------------------------------------------------------------------- |
| refund\_amount | string | Amount you want to refund to customer                               |
| remarks        | string | Any remarks/note you want to provide for this refund                |
| signature      | string | Generate signature with using refund\_amount and remarks parameters |

{% tabs %}
{% tab title="200 On successful refund, you will get refund id for future tracking" %}

```
{
    "status": true,
    "data": {
        "message": "Your refund is successfully processed",
        "refund_ref_no": "68284-82388-16633-62514"
    }
}
```

{% endtab %}

{% tab title="400 This error will be returned when the required field is not provided or in case of other validation error" %}

```
# Validation Error
{
    "status": false,
    "errors": [
        {
            "field": "refund_amount",
            "errorMessage": "Please provide refund amount",
            "errorCode": "validationError",
            "href": "http://api.paykun.com/#error_codes"
        }
    ]
}

# Refund amount is higher then transaction amount 
{
    "status": false,
    "errors": {
        "errorMessage": "Refund is not possible as refund amount is greater then transaction amount",
        "errorCode": "refundNotAllowed",
        "href": "http://api.paykun.com/#error_codes"
    }
}
```

{% endtab %}
{% endtabs %}

## Create Payment Link

<mark style="color:green;">`POST`</mark> `https://api.paykun.com/v1/merchant/payment/link/create`

Create payment link

#### Headers

| Name         | Type   | Description       |
| ------------ | ------ | ----------------- |
| MerchantId   | string | Your Merchant ID  |
| AccessToken  | string | Your Access Token |
| Content-Type | string | application/json  |

#### Request Body

| Name                  | Type    | Description                                                                                                                                                                                                                                           |
| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| failure\_url          | string  | if you want to redirect customer to your website on payment cancellation then provide the URl or leave it blank                                                                                                                                       |
| success\_url          | string  | If you want to redirect customer to your website on successful payment then provide the URL or leave it bank                                                                                                                                          |
| signature             | string  | Generate signature for all your parameters available in your form data                                                                                                                                                                                |
| amount                | number  | Amount that you want to collect                                                                                                                                                                                                                       |
| currency              | string  | Currency in which payment is to be collected. Default should be set to INR, other value is only supported is international transactions is activated for your account                                                                                 |
| payment\_for          | string  | Product/Service name                                                                                                                                                                                                                                  |
| for\_single\_customer | boolean | Is this payment link created for single customer or not                                                                                                                                                                                               |
| customer\_email       | string  | This field is required in case for\_single\_customer is set to true otherwise leave it empty, In any case this parameter should be present in request.                                                                                                |
| customer\_mono        | string  | This field is required in case for\_single\_customer is set to true otherwise leave it empty, In any case this parameter should be present in request                                                                                                 |
| customer\_fname       | string  | This field is required in case for\_single\_customer is set to true otherwise leave it empty, In any case this parameter should be present in request                                                                                                 |
| customer\_lname       | string  | This field is required in case for\_single\_customer is set to true otherwise leave it empty, In any case this parameter should be present in request                                                                                                 |
| notify\_by\_email     | boolean | If you want to notify customer via E-Mail then set this true, this can be true only if for\_single\_customer is true                                                                                                                                  |
| notify\_by\_sms       | boolean | If you want to notify customer via SMS then set this true, this can be true only if for\_single\_customer is true                                                                                                                                     |
| can\_expire           | boolean | Set true if you want this payment link to expire automatically at specific time                                                                                                                                                                       |
| expiry\_date          | string  | Date & time when this link should expire, This is required in case can\_expire is set to true otherwise leave it empty, In any case this parameter should be present in request. Format of date & time should be in d-m-Y H:i:s (15-07-2020 18:30:00) |
| receipt\_no           | string  | Provide receipt number if any otherwise leave it empty, In any case this parameter should be present in request                                                                                                                                       |
| note                  | string  | Provide note if any otherwise leave it empty, In any case this parameter should be present in request                                                                                                                                                 |

{% tabs %}
{% tab title="200 Payment link is created succesfully" %}

```
{
    "status": true,
    "data": {
        "message": "Payment link is created successfully",
        "payment_link_id": "WDAJyp1",
        "payment_link": "https://paykun.in/WDAJyp1"
    }
}
```

{% endtab %}

{% tab title="400 this error will be returned when any required field is not provided or in case of other validation error " %}

```
{
    "status": false,
    "errors": [
        {
            "field": "expiry_date",
            "errorMessage": "Expiry date should be future date",
            "errorCode": "validationError",
            "href": "http://api.paykun.com/#error_codes"
        }
    ]
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.paykun.com/technical-guide/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.