API Documentation

Welcome to the API documentation. Here you will find all the information you need to integrate with our API.

API Endpoint

The base URL for production API endpoints is: https://api.securepayment.fun/api/v1/

For the sandbox mode, the API endpoint is: https://sandboxapi.securepayment.fun/api/v1/

Authorization

The API uses API Keys in order to authenticate requests. Include your API Key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Example Request:

curl -X GET https://api.securepayment.fun/api/v1/resource \
-H 'Authorization: Bearer YOUR_API_KEY'

HTTP 400 - Bad Request (API Key Issues)

These errors are related to the API key used in the request. Possible reasons include:

Example error response:

{
    "headers": {
        "Authorization":"Authorization header is required and must contain bearer token with valid API key"
    }
}

HTTP 403 - Forbidden (API Key Issues)

These errors are related to the API key used in the request. Possible reasons include:

Example error response:

{
    "headers": {
        "Authorization":"The provided API key does not exist or has been revoked"
    }
}




Sandbox

Sandbox is a special environment with a non-real orders executuion flow, that alows to emulate any case of orders processing. Use it to tune and check your integration.

Emulate successful deposit

POST inr/orders/upi/deposits/{uuid}/actions/sandbox/emulate-success/

POST inr/orders/bank-transfer/deposits/{uuid}/actions/sandbox/emulate-success/

URL Parameters
Name Format Description Required
uuid UUID4 UUID of the target order. Yes

Example Request:
curl -i -X GET 
-H "Authorization: Bearer {YOUR-API-KEY}" \
"https://api.securepayment.fun/api/v1/inr/orders/upi/withdrawals/8eaf744b-f087-4b9a-9c11-c5946abf79b3/actions/sandbox/emulate-success/"


Emulate failed deposit

POST inr/orders/upi/deposits/{uuid}/actions/sandbox/emulate-failure/

POST inr/orders/bank-transfer/deposits/{uuid}/actions/sandbox/emulate-failure/

URL Parameters
Name Format Description Required
uuid UUID4 UUID of the target order. Yes

Example Request:
curl -i -X GET 
-H "Authorization: Bearer {YOUR-API-KEY}" \
"https://api.securepayment.fun/api/v1/inr/orders/upi/deposits/8eaf744b-f087-4b9a-9c11-c5946abf79b3/actions/sandbox/emulate-failure/"


Emulate successful withdrawal

POST inr/orders/upi/withdrawals/{uuid}/actions/sandbox/emulate-success/

POST inr/orders/bank-transfer/withdrawals/{uuid}/actions/sandbox/emulate-success/

URL Parameters
Name Format Description Required
uuid UUID4 UUID of the target order. Yes

Example Request:
curl -i -X GET 
-H "Authorization: Bearer {YOUR-API-KEY}" \
"https://api.securepayment.fun/api/v1/inr/orders/upi/withdrawals/8eaf744b-f087-4b9a-9c11-c5946abf79b3/actions/sandbox/emulate-success/"


Emulate failed withdrawal

POST inr/orders/upi/withdrawals/{uuid}/actions/sandbox/emulate-failure/

POST inr/orders/bank-transfer/withdrawals/{uuid}/actions/sandbox/emulate-failure/

URL Parameters
Name Format Description Required
uuid UUID4 UUID of the target order. Yes

Example Request:
curl -i -X GET 
-H "Authorization: Bearer {YOUR-API-KEY}" \
"https://api.securepayment.fun/api/v1/inr/orders/bank-transfer/withdrawals/8eaf744b-f087-4b9a-9c11-c5946abf79b3/actions/sandbox/emulate-falure/"






UPI Deposits


Create UPI deposit order

POST /inr/orders/upi/deposits/

Creates deposit order and initiates payment session for the end-user.

Parameters
Name Type Description Required
userID string ID of the user that initializes the payment session (on your end). Yes
ipAddr string The IP address of the user.
The payment session will be rejected if the real user's IP address will differ from the value specified here.
Yes
amount unsigned integer Invoice amount.
Format: 1 paise (lowest fraction), i.e., 1 INR = 100
Yes
successRedirectURL string The URL where the user should be redirected to after sucessfully made transaction. Yes
failureRedirectURL string The URL where the user should be redirected to after failed transaction (outdated payment session, etc). Yes
webhookURL string The URL where the webhook events about the order status must be forwarded to. No webhooks will be emitted, if this field will be left blank. See webhooks for details. No
Example Request:
curl -i -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {YOUR-API-KEY}" \
-d '{ \
    "ipAddr":"178.10.10.178", \
    "userID":"5432154321", \
    "amount":10000, \
    "successRedirectURL":"https://some.site/success/", \
    "failureRedirectURL":"https://some.site/failure/", \
    "webhookURL": "https://some.site/webhook/" \
}' \
"https://api.securepayment.fun/api/v1/inr/orders/upi/deposits/"

HTTP 201 - Created (Example Response):

{
    "uuid": "15c4511f-449c-4591-8ae7-45d7644c6701",
    "amount": 10000,
    "depositAmount": 9400,
    "createdAt": "2024-03-08T20:00:45.313603+02:00",
    "ttl": "2024-03-08T20:15:45.313603+02:00",
    "status": "pending",
    "payURL": "https://some.payment.page",
    "successRedirectURL": "https://some.site/success/",
    "failureRedirectURL": "https://some.site/failure/", 
    "webhookURL": "https://some.site/webhook/"
}
Name Type Format Description
uuid string UUID4 UUID4 of the created order.
amount integer Unsigned integer (0 < amount) Amount specified during the order creation (invoice amount).
depositAmount integer Unsigned integer (0 < depositAmount <= amount) Amount that will be effectively added to merhcant's balance.
createdAt string ISO 8601 Timestamp of order creation.
ttl string ISO 8601 Timestamp until order and corresponding invoice should be considered valid.
status string Enum: pending Order status, usually set to pending right after creation.
payURL string HTTPS URL URL where user should be redirected by merchant (to proceed with the invoice).
successRedirectURL string HTTPS URL URL where user will be redirected to by the payment system in case when the invoice processing will be successfull.
failureRedirectURL string HTTPS URL URL where user will be redirected to by the payment system in case when the invoice processing will be unsuccessfull (by any reason).
webhookURL string HTTPS URL If specified during order creation, defines the URL where the webhook events will be delivered.

HTTP 400 - Bad Request

The request does not match SCHEMA expectation. See error description provided in response, i.e:

{
    "fields": {
        "failureRedirectURL":"required"
    }
}

HTTP 417 - Expectation Failed

{
    "error": "No available capacity, please, try again later" 
}

The system encounters bank-related issue, no order can be created at the moment



Get UPI deposit order

GET /inr/orders/upi/deposits/{uuid}/

URL Parameters
Name Format Description Required
uuid UUID4 UUID of the target order. Yes
Example Request:
curl -i -X GET 
-H "Authorization: Bearer {YOUR-API-KEY}" \
"https://api.securepayment.fun/api/v1/inr/orders/upi/deposits/8eaf744b-f087-4b9a-9c11-c5946abf79b3/"

HTTP 200 - OK (Example Response):

{
    "uuid": "15c4511f-449c-4591-8ae7-45d7644c6701",
    "amount": 10000,
    "depositAmount": 9400,
    "createdAt": "2024-03-08T20:00:45.313603+02:00",
    "ttl": "2024-03-08T20:15:45.313603+02:00",
    "status": "pending",
    "payURL": "https://some.payment.page",
    "successRedirectURL": "https://some.site/success/",
    "failureRedirectURL": "https://some.site/failure/", 
    "webhookURL": "https://some.site/webhook/"
}
Name Type Format Description
uuid string UUID4 UUID4 of the created order.
amount integer Unsigned integer (0 < amount) The amount specified during the order creation (invoice amount).
depositAmount integer Unsigned integer (0 < depositAmount <= amount) The amount that will be effectively added to merhcant's balance.
createdAt string ISO 8601 The timestamp of the order creation.
ttl string ISO 8601 The timestamp until the order and the corresponding invoice should be considered valid.
status string Enum:
pending, paid, failed
  • pending: Order is in progress
  • paid: Order has been processed successfully
  • failed: Order has not been paid (error)
payURL string HTTPS URL URL where user should be redirected by merchant (to proceed with the invoice).
successRedirectURL string HTTPS URL URL where user will be redirected to by the payment system in case when the invoice processing will be successfull.
failureRedirectURL string HTTPS URL URL where user will be redirected to by the payment system in case when the invoice processing will be unsuccessfull (by any reason).
webhookURL string HTTPS URL If specified during order creation, defines the URL where the webhook events will be delivered.

HTTP 404 - Not Found:

Specified order was not found during the request execution.





Bank Transfer Deposits


Create bank transfer deposit order

POST /inr/orders/bank-transfer/deposits/

Creates deposit order and initiates payment session for the end-user.

Parameters
Name Type Description Required
userID string ID of the user that initializes the payment session (on your end). Yes
ipAddr string The IP address of the user.
The payment session will be rejected if the real user's IP address will differ from the value specified here.
Yes
amount unsigned integer Invoice amount.
Format: 1 paise (lowest fraction), i.e., 1 INR = 100
Yes
successRedirectURL string The URL where the user should be redirected to after sucessfully made transaction. Yes
failureRedirectURL string The URL where the user should be redirected to after failed transaction (outdated payment session, etc). Yes
webhookURL string The URL where the webhook events about the order status must be forwarded to. No webhooks will be emitted, if this field will be left blank. See webhooks for details. No
Example Request:
curl -i -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {YOUR-API-KEY}" \
-d '{ \
    "ipAddr":"178.10.10.178", \
    "userID":"5432154321", \
    "amount":10000, \
    "successRedirectURL":"https://some.site/success/", \
    "failureRedirectURL":"https://some.site/failure/", \
    "webhookURL": "https://some.site/webhook/" \
}' \
"https://api.securepayment.fun/api/v1/inr/orders/bank-transfer/deposits/"

HTTP 201 - Created (Example Response):

{
    "uuid": "15c4511f-449c-4591-8ae7-45d7644c6701",
    "amount": 10000,
    "depositAmount": 9400,
    "createdAt": "2024-03-08T20:00:45.313603+02:00",
    "ttl": "2024-03-08T20:15:45.313603+02:00",
    "status": "pending",
    "payURL": "https://some.payment.page",
    "successRedirectURL": "https://some.site/success/",
    "failureRedirectURL": "https://some.site/failure/", 
    "webhookURL": "https://some.site/webhook/"
}
Name Type Format Description
uuid string UUID4 UUID4 of the created order.
amount integer Unsigned integer (0 < amount)< /span> Amount specified during the order creation (invoice amount).
depositAmount integer Unsigned integer (0 < depositAmount <= amount)< /span> Amount that will be effectively added to merhcant's balance.
createdAt string ISO 8601 Timestamp of order creation.
ttl string ISO 8601 Timestamp until order and corresponding invoice should be considered valid.
status string Enum: pending Order status, usually set to pending right after creation.
payURL string HTTPS URL URL where user should be redirected by merchant (to proceed with the invoice).
successRedirectURL string HTTPS URL URL where user will be redirected to by the payment system in case when the invoice processing will be successfull.
failureRedirectURL string HTTPS URL URL where user will be redirected to by the payment system in case when the invoice processing will be unsuccessfull (by any reason).
webhookURL string HTTPS URL If specified during order creation, defines the URL where the webhook events will be delivered.

HTTP 400 - Bad Request

The request does not match SCHEMA expectation. See error description provided in response, i.e:

{
    "fields": {
        "failureRedirectURL":"required"
    }
}

HTTP 417 - Expectation Failed

{
    "error": "No available capacity, please, try again later" 
}

The system encounters bank-related issue, no order can be created at the moment



Get bank transfer deposit order

GET /inr/orders/bank-transfer/deposits/{uuid}/

URL Parameters
Name Format Description Required
uuid UUID4 UUID of the target order. Yes
Example Request:
curl -i -X GET 
-H "Authorization: Bearer {YOUR-API-KEY}" \
"https://api.securepayment.fun/api/v1/inr/orders/bank-transfer/deposits/8eaf744b-f087-4b9a-9c11-c5946abf79b3/"

HTTP 200 - OK (Example Response):

{
    "uuid": "15c4511f-449c-4591-8ae7-45d7644c6701",
    "amount": 10000,
    "depositAmount": 9400,
    "createdAt": "2024-03-08T20:00:45.313603+02:00",
    "ttl": "2024-03-08T20:15:45.313603+02:00",
    "status": "pending",
    "payURL": "https://some.payment.page",
    "successRedirectURL": "https://some.site/success/",
    "failureRedirectURL": "https://some.site/failure/", 
    "webhookURL": "https://some.site/webhook/"
}
Name Type Format Description
uuid string UUID4 UUID4 of the created order.
amount integer Unsigned integer (0 < amount) The amount specified during the order creation (invoice amount).
depositAmount integer Unsigned integer (0 < depositAmount <= amount) The amount that will be effectively added to merhcant's balance.
createdAt string ISO 8601 The timestamp of the order creation.
ttl string ISO 8601 The timestamp until the order and the corresponding invoice should be considered valid.
status string Enum:
pending, paid, failed
  • pending: Order is in progress
  • paid: Order has been processed successfully
  • failed: Order has not been paid (error)
payURL string HTTPS URL URL where user should be redirected by merchant (to proceed with the invoice).
successRedirectURL string HTTPS URL URL where user will be redirected to by the payment system in case when the invoice processing will be successfull.
failureRedirectURL string HTTPS URL URL where user will be redirected to by the payment system in case when the invoice processing will be unsuccessfull (by any reason).
webhookURL string HTTPS URL If specified during order creation, defines the URL where the webhook events will be delivered.

HTTP 404 - Not Found:

Specified order was not found during request execution.





UPI Withdrawals


Create UPI withdrawal order

POST /inr/orders/upi/withdrawals/

Parameters
Name Type Description Required
amount unsigned integer The amount that must be paid to th destiantion UPI address. The fees will be added to this amount.
Format: 1 paise (lowest fraction), i.e., 1 INR = 100
Yes
destinationUPIAddress string Destiantion UPI address. Yes
webhookURL string The URL where the webhook events about the order status must be forwarded to. No webhooks will be emitted, if this field will be left blank. See webhooks for the details. No
Example Request:
curl -i -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {YOUR-API-KEY}" \
-d '{ \
    "amount":10000, \
    "destinationUPIAddress":"some@upi", \
    "webhookURL": "https://some.site/webhook/" \
}' \
"https://api.securepayment.fun/api/v1/inr/orders/bank-transfer/deposits/"

HTTP 201 - Created (Example Response):

{
    "uuid": "15c4511f-449c-4591-8ae7-45d7644c6701",
    "amount": 10000,
    "merchantWithdrawalAmount": 10800,
    "createdAt": "2024-03-08T20:00:45.313603+02:00",
    "status": "pending",
    "webhookURL": "https://some.site/webhook/"
}
Name Type Format Description
uuid string UUID4 UUID4 of the created order.
amount integer Unsigned integer (0 < amount) Amount specified during the order creation (invoice amount).
merchantWithdrawalAmount integer Unsigned integer (0 < amount <= merchantWithdrawalAmount) Amount that would be effectively subtracted from the merhcant's balance once the order is executed.
destinationUPIAddress string UPI Adddress The address where the outgoing payment should be made.
createdAt string ISO 8601 Timestamp of order creation.
status string Enum: pending Order status, usually set to pending right after creation.
webhookURL string HTTPS URL If specified during order creation, defines the URL where the webhook events will be delivered.

HTTP 400 - Bad Request

The request does not match SCHEMA expectation. See error description provided in response, i.e:

HTTP 417 - Expectation Failed

{
    "error": "insufficient balance"
}

The merchant does not have sufficient balance to initialise the the operation.



Get UPI withdrawal order

GET /inr/orders/upi/withdrawals/{uuid}/

URL Parameters
Name Format Description Required
uuid UUID4 UUID of the target order. Yes
Example Request:
curl -i -X GET 
-H "Authorization: Bearer {YOUR-API-KEY}" \
"https://api.securepayment.fun/api/v1/inr/orders/upi/withdrawals/8eaf744b-f087-4b9a-9c11-c5946abf79b3/"

HTTP 200 - OK (Example Response):

{
    "uuid": "15c4511f-449c-4591-8ae7-45d7644c6701",
    "amount": 10000,
    "merchantWithdrawalAmount": 10080,
    "createdAt": "2024-03-08T20:00:45.313603+02:00",
    "status": "pending",
    "webhookURL": "https://some.site/webhook/"
}
Name Type Format Description
uuid string UUID4 UUID4 of the created order.
amount integer Unsigned integer (0 < amount) The amount specified during the order creation (invoice amount).
merchantWithdrawalAmount integer Unsigned integer (0 < amount <= merchantWithdrawalAmount) Amount that would be effectively subtracted from the merhcant's balance once the order is executed.
destinationUPIAddress string UPI Adddress The address where the outgoing payment should be made.
createdAt string ISO 8601 Timestamp of order creation.
status string Enum: pending Order status, usually set to pending right after creation.
webhookURL string HTTPS URL If specified during order creation, defines the URL where the webhook events will be delivered.

HTTP 404 - Not Found:

Specified order was not found during request execution.





Bank Transfer Withdrawals


Create Bank Transfer withdrawal order

POST /inr/orders/bank-transfer/withdrawals/

Parameters
Name Type Description Required
amount unsigned integer The amount that must be paid to th destiantion UPI address. The fees will be added to this amount.
Format: 1 paise (lowest fraction), i.e., 1 INR = 100
Yes
destinationBankAccountNumber string Account number of the destination bank account Yes
destinationBankAccountHolderName string Account holder name Yes
destinationBankIFSC string Destination bank IFSC code Yes
webhookURL string The URL where the webhook events about the order status must be forwarded to. No webhooks will be emitted, if this field will be left blank. See webhooks for the details. No
Example Request:
curl -i -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {YOUR-API-KEY}" \
-d '{ \
    "amount":10000, \
    "destinationUPIAddress":"some@upi", \
    "webhookURL": "https://some.site/webhook/" \
}' \
"https://api.securepayment.fun/api/v1/inr/orders/bank-transfer/deposits/"

HTTP 201 - Created (Example Response):

{
    "uuid": "15c4511f-449c-4591-8ae7-45d7644c6701",
    "amount": 10000,
    "merchantWithdrawalAmount": 10800,
    "destinationBankAccountNumber": "123456abcd",
    "destinationBankAccountHolderName": "John Doe",
    "destinationBankIFSC": "XXXX",
    "createdAt": "2024-03-08T20:00:45.313603+02:00",
    "status": "pending",
    "webhookURL": "https://some.site/webhook/"
}
Name Type Format Description
uuid string UUID4 UUID4 of the created order.
amount integer Unsigned integer (0 < amount) Amount specified during the order creation (invoice amount).
merchantWithdrawalAmount integer Unsigned integer (0 < amount <= merchantWithdrawalAmount) Amount that would be effectively subtracted from the merhcant's balance once the order is executed.
destinationBankAccountNumber string
destinationBankAccountHolderName string
destinationBankIFSC string
createdAt string ISO 8601 Timestamp of order creation.
status string Enum: pending Order status, usually set to pending right after creation.
webhookURL string HTTPS URL If specified during order creation, defines the URL where the webhook events will be delivered.

HTTP 400 - Bad Request

The request does not match SCHEMA expectation. See error description provided in response, i.e:

HTTP 417 - Expectation Failed

{
    "error": "insufficient balance"
}

The merchant does not have sufficient balance to initialise the the operation.



Get Bank Transfer withdrawal order

GET /inr/orders/bank-transfer/withdrawals/{uuid}/

URL Parameters
Name Format Description Required
uuid UUID4 UUID of the target order. Yes
Example Request:
curl -i -X GET 
-H "Authorization: Bearer {YOUR-API-KEY}" \
"https://api.securepayment.fun/api/v1/inr/orders/bank-transfer/withdrawals/8eaf744b-f087-4b9a-9c11-c5946abf79b3/"

HTTP 200 - OK (Example Response):

{
    "uuid": "15c4511f-449c-4591-8ae7-45d7644c6701",
    "amount": 10000,
    "merchantWithdrawalAmount": 10800,
    "destinationBankAccountNumber": "123456abcd",
    "destinationBankAccountHolderName": "John Doe",
    "destinationBankIFSC": "XXXX",
    "createdAt": "2024-03-08T20:00:45.313603+02:00",
    "status": "pending",
    "webhookURL": "https://some.site/webhook/"
}
Name Type Format Description
uuid string UUID4 UUID4 of the created order.
amount integer Unsigned integer (0 < amount) The amount specified during the order creation (invoice amount).
merchantWithdrawalAmount integer Unsigned integer (0 < amount <= merchantWithdrawalAmount) Amount that would be effectively subtracted from the merhcant's balance once the order is executed.
destinationBankAccountNumber string Account number of the destination bank account
destinationBankAccountHolderName string Account holder name
destinationBankIFSC string Destination bank IFSC code
createdAt string ISO 8601 Timestamp of order creation.
status string Enum: pending Order status, usually set to pending right after creation.
webhookURL string HTTPS URL If specified during order creation, defines the URL where the webhook events will be delivered.

HTTP 404 - Not Found:

Specified order was not found during request execution.





Webhooks

Webhooks allow you to receive real-time notifications about events. To use webhooks, you need to register a webhook endpoint during the order creation. See order creation docs for more details.

SLA

  • Webhooks are usually delivered withing a few seconds after the order status update.
  • If the server does not respond with HTTP CODE 200 or HTTP CODE 201, there will be another set of attempts, each one after some delay.
  • After each failure - the delay before the next attempt increases. The min delay is 5 seconds and max delay is 1 hour.
  • Events that was not sucessfully delivered to the caller will be discarded after 7 days after the initial event.

Events

order.statusUpdate

Triggered when the order status is changed.

Payload Example:
{
    "eventType": "order.statusUpdate",
    "orderUUID": "9612437a-bf53-456b-953f-5b213338bca7",
    "status": "paid",
    "timestamp":"2024-02-05T16:27:45+02:00"
}
Name Type Format Description
orderUUID string uuid4 ID of the corresponding order.
eventType string Enum: order.statusUpdate
timestamp string ISO 8601 Timestamp of event creation.
status string Enum Current status of the order (at the moment when the webhook has been triggered). The set of possible statuses is the same as during order fetching.