shurjoPay RESTful API Documentation

Introduction

shurjoPay currently provides 3 RESTful API for external systems to integrate with it. They are:

  • Generate Authentication Token
  • Initiate Payment Transaction
  • Verify Payment Transaction

shurjoPay provides a sandbox system for integrators and developers to test their application or site integration before going to production (live).

Base URL of the sandbox and production environments are provided below.

  • Production: https://engine.shurjopayment.com/api
  • Sandbox: https://sandbox.shurjopayment.com/api

Note: Append actual API endpoint to the above base URL to call a specific API.

Generate Authentication Token

Before initiating the payment process, the merchant app first needs to authenticate itself using the store username and password separately shared with them during live onboarding. This API responds back with an authentication token and few other necessary information. The generated token is valid for 15 minutes.

Specification

POST /get_token

Content-Type: application/json

Accept: application/json

Request Body Fields

Field Name Data Type Description
username string Store username provided by shurjoPay. Mandatory
password string Store password provided by shurjoPay. Mandatory

Response Body Fields

Field Name Data Type Description
token string Generated token
store_id integer Merchant store Id for which payment is initiated
execute_url string Execute url for payment execution. Obsolete
token_type string Type of token. e.g. Bearer
sp_code integer Response code. 1000 for a successful response. All response code are described in Response code section
message string Remarks for the request
token_create_time string Token creation time and date
expires_in string Expire time in milliseconds

   Sample cURL Request:


curl -X POST -H "Content-Type: application/json" \
  -d '{ "username":"sp_sandbox", "password":"pyyk97hu&6u6" }' \
  https://sandbox.shurjopayment.com/api/get_token
										

   Sample Request Body:


{
    "username": "sp_sandbox",
    "password":"pyyk97hu&6u6"
}
										

   Sample Response Body


{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUz .......................................................................... 26TPliPpq4BBvGCtAAiOiJKV1QiLCJhbGAiOiJKV1QiLCJhbG",
    "store_id": 1,
    "execute_url": "https://sandbox.shurjopayment.com/api/secret-pay",
    "token_type": "Bearer",
    "sp_code": "200",
    "message": "Ok",
    "token_create_time": "2023-03-06 01:21:28pm",
    "expires_in": 3600
}
										

Initiate Payment Transaction

This API is being used whenever the customers confirm their purchase and are ready to do payment. The request body of the checkout API consists of a total of 11 mandatory fields. This API is being used whenever the customers confirm their purchase and are ready to do payment. The request body of the checkout API consists of a total of 11 mandatory fields.

Specification

POST /secret-pay

Content-Type: application/json

multipart/form-data

Request Authorization Fields:

Name Data Type Description
token string Alphanumeric token for all valid communication with shurjoPay. Need to set the header in all requests along with token_type. Mandatory

Request Body Fields:

Name Data Type Description
prefix string Provided by the shurjoPay team Mandatory
token string Alphanumeric token for all valid communication with shurjoPay Mandatory
return_url string URL to redirect customer after payment processing Mandatory
cancel_url string URL to redirect customer after payment processing is cancelled Mandatory
store_id string Store ID provided by generate token API response Mandatory
amount float Amount that the customer is paying Mandatory
order_id string Dynamically generated order ID Mandatory
currency string Currency in which payment is being made Mandatory
customer_name string Name of the customer making payment Mandatory
customer_address string Address of the customer making payment Mandatory
customer_email string Email address of the customer making payment Mandatory
customer_phone string Phone number of the customer making payment Mandatory
customer_city string City of the customer making payment Mandatory
customer_post_code string Postal code of the customer making payment
client_ip string IP address of the customer making payment
discount_amount float Total amount of discount applied to payment
disc_percent float Total percentage of discount applied to payment
customer_state string State of the customer making payment
customer_country string Country of the customer making payment
shipping_address string Shipping address of the customer making payment
shipping_city string Shipping city of the customer making payment
shipping_country string Shipping country of the customer making payment
received_person_name string Name of the person who received the shipment
shipping_phone_number string Phone number of the person who received the shipment
value1 string Additional field for product or service name, ID, etc.
value2 string Additional field for product or service name, ID, etc.
value3 string Additional field for product or service name, ID, etc.
value4 string Additional field for product or service name, ID, etc.

Response Body Fields:

Name Data Type Description
checkout_url string Checkout url for payment execution.Customer makes payment by following this url.
amount float This field will have the amount the customer is going to pay
currency string This field will have the currency in which the customer is going to pay.
sp_order_id string The sp_order_id contains shurjoPay payment id.
customer_order_id string The order_id field should be dynamically generated by the merchant.
customer_name string This field will contain the name of the customer who is trying to do the payment
customer_address string This field will contain the address of the customer who is trying to do the payment.
customer_city string This field will contain the city of the customer who is trying to do the payment.
customer_phone string This field will contain the phone number of the customer who is trying to do the payment.
customer_email string This field will contain the email of the customer who is trying to do the payment.
client_ip string This field will contain the ip of the customer device who is trying to do the payment.
intent string This field will contain the purpose of the payment.Example: Sale, Service etc.
transactionStatus string This field will contain the state of the payment.

   Sample cURL Request:


curl --location --request POST 'https://sandbox.shurjopayment.com/api/secret-pay' \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL3NhbmRib3guc2h1cmpv....................................................................................................................ZOWSIsInN1YiI6IjEiLCJwcnYiOiI4MDVmMzllZWZjYzYyN2RhZDBhMDc2YzQ5NzkzIn0.dKN8CRDaV8BkwNwGhNyUscc7PwcQKJ3oS5IXysOyUl8' \
  --form 'prefix="sp"' \
  --form 'token="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL3NhbmRib3guc2h1c...........................................................................................................................EY1ZOWSIsInN1YiI6IjEiLCJwcnYiOiI4MDVmMzllZWZjYzY4YzQ5NzkzIn0.dKN8CRDaV8BkwNwGhNyUscc7PwcQKJ3oS5IXysOyUl8"' \
  --form 'return_url="https://www.sandbox.shurjopayment.com/response"' \
  --form 'cancel_url="https://www.sandbox.shurjopayment.com/response"' \
  --form 'store_id="1"' \
  --form 'amount="10"' \
  --form 'order_id="sp315689"' \
  --form 'currency="BDT"' \
  --form 'customer_name="ATM Fahim"' \
  --form 'customer_address="dhaka"' \
  --form 'customer_phone="01717302935"' \
  --form 'customer_city="Dhaka"' \
  --form 'customer_post_code="1212"' \
  --form 'client_ip="102.101.1.1" \
  --form 'discount_amount=10' \
  --form 'disc_percent=1' \
  --form 'customer_email="test@gmail.com"' \
  --form 'customer_state="dhaka"' \
  --form 'customer_postcode="2113"' \
  --form 'customer_country="BD"' \
  --form 'shipping_address="test1"' \
  --form 'shipping_city="testcity"' \
  --form 'shipping_country="test country"' \
  --form 'received_person_name="Jon doe"' \
  --form 'shipping_phone_number="01700000000"' \
  --form 'value1="test value1"' \
  --form 'value2=' \
  --form 'value3=' \
  --form 'value4=' \'
										

   Authorization:


  “token_type”: “bearer” 
  "token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL3d3dy5kZ..................................................................................CF_10uLLM”
										

   Request Body:


{
	"prefix": "sp",
	"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL3d3dy5..................................................................................I6IkZJZ2VyVjVGendKR1FpSzAiLCJzdWIiOiIxMDYiLCJwcnYiOiI4MDVmMzllZWZjYzY4YWZkOTgyNWI0MTIyN2RhZDBhMDc2YzQ5NzkzIn0.rkdhqPK4kjs7i8nSpueFcEYUAM2VUoHdiiCF_10uLLM",
	"return_url": "https://sandbox.shurjopayment.com/response",
	"cancel_url": "https://sandbox.shurjopayment.com/response",
	"store_id": "106",
	"amount": "10",
	"order_id": "sp315689",
	"currency": "BDT",
	"customer_name": "Ayshik",
	"customer_address": "dhaka",
	"customer_phone": "01700000000",
	"customer_city": "Dhaka",
	"customer_post_code": "1212",
	"client_ip": "102.101.1.1",
	"discount_amount": "10",
	"disc_percent": "1",
	"customer_email": "test@gmail.com",
	"customer_state": "dhaka",
	"customer_postcode": "2113",
	"customer_country": "BD",
	"shipping_address": "test1",
	"shipping_city": "testcity",
	"shipping_country": "test country",
	"received_person_name": "Jon doe",
	"shipping_phone_number": "01700000000",
	"value1": "test value1",
	"value2": "",
	"value3": "",
	"value4": "",
}

										

   Response Body:


{
	"checkout_url": "https://sandbox.securepay.shurjopayment.com/spaycheckout/?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL3NhbmRib3guc2h1cmpvcGF5bWVudC5......................................................................................................OiI4MDVmMzllZWZjYzY4YWZkOTgyNWI0MTIyN2RhZDBhMDc2YzQ5NzkzIn0.CGhyvcnJTohihf6Yx5xKTPZUpWBZQF2Z55DHXThNpfY&order_id=sp6405ae1473f63",
	"amount": 150,
	"currency": "BDT",
	"sp_order_id": "sp6405ae1473f63",
	"customer_order_id": "785247254",
	"customer_name": "Jon Due",
	"customer_address": "Dhaka",
	"customer_city": "Dhaka",
	"customer_phone": "01785478158",
	"customer_email": “test@gmail.com”,
	"client_ip": "192.168.10.35",.
	"intent": "sale",
	"transactionStatus": "Initiated"
}
										

Verify Payment Transaction

This verify order API is being used to get all the necessary response data of an order. It is also mandatory for customising the “return_url” UI with customer’s order’s information from the merchant's end.

Specification

POST /verification

Content-Type: application/json

application/json

Request Authorization Fields:

Name Data Type Description
token string Alphanumeric token for all valid communication with shurjoPay. Need to set the header in all requests along with token_type. Mandatory

Request Body Fields:

Name Data Type Description
order_id string verification, merchants must use order_id(shurjoPay payment id) that is sent from shurjoPay during call back. Mandatory

Response Body Fields:

Field Name Data Type Description
id integer This field contain unique identification
order_id string Verification, merchants must use order_id(shurjoPay payment id) that is sent from shurjoPay during call back
currency string This field will have the currency in which the customer is going to pay.
amount float This field will have the amount the customer make payment
payable_amount float This field contains a total payable amount.
discount_amount float This field contains a total discounted amount.
disc_percent float This field contains a total discounted percent.
received_amount float This field contain amount which received by shurjoPay
usd_amt float If someone pays in other currency without BDT then it is converted to USD.
usd_rate float This field contains payment time USD to BDT rate
method string This field contains payment methods like bank cards, mobile wallets etc.
sp_message string Response code. 1000 for a successful response. All response code are described in Response code section
sp_code integer This parameter needs to be checked before updating the merchant's database.
1000 : A successful transaction.
1001 : Transaction is declined by customer's Issuer Bank.
1002 : Transaction is canceled by the customer. For more details please check Response codes
name string This Field contains the customer name, Who made the payment.
email string This Field contains the customer email, Who made the payment.
address string This field contains the customer address who made the payment.
city string This field contains the customer city who made the payment.
value1 string This field can contain additional information such as product name, service name, service ID, etc.
value2 string This field can contain additional information such as product name, service name, service ID, etc.
value3 string This field can contain additional information such as product name, service name, service ID, etc.
value4 string This field can contain additional information such as product name, service name, service ID, etc.

   Sample cURL Request:


curl --location --request POST 'https://www.sandbox.shurjopayment.com/api/verification' \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL3NhbmRib3gu...........................................................................................................................1ZOWSIsInN1YiI6IjEiLCJwcnYiOiI4MDVmMzllZWZjYzY4YWZkOTgyNWI0MTIyN2RhZDBhMDc2YzQ5NzkzIn0.dKN8CRDaV8BkwNwGhNyUscc7PwcQKJ3oS5IXysOyUl8' \
  --header 'Content-Type: application/json' \
  --data '{
  "order_id":"spay612b73a935ab1"
  }'
										

   Authorization:


  “token_type”: “bearer” 
  "token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL3d3dy5kZ..................................................................................CF_10uLLM”
										

   Request Body:


{  "order_id":"sp6405c8f848b27"  }
										

   Response Body:


[
    {
        "id": 1109600,
        "order_id": "sp6405c8f848b27",
        "currency": "BDT",
        "amount": "10.0000",
        "payable_amount": "9.9000",
        "discount_amount": "0.0000",
        "disc_percent": 1,
        "recived_amount": "0.0000",
        "usd_amt": "0.0000",
        "usd_rate": 0,
        "card_holder_name": null,
        "card_number": null,
        "phone_no": null,
        "bank_trx_id": "0",
        "invoice_no": "sp6405c8f848b27",
        "bank_status": "Cancel",
        "customer_order_id": "sp315689",
        "sp_code": "1002",
        "sp_massage": "Cancel",
        "sp_message": "Cancel",
        "name": "Ayshik",
        "email": "test@gmail.com",
        "address": "dhaka",
        "city": "Dhaka",
        "value1": "test value1",
        "value2": null,
        "value3": null,
        "value4": null,
        "transaction_status": "Cancelled",
        "method": null,
        "date_time": "2023-03-06 17:06:19"
    }
]
										
Last Updated: Mon, 17-April-2023