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 |
---|---|---|
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 |
---|---|
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:
- 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.