# 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](https://docs.paykun.com/technical-guide/api-encryption-key-guide).
See How [signature generation and verification work](https://docs.paykun.com/technical-guide/signature-generation-and-verification).
## 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 |
{% 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
`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 |
{% 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
`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 |
{% 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
`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 |
{% 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 %}