Simpl Pay in 3
Table of Contents
API Integration sequence diagram 2
API Integration Explanation 3
API Specifications 4
Initiate Transaction API 4
Transaction Status Redirection 10
Signature Verification 12
Transaction Status Update Via Webhook 14
Transaction Status API 14
Data Sharing API 17
Transaction Refund API 20
API Integration sequence diagram
API Integration Explanation
Step1: During checkout, the merchant calls the Initiate Transaction API with order details, user
details and the transaction_status_redirection_url (Used in step3)
Step 2: Simpl responds with a redirection_url which the merchant should launch in the browser
in order for the user to carry out the transaction with Simpl.
Step 3: Once the user goes through Simpl’s transaction flow, the status of the transaction is
passed to the Merchant by launching the transaction_status_redirection_url passed in step1
Step 4: If the transaction succeeded, the merchant verifies the transaction status by calling the
Transaction Status API. Merchant can skip this API call if the transaction fails.
Step 5: Merchant records the transaction status and fulfills or cancels the order depending on
the status.
Data Sharing API Integration
This API needs to be initiated on load of product display page and checkout page. Data fetched
on these pages feeds our approval and underwriting models. It also helps Simpl to calibrate the
credit limit of the user as per their transaction [Link] eventually leads to higher
transaction success rates.
API Specifications
Initiate Transaction API
This is a server-to-server API call to initiate a Pay in 3 transaction. Merchant will hit the below
end-point when a user initiates a payment using Simpl Pay in 3 from the checkout page.
This API responds with a redirection_url upon successful initiation. The merchant app should
then redirect the user to the redirection_url to complete the transaction.
Please note that this API should never be called from the client, doing so would expose the
authorization secret which could result in misuse and financial loss.
URL: [Link]
Request Method: POST
Request Headers:
Key Value Comments
authorization merchant_client_secret merchant_client_secret will
be shared during merchant
onboarding
content_type application/json
Request Body Parameters
Parameter Name Data Type Mand Description
atory
(Y/N)
merchant_client_id string Y An identifier that uniquely identifies
the merchant
transaction_status_redirectio string Y The transaction status will be notified
n_url to the merchant through URL
callback using this value.
transaction_status_webhook string Y The transaction status will also be
_url notified through a webhook URL
order_id string Y Merchant’s unique order ID of the
transaction.
amount_in_paise integer Y Order amount in paise should be
greater than 300
discount_in_paise integer N Order discount amount in paise
shipping_amount_in_paise integer N Order shipping amount in paise
user.phone_number string Y User’s Phone number
[Link] string Y User’s Email
user.first_name string N User’s First Name
user.last_name string N User’s Last Name
billing_address.line1 string Y User’s Billing Address Line 1
billing_address.line2 string Y User’s Billing Address Line 2
billing_address.city string Y Billing Address City
billing _address.state string Y Billing Address State
billing_address.country string Y Billing Address Country
billing_address.pincode string Y Billing Address Pincode
shipping_address.line1 string N User’s Shipping Address Line 1
shipping_address.line2 string N User’s Shipping Address Line 2
shipping_address.city string N Shipping Address City
shipping_address.state string N Shipping Address State
shipping_address.country string N Shipping Address Country
shipping_address.pincode string N Shipping Address
Pincode
[Link] string Y SKU details about the transaction
[Link] string N Category of the sku items
[Link] string N Description of the sku items
[Link] integer Y Quantity details about the transaction
items.rate_per_item integer Y Rate of each item in the transaction
in paise
device_params.manufacturer string N Device Manufacturer
device_params.model string N Device Model
device_params.rooted boolean N Is Device rooted
device_params.android_id string N Android ID of the user’s device
device_params.ip_address string N IP address of the user
device_params.lat_lng string N Location info of the user (Latitude &
Longitude)
device_params.<custom_par string N Merchant can send any additional
am> custom parameter that will help to
identify the user or detect fraud.
merchant_params.customer_ string N Merchant's id for the user
id
merchant_params.inventory_ string N Inventory partner's ID
partner.ip_id
merchant_params.inventory_ string N Inventory partner's name
partner.ip_name
merchant_params.inventory_ string N Inventory partner's phone number
partner.ip_phone_number
merchant_params.inventory_ string N Inventory partner's email
partner.ip_email
merchant_params.inventory_ string N Inventory partner's address
partner.ip_address
merchant_params.service_p string N Service partner's ID
artner.sp_id
merchant_params.service_p string N Service partner's name
artner.sp_name
merchant_params.service_p string N Service partner's phone number
artner.sp_phone_number
merchant_params.service_partn string N Service partner's address
er.sp_address
mock_eligibility_response string N Only to be passed in Sandbox
environment
Valid values are
1. eligibility_success
2. eligibility_fail
Mocks the eligibility response in the
Sandbox environment for testing..
mock_eligibility_amount_in_pais integer N Only to be passed in Sandbox
e environment
Mocks the eligibility amount in the
Sandbox environment for testing various
flows.
Example Request Body
{
"merchant_client_id": "fab4d7f9-ab58-4805-aa3b-b0d3fd7b988e",
"transaction_status_redirection_url":
"[Link]
"transaction_status_webhook_url":
"[Link]
"user": {
"phone_number": "0000000000",
"email": "customer@[Link]",
"first_name": "",
"last_name": ""
},
"order_id": "BKS-5397",
"amount_in_paise": 500000,
"discount_in_paise": 3500,
"shipping_amount_in_paise": 3300,
"items": [
{
"sku": "Tea",
"category": "Food",
"description": "Green Tea",
"quantity": 5,
"rate_per_item": 1200
}
],
"device_params": {
"manufacturer": "OnePlus",
"model": "OnePlus6",
"rooted": true,
"android_id": "92184bf0a60baf71",
"ip_address": "[Link]",
"lat_lng": "0.0,0.0"
"custom_param_1": "value_1",
"custom_param_2": "value_2"
},
"merchant_params": {
"customer_id": "Some unique ID",
"inventory_partner": {
"ip_id": "Some unique ID",
"ip_name": "Abc xyz",
"ip_phone_number": "7865432109",
"ip_email": "abc@[Link]",
"ip_address": "Block A, street 4, Bangalore"
},
"service_partner": {
"sp_id": "Some unique ID",
"sp_name": "Abc xyz",
"sp_phone_number": "7865432109",
"sp_address": "Block A, street 4, Bangalore"
}
},
"billing_address": {
"line1": "811, Crescent Business Park",
"line2": "Near Telephone exchange",
"city": "Bangalore",
"state": "Karnataka",
"country": "India",
"pincode": "560001"
},
"shipping_address": {
"line1": "811, Crescent Business Park",
"line2": "Near Telephone exchange",
"city": "Bangalore",
"state": "Karnataka",
"country": "India",
"pincode": "560001"
},
"metadata": {
"delivery_type": "express",
"custom_param_1": "value",
"custom_param_2": "value"
}
}
Response Codes
Response Status Code Description
200 OK Transaction has been successfully initiated
401 Unauthorized Invalid authorization
400 Bad Request A mandatory request parameter is missing or
invalid
500 Internal Server Error Unexpected error
Success Response Body
Response parameter name Data type Description
success boolean Indicates where the request
was successful or not
data.redirection_url string A URL to which the Merchant
should redirect in order to
carry out the Simpl Pay in 3
transaction
Example Success Response
{
"success": true,
"data": {
"redirection_url":
"[Link]
}
}
Error Response Body
Response parameter name Data type Description
success boolean Indicates where the request
was successful or not
[Link] string Error Code
[Link] string Error Message
Error Codes
Response status code Error code
401 Unauthorized UNAUTHORIZED
400 Bad Request BAD_REQUEST
500 Internal Server Error INTERNAL_SERVER_ERROR
Example Error Response
{
"success": false,
"error": {
"code": "BAD_REQUEST",
"message": "amount_in_paise value is missing"
}
}
Transaction Status Redirection
Once the Pay in 3 transaction is completed, the user is redirected to the
transaction_status_redirection_url passed when initiating the transaction.
Please note to implement this API in an idempotent way as the status redirection can happen
multiple times.
URL Callback query parameters
Parameter Name Description
status Status of the transaction. SUCCESS/FAILED
order_id Merchant’s Order Id for the transaction
transaction_id Simpl transaction id. This is sent only when
the status is SUCCESS.
nonce One time token to mitigate replay attacks
signature Generated Signature for verification and
tamper proofing.
signature_algorithm Signature Algorithm (HMAC-SHA1)
error_code Error code to identify the reason for failure.
This is sent only when the status is FAILED
A sample transaction_status_redirection_url with SUCCESS status is shown below
[Link]
34&transaction_id=9506244d-3f5e-4eea-b07e-f40087da36f7&nonce=18722057ed9da49f90
28c8d62f3ece69&signature=c1b09e56458dfc65ced6eeb0050005f08daef48a&signature_alg
orithm=HMAC-SHA1
A sample transaction_status_redirection_url with FAILED status is shown below
[Link]
_CANCELLED&order_id=AES1234&nonce=18722057ed9da49f9028c8d62f3ece69&signatu
re=c1b09e56458dfc65ced6eeb0050005f08daef48a&signature_algorithm=HMAC-SHA1
Error Codes
Error Code Description
USER_CANCELLED User cancelled the payment
USER_UNAUTHORIZED User is not eligible for Pay in 3
EXCEEDED_CREDIT_LIMIT Transaction Amount exceeds spending limit
INTERNAL_SERVER_ERROR Unexpected error
Signature Verification
The signature that is passed along with the status response must be verified before acting on
the status. The value of the signature (HMAC signature) parameter in the
transaction_status_redirection_url is computed using the algorithm specified by the
signature_algorithm (HMAC-SHA1) parameter .
The signature is computed using the following algorithm
1. Get all the query parameters (key=values pairs) from the
transaction_status_redirection_url
Example
status=SUCCESS
order_id=AES&1234
transaction_id=9506244d-3f5e-4eea-b07e-f40087da36f7
nonce=18722057ed9da49f9028c8d62f3ece69
signature=c1b09e56458dfc65ced6eeb0050005f08daef48a
signature_algorithm=HMAC-SHA1
2. Except for signature and signature_algorithm, all the other parameters are used for
computing the signature.
Example
status=SUCCESS
order_id=AES&1234
transaction_id=9506244d-3f5e-4eea-b07e-f40087da36f7
nonce=18722057ed9da49f9028c8d62f3ece69
3. Percentage encode each key and value pair if they are decoded by the server. You can
skip this step if the key/value params are already Percent-encoded.
Example
Status
SUCCESS
Order_id
AES1234%26
Transaction_id
9506244d-3f5e-4eea-b07e-f40087da36f7
nonce
18722057ed9da49f9028c8d62f3ece69
Note the value of order_id has changed after encoding
4. Sort the parameters alphabetically (ASCII based sort) by the encoded key
Example
nonce
18722057ed9da49f9028c8d62f3ece69
order_id
AES1234%26
status
SUCCESS
transaction_id
9506244d-3f5e-4eea-b07e-f40087da36f7
5. Combine the key/value pair in sorted order and use the resulting string to compute the
HMAC signature
Example
nonce=18722057ed9da49f9028c8d62f3ece69&order_id=AES1234%26&status
=SUCCESS&transaction_id=9506244d-3f5e-4eea-b07e-f40087da36f7
6. The HMAC of the string can be calculated using the merchant_client_secret (secret
key) shared during the onboarding of the merchant. Simpl uses HMAC-SHA1 to
generate the signature.
Example
HMAC(
“sha1”, // cryptographic hash function used in the calculation of an HMAC
“Merchant_client_secret”, // secret key
“nonce=18722057ed9da49f9028c8d62f3ece69&order_id=AES1234%26&status
=SUCCESS&transaction_id=9506244d-3f5e-4eea-b07e-f40087da36f7” // message
)
Generated signature
c1b09e56458dfc65ced6eeb0050005f08daef48a
7. Compare the generated signature with the signature received in the status callback to
verify it.
Transaction Status Update Via Webhook
Optionally, the status of the transaction will also be sent to the merchant via a server-to-server
call right before the session expiry (30mins) to capture any missed status updates. This
functionality is enabled as soon as transaction_status_webhook_url param is passed during
the Initiate Transaction API call.
Please note that the webhook call will be triggered even if the status is previously updated via
status redirection url. Hence make sure to implement this in an idempotent way.
A GET Http request is made to the URL passed in transaction_status_webhook_url param of
Initiate Transaction API.
A sample webhook API call with SUCCESS status is shown below
GET
[Link]
ion_id=9506244d-3f5e-4eea-b07e-f40087da36f7&nonce=18722057ed9da49f9028c8d62f3ec
e69&signature=c1b09e56458dfc65ced6eeb0050005f08daef48a&signature_algorithm=HM
AC-SHA1
A sample webhook API with FAILED status is shown below
GET
[Link]
D&order_id=AES1234&nonce=18722057ed9da49f9028c8d62f3ece69&signature=c1b09e5
6458dfc65ced6eeb0050005f08daef48a&signature_algorithm=HMAC-SHA1
The payload, error code and signature verification mechanism is same as the Transaction
Status Redirection section.
Transaction Status API
The Transaction Status API is used to verify the status of the transaction post transaction status
redirection from Simpl. This API should be called by the merchant when the status is SUCCESS
in transaction_status_redirection_url. For FAILED transactions, this API call can be skipped.
Please note that this API should never be called from the client, doing so would expose the
authorization secret which could result in misuse and financial loss.
URL:
[Link]
Request Method: GET
Request Headers:
Key Value Comments
authorization merchant_client_secret merchant_client_secret will
be shared during merchant
onboarding
Request Parameters:
Note that the order_id is passed in the url as a path parameter. order_id is the Merchant’s
order id that is passed to Simpl during Initiate Transaction API call.
Response Codes
Response Status Code Description
200 OK Transaction status is known
401 Unauthorized Invalid authorization
400 Bad Request Invalid transaction id
500 Internal Server Error Unexpected error
Success Response Body
Response parameter name Data type Description
success boolean Indicates where the request was
successful or not
[Link] string Transaction id
[Link] string Transaction status
(SUCCESS/FAILED)
Example Success Response
{
"success": true,
"data": {
"id": "58992c70-2fa9-4293-bfb7-1ee7bd554a15",
"status": "SUCCESS",
"amount_in_paise": 20000
}
}
Error Response Body
Response parameter name Data type Description
success boolean Indicates where the request
was successful or not
[Link] string Error Code
[Link] string Error Message
Error Codes
Response status code Error code
401 Unauthorized UNAUTHORIZED
400 Bad Request BAD_REQUEST
500 Internal Server Error INTERNAL_SERVER_ERROR
Example Error Response
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Unauthorized"
}
}
Data Sharing API
This API ensures data-sharing between Simpl and merchant. On a high level, we expect
following data to be shared (formats mentioned in API detail):
1. User Data
2. Device data
3. Product/SKU/Order Data
This API needs to be initiated on load of product display page and checkout page. Data fetched
on these pages feeds our approval and underwriting models. It also helps Simpl to calibrate the
credit limit of the user as per their transaction indicators.
Please note that this API should never be called from the client, doing so would expose the
authorization secret which could result in misuse and financial loss.
URL: [Link]
Request Method: POST
Request Headers:
Key Value Comments
authorization merchant_client_secret merchant_client_secret will
be shared during merchant
onboarding
Request Body Parameters:
Please note that the below parameters represent the minimal base structure of the request
payload. Additional attributes specific to User, Order and Merchant has to be passed along with
this information as per the business agreement. Please refer to the example to see how
additional parameters would be passed.
Parameter Name Data Type Mand Description
atory
(Y/N)
merchant_name string Y Merchant’s Name
[Link] string Y User’s Phone Number
order JSON Y Order related attributes are passed in
this field
merchant_params JSON Y Merchant specific attributes are
passed in this field
Example Request Body
{
"merchant_name": "merchant",
"user": {
"customer_id": "58932c70-2fa9-4293-bfb7-1ee7bd554a15",
"phone": "2222222222",
"first_name": "FName",
"last_name": "LName",
"email": "customer@[Link]",
"gender": "female",
"first_transaction_date": "2021-01-01T[Link]"
},
"order": {
"order_id": "BKS-5397",
"order_description": "Shoes, Dresses",
"final_order_value": "100.00",
"payment_mode": "Card",
"loyalty_points_value": "85",
"discount_value": "25",
"timestamp": "2021-01-05T[Link]",
"address_line1": "811, Crescent Business Park",
"address_line2": "Near Telephone exchange",
"city": "Bangalore",
"pin": "560001",
"status": "SUCCESS",
"platform": "MOBILE",
"os": "ANDROID"
},
"merchant_params": {
"loyalty_score": "55",
"fraud_score": "0.2"
}
}
Response Codes
Response Status Code Description
200 OK Transaction status is known
401 Unauthorized Invalid authorization
400 Bad Request Missing mandatory request parameters
500 Internal Server Error Unexpected error
Success Response Body
Response parameter name Data type Description
success boolean Indicates where the request was
successful or not
[Link] string Success message
Example Success Response
{
"success": true,
"data": {
"message": "OK!"
}
}
Error Response Body
Response parameter name Data type Description
success boolean Indicates where the request
was successful or not
[Link] string Error Code
Error Codes
Response status code Error code Description
401 Unauthorized UNAUTHORIZED Invalid authorization
400 Bad Request INVALID_DATA_FORMAT Missing mandatory request
parameters
INVALID_PHONE_NUMBER Phone number has to be of
10 digits in length. If not, this
error is returned.
500 Internal Server Error ERROR_PROCESSING_RE Unexpected error
QUEST
Example Error Response
{
"success": false,
"data": {
"message": "INVALID_DATA_FORMAT"
}
}
Transaction Refund API
The Transaction Refund API is used to issue the requested refund for an order to the customer.
This API can handle both partial as well as full refunds.
Please note that this API should never be called from the client, doing so would expose the
authorization secret which could result in misuse and financial loss.
URL: [Link]
Request Method: POST
Request Headers:
Key Value Comments
authorization merchant_client_secret merchant_client_secret will
be shared during merchant
onboarding
content_type application/json
Request Body Parameters:
Parameter Name Data Type Mand Description
atory
(Y/N)
merchant_client_id string Y An identifier that uniquely identifies
the merchant
amount_in_paise integer Y Order amount in paise should be
greater than 0
transaction_id string Y Simpl transaction id
reason string N User’s reason for refund
order_id string Y Merchant’s unique refund order ID for
the transaction.
Example Request Body
{
"merchant_client_id": "fab4d7f9-ab58-4805-aa3b-b0d3fd7b988e",
"amount_in_paise": 500000,
"transaction_id": "e9a4c7e9-ab58-4805-aa3b-b0d3fd7b988e",
"reason": "Failed to deliver on time",
"order_id": "BKS-5397"
}
Response Codes
Response Status Code Description
200 OK Refund has been successfully initiated
401 Unauthorized Invalid credentials
400 Bad Request Required fields missing in the request body
500 Internal Server Error Unexpected error
Success Response Body
Response parameter name Data type Description
success boolean Indicates where the request
was successful or not
data.transaction_id string Simpl transaction id
data.refund_transaction_id string Simpl refund ID (Refund
reference number)
Example Success Response
{
"success": true,
"data": {
"transaction_id": "e9a4c7e9-ab58-4805-aa3b-b0d3fd7b988e",
"refund_transaction_id": "526097c8-0c25-4d51-a80c-64fab3e311e6"
}
}
Error Response Body
Response parameter name Data type Description
success boolean Indicates where the request
was successful or not
[Link] string Error Code
[Link] string Error Message
Error Codes
Response status code Error code
401 Unauthorized UNAUTHORIZED
400 Bad Request BAD_REQUEST
500 Internal Server Error INTERNAL_SERVER_ERROR
Example Error Response
{
"success": false,
"error": {
"code": "BAD_REQUEST",
"message": "Amount value is missing"
}
}
