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.
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 |
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 |
{
"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.
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": {
"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"
}
}
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": {
"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"
}