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 admin panel https://my.solidgate.com/.

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 https://my.solidgate.com/ admin panel.

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

By using this method, you can subscribe to the subscription service provided by Solid. 

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

 

    Init Subscription Request Body Parameters    

ParameterMandatoryTypeDescriptionExample
product_idYesString(36)ID of the predefined productfaf3b86a-1fe6-4ae5-84d4-ab0651d75db2
customer_account_idYesString(100)Customer ID in the merchant's system4dad42f808
customer_emailYesString(100)Customer emailjondou@gmail.com
geo_countryYesString(3)Customer country subject to ISO 3166-1 alpha-3GBR
ip_addressYesString(50)Customer IP (only public ones)8.8.8.8
order_idYesString(100)Order ID specified in the merchant system123443334
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 - applicationWEB
customer_date_of_birthNoString(50)Customer birth date in format YYYY-MM-DD2000-11-21
customer_first_nameNoString(100)Customer first nameJohn
customer_last_nameNoString(100)Customer last nameSnow
customer_phoneNoString(50)Customer telephone380111111111
form_nameNoString(100)Form namewo_cardholder
form_design_nameNoString(255)Form design namepromo_christmas
fraudulentNoBooleanThe customer is detected by the merchant system to be suspicious one. The payment will be effected via 3DSTRUE
geo_cityNoString(100)Customer cityNew Castle
languageNoString(2)Customer language settings. Available values: RU - Russian, EN - English, FR - French, ES - Spanish, PT - Portuguese, JA - Japanese, AR - Arabic, IT - Italian, TR - Turkish, PL - Polish, DE - Germanen
order_dateNoString(50)Date of order creation in format YYYY-MM-DD-HH-MM-SS2015-12-21 11:21:30
order_itemsNoString(255)Order items in UTF-8 codeitem 1, item 2
callback_urlNoString(255)URL of merchant page, where response with payment result will be senthttp://merchant.example/callback
fail_urlNoString(255)URL of merchant page, which a customer will be redirected in case of unsuccessful paymenthttp://merchant.example/fail
success_urlNoString(255)URL of merchant page, which a customer will be redirected in case of successful paymenthttp://merchant.example/success
chargeback_notification_urlNoString(255)URL of merchant page, where the notification of chargeback will be senthttp://merchant.example/chargeback
alert_chargeback_notification_urlNoString(255)URL of merchant page, where the notification of chargeback alerts will be senthttp://merchant.example/chargeback_alerts
verifiedNoBooleanA user was verified on the shop sideTRUE
retry_attemptNoIntegerNumber of retry payment1
traffic_sourceNoString(255)Source of trafficfacebook
transaction_sourceNoString(255)Source of transactions on sitemain_menu
user_agentNoStringUser-agent of the customerMozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36
deviceNoStringDevice of customeriPhone 8 iOS 12.0
order_numberNoIntegerNumber of payments by user1
typeNoStringParameter for transaction authorization through a payment formauth
settle_intervalNoIntegerTime (in hours) when auto-settle will be done1
force3dsNoBooleanRouting payments flag for 3DS flow (enabled by Solid account manager)FALSE
subscription_callback_urlNoString(255)Subscription callback addresshttp://merchant.example/subscription_callback

Init Subscription Request Sample

{
  "product_id": "faf3b86a-1fe6-4ae5-84d4-ab0651d75db2",
  "customer_account_id": "1591802025098",
  "customer_email": "test1591802025098@gmail.com",
  "customer_phone": "+380954543322",
  "geo_country": "USA",
  "ip_address": "8.8.8.8",
  "language": "en",
  "order_description": "test",
  "order_id": "1591802025090createSubscriptionChrome",
  "order_items": "order_items",
  "platform": "WEB",
  "fraudulent": true,
  "payment_type_data": {}
}

 

     Init Subscription Response Body Parameters    

ParameterTypeDescriptionExample
orderObjectObject with order information 
order:order_idStringOrder ID specified in merchant system777
order:amountIntegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents2575
order:currencyStringOrder currency (3 letter code under ISO 4217)USD
order: fraudulentBooleanThe customer was detected on the merchant end to be the suspicious oneTRUE
order:statusStringOrder statuscreated
order:subscription_idStringID of the user’s subscription83b19018-cbc4-4df0-899a-dda84fd2705e
pay_formObjectObject with data of payment form 
pay_form:tokenStringToken of payment form6e6525c18a2803372af41d5e8c6e7b20601
pay_form:form_urlStringPayment form urlhttps://form.solidgate.com/api/v1/purchase/6e6525c18a2803372af41d5e8c6e7b20601
pay_form:design_nameStringDesign name for depicting of payment formpromo_christmas

Init Subscription Response Sample | Success

{
  "pay_form": {
    "token": "0a8ec76958470f8f1c4798025bee64e6db9c23fb5ee0f8b250be9",
    "form_url": "https://form.solidgate.com/api/v1/purchase/0a8ec76958470f8f1c4798025bee64e6db9c23fb5ee0f8b250be9"
  },
  "order": {
    "order_id": "1591802025090createSubscriptionChrome",
    "status": "created",
    "amount": 200,
    "currency": "USD",
    "fraudulent": true
  }
}

 

    Init Subscription Response Body Parameters | Error

ParameterTypeDescriptionExample
errorObjectObject with information on error 
error:codeStringError codes list2.01
error: messagesObjectError messages 
error: messages:attribute_nameStringAttribute name where an error was foundcustomer_account_id
error: messages:error_messageArrayThe array of error messages relating to the respective attributeField required for subscription

Init Subscription Response Sample | Error

{
    "error": {
        "code": "2.01",
        "messages": {
            "customer_account_id": [
                "Field required for subscription"
            ]
        }
    }
}

Subscription callbacks

If subscription_callback_url parameter was passed to the subscription creation request, then, if the payment was successful, callbacks will start to arrive to the specified url. Structure of the callback is similar to the subscription / status method, but callback type parameter will be added to the structure additionally. There are three types of callbacks - init, renew, update, 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 - 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" and "status": "active";
  • When the subscription expiry date comes - in the notification we send "callback_type": "cancel" and "status": "cancelled";

Subscription callback sample

{
  "subscription": {
    "id": "559ec566-f101-434b-8928-ae747c2d1b17",
    "status": "cancelled",
    "started_at": "2020-10-26 16:02:19",
    "expired_at": "2020-10-26 16:07:38",
    "cancelled_at": "2020-10-26 16:14:38",
    "trial": false,
    "cancel_code": "8.09",
    "cancel_message": "Cancellation after redemption period",
    "payment_type": "card"
  },
  "product": {
    "name": "Test Product / trial charge_refund",
    "amount": 100,
    "currency": "USD",
    "trial": true,
    "payment_action": "charge_refund",
    "trial_period": 2,
    "product_id": "6df8b342-9e68-4a49-969c-ccb52d194eb7"
  },
  "customer": {
    "customer_account_id": "1603728112252"
  },
  "invoices": {
    "3f754199-7f99-4105-be4c-d0b50ec52504": {
      "id": "3f754199-7f99-4105-be4c-d0b50ec52504",
      "amount": 500,
      "status": "fail",
      "created_at": "2020-10-26 16:07:51",
      "updated_at": "2020-10-26 16:14:38",
      "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"
        },
        "4a7e27b3-9406-4b22-9e82-8ddafbf7ecdc": {
          "id": "4a7e27b3-9406-4b22-9e82-8ddafbf7ecdc",
          "status": "declined",
          "amount": 500,
          "created_at": "2020-10-26 16:07:53",
          "processed_at": "2020-10-26 16:09:37",
          "failed_reason": 3.02",
          "operation": "recurring",
          "retry_attempt": 1
        },
        "dd54998a-cda6-4210-8bee-357b978c98ad": {
          "id": "dd54998a-cda6-4210-8bee-357b978c98ad",
          "status": "declined",
          "amount": 500,
          "created_at": "2020-10-26 16:09:38",
          "processed_at": "2020-10-26 16:11:37",
          "failed_reason": "3.02",
          "operation": "recurring",
          "retry_attempt": 2
        },
        "83d53646-96b9-4699-a458-60703fdbf2eb": {
          "id": "83d53646-96b9-4699-a458-60703fdbf2eb",
          "status": "declined",
          "amount": 500,
          "created_at": "2020-10-26 16:11:38",
          "processed_at": "2020-10-26 16:14:37",
          "failed_reason": "3.02",
          "operation": "recurring",
          "retry_attempt": 3
        }
      }
    }
  },
  "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 specified in the merchant system4dad42f808
customer_first_nameNostring(100)Customer first nameJohn
customer_last_nameNostring(100)Customer last nameSnow
customer_phoneNostring(50)Customer phone number380111111111
customer_date_of_birthNostring(50)Birthdate in YYYY-MM-DD format2000-11-21
geo_cityNostring(100)Customer cityNew Castle
languageNostring(2)Customer language settings. Available values: RU - Russian, EN - Englishen
fraudulentNobooleanThe customer is detected by the merchant system to be suspicious one. The payment will be effected via 3DS.TRUE
callback_urlNostring(255)URL of merchant page, where response with payment result will be sent via a host-to-host connectionhttp://merchant.example/callback
chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback will be senthttp://merchant.example/chargeback
alert_chargeback_notification_urlNostring(255)URL of merchant page, where the notification of chargeback alerts will be senthttp://merchant.example/chargeback_alerts
status_urlNostring(255)URL of merchant page, which customers will be redirected upon 3DS verification on bank end with the status of operation in URL parameter - http://merchant.example/status/?order_id=123443334&status=approvedhttp://merchant.example/status
verifiedNobooleanThe user was verified on the shop side.TRUE
payment_typeYesstring(25)Type of recurring payment.1-click || retry || recurring
retry_attemptNointegerNumber of retry payment1
traffic_sourceNostring(255)Source of traffic.facebook
transaction_sourceNostring(255)Source of transactions on 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
operating_systemNostringInformation about the operating system of the customer deviceiOS
operating_system_versionNostringInformation about the version of the operating system of the customer device12
browserNostringInformation about the browser of the customer deviceSafari
browser_versionNostringInformation about the version of the browser of the customer device12
websiteNostring(255)Website from which transaction took place.Google.com
typeNostringThe parameter for transaction-authorization before a recurring paymentauth
settle_intervalNointegerTime (in hours) when auto-settle should do1
force3dsNobooleanRouting payments flag for 3DS flow (enabled by Solid account manager)FALSE
header_acceptYes - 3D 2.0string(255)Header Accept.text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng
header_accept_languageYes - 3D 2.0string(255)Header Accept Language.ru-RU,ru;q=0.9,en-US;q=0.8
browser_color_depthYes - 3D 2.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",
  "callback_url": "http://merchant.example/callback",
  "status_url": "http://merchant.example/status",
  "chargeback_notification_url": "http://merchant.example/chargeback",
  "verified": true,
  "payment_type": "1-click",
  "retry_attempt": "1",
  "traffic_source": "facebook",
  "transaction_source": "main_menu",
  "device": "iPhone 8 iOS 12.0",
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
  "operating_system": "iOS",
  "operating_system_version": "12.0",
  "browser": "Safari",
  "browser_version": "12.0",
  "type": "auth",
  "settle_interval": 1,
  "header_accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng",
  "header_accept_language": "ru-RU,ru;q=0.9,en-US;q=0.8",
  "browser_color_depth": 32,
  "browser_screen_height": 1920,
  "browser_screen_width": 1280,
  "browser_java_enabled": true,
  "browser_javascript_enabled": true,
  "time_zone_offset": 60
}

 

        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:cardholder_namestringCardholder nameTest User
transaction:card:card_exp_monthstringA month of the expiration date on the card. (2-digit format)3
transaction:card:card_exp_yearintegerA year of the expiration date on the card. (4-digit format)2025
transaction:card:card_typestringA type of the card.DEBIT
transaction:card_tokenobject  
transaction:card_token:tokenstringCard token to be used for recurring payments. It will be returned in case of successful payment.b5ddb0a1c...1fc4da81ecdad52c0
transactionsobjectAn object with information of transactions. 
transactions:<transaction_id>objectTransaction identification within the order. It contains an object with detailed information about the specified transaction. The order can have several transactions.1495123020887591dc450088f1
transactions:<transaction_id>:idstringTransactions identification within the order.1495123020887591dc450088f1
transactions:<transaction_id>:operationstringTransaction type. Transaction types are described in the respective directory.recurring
transactions:<transaction_id>:statusstringTransaction status within the order. Transaction statuses are described in the respective directory.created
transactions:<transaction_id>:descriptorstringThe descriptor for the transactionpayhere.com
transactions:<transaction_id>:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
transactions:<transaction_id>:currencystringThe currency of the order amount for marketing analytics.USD
transactions:<transaction_id>:created_atstringTransaction created DateTime2019-05-17 9:06:21
transactions:<transaction_id>:updated_atstringTransaction updated DateTime2019-05-17 9:06:21
transactions:<transaction_id>:cardobjectAn object with information about the card. Present in payment transactions. 
transactions:<transaction_id>:card:binintegerCard BIN444455
transactions:<transaction_id>:card:brandstringCard BrandVISA
transactions:<transaction_id>:card:numberstringMasked card number444455XXXXXX6666
transactions:<transaction_id>:card:cardholder_namestringCardholder NameTest User
transactions:<transaction_id>:card:bankstringBank emitentNATIONWIDE BUILDING SOCIETY
transactions:<transaction_id>:card:countrystringCountry of bankGBR
transactions:<transaction_id>:card:card_exp_monthstringA month of expiration date on card. (2-digit format)3
transactions:<transaction_id>:card:card_exp_yearintegerA year of expiration date on card. (4-digit format)2025
transactions:<transaction_id>:card:card_typestringA type of the card.DEBIT
transactions:<transaction_id>:card_tokenobject  
transactions:<transaction_id>:card_token:tokenstringCard token to be used for recurring payments. It will be returned in case of successful payment.8b5ddb0a1c...1fc4da81ecdad52c0
payment_adviserobject  
payment_adviser:advisestringRecommendation for next paymentpay / resign / recurring
    

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 Body Parameters | Error

ParameterTypeDescriptionExample
errorobjectObject with information on errors 
error:codestringError codes list2.01
error: messagesobjectObject with error list 
error:messages:<attribute_name>stringAttribute name where error was foundcurrency
error:messages:<error_message>arrayArray of error messages relating to respective attributeThis value should not be blank.

1-click Response Body Parameters | Error

{
    "error": {
        "code": "2.01",
        "messages": {
            "currency": [
                "This value should not be blank."
            ],
            "customer_email": [
                "This value should not be blank."
            ],
            "ip_address": [
                "This value should not be blank."
            ],
            "order_description": [
                "This value should not be blank."
            ],
            "order_id": [
                "This value should not be blank."
            ],
            "platform": [
                "This value should not be blank."
            ]
        }
    }
}

 

        1-click Response Body Parameters | Decline Error

ParameterTypeDescriptionExample
errorobjectObject with the information about the error 
error:"recommended_message_for_user"objectAn object with a list of error messages displayed to the user. 
error:"recommended_message_for_user":<error_message>stringError displayed to the user during the decline. (Decline error)"Solid antifraud engine"
error:codestringError code.2.01
error:messagesobjectObject with a list of error messages 
error:messages:<attribute_name>stringThe name of the attribute in which the error was found 
error:messages:<error_message>arrayArray of error messages related to this attributeThis value should not be blank.
error:typestringType of en error.soft

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 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_idYesStringCustomer ID in the merchant's system. In case of successful payment, card data will be tied to this ID.user_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
callback_urlNoStringURL of merchant page, where response with payment result will be senthttp://merchant.example/callback
subscription_callback_urlNoStringSubscription callback addresshttp://merchant.example/subscription_callback

PayPal Subscription Request Sample

{
  "product_id": "faf3b86a-1fe6-4ae5-84d4-ab0651d75db2",
  "payment_method": "paypal-vault",
  "callback_url": "http://merchant.example/callback",
  "customer_account_id": "user_id",
  "customer_date_of_birth": "2000-11-21",
  "customer_email": "example.user@example-email.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "380000000000",
  "geo_city": "New Castle",
  "geo_country": "GBR",
  "ip_address": "8.8.8.8",
  "language": "en",
  "order_date": "2015-12-21 11:21:30",
  "order_description": "Premium package",
  "order_id": "testPayPal777",
  "platform": "WEB"
}

 

    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: 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
pay_formObjectObject with data payment form data 
pay_form: tokenStringA token that is used in recurring charge3e74d293f47e4c7899613ba37e38ee43
pay_form: script_urlStringPayPal Button Scripthttps://gate.solidgate.com/widget/7d0d148742af492ea075e1972779df78

PayPal Subscription Response Sample

{
    "order": {
        "amount": 999,
        "currency": "USD",
        "order_id": "testPayPal777",
        "status": "created",
        "method": "paypal-vault"
    },
    "pay_form": {
        "token": "3e74d293f47e4c7899613ba37e38ee43",
        "script_url": "https://gate.solidgate.com/widget/3e74d293f47e4c7899613ba37e38ee43"
    }
}

PayPal Button elements on page

<div id="paypal-button"></div>
<script>
    var elem = document.getElementById('paypal-button');
    elem.addEventListener('order-started-processing', function (e) {
        console.log('order-started-processing',e);
    }, false);
    elem.addEventListener('order-processed', function (e) {
        console.log('order-processed',e);
    }, false);
    elem.addEventListener('order-already-processed', function (e) {
        console.log('order-already-processed', e)
    }, false);
    elem.addEventListener('button-ready', function (e) {
        console.log('button-ready', e)
    }, false);
    elem.addEventListener('button-error', function (e) {
        console.log('button-error',e);
    }, false);
</script>
<script type="text/javascript"
        src="https://gate.solidgate.com/widget/e403827025c44f0893baac3d760d3a3c"
        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"
  },
  "pay_form": {
    "token": "fb124ba2d884427d8724c1a78ad304de",
    "script_url": "https://gate.solidgate.com/widget/fb124ba2d884427d8724c1a78ad304de"
  },
  "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"
  },
  "pay_form": {
    "token": "a48fcc6c3abf425eaa61b2289675f489",
    "script_url": "https://gate.solidgate.com/widget/a48fcc6c3abf425eaa61b2289675f489"
  },
  "error": {
    "code": "0.01",
    "messages": [
      "General decline"
    ],
    "recommended_message_for_user": "General decline"
  },
  "transactions": [
    {
      "status": "fail",
      "method": "paypal-vault",
      "amount": 100,
      "currency": "EUR",
      "type": "pay"
    }
  ]
}
__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 from the callback_url used in the initial payment for the PayPal Subscription. 

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 from the callback_url used in the initial payment for the PayPal Subscription. 
customer_account_idNostring(100)Customer ID in the merchant's system. In case of successful payment, card data will be tied to this ID.4dad42f808
customer_date_of_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
callback_urlNostring(255)URL of merchant page, where response with payment result will be senthttp://merchant.example/callback
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",
  "callback_url": "http://merchant.example/callback",
  "currency": "USD",
  "customer_account_id": "user_id",
  "customer_date_of_birth": "2000-11-21",
  "customer_email": "example.user@example-email.com",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_phone": "380000000000",
  "geo_city": "New Castle",
  "geo_country": "GBR",
  "ip_address": "8.8.8.8",
  "language": "en",
  "order_date": "2015-12-21 11:21:30",
  "order_description": "Premium package",
  "order_id": "777",
  "platform": "WEB"
}

 

    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
pay_formobjectObject with data payment form data 
pay_form: tokenstringPayment form token5849cf0468afc0ac4be4963c619b776eee75271d56e3c6621ab21

PayPal 1-click Response Sample | Success

{
 "order": {
 "amount": 5000,
 "currency": "USD",
  "order_id": "1504269591134TEST",
  "status": "created"
  },
 "pay_form": {
 "token": "6de603708b5b4c33a681dc1e47b20ad3"
  }
}

PayPal 1-click Response Sample | Error

{
  "error": {
    "code": "2.01",
    "messages": {
      "currency": [
        "Invalid Currency."
      ]
    }
  }
}

Cancel the subscription

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

POSThttps://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 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

 

    Cancel Subscription Response Body Parameters | Error

ParameterTypeDescriptionExample
errorObjectObject with the error 
error:codeStringError codes list2.01
error: messagesObjectError messages 
error: messages:attribute_nameStringAttribute name where an error was foundsubscription_id
error: messages:error_messageArrayThe array of error messages relating to the respective attributeField `subscription_id` must be provided

Cancel Subscription Response Sample | Error

{
    "error": {
        "code": "2.01",
        "messages": {
            "subscription_id": [
                "Field `subscription_id` must be provided"
            ]
        }
    }
}

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.

POSThttps://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 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 MySolid admin panel.

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: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: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 days) of the product2
customerObjectObject with the information about the customer 
customer:customer_account_idString(100)ID of the customer1603728112252
invoicesObjectObject with the information about invoices 
invoices:invoice_idMapObject 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:MapObject 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,
    "product_id": "6df8b342-9e68-4a49-969c-ccb52d194eb7"
  },
  "customer": {
    "customer_account_id": "1603728112252"
  },
  "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": "active",
        "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"
    },
    "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,
    "product_id": "6df8b342-9e68-4a49-969c-ccb52d194eb7"
  },
  "customer": {
    "customer_account_id": "1603728112252"
  },
  "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"
        }
      }
    }
  }
}

 

    Status Subscription Response Body Parameters | Error

ParameterTypeDescriptionExample
errorObjectObject with information on error 
error:codeStringError codes list2.01
error:messagesObjectError messages 
error:messages:attribute_nameStringAttribute name where the error was foundsubscription_id
error:messages:error_messageArrayThe array of error messages relating to the respective attributeField `subscription_id` must be provided

Status Subscription Response Sample | Error

{
    "error": {
        "code": "2.01",
        "messages": {
            "subscription_id": [
                "Field `subscription_id` must be provided"
            ]
        }
    }
}

 

    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 was received for one of the user's invoices, then we unsubscribe the user from all subscriptions
8.04Fraud AlertIf 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 supportThe user contacted the service support team and asked to unsubscribe him from subscriptions
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

Subscription Reconciliation by a 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

 

    Reconciliation Subscription Request Body Parameters

ParameterMandatoryTypeDescriptionExample
customer_account_idyesStringCustomer ID in the merchant’s system1593011107489

Reconciliation Subscription Request Sample

{
"customer_account_id":"1593011107489"
}

 

    Reconciliation Subscription Response Body Parameters

ParameterTypeDescriptionExample
subscriptionObjectThe object that contains information about the subscription 
subscription:idString(36)The ID of the subscription64e1c283-17bf-45a7-90ea-2cb938081b2f
subscription:statusString(36)The state of the subscriptioncancelled
subscription:started_atString(36)Date of the start of the subscription2020-06-10 15:42:24
subscription:expired_atString(36)Date of the expiration of the subscription2020-09-10 15:42:24
subscription:cancelled_atString(36)Date of the subscription’s cancellation2020-06-26 6:43:58
subscription:trialBooleanTrial parameters of the subscriptionTRUE

Reconciliation Subscription Response Sample | Success


{
    "1e33c4af-5555-111-bbcb-1234567890d9": {
        "id": "1111c4af-8888-222f-aacb-4444555537d9",
        "status": "cancelled",
        "started_at": "2020-06-26 06:40:55",
        "expired_at": "2020-06-26 06:43:58",
        "cancelled_at": "2020-06-26 06:43:58",
        "trial": false
    },
    "e777729e-2o0-55f8-8cd9-r111c999959f": {
        "id": "e777779e-2cd0-99f8-8c99-e111c999959f",
        "status": "active",
        "started_at": "2020-06-25 14:37:24",
        "expired_at": "2020-06-28 14:37:24",
        "cancelled_at": "2020-06-26 06:44:35",
        "trial": false
    }
}