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

ParameterMandatoryTypeDescriptionExample
order_idYesstring(100)Order ID specified in the merchant system123443334
amountYesintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.1020
currencyYesstring(3)Order currency. 3 letter currency code under ISO-4217USD
recurring_tokenYesstring(255)Card token7ats8da7sd8-a66dfa7-a9s9das89t
order_descriptionYesstring(255)Order description in UTF-8 codePremium package
customer_emailYesstring(100)Customer emailjondou@gmail.com
ip_addressYesstring(50)Customer IP (only public ones)8.8.8.8
platformYesstring(6)Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application.WEB
geo_countryNostring(3)Customer country subject to ISO 3166-1 alpha-3GBR
order_dateNostring(50)Date of order creation in format YYYY-MM-DD-HH-MM-SS2015-12-21 11:21:30
order_itemsNostring(255)Order description in UTF-8 codeitem 1, item 2
customer_account_idNostring(100)Customer ID in the merchant's system. Required for Subscription Payments 4dad42f808
customer_first_nameNostring(100)Customer first nameJohn
customer_last_nameNostring(100)Customer last nameSnow
customer_phoneNostring(50)Customer phone number380111111111
customer_date_of_birthNostring(50)Birthdate in YYYY-MM-DD format2000-11-21
geo_cityNostring(100)Customer cityNew Castle
languageNostring(2)Customer language settings. Available values: RU - Russian, EN - Englishen
fraudulentNobooleanThe customer is detected by the merchant system to be suspicious one. The payment will be effected via 3DS.TRUE
fail_urlNostring(255)URL of merchant page, which a customer will be redirected in case of unsuccessful paymenthttp://merchant.example/fail
success_urlNostring(255)URL of merchant page, which a customer will be redirected in case of successful paymenthttp://merchant.example/success
verifiedNobooleanThe user was verified on the shop side.TRUE
payment_typeNostring(25)Type of recurring payment.1-click || retry || recurring || rebill || installment
retry_attemptNointegerNumber of retry payment1
traffic_sourceNostring(255)Source of traffic.facebook
transaction_sourceNostring(255)Source of transactions on site.main_menu
order_numberNointegerNumber of payments by user2
user_agentNostringUser-agent of customerMozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36
deviceNostringDevice of customeriPhone 8 iOS 12.0
websiteNostring(255)Website from which transaction took place.Google.com
typeNostringThe parameter for transaction-authorization before a recurring paymentauth
settle_intervalNointegerTime (in hours) when auto-settle should be done.1
force3dsNobooleanRouting payments flag for 3DS flow (enabled by Solid account manager)FALSE
header_acceptYes - 3D 2.0string(255)Header Accept.text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng
header_accept_languageYes - 3D 2.0string(255)Header Accept Language.ru-RU,ru;q=0.9,en-US;q=0.8
browser_color_depthYes - 3D 2.0integerColor depth of browser window.32
browser_screen_heightYes - 3D 2.0integerHeight of browser window.1920
browser_screen_widthYes - 3D 2.0integerWidth of browser window.1280
browser_java_enabledYes - 3D 2.0booleanIs java enabled on User browser.FALSE
browser_javascript_enabledYes - 3D 2.0booleanIs javascript enabled on User browser.FALSE
time_zone_offsetYes - 3D 2.0integerThe time difference, in minutes, between UTC time and the local time of the cardholder's browser.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

ParameterTypeDescriptionExample
orderobjectAn object with information of the transaction. 
order:order_idstringOrder ID specified in the merchant system777
order:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
order:currencystringOrder currency (3 letter code under ISO 4217)USD
order:fraudulentbooleanThe customer was detected on the merchant end to be a suspicious oneTRUE
order:marketing_amountintegerOrder amount converted in USD (or any other currency agreed) under open FX sources at the moment of transaction. This can be applied only for marketing forecasting.2575
order:marketing_currencystringThe currency of the order amount for marketing analytics.USD
order:refunded_amountintegerThe amount which was refunded0
order:descriptorstringThe descriptor for the transactionpayhere.com
order:statusstringStatus of payment processed. Types of order statuses are described in the respective directory.processing
transactionobjectAn object with information of the transaction. 
transaction:idstringTransaction identification within the order. The order can have several transactions.1495123020887591dc450088f1
transaction:operationstringTransaction type. Available values - recurring.recurring
transaction:statusstringTransaction status within the order.created
transaction:amountintegerTransaction amount.2575
transaction:currencystringTransaction currency.USD
transaction:created_atstringTransaction created DateTime2019-05-17 9:06:21
transaction:updated_atstringTransaction updated DateTime2019-05-17 9:06:21
transaction:cardobjectAn object with information about the card. Present in payment transactions. 
transaction:card:bankstringBank-emitent.NATIONWIDE BUILDING SOCIETY
transaction:card:binintegerCard BIN.444455
transaction:card:brandstringCard Brand.VISA
transaction:card:countrystringCountry of the bank.USA
transaction:card:numberstringMasked card number.444455XXXXXX6666
transaction:card:card_holderstringCardholder nameTest User
transaction:card:card_exp_monthstringA month of the expiration date on the card. (2-digit format)3
transaction:card:card_exp_yearintegerA year of the expiration date on the card. (4-digit format)2025
transaction:card:card_typestringA type of the card.DEBIT
transaction:card_tokenobject  
transaction:card_token:tokenstringCard token to be used for recurring payments. It will be returned in case of successful payment.b5ddb0a1c...1fc4da81ecdad52c0
transactionsobjectAn object with information of transactions. 
transactions:<transaction_id>objectTransaction identification within the order. It contains an object with detailed information about the specified transaction. The order can have several transactions.1495123020887591dc450088f1
transactions:<transaction_id>:idstringTransactions identification within the order.1495123020887591dc450088f1
transactions:<transaction_id>:operationstringTransaction type. Transaction types are described in the respective directory.recurring
transactions:<transaction_id>:statusstringTransaction status within the order. Transaction statuses are described in the respective directory.created
transactions:<transaction_id>:descriptorstringThe descriptor for the transactionpayhere.com
transactions:<transaction_id>:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
transactions:<transaction_id>:currencystringThe currency of the order amount for marketing analytics.USD
transactions:<transaction_id>:created_atstringTransaction created DateTime2019-05-17 9:06:21
transactions:<transaction_id>:updated_atstringTransaction updated DateTime2019-05-17 9:06:21
transactions:<transaction_id>:cardobjectAn object with information about the card. Present in payment transactions. 
transactions:<transaction_id>:card:binintegerCard BIN444455
transactions:<transaction_id>:card:brandstringCard BrandVISA
transactions:<transaction_id>:card:numberstringMasked card number444455XXXXXX6666
transactions:<transaction_id>:card:card_holderstringCardholder NameTest User
transactions:<transaction_id>:card:bankstringBank emitentNATIONWIDE BUILDING SOCIETY
transactions:<transaction_id>:card:countrystringCountry of bankGBR
transactions:<transaction_id>:card:card_exp_monthstringA month of expiration date on card. (2-digit format)3
transactions:<transaction_id>:card:card_exp_yearintegerA year of expiration date on card. (4-digit format)2025
transactions:<transaction_id>:card:card_typestringA type of the card.DEBIT
transactions:<transaction_id>:card_tokenobject  
transactions:<transaction_id>:card_token:tokenstringCard token to be used for recurring payments. It will be returned in case of successful payment.8b5ddb0a1c...1fc4da81ecdad52c0
payment_adviserobject  
payment_adviser:advisestringRecommendation for next paymentpay / resign / recurring
    

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 PayPal Subscription

Operation of subscription creation. It should be used while working with a PayPal button. 

This operation deems to create order in the system and return token being applied while calling the PayPal button. After that, you may use one-click payment technology for the subscription model.
 

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

 

    PayPal Subscription Request Body Parameters

ParameterMandatoryTypeDescriptionValue sample
product_idYesString(36)The ID of the predefined productfaf3b86a-1fe6-4ae5-84d4-ab0651d75db2
payment_methodYesStringPayPal Vaultpaypal-vault
customer_account_idNoStringCustomer ID in the merchant's system. Required for Subscription Paymentsuser_id
order_idYesStringOrder ID specified in merchant systemtestPayPal777
order_descriptionYesStringOrder description in UTF-8 codePremium package
platformYesStringCustomer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application.WEB
customer_emailYesStringAn email that belongs to a customerjondou@gmail.com
geo_countryYesString(3)Customer’s country. Code shall be in ISO 3166-1 alpha-3 format. (Mandatory for method PayPal)GBR
ip_addressYesStringIP address (only public ones)8.8.8.8
customer_date_of_birthNoStringCustomer birth date in format YYYY-MM-DD2000-11-21
customer_first_nameNoStringCustomer’s first nameJohn
customer_last_nameNoStringCustomer’s last nameSnow
customer_phoneNoStringCustomer’s telephone380000000000
geo_cityNoStringCustomer’s cityNew Castle
languageNoString(2)Customer’s language settings. Available values: RU - Russian, EN - Englishen
order_dateNoStringDate of order creation in format YYYY-MM-DD-HH-MM-SS2015-12-21 11:21:30

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

 

    PayPal Subscription Response Body Parameters

ParameterTypeDescriptionValue sample
orderObjectObject with information of the order 
order: methodStringA method that is used for the subscription paymentpaypal-vault
order: order_idStringOrder ID specified in merchant systemtestPayPal777
order: tokenStringA token that is used in recurring charge1349c909ddc8d934899a4f37ca63b3777593fc8f3dfea65c9e588972e5d9926cd67894
order: amountIntegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.999
order: currencyStringOrder currency (3 letter code under ISO 4217)USD
order: statusStringOrder statuscreated

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>
EventsValueDescription
EVENT_BUTTON_READYbutton-readyThe button is ready to be used
EVENT_BUTTON_ERRORbutton-errorThere is an error with the button rendering
EVENT_ORDER_STARTED_PROCESSINGorder-started-processingOrder is in processing
EVENT_ORDER_PROCESSEDorder-processedOrder is processed
EVENT_ORDER_ALREADY_PROCESSEDorder-already-processedAppears 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

ParameterMandatoryTypeDescriptionValue sample
amountYesintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.1020
currencyYesstring(3)Order currency. 3 letter currency code under ISO-4217USD
payment_methodNostring(255)Method that used to perform a transactionpaypal-vault
tokenYesstring(255)Token from the successful payment used in the initial payment for the PayPal Subscription. 
customer_account_idNostring(100)Customer ID in the merchant's system. Required for Subscription Payments 4dad42f808
customer_date_of_birthNostring(50)Customer birth date in format YYYY-MM-DD2000-11-21
customer_emailYesstring(100)Customer emailjondou@gmail.com
customer_first_nameNostring(100)Customer's first nameJohn
customer_last_nameNostring(100)Customer last nameSnow
customer_phoneNostring(50)Customer telephone380111111111
geo_countryNostring(3)Customer country. Code shall be in ISO 3166-1 alpha-3 format.GBR
geo_cityNostring(100)Customer cityNew Castle
ip_addressYesstring(50)Customer IP (only public ones)8.8.8.8
languageNostring(2)Customer language settings. Available values: RU - Russian, EN - Englishen
order_idYesstring(255)Order ID specified in merchant system123443334
order_dateNostring(50)Date of order creation in format YYYY-MM-DD-HH-MM-SS2015-12-21 11:21:30
order_descriptionYesstring(255)Order description in UTF-8 codePremium package
platformYesstring(6)Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application.WEB
return_urlYesstring(255)URL of merchant page, which a customer will be redirected after completed paymenthttp://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

ParameterTypeDescriptionValue sample
orderobjectObject with information on the order 
order: amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
order: currencystringOrder currency (3 letter code under ISO 4217)USD
order: order_idstringOrder ID specified in merchant system777
order: statusstringOrder statuscreated

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

ParameterMandatoryTypeDescriptionExample
subscription_idyesStringThe ID of the user’s subscription83b19018-cbc4-4df0-899a-dda84fd2705e
forcenoBooleanParameter of an immediate subscription cancellationFALSE
cancel_codenoStringOne of the appropriate cancellation codes8.13

Cancel Subscription Request Sample

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

 

    Cancel Subscription Response Body Parameter

ParameterTypeDescription
statusStringStatus 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

ParameterMandatoryTypeDescriptionExample
subscription_idyesStringThe ID of the user’s subscription83b19018-cbc4-4df0-899a-dda84fd2705e
expired_atnoStringSubscription expiration date in format YYYY-MM-DD-HH-MM-SS2020-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

ParameterTypeDescription
statusStringSubscription 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   

ParameterMandatoryTypeDescriptionExample
customer_account_idyesStringCustomer ID in the merchant’s system1593011107489
forcenoBooleanParameter of an immediate subscription cancellationfalse
cancel_codenoStringOne of the appropriate cancellation codes8.13

Cancel Subscription by Customer Request Sample

{
"customer_account_id":"1593011107489",
"force":"false"
}

 

    Cancel Subscription by Customer Response Body Parameters    

ParameterTypeDescription
statusStringStatus 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

ParameterMandatoryTypeDescriptionExample
subscription_idyesStringID of the user’s subscription83b19018-cbc4-4df0-899a-dda84fd2705e

Status Subscription Request Sample

{
"subscription_id":"83b19018-cbc4-4df0-899a-dda84fd2705e"
}

 

    Status Subscription Response Body Parameters

ParameterTypeDescriptionExample
subscriptionObjectThe object that contains information about the subscription 
subscription:idString(36)The ID of the subscription559ec566-f101-434b-8928-ae747c2d1b17
subscription:statusString(36)The status of the subscriptioncancelled
subscription:started_atString(36)Date of the start of the subscription2020-10-26 16:02:19
subscription:expired_atString(36)Date of the expiration of the subscription2020-10-26 16:07:38
subscription:next_charge_atString(36)Date when the next payment will be done2020-10-26 16:07:38
subscription:cancelled_atString(36)Date of the subscription’s cancellation2020-10-26 16:14:38
subscription:trialBooleanTrial parameters of the subscriptionTRUE
subscription:cancel_codeStringCancel code list"8.09"
subscription:cancel_messageStringThe error message associated with the corresponding ‘cancel code’"Cancellation after redemption period"
subscription:payment_typeStringPayment typecard
productObjectThe object that contains the information about the product of the subscription 
product:idString(36)The ID of the product6df8b342-9e68-4a49-969c-ccb52d194eb7
product:nameString(100)Name of the productTest Product
product:public_product_descriptionStringPurchase 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:amountIntegerAmount of currency paid for the product100
product:currencyStringThe currency of the subscriptionUSD
product:trialBooleanTrial parameters of the productTRUE
product:payment_actionString(100)Payment type that was used to pay for the productcharge_refund
product:trial_periodIntegerThe trial period (in minutes) of the product2
product:trial_amountIntegerAmount of currency paid for the trial100
product:trial_currencyString(3)The currency of the subscription trialUSD
customerObjectObject with the information about the customer 
customer:customer_account_idString(100)ID of the customer1603728112252
customer:customer_emailString(100)Customer emailsomeEmail1@gmail.com
invoicesObjectObject with the information about invoices 
invoices:invoice_idObjectObject with the information about invoice 
invoices:invoice_id:idString(100)The ID of the invoice0ca5b8e0-7478-42c4-8bc3-5862e6ac85f1
invoices:invoice_id:amountIntegerAmount of currency in the invoice500
invoices:invoice_id:statusString(100)Status of the invoicesuccess
invoices:invoice_id:created_atString(100)Date of the creation of the invoice2020-10-26 16:04:51
invoices:invoice_id:updated_atString(100)Date of the invoice update2020-10-26 16:06:38
invoices:invoice_id:billing_period_started_atString(100)Start date of the billing period2020-10-26 16:06:38
invoices:invoice_id:billing_period_ended_atString(100)Billing period end date2020-10-26 16:07:38
invoices:invoice_id:subscription_term_numberIntegerSubscription term number1
invoices:invoice_id:orders:ObjectObject with the information about the order 
invoices:invoice_id:orders:idString(100)ID of the order3cf93552-a629-44c8-80ab-f8589b4db1cb
invoices:invoice_id:orders:statusString(100)Current status of the orderauth_ok
invoices:invoice_id:orders:amountIntegerAmount of currency in the order500
invoices:invoice_id:orders:created_atString(100)Date of creation of the order2020-06-10 15:42:24
invoices:invoice_id:orders:processed_atString(100)Order processing date2020-06-10 15:42:24
invoices:invoice_id:orders:operationString(100)Type of operationauth
invoices:invoice_id:orders:retry_attemptIntegerRetry attempt number1

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 StatusDescription
ActiveSubscription is active
CancelledSubscription is cancelled and the user unsubscribed
RedemptionIf 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

 

CodeMessageDescription
8.01Card brand is not supportedMaestro 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.02Fraud Chargeback receivedIf chargeback for fraudelent transaction was received for one of the user's invoices, then we unsubscribe the user from all subscriptions.
8.03 Dispute ReceivedIf dispute/chargeback was received for one of the user's invoices, then we unsubscribe the user from all subscriptions.
8.04Fraud Alert receivedIf we receive a fraudulent alert, we unsubscribe the user from further recurring payments.
8.05Fraud Decline receivedIf we receive one of the fraudulent declines for the user (Stolen card, Lost card, etc), we unsubscribe the user.
8.06Cancellation by supportSupport team has cancel subscription due to customer inquire or other internal reasons.
8.07Recurring payment is blocked by AntifraudAntifraud has blocked the conduct of a recurrent payment due to decline 4.09
8.08Subscription has expiredThe subscription was created for a limited time. The deadline has expired, the subscription has expired. User is unsubscribed.
8.09Cancellation after redemption periodDecline on the recurring payment. Retries on the redemption period have been activated. Retries had no result. User is unsubscribed.
8.10Card Token has expiredThe card has an expiration date. After it was expired, the user is not reissuing the card. User is unsubscribed.
8.11Token revoked by customerBilling Token was cancelled by user on PayPal’s side.
8.12Bank antifraud systemThe payment was blocked by the bank's anti-fraud system or the card was added to the bank's blacklist.
8.13Invalid amountInadmissible amount considering the discount exceeding the threshold value.
8.14Cancellation by customerCustomer 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

ParameterMandatoryTypeDescriptionExample
customer_account_idyesStringCustomer ID in the merchant’s system1593011107489

Retrieve Subscriptions by Customer ID Request Sample

{
"customer_account_id":"1607111085012"
}

 

  Retrieve Subscriptions by Customer ID Response Body Parameters

ParameterTypeDescriptionExample
subscriptionObjectThe object that contains information about the subscription 
subscription:idString(36)The ID of the subscriptione16aa337-98a0-4439-9adb-ab7adf316b18
subscription:statusString(36)The state of the subscriptioncancelled
subscription:started_atString(36)Date of the start of the subscription2020-12-04 19:44:48
subscription:expired_atString(36)Date of the expiration of the subscription2020-12-04 19:50:51
subscription:cancelled_atString(36)Date of the subscription’s cancellation2020-12-04 19:51:51
subscription:trialBooleanTrial parameters of the subscriptionfalse
subscription:cancel_codeString(36)Subscription Cancel Code8.08
subscription:cancel_messageStringThe error message associated with the corresponding ‘cancel code’Subscription has expired
subscription:payment_typeStringPayment typecard
subscription:customerObjectThe object that contains the information about the customer 
subscription:customer:customer_account_idString(100)Customer ID in the merchant's system1607111085012
subscription:customer:customer_emailString(100)Customer emailtest@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
 

ParameterMandatoryTypeDescriptionExample
new_product_idyesStringThe ID of the new product, that can be used in the selected subscriptionb001cb28-1111-1111-9ba9-23a5abc0a0cf
subscription_idyesStringThe ID of the subscription2dd05019-11111111-1111-18d162f26761

Request Sample

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

Parameters of the successful response 
 

ParameterStatusDescription
statusStringStatus of the operation of the product replacement

Success Response Sample

{
"status": "ok"
}