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:

  1. 15 minutes after the initial failed notification
  2. 30 minutes after the previously failed retry
  3. 1 hour after the previously failed retry
  4. 2 hours after the previously failed retry
  5. 4 hours after the previously failed retry
  6. 8 hours after the previously failed retry
  7. 16 hours after the previously failed retry
  8. 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.

HeaderDescriptionExample
solidgate-event-idThe unique event identifiere1765cf7-70f7-4e56-8fb2-bd88744a94d1

Order Status

 

 Card Order Status Webhook Body Parameters

ParameterTypeDescriptionExample
orderobjectThe object with order information 
order:order_idstringOrder ID specified in the merchant system1572343279551
order:order_descriptionstringOrder description in UTF-8 code.Premium package
order:traffic_sourcestringSource of trafficfacebook
order:customer_emailstringCustomer emailjondou@gmail.com
order:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents2575
order:currencystringOrder currency. 3 letter currency code subject to ISO-4217USD
order:descriptorstringDescriptor of order transaction (how it looks in the Bank statement)FAKE_PSP
order:traffic_sourcestringA source of traffic.experiment_id=10
order:processing_amountintegerThe amount in processing currency1323
order:processing_currencystringProcessing currencyUSD
order:fraudulentbooleanThe customer was detected on the merchant end to be a suspicious onetrue
order:marketing_amountintegerOrder 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 forecasting2575
order:marketing_currencystringThe currency of the order amount for marketing analyticsUSD
order:statusstringStatus of processed payment. Types of statuses are described in respective directoriescreated
order:refunded_amountintegerThe amount which was refunded500
order_metadataobjectMetadata 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. 
transactionobjectAn object with current transaction information 
transaction:idstringIdentification of current transaction1495123020887591dc450088f1
transaction:operationstringType of current transaction. Transaction types are described in the respective directoryrefund
transaction:statusstringStatus of current refund. Transaction statues are described in the respective directorysuccess
transaction: descriptorstringDescriptor of order transaction (how it looks in the Bank statement)FAKE_PSP
transaction:amountintegerRefund amount2575
transaction: created_atstringTransaction created DateTime2019-05-17 9:06:21
transaction:updated_atstringTransaction updated DateTime2019-05-17 9:06:21
transaction:currencystringThe currency of transaction - 3-digit letter code under ISO 4217USD
transaction: cardobjectObject with information about the card. Present in payment transactions 
transaction: card: bankstringBank-emitentBUILDING SOCIETY
transaction: card: binstringCard BIN444455
transaction: card: brandstringCard BrandVISA
transaction: card: countrystringCountry of bankGBR
transaction: card: numberstringMasked card number444455XXXXXX6666
transaction:card: card_holderstringCardholder NameTest User
transaction:card:card_exp_monthstringA month of the expiration date on a card. (2-digit format)3
transaction:card:card_exp_yearintegerA year of the expiration date on a card. (4-digit format)2025
transaction:card:card_typestringA type of the card.DEBIT
transaction: card_tokenobject  
transaction:card_token: tokenstringCard token to be used for recurring payments. It will be returned in case of successful payment4056cd8cccf96...40015a997d74
transaction:refund_reasonstringIn case the refund is performed in the admin panel, you will receive the reason of refundVerify alert - Friendly Fraud
transaction:refund_reason_codestringIn case the refund is performed in the admin panel, you will receive the reason code of refund17
transactionsobjectAn object with transaction information. 
transactions:<transaction_id>stringTransaction identification within order. It contains an object with detailed information of specified transaction. Order can have several transactions1495123020887591dc450088f1
transactions:<transaction_id>:idstringTransaction identification within order1495123020887591dc450088f1
transactions:<transaction_id>:operationstringTransaction type. Transaction types are described in respective directorypay
transactions:<transaction_id>:statusstringTransaction status within order. Transaction statuses are described in respective directorysuccess
transactions:<transaction_id>:descriptorstringDescriptor of order transaction (how it looks in the Bank statement)FAKE_PSP
transactions:<transaction_id>:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents2575
transactions:<transaction_id>:currencystringThe currency of the order amount for marketing analytics.USD
transactions:<transaction_id>:created_atstringTransaction created DateTime2019-05-17 9:06:21
transactions:<transaction_id>:updated_atstringTransaction updated DateTime2019-05-17 9:06:21
transactions:<transaction_id>:cardobjectObject with information about the card. Present in payment transactions. 
transactions:<transaction_id>:card:binstringCard BIN444455
transactions:<transaction_id>:card:brandstringCard brandVISA
transactions:<transaction_id>:card:numberstringMasked card number444455XXXXXX6666
transactions:<transaction_id>:card:bankstringBank that issues the cardNATIONWIDE BUILDING SOCIETY
transactions:<transaction_id>:card:countrystringCountry of bankGBR
transactions:<transaction_id>:card:card_exp_monthstringA month of expiration date on the card (2-digit format).3
transactions:<transaction_id>:card:card_exp_yearintegerA year of expiration date on the card (4-digit format).2025
transactions:<transaction_id>:card:card_typestringA type of the card.DEBIT
transactions:<transaction_id>:card_tokenobject  
transactions:<transaction_id>:card_token:tokenstringCard token to be used for recurring payments. It will be returned in case of successful payment4056cd8cccf96...40015a997d74
transactions:<transaction_id>:billing_detailsobjectBilling Details 
transactions:<transaction_id>:billing_details:addressstringAddress of the billing8th Ave, Bowie Lane
transactions:<transaction_id>:billing_details:zipstringZIP for the billing10001
transactions:<transaction_id>:billing_details:countrystringCountry of the billingUSA
transactions:<transaction_id>:billing_details:citystringCity of the billingNew York
transactions:<transaction_id>:billing_details:statestringState of the billingFL
verify_urlstringUrl for 3DS verificationhttps://acs.solidgate.com/api/v1/verify-3ds/554293692/96454d39ed80f256e9f77bb36271b2aff0c2af3ec769911dfd
chargebacksobjectAn object with information on the chargeback 
chargebacks:<chargebacks_id>stringChargeback identification within order. It contains an object with detailed information of specified chargeback2
chargebacks:<chargebacks_id>:idintegerChargeback identification within order2
chargebacks:<chargebacks_id>:dispute_datestringThe date on which the chargeback was created by the Issuer2017-07-04
chargebacks:<chargebacks_id>:settlement_datestringThe date on which the chargeback was financially settled2017-07-04
chargebacks:<chargebacks_id>:amountintegerChargeback amount1000
chargebacks:<chargebacks_id>:currencystringChargeback currencyUSD
chargebacks:<chargebacks_id> :statusstringStatus of the chargeback flow in the chargeback cyclein_progress, document_sent, reversed, accepted, reversed, resolved, resolved_reversal
chargebacks:<chargebacks_id>:typestringStage of the chargeback flow1st_chb, 2nd_chb, arbitration
chargebacks:<chargebacks_id>:reason_codestringChargeback Reason Code10.4
chargebacks:<chargebacks_id>:reason_groupstringChargeback Reason GroupFraud
chargebacks:<chargebacks_id>:reason_descriptionstringChargeback Reason DescriptionFraud – Card-Absent Environment
chargebacks:<chargebacks_id>:chargeback_flowobjectChargeback operations 
chargebacks:<chargebacks_id> :chargeback_flow:<id>objectChargeback identification within chb operations.269323
chargebacks:<chargebacks_id> :chargeback_flow: <id>:idintegerUnique id for the chargeback flow269323
chargebacks:<chargebacks_id> :chargeback_flow: <id>:amountintegerAmount as an integer without fractions (i.e cents)100
chargebacks:<chargebacks_id> :chargeback_flow: <id>:dispute_amountintegerThe amount which would be disputed as an integer without fractions (i.e. in cents) in the chb_currency100
chargebacks:<chargebacks_id> :chargeback_flow: <id>:currencystring3 letter currency code under ISO 4217USD
chargebacks:<chargebacks_id> :chargeback_flow: <id>:typestringStage of the chargeback flow1st_chb, 2nd_chb, arbitration
chargebacks:<chargebacks_id> :chargeback_flow: <id>:statusstringStatus of the chargeback flow in the chargeback cyclein_progress, document_sent, reversed, accepted, reversed, resolved, resolved_reversal
chargebacks:<chargebacks_id> :chargeback_flow: <id>:datestringSettlement date2019-06-14
chargebacks:<chargebacks_id> :chargeback_flow: <id>:updated_datestringDate when the chargeback flow was updated2019-06-14
chargebacks:<chargebacks_id> :chargeback_flow: <id>:deadline_datestringDate till the chargeback flow should be updated or decision made2019-06-14
chargebacks:<chargebacks_id> :chargeback_flow: <id>:arn_codestringAcquirer reference number for the chargeback 
payment_adviserobject  
payment_adviser:advisestringRecommendation for next paymentpay / resign / recurring
device_infoobject  
device_info:user_agentstringDevice user agent infoMozilla/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

ParameterTypeDescriptionExample
chargebackobjectObject with chargeback information 
chargeback:idstringUnique chargeback identification141368
chargeback:dispute_datestringThe date on which the chargeback was created by the Issuer2019-06-14
chargeback:settlement_datestringThe date on which the chargeback was financially settled2019-06-14
chargeback:amountintegerAmount of chargeback body (face value) is integer without fractions (i.e. cents).100
chargeback:currencystring3 letter currency code subject to ISO 4217USD
chargeback:reason_codestringChargeback reason code10
chargeback:statusstringCurrent status of the dispute in the chargeback cyclein_progress, document_sent, reversed, accepted, reversed, resolved, resolved_reversa
chargeback:reason_groupstringChargeback reason code groupFraud, Authorization, Processing Error, Consumer Disputes
chargeback:reason_descriptionstringChargeback reason code descriptionFraud – Card-Present Environment
chargeback:typestringCurrent stage of the dispute in the chargeback cycle1st_chb, 2nd_chb, arbitration
chargeback_flowarrayChargeback operations 
chargeback_flow:idstringUnique id for the chargeback_flow269323
chargeback_flow:amountintegerAmount as an integer without fractions (i.e cents)100
chargeback_flow:dispute_amountintegerThe amount which would be disputed as an integer without fractions (i.e. in cents) in the chb_currency100
chargeback_flow:currencystring3 letter currency code under ISO 4217USD
chargeback_flow:typestringStage of the chargeback flow1st_chb, 2nd_chb, arbitration
chargeback_flow:statusstringStatus of the chargeback flow in the chargeback cyclein_progress, document_sent, reversed, accepted, reversed, resolved, resolved_reversal
chargeback_flow:datestringSettlement date2019-06-14
chargeback_flow:settlement_datestringThe date on which the chargeback was financially settled2019-06-14
chargeback_flow:updated_datestringDate when the chargeback flow was updated2019-06-14
chargeback_flow:deadline_datestringDate till the chargeback flow should be updated or decision made2019-06-24
chargeback_flow:arn_codestringAcquirer reference number for the chargeback 
orderobject  
order:order_idstringUnique order id number specified in merchant system1560508789823
order:amountintegerAmount of chargeback body (face value) is integer without fractions (i.e. cents).100
order:currencystring3 letter currency code subject to ISO 4217USD
order:statusstringOrder status at the moment of creating requestapproved


 

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

ParameterTypeDescriptionExample
alertobjectObject with chargeback alert information 
alert:idintegerUnique chargeback alert identification
 
35
alert:provider_namestringName of provider, that sent alerts
 
Ethoca
alert:provider_idintegerId of alert in the provider system33012
alert:alert_datestringDate of alert2019-11-25 11:01:03
alert:amountintegerThe amount, which pointed in alert
 
200
alert:currencystring3 letter currency code subject to ISO 4217
 
EUR
orderobject  
order:idstringUnique order id number specified in merchant system
 
1559728296457
order:amountintegerAmount of chargeback body (face value) is integer without fractions (i.e. cents).
 
10013
order:currencystring3 letter currency code subject to ISO 4217
 
USD
order:statusstringOrder status at the moment of creating request
 
approved
order:created_atstringTransaction created DateTime2019-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

ParameterTypeDescriptionValue sample
order_idStringOrder ID777
fraud_amountIntegerFraud order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
fraud_currencyStringFraud order currency (3 letter code under ISO 4217)USD
fraud_amount_usdIntegerFraud order amount in USD12367
fraud_typeIntegerType of fraud6
card_schemeStringCard SchemeVISA
fraud_report_dayStringDay of the report of the fraud2020-03-24 14:22:15
reason_code_descriptionstringDescription of reason codeFraudulent 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"
}