#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/json
x-api-user: api user name issued by Setu
x-api-password: api password issued by Setu

Request

{
"orderId": "COUWLje9V7wWs9N3w",
"transactionId": "UNIQUE_PAYMENT_TRANSACTION_ID",
"paymentDateTime": "YYYY-MM-DD HH:MM:SS in UTC",
"amount": "100.00",
"paymentMode": "CASH|UPI|IMPS|NEFT|ACCOUNT TRANSFER|INTERNET BANKING|WALLET|DEBIT CARD",
"paymentStatus": "SUCCESS|FAILURE"
}

The orderId is always prefixed with COUWL to identify Setu payment requests.

Response

{
"status": "acknowledged"
}

See API reference for more information.


#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.

Headers

X-SETU-BILLPAY-API-KEY: 77kxHrhbKNYXMwzHWFranymXV2xRkSRE
Content-Type: application/json

Request

{
"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|ACCOUNT TRANSFER|INTERNET BANKING|WALLET|DEBIT CARD",
"paymentStatus": "SUCCESS|FAILURE"
}
}

Refund

This API should be be idempotent on your end.

Headers

X-SETU-BILLPAY-API-KEY: 77kxHrhbKNYXMwzHWFranymXV2xRkSRE
Content-Type: application/json

Request

{
"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 Setu

Request

{
"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.


Was this page helpful?