API Reference Guide

Under this section you will find all API information that is used for processing payments.

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.

See How signature generation and verification work.

Get Transaction Status

GET 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

200 Transaction Details Successfully Retrieved.

{
    "status": true,
    "data": {
        "message": "Record retrieved successfully",
        "transaction": {
            "payment_id": "88253-41453-72735-05390",
            "merchant_email": "[email protected]",
            "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": "[email protected]",
                "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"
        }
    }
}

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

Get Order Details

GET 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

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": "[email protected]",
                "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"
            }
        ]
    }
}

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

Refund Transaction

POST 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

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

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

Create Payment Link

POST 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

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

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