NAV
shell

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

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

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.

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.