Webhooks

A webhook URL can be provided as a request parameter in the request body for certain endpoints, allowing you to receive notifications when the status of an underlying object changes.

This eliminates the need to schedule tasks or constantly poll Star SaaS’s endpoints for updates. Simply include a webhook_url in the API payload, and Star SaaS will send a POST request to your server whenever there is a status change in the object. Ensure that the webhook_url is set to HTTPS, as webhooks will not be triggered over unencrypted connections.

It’s essential to configure your endpoint URL to acknowledge Star SaaS's webhooks with standard HTTP response codes. For example, return a 2xx code to confirm the successful receipt of a POST request on your server.

If Star SaaS does not receive a 2xx acknowledgement, it will retry sending the webhook for up to 36 hours as detailed in the retry policy below.

The following Star SaaS objects trigger webhook responses:

Review
Chargeback
Payment
Refund

Not receiving webhooks?

In case of any server block or not receiving a response to your webhook URL, try whitelisting the below IP addresses:
Test Mode (Sandbox) : XX.XXX.XXX.XXX
Live Mode (Production) : XX.XXX.XXX.XXX

Retry Policy

If Star SaaS does not receive a 2xx status from your endpoint as an acknowledgement of successful webhook delivery, it keeps retrying.

The time between each retry increases exponentially by a power of 2 with jitter till a period of 12 hours. The first retry starts after 1 second of original webhook delivery.

This process is repeated 3 times. You can receive a retried webhook upto 36 hours from the delivery of the first webhook.

Review

Review notifications will be sent to the notify_url defined by merchant, in the format of NameValuePair. Below are the notification parameters:

Review

merchant_id

string

optional

Merchant ID or Merchant Number

<= 7 characters

account_id

string

optional

account_id

<= 10 characters

transaction_id

string

optional

Transaction ID generated by gateway system, the Transaction ID = Order No + '-' + 5 digits random number

<= 50 characters

order_no

string

optional

Merchat Order Number generated by Merchant

<= 50 characters

amount

string

optional

Full Order amount

<= 15 characters

currency

string

optional

Order Currency Code. Please refer to ISO 4217

<= 3 characters

order_status

string

optional

Order Status:
0: Failed (Authorization is rejected)
1: Succeed (Authorization is processed)

<= 5 characters

error_code

string

optional

Review Status:
R100: Accept
R200: Reject

<= 4 characters

result_info

string

optional

Order Status Message

<= 500 characters

note

string

optional

Same value of the “note” parameter defined in the payment request

<= 1000 characters

return_type

string

optional

Return type:
1: Real-time response from the browser
2: Real-time response from the server
3: Asynchronous response from the server

<= 1 characters

payment_method

string

optional

Payment Method

<= 50 characters

threeds_result

string

optional

3-D Secure Verification Result:
--Authentication Unavailable
--Failed
--Authentication offered but not used
--Unable to Complete Authentication

<= 100 characters

card

string

optional

Masked card number

<= 20 characters

encryption_data

string

optional

Signature Structure:
encryption_data=sha256(merchant_id + account_id + transaction_id + order_no + currency + amount + order_status + result_info + sign_key);
All encryption parameters need to remove spaces before encryption.

<= 100 characters

Chargeback

Chargeback notifications will be sent to the notify_url defined by merchant, in the format of NameValuePair. Below are the notification parameters:

Chargeback

merchant_id

string

optional

Merchant ID or Merchant Number

<= 7 characters

account_id

string

optional

Subaccount ID or Gateway Number

<= 10 characters

transaction_id

string

optional

Transaction ID generated by gateway system, the Transaction ID = Order No + '-' + 5 digits random number

<= 64 characters

order_no

string

optional

Merchat Order Number generated by Merchant

<= 50 characters

amount

string

optional

Full Order amount

<= 15 characters

currency

string

optional

Order Currency Code. Please refer to ISO 4217

<= 3 characters

order_status

string

optional

Chargeback Status Code
4000 :SEND FOR CHARGEBACK
4010 :CHARGED BACK
4020 :CHARGEBACK FAILED

<= 10 characters

error_code

string

optional

Review Status:
R100: Accept
R200: Reject

<= 4 characters

result_info

string

optional

Chargeback Status Message

<= 200 characters

chargeback_reason

string

optional

Chargeback Reason

<= 300 characters

note

string

optional

Same value of the “note” parameter defined in the payment request

<= 1000 characters

return_type

string

optional

Return type:
1: Real-time response from the browser
2: Real-time response from the server
3: Asynchronous response from the server

<= 10 characters

payment_method

string

optional

Payment Method

<= 50 characters

threeds_result

string

optional

3-D Secure Verification Result:
--Authentication Unavailable
--Failed
--Authentication offered but not used
--Unable to Complete Authentication

<= 100 characters

card

string

optional

Masked card number

<= 20 characters

billing_address

string

optional

Cardholder's billing address

<= 300 characters

first_name

string

optional

First name of Cardholder

<= 100 characters

last_name

string

optional

Last name of Cardholder

<= 50 characters

billing_city

string

optional

The city in the billing address

<= 100 characters

billing_state

string

optional

The state in the billing address

<= 100 characters

billing_country

string

optional

The country code of the country in the billing address

<= 2 characters

billing_postal_code

string

optional

The postal or zip code of the billing address

<= 100 characters

billing_phone

string

optional

Cardholder's phone number

<= 50 characters

billing_email

string

optional

Cardholder's email address

<= 200 characters

encryption_data

string

optional

Signature Structure:
encryption_data=sha256(merchant_id + account_id + transaction_id + order_no + currency + amount + order_status + result_info + sign_key);

All encryption parameters need to remove spaces before encryption.

<= 64 characters

Payment

For offline payment such as offline bank transfers, our gateway system will notify merchant with the final result via payment notification once payment is completed. These notifications will send to the ‘notify_url’ defined by merchant in HTML format via POST method.

Below are the parameters of payment notification

Payment

merchant_id

string

optional

Merchant ID or Merchant Number

<= 7 characters

account_id

string

optional

Subaccount Code or Subaccount ID or Gateway Number

<= 10 characters

transaction_id

string

optional

Transaction ID generated by gateway system, the Transaction ID = Order No + '-' + 5 digits random number

<= 64 characters

order_no

string

optional

Merchat Order Number generated by Merchant

<= 50 characters

amount

string

optional

The sum of the amounts of all items in an order; Value can be digits only
Please refer to ISO 4217 for decimal values of each currency

<= 15 characters

currency

string

optional

Order Currency Code. Please refer to ISO 4217

<= 3 characters

order_status

string

optional

Order Status:
-1: Waiting for process (This status will be used for offline transfer such as Konbini, Boleto etc.)
0: Failed
1: Succeed

<= 10 characters

error_code

string

optional

Error_code: Error Code

<= 4 characters

result_info

string

optional

Payment result information in the form of "Code + Details". Please refer to Error Code

<= 200 characters

payment_method

string

optional

Payment method. i.e. online bank transfer

<= 50 characters

threeds_result

string

optional

3-D Secure Verification Result:
--Authentication Unavailable
--Failed
--Authentication offered but not used
--Unable to Complete Authentication

<= 100 characters

return_type

string

optional

Return type:
1: Real-time response from the browser
2: Real-time response from the server
3: Asynchronous response from the server

<= 1 characters

note

string

optional

Same value of the “note” parameter defined in the payment request

<= 1000 characters

card

string

optional

Masked card number

<= 20 characters

billing_address

string

optional

Cardholder's billing address

<= 300 characters

first_name

string

optional

First name of Cardholder

<= 100 characters

last_name

string

optional

Last name of Cardholder

<= 50 characters

billing_city

string

optional

The city in the billing address

<= 100 characters

billing_state

string

optional

The state in the billing address

<= 100 characters

billing_country

string

optional

The country code of the country in the billing address

<= 2 characters

billing_postal_code

string

optional

The postal or zip code of the billing address

<= 100 characters

billing_phone

string

optional

Cardholder's phone number

<= 50 characters

billing_email

string

optional

Cardholder's email address

<= 200 characters

connector

string

optional

Connector names such as Acquirers, PSPs or Banks

<= 50 characters

encryption_data

string

optional

Signature Structure:
encryption_data=sha256(merchant_id + account_id + transaction_id + order_no + currency + amount + order_status + result_info + sign_key);

All encryption parameters need to remove spaces before encryption.

<= 64 characters

Refund

Refund notifications will be sent to the notify_url defined by merchant, in the format of NameValuePair. Below are the notification parameters:

Refund

merchant_id

string

optional

Merchant ID or Merchant Number

<= 7 characters

account_id

string

optional

Subaccount ID or Gateway Number

<= 10 characters

transaction_id

string

optional

Transaction ID generated by gateway system, the Transaction ID = Order No + '-' + 5 digits random number

<= 64 characters

order_no

string

optional

Merchat Order Number generated by Merchant

<= 50 characters

amount

string

optional

The sum of the amounts of all items in an order; Value can be digits only
Please refer to ISO 4217 for decimal values of each currency

<= 15 characters

currency

string

optional

Order Currency Code. Please refer to ISO 4217

<= 3 characters

order_status

string

optional

Refund Status Code
4100 :SEND FOR REFUND
4110 :REFUNDED
4120 :REFUNDED FAILED

<= 10 characters

error_code

string

optional

Refund Request Result
R100:Accept
R200:Reject

<= 4 characters

result_info

string

optional

Refund Status Message

<= 200 characters

note

string

optional

Same value of the “note” parameter defined in the payment request

<= 1000 characters

return_type

string

optional

Return type:
1: Real-time response from the browser
2: Real-time response from the server
3: Asynchronous response from the server

<= 10 characters

payment_method

string

optional

Payment method. i.e. online bank transfer

<= 50 characters

threeds_result

string

optional

3-D Secure Verification Result:
--Authentication Unavailable
--Failed
--Authentication offered but not used
--Unable to Complete Authentication

<= 100 characters

card

string

optional

Masked card number

<= 20 characters

billing_address

string

optional

Cardholder's billing address

<= 500 characters

first_name

string

optional

First name of Cardholder

<= 100 characters

last_name

string

optional

Last name of Cardholder

<= 50 characters

billing_city

string

optional

The city in the billing address

<= 100 characters

billing_state

string

optional

The state in the billing address

<= 100 characters

billing_country

string

optional

The country code of the country in the billing address

<= 2 characters

billing_postal_code

string

optional

The postal or zip code of the billing address

<= 100 characters

billing_phone

string

optional

Cardholder's phone number

<= 50 characters

billing_email

string

optional

Cardholder's email address

<= 200 characters

refund_amount

string

optional

Refund Amount

<= 15 characters

refund_reference_id

string

optional

Unique refund reference generated by our gateway system

<= 50 characters

encryption_data

string

optional

Signature Structure:
encryption_data=sha256(merchant_id + account_id + transaction_id + order_no + currency + amount + order_status + result_info + sign_key);

All encryption parameters need to remove spaces before encryption.

<= 64 characters

Retry Policy#

Review#

Chargeback#

Payment#

Refund#

Retry Policy

Review

Chargeback

Payment

Refund