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 indicators.This 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: https://sandbox-splitpay-api.getsimpl.com/api/v1/transaction/initiate

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

user.email 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

items.sku string Y SKU details about the transaction

items.category string N Category of the sku items

items.description string N Description of the sku items

items.quantity 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":
"https://merchant-website.com/simpl/transactions/status",
"transaction_status_webhook_url":
"https://merchant-website.com/simpl/transactions_webhook/status",
"user": {
"phone_number": "0000000000",
"email": "[email protected]",
"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": "13.235.154.11",
"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": "[email protected]",
"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":
"https://sandbox-splitpay.getsimpl.com/pay?token=b6a98535185823416e1dc717c5d5379e"
}
}

Error Response Body

Response parameter name Data type Description

success boolean Indicates where the request

was successful or not

error.code string Error Code

error.message 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

https://merchant-website.com/simpl/transactions/status?status=SUCCESS&order_id=AES12
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

https://merchant-website.com/simpl/transactions/status?status=FAILED&error_code=USER
_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
https://<transaction_status_webhook_url>?status=SUCCESS&order_id=AES1234&transact
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
https://<transaction_status_webhook_url>?status=FAILED&error_code=USER_CANCELLE
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:
https://sandbox-splitpay-api.getsimpl.com/api/v1/transaction_by_order_id/<order_id>/status

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

data.id string Transaction id

data.status 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

error.code string Error Code

error.message 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: https://sync-data-sandbox.getsimpl.com/api/v1/merchants

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

user.phone 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": "[email protected]",
"gender": "female",
"first_transaction_date": "2021-01-01T00:00:00"
},
"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-05T13:00:00",
"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

data.message 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

data.message 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: https://sandbox-splitpay-api.getsimpl.com/api/v1/transaction/refund

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

error.code string Error Code

error.message 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"
}
}