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

Request 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

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": {}
}

Parameters of the successful response

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

Success Response Sample

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

Example of response with information about an 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

Failure Response Sample

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

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.

All request must be signed.

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

Parameters of request

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
     

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
}

Parameters of the successful response

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
    

Example success response

{
  "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.

Request Example

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

Response Example

{
  "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

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

Response parameters with error description

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.

Response sample with information on 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."
            ]
        }
    }
}

Response parameters with the information about the error (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

Response example with an 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

Request 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

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

Parameters of the successful response

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

Parameters of the successful response

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

Example of response with information about an 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 attributeThis value should not be blank.

Response sample with information about the error

{
    "error": {
        "code": "2.01",
        "messages": {
            "customer_account_id": [
                "This value should not be blank."
            ]
        }
    }
}

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 - Approved

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 - Declined

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

Request 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

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

Parameters of the successful response

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

Parameters of the successful response

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

Response sample with information about the 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.

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

Request parameters

ParameterMandatoryTypeDescriptionExample
subscription_idyesStringID of the user’s subscription83b19018-cbc4-4df0-899a-dda84fd2705e
forcenoBooleanParameter of an immediate subscription cancellationFALSE

Request Sample

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

Parameters of the successful response 

ParameterTypeDescription
statusStringStatus of a subscription cancellation

Success Response Sample

{
"status": "ok"
}

Example of response with information about an 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

Failure Response Sample

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

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

Request parameters

ParameterMandatoryTypeDescriptionExample
subscription_idyesStringID 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

Request Sample

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

Parameters of the successful response 

ParameterTypeDescription
statusStringSubscription restoring status

Success Response Sample

{
"status": "ok"
}

Example of response with information about an 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

Failure Response Sample

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

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

Request parameters

ParameterMandatoryTypeDescriptionExample
customer_account_idyesStringCustomer ID in the merchant’s system1593011107489
forcenoBooleanParameter of an immediate subscription cancellationfals

Request Sample

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

Parameters of the successful response 

ParameterTypeDescription
statusStringStatus of a subscription cancellation

Success Response Sample

{
"status": "ok"
}

Example of response with information about an error 

ParameterTypeDescriptionExample
errorObjectObject with the 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 `customer_account_id` must be provided

Failure Response Sample

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

Subscription Status

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

After performing the Subscription Status request, you will receive the order status ID, which you can afterwards you can use to check external order ID in MySolid admin panel.

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

Request parameters

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

Request Sample

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

Parameters of the successful response 

ParameterTypeDescriptionExample
subscriptionObjectThe object that contains information about the subscription 
subscription:idString(36)The ID of the subscription64e1c283-17bf-45a7-90ea-2cb938081b2f
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
subscription:cancel_codeStringCancel code list"8.01"
subscription:cancel_messageStringThe error message associated with the corresponding ‘cancel code’"Card brand not supported"
subscription:payment_typeStringPayment typecard
productObjectThe object that contains the information about the product of the subscription 
product:idString(36)The ID of the productfaf3b86a-1fe6-4ae5-84d4-ab0651d75db2
product:nameString(100)Name of the productMeal plan
product:amountIntegerAmount of currency paid for the product200
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 productauth_void
product:trial_periodIntegerThe trial period (in days) of the product5
customerObjectObject with the information about the customer 
customer:customer_account_idString(100)ID of the customer1591792890564
invoicesObjectObject with the information about invoices 
invoices:invoice_idMapObject with the information about invoice 
invoices:invoice_id:idString(100)The ID of the invoicec0a1bc01-c5d3-4f11-87e4-06dda9865db3
invoices:invoice_id:amountIntegerAmount of currency in the invoice200
invoices:invoice_id:statusString(100)Status of the invoicesuccess
invoices:invoice_id:created_atString(100)Date of the creation of the invoice2020-06-10 15:42:24
invoices:invoice_id:updated_atString(100)Date of the invoice update2020-06-10 13:25:30
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 order200
invoices:invoice_id:orders:created_atString(100)Date of creation of the order2020-06-10 15:42:24
invoices:invoice_id:orders:operationString(100)Type of operationauth

Success Response Sample

{
  "subscription": {
    "id": "64e1c283-17bf-45a7-90ea-2cb938081b2f",
    "status": "active",
    "started_at": "2020-06-10 15:42:24",
    "expired_at": "2020-06-15 15:42:24",
    "trial": true,
    "payment_type": "card"
  },
  "product": {
    "id": "faf3b86a-1fe6-4ae5-84d4-ab0651d75db2",
    "name": "Meal plan",
    "amount": 200,
    "currency": "USD",
    "trial": true,
    "payment_action": "auth_void",
    "trial_period": 5
  },
  "customer": {
    "customer_account_id": "1591792890564"
  },
  "invoices": {
    "c0a1bc01-c5d3-4f11-87e4-06dda9865db3": {
      "id": "c0a1bc01-c5d3-4f11-87e4-06dda9865db3",
      "amount": 200,
      "status": "success",
      "created_at": "2020-06-10 15:42:24",
      "updated_at": "2020-06-10 13:25:30",
      "orders": {
        "3cf93552-a629-44c8-80ab-f8589b4db1cb": {
          "id": "3cf93552-a629-44c8-80ab-f8589b4db1cb",
          "status": "auth_ok",
          "amount": 200,
          "created_at": "2020-06-10 15:42:24",
          "operation": "auth"
   ]
        }
      }
    }
  }
}

Success Response Sample (Recurring was successful, but the subscription was cancelled due to one of the cancel codes)

{
  "subscription": {
    "id": "f5eb80f8-7bb7-410e-851d-f8629cdd6825",
    "status": "cancelled",
    "started_at": "2020-07-21 15:21:44",
    "expired_at": "2021-07-21 15:46:14",
    "cancelled_at": "2020-07-21 15:54:53",
    "trial": false,
    "cancel_code": "8.01",
    "cancel_message": "Card brand not supported",
    "payment_type": "card"
  },
  "product": {
    "name": "trial / auth-void",
    "amount": 99,
    "currency": "USD",
    "trial": true,
    "payment_action": "auth_void",
    "trial_period": 7,
    "product_id": "b001cb28-b050-4b19-9ba9-23a5abc0a0cf"
  },
  "customer": {
    "customer_account_id": " testSubscription777"
  },
  "invoices": {
    "49f3ec9b-ce92-4616-b94f-0497bddf810f": {
      "id": "49f3ec9b-ce92-4616-b94f-0497bddf810f",
      "amount": 99,
      "status": "success",
      "created_at": "2020-07-21 15:21:44",
      "updated_at": "2020-07-21 15:21:44",
      "orders": {
        "d2f51f64-860f-4da9-8768-e1f49246588a": {
          "id": "d2f51f64-860f-4da9-8768-e1f49246588a",
          "status": "auth_ok",
          "amount": 99,
          "created_at": "2020-07-21 15:21:44",
          "operation": "auth"
        },
        "1abd5784-d187-4323-af09-c5275b6b961b": {
          "id": "1abd5784-d187-4323-af09-c5275b6b961b",
          "status": "void_ok",
          "amount": 99,
          "created_at": "2020-07-21 15:21:44",
          "operation": "void"
        }
      }
    },
    "3075ebc8-2f83-4bdf-bbc3-a08ce75ac6f4": {
      "id": "3075ebc8-2f83-4bdf-bbc3-a08ce75ac6f4",
      "amount": 3000,
      "status": "success",
      "created_at": "2020-07-21 15:46:13",
      "updated_at": "2020-07-21 15:46:14",
      "orders": {
        "9c3157b9-f8bc-4ec9-b06a-2ec655a07692": {
          "id": "9c3157b9-f8bc-4ec9-b06a-2ec655a07692",
          "status": "approved",
          "amount": 3000,
          "created_at": "2020-07-21 15:46:13",
          "operation": "recurring"
        }
      }
    }
  }
}

Success Response Sample (Recurring was declined and subscription was cancelled immediately due to one of the cancel codes)

{
    "subscription": {
        "id": "876a717d-aa91-4cb7-9209-67519e859a3c",
        "status": "cancelled",
        "started_at": "2020-07-22 12:07:20",
        "expired_at": "2020-07-22 12:16:14",
        "cancelled_at": "2020-07-22 12:16:14",
        "trial": false,
        "payment_type": "card"
    },
    "product": {
        "id": "b001cb28-b050-4b19-9ba9-23a5abc0a0cf",
        "name": "trial / auth-void",
        "amount": 99,
        "currency": "AUD",
        "trial": true,
        "payment_action": "auth_void",
        "trial_period": 7
    },
    "customer": {
        "customer_account_id": "1595419629045"
    },
    "invoices": {
        "6ee15d1c-8db9-4639-8699-23964d125f13": {
            "id": "6ee15d1c-8db9-4639-8699-23964d125f13",
            "amount": 99,
            "status": "success",
            "created_at": "2020-07-22 12:7:20",
            "updated_at": "2020-07-22 12:7:20",
            "orders": {
                "f63d9ded-b64f-467c-9ca1-953f0b29787e": {
                    "id": "f63d9ded-b64f-467c-9ca1-953f0b29787e",
                    "status": "auth_ok",
                    "amount": 99,
                    "created_at": "2020-07-22 12:07:20",
                    "operation": "auth"
                },
                "b12c0f06-5424-4c03-ba44-4892c06ac5cf": {
                    "id": "b12c0f06-5424-4c03-ba44-4892c06ac5cf",
                    "status": "void_ok",
                    "amount": 99,
                    "created_at": "2020-07-22 12:07:20",
                    "operation": "void"
                }
            }
        },
        "a29dd357-2f24-414a-9928-ff86c7a49e49": {
            "id": "a29dd357-2f24-414a-9928-ff86c7a49e49",
            "amount": 3000,
            "status": "fail",
            "created_at": "2020-07-22 12:16:13",
            "updated_at": "2020-07-22 12:16:14",
            "orders": {
                "b04f1249-e9b5-4751-b6e3-757ecf84034c": {
                    "id": "b04f1249-e9b5-4751-b6e3-757ecf84034c",
                    "status": "declined",
                    "amount": 3000,
                    "created_at": "2020-07-22 12:16:13",
                    "failed_reason": "4.07",
                    "operation": "recurring"
                }
            }
        }
    }
}

Success Response Sample (Recurring was rejected due to one of the cancellation codes, for example 3.02, and the subscription goes into a redemption period)

{
    "subscription": {
        "id": "a447d53f-6e63-4491-834c-818aefd2aae6",
        "status": "redemption",
        "started_at": "2020-07-21 15:52:18",
        "expired_at": "2020-07-21 15:53:00",
        "trial": false,
        "payment_type": "card"
    },
    "product": {
        "id": "f3bb14a7-4238-4309-90e5-48ca219dd81f",
        "name": "product for testing everyday subscriptions",
        "amount": 100,
        "currency": "USD",
        "trial": true,
        "payment_action": "auth_void",
        "trial_period": 1
    },
    "customer": {
        "customer_account_id": "testRedemption777"
    },
    "invoices": {
        "44497146-73e0-4a9c-a5a8-5a8b7095742d": {
            "id": "44497146-73e0-4a9c-a5a8-5a8b7095742d",
            "amount": 500,
            "status": "retry",
            "created_at": "2020-07-21 15:56:13",
            "updated_at": "2020-07-21 15:56:14",
            "orders": {
                "14977554-667f-4946-b410-6b2cf0e622ca": {
                    "id": "14977554-667f-4946-b410-6b2cf0e622ca",
                    "status": "declined",
                    "amount": 1000,
                    "created_at": "2020-07-21 15:56:13",
                    "failed_reason": "3.02",
                    "operation": "recurring"
                },
                "21d3bcbd-4561-4e20-8a57-848af0be6ab9": {
                    "id": "21d3bcbd-4561-4e20-8a57-848af0be6ab9",
                    "status": "processing",
                    "amount": 500,
                    "created_at": "2020-07-21 15:56:14",
                    "operation": "recurring"
                }
            }
        }
    }
}

Example of response with information about an 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

Failure Response Sample

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

Example of response with available subscription statuses:

Subscription Statuses 
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’

Cancel codes:

CodeMessageDescription
8.01Card brand 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.02ChargeBackIf 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 DeclineIf 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.07AntifraudAntifraud has blocked the conduct of a recurrent payment due to decline 4.09
8.08Subscription ExpiredThe subscription was created for a limited time. The deadline has expired, the subscription has expired. User is unsubscribed
8.09Cancellation after the redemption periodDecline on the recurring payment. Retries on the redemption period have been activated. Retries had no result. User is unsubscribed.
8.10Token ExpiredThe card has an expiration date. After it was expired, the user is not reissuing the card. User is unsubscribed.
8.11Billing cancellation agreementBilling Token was cancelled by user on PayPal’s side.
   

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

Request parameters

ParameterMandatoryTypeDescriptionExample
customer_account_idyesStringCustomer ID in the merchant’s system1593011107489

Request Sample

{
"customer_account_id":"1593011107489"
}

Parameters of the successful response 

Parameter TypeDescription
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

Success Response Sample


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

Example of response with information about an error 

ParameterTypeDescriptionExample
errorObjectObject with the 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 `customer_account_id` must be provided

Failure Response Sample

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