Host to host API

SolidGate API - full host-to-host REST API. Parameters are transmitted with POST-method in the request body (JSON format). The payment form is hosted on the Merchant's end.

Only PCI DSS certified merchants are eligible for full API considering that merchant accepts and processes card.

SDK Kits

In order to start working with SolidGate API, JSON requests shall be sent to URL:

https://pay.solidgate.com/api/v1

Operation type

SolidGate can do the following operation types:

  • Init Payment - operation of order initiating. This performs order creation and transaction is prepared for payment.
  • Charge - basic operation of withdrawal amounts from cardholder's account. Upon successful payment, two scenarios on this order are possible - refund or chargeback. This operation can be made via 3DS. When the operation is successfully done, cardholder data are tokenized so that the subsequent payments can be affected by token (recurring payments).
  • Recurring - operation of payment by the token. In contrast to Charge, token previously received is to be sent in the request instead of cardholder data.Upon successful payment, two scenarios on this order are possible - refund or chargeback.
  • Status - request for receiving current order status.
  • Refund - request for transferring funds back to the cardholder. Refunds can be made only on successfully paid order. Only one refund can be effected per order.
  • Auth - operation to check the availability of a required amount of funds for a specific credit card and reserve it for a subsequent Settle
  • Settle - operation is used for settling an authorization transaction that was previously performed.
  • Void -  operation is used for voiding a previously performed authorization transactions.

Please, note that all requests must be signed.

InitPayment transaction

Operation of order initiating. It shall be used while working with a payment form. This operation deems to create order in the system and return token being applied while calling payment form.

POST https://pay.solidgate.com/api/v1/init-payment

 

    Init Payment Request Body Parameters

ParameterMandatoryTypeDescriptionExample
amountYesintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents1020
currencyYesstring(3)Currency amount. 3 letter currency code under ISO-4217USD
customer_account_idNostring(100)Customer ID in the merchant's system4dad42f808
customer_date_of_birthNostring(50)Customer birth date in format YYYY-MM-DD2000-11-21
customer_emailYesstring(100)Customer emailjondou@gmail.com
customer_first_nameNostring(100)Customer's first nameJohn
customer_last_nameNostring(100)Customer last nameSnow
customer_phoneNostring(50)Customer telephone380111111111
form_nameNostring(100)Form namewo_cardholder
form_design_nameNostring(100)Form design namepromo_christmas
fraudulentNobooleanThe customer is detected by the merchant system to be suspicious one. The payment will be effected via 3DSTRUE
geo_countryYesstring(3)Customer country subject to ISO 3166-1 alpha-3GBR
geo_cityNostring(100)Customer cityNew Castle
ip_addressYesstring(50)Customer IP (only public ones)8.8.8.8
languageNostring(2)Customer language settings. Available values: RU - Russian, EN - English, FR - French, ES - Spanish, PT - Portuguese, JA - Japanese, AR - Arabic, IT - Italian, TR - Turkish, PL - Polish, DE - Germanen
order_idYesstring(100)Order ID specified in merchant system123443334
order_dateNostring(50)Date of order creation in format YYYY-MM-DD-HH-MM-SS2015-12-21 11:21:30
order_descriptionYesstring(255)Order description in UTF-8 codePremium package
order_itemsNostring(255)Order items in UTF-8 codeitem 1, item 2
platformYesstring(6)Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - applicationWEB
callback_urlNostring(255)URL of merchant page, where response with payment result will be senthttp://merchant.example/callback
fail_urlNostring(255)URL of merchant page, which a customer will be redirected in case of unsuccessful paymenthttp://merchant.example/fail
success_urlNostring(255)URL of merchant page, which a customer will be redirected in case of successful paymenthttp://merchant.example/success
chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback will be senthttp://merchant.example/chargeback
alert_chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback alerts will be senthttp://merchant.example/chargeback_alerts
verifiedNobooleanA user was verified on the shop side.TRUE
retry_attemptNointegerNumber of retry payment1
traffic_sourceNostring(255)Source of trafficFacebook
transaction_sourceNostring(255)Source of transactions on sitemain_menu
user_agentNostringUser-agent of the customerMozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36
deviceNostringDevice of customeriPhone 8 iOS 12.0
order_numberNointegerNumber of payments by user1
typeNostringParameter for transaction authorization through a payment formauth
settle_intervalNointegerTime (in hours) when auto-settle will be done1
force3dsNobooleanRouting payments flag for 3DS flow (enabled by Solid account manager)FALSE
amountYesintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents1020
currencyYesstring(3)Currency amount. 3 letter currency code under ISO-4217USD
customer_account_idNostring(100)Customer ID in the merchant's system4dad42f808
customer_date_of_birthNostring(50)Customer birth date in format YYYY-MM-DD2000-11-21
customer_emailYesstring(100)Customer emailjondou@gmail.com
customer_first_nameNostring(100)Customer's first nameJohn
customer_last_nameNostring(100)Customer last nameSnow
customer_phoneNostring(50)Customer telephone380111111111
form_nameNostring(100)Form namewo_cardholder
form_design_nameNostring(100)Form design namepromo_christmas
fraudulentNobooleanThe customer is detected by the merchant system to be suspicious one. The payment will be effected via 3DSTRUE
geo_countryYesstring(3)Customer country subject to ISO 3166-1 alpha-3GBR
geo_cityNostring(100)Customer cityNew Castle
ip_addressYesstring(50)Customer IP (only public ones)8.8.8.8
languageNostring(2)Customer language settings. Available values: RU - Russian, EN - English, FR - French, ES - Spanish, PT - Portuguese, JA - Japanese, AR - Arabic, IT - Italian, TR - Turkish, PL - Polish, DE - Germanen
order_idYesstring(100)Order ID specified in merchant system123443334
order_dateNostring(50)Date of order creation in format YYYY-MM-DD-HH-MM-SS2015-12-21 11:21:30
order_descriptionYesstring(255)Order description in UTF-8 codePremium package
order_itemsNostring(255)Order items in UTF-8 codeitem 1, item 2
platformYesstring(6)Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - applicationWEB
callback_urlNostring(255)URL of merchant page, where response with payment result will be senthttp://merchant.example/callback
fail_urlNostring(255)URL of merchant page, which a customer will be redirected in case of unsuccessful paymenthttp://merchant.example/fail
success_urlNostring(255)URL of merchant page, which a customer will be redirected in case of successful paymenthttp://merchant.example/success
chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback will be senthttp://merchant.example/chargeback
alert_chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback alerts will be senthttp://merchant.example/chargeback_alerts
verifiedNobooleanA user was verified on the shop side.TRUE
retry_attemptNointegerNumber of retry payment1
traffic_sourceNostring(255)Source of trafficfacebook
transaction_sourceNostring(255)Source of transactions on sitemain_menu
user_agentNostringUser-agent of the customerMozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36
deviceNostringDevice of customeriPhone 8 iOS 12.0
order_numberNointegerNumber of payments by user1
typeNostringParameter for transaction authorization through a payment formauth
settle_intervalNointegerTime (in hours) when auto-settle will be done1
force3dsNobooleanRouting payments flag for 3DS flow (enabled by Solid account manager)FALSE

 

Init Payment Request Sample | Success

{
  "amount": 2575,
  "callback_url": "http://merchant.example/callback",
  "currency": "USD",
  "customer_account_id": "user_id",
  "customer_date_of_birth": "2000-11-21",
  "customer_email": "example.user@example-email.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "380000000000",
  "fraudulent": true,
  "fail_url": "http://merchant.example/fail",
  "form_name": "wo_cardholder",
  "form_design_name": "promo_christmas",
  "geo_city": "New Castle",
  "geo_country": "GBR",
  "ip_address": "8.8.8.8",
  "language": "en",
  "order_date": "2015-12-21 11:21:30",
  "order_description": "Premium package",
  "order_id": "777",
  "order_items": "item 1, item 2",
  "platform": "WEB",
  "success_url": "http://merchant.example/success",
  "chargeback_notification_url": "http://merchant.example/chargeback",
  "order_number" : 1
}

 

    Init Payment Response Body Parameters | Success

ParameterTypeDescriptionExample
orderobjectObject with order information 
order:order_idstringOrder ID specified in merchant system777
order:amountintOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents2575
order:currencystringOrder currency (3 letter code under ISO 4217)USD
order:fraudulentbooleanThe customer was detected on the merchant end to be the suspicious oneTRUE
order:statusstringOrder statuscreated
pay_formobjectObject with data of payment form 
pay_form:tokenstringToken of payment form6e6525c18a2803372af41d5e8c6e7b20601
pay_form:form_urlstringPayment form urlhttps://form.solidgate.com/api/v1/purchase/6e6525c18a2803372af41d5e8c6e7b20601
pay_form:design_namestringDesign name for depicting of payment formpromo_christmas

Init Payment Response Sample | Success

{
  "order": {
    "order_id": "777",
    "amount": 2575,
    "currency": "USD",
    "fraudulent": true,
    "status": "created",
  },
  "pay_form": {
    "token": "6e6525c18a2803372af41d5e8c6e7b20601",
    "form_url": "https://form.solidgate.com/api/v1/purchase/6e6525c18a2803372af41d5e8c6e7b20601",
    "design_name" : "promo_christmas"
  }
}

 

    Init Payment Response Body Parameters | Validation Error

ParameterTypeDescriptionExample
errorobjectObject with information on error 
error:codestringError codes list2.01
error:messagesobjectError messages 
error:messages:<attribute_name>stringAttribute name where the error was foundcurrency
error:messages:<error_message>arrayThe array of error messages relating to the respective attributeThis value should not be blank.

Init Payment Response Sample | Validation Error

{
    "error": {
        "code": "2.01",
        "messages": {
            "currency": [
                "This value should not be blank."
            ],
            "customer_email": [
                "This value should not be blank."
            ],
            "ip_address": [
                "This value should not be blank."
            ],
            "order_description": [
                "This value should not be blank."
            ],
            "order_id": [
                "This value should not be blank."
            ],
            "platform": [
                "This value should not be blank."
            ]
        }
    }
}

Charge transaction

Charge request - basic operation of withdrawal amounts from cardholder's account. Upon successful withdrawal, two scenarios on this order are possible - refund or chargeback. This operation can be made via 3DS. When the operation is successfully done, cardholder data are tokenized so that the subsequent payments can be affected by token (recurring transactions).
 

POST https://pay.solidgate.com/api/v1/charge

 

    Charge Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idYesstring(100)Order ID specified in the merchant system123443334
amountYesintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents1020
currencyYesstring(3)Order currency. 3 letter currency code under ISO-4217USD
card_numberYesstring(25)Card number4111111111111111
card_holderYesstring(32)Cardholder nameJOHN SNOW
card_exp_monthYesstring(2)The month of card expiration (2-digit format)1
card_exp_yearYesstring(4)Year of card expiration (4-digit format)2024
card_cvvYesstring(4)CVV2/CVC2 card - 3 or 4 digits code123
card_pinYes/Nostring(4)Card pin (mandatory parameter for NGA location).1111
order_descriptionYesstring(255)Order description in UTF-8 code.Premium package
customer_emailYesstring(100)Customer email.jondou@gmail.com
ip_addressYesstring(50)Customer IP (only public ones).8.8.8.8
platformYesstring(6)Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application.WEB
geo_countryYesstring(3)Customer country subject to ISO 3166-1 alpha-3.GBR
order_dateNostring(50)Date of order creation in format YYYY-MM-DD-HH-MM-SS.2015-12-21 11:21:30
order_itemsNostring(255)Order description in UTF-8 code.item 1, item 2
customer_account_idNostring(100)Сustomer ID specified in the merchant system.4dad42f808
customer_first_nameNostring(100)Customer first name.John
customer_last_nameNostring(100)Customer last name.Snow
customer_phoneNostring(50)Customer phone number.380111111111
customer_date_of_birthNostring(50)Birthdate in YYYY-MM-DD format.2000-11-21
geo_cityNostring(100)Customer City.New Castle
languageNostring(2)Customer language settings. Available values: RU - Russian, EN - English.en
fraudulentNobooleanCustomer is detected by the merchant system to be suspicious one. The payment will be effected via 3DS.TRUE
callback_urlNostring(255)URL of merchant page, where response with payment result will be sent via a host-to-host connection.http://merchant.example/callback
status_urlNostring(255)URL of merchant page, which customers will be redirected upon 3DS verification on bank end with the status of operation in URL parameter - http://merchant.example/status/?order_id=123443334&status=approved.http://merchant.example/status
chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback will be sent.http://merchant.example/chargeback
alert_chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback alerts will be senthttp://merchant.example/chargeback_alerts
verifiedNobooleanA user was verified on the shop side.TRUE
retry_attemptNointegerA number of retry payment.1
traffic_sourceNostring(255)Source of traffic.facebook
transaction_sourceNostring(255)Source of transactions on site.main_menu
user_agentNostringUser-agent of the customer.Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36
deviceNostringDevice of customeriPhone 8 iOS 12.0
operating_systemNostringInformation about the operating system of the customer deviceiOS
operating_system_versionNostringInformation about the version of the operating system of the customer device12
browserNostringInformation about the browser of the customer deviceSafari
browser_versionNostringInformation about the version of the browser of the customer device12
websiteNostring(255)Website from which transaction took place.google.com
order_numberNointegerA number of payments by the user.1
addressNostring(100)Address (mandatory parameter for USA location).New York, 10005, 15 William St
stateNostring(255)State (mandatory parameter for USA location).WA
zip_codeNostring(10)Parameter for identifying a location. (mandatory parameter for USA location)10005
cityNostring(100)Customer city. (mandatory parameter for USA location)New York
cpfNostring(255)Individual taxpayer registry identification. (mandatory parameter for Brazilian location)210.717.664-73
force3dsNobooleanRouting payments flag for 3DS flow (enabled by Solid account manager)FALSE
header_acceptYes - 3D 2.0string(255)Header Accept.text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng
header_accept_languageYes - 3D 2.0string(255)Header Accept Language.ru-RU,ru;q=0.9,en-US;q=0.8
browser_color_depthYes - 3D 2.0integerColor depth of browser window.32
browser_screen_heightYes - 3D 2.0integerHeight of browser window.1920
browser_screen_widthYes - 3D 2.0integerWidth of browser window.1280
browser_java_enabledYes - 3D 2.0booleanIs java enabled on User browser.FALSE
browser_javascript_enabledYes - 3D 2.0booleanIs javascript enabled on User browser.FALSE
time_zone_offsetYes - 3D 2.0integerThe time difference, in minutes, between UTC time and the local time of the cardholder's browser.-1

Charge Request Sample | Success

{
  "transactions": {
    "00016857481e16b07fc": {
      "id": "00016857481e16b07fc",
      "operation": "pay",
      "status": "created",
      "amount": 2575,
      "currency": "USD",
      "created_at": "2019-05-17 09:06:21",
      "updated_at": "2019-05-17 09:06:32",
      "card": {
        "bank": "STATE BANK",
        "bin": "411111",
        "brand": "VISA",
        "country": "USA",
        "number": "411111XXXXXX1111",
        "card_holder": "cardholder name",
        "card_exp_month": "03",
        "card_exp_year": 2025,
        "card_type": "DEBIT"
      }
    }
  },
  "order": {
    "order_id": "777",
    "amount": 2575,
    "currency": "USD",
    "fraudulent": true,
    "marketing_amount": 2575,
    "marketing_currency": "USD",
    "status": "created",
    "refunded_amount": 0,
    "total_fee_amount": 0
  },
  "transaction": {
    "id": "00016857481e16b07fc",
    "operation": "pay",
    "status": "created",
    "amount": 2575,
    "currency": "USD",
    "created_at": "2019-05-17 09:06:21",
    "updated_at": "2019-05-17 09:06:32",
    "card": {
      "bin": "411111",
      "brand": "VISA",
      "country": "USA",
      "number": "411111XXXXXX1111",
      "card_holder": "cardholder name",
      "card_exp_month": "03",
      "card_exp_year": 2025,
      "card_type": "DEBIT"
    }
  },
  "payment_adviser": {
    "advise": "pay"
  }
}

 

    Charge Response Body Parameters | Success

ParameterTypeDescriptionExample
transactionsobjectObject with information of transactions. 
transactions:<transaction_id>objectTransaction identification within the order. It contains an object with detailed information about the specified transaction. Order can contain several transactions.00016857481e16b07fc
transactions:<transaction_id>:idstringTransactions identification within the order.00016857481e16b07fc
transactions:<transaction_id>:operationstringTransaction type. Transaction types are described in respective directory.pay
transactions:<transaction_id>:statusstringTransaction status within the order. Transaction statuses are described in respective directory.success
transactions:<transaction_id>:descriptorstringThe descriptor for the transactionpayhere.com
transactions:<transaction_id>:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
transactions:<transaction_id>:currencystringTransaction currency.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 BIN411111
transactions:<transaction_id>:card:brandstringCard BrandVISA
transactions:<transaction_id>:card:numberstringMasked card number411111XXXXXX1111
transactions:<transaction_id>:card:card_holderstringCardholder nameTest User
transactions:<transaction_id>:card:bankstringBank emitentSTATE BANK
transactions:<transaction_id>:card:countrystringCountry of the bankUSA
transactions:<transaction_id>:card:card_exp_monthstringA month of the expiration date on a card. (2-digit format)3
transactions:<transaction_id>:card:card_exp_yearintegerA year of the expiration date on a card. (4-digit format)2025
transactions:<transaction_id>:card:card_typestringA type of the cardDEBIT
orderobjectObject with order information 
order:order_idstringOrder ID specified in the merchant system123443334
order:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
order:currencystringOrder currency (3 letter code under ISO 4217).USD
order:fraudulentbooleanThe customer was detected on the merchant end to be suspicious one.TRUE
order:marketing_amountintegerThe marketing amount of the order converted in USD (or other currency as agreed) at a publicly available rate at the time of the transaction. It can only be used for marketing forecasts.2575
order:marketing_currencystringThe currency of order amount for marketing analytics.USD
order:statusstringStatus of payment processed. Types of order statuses are described in the respective directory.created
order:refunded_amountintegerAmount of refund0
order:descriptorstringThe descriptor for the transactionpayhere.com
transactionobjectObject with information on the transaction. 
transaction:idstringID of the transaction inside the order. Order can contain several transactions02b988721b9e9ba89c7f75fbb8d21ceb5ea29550b75cd
transaction:operationstringTransaction type. Available values - pay.pay
transaction:statusstringTransaction status within the order.created
transaction:amountintegerTransaction amount.2575
transaction:currencystringTransaction currency.USD
transaction:created_atstringTransaction created DateTime2019-05-17 9:06:21
transaction:updated_atstringTransaction updated DateTime2019-05-17 9:06:21
transaction:card:objectObject with information about the card. Present in payment transactions. 
transaction:card:binstringCard BIN.411111
transaction:card:brandstringCard Brand.VISA
transaction:card:countrystringCountry of the bank.USA
transaction:card:numberstringMasked card number.411111XXXXXX1111
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
payment_adviserobjectThe object that contains advice from payment adviser 
payment_adviser:advisestringRecommendation for next paymentpay / resign / recurring

Charge Response Sample | Success

{
  "transactions": {
    "00016857481e16b07fc": {
      "id": "00016857481e16b07fc",
      "operation": "pay",
      "status": "created",
      "amount": 2575,
      "currency": "USD",
      "created_at": "2019-05-17 09:06:21",
      "updated_at": "2019-05-17 09:06:32",
      "card": {
        "bank": "STATE BANK",
        "bin": "411111",
        "brand": "VISA",
        "country": "USA",
        "number": "411111XXXXXX1111",
        "card_holder": "cardholder name",
        "card_exp_month": "03",
        "card_exp_year": 2025,
        "card_type": "DEBIT"
      }
    }
  },
  "order": {
    "order_id": "777",
    "amount": 2575,
    "currency": "USD",
    "fraudulent": true,
    "marketing_amount": 2575,
    "marketing_currency": "USD",
    "status": "created",
    "refunded_amount": 0
  },
  "transaction": {
    "id": "00016857481e16b07fc",
    "operation": "pay",
    "status": "created",
    "amount": 2575,
    "currency": "USD",
    "created_at": "2019-05-17 09:06:21",
    "updated_at": "2019-05-17 09:06:32",
    "card": {
      "bin": "411111",
      "brand": "VISA",
      "country": "USA",
      "number": "411111XXXXXX1111",
      "card_holder": "cardholder name", 
      "card_exp_month": "03",
      "card_exp_year": 2025,
      "card_type": "DEBIT"
    }
  },
  "payment_adviser": {
    "advise": "pay"
  }
}

 

    Charge Response Body Parameters | Decline

ParameterTypeDescriptionExample
transactionsobjectObject with information of transactions. 
transactions:<transaction_id>stringTransaction identification within the order. It contains an object with detailed information about the specified transaction. Order can contain several transactions.02b988721b9e9ba89c7f75fbb8d21ceb5ea29550b75cd
transactions:<transaction_id>:idstringTransactions identification within the order.02b988721b9e9ba89c7f75fbb8d21ceb5ea29550b75cd
transactions:<transaction_id>:operationstringTransaction type. pay
transactions:<transaction_id>:statusstringTransaction status within the order. fail
transactions:<transaction_id>:amountintOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.1000
transactions:<transaction_id>:currencystringTransaction currency. 3-letter currency code according to ISO-4217USD
transactions:<transaction_id>:feeobjectObject that contains information about fees. 
transactions:<transaction_id>:fee:amountintAmount of fees in undivided units(cents) without fractional component.25
transactions:<transaction_id>:fee:currencystringFee's currency. 3-letter currency code according to ISO-4217USD
transactions:<transaction_id>:errorobjectObject with the information regarding the error. 
transactions:<transaction_id>:error:codestringError code. Error codes list.4.09
transactions:<transaction_id>:error:messagesstringName of the attribute, in which the error was found."Solid antifraud engine"
transactions:<transaction_id>:error:messagesarrayAn array of error messages related to this attribute 
transactions:<transaction_id>:error:messages:<attribute_name>arrayAn array of error messages related to this attribute"Solid antifraud engine"
transactions:<transaction_id>:created_at:<date_time>stringDate and time of the order's creation2020-04-24 7:29:20
transactions:<transaction_id>:updated_at:<date_time>stringDate and time of the last order update2020-04-24 7:29:20
transactions:<transaction_id>:marketing_currencystringCurrency of the order for marketing analyticUSD
transactions:<transaction_id>:marketing_amountintThe marketing amount of the order converted in USD (or other currency as agreed) at a publicly available rate at the time of the transaction. It can only be used for marketing forecasts.1000
transactions:<transaction_id>:billing_detailsobjectObject that contains payment data 
transactions:<transaction_id>:billing_details:adressstringAdress that was sent in the request21 Bedford Ave
transactions:<transaction_id>:billing_details:zipstringZIP-code that was sent in the request91191
transactions:<transaction_id>:billing_details:countrystringISO-code of the country that was sent in the requestUSA
transactions:<transaction_id>:billing_details:citystringCity name that was sent in the requestBoston
transactions:<transaction_id>:billing_details:statestringCode of the State that was sent in the requestNY
transactions:<transaction_id>:cardobjectAn object that contains information about the bank card 
transactions:<transaction_id>:bankstringBank, that issued the credit cardCITIZENS STATE BANK
transactions:<transaction_id>:binstringBIN of the credit card453245
transactions:<transaction_id>:brandstringBrand of the credit cardVISA
transactions:<transaction_id>:countrystringCountry of the credit cardUSA
transactions:<transaction_id>:numberstringCredit card number453245XXXXXX2692
transactions:<transaction_id>:card_exp_monthstringThe month of card expiration (2-digit format)3
transactions:<transaction_id>:card_exp_yearintYear of the credit card expiration2021
transactions:<transaction_id>:card_typestringType of the credit cardDEBIT
transactions:<transaction_id>:card_holderstringName of the credit card ownerKurt Snow
transactions:errorobjectObject with the information about the error 
transactions:error:codearrayError code. Error codes list.4.09
transactions:error:code:<message>arrayAn array of error messages related to this attributeSolid antifraud engine
transactions:error:messagesobjectObject with the messages regarding errors 
transactions:error:messages:<message>stringName of the attribute in which the error was foundSolid antifraud engine
transactions:error:recommended_message_for_user:<message>arrayAn array of error messages related to this attribute"Solid antifraud engine"
transactions:orderobjectObject with the information about an order 
transactions:order:operationstringTransaction type. Transaction types are described in respective directory.pay
transactions:order:order_idstringOrder ID specified in the merchant system.02b988721b9e9ba89c7f75fbb8d21ceb5ea29550b75cd
transactions:order:statusstringOrder statusfail
transactions:order:amountintOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.1000
transactions:order:refund_amountintRefund amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.0
transactions:order:currencystringThe currency of the order. 3-letter currency code according to ISO-4217USD
transactions:order:marketing_amountintThe marketing amount of the order converted in USD (or other currency as agreed) at a publicly available rate at the time of the transaction. It can only be used for marketing forecasts.1000
transactions:order:marketing_currencystringThe currency of order amount for marketing analyticsUSD
transactions:order:fraudulentboolThe user was marked as fraudulent on the merchant's sideTRUE
transactionobjectObject with data about the transaction 
transaction:idstringID of the transaction inside the order. Order can contain several transactions02b988721b9e9ba89c7f75fbb8d21ceb5ea29550b75cd
transaction:operationstringTransaction type. Possible values: paypay
transaction:statusstringTransaction status inside of the order.fail
transaction:amountintOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.1000
transaction:currencystringThe currency of the order. 3-letter currency code according to ISO-4217USD
transaction:feeobjectAn object that contains the information about fees 
transaction:fee:amountintTotal fee amount25
transaction:fee:currencystringThe currency of fees for the orderUSD
transaction:errorobjectObject with the information about the error 
transaction:error:codearrayError code. Error codes list.4.09
transaction:error:code:<message>arrayAn array of error messages related to this attributeSolid antifraud engine
transaction:error:messagesobjectObject with the messages regarding errors 
transaction:error:messages:<message>stringName of the attribute in which the error was foundSolid antifraud engine
ransaction:error:recommended_message_for_user:<message>arrayAn array of error messages related to this attribute"Solid antifraud engine"
transaction:created_at:<date_time>stringDate and time of the order's creation2020-04-24 7:29:20
transaction:updated_at:<date_time>stringDate and time of the last order update2020-04-24 7:29:20
transaction:marketing_currencystringThe currency of order amount for marketing analytics.USD
transaction:marketing_amountintThe marketing amount of the order converted in USD (or other currency as agreed) at a publicly available rate at the time of the transaction. It can only be used for marketing forecasts.1000
transaction:billing_detailsobjectObject that contains payment data 
transaction:billing_details:addressstringAddress (mandatory parameter for USA location).21 Bedford Ave
transaction:billing_details:zipstringZIP-code that was sent in the request91191
transaction:billing_details:countrystringISO-code of the country that was sent in the requestUSA
transaction:billing_details:citystringCity name that was sent in the requestBoston
transaction:billing_details:statestringCode of the State that was sent in the requestNY
transaction:cardobjectObject with information about the card. Present in payment transactions 
transaction:card:bankstringBank, that issued the credit cardCITIZENS STATE BANK
transaction:card:binstringCard BIN453245
transaction:card:brandstringCard BrandVISA
transaction:card:countrystringCountry of the bankUSD
transaction:card:numberstringMasked card number453245XXXXXX2692
transaction:card:card_exp_monthstringThe month of card expiration (2-digit format)3
transaction:card:card_exp_yearintYear of card expiration (4-digit format)2021
transaction:card:card_typestringA type of cardDEBIT
transaction:card:card_holderstringCardholder nameKurt Snow
payment_adviserobjectThe object that contains advice from payment adviser 
payment_adviser:advise:arrayAn array with recommendations from the payment adviser 
payment_adviser:advise:<advise>stringRecommendations of the payment adviserpay

Charge Response Sample | Decline

{
  "transactions": {
    "02b988721b9e9ba89c7f75fbb8d21ceb5ea29550b75cd": {
      "id": "02b988721b9e9ba89c7f75fbb8d21ceb5ea29550b75cd",
      "operation": "pay",
      "status": "fail",
      "amount": 1000,
      "currency": "USD",
      "fee": {
        "amount": 25,
        "currency": "USD"
      },
      "error": {
        "code": "4.09",
        "messages": [
          "Solid antifraud engine"
        ],
        "recommended_message_for_user": "Solid antifraud engine"
      },
      "created_at": "2020-04-24 07:29:20",
      "updated_at": "2020-04-24 07:29:20",
      "marketing_currency": "USD",
      "marketing_amount": 1000,
      "billing_details": {
        "address": "21 Bedford Ave",
        "zip": "91191",
        "country": "USA",
        "city": "Boston",
        "state": "NY"
      },
      "card": {
        "bank": "CITIZENS STATE BANK",
        "bin": "453245",
        "brand": "VISA",
        "country": "USA",
        "number": "453245XXXXXX2692",
        "card_exp_month": "03",
        "card_exp_year": 2021,
        "card_type": "DEBIT",
        "card_holder": "Kurt Snow"
      }
    }
  },
  "error": {
    "code": "4.09",
    "messages": [
      "Solid antifraud engine"
    ],
    "recommended_message_for_user": "Solid antifraud engine"
  },
  "order": {
    "order_id": "1587713359140",
    "status": "declined",
    "amount": 1000,
    "refunded_amount": 0,
    "currency": "USD",
    "marketing_amount": 1000,
    "marketing_currency": "USD",
    "fraudulent": true
  },
  "transaction": {
    "id": "02b988721b9e9ba89c7f75fbb8d21ceb5ea29550b75cd",
    "operation": "pay",
    "status": "fail",
    "amount": 1000,
    "currency": "USD",
    "fee": {
      "amount": 25,
      "currency": "USD"
    },
    "error": {
      "code": "4.09",
      "messages": [
        "Solid antifraud engine"
      ],
      "recommended_message_for_user": "Solid antifraud engine"
    },
    "created_at": "2020-04-24 07:29:20",
    "updated_at": "2020-04-24 07:29:20",
    "marketing_currency": "USD",
    "marketing_amount": 1000,
    "billing_details": {
      "address": "21 Bedford Ave",
      "zip": "91191",
      "country": "USA",
      "city": "Boston",
      "state": "NY"
    },
    "card": {
      "bank": "CITIZENS STATE BANK",
      "bin": "453245",
      "brand": "VISA",
      "country": "USA",
      "number": "453245XXXXXX2692",
      "card_exp_month": "03",
      "card_exp_year": 2021,
      "card_type": "DEBIT",
      "card_holder": "Kurt Snow"
    }
  },
  "payment_adviser": {
    "advise": "pay"
  }
}

 

    Charge Response Body Parameters | Validation Error 

ParameterTypeDescriptionExample
errorobjectObject with information on errors 
error:codestringError codes list2.01
error: messagesobjectObject with error list 
error:messages:<attribute_name>stringAttribute name where error was foundcurrency
error:messages:<error_message>arrayArray of error messages relating to respective attributeThis value should not be blank.

Charge Response Sample | Validation Error

{
    "error": {
        "code": "2.01",
        "messages": {
            "currency": [
                "This value should not be blank."
            ],
            "customer_email": [
                "This value should not be blank."
            ],
            "ip_address": [
                "This value should not be blank."
            ],
            "order_description": [
                "This value should not be blank."
            ],
            "order_id": [
                "This value should not be blank."
            ],
            "platform": [
                "This value should not be blank."
            ]
        }
    }
}

 

    Charge Response Body Parameters | Fail 

ParameterTypeDescriptionExample
errorobjectObject with the information about the error 
error:codestringError code2.01
error:typestringType of en errorsoft
error:messagesobjectObject with a list of error messages 
error:messages:<attribute_name>stringThe name of the attribute in which the error was found 
error:messages:<error_message>arrayArray of error messages related to this attributeThis value should not be blank.
error:"recommended_message_for_user"objectAn object with a list of error messages displayed to the user 
error:"recommended_message_for_user":<error_message>stringError displayed to the user during the decline. (Decline error)"Solid antifraud engine"

Charge Response Sample | Fail

{
  "error": {
    "code": "4.09",
    "type": "soft",
    "messages": [
      "Solid antifraud engine"
    ],
    "recommended_message_for_user": "Solid antifraud engine"
  }
}

Recurring transaction

Operation of the recurring payment. In contrast to Charge, token previously received is to be sent in the request instead of cardholder data. Upon successful payment, two scenarios on this order are possible - refund or chargeback.
 

POST https://pay.solidgate.com/api/v1/recurring

Some recurring transactions can go through 3D verification.  You must be ready to show a bank page for a user. URL of bank page you can receive by notification or request of check order status.

 

    Recurring Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idYesstring(100)Order ID specified in the merchant system123443334
amountYesintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents1020
currencyYesstring(3)Order currency. 3 letter currency code under ISO-4217USD
recurring_tokenYesstring(255)Card token7ats8da7sd8-a66dfa7-a9s9das89t
order_descriptionYesstring(255)Order description in UTF-8 codePremium package
customer_emailYesstring(100)Customer emailjondou@gmail.com
ip_addressYesstring(50)Customer IP (only public ones)8.8.8.8
platformYesstring(6)Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - applicationWEB
geo_countryNostring(3)Customer country subject to ISO 3166-1 alpha-3GBR
order_dateNostring(50)Date of order creation in format YYYY-MM-DD-HH-MM-SS2015-12-21 11:21:30
order_itemsNostring(255)Order description in UTF-8 codeitem 1, item 2
customer_account_idNostring(100)Customer ID specified in the merchant system4dad42f808
customer_first_nameNostring(100)Customer first nameJohn
customer_last_nameNostring(100)Customer last nameSnow
customer_phoneNostring(50)Customer phone number380111111111
customer_date_of_birthNostring(50)Birthdate in YYYY-MM-DD format2000-11-21
geo_cityNostring(100)Customer cityNew Castle
languageNostring(2)Customer language settings. Available values: RU - Russian, EN - Englishen
fraudulentNobooleanThe customer is detected by the merchant system to be suspicious one. The payment will be effected via 3DSTRUE
callback_urlNostring(255)URL of merchant page, where response with payment result will be sent via a host-to-host connectionhttp://merchant.example/callback
chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback will be senthttp://merchant.example/chargeback
alert_chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback alerts will be senthttp://merchant.example/chargeback_alerts
status_urlNostring(255)URL of merchant page, which customers will be redirected upon 3DS verification on bank end with the status of operation in URL parameter - http://merchant.example/status/?order_id=123443334&status=approvedhttp://merchant.example/status
verifiedNobooleanThe user was verified on the shop sideTRUE
payment_typeYesstring(25)Type of recurring payment1-click || retry || recurring
retry_attemptNointegerNumber of retry payment1
traffic_sourceNostring(255)Source of trafficfacebook
transaction_sourceNostring(255)Source of transactions on the websitemain_menu
order_numberNointegerNumber of payments by user2
user_agentNostringUser-agent of customerMozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36
deviceNostringDevice of customeriPhone 8 iOS 12.0
operating_systemNostringInformation about the operating system of the customer deviceiOS
operating_system_versionNostringInformation about the version of the operating system of the customer device12
browserNostringInformation about the browser of the customer deviceSafari
browser_versionNostringInformation about the version of the browser of the customer device12
websiteNostring(255)The website from which transaction took placeGoogle.com
typeNostringThe parameter for transaction-authorization before a recurring paymentauth
settle_intervalNointegerTime (in hours) when auto-settle should do1
force3dsNobooleanRouting payments flag for 3DS flow (enabled by Solid account manager)FALSE
header_acceptYes - 3D 2.0string(255)Header Accepttext/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng
header_accept_languageYes - 3D 2.0string(255)Header Accept Languageru-RU,ru;q=0.9,en-US;q=0.8
browser_color_depthYes - 3D 2.0integerThe colour depth of the browser window32
browser_screen_heightYes - 3D 2.0integerHeight of browser window1920
browser_screen_widthYes - 3D 2.0integerWidth of the browser window1280
browser_java_enabledYes - 3D 2.0booleanIs java enabled on the User's browserFALSE
browser_javascript_enabledYes - 3D 2.0booleanIs javascript enabled on the User browserFALSE
time_zone_offsetYes - 3D 2.0integerThe time difference, in minutes, between UTC time and the local time of the cardholder's browser60

Recurring Request Sample | Success

{
  "amount": 2575,
  "recurring_token": "7ats8da7sd8-a66dfa7-a9s9das89t",
  "currency": "USD",
  "customer_account_id": "user_id",
  "customer_date_of_birth": "2000-11-21",
  "customer_email": "example.user@example-email.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "380000000000",
  "fraudulent": true,
  "geo_city": "New Castle",
  "geo_country": "GBR",
  "ip_address": "8.8.8.8",
  "language": "en",
  "order_date": "2015-12-21 11:21:30",
  "order_description": "Premium package",
  "order_id": "777",
  "order_items": "item 1, item 2",
  "platform": "WEB",
  "callback_url": "http://merchant.example/callback",
  "status_url": "http://merchant.example/status",
  "chargeback_notification_url": "http://merchant.example/chargeback",
  "verified": true,
  "payment_type": "1-click",
  "retry_attempt": "1",
  "traffic_source": "facebook",
  "transaction_source": "main_menu",
  "device": "iPhone 8 iOS 12.0",
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
  "operating_system": "iOS",
  "operating_system_version": "12.0",
  "browser": "Safari",
  "browser_version": "12.0",
  "type": "auth",
  "settle_interval": 1,
  "header_accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng",
  "header_accept_language": "ru-RU,ru;q=0.9,en-US;q=0.8",
  "browser_color_depth": 32,
  "browser_screen_height": 1920,
  "browser_screen_width": 1280,
  "browser_java_enabled": true,
  "browser_javascript_enabled": true,
  "time_zone_offset": 60
}

 

    Recurring Response Body Parameters | Success

ParameterTypeDescriptionExample
orderobjectAn object with information of the transaction. 
order:order_idstringOrder ID specified in the merchant system777
order:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
order:currencystringOrder currency (3 letter code under ISO 4217)USD
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 forecasting.2575
order:marketing_currencystringThe currency of the order amount for marketing analytics.USD
order:total_fee_amountintegerTotal fee by order transaction0
order:refunded_amountintegerThe amount which was refunded0
order:descriptorstringThe descriptor for the transactionpayhere.com
order:statusstringStatus of payment processed. Types of order statuses are described in the respective directory.processing
transactionobjectAn object with information of the transaction. 
transaction:idstringTransaction identification within the order. The order can have several transactions.1495123020887591dc450088f1
transaction:operationstringTransaction type. Available values - recurring.recurring
transaction:statusstringTransaction status within the order.created
transaction:amountintegerTransaction amount.2575
transaction:currencystringTransaction currency.USD
transaction:created_atstringTransaction created DateTime2019-05-17 9:06:21
transaction:updated_atstringTransaction updated DateTime2019-05-17 9:06:21
transaction:cardobjectAn object with information about the card. Present in payment transactions. 
transaction:card:bankstringBank-emitent.NATIONWIDE BUILDING SOCIETY
transaction:card:binintegerCard BIN.444455
transaction:card:brandstringCard Brand.VISA
transaction:card:countrystringCountry of the bank.USA
transaction:card:numberstringMasked card number.444455XXXXXX6666
transaction:card:cardholder_namestringCardholder nameTest User
transaction:card:card_exp_monthstringA month of the expiration date on the card. (2-digit format)3
transaction:card:card_exp_yearintegerA year of the expiration date on the 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 payment.b5ddb0a1c...1fc4da81ecdad52c0
transactionsobjectAn object with information of transactions. 
transactions:<transaction_id>objectTransaction identification within the order. It contains an object with detailed information about the specified transaction. The order can have several transactions.1495123020887591dc450088f1
transactions:<transaction_id>:idstringTransactions identification within the order.1495123020887591dc450088f1
transactions:<transaction_id>:operationstringTransaction type. Transaction types are described in the respective directory.recurring
transactions:<transaction_id>:statusstringTransaction status within the order. Transaction statuses are described in the respective directory.created
transactions:<transaction_id>:descriptorstringThe descriptor for the transactionpayhere.com
transactions:<transaction_id>:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
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>:cardobjectAn object with information about the card. Present in payment transactions. 
transactions:<transaction_id>:card:binintegerCard BIN444455
transactions:<transaction_id>:card:brandstringCard BrandVISA
transactions:<transaction_id>:card:numberstringMasked card number444455XXXXXX6666
transactions:<transaction_id>:card:cardholder_namestringCardholder NameTest User
transactions:<transaction_id>:card:bankstringBank emitentNATIONWIDE BUILDING SOCIETY
transactions:<transaction_id>:card:countrystringCountry of bankGBR
transactions:<transaction_id>:card:card_exp_monthstringA month of expiration date on card. (2-digit format)3
transactions:<transaction_id>:card:card_exp_yearintegerA year of expiration date on 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 payment.8b5ddb0a1c...1fc4da81ecdad52c0
payment_adviserobject  
payment_adviser:advisestringRecommendation for next paymentpay / resign / recurring

Recurring Response Sample | Success

{
  "transactions": {
    "1495123020887591dc450088f1": {
      "id": "1495123020887591dc450088f1",
      "operation": "recurring",
      "status": "created",
      "amount": 2575,
      "currency": "USD",
      "created_at": "2019-05-17 09:06:21",
      "updated_at": "2019-05-17 09:06:32",
      "card": {
        "bank": "STATE BANK",
        "bin": 444455,
        "brand": "VISA",
        "country": "USA",
        "number": "444455XXXXXX6666",
        "card_holder": "cardholder name",
        "card_exp_month": "03",
        "card_exp_year": 2025,
        "card_type": "DEBIT"
      },
      "card_token": {
        "token": "8b5ddb087c38496bc23fb5a1ce82c9640e1b8128aa9fe5bf54574d10c8a0493c71a1fc4da81e3782397fdc7c142ccdad52c0"
      }
    }
  },
  "order": {
    "order_id": "777",
    "amount": 2575,
    "currency": "USD",
    "fraudulent": true,
    "marketing_amount": 2575,
    "marketing_currency": "USD",
    "status": "processing",
    "total_fee_amount": 0,
    "refunded_amount": 0
  },
  "transaction": {
    "id": "1495123020887591dc450088f1",
    "operation": "recurring",
    "status": "created",
    "amount": 100,
    "currency": "USD",
    "created_at": "2019-05-17 09:06:21",
    "updated_at": "2019-05-17 09:06:32",
    "card": {
      "bin": 344940,
      "bank": "NATIONWIDE BUILDING SOCIETY",
      "brand": "AMEX",
      "country": "USA",
      "number": "344940XXXXXX1496",
      "card_holder": "cardholder name",
      "card_exp_month": "03",
      "card_exp_year": 2025,
      "card_type": "DEBIT"
    },
    "card_token": {
      "token": "8c6ecf6a69fc58f45ead35ed7c2a8f6edde8d7eb20e82263cba3702fcfb8faee8c1684ab910f8bb0ecb69d98386a998bf2fd"
    }
  },
  "payment_adviser": {
    "advise": "pay"
  }
}

In case you perform the recurring operation with a parameter type = `auth`, please be informed that basic operation of withdrawal amounts from cardholder’s account can be in place without `hold` funds. Not all banks support `hold`. Type of transaction should be `recurring` in this case. 

Recurring Auth Request Sample | Success

{
  "amount": 100,
  "currency": "USD",
  "customer_account_id": "1234567",
  "customer_email": "kurt.Cruickshank.toster@gmail.com",
  "customer_phone": "+380954543322",
  "geo_country": "USA",
  "ip_address": "8.8.8.8",
  "language": "en",
  "order_description": "test",
  "order_id": "1561453107326recurringCascade",
  "order_items": "order_items",
  "platform": "WEB",
  "fraudulent": true,
  "traffic_source": "onOff",
  "recurring_token": "57f3be9f46dee46db195bad976f13cf5a9d682953b9c854ec20b7",
  "type": "auth"
}

Recurring Auth Response Sample | Success

{
  "transactions": {
    "2e5432e30d1f0eb8fbde8f34604310f05d11e2337e9b0": {
      "id": "2e5432e30d1f0eb8fbde8f34604310f05d11e2337e9b0",
      "operation": "recurring-auth",
      "status": "created",
      "amount": 100,
      "currency": "USD",
      "created_at": "2019-06-25 08:58:27",
      "updated_at": "2019-06-25 08:58:27",
      "card": {
        "bank": "SETEFI S P A",
        "bin": 535572,
        "brand": "MASTERCARD",
        "country": "ITA",
        "number": "535572XXXXXX1833",
        "card_exp_month": "02",
        "card_exp_year": 2022,
        "card_type": "DEBIT",
        "card_holder": "abigail wood"
      },
      "card_token": {
        "token": "57f3be9f46dee46db195bad976f13cf5a9d682953b9c854ec20b7"
      }
    }
  },
  "order": {
    "order_id": "1561453107326recurringCascade",
    "status": "processing",
    "amount": 100,
    "refunded_amount": 0,
    "currency": "USD",
    "marketing_amount": 100,
    "marketing_currency": "USD",
    "fraudulent": true,
    "total_fee_amount": 0
  },
  "transaction": {
    "id": "2e5432e30d1f0eb8fbde8f34604310f05d11e2337e9b0",
    "operation": "recurring-auth",
    "status": "created",
    "amount": 100,
    "currency": "USD",
    "created_at": "2019-06-25 08:58:27",
    "updated_at": "2019-06-25 08:58:27",
    "card": {
      "bank": "SETEFI S P A",
      "bin": 535572,
      "brand": "MASTERCARD",
      "country": "ITA",
      "number": "535572XXXXXX1833",
      "card_exp_month": "02",
      "card_exp_year": 2022,
      "card_type": "DEBIT",
      "card_holder": "abigail wood"
    },
    "card_token": {
      "token": "57f3be9f46dee46db195bad976f13cf5a9d682953b9c854ec20b7"
    }
  }
}

Recurring Auth Response Sample | Final Status

{
  "transactions": {
    "2e5432e30d1f0eb8fbde8f34604310f05d11e2337e9b0": {
      "id": "2e5432e30d1f0eb8fbde8f34604310f05d11e2337e9b0",
      "operation": "recurring",
      "status": "success",
      "descriptor": "FAKE_PSP",
      "amount": 100,
      "currency": "USD",
      "fee": {
        "amount": 31,
        "currency": "USD"
      },
      "created_at": "2019-06-25 08:58:27",
      "updated_at": "2019-06-25 08:58:28",
      "card": {
        "bank": "SETEFI S P A",
        "bin": "535572",
        "brand": "MASTERCARD",
        "country": "ITA",
        "number": "535572XXXXXX1833",
        "card_exp_month": "02",
        "card_exp_year": 2022,
        "card_type": "DEBIT",
        "card_holder": "abigail wood"
      },
      "card_token": {
        "token": "57f3be9f46dee46db195bad976f13cf5a9d682953b9c854ec20b7"
      }
    }
  },
  "order": {
    "order_id": "1561453107326recurringCascade",
    "status": "approved",
    "amount": 100,
    "refunded_amount": 0,
    "currency": "USD",
    "marketing_amount": 100,
    "marketing_currency": "USD",
    "processing_amount": 100,
    "processing_currency": "USD",
    "descriptor": "FAKE_PSP",
    "fraudulent": true,
    "total_fee_amount": 31,
    "fee_currency": "USD"
  },
  "payment_adviser": {
    "advise": "recurring"
  }
}

 

    Recurring Response Body Parameters | Validation Error

ParameterTypeDescriptionExample
errorobjectAn object with information on errors 
error:codestringError codes list2.01
error: messagesobjectAn object with an error list 
error:messages:<attribute_name>stringAttribute name where an error was foundcurrency
error:messages:<error_message>arrayThe array of error messages relating to the respective attributeThis value should not be blank.

Recurring Response Sample | Validation Error

{
    "error": {
        "code": "2.01",
        "messages": {
            "currency": [
                "This value should not be blank."
            ],
            "customer_email": [
                "This value should not be blank."
            ],
            "ip_address": [
                "This value should not be blank."
            ],
            "order_description": [
                "This value should not be blank."
            ],
            "order_id": [
                "This value should not be blank."
            ],
            "platform": [
                "This value should not be blank."
            ]
        }
    }
}

 

    Recurring Response Body Parameters | Fail

ParameterTypeDescriptionExample
errorobjectObject with the information about the error 
error:"recommended_message_for_user"objectAn object with a list of error messages displayed to the user.  
error:"recommended_message_for_user":<error_message>stringError displayed to the user during the decline. (Decline error)"Solid antifraud engine"
error:codestringError code.2.01
error:messagesobjectObject with a list of error messages 
error:messages:<attribute_name>stringThe name of the attribute in which the error was found 
error:messages:<error_message>arrayArray of error messages related to this attributeThis value should not be blank.
error:typestringType of en error. soft

Recurring Response Sample | Fail

{
  "error": {
    "code": "4.09",
    "type": "soft",
    "messages": [
      "Solid antifraud engine"
    ],
    "recommended_message_for_user": "Solid antifraud engine"
  }
}

Solid can enable 3DS payments for recurring payment method. In order to set up this option, you need to contact your account manager at Solid.

You should be ready to show 3DS bank page for a user after recurring request, `verify_url` can be received from the following  requests: Status or Notification.

Request for recurring 3DS is the same as for the method recurring.

Resign 1-click

Resign 1-click allows you to perform transactions via token (like 1-click payments) but also requesting a CVV from the user.

POST https://pay.solidgate.com/api/v1/resign

Resign 3DS going through a few steps :

1) Resign request
2) Redirect to URL 3DS verification

Please, note, `verify_url` can be received from the following  requests: Status or Notification.

 

    Resign Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idYesstring(100)Order ID specified in the merchant system123443334
amountYesintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.1020
currencyYesstring(3)Order currency. 3 letter currency code under ISO-4217USD
recurring_tokenYesstring(255)Card token7ats8da7sd8-a66dfa7-a9s9das89t
card_cvvYesstring(4)CVV2/CVC2 of the card, 3 or 4 digits code123
order_descriptionYesstring(255)Order description in UTF-8 codePremium package
customer_emailYesstring(100)Customer emailjondou@gmail.com
ip_addressYesstring(50)Customer IP (only public ones)8.8.8.8
platformYesstring(6)Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application.WEB
status_urlYesstring(255)URL of merchant page, which customers will be redirected upon 3DS verification on bank end with the status of operation in URL parameter - http://merchant.example/status/?order_id=123443334&status=approved .http://merchant.example/status
geo_countryNostring(3)Customer country subject to ISO 3166-1 alpha-3GBR
order_dateNostring(50)Date of order creation in format YYYY-MM-DD-HH-MM-SS2015-12-21 11:21:30
order_itemsNostring(255)Order description in UTF-8 codeitem 1, item 2
customer_account_idNostring(100)Сustomer ID specified in the merchant system4dad42f808
customer_first_nameNostring(100)Customer's first nameJohn
customer_last_nameNostring(100)Customer last nameSnow
customer_phoneNostring(50)Customer phone number380111111111
customer_date_of_birthNostring(50)Birthdate in YYYY-MM-DD format2000-11-21
geo_cityNostring(100)Customer CityNew Castle
languageNostring(2)Customer language settings. Available values: RU - Russian, EN - Englishen
fraudulentNobooleanA customer is detected by the merchant system to be suspicious one. The payment will be effected via 3DS.TRUE
callback_urlNostring(255)URL of merchant page, where response with payment result will be sent via host-to-host connectionhttp://merchant.example/callback
chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback will be sent.http://merchant.example/chargeback
alert_chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback alerts will be senthttp://merchant.example/chargeback_alerts
verifiedNobooleanA user was verified on the shop side.TRUE
retry_attemptNointegerNumber of retry payment1
traffic_sourceNostring(255)Source of traffic.facebook
transaction_sourceNostring(255)Source of transactions on the website.main_menu
user_agentNostringUser-agent of customerMozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36
deviceNostringDevice of customeriPhone 8 iOS 12.0
operating_systemNostringInformation about the operating system of the customer deviceiOS
operating_system_versionNostringInformation about the version of the operating system of the customer device12
browserNostringInformation about the browser of the customer deviceSafari
browser_versionNostringInformation about the version of the browser of the customer device12
websiteNostringThe website from which transaction took place.google.com
typeNostringThe parameter for transaction-authorizationauth
order_numberNointegerNumber of payments by user1
force3dsNobooleanRouting payments flag for 3DS flow (enabled by Solid account manager)FALSE
header_acceptYes - 3D 2.0string(255)Header Accept.text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng
header_accept_languageYes - 3D 2.0string(255)Header Accept Language.ru-RU,ru;q=0.9,en-US;q=0.8
browser_color_depthYes - 3D 2.0integerThe colour depth of the browser window.32
browser_screen_heightYes - 3D 2.0integerHeight of browser window.1920
browser_screen_widthYes - 3D 2.0integerWidth of the browser window.1280
browser_java_enabledYes - 3D 2.0booleanIs java enabled on User's browser.FALSE
browser_javascript_enabledYes - 3D 2.0booleanIs javascript enabled on User's browser.FALSE
time_zone_offsetYes - 3D 2.0integerThe time difference, in minutes, between UTC time and the local time of the cardholder's browser.-1

Please, note, that `status_url` is a mandatory field that needs to redirect a user after going through 3DS verification.

Resign Request Sample | Success

{
  "amount": 2575,
  "callback_url": "http://merchant.example/callback",
  "recurring_token": "7ats8da7sd8-a66dfa7-a9s9das89t",
  "card_cvv": "123",
  "currency": "USD",
  "customer_account_id": "user_id",
  "customer_date_of_birth": "2000-11-21",
  "customer_email": "example.user@example-email.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "380000000000",
  "fraudulent": true,
  "geo_city": "New Castle",
  "geo_country": "GBR",
  "ip_address": "8.8.8.8",
  "language": "en",
  "order_date": "2015-12-21 11:21:30",
  "order_description": "Premium package",
  "order_id": "777",
  "order_items": "item 1, item 2",
  "platform": "WEB",
  "status_url": "http://merchant.example/status",
  "chargeback_notification_url": "http://merchant.example/chargeback",
  "order_number": "1",
  "header_accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng",
  "header_accept_language": "ru-RU,ru;q=0.9,en-US;q=0.8",
  "browser_color_depth": 32,
  "browser_screen_height": 1920,
  "browser_screen_width": 1280,
  "browser_java_enabled": true,
  "browser_javascript_enabled": true,
  "time_zone_offset": 60
}

 

    Resign Response Body Parameters | Success

ParameterTypeDescriptionExample
orderobjectAn object with order information 
order:order_idstringOrder ID specified in the merchant system777
order: amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
order:currencystringOrder currency (3 letter code under ISO 4217)USD
order:fraudulentbooleanA 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 forecasting.2575
order:marketing_currencystringThe currency of the order amount for marketing analytics.USD
order:statusstringStatus of payment processed. Types of order statuses are described in the respective directory.created
order:total_fee_amountintegerTotal fee by order transaction0
order:refunded_amountintegerAn amount which was refunded0
order:descriptorstringThe descriptor for the transactionpayhere.com
transactionsobjectAn object with information of transactions. 
transactions:<transaction_id>objectTransaction identification within order. It contains an object with detailed information of specified transaction. Order can have several transactions.00016857481e16b07fc
transactions:<transaction_id>:idstringTransactions identification within order.00016857481e16b07fc
transactions:<transaction_id>:operationstringTransaction type. Transaction types are described in respective directory.resign
transactions:<transaction_id>:statusstringTransaction status within order.
Transaction statuses are described in respective directory.
created
transactions:<transaction_id>:descriptorstringThe descriptor for the transactionpayhere.com
transactions:<transaction_id>:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
transactions:<transaction_id>:currencystringTransaction currency.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>:cardobjectAn object 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:card_holderstringCardholder nameTest User
transactions:<transaction_id>:card:bankstringBank emitentSTATE BANK
transactions:<transaction_id>:card:countrystringCountry of bankUSA
transactions:<transaction_id>:card:card_exp_monthstringA month of card expiration (2-digit format).3
transactions:<transaction_id>:card:card_exp_yearintegerA year of card expiration (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 payment.22f1cdc766a318...e8fa3a68f
transactionobjectAn object with information of the transaction. 
transaction:idstringTransaction identification within the order. The order can have several transactions.00016857481e16b07fc
transaction:operationstringTransaction type. Available values - pay.pay
transaction:statusstringTransaction status within the order.created
transaction:amountintegerTransaction amount.2575
transaction:currencystringTransaction currency.USD
transaction:created_atstringTransaction created DateTime2019-05-17 9:06:21
transaction:updated_atstringTransaction updated DateTime2019-05-17 9:06:21
transaction:card:objectAn object with information about the card. Present in payment transactions. 
transaction:card:bankstringA bank that issued the card.STATE BANK
transaction:card:binstringCard BIN.444455
transaction:card:brandstringCard Brand.VISA
transaction:card:countrystringCountry of the bank.USA
transaction:card:numberstringMasked card number.444455XXXXXX6666
transaction:card:card_holderstringCardholder NameTest User
transactions:card:card_exp_monthstringThe month of card expiration (2-digit format).3
transactions:card:card_exp_yearintegerYear of card expiration (4-digit format).2025
transactions: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 payment.22f1cdcb8a318...e8fae0a68f
payment_adviserobject  
payment_adviser:advisestringRecommendation for next paymentpay / resign / recurring

Resign Response Sample | Success

{
  "transactions": {
    "00016857481e16b07fc": {
      "id": "00016857481e16b07fc",
      "operation": "resign",
      "status": "created",
      "amount": 2575,
      "currency": "USD",
      "created_at": "2019-05-17 09:06:21",
      "updated_at": "2019-05-17 09:06:32",
      "card": {
        "bank": "STATE BANK",
        "bin": "444455",
        "brand": "VISA",
        "country": "USA",
        "number": "444455XXXXXX6666",
        "card_holder": "cardholder name",
        "card_exp_month": "03",
        "card_exp_year": 2025,
        "card_type": "DEBIT"
      },
      "card_token": {
        "token": "22f1cdcb85fbd81ac6766a318d03432f862a310a104c4a39fcc9e881a8d07cdc1afa0d3801628c5cc938338e8fae0963a68f"
      }
    }
  },
  "order": {
    "order_id": "777",
    "amount": 2575,
    "currency": "USD",
    "fraudulent": true,
    "marketing_amount": 2575,
    "marketing_currency": "USD",
    "refunded_amount": 0,
    "total_fee_amount": 0,
    "status": "created"
  },
  "transaction": {
    "id": "00016857481e16b07fc",
    "operation": "resign",
    "status": "created",
    "amount": 2575,
    "currency": "USD",
    "created_at": "2019-05-17 09:06:21",
    "updated_at": "2019-05-17 09:06:32",
    "card": {
      "bank": "STATE BANK",
      "bin": "444455",
      "brand": "VISA",
      "country": "USA",
      "number": "444455XXXXXX6666",
      "card_holder": "cardholder name",
      "card_exp_month": "03",
      "card_exp_year": 2025,
      "card_type": "DEBIT"
    },
    "card_token": {
      "token": "22f1cdcb85fbd81ac6766a318d03432f862a310a104c4a39fcc9e881a8d07cdc1afa0d3801628c5cc938338e8fae0963a68f"
    }
  },
  "payment_adviser": {
    "advise": "pay"
  }
}

 

    Resign Response Body Parameters | Validation Error

ParameterTypeDescriptionExample
errorobjectAn object with information on errors 
error:codestringError codes list2.01
error: messagesobjectAn object with an error list 
error:messages:<attribute_name>stringAttribute name where an error was foundcurrency
error:messages:<error_message>arrayThe array of error messages relating to the respective attributeThis value should not be blank.

Resign Response Sample | Validation Error

{
    "error": {
        "code": "2.01",
        "messages": {
            "currency": [
                "This value should not be blank."
            ],
            "customer_email": [
                "This value should not be blank."
            ],
            "ip_address": [
                "This value should not be blank."
            ],
            "order_description": [
                "This value should not be blank."
            ],
            "order_id": [
                "This value should not be blank."
            ],
            "platform": [
                "This value should not be blank."
            ]
        }
    }
}

 

    Resign Status Response Body Parameters | Success

ParameterTypeDescriptionExample
orderobjectAn object with information of the transaction 
order:order_idstringOrder ID specified in the merchant system777
order:statusstringStatus of processed payment. Types of order statuses are described in respective directoryapproved
order:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents2575
order:refunded_amountintegerThe amount which was refunded0
order:currencystringOrder currency (3 letter code under ISO 4217)USD
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:processing_currencystringThe currency of the order amount for marketing analyticsUSD
order:processing_amountintegerThe amount in processing currency2575
order:descriptorstringDescriptorDESCRIPTOR
order:fraudulentbooleanThe customer is detected by the merchant system to be suspicious oneTRUE
order:total_fee_amountintegerTotal fee by order transaction6
order:fee_currencystringFee currencyUSD
transactionsobjectAn object with information of transactions 
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>:idstringTransactions identification within order1495123020887591dc450088f1
transactions:<transaction_id>:operationstringTransaction type. Transaction types are described in respective directoryresign
transactions:<transaction_id>:statusstringTransaction status within order. Transaction statuses are described in respective directory.success
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 the 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
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 card. Present in payment transactions 
transactions:<transaction_id>:card:bankstringBank emitentSTATE BANK
transactions:<transaction_id>:card:binstringCard BIN444455
transactions:<transaction_id>:card:brandstringCard BrandVISA
transactions:<transaction_id>:card:numberstringMasked card number444455XXXXXX6666
transactions:<transaction_id>:card:card_holderstringCardholder nameTest User
transactions:<transaction_id>:card:card_exp_monthstringA month of card expiration (2-digit format)3
transactions:<transaction_id>:card:card_exp_yearintegerA year of card expiration (4-digit format)2025
transactions:<transaction_id>:card:card_typestringA type of the cardDEBIT
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
transactions:<transaction_id>:card_tokenobject  
transactions:<transaction_id>:card_token:tokenstringThe old card token which was used by previous payments7926cd8cccf96...400415a217d74
verify_urlstringUrl for 3DS verificationhttps://pay.signedpay.com/api/v1/verify-3ds/24230956/f3c4d..36637

Resign Status Response Sample | Success

{
    "transactions": {
    "15027983907575992e23bec0c8": {
      "id": "15027983907575992e23bec0c8",
      "operation": "resign",
      "status": "success",
      "descriptor": "descriptor",
      "amount": 2575,
      "currency": "USD",
      "created_at": "2019-05-17 09:06:21",
      "updated_at": "2019-05-17 09:06:32",
      "fee": {
        "amount": 6,
        "currency": "USD"
      },
      "card": {
        "bank": "STATE BANK",
        "bin": "453245",
        "brand": "VISA",
        "country": "USA",
        "number": "453245XXXXXX2692",
        "card_holder": "cardholder name",
        "card_exp_month": "03",
        "card_exp_year": 2025,
        "card_type": "DEBIT",
        "card_token": {
          "token": "36657ccf9d36a00b13e8f4af47e8e2c041b16458bc83cb7aaa36fd236d2d474d211636b20c51a7a713b4881ae7cc516be6"
        }
      },
      "card_token": {
        "token": "126cc63b62dbb98c314562da1fabb0056747dcfffAeec75bf50d5d7a091b556888a95fdd39b38027daee0db7bcbf7c1714cd"
      }
    }
  },
  "verify_url": "https://pay.signedpay.com/api/v1/verify-3ds/27285357/8fc73fe8fbb4163167f44f84e0ea022787a4e0a858a2523bbfe2b473984b0cfea726170de927fd9399c9b2b19298085d",
  "order": {
    "order_id": "1502798390757",
    "status": "approved",
    "refunded_amount": 0,
    "amount": 2575,
    "currency": "USD",
    "descriptor": "descriptor",
    "fraudulent": false,
    "marketing_amount": 2575,
    "marketing_currency": "USD",
    "processing_amount": 2575,
    "processing_currency": "USD",
    "total_fee_amount": 6,
    "fee_currency": "USD"
  }
}

Check Order Status

Check order status is a request for getting current order status.

POST https://pay.solidgate.com/api/v1/status

 

        Check Order Status Request Body Parameters 

ParameterMandatoryTypeDescriptionExample
order_idYesstring(255)Order ID specified in the merchant system123443334

Status Request Sample | Success

{
  "order_id": "123443334"
}

 

    Status Response Body Parameters | Success

ParameterTypeDescriptionExample
orderobjectAn object with information of the transaction. 
order:order_idstringOrder ID specified in the merchant system123443334
order:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
order:currencystringOrder currency (3 letter code under ISO 4217)USD
order:descriptorstringDescriptorDESCRIPTOR
order:fraudulentbooleanThe customer is detected by the merchant system to be suspicious one.TRUE
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 forecasting.2575
order:marketing_currencystringThe currency of the order amount for marketing analytics.USD
order:processing_amountintegerProcessing amount of the order2575
order:processing_currencystringProcessing currency of the orderUSD
order:statusstringStatus of processed payment. Types of order statuses are described in respective directorycreated
order:refunded_amountintegerThe amount which was refunded500
order:total_fee_amountintegerTotal fee by order transaction45
order:fee_currencystringThe currency of the order feeUSD
transactionsobjectAn object with information of transactions. 
transactions:<transaction_id>objectTransaction identification within order. It contains an object with detailed information of specified transaction. Order can have several transactions.1495123020887591dc450088f1
transactions:<transaction_id>:idstringTransactions identification within order.1495123020887591dc450088f1
transactions:<transaction_id>:operationstringTransaction type. Transaction types are described in respective directory.pay
transactions:<transaction_id>:statusstringTransaction status within order. Transaction statuses are described in respective directory.success
transactions:<transaction_id>:descriptorstringDescriptorDESCRIPTOR
transactions:<transaction_id>:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
transactions:<transaction_id>:currencystringProcessing currency of orderUSD
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 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:card_holderstringCardholder nameTest User
transactions:<transaction_id>:card:bankstringBank emitentBUILDING SOCIETY
transactions:<transaction_id>:card:countrystringCountry of bankGBR
transactions:<transaction_id>:card:card_exp_monthstringA month of card expiration (2-digit format).3
transactions:<transaction_id>:card:card_exp_yearintegerA year of card expiration (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 payment.4056cd8cccf96...40015a997d74
billing_detailsobjectBilling Details 
billing_details:addressstringAddress 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
verify_urlstringUrl for 3DS verificationhttps://pay.signedpay.com/api/v1/verify-3ds/24230956/f3c4d..36637
chargebacksobjectThe object with information of the chargeback. 
chargebacks:<chargebacks_id>stringChargeback identification within order. It contains an object with detailed information of specified chargeback.2
chargebacks:<chargebacks_id> :idintegerChargeback identification within order.2
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
chargebacks:<chargebacks_id> :statusstringStatus chargebackapproved
payment_adviserobject  
payment_adviser:advisestringRecommendation for next paymentpay / resign / recurring
device_infoobject  
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

Status Response Sample | Success

{
  "transactions": {
    "1499079426595a2302db936": {
      "id": "1499079426595a2302db936",
      "operation": "pay",
      "status": "success",
      "descriptor": "descriptor",
      "amount": 10000,
      "currency": "EUR",
      "created_at": "2019-05-17 09:06:21",
      "updated_at": "2019-05-17 09:06:32",
      "card": {
        "bank": "STATE BANK",
        "bin": "453245",
        "brand": "VISA",
        "country": "USA",
        "number": "453245XXXXXX2692",
        "card_holder": "cardholder name",
        "card_exp_month": "03",
        "card_exp_year": 2025,
        "card_type": "DEBIT",
        "card_token": {
          "token": "64edcaea1441e2bde37b8afd0d0160dbd8d9db0abedf685af7b4fd0e529c8caf19abf3acd0b9b7e0bb884c85d7a21c0926a4"
        },
        "billing_details": {
        "address": "11437 Woodmeadow Pkwy",
        "zip": "85001",
        "country": "USA",
        "city": "New Delhi",
        "state": "TX"
      }
    },
    "1499079426595b4ade6e24b": {
      "id": "1499079426595b4ade6e24b",
      "operation": "refund",
      "status": "success",
      "descriptor": "descriptor",
      "amount": 10000,
      "currency": "EUR",
    }
  },
  "chargebacks": {
    "2": {
      "id": 2,
      "dispute_date": "2017-07-04",
      "settlement_date": "2017-07-04",
      "amount": 1000,
      "currency": "EUR",
      "reason_code": "222",
      "status": "approved"
    }
  },
  "order": {
    "order_id": "1499079426",
    "status": "refunded",
    "amount": 10000,
    "refunded_amount": 10000,
    "currency": "EUR",
    "marketing_amount": 11415,
    "marketing_currency": "USD",
    "processing_amount": 10000,
    "processing_currency": "EUR",
    "descriptor": "qwerty",
    "fraudulent": true,
    "total_fee_amount": 353,
    "fee_currency": "USD"
  },
  "payment_adviser": {
    "advise": "pay"
  },
  "device_info": {
    "user_agent": "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"
  }
}

Status Response Sample | 3DS

{
 "transactions": {
   "15009770463205977179b0ca46": {
     "id": "15009770463205977179b0ca46",
     "operation": "pay",
     "status": "verify",
     "descriptor": "descriptor.com",
     "amount": 50,
     "currency": "EUR",
     "created_at": "2019-05-17 09:06:21",
     "updated_at": "2019-05-17 09:06:32",
     "card": {
       "bank": "CB BANK",
       "bin": "411118",
       "brand": "VISA",
       "country": "UKR",
       "number": "411118XXXXXX4220",
       "card_holder": "cardholder name",      
       "card_exp_month": "03",
       "card_exp_year": 2025,
       "card_type": "DEBIT"
     },
      "billing_details": {
        "address": "11437 Woodmeadow Pkwy",
        "zip": "85001",
        "country": "USA",
        "city": "New Delhi",
        "state": "TX"
   }
 },
 "verify_url": "https://pay.signedpay.com/api/v1/verify-3ds/24230956/f3c4d6af64e7e8ed58aea6cc0c938b230d594b9c4ec1dd224a471d01a318ebc4d2fb8cdba9dbd7d9fe3fe73ca6c944136637",
 "order": {
   "amount": 50,
   "currency": "EUR",
   "descriptor": "descriptor.com",
   "fraudulent": true,
   "marketing_amount": 59,
   "marketing_currency": "USD",
   "processing_amount": 59,
   "processing_currency": "USD",
   "order_id": "1500977046320",
   "status": "3ds_verify"
 },
 "payment_adviser": {
    "advise": "pay"
 },
 "device_info": {
    "user_agent": "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"
 }
}

 

        Check Order Status Response Body Parameters | Fail

ParameterTypeDescriptionExample
orderobjectAn object with information of the order 
order:order_idstringOrder ID specified in the merchant system777
order:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents2575
order:currencystringOrder currency (3 letter code under ISO 4217)USD
order:descriptorstringDescriptorDESCRIPTOR
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 payment processed. Types of statuses are described in respective directories.created
order:refunded_amountintegerThe amount which was refunded500
order:processing_amountintegerProcessing amount of the order2575
order:processing_currencystringProcessing currency of the orderUSD
order:total_fee_amountintegerTotal fee by order transaction45
order:fee_currencystringThe currency of the order feeUSD
transactionsobjectAn object with information of transactions 
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>: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 card. Present in payment transactions 
transactions:<transaction_id>:card:bankstringBank-emitentBUILDING SOCIETY
transactions:<transaction_id>:card:binstringCard BIN444455
transactions:<transaction_id>:card:brandstringCard brandVISA
transactions:<transaction_id>:card:numberstringMasked card number444455XXXXXX6666
transactions:<transaction_id>:card:card_holderstringCardholder nameTest User
transactions:<transaction_id>:card:countrystringCountry of bankGBR
transactions:<transaction_id>:card:card_exp_monthstringA month of card expiration (2-digit format).3
transactions:<transaction_id>:card:card_exp_yearintegerA year of card expiration (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:tokenstringСard token to be used for recurring payments.4056cd8cccf96...40015a997d74
errorobjectObject with information on errors 
error:codestringError codes list3.02
error: messagesarrayObject with error listInsufficient funds
error:recommended_message_for_userstringRecommended error message for the userInsufficient funds
payment_adviserobject  
payment_adviser:advisestringRecommendation for the next paymentpay / resign / recurring
verify_urlstringUrl for 3DS verificationhttps://pay.signedpay.com/api/v1/verify-3ds/24230956/f3c4d..36637
chargebacksobjectThe object with information of 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
chargebacks:<chargebacks_id> :statusstringStatus chargebackapproved
payment_adviserobject  
payment_adviser:advisestringRecommendation for next paymentpay / resign / recurring
device_infoobject  
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

Status Response Sample | Fail

{
  "order": {
    "amount": 1,
    "currency": "USD",
    "descriptor": "DESCRIPTOR",
    "fraudulent": false,
    "refunded_amount": 0,
    "marketing_amount": 1,
    "marketing_currency": "USD",
    "processing_amount": 0,
    "processing_currency": "EUR",
    "order_id": "1495182314822",
    "status": "declined",
    "total_fee_amount": 353,
    "fee_currency": "USD"
  },
  "error": {
    "code": "3.02",
    "messages": [
      "Insufficient funds"
    ],
    "recommended_message_for_user": "Insufficient funds"
  },
  "transactions": {
    "1495182314822591eabeec4198": {
      "id": "1495182314822591eabeec4198",
      "operation": "pay",
      "status": "fail",
      "descriptor": "DESCRIPTOR",
      "amount": 1,
      "currency": "USD",
      "created_at": "2019-05-17 09:06:21",
      "updated_at": "2019-05-17 09:06:32",
      "card": {
        "bank": "STATE BANK",
        "bin": "444455",
        "brand": "VISA",
        "country": "USA",
        "number": "444455XXXXXX6666",
        "card_holder": "cardholder name",
        "card_exp_month": "03",
        "card_exp_year": 2025,
        "card_type": "DEBIT"
      },
      "billing_details": {
        "address": "11437 Woodmeadow Pkwy",
        "zip": "85001",
        "country": "USA",
        "city": "New Delhi",
        "state": "TX"
    }
  },
  "payment_adviser": {
    "advise": "pay"
  },
  "device_info": {
    "user_agent": "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"
  }
}

Refund transaction

This is a request for transferring funds back to the cardholder. Refunds can be made only on successfully paid orders.

POST https://pay.solidgate.com/api/v1/refund

 

    Refund Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idYesstring(100)Order ID specified in the merchant system123443334
amountYesintegerRefund amount - integer without fractional component (i.e cents). For instance, 1020 (USD) means 10 USD and 20 cents1020
refund_reason_codeNostringRefund reason - 4 digit code, specified in the refund reason list0012

Refund Request Sample | Success

{
  "order_id": "777",
  "amount": 2575
}

 

        Refund Response Body Parameters | Success

ParameterTypeDescriptionExample
orderobjectObject with information on transactions 
order:order_idstringOrder ID specified in the merchant system777
order:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents2575
order:currencystringOrder currency (3 letter code under ISO 4217)USD
order:descriptorstringDescriptorDESCRIPTOR
order:fraudulentbooleanThe customer was detected on the merchant end to be 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 order amount for marketing analyticsUSD
order:processing_amountintegerAmount in processing currency2575
order: processing_currencystringProcessing currencyUSD
order:statusstringStatus of payment processed. 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_currencystringCurrency of order feeUSD
transactionobjectObject with information on the transaction 
transaction:idstringTransaction identification within the order. Order can have several transactions1495123020887591dc450088f1
transaction:operationstringTransaction type. Available values - refundrefund
transaction:statusstringTransaction status within the ordercreated
transaction: descriptorstringDescriptorDESCRIPTOR
transaction:amountintegerTransaction amount2575
transaction:currencystringTransaction currencyUSD
transaction:refund_reasonstringReason of the refundSystem Error - PSP
transaction:refund_reason_codestringReason code as specified in the refund reason list12
transaction:created_atstringTransaction created DateTime2019-05-17 9:06:21
transaction:updated_atstringTransaction updated DateTime2019-05-17 9:06:21
transactionsobjectObject with information on transactions 
transactions:<transaction_id>stringTransaction identification within order. It contain 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 cent2575
transactions:<transaction_id>:currencystringCurrency of transaction - 3 letter code under ISO 4217.USD
transactions:<transaction_id>:refund_reasonstringReason of the refundSystem Error - PSP
transactions:<transaction_id>:refund_reason_codestringReason code as specified in the refund reason list12
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:card_holderstringCardholder nameTest User
transactions:<transaction_id>:card:card_exp_monthstringA month of expiration date on a card. (2-digit format)3
transactions:<transaction_id>:card:card_exp_yearintegerA year of expiration date on a card. (4-digit format)2025
transactions:<transaction_id>:card:card_typestringA type of the cardDEBIT
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

Refund Response Sample | Success

{
  "order": {
    "order_id": "777",
    "amount": 2575,
    "currency": "USD",
    "fraudulent": true,
    "marketing_amount": 2575,
    "marketing_currency": "USD",
    "processing_amount": 2575,
    "processing_currency": "USD",
    "status": "refunded",
    "refunded_amount": 50,
    "total_fee_amount": 48,
    "fee_currency": "USD"
  },
  "transaction": {
    "id": "149310695572758ff0116380f7",
    "operation": "refund",
    "status": "success",
    "descriptor": "DESCRIPTOR",
    "amount": 2575,
    "currency": "USD",
    "refund_reason": "System Error - PSP",
    "refund_reason_code": "0012",
    "created_at": "2019-05-17 09:06:21",
    "updated_at": "2019-05-17 09:06:32",
  },
  "transactions": {
    "149310695572758ff0116380f7": {
      "id": "149310695572758ff0116380f7",
      "operation": "refund",
      "status": "success",
      "descriptor": "DESCRIPTOR",
      "amount": 2575,
      "currency": "USD",
      "refund_reason": "System Error - PSP",
      "refund_reason_code": "0012",
      "created_at": "2019-05-17 09:06:21",
      "updated_at": "2019-05-17 09:06:32",
    },
    "149310695572758ff010f5d352": {
      "id": "149310695572758ff010f5d352",
      "operation": "pay",
      "status": "success",
      "descriptor": "DESCRIPTOR",
      "amount": 2575,
      "currency": "USD",
      "created_at": "2019-05-17 09:06:21",
      "updated_at": "2019-05-17 09:06:32",
      "card": {
        "bin": "444455",
        "brand": "VISA",
        "country": "USA",
        "number": "444455XXXXXX6666",
        "card_holder": "cardholder name",
        "card_exp_month": "03",
        "card_exp_year": 2025,
        "card_type": "DEBIT"
        "card_token": {
          "token": "140dc2f1bd02c...f806d4db669ef"
        }
      }
    }
  }
}

 

    Refund Response Body Parameters | Validation Error

ParameterTypeDescriptionExample
errorobjectAn object with information on errors 
error:codestringError codes list2.01
error: messagesobjectAn object with an error list 
error:messages:<attribute_name>stringAttribute name where an error was foundcurrency
error:messages:<error_message>arrayThe array of error messages relating to the respective attributeThis value should not be blank.

Refund Response Sample | Validation Error

{
    "error": {
        "code": "2.01",
        "messages": {
            "amount": [
                "This value should not be blank."
            ]
        }
    }
}

AUTH transaction

AUTH request allows to check the availability of a required amount of funds for a specific credit card and reserve it for a subsequent Settle.

POST https://pay.solidgate.com/api/v1/auth

Zero dollar AUTH transaction allows you to verify a cardholder's payment information upon acceptance without actually billing the customer for a charge. This type of authorization request is particularly useful for merchants offering trial periods for a product or a service. The cardholder's details will be saved to their account, allowing you to charge the card when necessary.

For example, you may choose to collect credit card information during an initial registration process and offer a 30 day trial period before actually charging the customer's credit card.
 

Some issuing banks do not support $0 authorization and may reject the charge request even if all card details are accurate. If the issuing bank rejects the $0 authorization request, a follow-up request will be sent automatically with a $1 value amount or the equivalent in the submitted processing currency.

 

    Auth Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idYesstring(100)Order ID specified in the merchant system123443334
amountYesintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents1020
currencyYesstring(3)Order currency. 3 letter currency code under ISO-4217USD
card_numberYesstring(25)Card number4111111111111111
card_holderYesstring(32)Cardholder nameJOHN SNOW
card_exp_monthYesstring(2)A month of card expiration (2-digit format)1
card_exp_yearYesstring(4)Year of card expiration (4-digit format)2024
card_cvvYesstring(4)CVV2/CVC2 card - 3 or 4 digits code123
order_descriptionYesstring(255)Order description in UTF-8 codePremium package
customer_emailYesstring(100)Customer emailjondou@gmail.com
ip_addressYesstring(50)Customer IP (only public ones)8.8.8.8
platformYesstring(6)Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - applicationWEB
geo_countryYesstring(3)Customer country subject to ISO 3166-1 alpha-3GBR
order_dateNostring(50)Date of order creation in format YYYY-MM-DD-HH-MM-SS2015-12-21 11:21:30
order_itemsNostring(255)Order description in UTF-8 codeitem 1, item 2
settle_intervalNointegerTime (in hours) after the expiration of which auto-settled is done2
customer_account_idNostring(100)Сustomer ID specified in the merchant system4dad42f808
customer_first_nameNostring(100)Customer first nameJohn
customer_last_nameNostring(100)Customer last nameSnow
customer_phoneNostring(50)Customer phone number380111111111
customer_date_of_birthNostring(50)Birthdate in YYYY-MM-DD format2000-11-21
geo_cityNostring(100)Customer CityNew Castle
languageNostring(2)Customer language settings. Available values: RU - Russian, EN - Englishen
fraudulentNobooleanA customer is detected by the merchant system to be suspicious one. The payment will be effected via 3DSTRUE
callback_urlNostring(255)URL of merchant page, where response with payment result will be sent via the host-to-host connectionhttp://merchant.example/callback
status_urlNostring(255)URL of merchant page, which customers will be redirected upon 3DS verification on bank end with the status of operation in URL parameter - http://merchant.example/status/?order_id=123443334&status=approvedhttp://merchant.example/status
chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback will be senthttp://merchant.example/chargeback
alert_chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback alerts will be senthttp://merchant.example/chargeback_alerts
verifiedNobooleanA user was verified on the shop sideTRUE
retry_attemptNointegerA number of retry payment1
traffic_sourceNostring(255)Source of trafficfacebook
transaction_sourceNostring(255)Source of transactions on sitemain_menu
user_agentNostringUser-agent of the customerMozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36
deviceNostringDevice of customeriPhone 8 iOS 12.0
operating_systemNostringInformation about the operating system of the customer deviceiOS
operating_system_versionNostringInformation about the version of the operating system of the customer device12
browserNostringInformation about the browser of the customer deviceSafari
browser_versionNostringInformation about the version of the browser of the customer device12
websiteNostring(255)Website from which transaction took placegoogle.com
order_numberNointegerA number of payments by the user1
addressNostring(100)Address (mandatory parameter for USA location) 
stateNostring(255)State (mandatory parameter for USA location)WA
zip_codeNostring(10)The parameter for identifying a location. (mandatory parameter for USA location)10005
cityNostring(100)Customer city. (mandatory parameter for USA location)New York
cpfNostring(255)Individual taxpayer registry identification. (mandatory parameter for Brazilian location)210.717.664-73
force3dsNobooleanRouting payments flag for 3DS flow (enabled by Solid account manager)FALSE

Auth Request Sample | Success

{
  "amount": 2575,
  "callback_url": "http://merchant.example/callback",
  "card_cvv": "123",
  "card_exp_month": "12",
  "card_exp_year": "2018",
  "card_holder": "JOHN SNOW",
  "card_number": "4111111111111111",
  "currency": "USD",
  "customer_account_id": "user_id",
  "customer_date_of_birth": "2000-11-21",
  "customer_email": "example.user@example-email.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "380000000000",
  "fraudulent": true,
  "geo_city": "New Castle",
  "geo_country": "GBR",
  "ip_address": "8.8.8.8",
  "language": "en",
  "order_date": "2015-12-21 11:21:30",
  "order_description": "Premium package",
  "order_id": "777",
  "order_items": "item 1, item 2",
  "platform": "WEB",
  "status_url": "http://merchant.example/status",
  "chargeback_notification_url": "http://merchant.example/chargeback"
}

 

    Auth Response Body Parameters | Success

ParameterTypeDescriptionExample
transactionsobjectAn object with information on transactions. 
transactions:<transaction_id>objectTransaction identification within order. It contains an object with detailed information of specified transaction. Order can have several transactions.15174857081755a72fe8da8ccd
transactions:<transaction_id>:idstringTransactions identification within order.15174857081755a72fe8da8ccd
transactions:<transaction_id>:operationstringTransaction type. Transaction types are described in respective directory.auth
transactions:<transaction_id>:statusstringTransaction status within order. Transaction statuses are described in respective directory.success
transactions:<transaction_id>:descriptorstringThe descriptor for the transactionpayhere.com
transactions:<transaction_id>:amountintegerTransaction amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
transactions:<transaction_id>:currencystringTransaction currency.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>:cardobjectAn object with information about the card. Present in payment transactions. 
transactions:<transaction_id>:card:binstringCard BIN.411111
transactions:<transaction_id>:card:brandstringCard Brand.VISA
transactions:<transaction_id>:card:numberstringMasked card number.411111XXXXXX1111
transactions:<transaction_id>:card:card_holderstringCardholder nameTest User
transactions:<transaction_id>:card:bankstringBank emitent.STATE BANK
transactions:<transaction_id>:card:countrystringCountry of bank.USA
transactions:<transaction_id>:card:card_exp_monthstringA month of expiration date on a card. (2-digit format)3
transactions:<transaction_id>:card:card_exp_yearintegerA year of expiration date on a card. (4-digit format)2025
transactions:<transaction_id>:card:card_typestringA type of the card.DEBIT
orderobjectAn object with order information. 
order:order_idstringOrder ID specified in the merchant system.123443334
order:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
order:currencystringOrder currency (3 letter code under ISO 4217).USD
order:fraudulentstringA customer was detected on the merchant end to be suspicious one.TRUE
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 forecasting.2575
order:marketing_currencystringThe currency of the order amount for marketing analytics.USD
order:statusstringStatus of payment processed. Types of order statuses are described in the respective directory.processing
order:total_fee_amountintegerTotal fee amount0
order:refunded_amountintegerRefunded amount0
order:descriptorstringThe descriptor for the transactionpayhere.com
transactionobjectAn object with information on the transaction. 
transaction:idstringTransaction identification within the order. The order can have several transactions.15174857081755a72fe8da8ccd
transaction:operationstringTransaction type.auth
transaction:statusstringTransaction status within the order.created
transaction:amountintegerTransaction amount.2575
transaction:currencystringTransaction currency.USD
transaction:created_atstringTransaction created DateTime2019-05-17 9:06:21
transaction:updated_atstringTransaction updated DateTime2019-05-17 9:06:21
transaction:card:objectAn object with information about the card. Present in payment transactions. 
transaction:card:bankstringBank emitent.STATE BANK
transaction:card:binstringCard BIN.411111
transaction:card:brandstringCard Brand.VISA
transaction:card:countrystringCountry of the bank.USA
transaction:card:numberstringMasked card number.411111XXXXXX1111
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

Auth Response Sample | Success

{
  "transactions": {
    "37637fd27f201bb65f25bb68d1044": {
      "id": "37637fd27f201bb65f25bb68d1044",
      "operation": "auth",
      "status": "created",
      "descriptor": "descriptor.org",
      "amount": 10,
      "currency": "USD",
      "created_at": "2020-08-01 18:58:48",
      "updated_at": "2020-08-01 18:58:49",
      "marketing_currency": "USD",
      "marketing_amount": 10,
      "card": {
        "bank": "STATE BANK",
        "bin": "411111",
        "brand": "VISA",
        "country": "USA",
        "number": "411111XXXXXX1111",
        "card_exp_month": "10",
        "card_exp_year": 2024,
        "card_type": "DEBIT",
        "card_holder": "cardholder name"
      }
    }
  },
  "order": {
    "order_id": "1596308327582",
    "status": "processing",
    "amount": 10,
    "refunded_amount": 0,
    "currency": "USD",
    "marketing_amount": 10,
    "marketing_currency": "USD",
    "processing_amount": 10,
    "processing_currency": "USD",
    "descriptor": "descriptor.org",
    "fraudulent": false
  },
  "transaction": {
    "id": "37637fd27f201bb65f25bb68d1044",
    "operation": "auth",
    "status": "created",
    "descriptor": "descriptor.org",
    "amount": 10,
    "currency": "USD",
    "created_at": "2020-08-01 18:58:48",
    "updated_at": "2020-08-01 18:58:49",
    "marketing_currency": "USD",
    "marketing_amount": 10,
    "card": {
      "bank": "STATE BANK",
        "bin": "411111",
        "brand": "VISA",
        "country": "USA",
        "number": "411111XXXXXX1111",
        "card_exp_month": "10",
        "card_exp_year": 2024,
        "card_type": "DEBIT",
        "card_holder": "cardholder name"
    }
  }
}

 

    Auth Response Body Parameters | Validation Error 

ParameterTypeDescriptionExample
errorobjectAn object with information on errors 
error:codestringError codes list2.01
error: messagesobjectAn object with an error list 
error:messages:<attribute_name>stringAttribute name where an error was foundcurrency
error:messages:<error_message>arrayThe array of error messages relating to the respective attributeThis value should not be blank.

Auth Response Sample | Validation Error

{
    "error": {
        "code": "2.01",
        "messages": {
            "currency": [
                "This value should not be blank."
            ],
            "customer_email": [
                "This value should not be blank."
            ],
            "ip_address": [
                "This value should not be blank."
            ],
            "order_description": [
                "This value should not be blank."
            ],
            "order_id": [
                "This value should not be blank."
            ],
            "platform": [
                "This value should not be blank."
            ]
        }
    }
}

AUTH 3D transaction

AUTH request allows to check the availability of a required amount of funds for a specific credit card and reserve it for a subsequent Settle. 

AUTH 3D going through a few additional steps:

1) AUTH request;
2) Redirect to URL 3DS verification.

POST https://pay.solidgate.com/api/v1/auth

 

        1. Auth 3DS Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idYesstring(100)Order ID specified in the merchant system123443334
amountYesintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents1020
currencyYesstring(3)Order currency. 3 letter currency code under ISO-4217USD
card_numberYesstring(25)Card number4111111111111111
card_holderYesstring(32)Cardholder nameJOHN SNOW
card_exp_monthYesstring(2)A month of card expiration (2-digit format)01
card_exp_yearYesstring(4)Year of card expiration (4-digit format)2024
card_cvvYesstring(4)CVV2/CVC2 card - 3 or 4 digits code123
order_descriptionYesstring(255)Order description in UTF-8 codePremium package
customer_emailYesstring(100)Customer emailjondou@gmail.com
ip_addressYesstring(50)Customer IP (only public ones)8.8.8.8
platformYesstring(6)Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - applicationWEB
geo_countryYesstring(3)Customer country subject to ISO 3166-1 alpha-3GBR
order_dateNostring(50)Date of order creation in format YYYY-MM-DD-HH-MM-SS2015-12-21 11:21:30
order_itemsNostring(255)Order description in UTF-8 coditem 1, item 2
customer_account_idNostring(100)Сustomer ID specified in the merchant system.4dad42f808
customer_first_nameNostring(100)Customer's first nameJohn
customer_last_nameNostring(100)Customer last nameSnow
customer_phoneNostring(50)Customer phone number380111111111
customer_date_of_birthNostring(50)Birthdate in YYYY-MM-DD format2000-11-21
geo_cityNostring(100)Customer CityNew Castle
languageNostring(2)Customer language settings. Available values: RU - Russian, EN - Englishen
fraudulentNobooleanA customer is detected by the merchant system to be suspicious one. The payment will be effected via 3DStrue
callback_urlNostring(255)URL of merchant page, where response with payment result will be sent via the host-to-host connectionhttp://merchant.example/callback
status_urlNostring(255)URL of merchant page, which customers will be redirected upon 3DS verification on bank end with the status of the operation in the URL parameterhttp://merchant.example/status
chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback will be senthttp://merchant.example/chargeback
alert_chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback alerts will be senthttp://merchant.example/chargeback_alerts
verifiedNobooleanThe user was verified on the shop sidetrue
retry_attemptNointegerA number of retry payment1
traffic_sourceNostring(255)Source of trafficfacebook
transaction_sourceNostring(255)Source of transactions on the websitemain_menu
user_agentNostringUser-agent of the customerMozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36
deviceNostringDevice of customeriPhone 8 iOS 12.0
operating_systemNostringInformation about the operating system of the customer deviceiOS
operating_system_versionNostringInformation about the version of the operating system of the customer device12.0
browserNostringInformation about the browser of the customer deviceSafari
browser_versionNostringInformation about the version of the browser of the customer device12.0
order_numberNointegerA number of payments by the user.1
addressNostring(100)Address (mandatory parameter for USA location). 
stateNostring(255)State (mandatory parameter for USA location)WA
zip_codeNostring(10)The parameter for identifying a location. (mandatory parameter for USA location)10005
cityNostring(100)Customer city. (mandatory parameter for USA location)New York
cpfNostring(255)Individual taxpayer registry identification. (mandatory parameter for Brazilian location)210.717.664-73
force3dsNobooleanRouting payments flag for 3DS flow (enabled by Solid account manager)false
header_acceptYes - 3D 2.0string(255)Header Accepttext/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng
header_accept_languageYes - 3D 2.0string(255)Header Accept Languageru-RU,ru;q=0.9,en-US;q=0.8
browser_color_depthYes - 3D 2.0integerThe colour depth of the browser window32
browser_screen_heightYes - 3D 2.0integerHeight of browser window1920
browser_screen_widthYes - 3D 2.0integerWidth of the browser window1280
browser_java_enabledYes - 3D 2.0booleanIs java enabled on User's browserfalse
browser_javascript_enabledYes - 3D 2.0booleanIs javascript enabled on User's browserfalse
time_zone_offsetYes - 3D 2.0integerThe time difference, in minutes, between UTC time and the local time of the cardholder's browser60

Auth 3DS Request Sample | Success

{
  "amount": 2575,
  "callback_url": "http://merchant.example/callback",
  "card_cvv": "123",
  "card_exp_month": "12",
  "card_exp_year": "2018",
  "card_holder": "JOHN SNOW",
  "card_number": 4111111111111111,
  "currency": "USD",
  "customer_account_id": "user_id",
  "customer_date_of_birth": "2000-11-21",
  "customer_email": "example.user@example-email.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "380000000000",
  "fraudulent": true,
  "geo_city": "New Castle",
  "geo_country": "GBR",
  "ip_address": "8.8.8.8",
  "language": "en",
  "order_date": "2015-12-21 11:21:30",
  "order_description": "Premium package",
  "order_id": "777",
  "order_items": "item 1, item 2",
  "platform": "WEB",
  "status_url": "http://merchant.example/status",
  "chargeback_notification_url": "http://merchant.example/chargeback",
  "header_accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng",
  "header_accept_language": "ru-RU,ru;q=0.9,en-US;q=0.8",
  "browser_color_depth": 32,
  "browser_screen_height": 1920,
  "browser_screen_width": 1280,
  "browser_java_enabled": true,
  "browser_javascript_enabled": true,
  "time_zone_offset": 60
}

 

       Auth 3DS Response Body Parameters | Success

ParameterTypeDescriptionExample
transactionsobjectAn object with information on transactions 
transactions:<transaction_id>stringTransaction identification within the order. It contains an object with detailed information about the specified transaction. Order can have several transactions15174857081755a72fe8da8ccd
transactions:<transaction_id>:idstringTransactions identification within the order15174857081755a72fe8da8ccd
transactions:<transaction_id>:operationstringTransaction type. Transaction types are described in respective directoryauth
transactions:<transaction_id>:statusstringTransaction status within the order. Transaction statuses are described in respective directorysuccess
transactions:<transaction_id>:amountintegerTransaction amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents2575
transactions:<transaction_id>:currencystringTransaction currencyUSD
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>:cardobjectAn object with information about the card. Present in payment transactions 
transactions:<transaction_id>:card:binstringCard BIN411111
transactions:<transaction_id>:card:brandstringCard BrandVISA
transactions:<transaction_id>:card:numberstringMasked card number411111XXXXXX1111
transactions:<transaction_id>:card:card_holderstringCardholder nameTest User
transactions:<transaction_id>:card:bankstringBank emitentSTATE BANK
transactions:<transaction_id>:card:countrystringCountry of bankUSA
transactions:<transaction_id>:card:card_exp_monthstringA month of expiration date on a card. (2-digit format)3
transactions:<transaction_id>:card:card_exp_yearintegerA year of expiration date on a card. (4-digit format)2025
transactions:<transaction_id>:card:card_typestringA type of the cardDEBIT
orderobjectAn object with order information 
order:order_idstringOrder ID specified in the merchant system123443334
order:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents2575
order:currencystringOrder currency (3 letter code under ISO 4217)USD
order:fraudulentbooleanA customer was detected on the merchant end to be 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 payment processed. Types of order statuses are described in the respective directoryprocessing
order:total_fee_amountintegerTotal fee amount0
order:refunded_amountintegerRefunded amount0
order:descriptorstringThe descriptor for the transactionpayhere.com
transactionobjectAn object with information on the transaction 
transaction:idstringTransaction identification within the order. The order can have several transactions15174857081755a72fe8da8ccd
transaction:operationstringTransaction typepay
transaction:statusstringTransaction status within the ordercreated
transaction:amountintegerTransaction amount2575
transaction:currencystringTransaction currencyUSD
transaction:created_atstringTransaction created DateTime2019-05-17 9:06:21
transaction:updated_atstringTransaction updated DateTime2019-05-17 9:06:21
transaction:card:objectAn object with information about the card. Present in payment transactions 
transaction:card:bankstringA bank that issued the cardSTATE BANK
transaction:card:binstringCard BIN411111
transaction:card:brandstringCard BrandVISA
transaction:card:countrystringCountry of the bankUSA
transaction:card:numberstringMasked card number411111XXXXXX1111
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 cardDEBIT
transaction:card:card_typestringA type of the cardDEBIT
chargebacks:<chargebacks_id> :amountintegerChargeback amount1000
chargebacks:<chargebacks_id> :currencystringChargeback currencyUSD
chargebacks:<chargebacks_id> :reason_codestringReason code of chargeback222
chargebacks:<chargebacks_id> :statusstringStatus chargebackapproved
payment_adviserobject  
payment_adviser:advisestringRecommendation for next paymentpay / resign / recurring
device_infoobject  
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

Auth Response Sample | Success

{
  "transactions": {
    "15174857081755a72fe8da8ccd": {
      "id": "15174857081755a72fe8da8ccd",
      "operation": "auth",
      "status": "created",
      "amount": 2575,
      "currency": "USD",
      "created_at": "2019-05-17 09:06:21",
      "updated_at": "2019-05-17 09:06:32",
      "card": {
        "bank": "STATE BANK",
        "bin": "411111",
        "brand": "VISA",
        "country": "USA",
        "number": "411111XXXXXX1111",
        "card_holder": "cardholder name",
        "card_exp_month": "03",
        "card_exp_year": 2025,
        "card_type": "DEBIT"
      }
    }
  },
  "order": {
    "order_id": "123443334",
    "status": "processing",
    "amount": 2575,
    "refunded_amount": 0,
    "currency": "USD",
    "marketing_amount": 2575,
    "marketing_currency": "USD",
    "fraudulent": true,
    "total_fee_amount": 0,
    "descriptor":"payhere.com"
  },
  "transaction": {
    "id": "15174857081755a72fe8da8ccd",
    "operation": "auth",
    "status": "created",
    "amount": 2575,
    "currency": "USD",
    "created_at": "2019-05-17 09:06:21",
    "updated_at": "2019-05-17 09:06:32",
    "card": {
      "bank": "STATE BANK",
       "bin": "411111",
       "brand": "VISA",
       "country": "USA",
       "number": "411111XXXXXX1111",
       "card_holder": "cardholder name",
       "card_exp_month": "03",
       "card_exp_year": 2025,
       "card_type": "DEBIT"
      }
    }
}

2. Redirect to 3DS verification URL. 

Please, note, you should show the 3DS bank page for a user after the auth 3DS request, `verify_url` can be received from the following  requests: Status or Notification.

VOID transaction

The VOID request is used for voiding a previously performed authorized transactions.

POST https://pay.solidgate.com/api/v1/void

 

    Void Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idYesstring(100)Order ID specified in the merchant system 

Void Request Sample

{
  "order_id": "123443334"
}

 

    Void Response Body Parameters | Success

ParameterTypeDescriptionExample
orderobjectAn object with information of the transaction 
order:order_idstringOrder ID specified in the merchant system1517501959601
order:statusstringStatus of processed payment . Types of order statuses are described in respective directoryvoid_ok
order:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents2575
order:currencystringOrder currency (3 letter code under ISO 4217)USD
order:descriptorstringDescriptorDESCRIPTOR
order:fraudulentbooleanA customer is detected by the merchant system to be 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:processing_amountintegerAmount of order for marketing analytics2575
order:processing_currencystringProcessing amount of orderUSD
order:total_fee_amountintegerTotal fee by order transaction120
order:fee_currencystringThe currency of the order feeUSD
order:refunded_amountintegerRefunded amount0
transactionsobjectAn object with information on transactions 
transactions:<transaction_id>objectTransaction identification within the order. It contains an object with detailed information about the specified transaction. Order can have several transactions15175019596015a733f7a4f91a
transactions:<transaction_id>:idstringTransactions identification within the order15175019596015a733f7a4f91a
transactions:<transaction_id>:operationstringTransaction type. Transaction types are described in respective directoryvoid
transactions:<transaction_id>:statusstringTransaction status within the order. Transaction statuses are described in respective directorysuccess
transactions:<transaction_id>:descriptorstringDescriptor.DESCRIPTOR
transactions:<transaction_id>:amountintegerTransactions amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents2575
transactions:<transaction_id>:currencystringTransactions currencyUSD
transactions:<transaction_id>:created_atstringTransaction created DateTime2019-05-17 09:06:21
transactions:<transaction_id>:updated_atstringTransaction updated DateTime2019-05-17 09:06:21
transactions:<transaction_id>:cardobjectAn object with information about the card. Present in payment transactions 
transactions:<transaction_id>:card:binstringCard BIN411111
transactions:<transaction_id>:card:brandstringCard BrandVISA
transactions:<transaction_id>:card:numberstringMasked card number411111XXXXXX1111
transactions:<transaction_id>:card:card_holderstringCardholder nameTest User
transactions:<transaction_id>:card:bankstringBank that issues the cardSTATE BANK
transactions:<transaction_id>:card:countrystringCountry of bankUSA
transactions:<transaction_id>:card:card_exp_monthstringA month of expiration date on a card. (2-digit format)03
transactions:<transaction_id>:card:card_exp_yearintegerA year of expiration date on a card. (4-digit format)2025
transactions:<transaction_id>:card:card_typestringA type of the cardDEBIT
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 payment86c1b0416c3...e2c99a20
transactionobjectAn object with information on the transaction 
transaction:idstringTransaction identification within the order. The order can have several transactions00016857481e16b07fc
transaction:operationstringTransaction typevoid
transaction: statusstringTransaction status within the ordercreated
transaction: descriptorstringDescriptorDESCRIPTOR
transaction:amountintegerTransaction amount2575
transaction:currencystringTransaction currency.USD
transaction:created_atstringTransaction created DateTime2019-05-17 09:06:21
transaction:updated_atstringTransaction updated DateTime2019-05-17 09:06:21

Void Response Sample | Success

{
  "transactions": {
    "15175019596015a733f7a4f91a": {
      "id": "15175019596015a733f7a4f91a",
      "operation": "void",
      "status": "success",
      "descriptor": "DESCRIPTOR",
      "amount": 2575,
      "currency": "USD",
      "created_at": "2019-05-17 09:06:21",
      "updated_at": "2019-05-17 09:06:32"
    },
    "15175019596015a733e0929df7": {
      "id": "15175019596015a733e0929df7",
      "operation": "auth",
      "status": "success",
      "descriptor": "DESCRIPTOR",
      "amount": 2575,
      "currency": "USD",
      "created_at": "2019-05-17 09:06:21",
      "updated_at": "2019-05-17 09:06:32",
      "card": {
        "bank": "STATE BANK",
        "bin": "411111",
        "brand": "VISA",
        "country": "USA",
        "number": "411111XXXXXX1111",
        "card_holder": "cardholder name",
        "card_exp_month": "03",
        "card_exp_year": 2025,
        "card_exp_type": "DEBIT",
        "card_token": {
          "token": "86c1b0416c3088a6ca3de9998f934c6be2a3f7964ba883c4f67886041898584747d361116832107b563790ea99a5e2c99a20"
        }
      }
    }
  },
  "order": {
    "order_id": "1517501959601",
    "status": "void_ok",
    "amount": 2575,
    "refunded_amount": 0,
    "currency": "USD",
    "marketing_amount": 2575,
    "marketing_currency": "USD",
    "processing_amount": 2575,
    "processing_currency": "USD",
    "descriptor": "DESCRIPTOR",
    "fraudulent": true,
    "total_fee_amount": 120,
    "fee_currency": "USD"
  },
  "transaction": {
    "id": "15175019596015a733f7a4f91a",
    "operation": "void",
    "status": "success",
    "descriptor": "DESCRIPTOR",
    "amount": 2575,
    "currency": "USD",
    "created_at": "2019-05-17 09:06:21",
    "updated_at": "2019-05-17 09:06:32"
  }
}

 

    Void Response Body Parameters | Validation Error 

ParameterTypeDescriptionExample
errorobjectAn object with information on errors 
error:codestringError codes list. 2.01
error: messagesobjectAn object with an error list 
error: messages:<attribute_name>stringAttribute name where the error was foundsystem
error: messages:<error_message>arrayThe array of error messages relating to the respective attributeInvalid data for request

Void Response Sample | Validation Error

{
    "error": {
        "code": "2.01",
        "messages": {
            "currency": [
                "This value should not be blank."
            ],
            "customer_email": [
                "This value should not be blank."
            ],
            "ip_address": [
                "This value should not be blank."
            ],
            "order_description": [
                "This value should not be blank."
            ],
            "order_id": [
                "This value should not be blank."
            ],
            "platform": [
                "This value should not be blank."
            ]
        }
    }
}

SETTLE transaction

The Settle method is used for settling an authorized transaction that was previously performed.

POST https://pay.solidgate.com/api/v1/settle

 

    Settle Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idYesstring(100)Order ID specified in merchant system1517502021714
amountYesintegerSettle amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents2575

Please, note, if the Settle amount is less than AUTH one - the difference will be sent back to the user.

Settle Request Sample | Success

{
  "order_id": "1517502021714",
  "amount": 2575
}

 

    Settle Response Body Parameters | Success

ParameterTypeDescriptionExample
orderobjectAn object with information of the transaction 
order:order_idstringOrder ID specified in the merchant system1517502021714
order:statusstringStatus of processed payment. Types of order statuses are described in the  respective directorysettle_ok
order:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents2575
order:currencystringOrder currency (3 letter code under ISO 4217)USD
order:descriptorstringDescriptorDESCRIPTOR
order:fraudulentbooleanA customer is detected by the merchant system to be 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:processing_amountintegerAmount of order for marketing analytics2575
order:processing_currencystringProcessing amount of orderUSD
order:total_fee_amountintegerTotal fee by order transaction120
order:fee_currencystringThe currency of the order feeUSD
order:refunded_amountintegerRefunded amount0
transactionsobjectAn object with information on transactions 
transactions:<transaction_id>objectTransaction identification within the order. It contains an object with detailed information about the specified transaction. Order can have several transactions15175020217145a73465797e66
transactions:<transaction_id>:idstringTransactions identification within the order15175020217145a73465797e66
transactions:<transaction_id>:operationstringTransaction type. Transaction types are described in the respective directorysettle
transactions:<transaction_id>:statusstringTransaction status within the order. Transaction statuses are described in the respective directorysuccess
transactions:<transaction_id>:descriptorstringDescriptorDESCRIPTOR
transactions:<transaction_id>:amountintegerTransactions amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents2575
transactions:<transaction_id>:currencystringTransactions currencyUSD
transactions:<transaction_id>:created_atstringTransaction created DateTime2019-05-17 09:06:21
transactions:<transaction_id>:updated_atstringTransaction updated DateTime2019-05-17 09:06:21
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
transactions:<transaction_id>:cardobjectAn object with information about the card. Present in payment transactions 
transactions:<transaction_id>:card:binstringCard BIN411111
transactions:<transaction_id>:card:brandstringCard BrandVISA
transactions:<transaction_id>:card:numberstringMasked card number411111XXXXXX1111
transactions:<transaction_id>:card:card_holderstringCardholder nameTest User
transactions:<transaction_id>:card:bankstringBank emitent STATE BANK
transactions:<transaction_id>:card:countrystringCountry of bankUSA
transactions:<transaction_id>:card:card_exp_monthstringA month of expiration date on a card. (2-digit format)03
transactions:<transaction_id>:card:card_exp_yearintegerA year of expiration date on a card. (4-digit format)2025
transactions:<transaction_id>:card:card_typestringA type of the cardDEBIT
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 paymentd89f0b146fdffd...98b6d5d076
transactionobjectAn object with information on the transaction 
transaction:idstringTransaction identification within the order. The order can have several transactions15175020217145a73465797e66
transaction:operationstringTransaction typesettle
transaction:statusstringTransaction status within the ordercreated
transaction:descriptorstringDescriptorDescriptor
transaction:amountintegerSettle amount2575
transaction:currencystringTransactions currency.USD
transaction:created_atstringTransaction created DateTime2019-05-17 09:06:21
transaction:updated_atstringTransaction updated DateTime2019-05-17 09:06:21
transaction:feeobjectFee for the specified transaction. 
transaction:fee:amountintegerThe fee amount for the transaction - integer without fractional component (i.e cents). For instance, 120 (USD) means 1 USD and 20 cents31
transaction:fee:currencystringThe currency of transaction fee - 3-digit letter code under ISO 4217USD

Settle Response Sample | Success

{
  "transactions": {
    "15175020217145a73465797e66": {
      "id": "15175020217145a73465797e66",
      "operation": "settle",
      "status": "success",
      "descriptor": "DESCRIPTOR",
      "amount": 2575,
      "currency": "USD",
      "created_at": "2019-05-17 09:06:21",
      "updated_at": "2019-05-17 09:06:32",
      "fee": {
        "amount": 120,
        "currency": "USD"
      }
    },
    "15175020217145a733e4756ba3": {
      "id": "15175020217145a733e4756ba3",
      "operation": "auth",
      "status": "success",
      "descriptor": "DESCRIPTOR",
      "amount": 2575,
      "currency": "USD",
      "created_at": "2019-05-17 09:06:21",
      "updated_at": "2019-05-17 09:06:32",
      "fee": {
        "amount": 0,
        "currency": "USD"
      },
      "card": {
        "bank": "STATE BANK",
        "bin": "411111",
        "brand": "VISA",
        "country": "USA",
        "number": "411111XXXXXX1111",
        "card_holder": "cardholder name",
        "card_exp_month": "03",
        "card_exp_year": 2025,
        "card_type": "DEBIT",
        "card_token": {
          "token": "d89f0b146fdffd94f7a7a906e6194a34edas452fdf681111695a597317d3602942d9014175c63bf88751198b6d5d076"
        }
      }
    }
  },
  "order": {
    "order_id": "1517502021714",
    "status": "settle_ok",
    "amount": 2575,
    "refunded_amount": 0,
    "currency": "USD",
    "marketing_amount": 2575,
    "marketing_currency": "USD",
    "processing_amount": 2575,
    "processing_currency": "USD",
    "descriptor": "DESCRIPTOR",
    "fraudulent": true,
    "total_fee_amount": 120,
    "fee_currency": "USD"
  },
  "transaction": {
    "id": "15175020217145a73465797e66",
    "operation": "settle",
    "status": "success",
    "descriptor": "DESCRIPTOR",
    "amount": 2575,
    "currency": "USD",
    "created_at": "2019-05-17 09:06:21",
    "updated_at": "2019-05-17 09:06:32",
    "fee": {
      "amount": 31,
      "currency": "USD"
    }
  }
}

 

    Settle Response Body Parameters | Validation Error

ParameterTypeDescriptionExample
errorobjectAn object with information on errors 
error:codestringError codes list2.01
error: messagesobjectAn object with the error list 
error: messages:<attribute_name>stringAttribute name where the error was foundstatus
error: messages:<error_message>arrayThe array of error messages relating to the respective attributeIllegal order status for settle operation.

Settle Response Sample | Validation Error

{
  "error": {
    "code": "2.01",
    "messages": {
      "status": [
        "Illegal order status for settle operation."
      ]
    }
  }
}

ARN Codes

Request for receiving ARN code.

All requests must be signed.

POST https://pay.solidgate.com/api/v1/arn-code

 

    Receive ARN Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idYesstring(255)Order ID specified in the merchant system123443334

ARN is available only if the order status is refunded.

Receive ARN Request Sample | Success

{
  "order_id": "123443334"
}

 

    Receive ARN Response Body Parameters | Success

ParameterTypeDescriptionExample
arn_codesobjectArray data with information about ARN codes corresponding to the order requested 
arn_codes:arn_codestringARN code for a refund transaction. If PSP hasn't assigned ARN code yet, the value is equal to null. It can take up to 48 hours for a payment provider to assign ARN code for the transaction74208328039016341469667
arn_codes:amount_refundedintegerOrder amount - integer without fractional components (i.e cents). For instance, 1020 means 10 USD and 20 cents1020
arn_codes:currencystringOrder currency (3 letter code under ISO 4217)USD
arn_codes:transaction_statusstringTransaction status of a refund within the order. Transaction statuses are described in transaction status directorysuccess
arn_codes:sp_transaction_idstringThe ID of respective SP transaction if matched. If a refund is performed through PSP's admin-panel, it's difficult to establish a direct link with SP transaction in our system2045
arn_codes:created_atstringDate and time of refund performed on the PSP end2018-02-07 12:42:09

Receive ARN Response Sample | Success


{
    "arn_codes":[
        {
            "transaction_status":"success",
            "arn_code":"74208328039016341469667",
            "amount_refunded":100,
            "currency":"USD",
            "sp_transaction_id":2045,
            "created_at":"2018-02-07 12:42:09"
        }
    ],
    "error":null
}

Receive ARN Response Sample | Success without ARN

{
    "arn_codes":[
        {
            "transaction_status":"success",
            "arn_code":null,
            "amount_refunded":100,
            "currency":"USD",
            "sp_transaction_id":2045,
            "created_at":"2018-02-07 12:42:09"
        }
    ],
    "error":null
}

 

    Receive ARN Response Body Parameters | Error

ParameterTypeDescriptionExample
errorobjectObject with information about errors 
error:codestringError codes. Error codes directory.5.10
error: messagesarrayMessage error arrayThe processor does not support the requested API method
error: recommended_message_for_userstringThe error message is recommended to show a customerThe processor does not support the requested API method


 

Receive ARN Response Sample | Error


{
    "arn_codes":[],
    "error":{
        "code":"5.10",
        "messages":[
            "Processor does not support requested API method"
        ],
        "recommended_message_for_user":"Processor does not support requested API method"
    }
}

Payment form in one request

Payment form in one request is generated according to the following parameters:

Merchant - this is the unique merchant ID, provided to you during the integration process;

Form_Data - encrypted aes-cbc-256 string of JSON request data with random IV and the key is first 16bytes of merchant private key encrypted in АЕС key - first 15 bytes of the private key.

Signature - Signature of request. It allows verifying whether the request from the merchant is genuine on the payment gateway server. In this case, it’s generated not from JSON, but from Form_data. 
 

GET https://pay.solidgate.com/api/v1/form?merchant={merchant_id}&signature={signature}&form_data={form_data}

 

    Form Request Body Parameters

ParameterMandatoryTypeDescriptionExample
amountYesintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents1020
currencyYesstring(3)Currency amount. 3 letter currency code under ISO-4217USD
customer_account_idNostring(100)Customer ID in the merchant's system4dad42f808
customer_date_of_birthNostring(50)Customer birth date in format YYYY-MM-DD2000-11-21
customer_emailYesstring(100)Customer emailjondou@gmail.com
customer_first_nameNostring(100)Customer's first nameJohn
customer_last_nameNostring(100)Customer last nameSnow
customer_phoneNostring(50)Customer telephone380111111111
form_nameNostring(100)Form namewo_cardholder
form_design_nameNostring(100)Form design namepromo_christmas
fraudulentNobooleanThe customer is detected by the merchant system to be suspicious one. The payment will be effected via 3DSTRUE
geo_countryYesstring(3)Customer country subject to ISO 3166-1 alpha-3GBR
geo_cityNostring(100)Customer cityNew Castle
ip_addressYesstring(50)Customer IP (only public ones)8.8.8.8
languageNostring(2)Customer language settings. Available values: RU - Russian, EN - English, FR - French, ES - Spanish, PT - Portuguese, JA - Japaneseen
order_idYesstring(100)Order ID specified in merchant system123443334
order_dateNostring(50)Date of order creation in format YYYY-MM-DD-HH-MM-SS2015-12-21 11:21:30
order_descriptionYesstring(255)Order description in UTF-8 codePremium package
order_itemsNostring(255)Order items in UTF-8 codeitem 1, item 2
platformYesstring(6)Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - applicationWEB
callback_urlNostring(255)URL of merchant page, where response with payment result will be senthttp://merchant.example/callback
fail_urlNostring(255)URL of merchant page, which a customer will be redirected in case of unsuccessful paymenthttp://merchant.example/fail
success_urlNostring(255)URL of merchant page, which a customer will be redirected in case of successful paymenthttp://merchant.example/success
chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback will be senthttp://merchant.example/chargeback
alert_chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback alerts will be senthttp://merchant.example/chargeback_alerts
verifiedNobooleanA user was verified on the shop sideTRUE
retry_attemptNointegerNumber of retry payment1
traffic_sourceNostring(255)Source of trafficfacebook
transaction_sourceNostring(255)Source of transactions on the websitemain_menu
user_agentNostringUser-agent of the customerMozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36
deviceNostringDevice of customeriPhone 8 iOS 12.0
order_numberNointegerNumber of payments by user1
typeNostringParameter for transaction authorization through a payment formauth
settle_intervalNointegerTime (in hours) when auto-settle will be done1
force3dsNobooleanRouting payments flag for 3DS flow (enabled by Solid account manager)FALSE

Form Request Sample

{
  "amount": 2575,
  "callback_url": "http://merchant.example/callback",
  "currency": "USD",
  "customer_account_id": "user_id",
  "customer_date_of_birth": "2000-11-21",
  "customer_email": "example.user@example-email.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "380000000000",
  "fraudulent": true,
  "fail_url": "http://merchant.example/fail",
  "form_name": "wo_cardholder",
  "form_design_name": "promo_christmas",
  "geo_city": "New Castle",
  "geo_country": "GBR",
  "ip_address": "8.8.8.8",
  "language": "en",
  "order_date": "2015-12-21 11:21:30",
  "order_description": "Premium package",
  "order_id": "777",
  "order_items": "item 1, item 2",
  "platform": "WEB",
  "success_url": "http://merchant.example/success",
  "chargeback_notification_url": "http://merchant.example/chargeback",
  "order_number" : 1
}

In the case of the successful response, you will receive a link to the payment form.

Postmessages
After submitting the form and after the order changes its  status,  you receive a postmessage to the parent window, which contains information of the order.

Form Response Sample | 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"
      }
    }
  },
  "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"
  }
}

Resign in iFrame

Iframe for resign-payment is generated according to the following parameters:

Merchant - this is the unique merchant ID, provided to you during the integration process;

Form_Data - encrypted aes-cbc-256 string of JSON request data with random IV and the key is first 16bytes of merchant private key encrypted in АЕС key - first 15 bytes of the private key.

Signature - Signature of request. It allows verifying whether the request from the merchant is genuine on the payment gateway server. In this case, it’s generated not from JSON, but from Form_data.

GET https://pay.solidgate.com/api/v1/form/resign?merchant={merchant_id}&signature={signature}&form_data={form_data}

 

    Resign Form Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idYesstring(100)Order ID specified in the merchant’s system123443334
amountYesintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents1020
currencyYesstring(3)Order currency. 3 letter currency code under ISO-4217USD
recurring_tokenYesstring(255)Card token7ats8da7sd8-a66dfa7-a9s9das89t
order_descriptionYesstring(255)Order description in UTF-8 codePremium package
customer_emailYesstring(100)Customer emailjondou@gmail.com
ip_addressYesstring(50)Customer IP (only public ones)8.8.8.8
platformYesstring(6)Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - applicationWEB
status_urlYesstring(255)URL of the merchant’s page, which customers will be redirected upon 3DS verification on bank end with the status of the operation in URL parameterhttp://merchant.example/status
geo_countryNostring(3)Customer’s country subject to ISO 3166-1 alpha-3GBR
order_dateNostring(50)Date of the order creation in format YYYY-MM-DD-HH-MM-SS2015-12-21 11:21:30
order_itemsNostring(255)Order description in UTF-8 codeitem 1, item 2
customer_account_idNostring(100)Сustomer’s ID specified in the merchant’s system4dad42f808
customer_first_nameNostring(100)Customer’s first nameJohn
customer_last_nameNostring(100)Customer’s last nameSnow
customer_phoneNostring(50)Phone number of the customer380111111111
customer_date_of_birthNostring(50)Birthdate in YYYY-MM-DD format2000-11-21
geo_cityNostring(100)Customer’s CityNew Castle
languageNostring(2)Customer’s language settings. Available values: RU - Russian, EN - Englishen
fraudulentNobooleanCustomer is detected by the merchant’s system to be suspicious one. The payment will be effected via 3DSTRUE
callback_urlNostring(255)URL of the merchant’s page, where response with payment result will be sent via the host-to-host connectionhttp://merchant.example/callback
chargeback_notification_urlNostring(255)URL of the merchant’s page, where the notification of chargeback will be senthttp://merchant.example/chargeback
alert_chargeback_notification_urlNostring(255)URL of the merchant’s page, where the notification of chargeback alerts will be senthttp://merchant.example/chargeback_alerts
verifiedNobooleanA user was verified on the shop sideTRUE
typeNostringThe parameter for transaction-authorizationauth
websiteNostring(255)The website from which transaction took placeGoogle.com
retry_attemptNointegerNumber of retry payment1
traffic_sourceNostring(255)Source of trafficfacebook
transaction_sourceNostring(255)Source of the transactions on the websitemain_menu
user_agentNostringUser-agent of customerMozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36
deviceNostringDevice of customeriPhone 8 iOS 12.0
operating_systemNostringInformation about the operating system of the customer’s deviceiOS
operating_system_versionNostringInformation about the version of the operating system of the customer’s device12
browserNostringInformation about the browser of the customer’s deviceSafari
browser_versionNostringInformation about the version of the browser of the customer’s device12
order_numberNointegerNumber of payments by a user1
force3dsNobooleanRouting payments flag for 3DS flow (enabled by Solid account manager)FALSE
header_acceptYes - 3D 2.0string(255)Header Accepttext/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng
header_accept_languageYes - 3D 2.0string(255)Header Accept-Languageru-RU,ru;q=0.9,en-US;q=0.8
browser_color_depthYes - 3D 2.0integerColour depth of browser window32
browser_screen_heightYes - 3D 2.0integerHeight of browser window1920
browser_screen_widthYes - 3D 2.0integerWidth of the browser window1280
browser_java_enabledYes - 3D 2.0booleanIs java enabled on User's browserFALSE
browser_javascript_enabledYes - 3D 2.0booleanIs javascript enabled on User's browserFALSE
time_zone_offsetYes - 3D 2.0integerThe time difference, in minutes, between UTC time and the local time of the cardholder's browser1

In the case of the successful response, you will receive a short version of the payment form, that requires users only to enter his CVV. 

/media/19/download/7314c2a1-a7b0-4e1c-8bea-99981fb608c1.png?v=1&inline=0