Subscription Service

Solid Subscription Service is a service provided by Solid, that allows you to create and maintain a stable and healthy subscription model for your businesses.

At the very beginning of work with the Solid Subscription System, the merchant must manually create a product with subscription rules in the Merchant Portal.

After the product is created, the merchant will receive an automatically generated unique product identifier product_id. This product identifier will be used further in all subscription operations within the framework of this product, such as: creating different types of subscriptions, creation of orders with a subscription, etc.

Create Card Subscription

Before creating subscriptions, the merchant must manually create a product with subscription rules in the Merchant Portal. Read more on creating and managing a subscription at our help portal.

After the product is created, the merchant will receive an automatically generated unique product identifier product_id by which can create subscriptions.

To subscribe the end-user to the Solid subscription service, you will need to include to the Solid Payment Form (Solid SDK) request paymentintent parameters subscription product parameter product_id.

Subscription callbacks

To receive webhook events, you should add an endpoint via the HUB similar to other webhooks.

The callback structure is similar to the subscription/status method, but the callback type parameter will be added to the response object. There are four types of callbacks - init, renew, update, and cancel.

Sample of the subscription flow and callback types received:

The user has successfully paid for the trial - in the notification we send "callback_type": "init" and "status": "active";
The user has successfully paid for the renewal of the subscription after the trial or restored the specific subscription in case it was cancelled - in the notification we send "callback_type": "renew" and "status": "active";
The user came to the support service and asked to unsubscribe - the support employee cancelled the subscription without force (the subscription will still be active until the end of the period) - in the notification we send "callback_type": "update", "status": "active" and "subscription": "cancelled_at" (Note: this parameter is required, but in other cases, for example in refunds, this parameter is null);
When the subscription expiry date comes - in the notification we send "callback_type": "cancel" and "status": "cancelled".

Subscription callback sample
                                    {
  "subscription": {
    "id": "9e252e9f-c5a3-4dca-93df-4c9fcf54267e",
    "status": "cancelled",
    "started_at": "2020-12-08 12:37:24",
    "expired_at": "2020-12-08 12:38:24",
    "cancelled_at": "2020-12-08 12:42:36",
    "trial": false,
    "cancel_code": "8.09",
    "cancel_message": "Cancellation after redemption period",
    "payment_type": "card"
  },
  "product": {
    "name": "autotest_CARD",
    "amount": 100,
    "currency": "USD",
    "trial": true,
    "payment_action": "auth_void",
    "trial_period": 1,
    "trial_amount": 100,
    "trial_currency": "USD",
    "product_id": "ce43b415-5522-4373-b026-a365462f9790"
  },
  "customer": {
    "customer_account_id": "1607431041409",
    "customer_email": "someEmail1@gmail.com"
  },
  "invoices": {
    "9531a7ea-030e-48ae-8c79-f74e488790c6": {
      "id": "9531a7ea-030e-48ae-8c79-f74e488790c6",
      "amount": 76,
      "status": "fail",
      "created_at": "2020-12-08 12:38:51",
      "updated_at": "2020-12-08 12:42:36",
      "orders": {
        "22e45e37-d10d-4283-a47d-7bcba16e8b04": {
          "id": "22e45e37-d10d-4283-a47d-7bcba16e8b04",
          "status": "declined",
          "amount": 76,
          "created_at": "2020-12-08 12:40:36",
          "processed_at": "2020-12-08 12:42:36",
          "failed_reason": "3.02",
          "operation": "recurring",
          "retry_attempt": 2
        },
        "c179ed85-bc2b-4325-84bb-12d8eaf15203": {
          "id": "c179ed85-bc2b-4325-84bb-12d8eaf15203",
          "status": "declined",
          "amount": 90,
          "created_at": "2020-12-08 12:38:52",
          "processed_at": "2020-12-08 12:40:35",
          "failed_reason": "3.02",
          "operation": "recurring",
          "retry_attempt": 1
        },
        "38995ba1-1cd2-4dd1-8bde-8d4ac4da519f": {
          "id": "38995ba1-1cd2-4dd1-8bde-8d4ac4da519f",
          "status": "declined",
          "amount": 100,
          "created_at": "2020-12-08 12:38:51",
          "processed_at": "2020-12-08 12:38:52",
          "failed_reason": "3.02",
          "operation": "recurring"
        }
      }
    }
  },
  "callback_type": "cancel"
}
                                

Card 1-click payments

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

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

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

1-click Request Body Parameters

Parameter	Mandatory	Type	Description	Example
order_id	Yes	string(100)	Order ID specified in the merchant system	123443334
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
recurring_token	Yes	string(255)	Card token	7ats8da7sd8-a66dfa7-a9s9das89t
order_description	Yes	string(100)	Order description in UTF-8 code	Premium package
customer_email	Yes	string(100)	Customer email	jondou@gmail.com
ip_address	Yes	string(50)	Customer IP (only public ones)	8.8.8.8
platform	Yes	string(6)	Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application.	WEB
geo_country	No	string(3)	Customer country subject to ISO 3166-1 alpha-3	GBR
order_date	No	string(50)	Date of order creation in format YYYY-MM-DD-HH-MM-SS	2015-12-21 11:21:30
order_items	No	string(255)	Order description in UTF-8 code	item 1, item 2
customer_account_id	No	string(100)	Customer ID in the merchant's system. Required for Subscription Payments	4dad42f808
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 number	380111111111
customer_date_of_birth	No	string(50)	Birthdate in YYYY-MM-DD format	2000-11-21
geo_city	No	string(100)	Customer city	New Castle
language	No	string(2)	Customer language settings. Available values: RU - Russian, EN - English	en
fraudulent	No	boolean	The customer is detected by the merchant system to be suspicious one. The payment will be effected via 3DS.	TRUE
fail_url	No	string(255)	URL of merchant page, which a customer will be redirected in case of unsuccessful payment	http://merchant.example/fail
success_url	No	string(255)	URL of merchant page, which a customer will be redirected in case of successful payment	http://merchant.example/success
verified	No	boolean	The user was verified on the shop side.	TRUE
payment_type	No	string(25)	Type of recurring payment.	1-click \|\| retry \|\| recurring \|\| rebill \|\| installment
retry_attempt	No	integer	Number of retry payment	1
traffic_source	No	string(255)	Source of traffic.	facebook
transaction_source	No	string(255)	Source of transactions on site.	main_menu
order_number	No	integer	Number of payments by user	2
user_agent	No	string	User-agent of customer	Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36
device	No	string	Device of customer	iPhone 8 iOS 12.0
website	No	string(255)	Website from which transaction took place.	Google.com
type	No	string	The parameter for transaction-authorization before a recurring payment	auth
settle_interval	No	integer	Time (in hours) when auto-settle should be done.	1
force3ds	No	boolean	Routing payments flag for 3DS flow (enabled by Solid account manager)	FALSE
header_accept	Yes - 3D 2.0	string(255)	Header Accept.	text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng
header_accept_language	Yes - 3D 2.0	string(255)	Header Accept Language.	ru-RU,ru;q=0.9,en-US;q=0.8
browser_color_depth	Yes - 3D 2.0	integer	Color depth of browser window.	32
browser_screen_height	Yes - 3D 2.0	integer	Height of browser window.	1920
browser_screen_width	Yes - 3D 2.0	integer	Width of browser window.	1280
browser_java_enabled	Yes - 3D 2.0	boolean	Is java enabled on User browser.	FALSE
browser_javascript_enabled	Yes - 3D 2.0	boolean	Is javascript enabled on User browser.	FALSE
time_zone_offset	Yes - 3D 2.0	integer	The time difference, in minutes, between UTC time and the local time of the cardholder's browser.	60

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

1-click Response Body Parameters

Parameter	Type	Description	Example
order	object	An object with information of the transaction.
order:order_id	string	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 code under ISO 4217)	USD
order:fraudulent	boolean	The customer was detected on the merchant end to be a suspicious one	TRUE
order:marketing_amount	integer	Order amount converted in USD (or any other currency agreed) under open FX sources at the moment of transaction. This can be applied only for marketing forecasting.	2575
order:marketing_currency	string	The currency of the order amount for marketing analytics.	USD
order:refunded_amount	integer	The amount which was refunded	0
order:descriptor	string	The descriptor for the transaction	payhere.com
order:status	string	Status of payment processed. Types of order statuses are described in the respective directory.	processing
transaction	object	An object with information of the transaction.
transaction:id	string	Transaction identification within the order. The order can have several transactions.	1495123020887591dc450088f1
transaction:operation	string	Transaction type. Available values - recurring.	recurring
transaction:status	string	Transaction status within the order.	created
transaction:amount	integer	Transaction amount.	2575
transaction:currency	string	Transaction currency.	USD
transaction:created_at	string	Transaction created DateTime	2019-05-17 9:06:21
transaction:updated_at	string	Transaction updated DateTime	2019-05-17 9:06:21
transaction:card	object	An object with information about the card. Present in payment transactions.
transaction:card:bank	string	Bank-emitent.	NATIONWIDE BUILDING SOCIETY
transaction:card:bin	integer	Card BIN.	444455
transaction:card:brand	string	Card Brand.	VISA
transaction:card:country	string	Country of the bank.	USA
transaction:card:number	string	Masked card number.	444455XXXXXX6666
transaction:card:card_holder	string	Cardholder name	Test User
transaction:card:card_exp_month	string	A month of the expiration date on the card. (2-digit format)	3
transaction:card:card_exp_year	integer	A year of the expiration date on the card. (4-digit format)	2025
transaction:card:card_type	string	A type of the card.	DEBIT
transaction:card_token	object
transaction:card_token:token	string	Card token to be used for recurring payments. It will be returned in case of successful payment.	b5ddb0a1c...1fc4da81ecdad52c0
transactions	object	An object with information of transactions.
transactions:<transaction_id>	object	Transaction identification within the order. It contains an object with detailed information about the specified transaction. The order can have several transactions.	1495123020887591dc450088f1
transactions:<transaction_id>:id	string	Transactions identification within the order.	1495123020887591dc450088f1
transactions:<transaction_id>:operation	string	Transaction type. Transaction types are described in the respective directory.	recurring
transactions:<transaction_id>:status	string	Transaction status within the order. Transaction statuses are described in the respective directory.	created
transactions:<transaction_id>:descriptor	string	The descriptor for the transaction	payhere.com
transactions:<transaction_id>:amount	integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.	2575
transactions:<transaction_id>:currency	string	The currency of the order amount for marketing analytics.	USD
transactions:<transaction_id>:created_at	string	Transaction created DateTime	2019-05-17 9:06:21
transactions:<transaction_id>:updated_at	string	Transaction updated DateTime	2019-05-17 9:06:21
transactions:<transaction_id>:card	object	An object with information about the card. Present in payment transactions.
transactions:<transaction_id>:card:bin	integer	Card BIN	444455
transactions:<transaction_id>:card:brand	string	Card Brand	VISA
transactions:<transaction_id>:card:number	string	Masked card number	444455XXXXXX6666
transactions:<transaction_id>:card:card_holder	string	Cardholder Name	Test User
transactions:<transaction_id>:card:bank	string	Bank emitent	NATIONWIDE BUILDING SOCIETY
transactions:<transaction_id>:card:country	string	Country of bank	GBR
transactions:<transaction_id>:card:card_exp_month	string	A month of expiration date on card. (2-digit format)	3
transactions:<transaction_id>:card:card_exp_year	integer	A year of expiration date on card. (4-digit format)	2025
transactions:<transaction_id>:card:card_type	string	A type of the card.	DEBIT
transactions:<transaction_id>:card_token	object
transactions:<transaction_id>:card_token:token	string	Card token to be used for recurring payments. It will be returned in case of successful payment.	8b5ddb0a1c...1fc4da81ecdad52c0
payment_adviser	object
payment_adviser:advise	string	Recommendation for next payment	pay / resign / recurring

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

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

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

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

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

1-click Response Sample | Decline Error
                                    "error": {
       "code": "4.09",
       "type": "soft",
       "messages": [
           "Solid antifraud engine"
       ],
       "recommended_message_for_user": "Solid antifraud engine"
   }
                                

Create APM Subscription

Operation of subscription creation.

This operation deems to create an order in the system and returns the recurring token.

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

APM Subscription Request Body Parameters

Parameter	Mandatory	Type	Description	Value sample
product_id	Yes	String(36)	The ID of the predefined product	faf3b86a-1fe6-4ae5-84d4-ab0651d75db2
payment_method	Yes	String	Payment method ("paypal-vault", "mercadopago")	paypal-vault
customer_account_id	yes	String	Customer ID in the merchant's system.	user_id
order_id	Yes	String	Order ID specified in merchant system	testPayPal777
order_description	Yes	String(100)	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’s country. Code shall be in ISO 3166-1 alpha-3 format. (Mandatory for method PayPal). This field is deprecated, instead of geo_country use billing_address:country	GBR
billing_address	Yes	Object	The billing address of the user
billing_address:country	Yes	Strung(3)	ISO country code of the country that was sent in the request
ip_address	Yes	String	IP address (only public ones)	8.8.8.8
customer_email	Yes	String	An email that belongs to a customer
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
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
payment_type_data	No*	Object	Object with payment type data.
payment_type_data:{value}	No*	String	Specify the value that belongs to the user's country. For example: BRA — brazil_cpf ARG — argentina_dni, etc More information — https://dev.solidgate.com/developers/documentation/Information#payment-type-data	42243309114

* Mandatory for Mercado Pago

APM Subscription Request Sample
                                    {
  "product_id": "faf3b86a-1fe6-4ae5-84d4-ab0651d75db2",
  "payment_method": "paypal-vault",
  "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"
}

                                

APM Subscription Response Body Parameters

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, mercadopago
order: order_id	String	Order ID specified in merchant system	testPayPal777
order: token	String	A token that is used in recurring charge	1349c909ddc8d934899a4f37ca63b3777593fc8f3dfea65c9e588972e5d9926cd67894
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

PayPal Subscription Response Sample
                                    {
    "order": {
        "amount": 999,
        "currency": "USD",
        "order_id": "testPayPal777",
        "status": "created",
        "method": "paypal-vault"
    },
}
                                

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"
        data-script=" "
        data-btn-id="solid_pay_btn"
        data-overlay="true"
        data-tittle="Tittle for payment widget"
        data-description="widget.data-description">
</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
                                    bubbles: false
cancelBubble: false
cancelable: false
composed: false
currentTarget: null
defaultPrevented: false
detail:
data:
{
  "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"
  },
  "transactions": [
    {
      "status": "success",
      "method": "paypal-vault",
      "amount": 100,
      "currency": "USD",
      "type": "pay"
    }
  ]
}
__proto__: Object
eventPhase: 0
isTrusted: false
path: (10) [div#paypal-button, div.intro-box__inner-footer, div.intro-box__inner, div.intro-box__content, div.intro-box, div.app, body.en.ab_var_a.obv3, html..no-touchevents, document, Window]
returnValue: true
srcElement: div#paypal-button
target: div#paypal-button
timeStamp: 66495.45000000035
type: "order-processed"
__proto__: CustomEvent
                                

Event Order-Processed Sample | Decline
                                    bubbles: false
cancelBubble: false
cancelable: false
composed: false
currentTarget: null
defaultPrevented: false
detail:
data: 
{
  "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"
  },
  "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"
    }
  ]
}
__proto__: Object
eventPhase: 0
isTrusted: false
path: (10) [div#paypal-button, div.intro-box__inner-footer, div.intro-box__inner, div.intro-box__content, div.intro-box, div.app, body.en.ab_var_a.obv3, html..no-touchevents, document, Window]
returnValue: true
srcElement: div#paypal-button
target: div#paypal-button
timeStamp: 46688.41500000053
type: "order-processed"
__proto__: CustomEvent 
                                

PayPal 1-click Payments

PayPal 1-click is the operation that allows performing one-click payments using the PayPal vault method.

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

You can receive the token from the successful payment via webhook notification.

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

PayPal 1-click 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)	Method that used to perform a transaction	paypal-vault
token	Yes	string(255)	Token from the successful payment used in the initial payment for the PayPal Subscription.
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's 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(100)	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
return_url	Yes	string(255)	URL of merchant page, which a customer will be redirected after completed payment	http://merchant.example/return

PayPal 1-click Request Sample
                                    {
  "amount": 2575,
  "payment_method": "paypal-vault",
  "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"
}
                                

PayPal 1-click Response Body Parameters

Parameter	Type	Description	Value sample
order	object	Object with information on the order
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: order_id	string	Order ID specified in merchant system	777
order: status	string	Order status	created

PayPal 1-click Response Sample | Success
                                    {
 "order": {
 "amount": 5000,
 "currency": "USD",
  "order_id": "1504269591134TEST",
  "status": "created"
  },
}
                                

Cancel the subscription

By using this method, you can cancel the specific subscription of your client.

POST https://subscriptions.solidgate.com/api/v1/subscription/cancel

Cancel Subscription Request Body Parameters

Parameter	Mandatory	Type	Description	Example
subscription_id	yes	String	The ID of the user’s subscription	83b19018-cbc4-4df0-899a-dda84fd2705e
force	no	Boolean	Parameter of an immediate subscription cancellation	FALSE
cancel_code	no	String	One of the appropriate cancellation codes	8.13

Cancel Subscription Request Sample
                                    {
"subscription_id":"83b19018-cbc4-4df0-899a-dda84fd2705e",
"force":"false"
}
                                

Cancel Subscription Response Body Parameter

Parameter	Type	Description
status	String	Status of a subscription cancellation

Cancel Subscription Response Sample | Success
                                    {
"status": "ok"
}

                                

Restore the subscription

By using this method, you can restore the specific subscription of your client in case it was cancelled.

POST https://subscriptions.solidgate.com/api/v1/subscription/restore

Restore Subscription Request Body Parameters

Parameter	Mandatory	Type	Description	Example
subscription_id	yes	String	The ID of the user’s subscription	83b19018-cbc4-4df0-899a-dda84fd2705e
expired_at	no	String	Subscription expiration date in format YYYY-MM-DD-HH-MM-SS	2020-09-30 13:30:00

 Restore Subscription Request Sample
                                    {
"subscription_id":"83b19018-cbc4-4df0-899a-dda84fd2705e",
"expired_at":"2020-09-30 13:30:00"
}
                                

Restore Subscription Response Body Parameter

Parameter	Type	Description
status	String	Subscription restoring status

 Restore Subscription Response Sample | Success
                                    {
"status": "ok"
}
                                

Subscription cancellation by a Customer ID

By using this method, the merchant can cancel all subscriptions for the specific customer.

POST https://subscriptions.solidgate.com/api/v1/subscription/cancel-by-customer

Cancel Subscription by Customer Request Body Parameters

Parameter	Mandatory	Type	Description	Example
customer_account_id	yes	String	Customer ID in the merchant’s system	1593011107489
force	no	Boolean	Parameter of an immediate subscription cancellation	false
cancel_code	no	String	One of the appropriate cancellation codes	8.13

Cancel Subscription by Customer Request Sample
                                    {
"customer_account_id":"1593011107489",
"force":"false"
}
                                

Cancel Subscription by Customer Response Body Parameters

Parameter	Type	Description
status	String	Status of a subscription cancellation

Cancel Subscription by Customer Response Sample | Success
                                    {
"status": "ok"
}
                                

Subscription Status

By using this method you can check the status of the subscription.

After performing the Subscription Status request, you will receive information about the last invoice for the subscription and an order status ID, which you can later use to verify the external order ID in the Merchant Portal.

POST https://subscriptions.solidgate.com/api/v1/subscription/status

Status Subscription Request Body Parameters

Parameter	Mandatory	Type	Description	Example
subscription_id	yes	String	ID of the user’s subscription	83b19018-cbc4-4df0-899a-dda84fd2705e

Status Subscription Request Sample
                                    {
"subscription_id":"83b19018-cbc4-4df0-899a-dda84fd2705e"
}
                                

Status Subscription Response Body Parameters

Parameter	Type	Description	Example
subscription	Object	The object that contains information about the subscription
subscription:id	String(36)	The ID of the subscription	559ec566-f101-434b-8928-ae747c2d1b17
subscription:status	String(36)	The status of the subscription	cancelled
subscription:started_at	String(36)	Date of the start of the subscription	2020-10-26 16:02:19
subscription:expired_at	String(36)	Date of the expiration of the subscription	2020-10-26 16:07:38
subscription:next_charge_at	String(36)	Date when the next payment will be done	2020-10-26 16:07:38
subscription:cancelled_at	String(36)	Date of the subscription’s cancellation	2020-10-26 16:14:38
subscription:trial	Boolean	Trial parameters of the subscription	TRUE
subscription:cancel_code	String	Cancel code list	"8.09"
subscription:cancel_message	String	The error message associated with the corresponding ‘cancel code’	"Cancellation after redemption period"
subscription:payment_type	String	Payment type	card
product	Object	The object that contains the information about the product of the subscription
product:id	String(36)	The ID of the product	6df8b342-9e68-4a49-969c-ccb52d194eb7
product:name	String(100)	Name of the product	Test Product
product:public_product_description	String	Purchase details of the product. The value is filled in HUB. If the value is empty - for renew, the description is set to "Renew subscription id: <order_id>" and for recurring payment, the description is set to "Retry to renew subscription id: <order_id>".	Words Booster Stickers
product:amount	Integer	Amount of currency paid for the product	100
product:currency	String	The currency of the subscription	USD
product:trial	Boolean	Trial parameters of the product	TRUE
product:payment_action	String(100)	Payment type that was used to pay for the product	charge_refund
product:trial_period	Integer	The trial period (in minutes) of the product	2
product:trial_amount	Integer	Amount of currency paid for the trial	100
product:trial_currency	String(3)	The currency of the subscription trial	USD
customer	Object	Object with the information about the customer
customer:customer_account_id	String(100)	ID of the customer	1603728112252
customer:customer_email	String(100)	Customer email	someEmail1@gmail.com
invoices	Object	Object with the information about invoices
invoices:invoice_id	Object	Object with the information about invoice
invoices:invoice_id:id	String(100)	The ID of the invoice	0ca5b8e0-7478-42c4-8bc3-5862e6ac85f1
invoices:invoice_id:amount	Integer	Amount of currency in the invoice	500
invoices:invoice_id:status	String(100)	Status of the invoice	success
invoices:invoice_id:created_at	String(100)	Date of the creation of the invoice	2020-10-26 16:04:51
invoices:invoice_id:updated_at	String(100)	Date of the invoice update	2020-10-26 16:06:38
invoices:invoice_id:billing_period_started_at	String(100)	Start date of the billing period	2020-10-26 16:06:38
invoices:invoice_id:billing_period_ended_at	String(100)	Billing period end date	2020-10-26 16:07:38
invoices:invoice_id:subscription_term_number	Integer	Subscription term number	1
invoices:invoice_id:orders:	Object	Object with the information about the order
invoices:invoice_id:orders:id	String(100)	ID of the order	3cf93552-a629-44c8-80ab-f8589b4db1cb
invoices:invoice_id:orders:status	String(100)	Current status of the order	auth_ok
invoices:invoice_id:orders:amount	Integer	Amount of currency in the order	500
invoices:invoice_id:orders:created_at	String(100)	Date of creation of the order	2020-06-10 15:42:24
invoices:invoice_id:orders:processed_at	String(100)	Order processing date	2020-06-10 15:42:24
invoices:invoice_id:orders:operation	String(100)	Type of operation	auth
invoices:invoice_id:orders:retry_attempt	Integer	Retry attempt number	1

Status Subscription Response Body Sample | Success
                                    {
  "subscription": {
    "id": "559ec566-f101-434b-8928-ae747c2d1b17",
    "status": "active",
    "started_at": "2020-10-26 16:02:19",
    "expired_at": "2020-10-26 16:07:38",
    "next_charge_at": "2020-10-26 16:07:38",
    "trial": false,
    "payment_type": "card"
  },
  "product": {
    "name": "Test Product",
    "amount": 100,
    "currency": "USD",
    "trial": true,
    "payment_action": "charge_refund",
    "trial_period": 2,
    "trial_amount": 100,
    "trial_currency": "USD",
    "id": "6df8b342-9e68-4a49-969c-ccb52d194eb7"
  },
  "customer": {
    "customer_account_id": "1603728112252",
    "customer_email": "someEmail1@gmail.com"
  },
  "invoices": {
    "0ca5b8e0-7478-42c4-8bc3-5862e6ac85f1": {
      "id": "0ca5b8e0-7478-42c4-8bc3-5862e6ac85f1",
      "amount": 500,
      "status": "success",
      "created_at": "2020-10-26 16:04:51",
      "updated_at": "2020-10-26 16:06:38",
      "billing_period_started_at": "2020-10-26 16:06:38",
      "billing_period_ended_at": "2020-10-26 16:07:38",
      "subscription_term_number": 1,
      "orders": {
        "1e494ce4-083e-441e-b84b-30559ff2009a": {
          "id": "1e494ce4-083e-441e-b84b-30559ff2009a",
          "status": "declined",
          "amount": 1000,
          "created_at": "2020-10-26 16:04:51",
          "processed_at": "2020-10-26 16:04:52",
          "failed_reason": "3.02",
          "operation": "recurring"
        },
        "7917e824-029e-4f68-9d69-482c71239ff1": {
          "id": "7917e824-029e-4f68-9d69-482c71239ff1",
          "status": "approved",
          "amount": 500,
          "created_at": "2020-10-26 16:04:53",
          "processed_at": "2020-10-26 16:06:37",
          "operation": "recurring",
          "retry_attempt": 1
        }
      }
    }
  }
}
                                

Status Subscription Response Body Sample (Payment was successful, but the subscription was cancelled due to one of the cancel codes) 
                                    {
    "subscription": {
        "id": "c128f8ba-445d-4f9d-ae4d-73006f7a0a11",
        "status": "cancelled",
        "started_at": "2020-10-28 13:05:35",
        "expired_at": "2020-10-29 13:05:35",
        "cancelled_at": "2020-10-29 13:05:35",
        "trial": false,
        "cancel_code": "8.01",
        "cancel_message": "Card brand is not supported",
        "payment_type": "card"
    },
    "product": {
        "id": "831fdc79-5eec-4c80-9d4d-43f45c5df9ef",
        "name": "Test Product 2",
        "amount": 100,
        "currency": "USD",
        "trial": false
    },
    "customer": {
        "customer_account_id": "1603890326552",
        "customer_email": "someEmail1@gmail.com"
    },
    "invoices": {
        "65118005-ac0c-4cff-9cfc-ebbb5102e0b5": {
            "id": "65118005-ac0c-4cff-9cfc-ebbb5102e0b5",
            "amount": 100,
            "status": "success",
            "created_at": "2020-10-28 13:05:35",
            "updated_at": "2020-10-28 13:05:35",
            "billing_period_started_at": "2020-10-28 13:05:35",
            "billing_period_ended_at": "2020-10-29 13:05:35",
            "subscription_term_number": 1,
            "orders": {
                "1603890326537init": {
                    "id": "1603890326537init",
                    "status": "approved",
                    "amount": 100,
                    "created_at": "2020-10-28 13:05:35",
                    "processed_at": "2020-10-28 13:05:34",
                    "operation": "pay"
                }
            }
        }
    }
}
                                

Status Subscription Response Body Sample | Success for Insufficient Funds
                                    {
  "subscription": {
    "id": "559ec566-f101-434b-8928-ae747c2d1b17",
    "status": "redemption",
    "started_at": "2020-10-26 16:02:19",
    "expired_at": "2020-10-26 16:07:38",
    "next_charge_at": "2020-10-27 16:07:52",
    "trial": false,
    "payment_type": "card"
  },
  "product": {
    "name": "Test Product",
    "amount": 100,
    "currency": "USD",
    "trial": true,
    "payment_action": "charge_refund",
    "trial_period": 2,
    "trial_amount": 100,
    "trial_currency": "USD",
    "product_id": "6df8b342-9e68-4a49-969c-ccb52d194eb7"
  },
  "customer": {
    "customer_account_id": "1603728112252",
    "customer_email": "someEmail1@gmail.com"
  },
  "invoices": {
    "3f754199-7f99-4105-be4c-d0b50ec52504": {
      "id": "3f754199-7f99-4105-be4c-d0b50ec52504",
      "amount": 500,
      "status": "retry",
      "created_at": "2020-10-26 16:07:51",
      "updated_at": "2020-10-26 16:07:53",
      "orders": {
        "e34eea8c-d7f7-4e9a-86a8-1a11e91e93db": {
          "id": "e34eea8c-d7f7-4e9a-86a8-1a11e91e93db",
          "status": "declined",
          "amount": 1000,
          "created_at": "2020-10-26 16:07:51",
          "processed_at": "2020-10-26 16:07:52",
          "failed_reason": "3.02",
          "operation": "recurring"
        }
      }
    }
  }
}
                                

Available Subscription Statuses

Subscription Status	Description
Active	Subscription is active
Cancelled	Subscription is cancelled and the user unsubscribed
Redemption	If the subscription product contains retries, then if the recurring payment was declined due to one of the error codes, the subscription goes into the redemption period. If all retry attempts are declined, the subscription status will become ‘Cancelled’. If any of the attempts on the retry are successful, the subscription status will become ‘Active’

Available Subscription Cancel Codes

Code	Message	Description
8.01	Card brand is not supported	Maestro card is used for subscription, we process such payment and give one billing period for the user and then cancel subscription (one billing period - trial if exists).
8.02	Fraud Chargeback received	If chargeback for fraudelent transaction was received for one of the user's invoices, then we unsubscribe the user from all subscriptions.
8.03	Dispute Received	If dispute/chargeback was received for one of the user's invoices, then we unsubscribe the user from all subscriptions.
8.04	Fraud Alert received	If we receive a fraudulent alert, we unsubscribe the user from further recurring payments.
8.05	Fraud Decline received	If we receive one of the fraudulent declines for the user (Stolen card, Lost card, etc), we unsubscribe the user.
8.06	Cancellation by support	Support team has cancel subscription due to customer inquire or other internal reasons.
8.07	Recurring payment is blocked by Antifraud	Antifraud has blocked the conduct of a recurrent payment due to decline 4.09
8.08	Subscription has expired	The subscription was created for a limited time. The deadline has expired, the subscription has expired. User is unsubscribed.
8.09	Cancellation after redemption period	Decline on the recurring payment. Retries on the redemption period have been activated. Retries had no result. User is unsubscribed.
8.10	Card Token has expired	The card has an expiration date. After it was expired, the user is not reissuing the card. User is unsubscribed.
8.11	Token revoked by customer	Billing Token was cancelled by user on PayPal’s side.
8.12	Bank antifraud system	The payment was blocked by the bank's anti-fraud system or the card was added to the bank's blacklist.
8.13	Invalid amount	Inadmissible amount considering the discount exceeding the threshold value.
8.14	Cancellation by customer	Customer has directly cancelled the subscription using merchant's website or mobile app.

Retrieve Subscriptions by Customer ID

This method allows the merchant to get all subscriptions and their status for the specific customer.

POST https://subscriptions.solidgate.com/api/v1/subscription/list

Retrieve Subscriptions by Customer ID Request Body Parameters

Parameter	Mandatory	Type	Description	Example
customer_account_id	yes	String	Customer ID in the merchant’s system	1593011107489

Retrieve Subscriptions by Customer ID Request Sample
                                    {
"customer_account_id":"1607111085012"
}
                                

Retrieve Subscriptions by Customer ID Response Body Parameters

Parameter	Type	Description	Example
subscription	Object	The object that contains information about the subscription
subscription:id	String(36)	The ID of the subscription	e16aa337-98a0-4439-9adb-ab7adf316b18
subscription:status	String(36)	The state of the subscription	cancelled
subscription:started_at	String(36)	Date of the start of the subscription	2020-12-04 19:44:48
subscription:expired_at	String(36)	Date of the expiration of the subscription	2020-12-04 19:50:51
subscription:cancelled_at	String(36)	Date of the subscription’s cancellation	2020-12-04 19:51:51
subscription:trial	Boolean	Trial parameters of the subscription	false
subscription:cancel_code	String(36)	Subscription Cancel Code	8.08
subscription:cancel_message	String	The error message associated with the corresponding ‘cancel code’	Subscription has expired
subscription:payment_type	String	Payment type	card
subscription:customer	Object	The object that contains the information about the customer
subscription:customer:customer_account_id	String(100)	Customer ID in the merchant's system	1607111085012
subscription:customer:customer_email	String(100)	Customer email	test@gmail.com

Retrieve Subscriptions by Customer ID Response Sample | Success
                                    {
    "e16aa337-98a0-4439-9adb-ab7adf316b18": {
        "id": "e16aa337-98a0-4439-9adb-ab7adf316b18",
        "status": "cancelled",
        "started_at": "2020-12-04 19:44:48",
        "expired_at": "2020-12-04 19:50:51",
        "cancelled_at": "2020-12-04 19:51:51",
        "trial": false,
        "cancel_code": "8.08",
        "cancel_message": "Subscription has expired",
        "payment_type": "card",
        "customer": {
            "customer_account_id": "1607111085012",
            "customer_email": "test@gmail.com"
        }
    }
}
                                

Switch Subscription Product

By using this method, the merchant can replace the product used in the active subscription with a new one. After the request to switch the product has been completed, a callback will be sent with the corresponding update (new product name for the subscription). The new product settings will be applied after the next debiting date.

POST https://subscriptions.solidgate.com/api/v1/subscription/switch-subscription-product

Request parameters

Parameter	Mandatory	Type	Description	Example
new_product_id	yes	String	The ID of the new product, that can be used in the selected subscription	b001cb28-1111-1111-9ba9-23a5abc0a0cf
subscription_id	yes	String	The ID of the subscription	2dd05019-11111111-1111-18d162f26761

Request Sample
                                    {
"new_product_id": "b001cb28-1111-1111-9ba9-23a5abc0a0cf",
"subscription_id": "2dd05019-11111111-1111-18d162f26761" 
}
                                

Parameters of the successful response

Parameter	Status	Description
status	String	Status of the operation of the product replacement

Success Response Sample
                                    {
"status": "ok"
}
                                