shurjoPay RESTful API

Generate Token API:

What does the “generate token API” do?
To initiate the payment process, the merchant has to authenticate via the given username and password with the “generate token API” and the “generate token API” will respond back with a token and store_id and other necessary information. The token is valid till 15 minutes after it is created.

Generate Token API:

Method Token
POST Live: https://engine.shurjopayment.com/api/get_token
Sandbox: https://sandbox.shurjopayment.com/api/get_token

Request Body Parameters of Generate Token API:

Generate Token API request body fields:
  • username: Sandbox demo username is: “sp_sandbox”. For live “generate token API” url usage: the username will be provided to the merchant by the shurjoPay team.
  • password: Sandbox demo password is: “pyyk97hu&6u6”. For live “generate token API” url usage: the password will be provided to the merchant by the shurjoPay team.

Type Name Data Type MOC (Mandatory / Optional / Conditional) Length Description
Request body username string Mandatory 128
password string Mandatory 15

Response Body Parameters of Generate Token API:

Type Name Data Type MOC (Mandatory / Optional / Conditional) Length Description
Request body token string 128 Alphanumeric token for all valid communication with shurjoPay. Need to set in header in all request alone with token_type
store_id int Merchant store id for which payment is initiated
execute_url url Execute url for payment execution. Merchants need to post all payment data in this url for payment next after payment initialization.
token_type string Type of token. Like Bearer
sp_code integer Response code. 1000 for a successful response. All response code are described in Response code section
message string
expires_in integer Expire time in milliseconds 
								

									

										
   API Link:
	
	API Link: https://sandbox.shurjopayment.com/api/get_token
 
	Method: POST
	
										

										
   Body:

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

									

										
   Responce:

										
{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL3NhbmRib3guc2h1cmpvcGF5bWVudC5jb20vYXBpL2xvZ2luIiwia
	WF0IjoxNjY1OTE0ODc1LCJleHAiOjE2NjU5MTg0NzUsIm5iZiI6MTY2NTkxNDg3NSwianRpIjoiV3JFMG52NkozSXI4SVhmQyIsInN1YiI6IjEiLCJwcnYiO
	iI4MDVmMzllZWZjYzY4YWZkOTgyNWI0MTIyN2RhZDBhMDc2YzQ5NzkzIn0.j06rvmLLAn6w1EyV7I3tvVLntoGx1K0S9_5lazaTwBk",
    "store_id": 1,
    "execute_url": "https://sandbox.shurjopayment.com/api/secret-pay",
    "token_type": "Bearer",
    "sp_code": "200",
    "massage": "Ok",
    "TokenCreateTime": "2022-10-11 12:51:58pm",
    "expires_in": 3600
}

Checkout API

What does the “Checkout API” do?
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 12 mandatory fields.

Checkout API URL:

Method URL
POST Live: https://engine.shurjopayment.com/api/secret-pay
Sandbox: https://sandbox.shurjopayment.com/api/secret-pay

Request Body Parameters of Checkout API:

Checkout API Request Body Fields:
  • prefix: The sandbox demo prefix is “sp”. For live “Checkout API” url, it will be provided by the shurjoPay team.
  • token: Token needs to be generated by calling the “generate token API”. The “generate token API” will return back a response token in its response body. Note that, sandbox generated tokens will not work on a live checkout API url and vice versa.
  • return_url: For live checkout API URL usage: Return url is the url which the merchant wants to be redirected to after a customer is done with payment processing. This url should be an extension of the merchant's domain. As in an ideal case scenario, the customer should get back to the merchant’s website after they are done with their payment. Note that, this url should be customized by the developers of the merchant to show the necessary information, i.e. Invoice number, transaction status, paid amount of the transaction to the customers.
    Sandbox default return_url is:
    “https://sandbox.shurjopayment.com/response”.
  • cancel_url: For live checkout API URL usage: Cancel URL can be the same as the return_url. This url should be an extension of the merchant's domain. Or if a merchant wants then it can be customized too. This url will be executed whenever a customer cancels their payment and will be redirected to the following cancel_url the merchant has provided.
    Sandbox default cancel_url is: “https://www.sandbox.shurjopayment.com/response”.
  • store_id: Sandbox default store_id is: “1”. For live checkout API URL usage: The store_id field needs to be filled up by the response field from “generate token API”. The best practice is to store the store_id field while calling the “generate token API” for generating a token.
  • amount: Sandbox default amount can be any number. This field will have the amount the customer is going to pay. The amount should be in numbers.
  • order_id: Sandbox default order_id is: “sp12345”. The order_id field should be dynamically generated by the merchant. So that each individual transaction has a unique order_id. The order_id field should consist of the prefix letters and then the unique number of the order. For example: If the merchant’s prefix is “ABC” then the order_id’s should be like: ABC12345, ABC54321 etc.
  • currency: Sandbox and live checkout API URL default currency can be any standardized currency acronym format. This field will have the currency in which the customer is going to pay.
  • customer_name: This field will contain the name of the customer who is trying to do the payment.
  • customer_address: This field will contain the address of the customer who is trying to do the payment.
  • customer_email: This field will contain the address of the email who is trying to do the payment.
  • customer_phone: This field will contain the phone number of the customer who is trying to do the payment.
  • customer_city: This field will contain the city of the customer who is trying to do the payment.
  • client_ip: This field will contain the IP address of the customer who is trying to do the payment.

Response Body Parameters of Generate Token API:

Type Name Data Type MOC (Mandatory / Optional / Conditional) Length Description
Request body token string Mandatory 128
store_id int Mandatory 10
prefix string Mandatory 5 Any string not more than 5 characters. It distinguishes the stores of a merchant.
currency string Mandatory ISO format,(only BDT and USD are allowed)
return_url url Mandatory
cancel_url url Mandatory
amount url Mandatory
order_id string Mandatory Unique Order Id from merchant store.
discsount_am ount float Optional
disc_percent int Optional
client_ip ip Optional
customer_name string Mandatory 200
customer_phone string Mandatory 18
customer_email string Mandatory
customer_address string Mandatory 250
customer_city string Mandatory 15
customer_state string Optional
customer_postcode string Optional
customer_country string Optional
value1 string Optional Additional Field
value2 string Optional Additional Field
value3 string Optional Additional Field
value4 string Optional Additional Field 
								

									

										
   API Link:
	
	API Link: https://www.sandbox.shurjopayment.com/api/secret-pay
 
	Method: POST
	
										

										
   Body:

										
{
	"prefix":"sp",
	"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL3NhbmRib3guc2h1cmpvcGF5bWVudC5jb20vYXBpL2xvZ2luIiwia
	WF0IjoxNjY1OTE0ODc1LCJleHAiOjE2NjU5MTg0NzUsIm5iZiI6MTY2NTkxNDg3NSwianRpIjoiV3JFMG52NkozSXI4SVhmQyIsInN1YiI6IjEiLCJwcnYiO
	iI4MDVmMzllZWZjYzY4YWZkOTgyNWI0MTIyN2RhZDBhMDc2YzQ5NzkzIn0.j06rvmLLAn6w1EyV7I3tvVLntoGx1K0S9_5lazaTwBk",
	"return_url":"https://www.sandbox.shurjopayment.com/response",
	"cancel_url":"https://www.sandbox.shurjopayment.com/response",
	"store_id":"1",
	"amount":"10",
	"order_id":"sp315689",
	"currency":"BDT",
	"customer_name":"Maharab kibria",
	"customer_address":"Dhaka",
	"customer_phone":"01766666666",
	"customer_city":"Dhaka",
	"customer_post_code":"1212",
	"client_ip":"102.101.1.1"
}
										
									

									
   Authorization:

										
{
	"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL3NhbmRib3guc2h1cmpvcGF5bWVudC5jb20vYXBpL2xvZ2luIiwia
	WF0IjoxNjY1OTE0ODc1LCJleHAiOjE2NjU5MTg0NzUsIm5iZiI6MTY2NTkxNDg3NSwianRpIjoiV3JFMG52NkozSXI4SVhmQyIsInN1YiI6IjEiLCJwcnYiO
	iI4MDVmMzllZWZjYzY4YWZkOTgyNWI0MTIyN2RhZDBhMDc2YzQ5NzkzIn0.j06rvmLLAn6w1EyV7I3tvVLntoGx1K0S9_5lazaTwBk"
}
										
									

									

										
   Responce:

										
{
    "checkout_url": "https://sandbox.securepay.shurjopayment.com/spaycheckout/?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.
	eyJpc3MiOiJodHRwczovL3NhbmRib3guc2h1cmpvcGF5bWVudC5jb20vYXBpL2xvZ2luIiwiaWF0IjoxNjY1NjU3NTExLCJleHAiOjE2NjU2NjExMTEsI
	m5iZiI6MTY2NTY1NzUxMSwianRpIjoiTnlabHRtQ3VyVjY1YzhrNyIsInN1YiI6IjEiLCJwcnYiOiI4MDVmMzllZWZjYzY4YWZkOTgyNWI0MTIyN2RhZD
	BhMDc2YzQ5NzkzIn0.8SNq6ys1QyWRdqsHgBj0FC4aLwDuiR78HpA-Brj6ngM&order_id=sp6347eac8173d6",
    "amount": "10",
    "currency": "BDT",
    "sp_order_id": "sp634bd826d5c65",
    "customer_order_id": "sp315689",
    "customer_name": "Maharab kibria",
    "customer_address": "Dhaka",
    "customer_city": "Dhaka",
    "customer_phone": "01766666666",
    "customer_email": null,
    "client_ip": "102.101.1.1",
    "intent": "sale",
    "transactionStatus": "Initiated"
}

Once all the request body data fields have been correctly provided and the checkout API is being executed correctly, it will return a status code of 200 and a response body. The response body contains a “checkout_url” and other necessary information fields. The “checkout_url” field which has a url in it and it needs to be executed. After this checkout_url is being executed it will redirect the customers to the shurjoPay payment gateway UI to complete their payment. It is also recommended to store the “sp_order_id” inside the merchant's database, thus the merchant can trace back the order status later on.



Figure: ShurjoPay Sandbox Payment Gateway UI


After completing the payment the customer will be redirected to the merchant’s given url that has been provided on the “return_url” field of the checkout API.





Figure: Shurjopay sandbox generated return_url demo UI

Verify Order API

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

Verify order API URL:

Method URL
POST Live: https://engine.shurjopayment.com/api/verification
Sandbox: https://sandbox.shurjopayment.com/api/verification

Request Body Parameters of Verify Order:

Verify Order API request body fields:
  • Bearer Token: The verify order has an authorization header set as: Bearer token. The bearer token field has to be filled up by generating a token from “generate token API”. Note that, merchant generated custom order_id will not be accepted here.
  • order_id: The request body field is the order ID of the transaction. This order_id has to be provided from the response data of checkout API’s “sp_order_id”.

Type Name Data Type MOC (Mandatory / Optional / Conditional) Length Description
Request body order_id string Mandatory 128 For verification, merchants must use order_id that is sent from shurjoPay during call back.

Response Body Parameters of Verify Order:

Type Name Data Type Length Description
Request body order_id string Unique id generated by shurjoPay. Merchants can search payment details using order_id.
currency string ISO format
amount float
card_holder_name string
card_number string
phone_no string
bank_trx_id string Bank/MFS generated unique id
invoice_no string Unique id Generated by shurjoPay
bank_status string
customer_order_id string Customer_order_ id (Unique) that was sent by you during initiation. This parameter needs to be validated with your system database for security
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
sp_massage string Transaction Status - as Success / Failed / Cancel
This parameter needs to be checked before update your database
Success : A successful transaction.
Failed : Transaction is declined by customer's Issuer Bank.
Cancel : Transaction is canceled by the customer.
name string
email string
address string
city string
transaction_stat us string
method string
usd_amt float
usd_rate float
value1 string
value2 string
value3 string
value4 string 
									

										

											
   API Link:
		
		API Link: https://www.sandbox.shurjopayment.com/api/verification
 
		Method: POST
		
											

											
   Body:

											
	{
		"order_id":"sp634bd826d5c65"
	}
											
										

										

										
   Authorization:

											
	{
		"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL3NhbmRib3guc2h1cmpvcGF5bWVudC5jb20vYXBpL2xvZ2luIiwia
		WF0IjoxNjY1OTE0ODc1LCJleHAiOjE2NjU5MTg0NzUsIm5iZiI6MTY2NTkxNDg3NSwianRpIjoiV3JFMG52NkozSXI4SVhmQyIsInN1YiI6IjEiLCJwcnYiO
		iI4MDVmMzllZWZjYzY4YWZkOTgyNWI0MTIyN2RhZDBhMDc2YzQ5NzkzIn0.j06rvmLLAn6w1EyV7I3tvVLntoGx1K0S9_5lazaTwBk"
	}
											
										

										

											
   Responce:

											
	[
		{
			"order_id": "sp634bd826d5c65",
			"currency": "BDT",
			"amount": 10,
			"payable_amount": 10,
			"discsount_amount": null,
			"disc_percent": 0,
			"usd_amt": 0,
			"usd_rate": 0,
			"method": null,
			"sp_massage": "initiated",
			"sp_code": "1068",
			"name": "Maharab kibria",
			"email": null,
			"address": "Dhaka",
			"city": "Dhaka",
			"value1": null,
			"value2": null,
			"value3": null,
			"value4": null
		}
	]