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. Traditional Webhook Integration™

As the name suggests this is the traditional 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.

API Authentication

The TransactionCloud API uses API key and API password to authenticate requests. You can take your api key and password from 'API' tab in TransactionCloud Vendor Panel.

Authorization: API_KEY:API_PASSWORD

You must replace API_KEY:API_PASSWORD with your personal API key.

API Endpoints

Retrieve URL to manage transactions

This endpoint generates all transactions for customer by his email.

HTTP Request

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

curl --location --request GET 'https://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:

Code	Description
200	OK
401	Unauthorized

Query Parameters

Parameter	Default	Description
email	true	Set customer email.

Retrieve URL of hosted admin app.

This endpoint generates url to hosted admin panel.

HTTP Request

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

curl --location --request GET 'https://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:

Code	Description
200	OK
401	Unauthorized

Retrieve transactions by email

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

HTTP Request

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

curl --location --request GET 'https://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"
  },
  {
    "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"
  },
  {
    "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"
  },
  {
    "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"
  }
]

HTTP status codes:

Code	Description
200	OK
401	Unauthorized

URL Parameters

Parameter	Description
email	The email of customer.

Response parameters

Charge frequencies

Parameter	Description
DAILY	Represents daily subscription.
WEEKLY	Represents weekly subscription.
MONTHLY	Represents monthly subscription.
YEARLY	Represents yearly subscription.

Transaction statuses

Parameter	Description
TRANSACTION_STATUS_PENDING	Status of transaction is pending.
TRANSACTION_STATUS_REFUNDED	Status of transaction is refunded.
ONE_TIME_PAYMENT_STATUS_PAID	Status of one time payment transaction is paid.
SUBSCRIPTION_STATUS_ACTIVE	Status of subscription is active.
SUBSCRIPTION_STATUS_CANCELLED_PENDING	Status of subscription is cancelled pending.
SUBSCRIPTION_STATUS_CANCELLED	Status of subscription is cancelled.

Transaction types

Parameter	Description
ONETIME	Represents one time payment transaction type.
SUBSCRIPTION	Represents subscription transaction type.

Retrieve transaction by transaction id.

This endpoint retrieves transaction details by transaction id.

HTTP Request

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

curl --location --request GET 'https://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",
  "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:

Code	Description
200	OK
401	Unauthorized
404	Transaction not found

URL Parameters

Parameter	Description
id	The id of transaction id.

Assign email address by transaction id.

This endpoint changes customer assigned email for transaction by id.

HTTP Request

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

curl --location --request POST 'https://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"
}

HTTP status codes:

Code	Description
200	OK
401	Unauthorized
403	Wrong request
404	Transaction not found

URL Parameters

Parameter	Description
id	The id of transaction id.

Data parameters

Parameter	Description
assignEmail	Assign email address for a customer.

Cancel subscription

This endpoint cancel subscription by subscription id.

HTTP Request

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

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

HTTP status codes:

Code	Description
200	OK
401	Unauthorized
403	Wrong request
404	Subscription not found

URL Parameters

Parameter	Description
id	The id of subscription id.

Refund payment

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

HTTP Request

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

curl --location --request POST 'https://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:

Code	Description
200	OK
401	Unauthorized
403	Wrong request
404	Subscription not found

URL Parameters

Parameter	Description
id	The id of transaction id.

Retrieve transactions with changed status

curl --location --request GET 'https://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://api.transaction.cloud/v1/changed-transactions

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

Parameter	Description
CHANGED_STATUS_NEW	Recently changed status to new.
CHANGED_STATUS_RENEWED	Recently changed status to renewed (renewal of subscription).
CHANGED_STATUS_CANCELLED	Recently changed status to cancelled.
CHANGED_STATUS_REFUNDED	Recently changed status to refunded.
CHANGED_STATUS_TRIAL	Recently changed status to trial.
CHANGED_STATUS_VAULTED_ACTIVATION	Recently changed status to vaulted active.
CHANGED_STATUS_VAULTED_DEACTIVATION	Recently changed status to vaulted inactive.

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

HTTP status codes:

Code	Description
200	OK
401	Unauthorized
403	Wrong request

Marking transactions as processed

Transaction can be marked as a processed after some action.

HTTP Request

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

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

HTTP status codes:

Code	Description
200	OK
401	Unauthorized
403	Wrong request
404	Product not found

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://api.transaction.cloud/v1/customize-product/{product_id}

curl --location --request POST 'https://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"}'

URL	Parameters
product_id	product id to be customized

Request data

Parameter	Description
prices	list of prices. USD is obligatory. If given currency will be not provided it will be converted from dollars.
description	customized product description, if not provided will be implemented description from product.
payload	custom payload, if provided will override payload provided from widget.
transactionIdToMigrate	ID of transaction to be upgraded or downgraded. Prorate will be calculated based on remaining time from subscription and value. First charge of the new subscription will be delayed based on prorate value. Migrated transaction has to be an active subscription.

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:

Code	Description
200	OK
401	Unauthorized
403	Wrong request
404	Product not found

Charge vaulted customer

curl --location --request POST 'https://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://api.transaction.cloud/v1/charge-vaulted/transaction_id

URL	Parameters
transaction_id	transaction id

Request data

Parameter	Description
prices	net value to charge. USD is obligatory, if some currency will not be provided price will be converted from USD.
chargeDescription	charge description. Software or service description. Will be visible on invoice.

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:

Code	Description
200	OK
401	Unauthorized
403	Wrong request
404	Product not found
405	Transaction not active

Response data

Parameter	Description
status	status of charge. SUCCESS or FAILED
deactivation	flag is given customer vaulted is deactivated after this charge.
netValue	new charge value
price	gross value
taxValue	tax value
currency	charge currency

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

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.

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

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

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

<span data-ts-price 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>

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

<button
   data-ts-first-name="Test"
   data-ts-last-name="Test"
   data-ts-email="test@test.com"
   data-ts-non-editable-email="true"
   data-ts-zip-code="18951"
   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)

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 start payment of given product, use code below:

tc.buy("TC-EXAMPLE-PRODUCT-ID", {
    firstName: 'Test',
    lastName: 'Test',
    zipCode: '18951',
    email: 'test@test.com',
}).then(
    () => {
        console.log('payment started');
    },
    (error) => console.error(error)
);

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

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.

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

Name	Type	Description
webhookId	string	Unique id of the webhook. If the webhook is retried the same unique id is used again.
webhookType	string	Type of webhook received. Examples: “SUBSCRIPTION_ACTIVATED”, “SUBSCRIPTION_ACTIVATED_TRIAL”, “SUBSCRIPTION_CANCELLED”, “ONETIME_PAID”, “ONETIME_REFUNDED”, “VAULTED_SUBSCRIPTION_ACTIVATED”, “VAULTED_SUBSCRIPTION_DEACTIVATED”, “CHARGE”, “REFUND”
transactionId	string	Id of the order
transactionType	string	Type of order. Examples: "ONETIME", "SUBSCRIPTION", “VAULTED”
createDate	string	Date and time in UTC when the order was created
nextCharge	string	Date and time in UTC when the customer will be recharged
lastCharge	string	Date and time in UTC when the customer was last charged
chargeFrequency	string	Frequency of charging the customer for the order. For “ONETIME” and “VAULTED” orders the value is always “UNKNOWN”. Examples: “DAILY”, “WEEKLY”, “MONTHLY”, “YEARLY”, “UNKNOWN”
productId	string	Id of the product
productName	string	Name of the product
payload	string	Custom payload passed by you during the initiation of the buying process is returned here. We recommend encrypting the payload.
transactionStatus	string	Status of the order. Examples: "TRANSACTION_STATUS_PENDING”, "SUBSCRIPTION_STATUS_ACTIVE", "VAULTED_STATUS_ACTIVE", "VAULTED_STATUS_INACTIVE", "SUBSCRIPTION_STATUS_ACTIVE_TRIAL", "ONE_TIME_PAYMENT_STATUS_PAID", "SUBSCRIPTION_STATUS_CANCELLED", "TRANSACTION_STATUS_REFUNDED”, "SUBSCRIPTION_STATUS_CANCELLED_PENDING"
firstName	string	First name of the customer
lastName	string	Last name of the customer
organization	string	Customer’s organization name
email	string	Email address used by the customer during the checkout process. This email address will receive all email notifications from Transaction Cloud regarding the order.
assignedEmail	string	Email address used by the customer to sign-up on your website.
country	string	2 character ISO code of the country of customer
eventId	string	This is the unique Id of the charge or refund event. Each order can have multiple eventId related to charges and refunds. This Id can be used to access the invoice or the credit memo using the URL https://api.transaction.cloud/invoice/eventId
currency	string	3 character ISO code of the currency of the order
amountTotal	string	Total amount from the order
taxAmount	string	Amount of tax from the order
income	string	Your income after deduction of taxes and transaction processing fees
taxRate	string	Tax rate charged to the customer
affiliateCommission	string	If the sale was due to an affiliate, then this would display the commission received by the affiliate
affiliateCommissionCurrency	string	3 character ISO code of the currency of the order

Webhook orders examples (on the right side):

Subscription Purchase:

{
  "webhookId": "NhczrAwugRAiS4K",
  "webhookType": "SUBSCRIPTION_ACTIVATED",
  "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",
  "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",
  "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:

{
  "webhookType": "ONETIME_PAID",
  "webhookId": "x20rq2SDMMzdZ1O",
  "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"
}

Balance Affecting Events:

{
  "webhookId": "pmH4KtToca8QjzC",
  "webhookType": "CHARGE",
  "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",
  "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",
  "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",
  "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"
}

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:

Card Type	Card Number	Expiry Date	CVV Code	Country / Currency
Visa	4263982640269299	02/23	837
JCB	3566000020000410	02/23	123	JP/JPY
Mastercard	5425233430109903	04/23	123
Amex	374245455400126	05/23	1234
China Union Pay	6250941006528599	06/23	123	CN/USD

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:

Card Type	Card Number	Expiry Date	CVV Code
Visa	4111111111111111	MM/YY in the Future	123
JCB	3530111333300000	MM/YY in the Future	123

Apple Pay

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