—
–
/

to search

Introducing Setu Changelog Check it out ↗

Reading time — 2 minutes

Edit this page ↗

#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

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|AEPS|ACCOUNT TRANSFER|INTERNET BANKING|WALLET|DEBIT CARD|CREDIT CARD|PREPAID CARD|Bharat QR|USSD",
  "paymentStatus": "SUCCESS|FAILURE",
  "remitter": {
    "name": "XX",
    "pan": "xxxx",
    "email": "XXXX",
    "aadhaar": "XXX"
  },
  "accountInfo": "ICIC0000152|1234567890"
}

Response

{
  "status": "acknowledged"
}

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

To learn more about the remitter and accountInfo properties, please refer to the integration guide.

#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/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|AEPS|ACCOUNT TRANSFER|INTERNET BANKING|WALLET|DEBIT CARD|CREDIT CARD|PREPAID CARD|Bharat QR|USSD",
    "paymentStatus": "SUCCESS|FAILURE",
    "remitter": {
      "name": "XX",
      "pan": "xxxx",
      "email": "XXXX",
      "aadhaar": "XXX"
    },
    "accountInfo": "ICIC0000152|1234567890"
  }
}

To learn more about the remitter and accountInfo properties, please refer to the integration guide.

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