API Reference Guide
Under this section you will find all API information that is used for processing payments.
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.
getGet Transaction Status
get
https://api.paykun.com/v1/merchant/transaction/{transaction_id}
This endpoint allows you to get transaction status with many more details
Request
Response
Request
Path Parameters
transaction_id
required
string
Transaction id for which you want to retrieve the status
Headers
MerchantId
required
string
Your merchant ID
AccessToken
required
string
Your Access Token
Response
200: OK
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"}}}
400: Bad Request
Transaction with provided ID does not exist
{"status": false,"errors": {"errorMessage": "Record does not exist","errorCode": "dataNotFound","href": "http://api.paykun.com/#error_codes"}}
getGet 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.
Request
Response
Request
Path Parameters
order_id
required
string
Your Order ID for which you want to retrieve transaction list
Headers
MerchantId
required
string
Your merchant ID
AccessToken
required
string
Your Access Token
Query Parameters
page_number
required
integer
No of a page that you want to receive
limit
required
integer
How many records you want to retrieve in one request, At a time you can get maximum of 100 records
status
optional
string
Status of the transaction that you want to retrieve, it can be any valid status. For example, Success, Failed
start_date
optional
string
If you want to retrieve record between specific time range, then provide a start date
end_date
optional
string
If you want to retrieve record between specific time range, then provide an end date
customer_email
optional
string
If you want to retrieve a record for any particular customer then provide customer email
Response
200: OK
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"}]}}
400: Bad Request
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"}]}
postRefund Transaction
post
https://api.paykun.com/v1/merchant/transaction/{transaction_id}/refund
Refund transaction using the transaction ID
Request
Response
Request
Form Data Parameters
refund_amount
required
string
Amount you want to refund to customer
remarks
required
string
Any remarks/note you want to provide for this refund
Response
200: OK
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: Bad Request
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"}}
postCreate Payment Link
post
https://api.paykun.com/v1/merchant/payment/link/create
Create payment link
Request
Response
Request
Form Data Parameters
amount
required
number
Amount that you want to collect
currency
required
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
required
string
Product/Service name
for_single_customer
required
boolean
Is this payment link created for single customer or not
customer_email
optional
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
optional
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
optional
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
optional
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
required
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
required
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
required
boolean
Set true if you want this payment link to expire automatically at specific time
expiry_date
optional
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
optional
string
Provide receipt number if any otherwise leave it empty, In any case this parameter should be present in request
note
optional
string
Provide note if any otherwise leave it empty, In any case this parameter should be present in request
Response
200: OK
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: Bad Request
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"}]}