Alt Payments [PayPal, Sofort, iDeal, Boleto, PaySMS etc.]

SolidGate is a unique gateway for online payments. Both means of payment are available: cards and alternative payment methods such as bank transfers, USSD, Boleto etc.

Simple integration gets an opportunity to start working at once.

SolidGate integration steps

In order to start, you need the following:

- Merchant ID

- Secret Key for signing requests

The parameters are sent by POST method in the request body. The JSON format is applicable.

API Endpoint URL - https://gate.solidgate.com/api/v1/

SolidGate authorization

The authorisation is required for transmitting requests to SolidGate. It can be performed by signing each client's request to API. Merchant ID and its secret key shall be applied in order to calculate the signature.

Headers of each request are to be placed in the following additional fields:

Parameter	Description	Example
Merchant	Unique merchant ID. It is shared at the moment of registration	Test_Merchant
Signature	Signature of request. It allows you to verify whether the request from the merchant is genuine on the payment gateway server	MjNiYjVj…ZhYmMxMzNiZDY=

Signature creation

Value of a signature is base64-coding of hash function SHA-512. As for encryption key, merchant's secret key shall be applied.

As for signature data, the following string shall be used:

merchantId + requestJsonData + merchantId

where

merchantId - unique merchant identification,
requestJsonData - request body (JSON string).

Signature Creation Sample | PHP-language
                                    /**
* @param string $data
* @return string
*/
private function generateSignature($data)
{
   return base64_encode(
       hash_hmac('sha512',
           $this->getMerchantId() . $data . $this->getMerchantId(),
           $this->getPrivateKey())
   );
}
                                

data - request body (JSON string)
merchantId - unique merchant identification
privateKey - secret code for request signature. It's provided at the moment of merchant registration.

SolidGate methods

Init Payment - operation of order initiating. This performs order creation and transaction is ready for payment.
Status - request for receiving current order status.
Refund - request for transferring funds back. Refunds are available for successfully paid orders. Only one refund can be effected per order.
Invoice - request to create order and generate Invoice number.

SolidGate Init-Payment

Operation of order initiating. It shall be used while working with a payment form.

This operation deems to create order in the system and return token being applied while calling payment form.

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

Init Payment Request Body Parameters

Parameter	Mandatory	Type	Description	Value sample
amount	Yes	Integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	1020
currency	Yes	String(3)	Order currency. 3 letter currency code under ISO-4217	USD
payment_method	No	String	Payment method ( "przelewy24", "trustly", "bancontact", "giropay", "paysafecard", "sepa", "sofort", "ideal", "paypal", "yandex_money", "dcb", "paysms", "alipay")	paypal
payment_type_data	No	Object	Object with payment type data
payment_type_data:phone	No	String	The phone number for Mobile Carrier Billing (paysms)
payment_type_data:cpf	No	String	CPF - individual taxpayer registry identification, a number attributed by the Brazilian Federal Revenue. Mandatory for method boleto	42243309114
customer_account_id	No	String	Customer ID in the merchant's system. In case of successful payment, card data will be tied to this ID	4dad42f808
customer_date_of_birth	No	String	Customer birth date in format YYYY-MM-DD	2000-11-21
customer_email	Yes	String	Customer email	jondou@gmail.com
customer_first_name	No	String	Customer's first name	John
customer_last_name	No	String	Customer last name	Snow
customer_phone	No/Yes	String	Customer telephone (Mandatory for locations: UGA, KEN, TZA, GHA)	380111111111
geo_country	No/Yes	String(3)	Customer country. Code shall be in ISO 3166-1 alpha-3 format. (Mandatory for method PayPal)	GBR
geo_city	No	String	Customer city	New Castle
ip_address	Yes	String	Customer IP (only public ones)	8.8.8.8
language	No	String(2)	Customer language settings. Available values: RU - Russian, EN - English	en
order_id	Yes	String	Order ID specified in merchant system	123443334
order_date	No	String	Date of order creation in format YYYY-MM-DD-HH-MM-SS	2015-12-21 11:21:30
order_description	Yes	String	Order description in UTF-8 code	Premium package
platform	Yes	String	Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application	WEB
callback_url	No	String	URL of merchant page, where response with payment result will be sent	http://merchant.example/callback
return_url	Yes	String	URL of merchant page, to which a customer will be redirected after payment is complete	http://merchant.example/return
success_url	Yes	String	URL of merchant page, to which a customer will be redirected after success payment	http://merchant.example/success
fail_url	Yes	String	URL of merchant page, to which a customer will be redirected after unsuccess payment	http://merchant.example/fail

Init Payment Request Sample
                                    
{
  "amount": 2575,
  "payment_method": "paypal",
  "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",
  "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",
  "platform": "WEB"
}
                                

Init Payment Response Body Parameters

Parameter	Type	Description	Value sample
order	Object	Object with information of the order
order: order_id	String	Order ID specified in merchant system	777
order: amount	Integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.	2575
order: currency	String	Order currency (3 letter code under ISO 4217)	USD
order: status	String	Order status	created
pay_form	Object	Object with data payment form data
pay_form: token	String	Payment form token	5849cf0468afc0ac4be4963c619b776eee75271d56e3c6621ab21
pay_form: return_url	String	URL of merchant page, to which a customer will be redirected to complete a payment	https://www.paypal.com/ca/cgi-bin/merchantpaymentweb?cmd=_express-checkout&token=EC-1LX20314LJ600731B
payment_type_data	Object
payment_type_data:id	String	Ticket id	109/18369953-0
payment_type_data:number	String	Ticket number	34191091803699530044354689940002780050000015476
payment_type_data:expiration_date	String	Ticket expiration date	2019-09-08T02:59:00+0000
payment_type_data:barcode	String	Ticket barcode	34197800500000154761091836995300445468994000

Init Payment Response Body | Success
                                    {
 "order": {
 "amount": 5000,
 "currency": "USD",
  "order_id": "1504269591134TEST",
  "status": "created"
  },
 "pay_form": {
 "token": "6de603708b5b4c33a681dc1e47b20ad3",
 "return_url": "https://www.paypal.com/ca/cgi-bin/merchantpaymentweb?cmd=_express-checkout&amp;token=EC-1LX20314LJ601741A"
  }
}
                                

Init Payment Response Body Parameters | Error

Parameter	Type	Description	Example
error	Object	Object with information on error
error:code	String	Error codes list	2.01
error: messages	Object	Error messages
error: messages:attribute_name	String	Attribute name where an error was found	currency
error: messages:error_message	Array	The array of error messages relating to the respective attribute	This value should not be blank.

 Init Payment Response Body | Error
                                    {
  "error": {
    "code": "2.01",
    "messages": {
      "currency": [
        "Invalid Currency."
      ]
    }
  }
}
                                

SolidGate Init-Payment PayPal

Operation of order initiating. It shall be used while working with a payment widget.

This operation deems to create order in the system and return token being applied while calling payment widget.

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

Init Payment Request Body Parameters | PayPal

Parameter	Mandatory	Type	Description	Value sample
amount	Yes	Integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.	1020
currency	Yes	String(3)	Order currency. 3 letter currency code under ISO-4217	USD
payment_method	No	String	Payment method ( "przelewy24", "trustly", "bancontact", "giropay", "paysafecard", "sepa", "sofort", "ideal", "paypal", "yandex_money", "dcb", "paysms", "alipay")	paypal
payment_type_data	No	Object	Object with payment type data
payment_type_data:phone	No	String	The phone number for Mobile Carrier Billing (paysms)
payment_type_data:cpf	No	String	CPF - individual taxpayer registry identification, a number attributed by the Brazilian Federal Revenue. Mandatory for boleto payment method	42243309114
customer_account_id	No	String	Customer ID in the merchant's system. In case of successful payment, card data will be tied to this ID.	4dad42f808
customer_date_of_birth	No	String	Customer birth date in format YYYY-MM-DD	2000-11-21
customer_email	Yes	String	Customer email	jondou@gmail.com
customer_first_name	No	String	Customer's first name	John
customer_last_name	No	String	Customer last name	Snow
customer_phone	No/Yes	String	Customer telephone (Mandatory for locations: UGA, KEN, TZA, GHA)	380111111111
geo_country	No/Yes	String(3)	Customer country. Code shall be in ISO 3166-1 alpha-3 format. (Mandatory for method PayPal)	GBR
geo_city	No	String	Customer city	New Castle
ip_address	Yes	String	Customer IP (only public ones)	8.8.8.8
language	No	String(2)	Customer language settings. Available values: RU - Russian, EN - English	en
order_id	Yes	String	Order ID specified in merchant system	123443334
order_date	No	String	Date of order creation in format YYYY-MM-DD-HH-MM-SS	2015-12-21 11:21:30
order_description	Yes	String	Order description in UTF-8 code	Premium package
platform	Yes	String	Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application.	WEB
callback_url	No	String	URL of merchant page, where response with payment result will be sent	http://merchant.example/callback
return_url	Yes	String	URL of merchant page, to which a customer will be redirected after payment is complete	http://merchant.example/return
success_url	Yes	String	URL of merchant page, to which a customer will be redirected after success payment	http://merchant.example/success
fail_url	Yes	String	URL of merchant page, to which a customer will be redirected after unsuccess payment	http://merchant.example/fail

Init Payment Request Body | PayPal
                                    {
  "amount": 2575,
  "payment_method": "paypal",
  "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",
  "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",
  "platform": "WEB"
}
                                

Init Payment Response Body Parameters | PayPal

Parameter	Type	Description	Value sample
order	Object	Object with information of the order
order: order_id	String	Order ID specified in merchant system	777
order: amount	Integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	2575
order: currency	String	Order currency (3 letter code under ISO 4217)	USD
order: status	String	Order status	created
pay_form	Object	Object with data payment form data
pay_form: token	String	Payment form token	5849cf0468afc0ac4be4963c619b776eee75271d56e3c6621ab21
pay_form: return_url	String	URL of merchant page, to which a customer will be redirected to complete a payment	https://www.paypal.com/ca/example-url
payment_type_data	Object
payment_type_data:id	String	Ticket id	109/18369953-0
payment_type_data:number	String	Ticket number	34191091803699530044354689940002780050000015476
payment_type_data:expiration_date	String	Ticket expiration date	2019-09-08T02:59:00+0000
payment_type_data:barcode	String	Ticket barcode	34197800500000154761091836995300445468994000

Init Payment Response Body | PayPal Success
                                    {
 "order": {
 "amount": 5000,
 "currency": "USD",
  "order_id": "1504269591134TEST",
  "status": "created"
  },
 "pay_form": {
 "token": "6de603708b5b4c33a681dc1e47b20ad3",
 "return_url": "https://www.paypal.com/ca/cgi-bin/merchantpaymentweb?cmd=_express-checkout&token=EC-1LX20314LJ601741A"
  } 
}
                                

Init Payment Response Body Parameters | PayPal with Error

Parameter	Type	Description	Example
error	Object	Object with information on error
error:code	String	Error codes list	2.01
error: messages	Object	Error messages
error: messages:attribute_name	String	Attribute name where an error was found	currency
error: messages:error_message	Array	The array of error messages relating to the respective attribute	This value should not be blank.

Init Payment Response Body | PayPal with Error
                                    {
  "error": {
    "code": "2.01",
    "messages": {
      "currency": [
        "Invalid Currency."
      ]
    }
  }
}

                                

SolidGate Init-Payment AliPay

Operation of order initiating. It shall be used while working with a payment widget.

This operation deems to create order in the system and return token being applied while calling a payment widget.

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

Init Payment Request Body Parameters | AliPay

Parameter	Mandatory	Type	Description	Value sample
amount	Yes	Integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	1020
currency	Yes	String(3)	Order currency. 3 letter currency code under ISO-4217	USD
payment_method	No	String	Payment method ( "przelewy24", "trustly", "bancontact", "giropay", "paysafecard", "sepa", "sofort", "ideal", "paypal", "yandex_money", "dcb", "paysms", "alipay")	AliPay
payment_type_data	No	Object	Object with payment type data
payment_type_data:phone	No	String	Phone number	380000000000
customer_account_id	No	String	Customer ID in the merchant's system. In case of successful payment, card data will be tied to this ID	4dad42f808
customer_date_of_birth	No	String	Customer birth date in format YYYY-MM-DD	2000-11-21
customer_email	Yes	String	Customer email	jondou@gmail.com
customer_first_name	No	String	Customer's first name	John
customer_last_name	No	String	Customer last name	Snow
customer_phone	No/Yes	String	Customer telephone (Mandatory for locations: UGA, KEN, TZA, GHA)	380111111111
geo_country	No/Yes	String(3)	Customer country. Code shall be in ISO 3166-1 alpha-3 format. (Mandatory for method PayPal)	GBR
geo_city	No	String	Customer city	New Castle
ip_address	Yes	String	Customer IP (only public ones)	8.8.8.8
language	No	String(2)	Customer language settings. Available values: RU - Russian, EN - English	en
order_id	Yes	String	Order ID specified in merchant system	123443334
order_date	No	String	Date of order creation in format YYYY-MM-DD-HH-MM-SS	2015-12-21 11:21:30
order_description	Yes	String	Order description in UTF-8 code	Premium package
platform	Yes	String	Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application	WEB
callback_url	No	String	URL of merchant page, where response with payment result will be sent	http://merchant.example/callback
return_url	Yes	String	URL of merchant page, to which a customer will be redirected after payment is complete	http://merchant.example/return
success_url	Yes	String	URL of merchant page, to which a customer will be redirected after success payment	http://merchant.example/success
fail_url	Yes	String	URL of merchant page, to which a customer will be redirected after unsuccess payment	http://merchant.example/fail

Init Payment Request Sample | AliPay
                                    {
  "amount": 2575,
  "payment_method": "A",
  "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",
  "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",
  "platform": "WEB"
}
                                

Init Payment Response Body Parameters | AliPay

Parameter	Type	Description	Value sample
order	Object	Object with information of the order
order: order_id	String	Order ID specified in merchant system	777
order: amount	Integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	2575
order: currency	String	Order currency (3 letter code under ISO 4217)	USD
order: status	String	Order status	created
pay_form	Object	Object with data payment form data
pay_form: token	String	Payment form token	5849cf0468afc0ac4be4963c619b776eee75271d56e3c6621ab21
pay_form: return_url	String	URL of merchant page, to which a customer will be redirected to complete a payment	https://www.returnurl.com
payment_type_data	Object
payment_type_data:id	String	Ticket id	109/18369953-0
payment_type_data:number	String	Ticket number	34191091803699530044354689940002780050000015476
payment_type_data:expiration_date	String	Ticket expiration date	2019-09-08T02:59:00+0000
payment_type_data:barcode	String	Ticket barcode	34197800500000154761091836995300445468994000

    Init Payment Response Sample | AliPay
                                    {
 "order": {
 "amount": 5000,
 "currency": "USD",
  "order_id": "1504269591134TEST",
  "status": "created"
  },
 "pay_form": {
 "token": "6de603708b5b4c33a681dc1e47b20ad3",
 "return_url": "https://www.returnurl.com"
  } 
}
                                

Init Payment Response Body Parameters | AliPay with Error

Parameter	Type	Description	Example
error	Object	Object with information on error
error:code	String	Error codes list	2.01
error: messages	Object	Error messages
error: messages:attribute_name	String	Attribute name where an error was found	currency
error: messages:error_message	Array	The array of error messages relating to the respective attribute	This value should not be blank

Init Payment Response Sample | AliPay with Error
                                    {
  "error": {
    "code": "2.01",
    "messages": {
      "currency": [
        "Invalid Currency."
      ]
    }
  }
}
                                

SolidGate Init-Payment Sofort

Operation of order initiating. It shall be used while working with a payment widget.

This operation deems to create order in the system and return token being applied while calling payment widget.

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

Init Payment Request Body Parameters | Sofort

Parameter	Mandatory	Type	Description	Value sample
amount	Yes	Integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	1020
currency	Yes	String(3)	Order currency. 3 letter currency code under ISO-4217	USD
payment_method	No	String	Payment method ( "przelewy24", "trustly", "bancontact", "giropay", "paysafecard", "sepa", "sofort", "ideal", "paypal", "yandex_money", "dcb", "paysms", "alipay")	Sofort
payment_type_data	No	Object	Object with payment type data
payment_type_data:phone	No	String	Phone number	380000000000
customer_account_id	No	String	Customer ID in the merchant's system. In case of successful payment, card data will be tied to this ID	4dad42f808
customer_date_of_birth	No	String	Customer birth date in format YYYY-MM-DD	2000-11-21
customer_email	Yes	String	Customer email	jondou@gmail.com
customer_first_name	No	String	Customer's first name	John
customer_last_name	No	String	Customer last name	Snow
customer_phone	No/Yes	String	Customer telephone (Mandatory for locations: UGA, KEN, TZA, GHA)	380111111111
geo_country	No/Yes	String(3)	Customer country. Code shall be in ISO 3166-1 alpha-3 format. (Mandatory for method PayPal)	GBR
geo_city	No	String	Customer city	New Castle
ip_address	Yes	String	Customer IP (only public ones)	8.8.8.8
language	No	String(2)	Customer language settings. Available values: RU - Russian, EN - English	en
order_id	Yes	String	Order ID specified in merchant system	123443334
order_date	No	String	Date of order creation in format YYYY-MM-DD-HH-MM-SS	2015-12-21 11:21:30
order_description	Yes	String	Order description in UTF-8 code	Premium package
platform	Yes	String	Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application	WEB
callback_url	No	String	URL of merchant page, where response with payment result will be sent	http://merchant.example/callback
return_url	Yes	String	URL of merchant page, to which a customer will be redirected after payment is complete	http://merchant.example/return
success_url	Yes	String	URL of merchant page, to which a customer will be redirected after success payment	http://merchant.example/success
fail_url	Yes	String	URL of merchant page, to which a customer will be redirected after unsuccess payment	http://merchant.example/fail

 Init Payment Request Sample | Sofort
                                    {
  "amount": 2575,
  "payment_method": "Sofort",
  "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",
  "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",
  "platform": "WEB"
}
                                

Init Payment Response Body Parameters | Sofort

Parameter	Type	Description	Value sample
order	object	Object with information of the order
order: order_id	string	Order ID specified in merchant system	777
order: amount	integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	2575
order: currency	string	Order currency (3 letter code under ISO 4217)	USD
order: status	string	Order status	created
pay_form	object	Object with data payment form data
pay_form: token	string	Payment form token	5849cf0468afc0ac4be4963c619b776eee75271d56e3c6621ab21
pay_form: return_url	string	URL of merchant page, to which a customer will be redirected to complete a payment	https://www.returnurl.com
payment_type_data	object
payment_type_data:id	string	Ticket id	109/18369953-0
payment_type_data:number	string	Ticket number	34191091803699530044354689940002780050000015476
payment_type_data:expiration_date	string	Ticket expiration date	2019-09-08T02:59:00+0000
payment_type_data:barcode	string	Ticket barcode	34197800500000154761091836995300445468994000

 Init Payment Response Sample | Sofort 
                                    {
 "order": {
 "amount": 5000,
 "currency": "USD",
  "order_id": "1504269591134TEST",
  "status": "created"
  },
 "pay_form": {
 "token": "6de603708b5b4c33a681dc1e47b20ad3",
 "return_url": "https://www.returnurl.com"
  } 
}
                                

Init Payment Response Body Parameters | Sofort with Error

Parameter	Type	Description	Example
error	Object	Object with information on error
error:code	String	Error codes list	2.01
error: messages	Object	Error messages
error: messages:attribute_name	String	Attribute name where an error was found	currency
error: messages:error_message	Array	The array of error messages relating to the respective attribute	This value should not be blank

 Init Payment Response Sample | Sofort with Error
                                    {
  "error": {
    "code": "2.01",
    "messages": {
      "currency": [
        "Invalid Currency."
      ]
    }
  }
}
                                

SolidGate Init-Payment iDeal

Operation of order initiating. It shall be used while working with a payment widget.

This operation deems to create order in the system and return token being applied while calling a payment widget.

The current flow of work with iDeal goes as follows:

User is presented with bank selection. Merchant will match bank and BIC;
The merchant sends init-request to Solid. It should contain all mandatory fields (BIC, etc…);
In response, Solid provides a URL of the payment page;
The merchant provides the redirect_page for a user with iDeal payment form;
User will execute payment or decline it;
After this, he will return to success or fail URL, in response to the status of the transaction.

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

Request parameters

Parameter	Mandatory	Type	Description	Value sample
amount	Yes	Integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.	1020
currency	Yes	String(3)	Order currency. 3 letter currency code under ISO-4217 EUR only	EUR
payment_method	No	String	Payment method ( "przelewy24", "trustly", "bancontact", "giropay", "paysafecard", "sepa", "sofort", "ideal", "paypal", "yandex_money", "dcb", "paysms", "alipay")	ideal
payment_type_data	Yes	Object	Object with payment type data
payment_type_data:bic	Yes	String	A BIC code is an international bank code that identifies particular banks worldwide.	ABNANL2A
payment_type_data:phone	No	String	Phone number.	380000000000
customer_account_id	No	String	Customer ID in the merchant's system. In case of successful payment, card data will be tied to this ID.	4dad42f808
customer_date_of_birth	No	String	Customer birth date in format YYYY-MM-DD	2000-11-21
customer_email	Yes	String	Customer email	jondou@gmail.com
customer_first_name	No	String	Customer's first name	John
customer_last_name	No	String	Customer last name	Snow
customer_phone	No/Yes	String	Customer telephone (Mandatory for locations: UGA, KEN, TZA, GHA)	380111111111
geo_country	No/Yes	String(3)	Customer country. Code shall be in ISO 3166-1 alpha-3 format. (Mandatory for method PayPal)	GBR
geo_city	No	String	Customer city	New Castle
ip_address	Yes	String	Customer IP (only public ones)	8.8.8.8
language	No	String(2)	Customer language settings. Available values: RU - Russian, EN - English	en
order_id	Yes	String	Order ID specified in merchant system	123443334
order_date	No	String	Date of order creation in format YYYY-MM-DD-HH-MM-SS	2015-12-21 11:21:30
order_description	Yes	String	Order description in UTF-8 code	Premium package
platform	Yes	String	Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application.	WEB
callback_url	No	String	URL of merchant page, where response with payment result will be sent	http://merchant.example/callback
return_url	Yes	String	URL of merchant page, to which a customer will be redirected after payment is complete	http://merchant.example/return
success_url	Yes	String	URL of merchant page, to which a customer will be redirected after success payment	http://merchant.example/success
fail_url	Yes	String	URL of merchant page, to which a customer will be redirected after unsuccess payment	http://merchant.example/fail

Request sample
                                    {
  "amount": 2575,
  "payment_method": "ideal",
  "payment_type_data": {
    "bic": "ABNANL2A"
  },
  "callback_url": "http://merchant.example/callback",
  "currency": "EUR",
  "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",
  "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",
  "platform": "WEB"
}
                                

Parameters of the successful response

Parameter	Type	Description	Value sample
order	Object	Object with information of the order
order: order_id	String	Order ID specified in merchant system	777
order: amount	Integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.	2575
order: currency	String	Order currency (3 letter code under ISO 4217) EUR only	EUR
order: status	String	Order status	created
pay_form	Object	Object with data payment form data
pay_form: token	String	Payment form token	5849cf0468afc0ac4be4963c619b776eee75271d56e3c6621ab21
pay_form: return_url	String	URL of merchant page, to which a customer will be redirected to complete a payment	https://www.returnurl.com
payment_type_data	Object
payment_type_data:id	String	Ticket id	109/18369953-0
payment_type_data:number	String	Ticket number	34191091803699530044354689940002780050000015476
payment_type_data:expiration_date	String	Ticket expiration date	2019-09-08T02:59:00+0000
payment_type_data:barcode	String	Ticket barcode	34197800500000154761091836995300445468994000

Parameters of the successful response
                                    {
 "order": {
 "amount": 5000,
 "currency": "EUR",
  "order_id": "1504269591134TEST",
  "status": "created"
  },
 "pay_form": {
 "token": "6de603708b5b4c33a681dc1e47b20ad3",
 "return_url": "https://www.returnurl.com"
  } 
}
                                

Example of response with information about an error

Parameter	Type	Description	Example
error	Object	Object with information on error
error:code	String	Error codes list	2.01
error: messages	Object	Error messages
error: messages:attribute_name	String	Attribute name where an error was found	currency
error: messages:error_message	Array	The array of error messages relating to the respective attribute	This value should not be blank.

Response sample with information about the error
                                    {
  "error": {
    "code": "2.01",
    "messages": {
      "currency": [
        "Invalid Currency."
      ]
    }
  }
}
                                

List of available BIC providers

Issuer’s name	BIC
ABN AMRO	ABNANL2A
ASN Bank	ASNBNL21
bunq	BUNQNL2A
Handelsbanken	HANDNL2A
ING	INGBNL2A
Knab	KNABNL2H
Moneyou	MOYONL21
Rabobank	RABONL2U
RegioBank	RBRBNL21
SNS	SNSBNL2A
Triodos Bank	TRIONL2U
Van Lanschot	FVLBNL22

SolidGate payment form

Payment widget should be shown to the customer can enter payment data. In order to pay the order, the following action should be:

Widget rendering

Payment widget should be rendered on HTML (for mobile apps Webview is applicable). "Token" data received from init-payment response shall be used.

HTML-tag script shall be created with attributes from widget key in order to switch widget on. Data-btn-id shall not be used. The received token shall be specified in field SCR.

Code samle
                                    src="https://gate.solid.com/widget/c27f5cfc68da4123968d4118c9940e76"
<script type="text/javascript" src="{widget.src}"
data-script="{widget.data-script}"
data-title="{widget.data-title}"
data-description="{widget.data-description}">
</script>
                                

Example
                                    
<script type="text/javascript"
src="http://gate.solid.com/widget/dccad90d23254c129afaf64545c7e13c"
data-script=" "    
data-btn-id="solid_pay_btn"
data-overlay="true"     
data-tittle="Tittle for payment widget"    
data-description="widget.data-description">
</script>
                                

data-script = "btn_script" - mandatory parameter to search script
data-btn-id = "solid_pay_btn" - ID buttons which call the widget. If the parameter is not specified, a green button with text "PAY" will be created in order to call widget.
data-overlay = "true" - parameter to call dark background for the open widget. If the parameter is not specified, there will be no background.
data-title="Title for payment widget" - header parameter
data-description="Boost premium" - service name for which you get paid
In this case, we receive standard button "PAY" resulting in the widget to be open

Event

document.addEventListener('closeWidget') - event for widget closing;

openWidget - event for widget opening. Parameter 'widgetHeight' transmits the widget height before opening;

payment - event for payment which transmits the information with regards to payment status (approved or declined).

SolidGate - One-click payments

One-click payments are linked to “customer_account_id” value. If the customer with particular "customer_account_id" made successful payments, while widget rendering a partial card number will be seen in order to make the one-click payment or enter a new card.

/media/22/download/image%20%283%29.webp?v=1&inline=0

SolidGate Refund

This is a request for transferring funds back to the cardholder.

Refunds are applicable only for successful orders.

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

Request Body Parameters

Parameter	Mandatory	Type	Description	Value sample
order_id	Yes	string(255)	Order ID specified in merchant system	777
amount	Yes	integer	Refund amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	2575

Request sample
                                    {
  "order_id": "1511285499878WIDGET",
  "amount": 2000
}
                                

Response Body Parameters

Parameter	Type	Description	Example
order	object	Object with information about the order
order: order_id	string	Order ID specified in merchant system	777
order: amount	integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	2575
order: currency	string	Order currency. 3 letter currency code under ISO-4217	NGN
order: status	string	Transaction status	refunded
order: method	string	Payment method	solid-cards
order:processing_amount	string	Amount in processing currency	2575
order: processing_currency	string	Processing currency	NGN
pay_form	object
pay_form: token	string	Card token being applied for recurring payments. It's returned in case of successful payment	4056cd8cccf96...40015a997d74
card_token	object
card_token:token	string	Card token being applied for recurring payments. It's returned in case of successful payment	ae7ab1407317e77d9d1002cb41512c5e15def5d8b1
card_token: card_number	string	Card number in an encrypted format	453245XXXXXX2692
card_token: card_brand	string	Card brand	VISA
card_token: card_country	string	Country of card origin	NGN
card_token: card_bank	string	Issuing bank	CITIZENS STATE BANK
transactions	object
transactions: status	string	Transaction status	approved
transactions: method	string	Payment method	solid-cards
transactions: amount	string	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	2575
transactions: currency	string	Order currency. 3 letter currency code under ISO-4217	NGN
transactions: type	string	Type of transaction	refund

Successful response sample
                                    {
  "order": {
    "amount": 2575,
    "currency": "NGN",
    "order_id": "777",
    "status": "refunded",
    "method": "solid-cards",
    "processing_amount": "2575",
    "processing_currency": "NGN"
  },
  "card_token": {
    "token": "8a50381475ef122ed870dceb3b378cc976a53d1cbe92cdcdeaae7ec6c4e1659e1440c232d924b8a57645a2b56b4d099180bb",
    "card_number": "453245XXXXXX2692",
    "card_brand": "VISA",
    "card_country": "USA",
    "card_bank": "CITIZENS STATE BANK"
  },
  "pay_form": {
    "token": "2cf4d230f79943a49d695091bb919268"
  },
  "transactions": [
    {
      "status": "approved",
      "method": "solid-cards",
      "amount": 2575,
      "currency": "NGN",
      "type": "pay"
    },
    {
      "status": "refunded",
      "method": "solid-cards",
      "amount": 2575,
      "currency": "NGN",
      "type": "refund"
    }
  ]
}
                                

Response sample with information about the error
                                    
{
  "error": {
    "code": "2.01",
    "messages": {
      "amount": [
        "This value should be greater than or equal to 1."
      ]
    }
  }
}

                                

SolidGate - Cash Invoice Payments

Operation of invoice creation. It's applied to pay cash at the bank branch.

This operation creates order in the system. Invoice is generated and linked to the order. Payment details are returned on bank end.

POST https://gate.solidgate.com/api/v1/invoice

Request parameters

Parameter	Mandatory	Type	Description	Value sample
amount	Yes	integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	1020
currency	Yes	string(3)	Order currency. 3 letter currency code under ISO-4217	USD
customer_account_id	No	string(100)	Customer ID specified in the merchant system. Card data are linked to this field if the payment is successful	4dad42f808
customer_date_of_birth	No	string(50)	Customer birthday in format YYYY-MM-DD	2000-11-21
customer_email	Yes	string(100)	Customer email	jondou@gmail.com
customer_first_name	No	string(100)	Customer first name	John
customer_last_name	No	string(100)	Customer last name	Snow
customer_phone	No	string(50)	Customer phone	380111111111
geo_country	No	string(3)	Customer country. The code in the format under ISO 3166-1 alpha-3	GBR
geo_city	No	string(100)	Customer city	New Castle
ip_address	Yes	string(50)	Customer IP (only public ones)	8.8.8.8
language	No	string(2)	Customer language settings. Available values: RU - Russian, EN - English	en
order_id	Yes	string(255)	Order ID specified in the merchant system	123443334
order_date	No	string(50)	Date of creation order in format YYYT-MM-DD-MM-SS	2015-12-21 11:21:30
order_description	Yes	string(255)	Order description in UTF-8 code	Premium package
platform	Yes	string(6)	Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application	WEB
callback_url	No	string(255)	URL of merchant page, where response with payment result will be sent	http://merchant.example/callback

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",
  "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",
  "platform": "WEB"
}
                                

Successful response samples

Parameter	Type	Description	Value Sample
order	object	Object with information about the order
order: order_id	integer	Order ID specified in the merchant system	777
order: amount	integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	2575
order: currency	string	Order currency. 3 letter currency code under ISO-4217	USD
order: status	string	Transaction status	created
order: method	string	Payment method	invoice
invoice	object	Object with information about the invoice
invoice: invoice_number	string	Invoice number	52120039560
invoice: invoice_merchant	string	Merchant to whom the payment is assigned	merchant
invoice: email	string	Customer email to be indicated in payment details	john.snow@gmail.com

Response sample for successful payment
                                    {
  "order": {
    "amount": 1500,
    "currency": "NGN",
    "order_id": 1511189076,
    "status": "created",
    "method": "invoice"
  },
  "invoice": {
    "invoice_number": "52120039560",
    "invoice_merchant": "merchant",
    "email": "example.user@example-email.com"
  }
}
                                

Successful response sample | Status method applied

Parameter	Type	Description	Example
order	object	Object with information about the order
order: amount	integer	Order amount	25000
order: currency	string	Order currency	NGN
order: order_id	string	Order ID specified in the merchant system	151134992549
order: status	string	Transaction status	approved
order: method	string	Payment method	invoice
order: processing_amount	string	Paid amount	25000
order: processing_currency	string	Transaction currency	NGN
transactions	object	Object with information about the transaction
transactions: status	string	Transaction status	approved
transactions: method	string	Transaction Payment method	invoice
transactions: amount	integer	Transaction amount	25000
transactions: currency	string	Transaction currency	NGN
transactions: type	string	Transaction type	pay

Successful response sample
                                    
{
  "order": {
    "amount": 25000,
    "currency": "NGN",
    "order_id": "1513010320068invoice",
    "status": "approved",
    "method": "invoice",
    "processing_amount": "25000",
    "processing_currency": "NGN"
  },
  "transactions": [
    {
      "status": "approved",
      "method": "invoice",
      "amount": 25000,
      "currency": "NGN",
      "type": "pay"
    }
  ]
}

                                

Successful response sample (partial_approved)
                                    {
  "order": {
    "amount": 25000,
    "currency": "NGN",
    "order_id": "1513010535090invoice",
    "status": "partial_approved",
    "method": "invoice",
    "processing_amount": "24900",
    "processing_currency": "NGN"
  },
  "transactions": [
    {
      "status": "approved",
      "method": "invoice",
      "amount": 24900,
      "currency": "NGN",
      "type": "pay"
    }
  ]
}
                                

If the invoice was paid with the amount more or less, the order status will be deemed as "Partial_approved".

Response sample with information about the error
                                    {
  "error": {
    "code": "2.01",
    "messages": {
      "amount": [
        "This value should be greater than or equal to "1"."
      ]
    }
  }
}
                                

SolidGate Status

Request in order to get current order status.

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

Request parameters

Parameter	Mandatory	Type	Description	Value sample
order_id	Yes	string(255)	Order ID specified in merchant system	123443334

Request sample
                                    {
  "order_id": "777"
}
                                

Response Body Parameters | Success

Parameter	Type	Description	Example
order	object	Object with information about the order
order: order_id	string	Order ID specified in merchant system	777
order: amount	integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	2575
order: currency	string	Order currency. 3 letter currency code under ISO-4217	USD
order: status	string	Order status	created
order: method	string	Payment method	solid-cards
order: created_at	String	When the order was created	2020-07-02 23:39:06
order: updated_at	String	The last time the order was updated	2020-07-08 01:40:44
order: customer_email	String	Email of the customer	test@gmail.com
order: ip_address	String	IP of the customer	70.65.246.237
pay_form	object
pay_form: token	string	Card token being applied for recurring payments. It's returned in case of successful payment	4056cd8cccf96...40015a997d74
card_token	object
card_token: token	string	Card token being applied for recurring payments. It's returned in case of successful payment	ae7ab1407317e77d9d1002cb41512c5e15def5d8b1
card_token: card_number	string	Card number in an encrypted format	453245XXXXXX2692
card_token: card_brand	string	Card brand	VISA
card_token: card_country	string	Country of card origin	USA
card_token: card_bank	string	Issuing bank	STATE BANK
transactions	object	Object with information about the transaction
transactions: status	string	Transaction status	approved
transactions: method	string	Transaction Payment method	solid-cards
transactions: amount	integer	Transaction amount	1500
transactions: currency	string	Transaction currency	NGN
transactions: type	string	Transaction type	pay

Response Body Sample
                                    {
  "order": {
    "amount": 1500,
    "currency": "NGN",
    "order_id": "1513005352925widget",
    "status": "approved",
    "method": "solid-cards",
    "created_at": "2020-07-02 23:39:06",
    "updated_at": "2020-07-08 01:40:44",
    "customer_email": "test@gmail.com",
    "ip_address": "8.8.8.8",
  },
  "card_token": {
    "token": "805c558d57f50befc2d8bca4c3dcc04afcb211870637984cc6c96bd3b4e376f61c7fd2dc0ec409451c40fde7323abf54a8bf",
    "card_number": "453245XXXXXX2692",
    "card_brand": "VISA",
    "card_country": "USA",
    "card_bank": "STATE BANK"
  },
  "pay_form": {
    "token": "57c70aed87c94c6cb50cb68e64cffa91"
  },
  "transactions": [
    {
      "status": "approved",
      "method": "solid-cards",
      "amount": 1500,
      "currency": "NGN",
      "type": "pay"
    }
  ]
}
                                

SolidGate Recurring

Operation of order initiating. It shall be used while working with a payment form.

This operation deems to create order in the system and return token being applied while calling payment form.

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

Request Body Parameters

Parameter	Mandatory	Type	Description	Value sample
amount	Yes	integer	Order amount - integer without fractional component (i.e., cents). For instance, 1020 means 10 USD and 20 cents	1020
currency	Yes	string(3)	Order currency. 3 letter currency code under ISO-4217	USD
payment_method	No	string(255)	Payment method ( "przelewy24", "trustly", "bancontact", "giropay", "paysafecard", "sepa", "sofort", "ideal", "paypal", "yandex_money", "dcb")	paypal
token	Yes	string(255)	Card token that can be used for future transactions	afsdgrg34g34g34g34g
customer_account_id	No	string(100)	Customer ID in the merchant's system. In case of successful payment, card data will be tied to this ID	4dad42f808
customer_date_of_birth	No	string(50)	Customer birth date in format YYYY-MM-DD	2000-11-21
customer_email	Yes	string(100)	Customer email	jondou@gmail.com
customer_first_name	No	string(100)	Customer-first name	John
customer_last_name	No	string(100)	Customer last name	Snow
customer_phone	No	string(50)	Customer telephone	380111111111
geo_country	No	string(3)	Customer country. Code shall be in ISO 3166-1 alpha-3 format	GBR
geo_city	No	string(100)	Customer city	New Castle
ip_address	Yes	string(50)	Customer IP (only public ones)	8.8.8.8
language	No	string(2)	Customer language settings. Available values: RU - Russian, EN - English	en
order_id	Yes	string(255)	Order ID specified in merchant system	123443334
order_date	No	string(50)	Date of order creation in format YYYY-MM-DD-HH-MM-SS	2015-12-21 11:21:30
order_description	Yes	string(255)	Order description in UTF-8 code	Premium package
platform	Yes	string(6)	Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application	WEB
callback_url	No	string(255)	URL of merchant page, where response with payment result will be sent	http://merchant.example/callback
return_url	Yes	string(255)	URL of merchant page, which a customer will be redirected after completed payment	http://merchant.example/return

Request sample
                                    {
  "amount": 2575,
  "payment_method": "paypal",
  "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",
  "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",
  "platform": "WEB"
}
                                

Response Body Parameters | Success

Parameter	Type	Description	Value sample
order	object	Object with information on the order
order: order_id	string	Order ID specified in merchant system	777
order: amount	integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	2575
order: currency	string	Order currency (3 letter code under ISO 4217)	USD
order: status	string	Order status	created
pay_form	object	Object with data payment form data
pay_form: token	string	Payment form token	5849cf0468afc0ac4be4963c619b776eee75271d56e3c6621ab21

Response Body Sample | Success
                                    {
 "order": {
 "amount": 5000,
 "currency": "USD",
  "order_id": "1504269591134TEST",
  "status": "created"
  },
 "pay_form": {
 "token": "6de603708b5b4c33a681dc1e47b20ad3"
  }
}

                                

Response Body Sample | Error
                                    {
  "error": {
    "code": "2.01",
    "messages": {
      "currency": [
        "Invalid Currency."
      ]
    }
  }
}
                                

SolidGate - Boleto

Voucher payments and the way Brazilians pay

The Boleto Bancário is a printable voucher that Brazilians use to pay for their monthly bills, such as water and energy, or even governmental taxes or fines, and has become one of the preferred payment methods for online purchases in Brazil. Customers can pay the boleto in cash in more than 200K payment locations, or through internet banking.

71,1% of Brazilians who pay online with boleto do have a checking account. This shows that using this voucher is a matter of preference rather than a necessity.

38,8% of them pay with boleto because they fear credit card fraud.

/media/23/download/09-04%2012-54-47.png?v=1&inline=0

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

Request parameters

Parameter	Mandatory	Type	Description	Value sample
amount	Yes	integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	1000
currency	Yes	string(3)	Order currency. 3 letter currency code under ISO-4217	BRL
customer_account_id	No	string	Customer ID in the merchant's system. In case of successful payment, card data will be tied to this ID	4dad42f808
customer_date_of_birth	No	string	Customer birth date in format YYYY-MM-DD	2000-11-21
customer_email	Yes	string	Customer email
customer_first_name	No	string	Customer-first name	John
customer_last_name	No	string	Customer last name	Snow
customer_phone	No	string	Customer telephone	380111111111
geo_country	No	string(3)	Customer country. Code shall be in ISO 3166-1 alpha-3 format	BRA
geo_city	No	string	Customer city	New Castle
ip_address	Yes	string	Customer IP (only public ones)	8.8.8.8
language	No	string(2)	Customer language settings. Available values: RU - Russian, EN - English	en
order_id	Yes	string	Order ID specified in merchant system	123443334
order_date	No	string	Date of order creation in format YYYY-MM-DD-HH-MM-SS	2015-12-21 11:21:30
order_description	Yes	string	Order description in UTF-8 code	Premium package
platform	Yes	string	Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application.	WEB
payment_type_data	Yes	object	Object with payment type data
payment_type_data:cpf	Yes	string	CPF - individual taxpayer registry identification, a number attributed by the Brazilian Federal Revenue	42243309114
payment_method	Yes	string	Payment method	boleto
callback_url	No	string	URL of merchant page, where response with payment result will be sent	http://merchant.example/callback

Request Body Sample 
                                    {
  "amount": 2500,
  "currency": "BRL",
  "customer_account_id": "1567491958095widget",
  "customer_email": "kurt.Cruickshank.toster@gmail.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "+380954543322",
  "geo_country": "BRA",
  "ip_address": "8.8.8.8",
  "language": "en",
  "order_description": "test",
  "order_id": "1567491958095widget",
  "order_items": "order_items",
  "platform": "WEB",
  "payment_method": "boleto",
  "payment_type_data": {
    "cpf": "42243309114"
  },
  "callback_url": "http://merchant.example/callback"
}
                                

Response Body Parameters | Success

Parameter	Type	Description	Value sample
order	object	Object with information of the order
order: order_id	string	Order ID specified in merchant system	777
order: amount	integer	Order amount - integer without fractional component (i.e., cents). For instance, 1020 means 10 USD and 20 cents	2575
order: currency	string	Order currency (3 letter code under ISO 4217)	USD
order: status	string	Order status	created
pay_form	object	Object with data payment form data
pay_form: token	string	Payment form token	5849cf0468afc0ac4be4963c619b776eee75271d56e3c6621ab21
payment_type_data	object
payment_type_data:id	string	Ticket id	109/18369953-0
payment_type_data:number	string	Ticket number	34191091803699530044354689940002780050000015476
payment_type_data:expiration_date	string	Ticket expiration date	2019-09-08T02:59:00+0000
payment_type_data:barcode	string	Ticket barcode	34197800500000154761091836995300445468994000
transactions	array	An object with information of transactions
transactions: status	string	Transaction status	processing
transactions: method	string	Transaction method	boleto
transactions: amount	integer	Transaction amount	2500
transactions: currency	string	Transaction currency	BRL
transactions: type	string	Transaction type	pay

Response Body Sample | Success
                                    {
  "payment_type_data": {
    "id": "109/18414522-8",
    "number": "34191091804145228044354689940002880060000002500",
    "expiration_date": "2019-09-09T02:59:00+0000",
    "barcode": "34198800600000025001091841452280445468994000"
  },
  "order": {
    "amount": 2500,
    "currency": "BRL",
    "order_id": "1567491958095widget",
    "status": "processing",
    "method": "boleto"
  },
  "pay_form": {
    "token": "885262c417834dfbb8b1dfceaf119aff"
  },
  "transactions": [
    {
      "status": "processing",
      "method": "boleto",
      "amount": 2500,
      "currency": "BRL",
      "type": "pay"
    }
  ]
}
                                

Responsive Boleto for Mobile Devices

Thinking of increasing mobile conversions, Solid improved the mobile user experience by creating a boleto 100% optimized for mobile devices.

Example of appearance for user

/media/24/download/09-04%2013-02-42.png?v=1&inline=0

Barcode needs to have the Interleaved 2 of 5 (ITF) format in order to be recognized by all Boleto Bancario barcode readers.

Refund

This is a request for transferring funds back to the cardholder.

Refunds are applicable only for successful orders.

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

Request Body Parameters

Parameter	Mandatory	Type	Description	Value sample
amount	Yes	integer	Refund amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	2575
order_id	Yes	string(255)	Order ID specified in merchant system	777
refund_type_data	Yes	object
refund_type_data:beneficiary_name	Yes	string(255)	User's full name	Emilia Dark
refund_type_data:bank_account	Yes	string(255)	User's bank account number
refund_type_data:bank_branch	Yes	string(255)	User's bank branch name
refund_type_data:bank	Yes	string(255)	User's bank name
refund_type_data:bank_account_type	Yes	string(255)	Type of bank account. C: for Current accounts; S: for Savings accounts; I: International accounts	C
refund_type_data:description	No	string(255)	Description of the refund

Request Sample
                                    {
  "amount": 2575,
  "order_id": "777",
  "payment_type_data": {},
  "refund_type_data": {
    "beneficiary_name": "Emilia Dark",
    "bank_account": "account",
    "bank_branch": "branch",
    "bank": "bank",
    "bank_account_type": "C",
    "description": "description"
  }
}
                                

Response Body Parameters

Parameter	Type	Description	Value sample
order	object	Object with information about the order
order: order_id	string	Order ID specified in merchant system	777
order: amount	integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	2575
order: currency	string	Order currency. 3 letter currency code under ISO-4217	BRL
order: status	string	Transaction status	refunded
order: method	string	Payment method	solid-cards
order:processing_amount	string	Amount in processing currency	2575
order: processing_currency	string	Processing currency	BRL
pay_form	object
pay_form: token	string	Card token being applied for recurring payments. It's returned in case of successful payment	4056cd8cccf96...40015a997d74
card_token	object
card_token:token	string	Card token being applied for recurring payments. It's returned in case of successful payment.	ae7ab1407317e77d9d1002cb41512c5e15def5d8b1
card_token: card_number	string	Card number in an encrypted format.	453245XXXXXX2692
card_token: card_brand	string	Card brand	VISA
card_token: card_country	string	Country of card origin	NGN
card_token: card_bank	string	Issuing bank	CITIZENS STATE BANK
transactions	object
transactions: status	string	Transaction status	approved
transactions: method	string	Payment method	solid-cards
transactions: amount	string	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.	2575
transactions: currency	string	Order currency. 3 letter currency code under ISO-4217	BRL
transactions: type	string	Type of transaction	refund
payment_type_data	object
payment_type_data: id	string	Ticket id	109/32588901-5
payment_type_data: number	string	Ticket number	34191093215889015044254689940002681130000050000
payment_type_data: expiration_date	string	Ticket expiration date	2019-12-25T01:59:00+0000
payment_type_data: barcode	string	Ticket barcode	34196811300000500001093258890150445468994000

Response Sample | Success
                                    {
  "payment_type_data": {
    "id": "109/32588901-5",
    "number": "34191093215889015044254689940002681130000050000",
    "expiration_date": "2019-12-25T01:59:00+0000",
    "barcode": "34196811300000500001093258890150445468994000"
  },
  "order": {
    "amount": 2575,
    "currency": "BRL",
    "order_id": "1576766096183widget",
    "status": "refunded",
    "method": "boleto"
  },
  "pay_form": {
    "token": "7df93d046e76442aa585bddbf6d8d44b"
  },
  "transactions": [
    {
      "status": "success",
      "method": "boleto",
      "amount": 2575,
      "currency": "BRL",
      "type": "pay"
    },
    {
      "status": "success",
      "method": "boleto",
      "amount": 2575,
      "currency": "BRL",
      "type": "refund"
    }
  ]
}
                                

SolidGate - Callbacks

SolidGate can notify merchants about different events taking place with orders. Callback notification shall be sent with a POST request to URL specified by merchant. The JSON format is applicable.

The following notification types are applicable:

Order status Callback - notification about any order status change

In order to apply the function of notification on status changes, the merchant is required to send filled attribute callback_url during the initial request (Callback URL is web-resource address on merchant end). POST requests in JSON format will be sent to this URL. These requests are notifications regarding the current order status.

Request Body Parameters

Parameters	Type	Description	Value Sample
order	object	Object with information about the order
order:order_id	string	Order ID specified in merchant system	777
order:amount	string	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	2575
order:currency	string	Order currency. 3 letter currency code under ISO-4217	USD
order:status	string	Transaction status	approved
order: method	string	Payment method	solid-cards
order: processing_amount	string	Amount in processing currency	2575
order: processing_currency	string	Processing currency	NGN
pay_form	object	Object with information about payment form
pay_form: token	string	Payment form token	5849cf0468afc...c6621ab21
card_token	object
card_token: token	string	Card number in encrypted format	ae7ab1407317e77d9d1002cb41512c5e15def5d8b1
card_token: card_number	string	Card number	453245XXXXXX2692
card_token: card_brand	string	Card brand	VISA
card_token: card_country	string	Country of card origin	USA
card_token: card_bank	string	Issuing bank	STATE BANK
transactions	object
transactions: status	string	Transaction status	approved
transactions: method	string	Payment method	solid-cards
transactions: amount	string	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.	2575
transactions: currency	string	Order currency. 3 letter currency code under ISO-4217	NGN
transactions: type	string	Type of transaction	pay

Request Sample | Success
                                    {
  "order": {
    "amount": 1500,
    "currency": "NGN",
    "order_id": "1555932951120widget",
    "status": "approved",
    "method": "solid-cards",
    "processing_amount": "5",
    "processing_currency": "USD"
  },
  "card_token": {
    "token": "7fa26c8feb7593a6eb3eed508651d65a8a4aa5f860f30fe382d879f9d2b478f8f95e3aabb5ef304148d1ae15fd4b04104438",
    "card_number": "453245XXXXXX2692",
    "card_brand": "VISA",
    "card_country": "USA",
    "card_bank": "CITIZENS STATE BANK"
  },
  "pay_form": {
    "token": "d9ecff062860423f87bba5f9cce5afcf"
  },
  "transactions": [
    {
      "status": "success",
      "method": "solid-cards",
      "amount": 1500,
      "currency": "NGN",
      "type": "pay"
    }
  ]
}
                                

Request Body Parameters | During Invoice Payment

Parameter	Type	Description	Value sample
order	object	Object with information about the order
order: amount	integer	Order amount	25000
order: currency	string	Order currency	NGN
order: order_id	string	Order ID specified in merchant system	151134992549
order: status	string	Transaction status	approved
order: method	string	Payment method	invoice
order: processing_amount	string	Paid amount	25000
order: processing_currency	string	Payment currency	NGN

Request Sample | Success
                                    
{
  "order": {
    "amount": 21000,
    "currency": "NGN",
    "order_id": "1511353425147invoice",
    "status": "approved",
    "method": "invoice",
    "processing_amount": "21000",
    "processing_currency": "NGN"
  }
}
                                

Once the callback is sent, we expect to see from merchant code-200 in response and JSON as follows:
                                    {
  "status": "ok"
}
                                

In case we get response different from the specified one, the callback will be considered to be not received.

SolidGate Init-Payment M-PESA

Operation of order initiating. It shall be used while working with a payment widget.

This operation deems to create order in the system and return token being applied while calling a payment widget.

POST https://gate.solidgate.com/api/v1/invoice

Request Body Parameters | M-PESA

Parameter	Mandatory	Type	Description	Value sample
amount	Yes	Integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	1020
currency	Yes	String(3)	Order currency. 3 letter currency code under ISO-4217	KES
payment_method	No	String	Payment method ( "przelewy24", "trustly", "bancontact", "giropay", "paysafecard", "sepa", "sofort", "ideal", "paypal", "yandex_money", "dcb", "paysms", "alipay")	mpesa
payment_type_data	No	Object	Object with payment type data
payment_type_data:phone	No	String	Phone number	380000000000
customer_account_id	No	String	Customer ID in the merchant's system. In case of successful payment, card data will be tied to this ID	4dad42f808
customer_date_of_birth	No	String	Customer birth date in format YYYY-MM-DD	2000-11-21
customer_email	Yes	String	Customer email	jondou@gmail.com
customer_first_name	No	String	Customer's first name	John
customer_last_name	No	String	Customer last name	Snow
customer_phone	No/Yes	String	Customer telephone (Mandatory for locations: UGA, KEN, TZA, GHA)	380111111111
geo_country	No/Yes	String(3)	Customer country. Code shall be in ISO 3166-1 alpha-3 format. (Mandatory for method PayPal)	KEN
geo_city	No	String	Customer city	New Castle
ip_address	Yes	String	Customer IP (only public ones)	8.8.8.8
language	No	String(2)	Customer language settings. Available values: RU - Russian, EN - English	en
order_id	Yes	String	Order ID specified in merchant system	123443334
order_date	No	String	Date of order creation in format YYYY-MM-DD-HH-MM-SS	2015-12-21 11:21:30
order_description	Yes	String	Order description in UTF-8 code	Premium package
platform	Yes	String	Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application	WEB
callback_url	No	String	URL of merchant page, where response with payment result will be sent	http://merchant.example/callback
return_url	Yes	String	URL of merchant page, to which a customer will be redirected after payment is complete	http://merchant.example/return
success_url	Yes	String	URL of merchant page, to which a customer will be redirected after success payment	http://merchant.example/success
fail_url	Yes	String	URL of merchant page, to which a customer will be redirected after unsuccess payment	http://merchant.example/fail

Reuest Sample | M-PESA
                                    {
  "amount": 10000,
  "currency": "KES",
  "customer_email": "test@email.com",
  "customer_phone": "+380954543322",
  "fail_url": "https://www.google.com/",
  "geo_country": "KEN",
  "ip_address": "8.8.8.8",
  "language": "en",
  "order_description": "test",
  "order_id": "1607005109943widget",
  "order_items": "order_items",
  "platform": "WEB",
  "fraudulent": true,
  "return_url": "https://www.google.com/",
  "payment_type_data": {
    "phone": "0714074869"
  }
}
                                

Response Body Parameters | M-PESA

Parameter	Type	Description	Value sample
payment_type_data	object	Object with information about the payment data
payment_type_data:business_number	string	Business account number	527773
payment_type_data:account_numbe	string	Account number	292814
order	object	Object with information about the order
order: order_id	string	Order ID specified in merchant system	777
order: amount	integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	2575
order: currency	string	Order currency. 3 letter currency code under ISO-4217	BRL
order: status	string	Transaction status	refunded
order: method	string	Payment method	solid-cards
order:processing_amount	string	Amount in processing currency	2575
order: processing_currency	string	Processing currency	BRL
pay_form	object
pay_form: token	string	Card token being applied for recurring payments. It's returned in case of successful payment	4056cd8cccf96...40015a997d74
card_token	object
card_token:token	string	Card token being applied for recurring payments. It's returned in case of successful payment.	ae7ab1407317e77d9d1002cb41512c5e15def5d8b1
card_token: card_number	string	Card number in an encrypted format.	453245XXXXXX2692
card_token: card_brand	string	Card brand	VISA
card_token: card_country	string	Country of card origin	NGN
card_token: card_bank	string	Issuing bank	CITIZENS STATE BANK
transactions	object
transactions: status	string	Transaction status	approved
transactions: method	string	Payment method	solid-cards
transactions: amount	string	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.	2575
transactions: currency	string	Order currency. 3 letter currency code under ISO-4217	BRL
transactions: type	string	Type of transaction	refund
payment_type_data	object
payment_type_data: id	string	Ticket id	109/32588901-5
payment_type_data: number	string	Ticket number	34191093215889015044254689940002681130000050000
payment_type_data: expiration_date	string	Ticket expiration date	2019-12-25T01:59:00+0000
payment_type_data: barcode	string	Ticket barcode	34196811300000500001093258890150445468994000

Response Sample
                                    {
  "payment_type_data": {
    "business_number": "527773",
    "account_number": "292814"
  },
  "order": {
    "amount": 10000,
    "currency": "KES",
    "order_id": "1607006174779widget",
    "status": "processing",
    "method": "mpesa",
    "customer_email": "test@email.com",
    "ip_address": "8.8.8.8",
    "created_at": "2020-12-03 14:36:15",
    "updated_at": "2020-12-03 14:36:15"
  },
  "pay_form": {
    "token": "64807cb4384d4253bae2d3a90418829c",
    "script_url": "https://gate.sp-stage.us/widget/64807cb4384d4253bae2d3a90418829c"
  }
}
                                

SolidGate Init-Payment SEPA

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

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

SEPA Request Body Parameters

Parameter	Mandatory	Type	Description	Value sample
payment_method	Yes	String	Payment method	sepa
payment_type_data	Yes	Object	Object with payment type data
payment_type_data:iban	Yes	String	International Bank Account Number	DE52100100101234567892
customer_first_name	Yes	String	Customer's first name	John
customer_last_name	Yes	String	Customer last name	Snow
geo_country	Yes	String(3)	Customer country. Code shall be in ISO 3166-1 alpha-3 format. (Mandatory for method PayPal)	GBR
geo_city	Yes	String	Customer city	New Castle
zip_code	Yes	String	Parameter for identifying a location.	10005
address	Yes	String	Payer Address	Kyrilivska
amount	Yes	Integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	1020
currency	Yes	String(3)	Order currency. 3 letter currency code under ISO-4217	USD
customer_account_id	No	String	Customer ID in the merchant's system. In case of successful payment, card data will be tied to this ID	4dad42f808
customer_date_of_birth	No	String	Customer birth date in format YYYY-MM-DD	2000-11-21
customer_email	No	String	Customer email	jondou@gmail.com
customer_phone	No	String	Customer telephone	380111111111
ip_address	No	String	Customer IP (only public ones)	8.8.8.8
language	No	String(2)	Customer language settings. Available values: RU - Russian, EN - English	en
order_id	No	String	Order ID specified in merchant system	123443334
order_date	No	String	Date of order creation in format YYYY-MM-DD-HH-MM-SS	2015-12-21 11:21:30
order_description	Yes	String	Order description in UTF-8 code	Premium package
platform	No	String	Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application	WEB
fail_url	Yes	String	URL of merchant page, to which a customer will be redirected after unsuccessful payment	http://merchant.example/fail
return_url	Yes	String	URL of merchant page, to which a customer will be redirected after payment is complete	http://merchant.example/return
success_url	Yes	String	URL of merchant page, to which a customer will be redirected after successful payment	http://merchant.example/success
callback_url	No	String	URL of merchant page, where response with payment result will be sent	http://merchant.example/callback

Successful Request Sample 
                                    {
  "order_id": "295",
  "amount": 1000,
  "currency": "EUR",
  "payment_method": "sepa",
  "order_description": "Premium package",
  "customer_email": "example.user@example-email.com",
  "customer_first_name": "Alex",
  "customer_last_name": "Show",
  "ip_address": "8.8.8.8",
  "platform": "WEB",
  "geo_country": "GBR",
  "geo_city": "Kyiv",
  "customer_account_id": 12,
  "return_url": "https://return.solidgate.com",
  "zip_code": "11111",
  "address": "Vashyngton str. 1",
  "payment_type_data": {
      "iban": "DE52100100101234567892"
  }
}
                                

SEPA Response Body Parameters

Parameter	Type	Description	Value sample
order	Object	Object with information of the order
order: amount	Integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	1020
order: currency	String	Order currency (3 letter code under ISO 4217)	USD
order: order_id	String	Order ID specified in merchant system	10918369953
order: status	String	Order status	created

Successful Response Sample
                                    {
 "order": {
 "amount": 1020,
 "currency": "EUR",
  "order_id": "1504269591134TEST",
  "status": "created"
  }
}
                                

If you want to test the different use cases for SEPA payment, please use the following test IBANs. These IBANs have a valid checksum and should be supplied when creating a new mandate.

Test IBAN List (only for Sandbox accounts)

IBAN	Description
DE09100100101234567890	The customer's mandate and payment can't be set up because their bank details are invalid. Payment not accepted.
DE79100100101234567891	The customer's payment is accepted, but not collected yet. The mandate is marked as activated. The payment will remain on Status 1 (accepted).
DE52100100101234567892	The customer's payment is accepted but then canceled before collection. The mandate is marked as activated. The payment is marked as Status 1 (accepted), then Status 2 (canceled).
DE25100100101234567893	The customer's payment is collected successfully and paid out to you. The mandate is marked as activated. The payment is marked as Status 1 (accepted), then Status 3 (paid).
DE95100100101234567894	The customer’s payment is provided to the bank successfully but is then charged back due to a request by a merchant. The mandate is marked as activated. The payment is marked as Status 1 (accepted), then Status 3 (paid). Finally, the payment is marked as Status 4 (charge-back) with Token (RFND).
DE68100100101234567895	The customer's payment is collected successfully but is then charged back by the customer disputing it with their bank (actively initiated by the customer). The mandate is marked as activated. The payment is marked as status 1 (accepted), then status 3 (paid). Finally, the payment is marked as status 4 (chargeback) with the token (ACT).
DE41100100101234567896	The customer's payment is provided to the bank successfully but is then charged back by their bank due to no sufficient funds. The mandate is marked as activated. The payment is marked as Status 1 (accepted), then Status 3 (paid). Finally, the payment is marked as Status 4 (chargeback) with Token (NSF).
DE14100100101234567897	The customer's payment is provided to the bank successfully but is then charged back by the bank due to other reasons (no bank account, saving account). The mandate is marked as activated. The payment is marked as Status 1 (accepted), then Status 3 (paid). Finally, the payment is marked as Status 4 (chargeback) with Token (OTHR).
DE84100100101234567898	The customer's payment is provided to the bank successfully but is then charged back by the bank due to format errors. The mandate is marked as activated. The payment is marked as Status 1 (accepted), then Status 3 (paid). Finally, the payment is marked as Status 4 (chargeback) with Token (FRM).