Introduction

There are two ways to integrate with Transaction Cloud’s platform:

1. Singularity-Integration™

This is the fastest way to integrate. Depending on your use case this integration can be accomplished within a few minutes to a few hours. This integration utilizes Transaction Cloud’s proprietary Singularity-Integration™ which is a combination of Transaction Cloud’s proprietary One-Directional-API™, and One-Data-Cloud™. This integration architecture was designed with speed, flexibility and robustness in mind. It accomplishes everything that a basic webhook integration can provide but without configuring webhooks, without storing information in your system’s database and without having to create a management panel for customers or support personnel. Instead of storing data on your database all the data can be accessed on demand using calls to the One-Directional-API™. Based on your workflow these calls can be made upon events such as customer sign-up, sign-in or certain calls can be made based on a set frequency. Management panel for customers and support personnel can be created by processing the URL from API response in an iframe. There is no need to develop a management panel from scratch. Neither is there any need to set-up a mechanism to deal with duplicate webhooks nor to save customer’s purchase information in your own database.

2. Webhook Integration

As the name suggests this is the webhook integration by which you can receive real-time webhooks. You can configure and process these webhooks, save information in your database, trigger events, and send API requests. This type of integration is typically resource intensive but provides maximum flexibility and customization for an advanced use case. More information about it can be obtained in the Webhook section.

Panel: https://app.transaction.cloud

API URL: https://api.transaction.cloud

Sandbox environment is available for testing. More information on it can be obtained in the Testing section.

How To start?

1st step

Create an account by clicking here. Wait for a welcome email and start the onboarding process with our specialists.

2nd step

Submit your account details for verification. Wait for confirmation email.

3rd step

Create your first product by clicking here: choose suitable product form, one-time payment or subscription and define prices, description and other details. Copy each product ID for further integration in your platform.

4th step

Add our Widget script to the end of your HTML body section.

<script src="https://cdn.transaction.cloud/latest/widget.min.js" async></script>

5th step

Add a payment button to your website where you would like to show your products. We are very flexible in terms of the integration process, so you can do it in 3 ways.

1) Use our easy to use HTML syntax HTML syntax to start buying procedures. It is recommended solution.

2) Use JavaScript API if you need more customization.

3) You can also omit using our JS widget script, and build the URL address of the hosted payment form on your own. Here is the structure:

https://hosted.transaction.cloud/payment/product/PRODUCT_ID

You can pass optional payment parameters as a GET parameters, for example:

https://hosted.transaction.cloud/payment/product/PRODUCT_ID?email=mail@domain.com&firstname=First&lastname=Second

6th step

After successful payment, the customer is redirected to your website on configured in each product URL address with special constant parameters like TRANSACTION_ID and EMAIL.

https://your-domain.com/transactioncloud/order/TRANSACTION_ID/EMAIL

To maintain connection between TransactionCloud one-time payments and subscriptions with your customers accounts we enforce you to assign user account email address in the new transaction.

To do all of this, create a special web page to create a user account and assign a user email address into a new transaction.

Collect TRANSACTION_ID and EMAIL from URL params and validate if the transaction is successful with our API.

Then continue with your own account creation process (create new account or reuse existing one) and assign an account email address to this new transaction with our API.

7th step

Each time you need to check if a user has paid access, check current state with user account email by using our API system.

8th step

Allow your users to manage their own transactions by redirecting to the TransactionCloud management panel with help of our API. All things like transaction review, invoices download, canceling subscription are already ready to use by your users. There’s no need to do it on your own.

9th step

If you have your own customer support administration panel then you can include our management tool into your solution. It's as simple as including one IFRAME with a URL generated by our API.

If you have any questions regarding the integration process feel free to ask us here.

Use cases

Sell one time product to customers

Setting up a 'One-Time Product' in Transaction Cloud's app is simple, just select it as the product type. The app also provides an Embed Product tool to obtain the HTML or JS code to add the product to your website. If preferred, you can use the payment preview URL of the product as a payment link on your website.

Sell recurring subscription to customers

Setting up Recurring Subscriptions in Transaction Cloud's app is easy, simply select 'subscription' as the product type. The app supports daily, weekly, monthly, bi-annually and annually billing frequencies. You can obtain the HTML or JS code to add the product to your website using the Embed Product tool in the app. Alternatively, the payment preview URL of the product can be used as a payment link on your website.

Provide a free trial to customers

To offer customers an initial free trial, activate the free trial option in the subscription product details in Transaction Cloud's app. Upon purchase, the free trial will be triggered. If the customer does not cancel the subscription, they will be charged at the end of the free trial period.

Provide discount to customers

Creating discount coupons in the Transaction Cloud app is straightforward. Customers can redeem the coupon during the checkout process.

Charge Personalized price to the customer

To achieve this, utilize the customize product on demand endpoint and provide the product_id of any ‘One-Time Product’ or ‘Subscription’ configured in the Transaction Cloud app, along with the cart price, description, and payload (which can be the names of items in the cart). Then, use the link provided in the API response to create a checkout button for the customer.

Include any information from your system or customer in the transaction

To achieve this, utilize the "payload" field and transfer information to the checkout screen. Encrypting the payload is recommended. The payload can be obtained through a webhook or via API endpoints and is also visible in the hosted admin app.

Usage based charge to the customer

To achieve this, create a vaulted subscription product in Transaction Cloud’s app then utilize the charge vaulted customer endpoint. You can bill any customer who has bought a vaulted subscription at any time using this endpoint. Our system won't process the payment unless it receives this API request. You must manage the usage data, unit price, and billing frequency for any vaulted subscriptions.

Upgrade / Downgrade product

To achieve this, utilize the customize product on demand and pass only the upgraded/downgrade product_id and transactionIdToMigrate. Then, use the link provided in the API response to create an upgrade/downgrade button for the customer.

HTTP Request

GET https://sandbox-api.transaction.cloud/v1/customize-product/{product_id}

curl --location --request POST 'https://sandbox-api.transaction.cloud/v1/customize-product/TC-PR_X100X10' \
--header 'Authorization: API_KEY:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data-raw '{"transactionIdToMigrate":"TC-TR_X1000"}'

The above command returns JSON structured like this:

{
  "link": "https://hosted.transaction.cloud/payment/product/PC_XXX",
  "customProductId": "PC_z4wvoA0LjMGVLCBxr0UMzpk+KzRbD82BAr0zuLDNl4lr4MOCxz3YM4XDe6eHswLDusAtyO5Z3qrZ5rdraC5e_KLBVhS_X7znubZuKaLlD8pkRoDtEWd4"
}

Pass price from Cart to Checkout

To accomplish this, use the customize product on demand and send the product_id of any one time product in from the Transaction Cloud app, price from the cart, description and payload, which can be names of products in the cart. Then, use the link provided in the API response to create a checkout button for the customer.

HTTP Request

GET https://sandbox-api.transaction.cloud/v1/customize-product/{product_id}

curl --location --request POST 'https://sandbox-api.transaction.cloud/v1/customize-product/TC-PR_X100X10' \
--header 'Authorization: API_KEY:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data-raw '{"prices": [{"currency":"USD", "value" :500.00}], "description": "Product description", "payload" : "Test payload"}'

The above command returns JSON structured like this:

{
  "link": "https://hosted.transaction.cloud/payment/product/PC_XXX",
  "customProductId": "PC_z4wvoA0LjMGVLCBxr0UMzpk+KzRbD82BAr0zuLDNl4lr4MOCxz3YM4XDe6eHswLDusAtyO5Z3qrZ5rdraC5e_KLBVhS_X7znubZuKaLlD8pkRoDtEWd4"
}

API Authentication

The TransactionCloud API uses API key and API password to authenticate requests with Authorization HTTP header. You can take your api key and password from API Set up tab in TransactionCloud Vendor Panel.

Header format:

Authorization: API_KEY:API_PASSWORD

API Endpoints

API URL: https://api.transaction.cloud/

Sandbox API URL: https://sandbox-api.transaction.cloud/

Retrieve URL to manage transactions

This endpoint generates all transactions for customer by his email.

HTTP Request

GET https://sandbox-api.transaction.cloud/v1/generate-url-to-manage-transactions/yourCustomer@domain.com

curl --location --request GET 'https://sandbox-api.transaction.cloud/v1/generate-url-to-manage-transactions/yourCustomer@domain.com' \
--header 'Authorization: API_KEY:API_PASSWORD'

The above command returns JSON structured like this:

{
  "url": "https://hosted.transaction.cloud/manage/token"
}

HTTP status codes:

Query Parameters

Retrieve URL of hosted admin app.

This endpoint generates url to hosted admin panel.

HTTP Request

GET https://sandbox-api.transaction.cloud/v1/generate-url-to-admin

curl --location --request GET 'https://sandbox-api.transaction.cloud/v1/generate-url-to-admin' \
--header 'Authorization: API_KEY:API_PASSWORD'

The above command returns JSON structured like this:

{
  "url": "https://hosted.transaction.cloud/admin/token"
}

HTTP status codes:

Retrieve transactions by email

This endpoint retrieves all transaction data by customer email or assigned email.

HTTP Request

GET https://sandbox-api.transaction.cloud/v1/transactions/yourCustomer@domain.com

curl --location --request GET 'https://sandbox-api.transaction.cloud/v1/transactions/yourCustomer@domain.com' \
--header 'Authorization: API_KEY:API_PASSWORD'

The above command returns JSON structured like this:

[
  {
    "assignedEmail": "",
    "chargeFrequency": "UNKNOWN",
    "country": "US",
    "createDate": "2021-09-20",
    "email": "customer@domain.com",
    "id": "TC-TR_xxyyxxx",
    "lastCharge": "2021-09-20",
    "payload": "",
    "productId": "TC-PR_qqqzzzyy",
    "productName": "Product name",
    "transactionStatus": "ONE_TIME_PAYMENT_STATUS_PAID",
    "transactionType": "ONETIME",
    "netPrice": 20.0,
    "tax": 2.4,
    "currency": "USD",
    "netPriceInUSD": 20.0,
    "netPriceInUSDS": "20.0",
    "netPriceS": "20.0",
    "taxS": "2.4",
    "whoCanceled": null
  },
  {
    "assignedEmail": "",
    "chargeFrequency": "WEEKLY",
    "country": "US",
    "createDate": "2021-09-20",
    "email": "customer@domain.com",
    "id": "TC-TR_yyyxxyy",
    "lastCharge": "2021-09-20",
    "nextCharge": "2021-09-27",
    "payload": "",
    "productId": "TC-PR_zzzyyxx",
    "productName": "Product name",
    "transactionStatus": "SUBSCRIPTION_STATUS_ACTIVE",
    "transactionType": "SUBSCRIPTION",
    "netPrice": 20.0,
    "tax": 2.4,
    "currency": "USD",
    "netPriceInUSD": 20.0,
    "netPriceInUSDS": "20.0",
    "netPriceS": "20.0",
    "taxS": "2.4",
    "whoCanceled": null
  },
  {
    "assignedEmail": "",
    "chargeFrequency": "MONTHLY",
    "country": "US",
    "createDate": "2021-09-17",
    "email": "customer@domain.com",
    "id": "TC-TR_nm7p44R",
    "lastCharge": "2021-09-17",
    "nextCharge": "2021-10-17",
    "payload": "",
    "productId": "TC-PR_x1GDr9m",
    "productName": "Product name",
    "transactionStatus": "SUBSCRIPTION_STATUS_ACTIVE",
    "transactionType": "SUBSCRIPTION",
    "netPrice": 20.0,
    "tax": 2.4,
    "currency": "USD",
    "netPriceInUSD": 20.0,
    "netPriceInUSDS": "20.0",
    "netPriceS": "20.0",
    "taxS": "2.4",
    "whoCanceled": null
  },
  {
    "assignedEmail": "",
    "chargeFrequency": "YEARLY",
    "country": "US",
    "createDate": "2021-09-23",
    "email": "customer@domain.com",
    "id": "TC-TR_yxyyxxx",
    "lastCharge": "2021-09-23",
    "nextCharge": "2022-09-23",
    "payload": "",
    "productId": "TC-PR_yyyzzqqq",
    "productName": "Product name",
    "transactionStatus": "SUBSCRIPTION_STATUS_CANCELLED",
    "transactionType": "SUBSCRIPTION",
    "netPrice": 20.0,
    "tax": 2.4,
    "currency": "USD",
    "netPriceInUSD": 20.0,
    "netPriceInUSDS": "20.0",
    "netPriceS": "20.0",
    "taxS": "2.4",
    "whoCanceled": "CUSTOMER"
  }
]

HTTP status codes:

URL Parameters

Response parameters

Charge frequencies

Transaction statuses

Transaction types

Who initiated cancelation

Retrieve transaction by transaction id.

This endpoint retrieves transaction details by transaction id.

HTTP Request

GET https://sandbox-api.transaction.cloud/v1/transaction/<id>

curl --location --request GET 'https://sandbox-api.transaction.cloud/v1/transaction/TC-TR_xxyyxxx' \
--header 'Authorization: API_KEY:API_PASSWORD'

The above command returns JSON structured like this:

{
  "chargeFrequency": "UNKNOWN",
  "country": "US",
  "createDate": "2021-09-20",
  "email": "customer@domain.com",
  "id": "TC-TR_xxyyxxx",
  "lastCharge": "2021-09-20",
  "payload": "",
  "productId": "TC-PR_qqqzzzyy",
  "productName": "Product name",
  "transactionStatus": "ONE_TIME_PAYMENT_STATUS_PAID",
  "transactionType": "ONETIME",
  "netPrice": 20.0,
  "tax": 2.4,
  "currency": "USD",
  "netPriceInUSD": 20.0,
  "netPriceInUSDS": "20.0",
  "netPriceS": "20.0",
  "taxS": "2.4",
  "whoCanceled": null,
  "entries":[
    {
      "affiliateIncome":"10.0",
      "affiliateIncomeCurrency":"USD",
      "amountTotal":"37.0",
      "country":"CY",
      "createDate":"2022-09-22T06:57:25.000Z",
      "currency":"EUR",
      "id":"TC-BA_nm7qD0A",
      "income":"27.0",
      "incomeCurrency":"USD",
      "taxAmount":"5.0",
      "taxRate":0.19,
      "type":"SUBSCRIPTION_PAYMENT"
    },
    {
      "affiliateIncome":"10.0",
      "affiliateIncomeCurrency":"USD",
      "amountTotal":"37.0",
      "country":"CY",
      "createDate":"2022-09-23T06:58:26.000Z",
      "currency":"EUR",
      "id":"TC-BA_7R3lvVA",
      "income":"27.0",
      "incomeCurrency":"USD",
      "taxAmount":"5.0",
      "taxRate":0.19,
      "type":"SUBSCRIPTION_PAYMENT"
    }]
}

HTTP status codes:

URL Parameters

Assign email address by transaction id.

This endpoint changes customer assigned email for transaction by id.

HTTP Request

POST https://sandbox-api.transaction.cloud/v1/transaction/<transaction-id>

curl --location --request POST 'https://sandbox-api.transaction.cloud/v1/transaction/TC-TR_zxzqqqq' \
--header 'Authorization: API_KEY:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data-raw '{"assignEmail":"assignedEmail@domain.com"}'

The above command returns JSON structured like this:

{
  "assignEmail": "assignedEmail@domain.com",
  "chargeFrequency": "UNKNOWN",
  "country": "US",
  "createDate": "2021-09-14",
  "email": "customer@domain.com",
  "id": "TC-TR_zxzqqqq",
  "lastCharge": "2021-09-14",
  "payload": "",
  "productId": "TC-PR_xxxqqzz",
  "productName": "Product name",
  "transactionStatus": "TRANSACTION_STATUS_REFUNDED",
  "transactionType": "ONETIME",
  "whoCanceled": null
}

HTTP status codes:

URL Parameters

Data parameters

Edit Existing Payload by transaction id.

This endpoint changes payload for transaction by id. The maximum length of the payload string can be 5000 characters.

HTTP Request

POST https://sandbox-api.transaction.cloud/v1/transaction/<transaction-id>

curl --location --request POST 'https://sandbox-api.transaction.cloud/v1/transaction/TC-TR_zxzqqqq' \
--header 'Authorization: API_KEY:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data-raw '{"payload":"new payload data"}'

The above command returns JSON structured like this:

{
  "assignEmail": "assignedEmail@domain.com",
  "chargeFrequency": "UNKNOWN",
  "country": "US",
  "createDate": "2021-09-14",
  "email": "customer@domain.com",
  "id": "TC-TR_zxzqqqq",
  "lastCharge": "2021-09-14",
  "payload": "new payload data",
  "productId": "TC-PR_xxxqqzz",
  "productName": "Product name",
  "transactionStatus": "TRANSACTION_STATUS_REFUNDED",
  "transactionType": "ONETIME",
  "whoCanceled": null
}

HTTP status codes:

URL Parameters

Data parameters

Cancel subscription

This endpoint cancel subscription by subscription id.

HTTP Request

POST https://sandbox-api.transaction.cloud/v1/cancel-subscription/<id>

curl --location --request POST 'https://sandbox-api.transaction.cloud/v1/cancel-subscription/TC-TR_XXXXXX' \
--header 'Authorization: API_KEY:API_PASSWORD'

HTTP status codes:

URL Parameters

Refund payment

This endpoint refund payment by id. ID can be retrieved from this endpoint.

HTTP Request

POST https://sandbox-api.transaction.cloud/v1/refund-transaction/<id>

curl --location --request POST 'https://sandbox-api.transaction.cloud/v1/refund-transaction/TC-BA_XXXXXXX' \
--header 'Authorization: API_KEY:API_PASSWORD'

The above command returns JSON structured like this:

[
  {
    "TCFee": 0.72,
    "amountTotal": 4.36,
    "currency": "USD",
    "externalId": "5559995555",
    "hashId": "TC-BA_YYYZZZX",
    "id": "4/2/2022",
    "incomeCurrency": "USD",
    "invoiceLink": "https://api.transaction.cloud/invoice/TC-BA_YYYZZZX",
    "paymentProvider": "BLUESNAP",
    "refundable": false,
    "taxAmount": 0.36,
    "timestamp": 1643974626000,
    "transactionFee": 0.0,
    "vendorIncome": 3.28,
    "country": "US",
    "TCFeeS": "0.72",
    "amountTotalS": "4.36",
    "taxAmountS": "0.36",
    "transactionFeeS": "0.0",
    "vendorIncomeS": "3.28"
  }
]

HTTP status codes:

URL Parameters

Retrieve transactions with changed status

curl --location --request GET 'https://sandbox-api.transaction.cloud/v1/changed-transactions' \
--header 'Authorization: API_KEY:API_PASSWORD'

Retrieve transactions with changed status recently for processing. Changed status field in transactions will be change value to empty string after retrieving transactions with filled this field.

HTTP Request

GET https://sandbox-api.transaction.cloud/v1/changed-transactions

This endpoint return transactions with field: 'changedStatus'. Possible values for field 'changedStatus' are:

Changed status can be retrieved via webhooks. Url can be setup in vendor panel.

The above command returns JSON structured like this:

[
  {
    "assignedEmail": "",
    "changedStatus": "CHANGED_STATUS_CANCELLED",
    "chargeFrequency": "MONTHLY",
    "country": "US",
    "createDate": "2022-01-31",
    "email": "customer@domain.com",
    "id": "TC-TR_XXXYYZZ",
    "lastCharge": "2022-01-31",
    "nextCharge": "2022-02-28",
    "payload": "",
    "productId": "TC-PR_XXXYYZZ",
    "productName": "Product",
    "transactionStatus": "SUBSCRIPTION_STATUS_CANCELLED",
    "transactionType": "SUBSCRIPTION",
    "whoCanceled": "VENDOR"
  },
  {
    "assignedEmail": "",
    "changedStatus": "CHANGED_STATUS_NEW",
    "chargeFrequency": "WEEKLY",
    "country": "US",
    "createDate": "2022-02-02",
    "email": "customer@domain.com",
    "id": "TC-TR_YYYZZXX",
    "lastCharge": "2022-02-02",
    "nextCharge": "2022-02-09",
    "payload": "",
    "productId": "TC-PR_XXXXXXX",
    "productName": "Another product",
    "transactionStatus": "SUBSCRIPTION_STATUS_ACTIVE",
    "transactionType": "SUBSCRIPTION",
    "whoCanceled": null
  },
  {
    "assignedEmail": "assignedUser@domain.com",
    "changedStatus": "CHANGED_STATUS_NEW",
    "chargeFrequency": "UNKNOWN",
    "country": "US",
    "createDate": "2022-02-04",
    "email": "customer@domain.com",
    "id": "TC-TR_ZZZZYYX",
    "lastCharge": "2022-02-04",
    "payload": "",
    "productId": "TC-PR_YYYZZXX",
    "productName": "One time product",
    "transactionStatus": "ONE_TIME_PAYMENT_STATUS_PAID",
    "transactionType": "ONETIME",
    "whoCanceled": null
  }
]

HTTP status codes:

Marking transactions as processed

Transaction can be marked as a processed after some action.

HTTP Request

POST https://sandbox-api.transaction.cloud/v1/changed-transactions/TC-TR_XXXYYZZ

curl --location --request POST 'https://sandbox-api.transaction.cloud/v1/changed-transactions/TC-TR_XXXYYZZ' \
--header 'Authorization: API_KEY:PASSWORD'

HTTP status codes:

Customize product on demand

This endpoint allows to customize product on demand and generate new customized product ID and link to payment. New product ID can be used to payment or widget.

HTTP Request

POST https://sandbox-api.transaction.cloud/v1/customize-product/{product_id}

curl --location --request POST 'https://sandbox-api.transaction.cloud/v1/customize-product/TC-PR_X100X10' \
--header 'Authorization: API_KEY:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data-raw '{"prices": [{"currency":"USD", "value" :500.00}], "description": "Product description", "payload" : "Test payload", "transactionIdToMigrate":"TC-TR_X1000", "expiresIn": 60}'

Request data

The above command returns JSON structured like this:

{
  "link": "https://hosted.transaction.cloud/payment/product/PC_XXX",
  "customProductId": "PC_z4wvoA0LjMGVLCBxr0UMzpk+KzRbD82BAr0zuLDNl4lr4MOCxz3YM4XDe6eHswLDusAtyO5Z3qrZ5rdraC5e_KLBVhS_X7znubZuKaLlD8pkRoDtEWd4"
}

HTTP status codes:

Charge vaulted customer

curl --location --request POST 'https://sandbox-api.transaction.cloud/v1/charge-vaulted/TC-TR_XXXYYZZ' \
--header 'Authorization: API_KEY:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data-raw '{"prices": [{"currency":"USD", "value" :500.00}], "chargeDescription":"SaaS description"}'

Charge vaulted customer based on given price for SaaS services.

HTTP Request

https://sandbox-api.transaction.cloud/v1/charge-vaulted/transaction_id

Request data

The above command returns JSON structured like this:

{
  "currency": "EUR",
  "deactivation": false,
  "netValue": 525,
  "price": 624,
  "status": "SUCCESS",
  "taxValue": 99,
  "netValueS": "525",
  "priceS": "624",
  "taxValueS": "99"
}

HTTP status codes:

Response data

FAQ

Use Cases and Checkout Process Questions

1. What are the available use cases?

Fixed price subscriptions, one-time products, metered/usage-based billing, subscriptions with trials, customized pricing for each customer, checkout for multiple products in a cart, and discount coupons are among the possible use cases. If you have a unique requirement, contact customer service as they may already have a solution for it.

2. How can I generate a payment link?

You can obtain a payment link by copying the URL of the checkout page of the product.

3. How can I include our own order number in the checkout process and receive it after a customer's successful payment?

You can add your internal order number to the transaction by utilizing the payload field.

4. How can I keep track of the number of licenses purchased by a customer for internal reference?

The information can be added to the payload field. Additionally, you have the ability to modify the payload at a later time to reflect any changes in the number of licenses used by the customer.

5. How can I include additional information, such as the customer's website, with an order?

The payload field can be utilized to attach extra information to an order, such as an order number, the customer's website URL, or the number of licenses purchased. This information can be edited later, accessed through an API request or Webhook, and viewed in the admin plugin tool, providing valuable information for customer service purposes.

6.How can I display the checkout page in the customer's preferred language?

The checkout page automatically recognizes the language setting of the customer's device and opens the page accordingly.

7. How can I implement usage-based or variable billing for a subscription product?

You can create a vaulted subscription product through the app and use API calls to charge the customer based on their usage and the agreed upon billing frequency. This will allow you to charge custom prices on-demand.

8. How can I charge customers a personalized price based on selected options?

The custom-product endpoint allows you to generate a temporary, unique productId, which can be used to charge each customer an individualized price. This endpoint can also be used in the shopping cart when a customer has added multiple items from your website.

9. Does using the custom product endpoint result in the creation of new products in the app?

No, utilizing the custom product endpoint does not result in the creation of new products in the app. It only generates a temporary, unique product ID.

10. What is the process to set up discount coupons?

To create discount coupons, you can use the coupons section within the app.

11. How can I obtain the code to open the checkout screen from my website?

The code can be generated using the Embed Product tool in the app. By inserting the code on your website's product or pricing page, a button will be created to open the checkout screen.

12. Can I choose a specific billing frequency for my subscription products?

Yes, you have the option to select daily, weekly, monthly, semi-annually, or annual billing frequency for your subscription products. With vaulted subscriptions, you have complete control over the billing frequency, and you can trigger a charge for the customer at any time using the API call.

13. Is it possible to show the checkout page on my own website?

Yes, you can utilize the plugin code from the Embed product tool to open the checkout in a pop-up overlay. However, it's important to note that some payment options may not be available to the customer due to security restrictions from various payment methods. The hosted checkout page offers a larger number of payment methods, boosting conversion rates.

Webhooks and API Questions

1. Is it possible to receive webhook notifications via email?

Transaction Cloud offers email notifications for events such as subscription activation, deactivation, charge, and refund. If you require webhooks to be sent to your email, you may use a third-party service or write custom code.

2. How many webhook URLs can I set up?

You can set up to 5 URLs separated by '|' in the API setup section of the app. This allows you to receive webhooks simultaneously on multiple systems, such as order fulfillment, CRM, email marketing, accounting, etc.E.g.: https://example1.com|example2.com|example3.com|example4.com|example5.com

3. Why am I receiving 401 unauthorized responses from the API?

If you are receiving 401 unauthorized responses from the API, it is likely because you are using incorrect authentication credentials. Please make sure you are using the correct API_KEY:API_PASSWORD, as using credentials from the sandbox on the production API or vice versa is a common cause of this error.

4. How can I confirm the authenticity of a webhook?

You can verify the authenticity of a webhook by using its IP address. https://app.transaction.cloud/api-docs/#webhook-verification

5. How can I prevent information duplication caused by repeated webhooks?

To prevent information duplication caused by repeated webhooks, you can store the unique webhookId for each event in your database. Our system will repeat a webhook until it receives an HTTP status code of 200. By keeping track of the webhookId, your system can determine if a received webhook is new or a repeat, thus avoiding duplication of information.

Customer Management and Access Questions

1. How do I give the customer access to their purchased product?

The access to the customer's purchased product can be granted as follows:

With Singularity Integration, have the customer sign in to your platform and use the API endpoint to retrieve a list of the customer's purchased products. This list can then be used to make the purchased product accessible.
https://app.transaction.cloud/api-docs/#retrieve-transactions-by-email

With webhook integration, your system should already have information on purchased and active products stored in your database, which can be used to provide access to the customer's purchased product.

2. How can I show an account management screen to the customer?

The account management screen can be made available to the customer by having them sign in to your platform and using the API endpoint. This will generate the URL for the screen, which can be displayed within an iframe. Additionally, the customer can access the management screen through a link in Transaction Cloud's notification emails.
https://app.transaction.cloud/api-docs/#retrieve-url-to-manage-transactions

3. How can I provide a management screen to my customer service representative?

The management screen can be made available to your customer service representative by having them sign in to your platform and using the API endpoint. The URL for the management screen will be generated, which can then be displayed within an iframe for the representative
https://app.transaction.cloud/api-docs/#retrieve-url-of-hosted-admin-app

Affiliate and Fraud Prevention Questions

1. Do affiliates have access to a dashboard to view their account balance and campaign performance?

Yes, affiliates have their own panel with a dashboard, performance details, and the ability to generate marketing links to promote your landing page.

2. How do I activate fraud prevention?

Fraud prevention is already active on your account and requires no configuration or set-up rules.

Integration Questions

1. How do I integrate Transaction Cloud with Wordpress, Woocommerce, Bubble, or Tilda?

You can utilize the embed product tool within the app to create the code that can be inserted on your website's product or pricing page.

2. Will your team provide code for my website?

No, our team cannot provide code for your website. However, our technical support team will assist you by answering any questions and providing you with all necessary information to ensure a smooth and efficient integration.

Feature Related Questions

1. How do I request new features for the platform?

To request new features, kindly send an email to our customer service team.

2. What's the next feature in the pipeline?

To find out the upcoming features, please contact the customer service team, who can provide you with the latest information.

Widget.js

Get Started

In order, to speed up the integration, we have developed a simple and easy-to-use JavaScript plug-in Widget.js which can be quickly embedded on your website.

Widget.js allows you to:

• Automatically geolocate the customer and display formatted product price and the correct sales tax in the local currency of the customer
• Start the checkout process with prefilled data like email address, full name etc. once the customer selects the subscription product by selecting its billing plan

Widget.js URL: https://cdn.transaction.cloud/latest/widget.min.js

Sandbox Widget.js URL: https://sandbox-cdn.transaction.cloud/latest/widget.sandbox.min.js

Installation

In order, to start using Widget.js include the following HTML script snippet before your application code. In most cases it needs to be included in the beginning of <head>tag.

Widget.js supports 2 ways of product embedding: Basic Integration (HTML syntax) and Advanced integration (JS API).

If you have just static website, we recommedn you to choose basic integration. If you need more flexibility and/or you're using JS frameworks like Angular, React, Vue.js etc. we higly recommend you to start with advanced integration process.

Basic Integration (HTML syntax)

Our Widget.js script detects the special HTML data tags for embedding the price and for starting the checkout process.

Displaying Product Price

Product name: <span data-ts-product-name data-ts-product="TC-EXAMPLE-PRODUCT-ID"></span>

Product description: <p data-ts-product-description data-ts-product="TC-EXAMPLE-PRODUCT-ID"></p>

Product image: <div data-ts-product-image data-ts-product="TC-EXAMPLE-PRODUCT-ID"></div>

Displaying Product Price

To display product price, include the following data tag on any HTML object such as span, div or anything that suits your layout.

Price (gross): <span data-ts-price data-ts-product="TC-EXAMPLE-PRODUCT-ID"></span>

Price (nett): <span data-ts-price data-ts-show-net="true" data-ts-product="TC-EXAMPLE-PRODUCT-ID"></span>

Price (tax): <span data-ts-price data-ts-show-tax="true" data-ts-product="TC-EXAMPLE-PRODUCT-ID"></span>

Starting Checkout Process

To start checkout process of any product, use the following data tag on any HTML object such as button, span, div or anything that you want to use to trigger checkout.

<button data-ts-button data-ts-product="TC-EXAMPLE-PRODUCT-ID"></button>

In the above example, standard styles will be applied. If you want to style the payment button with your own branding, add data-ts-style="none" tag. Please see the example below,

<button data-ts-button data-ts-product="TC-EXAMPLE-PRODUCT-ID" data-ts-style="none"></button>

By default payment form will replace current page. If yu prefer to open in in Popup, pass additional parameter:

<button data-ts-button data-ts-popup="true" data-ts-product="TC-EXAMPLE-PRODUCT-ID"></button>

Warning! Not all payment methods are available in this mode. For example Apple Pay is not allowed in Popup mode.

You can also pass additional information about the customer if you want to use prefilled details. Please see full example below:

<button
   data-ts-first-name="Test"
   data-ts-last-name="Test"
   data-ts-zip-code="18951"
   data-ts-company-name="Test"
   data-ts-company-id="123"
   data-ts-email="test@test.com"
   data-ts-non-editable-email="true"
   data-ts-coupon="SPECIAL-COUPON"
   data-ts-payload="secured-encrypted-string-here"></button>

In the above example, payload is used to pass your customer’s data in the form of an encrypted serialized string. You can also force the checkout form to make the email address of the customer non editable.

Advanced integration (JS API)

Our Widget.js script also opens the possibility of using public JS API for more advanced use-cases. With this solution, you have even more control and flexibility on the integration process. It’s a perfect match for JS frameworks like Angular, React or Vue.js. All public methods are available in global window.tc variable and use Promise pattern to handle asynchronous tasks.

To display product price, use code below:

tc.getPrice("TC-EXAMPLE-PRODUCT-ID").then(
    (price) => {
        console.log(price);
        // {
        //  currency: string,
        //  price: number,
        //  priceNet: number,
        //  tax: number,
        //  taxName: string,
        //  taxRate: number
        // }
    },
    (error) => console.error(error)
);

To get full product model, use code below:

tc.getProduct("TC-EXAMPLE-PRODUCT-ID").then(
    (product) => {
        console.log(product);
        // {
        //     id: string,
        //     name: string,
        //     description: string,
        //     logoUrl: string,
        //     recurring: boolean,
        //     type: 'PRODUCT_TYPE_VAULTED', 'PRODUCT_TYPE_RECURRING', 'PRODUCT_TYPE_ONETIME',
        //     chargeFrequency: null | 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'HALF_YEARLY', 'YEARLY',
        //     price: {
        //         currency: string,
        //         price: number,
        //         priceNet: number,
        //         tax: number,
        //         taxName: string,
        //         taxRate: number
        //     }
        // }
    },
    (error) => console.error(error)
);

To start payment of given product, use code below:

tc.buy("TC-EXAMPLE-PRODUCT-ID").then(
    () => {
        console.log('payment started');
    },
    (error) => console.error(error)
);

By default payment form will replace current page. If yu prefer to open in in Popup, pass additional parameter:

tc.buy("TC-EXAMPLE-PRODUCT-ID", { popup: true }).then(
    (data) => {
        console.log(data);
        // {
        //     type: 'CLOSE' | 'TRANSACTION',
        //     message: string,
        //     transaction null | {
        //         id: string,
        //         email: string,
        //         url: string
        //     }
        // }
    },
    (error) => console.error(error)
);

Warning! Not all payment methods are available in this mode. For example Apple Pay is not allowed in Popup mode.

You can also pass additional information about the customer if you want to use prefilled details. Please see full example below:

tc.buy("TC-EXAMPLE-PRODUCT-ID", {
    firstName: 'Test',
    lastName: 'Test',
    companyName: 'Test',
    companyId: '123',
    zipCode: '18951',
    email: 'test@test.com',
    nonEditableEmail: true,
    coupon: 'SPECIAL-COUPON',
    payload: 'secured-encrypted-string-here'
}).then(
    () => {
        console.log('payment started');
    },
    (error) => console.error(error)
);

Please note that second options argument is completely optional and can be skipped.

Payload

Payload can be used to pass any data in the form of an encrypted serialized string. Example use cases: Internal order reference number, Licenses purchased by customer, Products purchased by customer, User ID. The maximum length of the payload string can be 5000 characters. Upon successful completion of transaction, Payload can be obtained via webhooks or by using one of the Retrieve Transactions endpoint. Existing Payload can also be updated using the Edit Existing Payload endpoint.

Webhooks

Overview

Transaction Cloud also supports integration using webhooks. You can integrate these webhooks with your backend or third-party systems for updating your database and triggering events

Set up Webhooks

You can define your webhook URL in the API setup section of the production or sandbox app. Subsequently, webhooks are posted on this URL for all future events. There are two categories of webhooks:

1. Orders:

Activation/cancellation of subscriptions, purchase of one time product, and activation/deactivation of vaulted subscriptions.

2. Balance Affecting Events:

Charges, and refunds to customers.

Please note, our system does automatic retries of the webhook until HTTP status code 200 is received. We recommend designing the script to parse duplicate posts.

Webhook contents

Webhook verification

You can use the IP address to verify webhook. All webhook will arrive from this IP:

Webhook examples (in the shell section):

Subscription Purchase:

{
  "webhookId": "NhczrAwugRAiS4K",
  "webhookType": "SUBSCRIPTION_ACTIVATED",
  "whoCanceled": null,
  "transactionId": "TC-TR_XXXYYZZ",
  "transactionType": "SUBSCRIPTION",
  "createDate": "2022-11-23T20:30:03.586Z",
  "nextCharge": "2022-12-23T20:30:03.586Z",
  "lastCharge": "2022-11-23T20:30:03.586Z",
  "chargeFrequency": "MONTHLY",
  "productId": "TC-PR_1112233",
  "productName": "Product",
  "payload": "",
  "transactionStatus": "SUBSCRIPTION_STATUS_ACTIVE",
  "firstName": "customer_first_name",
  "lastName": "customer_last_name",
  "organization": "",
  "email": "customer@domain.com",
  "assignedEmail": "",
  "country": "US"
}

Subscription Cancellation:

{
  "webhookId": "yRafvEh9AQaRFIu",
  "webhookType": "SUBSCRIPTION_CANCELLED",
  "whoCanceled": "CUSTOMER",
  "transactionId": "TC-TR_XXXYYZZ",
  "transactionType": "SUBSCRIPTION",
  "createDate": "2022-11-23T20:30:03.586Z",
  "nextCharge": "2022-12-23T20:30:03.586Z",
  "lastCharge": "2022-11-23T20:30:03.586Z",
  "chargeFrequency": "MONTHLY",
  "productId": "TC-PR_1112233",
  "productName": "Product",
  "payload": "",
  "transactionStatus": "SUBSCRIPTION_STATUS_CANCELLED",
  "firstName": "customer_first_name",
  "lastName": "customer_last_name",
  "organization": "",
  "email": "customer@domain.com",
  "assignedEmail": "",
  "country": "US"
}

Vaulted Subscription Activation:

{
  "webhookId": "uSKCLf8LOGkouEY",
  "webhookType": "VAULTED_SUBSCRIPTION_ACTIVATED",
  "whoCanceled": null,
  "transactionId": "TC-TR_FFFGGHH",
  "transactionType": "VAULTED",
  "createDate": "2022-11-24T00:21:15.986Z",
  "lastCharge": "2022-11-24T00:21:15.986Z",
  "chargeFrequency": "UNKNOWN",
  "productId": "TC-PR_1112299",
  "productName": "Product",
  "payload": "",
  "transactionStatus": "VAULTED_STATUS_ACTIVE",
  "firstName": "customer_first_name",
  "lastName": "customer_last_name",
  "organization": "",
  "email": "customer@domain.com",
  "assignedEmail": "",
  "country": "US"
}

Purchase of One Time Product:

{
  "webhookId": "x20rq2SDMMzdZ1O",
  "webhookType": "ONETIME_PAID",
  "whoCanceled": null,
  "transactionId": "TC-TR_LLLKKJJ",
  "productId": "TC-PR_NNNMMAA",
  "productName": "Product",
  "createDate": "2022-11-23T22:16:05.287Z",
  "payload": "",
  "transactionType": "ONETIME",
  "transactionStatus": "ONE_TIME_PAYMENT_STATUS_PAID",
  "lastCharge": "2022-11-23T22:16:05.287Z",
  "chargeFrequency": "UNKNOWN",
  "email": "customer@domain.com",
  "assignedEmail": "",
  "country": "US",
  "organization": "",
  "firstName": "customer_first_name",
  "lastName": "customer_last_name"
}

Subscription’s First charge:

{
  "webhookId": "pmH4KtToca8QjzC",
  "webhookType": "CHARGE",
  "whoCanceled": null,
  "transactionId": "TC-TR_XXXYYZZ",
  "transactionType": "SUBSCRIPTION",
  "createDate": "2022-11-23T20:30:03.586Z",
  "productId": "TC-PR_1112233",
  "productName": "Product",
  "firstName": "customer_first_name",
  "lastName": "customer_last_name",
  "organization": "",
  "email": "customer@domain.com",
  "assignedEmail": "",
  "country": "US",
  "eventId": "TC-BA_AAABBCC",
  "currency": "USD",
  "amountTotal": "5400.00",
  "taxAmount": "400.00",
  "income": "4729.50",
  "taxRate": "0.08",
  "affiliateCommission": "0.00",
  "affiliateCommissionCurrency": "USD"
}

Subscription’s Renewal

{
  "webhookId": "qtL5LuUpdb9RkzD",
  "webhookType": "CHARGE",
  "transactionId": "TC-TR_XXXYYZZ",
  "transactionType": "SUBSCRIPTION",
  "whoCanceled": null,
  "createDate": "2022-11-23T20:30:03.586Z",
  "productId": "TC-PR_1112233",
  "productName": "Product",
  "firstName": "customer_first_name",
  "lastName": "customer_last_name",
  "organization": "",
  "email": "customer@domain.com",
  "assignedEmail": "",
  "country": "US",
  "eventId": "TC-BA_CCCDDEE",
  "currency": "USD",
  "amountTotal": "5400.00",
  "taxAmount": "400.00",
  "income": "4729.50",
  "taxRate": "0.08",
  "affiliateCommission": "0.00",
  "affiliateCommissionCurrency": "USD"
}

Refund of a charge:

{
  "webhookId": "qn8ixxv6jy4tReQ",
  "webhookType": "REFUND",
  "whoCanceled": null,
  "transactionId": "TC-TR_XXXYYZZ",
  "transactionType": "SUBSCRIPTION",
  "createDate": "2022-11-23T20:30:03.586Z",
  "productId": "TC-PR_1112233",
  "productName": "Product",
  "firstName": "customer_first_name",
  "lastName": "customer_last_name",
  "organization": "",
  "email": "customer@domain.com",
  "assignedEmail": "",
  "country": "US",
  "eventId": "TC-BA_DDDEEFF",
  "currency": "USD",
  "amountTotal": "-5400.00",
  "taxAmount": "-400.00",
  "income": "-5000.00",
  "taxRate": "0.08",
  "affiliateCommission": "0.00",
  "affiliateCommissionCurrency": "USD"
}

Charge for One Time Product:

{
  "webhookId": "BpQlxiBykCpdp2d",
  "webhookType": "CHARGE",
  "whoCanceled": null,
  "transactionId": "TC-TR_LLLKKJJ",
  "transactionType": "ONETIME",
  "createDate": "2022-11-23T22:16:05.287Z",
  "productId": "TC-PR_NNNMMAA",
  "productName": "Product",
  "firstName": "customer_first_name",
  "lastName": "customer_last_name",
  "organization": "",
  "email": "customer@domain.com",
  "assignedEmail": "",
  "country": "US",
  "eventId": "TC-BA_ZZZCCVV",
  "currency": "USD",
  "amountTotal": "32.39",
  "taxAmount": "2.40",
  "income": "27.87",
  "taxRate": "0.08",
  "affiliateCommission": "0.00",
  "affiliateCommissionCurrency": "USD"
}

Chargeback:

{
  "webhookId": "qn8ixxv6jy4tReQ",
  "webhookType": "CHARGEBACK",
  "whoCanceled": null,
  "transactionId": "TC-TR_XXXYYZZ",
  "transactionType": "SUBSCRIPTION",
  "createDate": "2022-11-23T20:30:03.586Z",
  "productId": "TC-PR_1112233",
  "productName": "Product",
  "firstName": "customer_first_name",
  "lastName": "customer_last_name",
  "organization": "",
  "email": "customer@domain.com",
  "assignedEmail": "",
  "country": "US",
  "eventId": "TC-BA_DDDEEFF",
  "currency": "USD",
  "amountTotal": "-30.00",
  "taxAmount": "0.00",
  "income": "-30.00",
  "taxRate": "0.00",
  "affiliateCommission": "0.00",
  "affiliateCommissionCurrency": "USD"
}

Testing

Sandbox Environment

Test the integration in a specially prepared Sandbox Environment. Create separate account and products on https://sandbox-app.transaction.cloud. Everything works the same as in the production environment, except that the transactions are virtual and do not result in actual payments.

Sandbox Panel: https://sandbox-app.transaction.cloud

Sandbox API URL: https://sandbox-api.transaction.cloud

Sandbox Widget.js URL: https://sandbox-cdn.transaction.cloud/latest/widget.sandbox.min.js

Cards

Please use the following cards for testing the checkout process of sandbox account using cards:

Google Pay

You can use your existing Google Pay account to complete the checkout process in Sandbox. Even though your real card is associated with your GooglePay account, there won’t be a real charge on your card while testing the sandbox checkout process.

PayPal

Please use the following cars for testing the checkout process of sandbox account using PayPal:

Apple Pay

Unfortunately, due to restrictions from Apple. Apple Pay is only available in production mode so no sandbox testing can be performed.