—
–
/

to search

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