Alternative Payments Methods
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.
API Endpoint URL - https://gate.solidgate.com/api/v1/
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.
Please, note that all requests must be signed.
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 | Yes | String | Payment method ( "paypal-vault","przelewy24", "trustly", "bancontact", "giropay", "paysafecard", "sepa", "sofort", "ideal", "yandex_money", "dcb", "paysms", "alipay") | sepa |
| 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. Required for Subscription Payments | 4dad42f808 |
| customer_date_of_birth | No | String | Customer birth date in format YYYY-MM-DD | 2000-11-21 |
| customer_email | Yes | String | Customer email. Must be valid. | 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 | String(3) | Customer country. Code shall be in ISO 3166-1 alpha-3 format. | 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 | No | String | URL of merchant page, to which a customer will be redirected after payment is complete | http://merchant.example/return |
| success_url | No | String | URL of merchant page, to which a customer will be redirected after success payment | http://merchant.example/success |
| fail_url | No | 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": "sepa",
"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&token=EC-1LX20314LJ601741A"
}
}SolidGate Init-Payment PayPal
Operation of order initiating. This operation creates an order in the system and returns the Java script URL applied while calling the PayPal button.
If you work under the subscription model, after successful payment, you will receive in the object order a token that you could use for recurring payments.
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 |
| product_id | Yes | String(36) | The ID of the predefined product | faf3b86a-1fe6-4ae5-84d4-ab0651d75db2 |
| payment_method | Yes | String | PayPal Vault | paypal-vault |
| customer_account_id | No | String | Customer ID in the merchant's system. Required for Subscription Payments | user_id |
| order_id | Yes | String | Order ID specified in merchant system | testPayPal777 |
| 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 |
| customer_email | Yes | String | An email that belongs to a customer | jondou@gmail.com |
| geo_country | No | String(3) | Customer’s country. Code shall be in ISO 3166-1 alpha-3 format. | GBR |
| ip_address | Yes | String | IP address (only public ones) | 8.8.8.8 |
| customer_date_of_birth | No | String | Customer birth date in format YYYY-MM-DD | 2000-11-21 |
| customer_first_name | No | String | Customer’s first name | John |
| customer_last_name | No | String | Customer’s last name | Snow |
| customer_phone | No | String | Customer’s telephone | 380000000000 |
| geo_city | No | String | Customer’s city | New Castle |
| language | No | String(2) | Customer’s language settings. Available values: RU - Russian, EN - English | en |
| order_date | No | String | Date of order creation in format YYYY-MM-DD-HH-MM-SS | 2015-12-21 11:21:30 |
| callback_url | No | String | URL of merchant page, where response with payment result will be sent | http://merchant.example/callback |
| subscription_callback_url | No | String | Subscription callback address | http://merchant.example/subscription_callback |
| return_url | No | String | URL of merchant page, to which a customer will be redirected after payment is complete | http://merchant.example/return |
| success_url | No | String | URL of merchant page, to which a customer will be redirected after success payment | http://merchant.example/success |
| fail_url | No | 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,
"currency": "USD",
"payment_method": "paypal-vault",
"callback_url": "http://merchant.example/callback",
"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": "testPayPal777",
"platform": "WEB"
}Init Payment Response Body Parameters | PayPal
| Parameter | Type | Description | Value sample |
|---|---|---|---|
| order | Object | Object with information of the order | |
| order: method | String | A method that is used for the subscription payment | paypal-vault |
| order: order_id | String | Order ID specified in merchant system | testPayPal777 |
| order: amount | Integer | Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents. | 999 |
| 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: script_url | String | PayPal Button Script | https://gate.solidgate.com/widget/7d0d148742af492ea075e1972779df78 |
Init Payment Response Body | PayPal Success
{
"order": {
"amount": 999,
"currency": "USD",
"order_id": "testPayPal777",
"status": "created",
"method": "paypal-vault"
},
"pay_form": {
"script_url": "https://gate.solidgate.com/widget/3e74d293f47e4c7899613ba37e38ee43"
}
}PayPal Button elements on page
<div id="paypal-button"></div>
<script>
var elem = document.getElementById('paypal-button');
elem.addEventListener('order-started-processing', function (e) {
console.log('order-started-processing',e);
}, false);
elem.addEventListener('order-processed', function (e) {
console.log('order-processed',e);
}, false);
elem.addEventListener('order-already-processed', function (e) {
console.log('order-already-processed', e)
}, false);
elem.addEventListener('button-ready', function (e) {
console.log('button-ready', e)
}, false);
elem.addEventListener('button-error', function (e) {
console.log('button-error',e);
}, false);
</script>
<script type="text/javascript"
src="https://gate.solidgate.com/widget/e403827025c44f0893baac3d760d3a3c"
>
</script>| Events | Value | Description |
|---|---|---|
| EVENT_BUTTON_READY | button-ready | The button is ready to be used |
| EVENT_BUTTON_ERROR | button-error | There is an error with the button rendering |
| EVENT_ORDER_STARTED_PROCESSING | order-started-processing | Order is in processing |
| EVENT_ORDER_PROCESSED | order-processed | Order is processed |
| EVENT_ORDER_ALREADY_PROCESSED | order-already-processed | Appears if the user goes on the page with the order creation again |
Event Order-Processed Sample | Success
{
"order": {
"amount": 100,
"currency": "USD",
"order_id": "1595234886934init",
"status": "approved",
"method": "paypal-vault",
"token": "6c441e1117978dad8c47f1985420f55c4884a323fdf35dfcb8d3dc35ccb5d09b369b0fd89d00f054cce34b3c6a854184b995",
"customer_email": "kurt.Cruickshank.toster@gmail.com",
"ip_address": "8.8.8.8",
"created_at": "2020-07-20 08:48:07",
"updated_at": "2020-07-20 08:49:19"
},
"pay_form": {
"script_url": "https://gate.solidgate.com/widget/fb124ba2d884427d8724c1a78ad304de"
},
"transactions": [
{
"status": "success",
"method": "paypal-vault",
"amount": 100,
"currency": "USD",
"type": "pay"
}
]
}
Event Order-Processed Sample | Decline
{
"order": {
"amount": 100,
"currency": "EUR",
"order_id": "1595234705069init",
"status": "declined",
"method": "paypal-vault",
"customer_email": "kurt.Cruickshank.toster@gmail.com",
"ip_address": "8.8.8.8",
"created_at": "2020-07-20 08:45:05",
"updated_at": "2020-07-20 08:46:27"
},
"pay_form": {
"script_url": "https://gate.solidgate.com/widget/a48fcc6c3abf425eaa61b2289675f489"
},
"error": {
"code": "0.01",
"messages": [
"General decline"
],
"recommended_message_for_user": "General decline"
},
"transactions": [
{
"status": "fail",
"method": "paypal-vault",
"amount": 100,
"currency": "EUR",
"type": "pay"
}
]
}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 — 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. Required for Subscription Payments | 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 | String(3) | Customer country. Code shall be in ISO 3166-1 alpha-3 format. | 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 | No | String | URL of merchant page, to which a customer will be redirected after payment is complete | http://merchant.example/return |
| success_url | No | String | URL of merchant page, to which a customer will be redirected after success payment | http://merchant.example/success |
| fail_url | No | 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"
}
}SolidGate Init-Payment Sofort
Operation of order initiating.
This operation creates an order in the system and returns a redirect URL. You should redirect the end-user to this URL.
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 — sofort | 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. Required for Subscription Payments | 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 | String(3) | Customer country. Code shall be in ISO 3166-1 alpha-3 format. | 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 | No | String | URL of merchant page, to which a customer will be redirected after payment is complete | http://merchant.example/return |
| success_url | No | String | URL of merchant page, to which a customer will be redirected after success payment | http://merchant.example/success |
| fail_url | No | 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"
}
}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 — ideal | 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. Required for Subscription Payments | 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 | String(3) | Customer country. Code shall be in ISO 3166-1 alpha-3 format. | 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 | No | String | URL of merchant page, to which a customer will be redirected after payment is complete | http://merchant.example/return |
| success_url | No | String | URL of merchant page, to which a customer will be redirected after success payment | http://merchant.example/success |
| fail_url | No | 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"
}
}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 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"
}
]
}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-vault", "yandex_money", "dcb") | paypal-vault |
| 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. Required for Subscription Payments | 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 | No | string(255) | URL of merchant page, which a customer will be redirected after completed payment | http://merchant.example/return |
| success_url | No | string(255) | URL of merchant page, to which a customer will be redirected after success payment | http://merchant.example/success |
| fail_url | No | string(255) | URL of merchant page, to which a customer will be redirected after unsuccess payment | http://merchant.example/fail |
Request sample
{
"amount": 2575,
"payment_method": "paypal-vault",
"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"
}
}
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.
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. Required for Subscription Payments | 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:brazil_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 |
| return_url | No | string | URL of merchant page, to which a customer will be redirected after payment is complete | http://merchant.example/return |
| success_url | No | string | URL of merchant page, to which a customer will be redirected after success payment | http://merchant.example/success |
| fail_url | No | string | URL of merchant page, to which a customer will be redirected after unsuccess payment | http://merchant.example/fail |
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": {
"brazil_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
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 - OXXO
The payment method OXXO gives you access to the redirect solution. The API returns a return_url, for redirection of the user to a Solid-hosted page. The user will be able to see the ticket to pay or print it.
During using the Redirect method, the payment will have the "status = Pending" until the user pays the ticket, and Solid gets notified about it.
POST https://gate.solidgate.com/api/v1/init-payment
Reuest Body Parametrs | OXXO
| Parameter | Mandatory | Type | Description | Value sample |
| order_id | Yes | String | Order ID specified in merchant system | 123443334 |
| amount | Yes | Integer | Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 MXN and 20 cents | 1020 |
| currency | Yes | String(3) | Order currency. 3 letter currency code under ISO-4217 | MXN |
| payment_method | Yes | String | Payment method — "OXXO" | OXXO |
| payment_type_data | Yes | object | Object with information about the payment | |
| payment_type_data:mexico_curp | Yes | String | Unique Population Registry Code | ZAZD801124MBSYQN13 |
| customer_email | Yes | String | Customer email | jondou@gmail.com |
| ip_address | Yes | String | Customer IP (only public ones) | 8.8.8.8 |
| 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 |
| geo_country | Yes | String(3) | Customer country. Code shall be in ISO 3166-1 alpha-3 format. | MEX |
Reuest Sample | OXXO
{
"order_id": "123443334"
"amount": 1020
"currency": "MXN"
"payment_method": "OXXO"
"payment_type_data": {
"mexico_curp": "ZAZD801124MBSYQN13"
},
"customer_email": "jondou@gmail.com"
"ip_address": "8.8.8.8"
"order_description": "Premium package"
"platform": "WEB"
"geo_country": "MEX"
}Response Body Parameters | OXXO
| Parameter | Type | Description | Value sample |
| order | object | Object with information about the order | |
| order: order_id | string | Order ID specified in merchant system | 123443334 |
| 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 currency code under ISO-4217 | MXN |
| order: status | string | Transaction status | processing |
| order: method | string | Payment method | OXXO |
| order: customer_email | String | Customer email | jondou@gmail.com |
| order: ip_address | String | Customer IP (only public ones) | 8.8.8.8 |
| order: order_description | String | Order description in UTF-8 code | Premium package |
| order: created_at | String | Date of payment creation | 2021-11-02 14:27:53 |
| order: updated_at | String | Date of payment update | 2021-11-02 14:27:54 |
| transactions | object | ||
| transactions: id | string | Transaction ID | 123456789 |
| transactions: status | string | Transaction status | processing |
| 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. | 1020 |
| transactions: currency | string | Order currency. 3 letter currency code under ISO-4217 | MXN |
| transactions: type | string | Type of transaction | pay |
| transactions: created_at | string | Date of payment creation | 2021-11-02 14:27:53 |
| return_url | string | return_url is used to redirect the user to a Solid-hosted page | https://solid.return_url.com |
Response Sample | OXXO
{
order":
"amount": 1020
"currency": "MXN"
"order_id": "123443334"
"status": "processing"
"method": "oxxo"
"customer_email": "jondou@gmail.com"
"ip_address": "8.8.8.8"
"order_description": "Premium package"
"created_at": "2021-11-02 14:27:53"
"updated_at": "2021-11-02 14:27:54"
"transactions": [
"id": "123456789"
"status": "processing"
"method": "oxxo"
"amount": 1020
"currency": "MXN"
"type": "pay"
"created_at": "2021-11-02 14:27:53"
"return_url": "https://solid.return_url.com"
]
}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"
}
]
}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/init-payment
Request Body Parameters | M-PESA
| Parameter | Mandatory | Type | Description | Value sample |
|---|---|---|---|---|
| order_id | Yes | String | Order ID specified in merchant system | 4762dc9 |
| amount | Yes | Integer | Order amount - integer without fractional component (i.e cents). For instance, 5020 means 50 USD and 20 cents | 5020 |
| currency | Yes | String(3) | Order currency. 3 letter currency code under ISO-4217 | KES |
| customer_phone | Yes | String | Customer telephone (Mandatory for KEN) | 254426327283 |
| customer_email | Yes | String | Customer email | john-snow@gmail.com |
| payment_method | No | String | Payment method — "mpesa" | mpesa |
| ip_address | Yes | String | Customer IP (only public ones) | 8.8.8.8 |
| 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 |
| geo_country | Yes | String(3) | Customer country. Code shall be in ISO 3166-1 alpha-3 format. | KEN |
| customer_first_name | No | String | Customer's first name | John |
| customer_last_name | No | String | Customer last name | Snow |
Reuest Sample | M-PESA
{
order_id: "4762dc9",
amount: 5020,
currency: "KES",
customer_phone: "254754541123",
payment_method: "mpesa",
customer_email: "john-snow@gmail.com",
ip_address: "8.8.8.8",
order_description: "Premium package",
platform: "WEB",
geo_country: "KEN",
customer_first_name: "John",
customer_last_name: "Snow"
}
Response Body Parameters | M-PESA
| Parameter | Type | Description | Value sample |
|---|---|---|---|
| payment_type_data | object | Object with information about the payment data | Your customers could complete payments in two ways. First method — pop-up message on phone. The second way — manual one. * See more information under the table. * |
| order | object | Object with information about the order | |
| order: order_id | string | Order ID specified in merchant system | 4762dc9 |
| order: amount | integer | Order amount - integer without fractional component (i.e cents). For instance, 5020 means 50 USD and 20 cents | 5020 |
| order: currency | string | Order currency. 3 letter currency code under ISO-4217 | KES |
| order: status | string | Transaction status | refunded |
| order: method | string | Payment method | solid-cards |
| order: customer_email | string | Customer email | john-snow@gmail.com |
| order: ip_address | string | Customer IP (only public ones) | 8.8.8.8 |
| order: order_description | string | Order description in UTF-8 code | Premium package |
| order: created_at | string | Date of payment creation | 2021-10-06 11:26:45 |
| order: updated_at | string | Date of payment update | 2021-10-06 11:26:48 |
| transactions | object | Object with information about the transaction | |
| 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. | 5000 |
| transactions: currency | string | Order currency. 3 letter currency code under ISO-4217 | KES |
| transactions: type | string | Type of transaction | refund |
| transactions: created_at | string | Date of payment creation | 2021-10-06 11:26:45 |
* Your customers could complete payments in two ways.
First method — pop-up message on phone. A pop-up message will appear at a user device, and the user must complete verification by instruction from a pop-up. So the customer will receive an M-PESA prompt on his phone requesting him to enter M-PESA PIN to complete payment. Unfortunately, some phones don't support this flow.
The second way — manual one. For manual scenario, you should show the next message that you will receive with every transaction:
“You can also pay using Lipa na MPESA by using the following instructions:
1. Go to the M-PESA menu.
2. Select Lipa na M-PESA.
3. Select the Paybill option.
4. Enter business number 9****3.
5. Enter your account number R18****18.
6. Enter the amount — 10.
7. Enter PIN and press OK to send.
8. You will receive a confirmation SMS with your payment reference number.”
Response Sample
{
payment_type_data: {
instruction_html: "Dear Customer, Shortly you will receive an M-PESA prompt on your phone requesting you to enter your M-PESA PIN to complete your payment. Please ensure your phone is on and unlocked to enable you to complete the process. Thank you. You can also pay using Lipa na MPESA by using the following instructions: 1. Go to the M-PESA menu. 2. Select Lipa na M-PESA. 3. Select the Paybill option. 4. Enter business number 9****3. 5. Enter your account number R18****18. 6. Enter the amount — 10. 7. Enter PIN and press OK to send. 8. You will receive a confirmation SMS with your payment reference number."
},
order: {
amount: 5000,
currency: "KES",
order_id: "4762dc9",
status: "processing",
method: "mpesa",
customer_email: "john-snow@gmail.com",
ip_address: "8.8.8.8",
order_description: "order_description",
created_at: "2021-10-06 11:26:45",
updated_at: "2021-10-06 11:26:48"
},
transactions: [
{
id: "93865c0a-cee4-4d9e-9577-c650c3f34e91",
status: "processing",
method: "mpesa",
amount: 5020,
currency: "KES",
type: "pay",
created_at: "2021-10-06 11:26:45"
}
]
}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 | No | String(3) | Customer country. Code shall be in ISO 3166-1 alpha-3 format. | 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. Required for Subscription Payments | 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 | 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 |
| fail_url | No | String | URL of merchant page, to which a customer will be redirected after unsuccessful payment | http://merchant.example/fail |
| return_url | No | String | URL of merchant page, to which a customer will be redirected after payment is complete | http://merchant.example/return |
| success_url | No | 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 |
| Others parameters | * See Init Payment Response Body Parameters |
Successful Response Sample
{
"order": {
"amount": 1000,
"currency": "EUR",
"order_id": "295",
"status": "processing",
"method": "sepa",
"token": "377fd15f056396919b1b2204803a9f6b5513541c9ee22fb298c92881614340a02a2c15a2e90b7683cb1974c9a3421bfd540c",
"customer_email": "example.user@example-email.com",
"ip_address": "8.8.8.8",
"order_description": "Premium package",
"created_at": "2021-11-22 16:40:49",
"updated_at": "2021-11-22 16:40:50"
},
"transactions": [
{
"id": "e008b1be-7481-4c0c-8c27-f853d4ca33fb",
"status": "processing",
"method": "sepa",
"amount": 1000,
"currency": "EUR",
"type": "pay",
"created_at": "2021-11-22 16:40:49"
}
]
}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). |
SolidGate Przelewy24
Operation of order initiating.
This operation creates an order in the system and returns a redirect URL. You should redirect the end-user to this URL.
POST https://gate.solidgate.com/api/v1/init-payment
Przelewy24 request parameters
| Parameter | Mandatory | Type | Description | Value sample |
| payment_method | Yes | String | Payment method | przelewy24 |
| 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. | POL |
| geo_city | No | String | Customer city | Warsaw |
| amount | Yes | Integer | Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents | 100 |
| currency | Yes | String(3) | Order currency. 3 letter currency code under ISO-4217 | PLN |
| customer_account_id | No | String | Customer ID in the merchant's system. | 0101010 |
| customer_date_of_birth | No | String | Customer birth date in format YYYY-MM-DD | 1996-11-21 |
| customer_email | Yes | String | Customer email | john.user@example-email.com |
| customer_phone | No | String | Customer telephone | 380661111222 |
| ip_address | Yes | String | Customer IP (only public ones) | 8.8.8.8 |
| language | No | String(2) | Customer language settings. | en |
| order_id | Yes | String | Order ID specified in merchant system | 12313423424 |
| order_date | No | String | Date of order creation in format YYYY-MM-DD-HH-MM-SS | 2022-05-02 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 |
| fail_url | No | String | URL of merchant page, to which a customer will be redirected after unsuccessful payment | http://merchant.example/fail |
| return_url | No | String | URL of merchant page, to which a customer will be redirected after payment is complete | http://merchant.example/return |
| success_url | No | 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
{
"amount": 100,
"currency": "PLN",
"payment_method": "przelewy24",
"customer_account_id": "0101010",
"customer_date_of_birth": "1996-11-21",
"customer_email": "john.user@example-email.com",
"customer_first_name": "John",
"customer_last_name": "Snow",
"customer_phone": "380661111222",
"geo_country": "POL",
"geo_city": "Warsaw",
"ip_address": "8.8.8.8",
"language": "en",
"order_id": "113234324535345",
"order_date": "2022-05-02",
"order_description": "test",
"platform": "WEB"
}Przelewy24 response 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 | 100 |
| order: currency | String | Order currency (3 letter code under ISO 4217) | PLN |
| order: order_id | String | Order ID specified in merchant system | 1657436866422 |
| order: status | String | Order status | processing |
| pay_form | Object | Object with information about Redirect_URL | |
| pay_form: return_url | String | URL of merchant page, to which a customer will be redirected to complete a payment | https://example.com/pay_form_url |
| Others parameters | * See Init Payment Response Body Parameters |
Successful Response Sample
{
"order": {
"amount": 100,
"currency": "PLN",
"order_id": "1657436866422",
"status": "processing",
"method": "przelewy24",
"customer_email": "john.user@example-email.com",
"ip_address": "8.8.8.8",
"order_description": "test",
"created_at": "2022-05-30 12:17:49",
"updated_at": "2022-05-30 12:17:53"
},
"pay_form": {
"return_url": "https://example.com/pay_form_url"
}
}SolidGate Blik
Operation of order initiating.
This operation creates an order in the system and returns a redirect URL. You should redirect the end-user to this URL.
POST https://gate.solidgate.com/api/v1/init-payment
Blik request parameters
| Parameter | Mandatory | Type | Description | Value sample |
| payment_method | Yes | String | Payment method | blik |
| 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. | POL |
| geo_city | No | String | Customer city | Warsaw |
| amount | Yes | Integer | Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents | 189798 |
| currency | Yes | String(3) | Order currency. 3 letter currency code under ISO-4217 | PLN |
| customer_account_id | No | String | Customer ID in the merchant's system. | 01010102 |
| customer_date_of_birth | No | String | Customer birth date in format YYYY-MM-DD | 1996-11-21 |
| customer_email | Yes | String | Customer email | john.user@example-email.com |
| customer_phone | No | String | Customer telephone | 380661111222 |
| ip_address | Yes | String | Customer IP (only public ones) | 8.8.8.8 |
| language | No | String(2) | Customer language settings. | en |
| order_id | Yes | String | Order ID specified in merchant system | 12313423424 |
| order_date | No | String | Date of order creation in format YYYY-MM-DD-HH-MM-SS | 2022-05-02 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 |
| fail_url | No | String | URL of merchant page, to which a customer will be redirected after unsuccessful payment | http://merchant.example/fail |
| return_url | No | String | URL of merchant page, to which a customer will be redirected after payment is complete | http://merchant.example/return |
| success_url | No | 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
{
"amount": 189798,
"currency": "PLN",
"payment_method": "blik",
"customer_account_id": "01010102",
"customer_date_of_birth": "1996-11-21",
"customer_email": "john.user@example-email.com",
"customer_first_name": "John",
"customer_last_name": "Snow",
"customer_phone": "380661111222",
"geo_country": "POL",
"geo_city": "Warsaw",
"ip_address": "8.8.8.8",
"language": "en",
"order_id": "123456789",
"order_date": "2022-05-02",
"order_description": "test",
"platform": "WEB"
}Blik response 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 | 189798 |
| order: currency | String | Order currency (3 letter code under ISO 4217) | PLN |
| order: order_id | String | Order ID specified in merchant system | 1653981009694 |
| order: status | String | Order status | processing |
| pay_form | Object | Object with information about Redirect_URL | |
| pay_form: return_url | String | URL of merchant page, to which a customer will be redirected to complete a payment | https://example.com/pay_form_url |
| Others parameters | * See Init Payment Response Body Parameters |
Successful Response Sample
{
"order": {
"amount": 189798,
"currency": "PLN",
"order_id": "1653981009694",
"status": "processing",
"method": "blik",
"customer_email": "john.user@example-email.com",
"ip_address": "8.8.8.8",
"order_description": "test",
"created_at": "2022-05-31 07:10:12",
"updated_at": "2022-05-31 07:10:12"
},
"pay_form": {
"return_url": "https://example.com/pay_form_url"
}
}