Required APIs
APIs required for custom payment
APIs for integrating your own payment gateway
Webhook
The following API needs to be integrated by you, and is sent in the case of a successful or failed payment. Please build retry mechanisms to account for network & http errors. The API is idempotent on our end.
URL
/webhooks/payment-event
Headers
Content-type: application/jsonRequest
{
"orderId": "COUWLje9V7wWs9N3w",
"transactionId": "UNIQUE_PAYMENT_TRANSACTION_ID",
"paymentDateTime": "YYYY-MM-DD HH:MM:SS in UTC",
"amount": "100.00",
"paymentMode": "CASH|UPI|IMPS|NEFT|AEPS|ACCOUNT TRANSFER|INTERNET BANKING|WALLET|DEBIT CARD|CREDIT CARD|PREPAID CARD|Bharat QR|USSD",
"paymentStatus": "SUCCESS|FAILURE"
}The orderId is always prefixed with COUWL to identify Setu payment requests.
Response
{
"status": "acknowledged"
}APIs you need to support
These APIs are needed to handle various payment scenarios and let Setu know about payment status.
Get payment status
URL
As provided by you, with the suffix /setu/v1/getPaymentStatus.
For example, if the URL provided by you is https://example.com, the URL for this API will be https://example.com/setu/v1/getPaymentStatus.
Headers
X-SETU-BILLPAY-API-KEY: 77kxHrhbKNYXMwzHWFranymXV2xRkSRE
Content-Type: application/jsonRequest
{
"orderId": "COUWLje9V7wWs9N3w"
}Response
{
"status": "success/invalid-order-id",
"message": "",
"data": {
"orderId": "COUWLje9V7wWs9N3w",
"transactionId": "UNIQUE_PAYMENT_TRANSACTION_ID",
"paymentDateTime": "YYYY-MM-DD HH:MM:SS in UTC",
"amount": "100.00",
"paymentMode": "CASH|UPI|IMPS|NEFT|AEPS|ACCOUNT TRANSFER|INTERNET BANKING|WALLET|DEBIT CARD|CREDIT CARD|PREPAID CARD|Bharat QR|USSD",
"paymentStatus": "SUCCESS|FAILURE"
}
}Refund
This API should be be idempotent on your end.
URL
As provided by you, with the suffix /setu/v1/refund.
For example, if the URL provided by you is https://example.com, the URL for this API will be https://example.com/setu/v1/refund.
Headers
X-SETU-BILLPAY-API-KEY: 77kxHrhbKNYXMwzHWFranymXV2xRkSRE
Content-Type: application/jsonRequest
{
"orderId": "COUWLje9V7wWs9N3w",
"amount": "100.00",
"transactionId": "UNIQUE_PAYMENT_TRANSACTION_ID"
}Response
{
"status": "success/failure",
"message": "Accepted/Reason for rejection",
"data": {
"orderId": "COUWLje9V7wWs9N3w",
"transactionId": "UNIQUE_PAYMENT_TRANSACTION_ID",
"refundId": "UNIQUE_REFUND_ID"
}
}Refund status — optional webhook
URL
/webhooks/refund-event
Headers
Content-type: application/json
x-api-user: api user name issued by Setu
x-api-password: api password issued by SetuRequest
{
"orderId": "COUWLje9V7wWs9N3w",
"refundId": "UNIQUE_REFUND_ID",
"refundStatus": "success/failure",
"refundDateTime": "YYYY-MM-DD HH:MM:SS in UTC"
}Response
{
"status": "acknowledged"
}See API reference for more information.
Listen to user events
You can optionally listen to events sent by Setu. Please check supported user events.