Custom Integration Document

Version 1.0

Getting Your Credentials

Postman API Collection

Pay With bSecure

Order Statuses

Payment Statuses

Login With bSecure

API Status Codes & Response Structure

API & Portal URLs

Page 1
 Custom Integration Document
Version 1.0

Getting Your Credentials

1. Go to Builders Portal
2. Integration >> Enable keys for the environment Live / Sandbox
3. Save & Copy your credentials (Client ID & Client Secret).
4. Please make sure to keep credentials at safe place in your code
5. Select My Stores. And create a new store by clicking on the button.
6. Select Integration Type (Custom Integration)
7. Fill following fields:
a. Store Name its required in any case
b. Store URL its required in any case
c. Product detail URL Required for feature “Manual Orders”
d. Login Redirect URL Required for feature “Login with bSecure”
e. Checkout Redirect URL Required for feature “Pay with bSecure“
f. Checkout Order Status webhook Required for feature “Pay with bSecure”
g. Minimum order amount to ask for CNIC Optional
h. Minimum cart value to proceed to checkout Optional

Postman API Collection

Before moving ahead please make sure you have imported the bSecure Postman API collection and environment and its
working! Currently we have following merchant APIs:

POST 1.1 - Get Merchant Access Token

POST 1.2 - Create Order

POST 1.3 - Get Order Status

POST 1.4 - Get Customer Profile

Page 2
 Custom Integration Document
Version 1.0

bSecure - Payment Gateway

Order Creation
1. Get Merchant Access Token by calling API 1.1 (see postman collection)
2. Create Order by calling API 1.4 (see postman collection)
3. Redirect to Checkout URL you received in step 2
Callback on Order Placement
1. Once the order is successfully placed, bSecure will redirect the customer to the url you mentioned in “Checkout
redirect url” in your environment settings in Partners Portal, with one additional params “order_ref” in the query
string.
Order Status Fetch
1. By using order_ref you received in the above callback you can call API 1.3 to get order details. (see postman
collection), you can use these details to add order in your system.
Order Status Change Webhook
1. Whenever there is any change in order status or payment status, bSecure will send you an update with complete
order details (contents will be the same as response of API 1.3) on the URL you mentioned in “Checkout order status
webhook” in your environment settings in Partners Portal. (your webhook must be able to accept POST request)

Create Order Request Params:

{
"store_id": "ST-00XXXX", Optional String Store Id mentioned on your builder portal
"order_id": "ABC-123", Required String Id generated by your system
"currency": "PKR", Required String Currency Code of Order
"total_amount": 1000, Required Numeric
"sub_total_amount": 1000, Required Numeric
"discount_amount": 0, Required Numeric
"customer": {
"name": "asas", Required String
"email": "[email protected]", Optional String
"country_code": "92", Optional String (required if phone_number is not null)
"phone_number": "3122239449", Optional String
},
"customer_address": {
"country": "Pakistan", Required String
"province": "Sindh", Optional String
"city": "Karachi", Required String
"area": "", Optional String
"address": "" Required String
"zip_code": "" Optional String
}
}
● If access_token has already been generated with store_id attached in that case store_id would be optional in create
order request.

Page 3
 Custom Integration Document
Version 1.0

Pay With bSecure

Order Creation
4. Get Merchant Access Token by calling API 1.1 (see postman collection)
5. Create Order by calling API 1.2 (see postman collection)
6. Redirect to Checkout URL you received in step 2

Callback on Order Placement

2. Once the order is successfully placed, bSecure will redirect the customer to the url you mentioned in “Checkout
redirect url” in your environment settings in Partners Portal, with one additional param “order_ref” in the query
string.

Order Status Fetch

2. By using order_ref you received in the above callback you can call API 1.3 to get order details. (see postman
collection), you can use these details to add order in your system.

Order Status Change Webhook

2. Whenever there is any change in order status or payment status, bSecure will send you an update with complete
order details (contents will be the same as response of API 1.3) on the URL you mentioned in “Checkout order status
webhook” in your environment settings in Partners Portal. (your webhook must be able to accept POST request)
Order Statuses

Status ID Description

created 1 Order created by merchant

initiated 2 Customer landed on bSecure checkout URL. Order is awaiting fulfillment.

placed 3 Customer successfully placed the order

awaiting-confirmation 4 Customer successfully placed the order, but is awaiting for customer confirmation to
authenticate the transaction.

canceled 5 Customer cancelled the order at the time of confirmation.

expired 6 Order not processed within expected time frame.

failed 7 Max payment attempt reached

awaiting-payment 8 Customer successfully placed the order, but is payment is due or awaiting payment.

Page 4
 Custom Integration Document
Version 1.0

Payment Statuses

Status ID Description

Pending 0 Order placed. But payment is awaiting for fullfilment by the customer.

Completed 1 Order fulfilled, placed and payment has also been received.

Failed 2 Payment failed or was declined or maximum attempt for payment request reached.

Create Order Request Params:

{
"store_id": "ST-00XXXX", Optional String Store Id mentioned on your builder portal
"order_id": "ABC-123", Required String Id generated by your system
"currency_code": "PKR", Required String Currency Code of Order
"total_amount": 1000, Required Numeric
"sub_total_amount": 1000, Required Numeric
"discount_amount": 0, Required Numeric
"shipment_charges": "ST-00XXXX", Optional String If custom shipment method is applied
"shipment_method_name": "ABC-123", Optional String If custom shipment method is applied
"products": [ Required Array
{
"name": "Product 1", Required String
"sku": "sku-111", Required String
"quantity": 1, Required Numeric
"price": 1000, Required Numeric
"discount": 0, Required Numeric
"sale_price": 1000, Required Numeric
"sub_total": 1000, Required Numeric
"image": "https://a.com/a.png", Required URL
"short_description": "string", Optional String
"description": "string" Optional String
}
],
"customer": {
"name": "asas", Optional String
"email": "[email protected]", Optional String
"country_code": "92", Optional String (required if phone_number is not null)
"phone_number": "3122239449", Optional String
"auth_code": "asas", Optional String (required if login with bSecure is used)
}
}

Page 5
 Custom Integration Document
Version 1.0

● If access_token has already been generated with store_id attached in that case store_id would be optional in create
order request.
● If the customer has already signed-in via bSecure (Login With bSecure) into your system and you must have an
auth_code for the customer, you can just pass that code in the customer object no need for the rest of the fields.

● Since all the fields in customer object are optional, if you don’t have any information about customer just pass the
empty object: customer:{}
● If you are not using bSecure shipment and want to apply custom shipment to your orders then set :
shipment_charges and shipment_method_name fields

Login With bSecure

Step 1: Redirect the Customer to the following URL:

https://login.bsecure.pk/auth/sso

● With following params in query string:

scope profile
What customer information you can access after successful authorization.

response_type code
OAuth2.0 grant type

client_id Please enter the Client ID and Store slug in below mentioned format.
ex. 93399945-01b5-4a71-8ad2-ae9d811XXXXX:ST-0010XXX

state Unique String for each request, bSecure will return this string to you in
redirect params, this is used to identify that request was generated by your
server not someone else.

We strongly suggest you to save this string in your DB before redirecting the
customer and match it on callback.

● Your final URL should look like this:

https://login.bsecure.pk/auth/sso?scope=profile&response_type=code&client_id=xyz:ST-
0010XXX&state=abc

● On Successful Authorization
bSecure will redirect to Login redirect url you provided when setting up environment in Builders portal, along
with two parameters in query string: code & state

Page 6
 Custom Integration Document
Version 1.0

eg: https://my-store.com/sso-callback?code=abc&state=xyz

Step 2: Verify Callback

● Verify the state you received in the callback by matching it to the value you stored in DB before sending the
Login with bSecure request, you should only proceed if and only if both values match.

Step 3: Get User Profile

● Get Merchant Access token by calling API 1.1 (see postman collection)
● Get Customer Profile by calling API 1.4 using the access token you got from API 1.1 and code you got via login
callback (see postman collection)
● you can save this code for later use.

Page 7
 Custom Integration Document
Version 1.0

API Status Codes & Response Structure

Sample Response:
{
"status": 200,
"message": "Order placed successfully",
"body": {
"expiry": "2020-09-22 02:54:17",
"checkout_url": "http://your-store-url/",
"checkout_url": "http://orders.bsecure.pk/checkout?ref=4fa8a4b6-5408-4b670",
"order_reference": "4fa8a4b6-5408-4b67-8dd5-3e939c470b00",
"merchant_order_id": "6c9fdd48-9ed1-472a-8242-bed87b6e85cd",
"merchant_store_name": "Your-store-name"
}
}

Each API’s response will have 3 root keys:

1. Status
2. Message
3. Body

Following is the description of Status codes and data types of Message & Body fields w.r.t to status code.

Status Message Body

200 Success String Dictionary

500 Internal Server Error Array of Strings Empty Array

400 Unprocessable request Array of Strings Empty Array

401 Authentication Error Array of Strings Empty Array

422 Validation Error Array of Strings Empty Array

API & Portal URLs

Builder Portal URL https://builder.bsecure.pk/

API Base URL https://api.bsecure.pk/v1

Page 8