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/
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 |
- Updates the order's state to paid
- Creates a fake underlying transaction for an order.
- Schedules corresponding webhook event sumbission (if configured).
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 |
- Updates the order's state to failed
- Creates a fake underlying transaction for an order.
- Schedules corresponding webhook event sumbission (if configured).
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 |
- Updates the order's state to paid
- Creates a fake underlying transaction for an order.
- Schedules corresponding webhook event sumbission (if configured).
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 |
- Updates the order's state to failed
- Creates a fake underlying transaction for an order.
- Schedules corresponding webhook event sumbission (if configured).
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 |
|
| 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 |
|
| 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. |