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.

Add endpoints for events

You can manage webhooks in the channel settings under the Developer section of the Hub.

It is possible to add up to 20 different endpoints to receive the following events:

Updated Card Order - the status of a card order has been updated
Received Card Dispute - a new Dispute for the card order has been received
Received Card Fraud Alert - a TC40/SAFE alert has been received
Received Card Prevention Alert - an Issuer Network Alert has been received
Updated Subscription** - a subscription or a related order status has been updated
Updated Alternative Order - the status of an alternative order has been updated

If you select to receive the same event for several endpoints, we will send the webhook notification to all of them.

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

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:order_description	string	Order description in UTF-8 code.	Premium package
order:traffic_source	string	Source of traffic	facebook
order:customer_email	string	Customer email	jondou@gmail.com
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 of order transaction (how it looks in the Bank statement)	FAKE_PSP
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
order_metadata	object	Metadata is useful for storing additional, structured information about an object. The object consists of a set of key-value pairs (e.g. “coupon_code”: “NY2018", “partner_id”: “123989"). The callback notification returns an order_metadata from the order in each state. The validation of up to 10 fields with an upper limit of 255 characters.
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 of order transaction (how it looks in the Bank statement)	FAKE_PSP
transaction:amount	integer	Refund amount	2575
transaction: created_at	string	Transaction created DateTime	2019-05-17 9:06:21
transaction:updated_at	string	Transaction updated DateTime	2019-05-17 9:06:21
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_holder	string	Cardholder Name	Test User
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 of order transaction (how it looks in the Bank statement)	FAKE_PSP
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	The currency of the order amount for marketing analytics.	USD
transactions:<transaction_id>:created_at	string	Transaction created DateTime	2019-05-17 9:06:21
transactions:<transaction_id>:updated_at	string	Transaction updated DateTime	2019-05-17 9:06:21
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
transactions:<transaction_id>:billing_details	object	Billing Details
transactions:<transaction_id>:billing_details:address	string	Address of the billing	8th Ave, Bowie Lane
transactions:<transaction_id>:billing_details:zip	string	ZIP for the billing	10001
transactions:<transaction_id>:billing_details:country	string	Country of the billing	USA
transactions:<transaction_id>:billing_details:city	string	City of the billing	New York
transactions:<transaction_id>:billing_details:state	string	State of the billing	FL
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	The date on which the chargeback was created by the Issuer	2017-07-04
chargebacks:<chargebacks_id>:settlement_date	string	The date on which the chargeback was financially settled	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
                                    {
  "transaction": {
    "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"
  },
  "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", 
    "customer_email":"jondou@gmail.com",
    "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"
               }
         }
     }
},
  "order_metadata": {
    "coupon_code": "NY2018",
    "partner_id": "123989",
    "udf_client_type": "vipClient",
    "udf_delivery_group": "fastDelivery"
     },
  "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

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	The date on which the chargeback was created by the Issuer	2019-06-14
chargeback:settlement_date	string	The date on which the chargeback was financially settled	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	10
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	Fraud – Card-Present Environment
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:settlement_date	string	The date on which the chargeback was financially settled	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": "10",
    "status": "in_progress",
    "reason_group": "Fraud",
    "reason_description": "Fraud – Card-Absent Environment",
    "type": "1st_chb"
  },
  "chargeback_flow": [
    {
      "id": "269323",
      "amount": 100,
      "dispute_amount": 100,
      "currency": "USD",
      "type": "1st_chb",
      "status": "in_progress",
      "date": "2019-06-14",
      "settlement_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

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	Transaction created DateTime	2019-12-45 11:01:03

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"
}
                                