Webhooks

SolidGate can notify merchants on different events taking place with their orders. Webhook notification is to be sent by POST-request to the URL specified by the merchant in JSON format.

Process events

When your server receives webhook notifications, it should acknowledge and respond with any 2xx HTTP status code within 30 seconds. If we don't get this response in time, the webhook will fail, and we will try to resend it.

Webhook retries

If you're not responding correctly and the webhook notification is failed, the retry mechanism automatically will try to resend it multiple times.

We will try to deliver notifications several times as stated below:

15 minutes after the initial failed notification
30 minutes after the previously failed retry
1 hour after the previously failed retry
2 hours after the previously failed retry
4 hours after the previously failed retry
8 hours after the previously failed retry
16 hours after the previously failed retry
24 hours after the previously failed retry

Handle duplicate events

Occasionally you could receive the same event more than once. For example, it could happen while retrying notifications or when you request to resend some events.

We advise you to guard against duplicated events by making your event processing idempotent. One way of doing this is logging the event ID you’ve processed and then not processing already-logged events.

We provide the event ID in the request header params as described below.

Header	Description	Example
solidgate-event-id	The unique event identifier	e1765cf7-70f7-4e56-8fb2-bd88744a94d1

Order Status

In order to use the function of notifications on order status changes, the merchant shall send filled attribute callback_url of web-resource on its end. POST-requests will be sent to this URL in JSON by notifying the current order status.

POST https://your-domain.com/{custom_URI}

Card Order Status Webhook Body Parameters

Parameter	Type	Description	Example
order	object	The object with order information
order:order_id	string	Order ID specified in the merchant system	1572343279551
order:amount	integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	2575
order:currency	string	Order currency. 3 letter currency code subject to ISO-4217	USD
order:descriptor	string	Descriptor	DESCRIPTOR
order:order_description	string	A description of the order.	Acquiring user account from previously saved card
order:traffic_source	string	A source of traffic.	experiment_id=10
order:processing_amount	integer	The amount in processing currency	1323
order:processing_currency	string	Processing currency	USD
order:fraudulent	boolean	The customer was detected on the merchant end to be a suspicious one	TRUE
order:marketing_amount	integer	Order amount converted in USD (or any other currency agreed) under open FX sources at the moment of transaction. This can be applied only for marketing forecasting	2575
order:marketing_currency	string	The currency of the order amount for marketing analytics	USD
order:status	string	Status of processed payment. Types of statuses are described in respective directories	created
order:refunded_amount	integer	The amount which was refunded	500
pay_form	object	An object with payment form information
pay_form:token	string	Payment form token	5849cf0468afc...c6621ab21
pay_form:design_name	string	Name of design to show payment form	promo_christmas
transaction	object	An object with current transaction information
transaction:id	string	Identification of current transaction	1495123020887591dc450088f1
transaction:operation	string	Type of current transaction. Transaction types are described in the respective directory	refund
transaction:status	string	Status of current refund. Transaction statues are described in the respective directory	success
transaction: descriptor	string	Descriptor	DESCRIPTOR
transaction:amount	integer	Refund amount	2575
transaction:currency	string	The currency of transaction - 3-digit letter code under ISO 4217	USD
transaction: card	object	Object with information about the card. Present in payment transactions
transaction: card: bank	string	Bank-emitent	BUILDING SOCIETY
transaction: card: bin	string	Card BIN	444455
transaction: card: brand	string	Card Brand	VISA
transaction: card: country	string	Country of bank	GBR
transaction: card: number	string	Masked card number	444455XXXXXX6666
transaction:card:card_exp_month	string	A month of the expiration date on a card. (2-digit format)	3
transaction:card:card_exp_year	integer	A year of the expiration date on a card. (4-digit format)	2025
transaction:card:card_type	string	A type of the card.	DEBIT
transaction: card_token	object
transaction:card_token: token	string	Card token to be used for recurring payments. It will be returned in case of successful payment	4056cd8cccf96...40015a997d74
transaction:refund_reason	string	In case the refund is performed in the admin panel, you will receive the reason of refund	Verify alert - Friendly Fraud
transaction:refund_reason_code	string	In case the refund is performed in the admin panel, you will receive the reason code of refund	17
transactions	object	An object with transaction information.
transactions:<transaction_id>	string	Transaction identification within order. It contains an object with detailed information of specified transaction. Order can have several transactions	1495123020887591dc450088f1
transactions:<transaction_id>:id	string	Transaction identification within order	1495123020887591dc450088f1
transactions:<transaction_id>:operation	string	Transaction type. Transaction types are described in respective directory	pay
transactions:<transaction_id>:status	string	Transaction status within order. Transaction statuses are described in respective directory	success
transactions:<transaction_id>:descriptor	string	Descriptor	DESCRIPTOR
transactions:<transaction_id>:amount	integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	2575
transactions:<transaction_id>:currency	string		USD
billing_details	object	Billing Details
billing_details:address	string	Adress of the billing	8th Ave, Bowie Lane
billing_details:zip	string	ZIP for the billing	10001
billing_details:country	string	Country of the billing	USA
billing_details:city	string	City of the billing	New York
billing_details:state	string	State of the billing	FL
transactions:<transaction_id>:card	object	Object with information about the card. Present in payment transactions.
transactions:<transaction_id>:card:bin	string	Card BIN	444455
transactions:<transaction_id>:card:brand	string	Card brand	VISA
transactions:<transaction_id>:card:number	string	Masked card number	444455XXXXXX6666
transactions:<transaction_id>:card:bank	string	Bank that issues the card	NATIONWIDE BUILDING SOCIETY
transactions:<transaction_id>:card:country	string	Country of bank	GBR
transactions:<transaction_id>:card:card_exp_month	string	A month of expiration date on the card (2-digit format).	3
transactions:<transaction_id>:card:card_exp_year	integer	A year of expiration date on the card (4-digit format).	2025
transactions:<transaction_id>:card:card_type	string	A type of the card.	DEBIT
transactions:<transaction_id>:card_token	object
transactions:<transaction_id>:card_token:token	string	Card token to be used for recurring payments. It will be returned in case of successful payment	4056cd8cccf96...40015a997d74
verify_url	string	Url for 3DS verification	https://acs.solidgate.com/api/v1/verify-3ds/554293692/96454d39ed80f256e9f77bb36271b2aff0c2af3ec769911dfd
chargebacks	object	An object with information on the chargeback
chargebacks:<chargebacks_id>	string	Chargeback identification within order. It contains an object with detailed information of specified chargeback	2
chargebacks:<chargebacks_id> :id	integer	Chargeback identification within order	2
chargebacks:<chargebacks_id> :dispute_date	string	Dispute date	2017-07-04
chargebacks:<chargebacks_id> :settlement_date	string	Settlement date	2017-07-04
chargebacks:<chargebacks_id> :amount	integer	Chargeback amount	1000
chargebacks:<chargebacks_id> :currency	string	Chargeback currency	USD
chargebacks:<chargebacks_id> :status	string	Status of the chargeback flow in the chargeback cycle	in_progress, document_sent, reversed, accepted, reversed, resolved, resolved_reversal
chargebacks:<chargebacks_id>: type	string	Stage of the chargeback flow	1st_chb, 2nd_chb, arbitration
chargebacks:<chargebacks_id>: reason_code	string	Chargeback Reason Code	10.4
chargebacks:<chargebacks_id>: reason_group	string	Chargeback Reason Group	Fraud
chargebacks:<chargebacks_id>: reason_description	string	Chargeback Reason Description	Fraud – Card-Absent Environment
chargebacks:<chargebacks_id> :chargeback_flow	object	Chargeback operations
chargebacks:<chargebacks_id> :chargeback_flow: <id>	object	Chargeback identification within chb operations.	269323
chargebacks:<chargebacks_id> :chargeback_flow: <id>:id	integer	Unique id for the chargeback flow	269323
chargebacks:<chargebacks_id> :chargeback_flow: <id>:amount	integer	Amount as an integer without fractions (i.e cents)	100
chargebacks:<chargebacks_id> :chargeback_flow: <id>:dispute_amount	integer	The amount which would be disputed as an integer without fractions (i.e. in cents) in the chb_currency	100
chargebacks:<chargebacks_id> :chargeback_flow: <id>: currency	string	3 letter currency code under ISO 4217	USD
chargebacks:<chargebacks_id> :chargeback_flow: <id>: type	string	Stage of the chargeback flow	1st_chb, 2nd_chb, arbitration
chargebacks:<chargebacks_id> :chargeback_flow: <id>: status	string	Status of the chargeback flow in the chargeback cycle	in_progress, document_sent, reversed, accepted, reversed, resolved, resolved_reversal
chargebacks:<chargebacks_id> :chargeback_flow: <id>: date	string	Settlement date	2019-06-14
chargebacks:<chargebacks_id> :chargeback_flow: <id>: updated_date	string	Date when the chargeback flow was updated	2019-06-14
chargebacks:<chargebacks_id> :chargeback_flow: <id>: deadline_date	string	Date till the chargeback flow should be updated or decision made	2019-06-14
chargebacks:<chargebacks_id> :chargeback_flow: <id>: arn_code	string	Acquirer reference number for the chargeback
payment_adviser	object
payment_adviser:advise	string	Recommendation for next payment	pay / resign / recurring
device_info	object
device_info:user_agent	string	Device user agent info	Mozilla/5.0 (Linux; U; Android 4.4.2; zh-cn; GT-I9500 Build/KOT49H) AppleWebKit/537.36 (KHTML, like Gecko)Version/4.0 MQQBrowser/5.0 QQ-URL-Manager Mobile Safari/537.36

Card Order Status Webhook Sample
                                    {
  "pay_form": {
    "token": "5849cf0468afc0ac4be4963c619b776eee75271d56e3c6621ab21",
    "design_name": "promo_christmas"
  },
  "transaction": {
    "amount": 2575,
    "created_at": "2019-10-29 10:01:20",
    "currency": "USD",
    "descriptor": "DESCRIPTOR",
    "id": "019df544f616335014f36d45644ecaa05db80df08ca94",
    "operation": "refund",
    "status": "success",
    "updated_at": "2019-10-29 10:01:20"
  },
  "transactions": {
    "019df544f616335014f36d45644ecaa05db80defcec25": {
      "amount": 2575,
      "card": {
        "bin": "471688",
        "brand": "VISA",
        "card_exp_month": "08",
        "card_exp_year": 2022,
        "card_holder": "diana goodman",
        "card_type": "DEBIT",
        "country": "TUR",
        "number": "471688XXXXXX3303"
      },
       "card_token": {
          "token": "3a5e10e65c9b6567c6a23738017ef5aefef0c42905c0cb3def5723ba8fe47a819"
        },
      "created_at": "2019-10-29 10:01:19",
      "currency": "USD",
      "descriptor": "FAKE_PSP",
      "id": "019df544f616335014f36d45644ecaa05db80defcec25",
      "operation": "pay",
      "status": "success",
      "updated_at": "2019-10-29 10:01:20"
    },
    "019df544f616335014f36d45644ecaa05db80df08ca94": {
      "amount": 2575,
      "created_at": "2019-10-29 10:01:20",
      "currency": "USD",
      "descriptor": "FAKE_PSP",
      "id": "019df544f616335014f36d45644ecaa05db80df08ca94",
      "operation": "refund",
      "status": "success",
      "updated_at": "2019-10-29 10:01:20"
    },
     "billing_details": {
            "address": "11437 Woodmeadow Pkwy",
            "zip": "85001",
            "country": "USA",
            "city": "New Delhi",
            "state": "TX"
      },
  },
  "order": {
    "amount": 2575,
    "currency": "USD",
    "descriptor": "FAKE_PSP",
    "fraudulent": true,
    "marketing_amount": 2575,
    "marketing_currency": "USD",
    "order_id": "1572343279551",
    "order_description": "Acquiring user account from previously saved card",
    "traffic_source": "experiment_id=10", 
    "processing_amount": 2575,
    "processing_currency": "USD",
    "refunded_amount": 2575,
    "status": "refunded"
  },
"chargebacks":{
      "494531":{
         "id":494531,
         "dispute_date":"2021-07-13",
         "settlement_date":"2021-07-13",
         "amount":1200,
         "status":"accepted",
         "reason_code":"4853",
         "currency":"USD",
         "type":"1st_chb",
         "chargeback_flow":{
            "759854":{
               "id":759854,
               "amount":1200,
               "currency":"USD",
               "type":"1st_chb",
               "status":"accepted",
               "date":"2021-07-13",
               "updated_date":"2021-07-13",
               "deadline_date":"2021-07-23",
               "arn_code":"21edw"
               }
         }
     }
},
  "verify_url": "https://acs.solidgate.com/api/v1/verify-3ds/554293692/96454d39ed80f256e9f77bb36271b2aff0c2af3ec769911dfd",
  "payment_adviser": {
    "advise": "recurring"
  }
}
                                

For the purpose of distinguishing every “Solid” transaction, we will provide you with a signature that was generated according to the following rules:
Access to SolidGate Gateway API.

Chargeback

Merchant can receive chargeback notifications. Merchant shall transmit filled parameter chargeback_notification_url - web-resource address on merchant end where POST request in JSON format will be sent by notifying about coming chargeback.

POST https://your-domain.com/{custom_URI}

Chargeback Webhook Body Parameters

Parameter	Type	Description	Example
chargeback	object	Object with chargeback information
chargeback:id	string	Unique chargeback identification	141368
chargeback:dispute_date	string	Date of issuing chargeback when customer addresses this to the bank	2019-06-14
chargeback:settlement_date	string	Settlement date	2019-06-14
chargeback:amount	integer	Amount of chargeback body (face value) is integer without fractions (i.e. cents).	100
chargeback:currency	string	3 letter currency code subject to ISO 4217	USD
chargeback:reason_code	string	Chargeback reason code	16
chargeback:status	string	Current status of the dispute in the chargeback cycle	in_progress, document_sent, reversed, accepted, reversed, resolved, resolved_reversa
chargeback:reason_group	string	Chargeback reason code group	Fraud, Authorization, Processing Error, Consumer Disputes
chargeback:reason_description	string	Chargeback reason code description	1st_chb, 2nd_chb, arbitration
chargeback:type	string	Current stage of the dispute in the chargeback cycle	1st_chb, 2nd_chb, arbitration
chargeback_flow	array	Chargeback operations
chargeback_flow:id	string	Unique id for the chargeback_flow	269323
chargeback_flow:amount	integer	Amount as an integer without fractions (i.e cents)	100
chargeback_flow:dispute_amount	integer	The amount which would be disputed as an integer without fractions (i.e. in cents) in the chb_currency	100
chargeback_flow:currency	string	3 letter currency code under ISO 4217	USD
chargeback_flow:type	string	Stage of the chargeback flow	1st_chb, 2nd_chb, arbitration
chargeback_flow:status	string	Status of the chargeback flow in the chargeback cycle	in_progress, document_sent, reversed, accepted, reversed, resolved, resolved_reversal
chargeback_flow:date	string	Settlement date	2019-06-14
chargeback_flow:updated_date	string	Date when the chargeback flow was updated	2019-06-14
chargeback_flow:deadline_date	string	Date till the chargeback flow should be updated or decision made	2019-06-24
chargeback_flow:arn_code	string	Acquirer reference number for the chargeback
order	object
order:order_id	string	Unique order id number specified in merchant system	1560508789823
order:amount	integer	Amount of chargeback body (face value) is integer without fractions (i.e. cents).	100
order:currency	string	3 letter currency code subject to ISO 4217	USD
order:status	string	Order status at the moment of creating request	approved

Chargeback Webhook Sample
                                    {
  "chargeback": {
    "id": "141368",
    "dispute_date": "2019-06-14",
    "settlement_date": "2019-06-14",
    "amount": 100,
    "currency": "USD",
    "reason_code": "16",
    "status": "in_progress",
    "reason_group": "Consumer Disputes",
    "reason_description": "Credit Purchase Amount- Damaged Goods",
    "type": "1st_chb"
  },
  "chargeback_flow": [
    {
      "id": "269323",
      "amount": 100,
      "dispute_amount": 100,
      "currency": "USD",
      "type": "1st_chb",
      "status": "in_progress",
      "date": "2019-06-14",
      "updated_date": "2019-06-14",
      "deadline_date": "2019-06-24",
      "arn_code": null
    }
  ],
  "order": {
    "order_id": "1560508789823",
    "amount": 100,
    "currency": "USD",
    "status": "approved"
  }
}
                                

Alert-chargeback

Merchant can receive chargeback alerts notifications. Merchant shall transmit filled parameter alert_chargeback_notification_url - web-resource address on merchant end where POST request in JSON format will be sent by notifying about coming chargeback alert.

POST https://your-domain.com/{custom_URI}

Alert Chargeback Webhook Body Parameters

Parameter	Type	Description	Example
alert	object	Object with chargeback alert information
alert:id	integer	Unique chargeback alert identification	35
alert:provider_name	string	Name of provider, that sent alerts	Ethoca
alert:provider_id	integer	Id of alert in the provider system	33012
alert:alert_date	string	Date of alert	2019-11-25 11:01:03
alert:amount	integer	The amount, which pointed in alert	200
alert:currency	string	3 letter currency code subject to ISO 4217	EUR
order	object
order:id	string	Unique order id number specified in merchant system	1559728296457
order:amount	integer	Amount of chargeback body (face value) is integer without fractions (i.e. cents).	10013
order:currency	string	3 letter currency code subject to ISO 4217	USD
order:status	string	Order status at the moment of creating request	approved
order:created_at	string	Date of creating the transaction

Alert Chargeback Webhook Sample | Success
                                    {
  "alert": {
    "id": 35,
    "provider_name": "ethoca",
    "provider_id": 33012,
    "alert_date": "2017-11-25 11:01:03",
    "amount": 200,
    "currency": "EUR"
  },
  "order": {
    "id": "1559728296457",
    "amount": 3,
    "currency": "USD",
    "status": "refunded",
    "created_at": "2019-06-05 09:51:38"
  }
}
                                

Fraud Alert

Fraud Alert Webhook Body Parameters

Parameter	Type	Description	Value sample
order_id	String	Order ID	777
fraud_amount	Integer	Fraud order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.	2575
fraud_currency	String	Fraud order currency (3 letter code under ISO 4217)	USD
fraud_amount_usd	Integer	Fraud order amount in USD	12367
fraud_type	Integer	Type of fraud	6
card_scheme	String	Card Scheme	VISA
fraud_report_day	String	Day of the report of the fraud	2020-03-24 14:22:15
reason_code_description	string	Description of reason code	Fraudulent Use of Account Number

Fraud Alerts Webhook Sample 
                                    {
  "order_id": "1584714374170",
  "fraud_amount": 100,
  "fraud_currency": "USD",
  "fraud_amount_usd": 100,
  "fraud_report_date": "2020-03-20 14:26:15",
  "card_scheme": "VISA",
  "fraud_type": "6",
  "reason_code_description": "Fraudulent Use of Account Number"
}
                                