Direct Integration using shurjoPay RESTful API

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

shurjoPay RESTful API Documentation

Introduction

Generate Authentication Token

Specification

POST /get_token

Request Body Fields

Response Body Fields

Sample cURL Request:

Sample Request Body:

Sample Response Body

Initiate Payment Transaction

Specification

POST /secret-pay

Request Authorization Fields:

Request Body Fields:

Response Body Fields:

Sample cURL Request:

Authorization:

Request Body:

Response Body:

Verify Payment Transaction

Specification

POST /verification

Request Authorization Fields:

Request Body Fields:

Response Body Fields:

Sample cURL Request:

Authorization:

Request Body:

Response Body: