Transaction Cloud - API Reference - Documentation v1

API Reference

Create Account

API Authentication

The TransactionCloud API uses API login and API password to authenticate all requests with the Authorization HTTP header.

You can find these details in the API Set up page in your Vendor Panel.

Keep your API credentials secure and don't expose it publicly.

Header format:

You have to attach the header below to all API calls.

Authorization: API_LOGIN:API_PASSWORD

You must replace API_LOGIN:API_PASSWORD with your personal API credentials.
Please remember that sandbox and production environment have separate credentials.

API Error Codes

Our API return HTTP responses with error codes in case of invalid request, missing data, failed authorization and in other unexpected cases. In some cases, JSON body with an error explanation will be available.

List of error codes

Code	Status
400	Invalid input data error string Error name. Example: "Price in USD is required" message string Issue description with potential fix. Example: "Please add missing USD price value"
401	Authorization issue
404	Resource not found
500	Fatal system error
503	System temporary unavailable

API Endpoints

API URL

https://api.transaction.cloud/

Sandbox API URL

https://sandbox-api.transaction.cloud/

In all examples below, the Sandbox API is used by default.

Get URL to manage transactions

Generates all transactions for customer by email.

GET https://sandbox-api.transaction.cloud/v1/generate-url-to-manage-transactions/{customerEmail}

Query Parameters

Schema

email string<email> required

Email address used by the customer during purchase.

Example: "test@domain.com"

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request GET https://sandbox-api.transaction.cloud/v1/generate-url-to-manage-transactions/{customerEmail} \
--header 'Authorization: API_LOGIN:API_PASSWORD'

Response (Object)

Schema

url string

Address URL.

Example

                                
                                    Example response (Object)
                                    
                                
                                {
    "url": "https://hosted.transaction.cloud/manage/token"
}

Get URL to Admin Plug-in tool

Generates a temporary URL address to embed the Plug-in tool on your website using an iframe.

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

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request GET https://sandbox-api.transaction.cloud/v1/generate-url-to-admin \
--header 'Authorization: API_LOGIN:API_PASSWORD'

Response (Object)

Schema

url string

Address URL.

Example

                                
                                    Example response (Object)
                                    
                                
                                {
    "url": "https://hosted.transaction.cloud/admin/token"
}

Get transactions by email

Retrieves all transactions by email.

GET https://sandbox-api.transaction.cloud/v1/transactions/{email}

Query Parameters

Schema

email string<email> required

Email address used by the customer during purchase.

Example: "test@domain.com"

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request GET https://sandbox-api.transaction.cloud/v1/transactions/test@domain.com \
--header 'Authorization: API_LOGIN:API_PASSWORD'

Response (Array)

Schema

id string

Unique identification for the transaction.

Example: "TC-TR_xxyyxxx"

createDate string<datetime>

Transaction create date.

Format: YYYY-MM-DDTHH:MM:SS.sZ

email string<email>

Email address used by the customer during purchase.

assignedEmail string<email> | null

Email address used by the customer during website sign-up. It will be null until you set it with the "Assign email" endpoint.

productId string

Unique product identificator.

Example: "TC-PR_yyyyxxxx"

productName string

Name of the product.

transactionType string<transactionType>

Type of product. Possible values:

Value	Description
ONETIME	One-time product transaction.
SUBSCRIPTION	Recurring product transaction.
VAULTED	Vaulted product transaction.

transactionStatus string<transactionStatus>

Current status of the transaction. Possible values:

Value	Description
TRANSACTION_STATUS_PENDING	Pending payment.
TRANSACTION_STATUS_REFUNDED	Refunded one-time payment product.
ONE_TIME_PAYMENT_STATUS_PAID	Paid one-time product.
SUBSCRIPTION_STATUS_ACTIVE	Active subscription.
SUBSCRIPTION_STATUS_ACTIVE_TRIAL	Active subscription in trial period.
SUBSCRIPTION_STATUS_CANCELLED_PENDING	Subscription cancellation in progress.
SUBSCRIPTION_STATUS_CANCELLED	Cancelled subscription.
VAULTED_STATUS_ACTIVE	Active vaulted product.
VAULTED_STATUS_INACTIVE	Inactive vaulted product.

chargeFrequency string<chargeFrequency> | null

Frequency of charges for recurring products. Possible values:

Value	Description
UNKNOWN	Unset charge frequency.
DAILY	Once per day.
WEEKLY	Once per week.
MONTHLY	Once per month.
HALF_YEARLY	Twice per year.
YEARLY	Once per year.

country string<countryCode>

Country where customer completed the payment.

Example: "US"

lastCharge string<datetime>

Date of the last successful payment.

Format: YYYY-MM-DDTHH:MM:SS.sZ

nextCharge string<datetime>

Date of the next payment.

Format: YYYY-MM-DDTHH:MM:SS.sZ

payload string | null

Encrypted custom data passed before the checkout process. It's highly recommended to encrypt this data on your end.

Requirements: <5000 characters

whoCanceled string<whoCanceled> | null

Reason for cancellation in case of a canceled subscription or vaulted transaction. Possible values:

Value	Description
TRANSACTION_CLOUD_ADMIN	TransactionCloud.
VENDOR	Vendor.
CUSTOMER	Customer cancellation.
NEXT_CHARGE_FAILED	Failed next charge.

netPrice number

Net price.

netPrice string

Net price.

netPriceInUSD number

Net price in USD.

netPriceInUSDS string

Net price in USD.

tax number

Tax amount.

taxS string

Tax amount.

currency string<currency>

Currency code of the transaction.

Example: "USD"

Example

                                
                                    Example response (Array)
                                    
                                
                                [
    {
        "assignedEmail": "",
        "chargeFrequency": "UNKNOWN",
        "country": "US",
        "createDate": "2023-07-20T10:31:30.686Z",
        "email": "customer@domain.com",
        "id": "TC-TR_xxyyxxx",
        "lastCharge": "2023-07-20T10:31:30.686Z",
        "payload": "",
        "productId": "TC-PR_qqqzzzyy",
        "productName": "Name of the product.",
        "transactionStatus": "ONE_TIME_PAYMENT_STATUS_PAID",
        "transactionType": "ONETIME",
        "netPrice": 16.25,
        "tax": 2.4,
        "currency": "USD",
        "netPriceInUSD": 4.09,
        "netPriceInUSDS": "16.25",
        "netPriceS": "4.09",
        "taxS": "2.4",
        "whoCanceled": null
    },
    {
        "assignedEmail": "",
        "chargeFrequency": "WEEKLY",
        "country": "US",
        "createDate": "2023-07-20T10:31:30.686Z",
        "email": "customer@domain.com",
        "id": "TC-TR_yyyxxyy",
        "lastCharge": "2023-07-20T10:31:30.686Z",
        "nextCharge": "2023-08-20T10:31:30.686Z",
        "payload": "",
        "productId": "TC-PR_zzzyyxx",
        "productName": "Name of the product.",
        "transactionStatus": "SUBSCRIPTION_STATUS_ACTIVE",
        "transactionType": "SUBSCRIPTION",
        "netPrice": 20,
        "tax": 2.4,
        "currency": "USD",
        "netPriceInUSD": 20,
        "netPriceInUSDS": "20.0",
        "netPriceS": "20.0",
        "taxS": "2.4",
        "whoCanceled": null
    },
    {
        "assignedEmail": "",
        "chargeFrequency": "MONTHLY",
        "country": "US",
        "createDate": "2023-03-20T11:32:23.732Z",
        "email": "customer@domain.com",
        "id": "TC-TR_nm7p44R",
        "lastCharge": "2023-03-20T11:32:23.732Z",
        "nextCharge": "2023-04-20T11:32:23.732Z",
        "payload": "",
        "productId": "TC-PR_x1GDr9m",
        "productName": "Name of the product.",
        "transactionStatus": "SUBSCRIPTION_STATUS_ACTIVE",
        "transactionType": "SUBSCRIPTION",
        "netPrice": 20,
        "tax": 2.4,
        "currency": "USD",
        "netPriceInUSD": 20,
        "netPriceInUSDS": "20.0",
        "netPriceS": "20.0",
        "taxS": "2.4",
        "whoCanceled": null
    },
    {
        "assignedEmail": "",
        "chargeFrequency": "MONTHLY",
        "country": "US",
        "createDate": "2023-07-20T10:31:30.686Z",
        "email": "customer@domain.com",
        "id": "TC-TR_yyyxxyy",
        "lastCharge": "2023-07-20T10:31:30.686Z",
        "nextCharge": "2023-08-20T10:31:30.686Z",
        "payload": "",
        "productId": "TC-PR_zzzyyxx",
        "productName": "Name of the product.",
        "transactionStatus": "SUBSCRIPTION_STATUS_ACTIVE",
        "transactionType": "SUBSCRIPTION",
        "netPrice": 20,
        "tax": 2.4,
        "currency": "USD",
        "netPriceInUSD": 20,
        "netPriceInUSDS": "20.0",
        "netPriceS": "20.0",
        "taxS": "2.4",
        "whoCanceled": "CUSTOMER"
    }
]

Get transaction by ID

Retrieves transaction by ID.

GET https://sandbox-api.transaction.cloud/v1/transaction/{transaction-id}

Query Parameters

Schema

transaction-id string required

Unique identification for the transaction.

Example: "TC-TR_xxyyxxx"

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request GET https://sandbox-api.transaction.cloud/v1/transaction/TC-TR_xxyyxxx \
--header 'Authorization: API_LOGIN:API_PASSWORD'

Response (Object)

Schema

id string

Unique identification for the transaction.

Example: "TC-TR_xxyyxxx"

createDate string<datetime>

Date of transaction creation.

Format: YYYY-MM-DDTHH:MM:SS.sZ

email string<email>

Email address used by the customer during purchase.

assignedEmail string<email> | null

Email address used by the customer during website sign-up. It will be null until you set it with the "Assign email" endpoint.

productId string

Unique product identificator.

Example: "TC-PR_yyyyxxxx"

productName string

Name of the product.

transactionType string<transactionType>

Type of product. Possible values:

Value	Description
ONETIME	One-time product transaction.
SUBSCRIPTION	Recurring product transaction.
VAULTED	Vaulted product transaction.

transactionStatus string<transactionStatus>

Current status of the transaction. Possible values:

Value	Description
TRANSACTION_STATUS_PENDING	Pending payment.
TRANSACTION_STATUS_REFUNDED	Refunded one-time payment product.
ONE_TIME_PAYMENT_STATUS_PAID	Paid one-time product.
SUBSCRIPTION_STATUS_ACTIVE	Active subscription.
SUBSCRIPTION_STATUS_ACTIVE_TRIAL	Active subscription in trial period.
SUBSCRIPTION_STATUS_CANCELLED_PENDING	Subscription cancellation in progress.
SUBSCRIPTION_STATUS_CANCELLED	Cancelled subscription.
VAULTED_STATUS_ACTIVE	Active vaulted product.
VAULTED_STATUS_INACTIVE	Inactive vaulted product.

chargeFrequency string<chargeFrequency> | null

Frequency of charges for recurring products. Possible values:

Value	Description
UNKNOWN	Unset charge frequency.
DAILY	Once per day.
WEEKLY	Once per week.
MONTHLY	Once per month.
HALF_YEARLY	Twice per year.
YEARLY	Once per year.

country string<countryCode>

Country where customer completed the payment.

Example: "US"

lastCharge string<datetime>

Date of the last successful payment.

Format: YYYY-MM-DDTHH:MM:SS.sZ

payload string | null

Encrypted custom data passed before the checkout process. It's highly recommended to encrypt this data on your end.

Requirements: <5000 characters

whoCanceled string<whoCanceled> | null

Reason for cancellation in case of a canceled subscription or vaulted transaction. Possible values:

Value	Description
TRANSACTION_CLOUD_ADMIN	TransactionCloud.
VENDOR	Vendor.
CUSTOMER	Customer cancellation.
NEXT_CHARGE_FAILED	Failed next charge.

netPrice number

Net price.

netPrice string

Net price.

netPriceInUSD number

Net price in USD.

netPriceInUSDS string

Net price in USD.

tax number

Tax amount.

taxS string

Tax amount.

currency string<currency>

Currency code of the transaction.

Example: "USD"

entries Array<TransactionEntry>

Transaction entries.

TransactionEntry

id string

Unique identification for the transaction entry.

Example: "TC-BA_xxyyxxx"

type string<transactionEntryType>

Transaction entry type. Possible values:

Value	Description
SUBSCRIPTION_PAYMENT	Subscription charge.
VAULTED_PAYMENT	Vaulted charge.
ONETIME_PAYMENT	One-time payment.
SUBSCRIPTION_REFUND	Subscription charge refund.
ONETIME_PAYMENT_REFUND	One-time payment refund.
CHARGEBACK	Payment chargeback.

createDate string<datetime>

Date of entry creation.

Format: YYYY-MM-DDTHH:MM:SS.sZ

taxAmount string

Total tax amount.

income string

Total income amount.

incomeCurrency string<currency>

Income currency.

Example: "USD"

taxRate string

Tax rate for the transaction.

currency string<currency>

Currency code of the transaction.

Example: "USD"

amountTotal string

Total event amount.

affiliateIncome string

Total affiliate income.

affiliateIncomeCurrency string<currency>

Affiliate income currency.

Example: "USD"

Example

                                
                                    Example response (Object)
                                    
                                
                                {
    "assignedEmail": "",
    "chargeFrequency": "YEARLY",
    "country": "US",
    "createDate": "2023-07-20T10:31:30.686Z",
    "email": "customer@domain.com",
    "id": "TC-TR_yxyyyxx",
    "lastCharge": "2023-07-20T10:31:30.686Z",
    "nextCharge": "2023-08-20T10:31:30.686Z",
    "payload": "",
    "productId": "TC-PR_yyyzzxxx",
    "productName": "Name of the product.",
    "transactionStatus": "SUBSCRIPTION_STATUS_CANCELLED",
    "transactionType": "SUBSCRIPTION",
    "netPrice": 20,
    "tax": 2.4,
    "currency": "USD",
    "netPriceInUSD": 20,
    "netPriceInUSDS": "20.0",
    "netPriceS": "20.0",
    "taxS": "2.4",
    "whoCanceled": "CUSTOMER",
    "entries": [
        {
            "affiliateIncome": "0.00",
            "affiliateIncomeCurrency": "USD",
            "amountTotal": "19.98",
            "country": "PL",
            "createDate": "2023-07-20T10:31:31.000Z",
            "currency": "PLN",
            "id": "TC-BA_XXYYZZZ",
            "income": "3.02",
            "incomeCurrency": "USD",
            "taxAmount": "3.74",
            "taxRate": 0.23,
            "type": "SUBSCRIPTION_PAYMENT"
        }
    ]
}

Update transaction email

Customer's updated email address is stored in the transaction's 'assignEmail' field. The original email address provided by the customer in the payment form remains in the 'email' field and is not editable. After using this endpoint, the 'assignEmail' field will have a higher priority over the 'email' field throughout the system. This endpoint helps you maintain a seamless connection between transactions and customer profiles in your system.

POST https://sandbox-api.transaction.cloud/v1/transaction/{transaction-id}

Query Parameters

Schema

transaction-id string required

Unique identification for the transaction.

Example: "TC-TR_xxyyxxx"

Request Body application/json

Schema

assignEmail string<email> required

Assign an email address for a customer.

Example: "assignedEmail@domain.com"

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request POST https://sandbox-api.transaction.cloud/v1/transaction/TC-TR_xxyyxxx \
--header 'Authorization: API_LOGIN:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data '{"assignEmail":"assignedEmail@domain.com"}'

Response (Object)

Schema

assignEmail string<email>

Assign an email address for a customer.

Example: "assignedEmail@domain.com"

chargeFrequency string<chargeFrequency> | null

Frequency of charges for recurring products. Possible values:

Value	Description
UNKNOWN	Unset charge frequency.
DAILY	Once per day.
WEEKLY	Once per week.
MONTHLY	Once per month.
HALF_YEARLY	Twice per year.
YEARLY	Once per year.

country string<countryCode>

Country where customer completed the payment.

Example: "US"

createDate string<datetime>

Transaction create date.

Format: YYYY-MM-DDTHH:MM:SS.sZ

email string<email>

Email address used by the customer during purchase.

id string

Unique identification for the transaction.

Example: "TC-TR_xxyyxxx"

lastCharge string<datetime>

Date of the last successful payment.

Format: YYYY-MM-DDTHH:MM:SS.sZ

payload string | null

Encrypted custom data passed before the checkout process. It's highly recommended to encrypt this data on your end.

Requirements: <5000 characters

productId string

Unique product identificator.

Example: "TC-PR_yyyyxxxx"

productName string

Name of the product.

transactionStatus string<transactionStatus>

Current status of the transaction. Possible values:

Value	Description
TRANSACTION_STATUS_PENDING	Pending payment.
TRANSACTION_STATUS_REFUNDED	Refunded one-time payment product.
ONE_TIME_PAYMENT_STATUS_PAID	Paid one-time product.
SUBSCRIPTION_STATUS_ACTIVE	Active subscription.
SUBSCRIPTION_STATUS_ACTIVE_TRIAL	Active subscription in trial period.
SUBSCRIPTION_STATUS_CANCELLED_PENDING	Subscription cancellation in progress.
SUBSCRIPTION_STATUS_CANCELLED	Cancelled subscription.
VAULTED_STATUS_ACTIVE	Active vaulted product.
VAULTED_STATUS_INACTIVE	Inactive vaulted product.

transactionType string<transactionType>

Type of product. Possible values:

Value	Description
ONETIME	One-time product transaction.
SUBSCRIPTION	Recurring product transaction.
VAULTED	Vaulted product transaction.

netPrice number

Net price.

netPrice string

Net price.

netPriceInUSD number

Net price in USD.

netPriceInUSDS string

Net price in USD.

tax number

Tax amount.

taxS string

Tax amount.

whoCanceled string<whoCanceled> | null

Reason for cancellation in case of a canceled subscription or vaulted transaction. Possible values:

Value	Description
TRANSACTION_CLOUD_ADMIN	TransactionCloud.
VENDOR	Vendor.
CUSTOMER	Customer cancellation.
NEXT_CHARGE_FAILED	Failed next charge.

Example

                                
                                    Example response (Object)
                                    
                                
                                {
    "assignEmail": "assignedEmail@domain.com",
    "chargeFrequency": "UNKNOWN",
    "country": "US",
    "createDate": "2023-07-20T10:31:30.686Z",
    "email": "customer@domain.com",
    "id": "TC-TR_zxzqqqq",
    "lastCharge": "2023-07-20T10:31:30.686Z",
    "payload": "",
    "productId": "TC-PR_xxxqqzz",
    "productName": "Name of the product.",
    "transactionStatus": "TRANSACTION_STATUS_REFUNDED",
    "transactionType": "ONETIME",
    "netPrice": 20,
    "netPriceInUSD": 20,
    "netPriceInUSDS": "20.0",
    "netPriceS": "20.0",
    "tax": 4,
    "taxS": "4.0",
    "whoCanceled": null
}

Update transaction payload

Update payload saved in transaction.

POST https://sandbox-api.transaction.cloud/v1/transaction/{transaction-id}

Query Parameters

Schema

transaction-id string required

Unique identification for the transaction.

Example: "TC-TR_xxyyxxx"

Request Body application/json

Schema

payload string | null required

Encrypted custom data passed before the checkout process. It's highly recommended to encrypt this data on your end.

Example: "example custom data string" Requirements: <5000 characters

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request POST https://sandbox-api.transaction.cloud/v1/transaction/TC-TR_xxyyxxx \
--header 'Authorization: API_LOGIN:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data '{"payload":"example custom data string"}'

Response (Object)

Schema

assignEmail string<email>

Assign an email address for a customer.

Example: "assignedEmail@domain.com"

chargeFrequency string<chargeFrequency> | null

Frequency of charges for recurring products. Possible values:

Value	Description
UNKNOWN	Unset charge frequency.
DAILY	Once per day.
WEEKLY	Once per week.
MONTHLY	Once per month.
HALF_YEARLY	Twice per year.
YEARLY	Once per year.

country string<countryCode>

Country where customer completed the payment.

Example: "US"

createDate string<datetime>

Transaction create date.

Format: YYYY-MM-DDTHH:MM:SS.sZ

email string<email>

Email address used by the customer during purchase.

id string

Unique identification for the transaction.

Example: "TC-TR_xxyyxxx"

lastCharge string<datetime>

Date of the last successful payment.

Format: YYYY-MM-DDTHH:MM:SS.sZ

payload string | null

Encrypted custom data passed before the checkout process. It's highly recommended to encrypt this data on your end.

Requirements: <5000 characters

productId string

Unique product identificator.

Example: "TC-PR_yyyyxxxx"

productName string

Name of the product.

transactionStatus string<transactionStatus>

Current status of the transaction. Possible values:

Value	Description
TRANSACTION_STATUS_PENDING	Pending payment.
TRANSACTION_STATUS_REFUNDED	Refunded one-time payment product.
ONE_TIME_PAYMENT_STATUS_PAID	Paid one-time product.
SUBSCRIPTION_STATUS_ACTIVE	Active subscription.
SUBSCRIPTION_STATUS_ACTIVE_TRIAL	Active subscription in trial period.
SUBSCRIPTION_STATUS_CANCELLED_PENDING	Subscription cancellation in progress.
SUBSCRIPTION_STATUS_CANCELLED	Cancelled subscription.
VAULTED_STATUS_ACTIVE	Active vaulted product.
VAULTED_STATUS_INACTIVE	Inactive vaulted product.

transactionType string<transactionType>

Type of product. Possible values:

Value	Description
ONETIME	One-time product transaction.
SUBSCRIPTION	Recurring product transaction.
VAULTED	Vaulted product transaction.

netPrice number

Net price.

netPrice string

Net price.

netPriceInUSD number

Net price in USD.

netPriceInUSDS string

Net price in USD.

tax number

Tax amount.

taxS string

Tax amount.

whoCanceled string<whoCanceled> | null

Reason for cancellation in case of a canceled subscription or vaulted transaction. Possible values:

Value	Description
TRANSACTION_CLOUD_ADMIN	TransactionCloud.
VENDOR	Vendor.
CUSTOMER	Customer cancellation.
NEXT_CHARGE_FAILED	Failed next charge.

Example

                                
                                    Example response (Object)
                                    
                                
                                {
    "assignEmail": "assignedEmail@domain.com",
    "chargeFrequency": "UNKNOWN",
    "country": "US",
    "createDate": "2023-07-20T10:31:30.686Z",
    "email": "customer@domain.com",
    "id": "TC-TR_zxzqqqq",
    "lastCharge": "2023-07-20T10:31:30.686Z",
    "payload": "new payload data",
    "productId": "TC-PR_xxxqqzz",
    "productName": "Name of the product.",
    "transactionStatus": "TRANSACTION_STATUS_REFUNDED",
    "transactionType": "ONETIME",
    "netPrice": 20,
    "netPriceInUSD": 20,
    "netPriceInUSDS": "20.0",
    "netPriceS": "20.0",
    "tax": 4,
    "taxS": "4.0",
    "whoCanceled": null
}

Cancel subscription

Cancel subscription by transaction id.

POST https://sandbox-api.transaction.cloud/v1/cancel-subscription/{transaction-id}

Query Parameters

Schema

transaction-id string required

Unique identification for the transaction.

Example: "TC-TR_xxyyxxx"

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request POST https://sandbox-api.transaction.cloud/v1/cancel-subscription/TC-TR_xxyyxxx \
--header 'Authorization: API_LOGIN:API_PASSWORD'

Refund payment

Refund payment by transaction-id.

POST https://sandbox-api.transaction.cloud/v1/refund-transaction/{transaction-id}

Query Parameters

Schema

transaction-id string required

Unique identification for the transaction.

Example: "TC-TR_xxyyxxx"

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request POST https://sandbox-api.transaction.cloud/v1/refund-transaction/TC-TR_xxyyxxx \
--header 'Authorization: API_LOGIN:API_PASSWORD'

Get transactions with changed status

Retrieve transactions with recently changed status for processing. After processing each of them, you can mark them as processed with this request. When you execute the ‘Get transactions with changed status’ request again, only unprocessed transactions will be retrieved.

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

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request GET https://sandbox-api.transaction.cloud/v1/changed-transactions \
--header 'Authorization: API_LOGIN:API_PASSWORD'

Response (Array)

Schema

assignEmail string<email>

Assign an email address for a customer.

Example: "assignedEmail@domain.com"

changeStatus string<status> | null

Changed status possible values:

Value	Description
CHANGED_STATUS_NEW	New transaction.
CHANGED_STATUS_RENEWED	Transaction renewed.
CHANGED_STATUS_CANCELLED	Transaction cancelled.
CHANGED_STATUS_REFUNDED	Transaction refunded.
CHANGED_STATUS_TRIAL	Trial
CHANGED_STATUS_VAULTED_ACTIVATION	Activated vaulted.
CHANGED_STATUS_VAULTED_DEACTIVATION	Deactivated vaulted.

chargeFrequency string<chargeFrequency> | null

Frequency of charges for recurring products. Possible values:

Value	Description
UNKNOWN	Unset charge frequency.
DAILY	Once per day.
WEEKLY	Once per week.
MONTHLY	Once per month.
HALF_YEARLY	Twice per year.
YEARLY	Once per year.

country string<countryCode>

Country where customer completed the payment.

Example: "US"

createDate string<datetime>

Transaction create date.

Format: YYYY-MM-DDTHH:MM:SS.sZ

email string<email>

Email address used by the customer during purchase.

id string

Unique identification for the transaction.

Example: "TC-TR_xxyyxxx"

lastCharge string<datetime>

Date of the last successful payment.

Format: YYYY-MM-DDTHH:MM:SS.sZ

nextCharge string<datetime>

Date of the next payment.

Format: YYYY-MM-DDTHH:MM:SS.sZ

payload string | null

Encrypted custom data passed before the checkout process. It's highly recommended to encrypt this data on your end.

Requirements: <5000 characters

productId string

Unique product identificator.

Example: "TC-PR_yyyyxxxx"

productName string

Name of the product.

transactionStatus string<transactionStatus>

Current status of the transaction. Possible values:

Value	Description
TRANSACTION_STATUS_PENDING	Pending payment.
TRANSACTION_STATUS_REFUNDED	Refunded one-time payment product.
ONE_TIME_PAYMENT_STATUS_PAID	Paid one-time product.
SUBSCRIPTION_STATUS_ACTIVE	Active subscription.
SUBSCRIPTION_STATUS_ACTIVE_TRIAL	Active subscription in trial period.
SUBSCRIPTION_STATUS_CANCELLED_PENDING	Subscription cancellation in progress.
SUBSCRIPTION_STATUS_CANCELLED	Cancelled subscription.
VAULTED_STATUS_ACTIVE	Active vaulted product.
VAULTED_STATUS_INACTIVE	Inactive vaulted product.

transactionType string<transactionType>

Type of product. Possible values:

Value	Description
ONETIME	One-time product transaction.
SUBSCRIPTION	Recurring product transaction.
VAULTED	Vaulted product transaction.

whoCanceled string<whoCanceled> | null

Reason for cancellation in case of a canceled subscription or vaulted transaction. Possible values:

Value	Description
TRANSACTION_CLOUD_ADMIN	TransactionCloud.
VENDOR	Vendor.
CUSTOMER	Customer cancellation.
NEXT_CHARGE_FAILED	Failed next charge.

Example

                                
                                    Example response (Array)
                                    
                                
                                [
    {
        "assignedEmail": "",
        "changedStatus": "CHANGED_STATUS_CANCELLED",
        "chargeFrequency": "MONTHLY",
        "country": "US",
        "createDate": "2023-03-20T11:32:23.732Z",
        "email": "customer@domain.com",
        "id": "TC-TR_XXXYYZZ",
        "lastCharge": "2023-07-07T02:22:48.750Z",
        "nextCharge": "2023-08-07T02:22:48.750Z",
        "payload": "",
        "productId": "TC-PR_XXXYYZZ",
        "productName": "Product",
        "transactionStatus": "SUBSCRIPTION_STATUS_CANCELLED",
        "transactionType": "SUBSCRIPTION",
        "whoCanceled": "VENDOR"
    },
    {
        "assignedEmail": "",
        "changedStatus": "CHANGED_STATUS_NEW",
        "chargeFrequency": "WEEKLY",
        "country": "US",
        "createDate": "2023-03-20T11:32:23.732Z",
        "email": "customer@domain.com",
        "id": "TC-TR_YYYZZXX",
        "lastCharge": "2023-07-07T02:22:48.750Z",
        "nextCharge": "2023-08-07T02:22:48.750Z",
        "payload": "",
        "productId": "TC-PR_XXXXXXX",
        "productName": "Another product",
        "transactionStatus": "SUBSCRIPTION_STATUS_ACTIVE",
        "transactionType": "SUBSCRIPTION",
        "whoCanceled": null
    },
    {
        "assignedEmail": "assignedUser@domain.com",
        "changedStatus": "CHANGED_STATUS_NEW",
        "chargeFrequency": "UNKNOWN",
        "country": "US",
        "createDate": "2023-03-20T11:32:23.732Z",
        "email": "customer@domain.com",
        "id": "TC-TR_ZZZZYYX",
        "lastCharge": "2023-07-07T02:22:48.750Z",
        "payload": "",
        "productId": "TC-PR_YYYZZXX",
        "productName": "One time product",
        "transactionStatus": "ONE_TIME_PAYMENT_STATUS_PAID",
        "transactionType": "ONETIME",
        "whoCanceled": null
    }
]

Mark changed transaction as processed

After processing transactions with recently changed status, use this endpoint to mark each of them as processed. When you execute the ‘Get transactions with changed status’ request again, only unprocessed transactions will be retrieved.

POST https://sandbox-api.transaction.cloud/v1/changed-transactions/{transaction-id}

Query Parameters

Schema

transaction-id string required

Unique identification for the transaction.

Example: "TC-TR_xxyyxxx"

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request POST https://sandbox-api.transaction.cloud/v1/changed-transactions/TC-TR_xxyyxxx \
--header 'Authorization: API_LOGIN:API_PASSWORD'

Customize product

Allows to customize products on demand, generate new customized product IDs, and link them to payment. IDs of customized products can be used for payments or inside a widget.

POST https://sandbox-api.transaction.cloud/v1/customize-product/{product-id}

Query Parameters

Schema

product-id string required

Unique product identificator.

Example: "TC-PR_yyyyxxxx"

Request Body application/json

Schema

prices Array<Price> required

List of prices. USD is mandatory! If the provided currency is not available, it will be converted from USD.

Example: "[{"currency":"USD", "value" :500.00}]"

Price

currency string<currency>

Currency code of the transaction.

Example: "USD"

value number

Net price.

Example: "500"

description string

Customized product description. If not provided, the original description of the product will be used.

Example: "description of customized product"

payload string

If provided, the custom payload will override the payload provided from the widget.

Example: "payload example" Requirements: <5000 characters

transactionIdToMigrate string

ID of the transaction to be upgraded or downgraded. Prorate will be calculated based on the remaining time from the subscription and its value. The first charge of the new subscription will be delayed based on the prorate value. The migrated transaction must be an active subscription.

Example: "TC-TR_XXXYYZZ"

expiresIn number

Number of SECONDS after the customized product will expire.

Example: "3600"

userFirstName string

First name of the user for whom the customized product is dedicated.

Example: "Pawel"

userLastName string

Last name of the user for whom the customized product is dedicated.

Example: "Bergmann"

userMail string

Email of the user for whom the customized product is dedicated. Editing in the payment panel won't be possible.

Example: "pawel@gmail.com"

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request POST https://sandbox-api.transaction.cloud/v1/customize-product/TC-PR_yyyyxxxx \
--header 'Authorization: API_LOGIN:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data '{"prices":"[{\"currency\":\"USD\", \"value\" :500.00}]","description":"description of customized product","payload":"payload example","transactionIdToMigrate":"TC-TR_XXXYYZZ","expiresIn":3600,"userFirstName":"Pawel","userLastName":"Bergmann","userMail":"pawel@gmail.com"}'

Response (Object)

Schema

link string

URL address with personalized payment.

customProductId string

ID of the personalized product.

Example

                                
                                    Example response (Object)
                                    
                                
                                {
    "link": "https://hosted.transaction.cloud/payment/product/PC_XXXYYYY",
    "customProductId": "PC_z4wvoA0LjMGVLCBxr2BAr0zuLDNlxz3XDe6eHswLDusAtyO5Z3qrZ5rdraC5e_KLBVhS_X7znubZuKaLlD8pkRoDtEWd4"
}

Charge vaulted customer

Charge vaulted customers based on the given price for SaaS services.

POST https://sandbox-api.transaction.cloud/v1/charge-vaulted/{transaction-id}

Query Parameters

Schema

transaction-id string required

Unique identification for the transaction.

Example: "TC-TR_xxyyxxx"

Request Body application/json

Schema

prices Array<Price> required

List of prices. USD is mandatory! If the provided currency is not available, it will be converted from USD.

Example: "[{"currency":"USD", "value" :500.00}]"

Price

currency string<currency>

Currency code of the transaction.

Example: "USD"

value number

Net price.

Example: "500"

chargeDescription string

Description of the charge. Software or service description. It will be visible on the invoice.

Example: "SaaS description"

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request POST https://sandbox-api.transaction.cloud/v1/charge-vaulted/TC-TR_xxyyxxx \
--header 'Authorization: API_LOGIN:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data '{"prices":"[{\"currency\":\"USD\", \"value\" :500.00}]","chargeDescription":"SaaS description"}'

Response (Object)

Schema

currency string<currency>

Currency code of the transaction.

Example: "USD"

deactivation boolean

Information about the activity of vaulted payments.

price number

Price.

priceS string

Price.

taxValue number

Tax amount.

taxValueS string

Tax amount.

netValue number

Net price.

netValueS string

Net price.

status string

Payment status for vaulted transactions.

Example: "SUCCESS"

Value	Description
SUCCESS	transaction succeeded.
FAILED	Transaction failed.

Example

                                
                                    Example response (Object)
                                    
                                
                                {
    "currency": "EUR",
    "deactivation": false,
    "netValue": 525,
    "price": 624,
    "status": "SUCCESS",
    "taxValue": 99,
    "netValueS": "525",
    "priceS": "624",
    "taxValueS": "99"
}

Check licence

Check if your licence have been granted.

GET https://sandbox-api.transaction.cloud/v1/check-licence/{productId}/{licence}

Query Parameters

Schema

productId string required

Unique product identificator.

Example: "TC-PR_yyyyxxxx"

licence string required

Licence provided by client

Example: "LICE-ENCE-HERE"

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request GET https://sandbox-api.transaction.cloud/v1/check-licence/TC-PR_yyyyxxxx/LICE-ENCE-HERE \
--header 'Authorization: API_LOGIN:API_PASSWORD'

Response (Object)

Schema

checkLicenceStatus string

Status of provided licence

Value	Description
LICENCE_STATUS_NEW	The license is new and has not been received by any customers yet.
LICENCE_STATUS_USED	The license has been provided to one customer.
LICENCE_DOES_NOT_EXIST	This licence does not exist
LICENCE_STATUS_CHARGED_BACK	The transaction with this license was refunded or charged back.

Example

                                
                                    Example response (Object)
                                    
                                
                                {
    "licenceStatus": "LICENCE_STATUS_NEW"
}