Introduction

Transaction Cloud’s Singularity-Integration™ Architecture

Transaction Cloud uses its innovative Singularity-Integration™ architecture which combines One-Directional-API™, and One-Data-Cloud™. This means Transaction Cloud's API only responds to requests, but it doesn’t send any webhooks. This saves valuable resources as there is no cumbersome setup which is typical of webhooks based integration. It also avoids inadvertent mismatch of data due to missed or duplicate webhooks. Moreover, all data is stored on the One-Data-Cloud™ which eliminates the need of storing redundant data on the vendor's database. If needed, the vendor still has the ability and flexibility to store data on its database. The One- Directional-API™ also creates ready-to-embed management tools that allow secure access to features such as refunds, cancellations & data such as purchases, invoices, credit notes etc. through the vendor's access-controlled interface.

As a result, the time and resources required for integration are reduced by 50%. Additionally, the points of failure and maintenance cost over the long run are significantly reduced resulting in a reliable, resilient, and efficient system.

Panel: https://app.transaction.cloud

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

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

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

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

Query Parameters

Parameter	Default	Description
email	true	Set customer email.

Retrieve URL of hosted admin app.

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

This endpoint generates url to hosted admin panel.

HTTP Request

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

Retrieve transactions by email

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": "United States",
        "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"
    },
    {
        "assignedEmail": "",
        "chargeFrequency": "WEEKLY",
        "country": "United States",
        "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"
    },
    {
        "assignedEmail": "",
        "chargeFrequency": "MONTHLY",
        "country": "United States",
        "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"
     },
     {
        "assignedEmail": "",
        "chargeFrequency": "YEARLY",
        "country": "United States",
        "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"
    }
]

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

HTTP Request

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

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.

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": "United States",
      "createDate": "2021-09-20",
      "email": "customer@domain.com",
      "id": "TC-TR_xxyyxxx",
      "lastCharge": "2021-09-20",
      "productId": "TC-PR_qqqzzzyy",
      "productName": "Product name",
      "transactionStatus": "ONE_TIME_PAYMENT_STATUS_PAID",
      "transactionType": "ONETIME"
}

This endpoint retrives transaction details by transaction id.

HTTP Request

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

URL Parameters

Parameter	Description
id	The id of transaction id.

Assign email address by 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": "United States",
    "createDate": "2021-09-14",
    "email": "customer@domain.com",
    "id": "TC-TR_zxzqqqq",
    "lastCharge": "2021-09-14",
    "productId": "TC-PR_xxxqqzz",
    "productName": "Product name",
    "transactionStatus": "TRANSACTION_STATUS_REFUNDED",
    "transactionType": "ONETIME"
}

This endpoint changes customer assigned email for transaction by id.

HTTP Request

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

URL Parameters

Parameter	Description
id	The id of transaction id.

Data parameters

Parameter	Description
assignEmail	Assign email address for a customer.

Cancel subscription

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

This endpoint cancel subscription by subscription id.

The above command returns HTTP status code:

200 OK

HTTP Request

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

URL Parameters

Parameter	Description
id	The id of subscription id.

Refund transaction

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

This endpoint refund transaction by transaction id.

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": "United States"
    }
]

HTTP Request

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

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.

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

The above command returns JSON structured like this:

[
    {
            "assignedEmail": "",
            "changedStatus": "CHANGED_STATUS_CANCELLED",
            "chargeFrequency": "MONTHLY",
            "country": "United States",
            "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": "United States",
            "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": "test@test.pl",
            "changedStatus": "CHANGED_STATUS_NEW",
            "chargeFrequency": "UNKNOWN",
            "country": "United States",
            "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 Request

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

Marking transactions as processed

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

Transaction can be marked as a processed after some action.

The above command returns HTTP status code:

200 OK

HTTP Request

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

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.

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.