NAV
shell

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

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

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:

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.