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

PHP SDK

Golang SDK

Kotlin SDK

Python SDK

Node.JS

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.

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.

All requests must be signed. 

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

Request parameters

ParameterMandatoryTypeDescriptionExample
amountYesintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.1020
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 3DS.TRUE
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 - application.WEB
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 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 site.main_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

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
}

Parameters of the successful response

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

Example of successful response

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

Response parameters with error description

meterTypeDescriptionExample
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>arrayArray of error messages relating to the respective attributeThis value should not be blank.

Response sample with information on 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 payments).

All requests must be signed.

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

Request parameters

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

Example of successful response

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

Parameters of unsuccessful response (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. Transaction types are described in respective directory.pay
transactions:<transaction_id>:statusstringTransaction status within the order. Transaction statuses are described in respective directory.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

Example of decline response

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

Response parameters with error description (Validation) 
 

ParameterTypeDescriptionExample
errorobjectObject with information on errors. 
error:codestringError codes list.2.01
error: messagesobjectObject with error list. 
error:messages:<attribute_name>stringAttribute name where error was found.currency
error:messages:<error_message>arrayArray of error messages relating to respective attribute.This value should not be blank.

Example of response with error message

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

Response parameters with the information about the error (Decline Error)

ParameterTypeDescriptionExample
errorobjectObject with the information about the error 
error:codestringError code.2.01
error:typestringType of en error.soft
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"

Example of response with decline error message

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

All requests must be signed.

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.

Parameters of request
 

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
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
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 3DS.TRUE
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 side.TRUE
payment_typeYesstring(25)Type of recurring payment.1-click || retry || recurring
retry_attemptNointegerNumber of retry payment1
traffic_sourceNostring(255)Source of traffic.facebook
transaction_sourceNostring(255)Source of transactions on the website.main_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 place.Google.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 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 the User's browser.FALSE
browser_javascript_enabledYes - 3D 2.0booleanIs javascript enabled on the 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.60

Request sample

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

Parameters of the successful response
 

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

Example success response

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

Request example for Recurring-auth

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

Response example for Recurring-auth

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

Final status example for Recurring-auth

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

Response parameters with error description

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.

Response sample with information on 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."
            ]
        }
    }
}

Response parameters with the information about the error (Decline Error)
 

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

Example of response with decline error message

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

1-click payments + 3DS

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 request - STATUS or from 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.

All requests must be signed.

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

Resign 3DS going through a few steps :

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

verify_url gets by request - STATUS or from NOTIFICATION

Request 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

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

Request sample

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

Parameters of the successful response

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

Example of successful response

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

Response parameters with error description

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 error was foundcurrency
error:messages:<error_message>arrayArray of error messages relating to respective attributeThis value should not be blank.

Example of response with error message

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

Response to method status after method resign
 

ParameterTypeDescriptionExample
orderobjectAn object with information of the transaction. 
order:order_idstringOrder ID specified in the merchant system777
order:statusstringStatus of payment processed. Types of order statuses are described in respective directory.approved
order:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
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 forecasting.2575
order:marketing_currencystringThe currency of the order amount for marketing analytics.USD
order:processing_currencystringThe currency of the order amount for marketing analytics.USD
order:processing_amountintegerThe amount in processing currency2575
order:descriptorstringDescriptorDESCRIPTOR
order:fraudulentbooleanThe customer is detected by the merchant system to be suspicious one.TRUE
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 contatins 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.resign
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>: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 cents.120
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 emitent.STATE 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 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
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

Response on status after resign

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

Request for getting current order status.

All requests must be signed.

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

Request parameters

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

Request sample

{
  "order_id": "123443334"
}

Parameters of the successful response

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 payment processed. Types of order statuses are described in respective directory.created
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

Example success response

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

Example response for 3DS card

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

Response parameters with error description

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 cents.2575
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 forecasting.2575
order:marketing_currencystringThe currency of the order amount for marketing analytics.USD
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 transactions.1495123020887591dc450088f1
transactions:<transaction_id>:idstringTransaction 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>: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:tokenstringCard 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 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

Response sample with information on error

{
  "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 order.

All requests must be signed.

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

Request parameters

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

Request sample

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

Parameters of the successful response

ParameterTypeDescriptionExample
orderobjectObject with information on transactions. 
order:order_idstringOrder ID specified in the merchant system.777
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:descriptorstringDescriptor.DESCRIPTOR
order:fraudulentbooleanThe 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 order amount for marketing analytics.USD
order:processing_amountintegerAmount in processing currency.2575
order: processing_currencystringProcessing currency.USD
order:statusstringStatus of payment processed. Types of statuses are described in respective directories.created
order:refunded_amountintegerThe amount which was refunded.500
order:total_fee_amountintegerTotal fee by order transaction.45
order:fee_currencystringCurrency of order fee.USD
transactionobjectObject with information on the transaction. 
transaction:idstringTransaction identification within the order. Order can have several transactions.1495123020887591dc450088f1
transaction:operationstringTransaction type. Available values - refund.refund
transaction:statusstringTransaction status within the order.created
transaction: descriptorstringDescriptor.DESCRIPTOR
transaction:amountintegerTransaction amount.2575
transaction:currencystringTransaction currency.USD
transaction:refund_reasonstringReason of the refundSystem Error - PSP
transaction:refund_reason_codestringReason code as specified in the refund reason list.12
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 contatins an object with detailed information of specified transaction. Order can have several transactions.1495123020887591dc450088f1
transactions:<transaction_id>:idstringTransaction 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>:descriptorstringDescriptor.DESCRIPTOR
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>: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 list.12
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 BIN.444455
transactions:<transaction_id>:card:brandstringCard brand.VISA
transactions:<transaction_id>:card:numberstringMasked card number.444455XXXXXX6666
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 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

Example success response

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

Response parameters with error description

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 foundamount
error:messages:<error_message>arrayArray of error messages relating to the the respective attributeThis value should not be blank.

Response sample with information on 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.
 

All requests must be signed.

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.

Request parameters

ParameterMandatoryTypeDescriptionExample
order_idYesstring(100)Order ID specified in the merchant system.123443334
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-4217.USD
card_numberYesstring(25)Card number.4111111111111111
card_holderYesstring(32)Cardholder name.JOHN 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 code.123
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
settle_intervalNointegerTime (in hours) after the expiration of which auto-settled is done2
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
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 the 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=approvedhttp://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). 
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

Request sample

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

Parameters of the successful response

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

Example of successful response

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

Response parameters with error description
 

ParameterTypeDescriptionExample
errorobjectAn object with information on errors. 
error:codestringError codes list.2.01
error: messagesobjectAn object with error list. 
error:messages:<attribute_name>stringAttribute name where error was found.currency
error:messages:<error_message>arrayArray of error messages relating to respective attribute.This value should not be blank.

Example of response with error message

{
    "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. 
All requests must be signed.

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 request

Request parameter

 

ParameterMandatoryTypeDescriptionExample
order_idYesstring(100)Order ID specified in the merchant system.123443334
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-4217.USD
card_numberYesstring(25)Card number.4111111111111111
card_holderYesstring(32)Cardholder name.JOHN 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 code.123
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's 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
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 the 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 the operation in the URL parameter.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
verifiedNobooleanThe 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 the website.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.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 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.60

Request sample

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

Parameters of the successful response

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 transactions.15174857081755a72fe8da8ccd
transactions:<transaction_id>:idstringTransactions identification within the order.15174857081755a72fe8da8ccd
transactions:<transaction_id>:operationstringTransaction type. Transaction types are described in respective directory.auth
transactions:<transaction_id>:statusstringTransaction status within the order. Transaction statuses are described in respective directory.success
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:fraudulentbooleanA 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.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.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
transaction:card:card_typestringA type of the card.DEBIT
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

Example of successful response

{
  "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 URL 3DS verification
verify_url is delivered by request - STATUS or from NOTIFICATIONS;

VOID transaction

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

All requests must be signed.

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

Request parameters
 

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

Request sample

{
  "order_id": "123443334"
}

Parameters of the successful response

 

ParameterTypeDescriptionExample
orderobjectAn object with information of the transaction. 
order:order_idstringOrder ID specified in the merchant system.1517501959601
order:statusstringStatus of payment processed. Types of order statuses are described in respective directory.void_ok
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:descriptorstringDescriptor.DESCRIPTOR
order:fraudulentbooleanA 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_amountintegerAmount of order for marketing analytics.2575
order:processing_currencystringProcessing amount of order.USD
order:total_fee_amountintegerTotal fee by order transaction.120
order:fee_currencystringThe currency of the order fee.USD
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 transactions.15175019596015a733f7a4f91a
transactions:<transaction_id>:idstringTransactions identification within the order.15175019596015a733f7a4f91a
transactions:<transaction_id>:operationstringTransaction type. Transaction types are described in respective directory.void
transactions:<transaction_id>:statusstringTransaction status within the order. Transaction statuses are described in respective directory.success
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 cents.2575
transactions:<transaction_id>:currencystringTransactions currency.USD
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 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)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 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.86c1b0416c3...e2c99a20
transactionobjectAn object with information on the transaction. 
transaction:idstringTransaction identification within the order. The order can have several transactions.00016857481e16b07fc
transaction:operationstringTransaction type.void
transaction: statusstringTransaction status within the order.created
transaction: descriptorstringDescriptor.DESCRIPTOR
transaction:amountintegerTransaction amount.2575
transaction:currencystringTransaction currency.USD
transaction:created_atstringTransaction created DateTime2019-05-17 09:06:21
transaction:updated_atstringTransaction updated DateTime2019-05-17 09:06:21

Example success response

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

Response parameters with error description

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

Example of response with error message

{
  "error": {
    "code": "2.01",
    "messages": {
      "system": [
        "Invalid data for request"
      ]
    }
  }
}

SETTLE transaction

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

All requests must be signed.

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

Request 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 cents.2575

If SETTLE amount is less than AUTH one - the difference will be sent back to the user.

Request sample

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

Parameters of the successful response

ParameterTypeDescriptionExample
orderobjectAn object with information of the transaction. 
order:order_idstringOrder ID specified in the merchant system.1517502021714
order:statusstringStatus of payment processed. Types of order statuses are described in the  respective directory.settle_ok
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:descriptorstringDescriptor.DESCRIPTOR
order:fraudulentbooleanA 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_amountintegerAmount of order for marketing analytics.2575
order:processing_currencystringProcessing amount of order.USD
order:total_fee_amountintegerTotal fee by order transaction.120
order:fee_currencystringThe currency of the order fee.USD
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 transactions.15175020217145a73465797e66
transactions:<transaction_id>:idstringTransactions identification within the order.15175020217145a73465797e66
transactions:<transaction_id>:operationstringTransaction type. Transaction types are described in the respective directory.settle
transactions:<transaction_id>:statusstringTransaction status within the order. Transaction statuses are described in the respective directory.success
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 cents.2575
transactions:<transaction_id>:currencystringTransactions currency.USD
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 cents.120
transactions:<transaction_id>:fee:currencystringCurrency of transaction fee - 3-digit letter code under ISO 4217.USD
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)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 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.d89f0b146fdffd...98b6d5d076
transactionobjectAn object with information on the transaction. 
transaction:idstringTransaction identification within the order. The order can have several transactions.15175020217145a73465797e66
transaction:operationstringTransaction type.settle
transaction:statusstringTransaction status within the order.created
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 cents.31
transaction:fee:currencystringThe currency of transaction fee - 3-digit letter code under ISO 4217.USD

Example success response

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

Response parameters with error description

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.

Example of response with error message

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

Request parameters

ParameterMandatoryTypeDescriptionExample
order_idYesstring(255)Order ID specified in the merchant system.123443334

ARN is available only if the order status is refunded.

Request sample

{
  "order_id": "123443334"
}

Parameters of the successful response
 

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 transaction.74208328039016341469667
arn_codes:amount_refundedintegerOrder amount - integer without fractional components (i.e cents). For instance, 1020 means 10 USD and 20 cents.1020
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 directory.success
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 system.2045
arn_codes:created_atstringDate and time of refund performed on the PSP end.2018-02-07 12:42:09

Example of successful response


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

Example of successful response 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
}

Response parameters with error description

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


 

Example of response with error message


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

Request parameters

ParameterMandatoryTypeDescriptionExample
amountYesintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.1020
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 3DS.TRUE
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 - application.WEB
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 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 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

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.

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

Request parameters
<!--td {border: 1px solid #ccc;}br {mso-data-placement:same-cell;}-->

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 cents.1020
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 - application.WEB
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 3DS.TRUE
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 sent.http://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 side.TRUE
typeNostringThe parameter for transaction-authorizationauth
websiteNostring(255)The website from which transaction took place.Google.com
retry_attemptNointegerNumber of retry payment1
traffic_sourceNostring(255)Source of traffic.facebook
transaction_sourceNostring(255)Source of the 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’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 Accept.text/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

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.