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
  • Received Alternative Dispute - a new Dispute for the alternative order has been received

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

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

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:descriptorstringDescriptorDESCRIPTOR
order:order_descriptionstringA description of the order.Acquiring user account from previously saved card
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
pay_formobjectAn object with payment form information 
pay_form:tokenstringPayment form token5849cf0468afc...c6621ab21
pay_form:design_namestringName of design to show payment formpromo_christmas
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: descriptorstringDescriptorDESCRIPTOR
transaction:amountintegerRefund amount2575
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_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>:descriptorstringDescriptorDESCRIPTOR
transactions:<transaction_id>:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents2575
transactions:<transaction_id>:currencystring USD
billing_detailsobjectBilling Details 
billing_details:addressstringAdress of the billing8th Ave, Bowie Lane
billing_details:zipstringZIP for the billing10001
billing_details:countrystringCountry of the billingUSA
billing_details:citystringCity of the billingNew York
billing_details:statestringState of the billingFL
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
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_datestringDispute date2017-07-04
chargebacks:<chargebacks_id> :settlement_datestringSettlement date2017-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

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

ParameterTypeDescriptionExample
chargebackobjectObject with chargeback information 
chargeback:idstringUnique chargeback identification141368
chargeback:dispute_datestringDate of issuing chargeback when customer addresses this to the bank2019-06-14
chargeback:settlement_datestringSettlement date2019-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 code16
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 description1st_chb, 2nd_chb, arbitration
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: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": "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

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_atstringDate 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

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