Simpl v4 API specifications

The list of APIs to be implemented for Merchant – Simpl integration using v4 API are explained below.

Note:
1. As part of future changes in API, we may add new response parameters. Hence, please ensure
forward compatibility with such additions.
2. In few of the corner cases, response parameters may have a null value. Each API has a
description of their specific cases.
Integration API sequence diagram

Case 1: User is eligible to transact

Case 2: User is eligible to transact but further action is required
Case 3: User is not eligible to transact (Unauthorised or Unable to process)
API Specifications
1. Eligibility API
Merchant will hit the below end-point to ensure a user is eligible for transaction. This API needs to initiated
at the checkout page to ensure that if a user is not eligible he/she should not see Simpl at all or should see
a greyed out disabled Simpl button.
#API Endpoint
Host URL: https://sandbox-approvals-api.getsimpl.com
Headers:
"authorization”: "authorization_secret_key"
"content_type" : "application/json"

POST /api/v4 /check_eligibility

{
amount_in_paise: “” //MANDATORY
phone_number:””, //MANDATORY
device_params: {
parameter_name: “parameter_value”
(Request field name is ‘device_params’ if fingerprint params are
generated directly via merchant else ‘payload’ if generated by using
Simpl SDK)
}

#RESPONSE
## Case 1: User is eligible to transact on button click
HTTP Status Code: 200
{
"api_version": "4.0", "data":
{
"available_credit_in_paise": 500000,
"error_code": null,
"redirection_url": null,
"status": "eligible",
"token": "<charge_token>"
// This is a one-time token generated for every user only if their Simpl account is linked
on merchant using OTP. This should be passed in the Charge API.
},
"success": true
}
## Case 2: Account exists but further action is required
### Case 2.1: Linking Required
HTTP Status Code: 200
{
"api_version": "4.0", "data":
{
"available_credit_in_paise": 0,
"error_code": "linking_required",
"redirection_url": "<link>",
"status": "eligible",
"token": null
},
"success": true
}

### Case 2.2: Insufficient credit

HTTP Status Code: 200
{
“api_version”: “4.0",
“data”:
{
“available_credit_in_paise”: 0,
“error_code”: “insufficient_credit”,
“redirection_url”: “<link>“,
“status”: “eligible”,
“token”: null
},
“success”: true
}

### Case 2.3: Pending Bill

HTTP Status Code: 200
{
“api_version”: “4.0",
“data”:
{
“available_credit_in_paise”: 0,
“error_code”: “pending_dues”,
“redirection_url”: "<link>",
“status”: “eligible"
"token": null
},
“success”: true
 }

Error Code Error Description Comments

linking_required Link your Simpl account Show error_description to user
along with button and redirect
user to redirection_URL on
button click.
pending_dues Clear your previous dues to Show error_description to user
proceed along with button and redirect
user to redirection_URL on
button click
insufficient_credit Clear your previous dues to Show error_description to user
proceed along with button and redirect
user to redirection_URL on
button click

Note: Handling redirection_url

Simpl will configure a URL for post-payment redirection URL for merchants. This URL will be provided by
merchants to Simpl which will be configured at our backend beforehand.
Pass a query string merchant_payload=<Stringified JSON> before launching the Simpl redirection URL if you
want to receive extra details to the post-payment redirection URL after the successful user action. You can
store orderID of the user in merchant_payload so that you can go ahead and charge the transaction for that
orderID when the user pays back the Simpl pending bill.

The URL will receive the response via HTTP POST as follows:

Request Method - SUCCESS:

success: true,
token: <charge_token>,
available_credit_in_paise: ,
merchant_payload: StringifiedJSON

FAILURE:
success: false,
error_code: “”,
merchant_payload: StringifiedJSON
## Case 3: Account doesn’t exist or (Transaction amount > global limit of user)
### Case 3.1: Unauthorized user
HTTP Status Code: 200
{
“api_version”: “4.0”,
“data”:
{
“error_code”: “user_unauthorized”,
“status”: “not_eligible”
},
“success”: true
}

### Case 3.2: Unable to process

HTTP Status Code: 200
{
“api_version”: “4.0”,
“data”:
{
“error_code”: “unable_to_process”,
“status”: “not_eligible"
},
“success”: true
}

Error Code Error Description Comments

unable_to_process Transaction Amount exceeds Grey out Simpl button with Error
spending limit Description
user_unauthorized You are not eligible to use Simpl Grey out Simpl button with Error
Description
2. Payment–Authorization / Charge API
In the first phase of the integration, Simpl will auto-capture all authorization requests. Hence, the status will
be “captured” for all authorization requests. The token passed in the successful eligibility call is needed to
charge a transaction.
#API Endpoint
Host URL: https://sandbox-approvals-api.getsimpl.com
Headers:
"authorization”: "authorization_secret_key"
"content_type" : "application/json"

POST /api/v4/transaction
{
amount_in_paise: 500000,
token: "<charge_token>",
order_id : “payment_id”, items:
[{
sku: "unique_sku_id", quantity:
"qty_value",
rate_per_item: "rate_value"
}],
shipping_address:
{
line1:"811, Crescent Business Park",
line2:"Near Telephone exchange",
city:"Mumbai",
state:"Maharashtra",
country: "India"
},
billing_address:
{
line1:"811, Crescent Business Park",
line2:"Near Telephone exchange",
city:"Mumbai",
state:"Maharashtra", country:
"India"
},
metadata:
{
email: “customers_email_id”,
customer_id : “customer_id”
 }
}

#RESPONSE
## Case 1: Charge placed successfully
HTTP Status Code: 200
{
"api_version": "4.0",
"data":
{
"due_by":
{
"due_by_in_time": "2019-08-20T23:59:59+05:30",
"due_by_in_words": "20 August, 2019"
},
"transaction":
{
"amount_in_paise": 500000,
"billing_address": null,
"delivered": false,
"id": "<transaction_id>",
"items": [{
"quantity": "12",
"rate_per_item": "1200",
"sku": "some unique id"
}],
"order":
{
"merchant_order_id": "<order_id_by_merchant>"
},
"shipping_address": null,
"shipping_amount_in_paise": 0,
"status": "CLAIMED"
},
},
"success": true
}

## Case 2: Charge unsuccessful

### Case 2.1: Insufficient Credit

HTTP Status Code: 200

{
"api_version": "4.0",
"error":
{
 "code": "insufficient_credit",
"message": "user does not have sufficient credit for this transaction"
},
"success": false
}

### Case 2.2: Bad request / Wrong Request

HTTP Status Code: 400
{
"api_version": "4.0",
"error":
{
"code": "bad_request",
"message": "invalid request body"
},
"success": false
}
### Case 2.3: Invalid token
HTTP Status Code: 200
{
"api_version": "4.0",
"error":
{
"code": "invalid_token",
"message": "invalid token <wrong_token>"
},
"success": false
}
### Case 2.4: Invalid Merchant
HTTP Status Code: 200
{
"api_version": "4.0",
"error":
{
"code": "unauthorized",
"message": "invalid merchant"
},
"success": false
}
3. Refund API

#API Endpoint
Host URL: https://sandbox-approvals-api.getsimpl.com
Headers:
"authorization”: "authorization_secret_key"
"content_type" : "application/json"

POST /api/v4/refund
{
amount_in_paise: XXXX_XX,
reason: "reason_for_refund",
order_id: "refund_id",
transaction_id: "parent_transaction_id"
}
# RESPONSE
## Case 1: Refund successful
HTTP Status Code: 200
{
"api_version": "4.0",
"data":
{
"refunded_transaction_id": "<refund_txn_id>",
"transaction_id": "<parent_txn_id>"
},
"success": true
}
## Case 2: Refund Unsuccessful
### Case 2.1: Refund amount is greater than amount of parent transaction
HTTP Status Code: 200
{
"api_version": "4.0", "error":
{
"code": "refund_amount_greater_than_charged",
"message": "Invalid refund amount. You can only refund upto XXX"
},
"success": false
}

### Case 2.2: Refund can't be placed before a transaction is not charged
HTTP Status Code: 200
{
"api_version": "4.0", "error":
{
"code": "transaction_not_delivered",
"message": "Transaction needs to be charged and delivered to process refunds. Please use
the update end points if the transaction has not been delivered yet."
},
"success": false
}

### Case 2.3: Bad request / Wrong Request

HTTP Status Code: 400
{
"api_version": "4.0", "error":
{
"code": "bad_request",
"message": "invalid request body"
},
"success": false
}

### Case 2.4: No refund is possible as total amount is refunded

HTTP Status Code: 400
{
"api_version": "4.0", "error":
{
"code": "refund_amount_greater_than_refundable",
"message": "The transaction already has refunds/chargebacks, you can only refund upto
Rs.0"
},
"success": false
}
4. Fetch transaction by order ID
Use this endpoint to fetch transaction details related to a particular orderID from verification standpoint.

#API Endpoint
GET /api/v4/transaction_by_order_id/:order_id Host

URL: https://sandbox-approvals-api.getsimpl.com

Headers:
"authorization": ": authorization_secret_key”
"content_type" : "application/json"

#RESPONSE

Case 1: RESPONSE SUCCESS

{
"api_version": "4.0", "data":

{
"transaction":
{
"amount_in_paise": 10000, "billing_address":
{
"city": "Mumbai"
},
"delivered": false,
"discount_amount_in_paise": 0,
"id": "a75077c5-806b-4c23-9129-8eb946895ded",
"items": [{
"quantity": "12",
"rate_per_item": "1200",
"sku": "some unique id"
}],
"metadata": null,
"order":{
"merchant_order_id": "N21234"
},
"refunds": [
{
"amount_in_paise": 10000,
"billing_address": {},
"delivered": false,
"discount_amount_in_paise": 0,
"id": "90ebd720-eb86-4528-b2d0-dbb099795156",
"items": [],
 "metadata": null,
"order": {
"merchant_order_id": ""
},
"shipping_address": {},
"shipping_amount_in_paise": 0,
"status": "REFUND"
}
],
"shipping_address":
{
"city": "Bangalore"
},
"shipping_amount_in_paise": 0,
"status": "CLAIMED"
}
},
"success": true
}
Case 2: RESPONSE ERROR

##Case 2.1: Transaction not found

"api_version": "4.0", "error":

{
"code": "transaction_not_found",
“message”: “Transaction not found”
},

"success": false
}

##Case 2.2: Invalid authorisation secret

{
"api_version": "4.0", "error":
{
"code": "unauthorized",
"message": "invalid merchant"
},

"success": false
}
5. Delinking API
Use this endpoint to delink a user using his phone_number. Post delinking, if a user transacts again for that
merchant, he/she will go through a new user flow and will be asked for OTP.

#API Endpoint
Host URL: https://sandbox-approvals-api.getsimpl.com

Headers:

"content_type" : "application/json"
"authorization": ":<merchant-client-secret>"

POST /api/v4/users/delink
{
"phone_number" : "1234567891" ,
}

#RESPONSE

Case 1: RESPONSE SUCCESS

{
"api_version": "4.0",
"data": {},
"success": true
}

Case 2: RESPONSE ERROR

##Case 2.1: Invalid merchant secret:

{
"api_version": "4.0", "error":
{
"code": "unauthorized",
"message": "invalid merchant"
},
"success": false
}

##Case 2.2: User not found:

{
"api_version": "4.0", "error":
{
"code": "user_not_found",
"message": " user with phone number 1234567891 not found"
},
 "success": false
}