Notification

SolidGate can notify merchants on different events taking place with their orders. Callback notification is to be sent by POST-request to the URL specified by the merchant in JSON format.

There are the following types of notification:
Order status Callback - notification about any change of order status;

Chargeback notification - chargeback notifications from Bank.

Order-Status-Callback

In order to use the function of notifications on order status changes, the merchant shall send filled attribute call_back_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/payments/signedpay/callback

Request parameters

ParameterTypeDescriptionExample
orderobjectThe object with order information 
order:order_idstringOrder ID specified in the merchant system1572343279551
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: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:total_fee_amountintegerTotal fee by order transaction45
order:fee_currencystringThe currency of the order feeUSD
order:true_ipstringUser true IP64.51.120.120
order:risk_ratingstringRisk rating from ThreatMetrix Online Fraud Detection System (high, medium, low, neutral, trusted)high
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 fee - 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: card_tokenobject  
Transaction: card: 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
transactions:<transaction_id>:feeobjectFee for specified transaction 
transactions:<transaction_id>:fee:amountintegerFee amount for transaction - integer without fractional component (i.e cents). For instance, 120 (USD) means 1 USD and 20 cents120
transactions:<transaction_id>:fee:currencystringCurrency of transaction fee - 3-digit letter code under ISO 4217USD
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:card_tokenobject  
transactions:<transaction_id>:card: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://pay.signedpay.com/api/v1/verify-3ds/24230956/f3c4d..36637
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> :reason_codestringReason code of chargeback222
payment_adviserobject  
payment_adviser:advisestringRecommendation for next paymentpay / resign / recurring

Example success request

{
  "pay_form": {
    "token": "5849cf0468afc0ac4be4963c619b776eee75271d56e3c6621ab21",
    "design_name": "promo_christmas"
  },
  "transaction": {
    "amount": 2575,
    "created_at": "2019-10-29 10:01:20",
    "currency": "USD",
    "descriptor": "DESCRIPTOR",
    "fee": {
      "amount": 35,
      "currency": "USD"
    },
    "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_token": {
          "token": "3a5e10e65c9b6567c6a23738017ef5aefef0c42905c0cb3def5723ba8fe47a819"
        },
        "card_type": "DEBIT",
        "country": "TUR",
        "number": "471688XXXXXX3303"
      },
      "created_at": "2019-10-29 10:01:19",
      "currency": "USD",
      "descriptor": "FAKE_PSP",
      "fee": {
        "amount": 80,
        "currency": "USD"
      },
      "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",
      "fee": {
        "amount": 35,
        "currency": "USD"
      },
      "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",
    "fee_currency": "USD",
    "fraudulent": true,
    "marketing_amount": 2575,
    "marketing_currency": "USD",
    "order_id": "1572343279551",
    "processing_amount": 2575,
    "processing_currency": "USD",
    "refunded_amount": 2575,
    "status": "refunded",
    "total_fee_amount": 115
  },
  "verify_url": "https://pay.signedpay.com/api/v1/verify-3ds/24230956/f3c4d6af64e7e8ed58aea6cc0c938b230d594b9c4ec1dd224a471d01a318ebc4d2fb8cdba9dbd7d9fe3fe73ca6c944136637",
  "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 is supposed to send 200th code in response to callback sent and JSON as follows:

Example of success response

{
  "status": "ok"
}

If the response is different from specified above, a callback will be considered as not delivered and will be re-notification during 24 hours by the next schedule :
1) First re-notification after 15 minutes
2) Second re-notification after 30 minutes
3) Third re-notification after 1 hour
4) Fourth re-notification after 2 hour
5) Fifth re-notification after 4 hour
6) Sixth re-notification after 8 hour
7) Seventh re-notification after 16 hour
8) Ninth re-notification after 24 hour

Chargeback Notifications

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/payments/signedpay/chargeback-notification

Request 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, etc.
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:marketing_fee_currencystringfee amount currencyUSD
chargeback:marketing_fee_amountintegerfee amount commission10
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
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


 

Example success response

{
  "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",
    "marketing_fee_currency": "USD",
    "marketing_fee_amount": 10
  },
  "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"
  }
}

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 is supposed to send 200th code in response to callback sent and JSON as follows:

Response

{
  "status": "ok"
}

If the response is different from specified above, the callback will be considered as not delivered.

Post messages

Payment form in the iframe is able to communicate with parent window by postMessage.
 

For receiving messages you must execute JavaScript code:

window.addEventListener('message', function (msg) {
console.log(msg');
}, false)

After the execution of this code, you can analyze the status of payment and height of the form.

Control of height of the form is useful for work in different locations. For example, the payment form for the USA location has additional fields (address, city, zip code), the form of EU location has no such fields, so they have different height. Solid is controlling the number of fields, the height of iframe must be controlled by the merchant. 
After the form is submitted SOLID doesn't send notification about the form submit.  Notification is sent after handling of the order.

Available types of messages:

WindowHeight {
height:integer,
type:"windowHeight"
}

OrderStatus {
response: { ... },
type:"orderStatus"
}

Example a CustomEvent:

{
  "pay_form": {
    "token": "3a6dbbb7ddd4e555fdbbd233a5d4c0a8076472155afeda8625dad7ca",
    "design_name": "form_design"
  },
  "transactions": {
    "2094700805afedaa47b17aaf": {
      "id": "2094700805afedaa47b17aaf",
      "operation": "pay",
      "status": "fail",
      "descriptor": "descriptor.net",
      "amount": 1200,
      "currency": "USD",
      "fee": {
        "amount": 12,
        "currency": "USD"
      },
      "card": {
        "bank": "US BANK NA",
        "bin": "444411",
        "brand": "VISA",
        "country": "USA",
        "number": "444411XXXXXX1111",
        "card_exp_month": "11",
        "card_exp_year": 2024
      }
    }
  },
  "error": {
    "code": "2.01",
    "messages": [
      "Invalid Data"
    ],
    "recommended_message_for_user": "Invalid Data"
  },
  "order": {
    "order_id": "209470080",
    "status": "declined",
    "amount": 9900,
    "refunded_amount": 0,
    "currency": "RUB",
    "marketing_amount": 157,
    "marketing_currency": "USD",
    "processing_amount": 1200,
    "processing_currency": "USD",
    "descriptor": "paylife.net",
    "fraudulent": false,
    "total_fee_amount": 12,
    "fee_currency": "USD"
  }
}

Alert-chargeback notifications

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/payments/signedpay/alert-chargeback-notification

Request 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 

Example success response

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

Merchant is supposed to send 200th code in response to callback sent and JSON as follows:

Example success response by merchant

{
  "status": "ok"
}

If the response is different from specified above, the callback will be considered as not delivered.