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.
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:
If you select to receive the same event for several endpoints, we will send the webhook notification to all of them.
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.
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:
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 |
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 | |
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 |
{
"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 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": {
"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"
}
}
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": {
"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 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 |
{
"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"
}