{ "info": { "description": "Required HTTP headers\nAll requests to the API must contain the following HTTP headers:\n\nAuthorization\n\nHTTP basic authorization\nYou can obtain your username and password in Control center on a\n\"Setup Control Center API\" page\nExample: `Authorization: Basic OTgwNDAwMDAwMDAwMDEwMC10ZXN0OnB3ZDEyMw==`\n\nAccept\n\nContent negotiation - requested content type(s) and API version\nCurrently only JSON (`application/json`) format is supported\nAPI version must be declared as a media type parameter, specifying all\nthree MAJOR.MINOR.PATCH version numbers (`version=2.0.0`)\nExample: `Accept: application/json; version=2.0.0`\n\nGeneral considerations\n\nAuthorization errors return 401 HTTP status\nObjects that do not exists return 404 HTTP status\nContent negotitation errors, including omitted requested API version in content negotiation header\nreturn 406 HTTP status\nMissing parameters or application errors (e.g. \"Sale already cancelled\") return HTTP status 412 - Precondition failed\n\nAPI Rate Limits\nEach customer is limited to 500 API requests per hour. This limit is shared\nacross all API users that were created on API setup page in the Control Center account.\n\nEach response contains rate limit information in the HTTP response headers:\n\nX-RateLimit-Limit - The maximum number of requests that the consumer is permitted to make per hour.\nX-RateLimit-Remaining - The number of requests remaining in the current period.\nX-RateLimit-Reset - The time at which the current rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time).\n\nSuccess response headers example:\n\n`HTTP 200 OK\nContent-Type: application/json; charset=utf-8\nX-RateLimit-Limit: 500\nX-RateLimit-Remaining: 437\nX-RateLimit-Reset: 1472814000\n\n...\n`\nError response when rate limit exceeded:\n\n`HTTP 429 Too Many Requests\nContent-Type: application/json; charset=utf-8\nRetry-After: 951\nX-RateLimit-Limit: 500\nX-RateLimit-Remaining: 0\nX-RateLimit-Reset: 1472814000\n\n{\n \"error\" : {\n \"documentation\" : \"https://controlcenter.verotel.com/api-doc/index.html\",\n \"status\" : 429,\n \"title\" : \"Rate limit exceeded\"\n }\n}\n`", "title": "Verotel Control Center API Documentation", "version": "2.0.0" }, "openapi": "3.1.0", "paths": { "/dashboard/announcements": { "get": { "description": "This endpoint provides currently valid announcements, otherwise shown in Control Center.", "operationId": "GetDashboardAnnouncements", "parameters": [ { "description": "HTTP basic authorization. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } }, { "description": "Requested content type and version of recource. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Accept", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "fingerprint": { "description": "hash of the announcement content, can be used to differentiate between announcements", "type": "string" }, "html_content": { "description": "body of the announcement in HTML format", "type": "string" } }, "required": [ "html_content", "fingerprint" ], "type": "object", "x-order": [ "html_content", "fingerprint" ] } } }, "description": "Success 200" }, "401": { "description": "Unauthorized access" }, "406": { "description": "Missing version" } }, "summary": "Get currently valid announcements", "tags": [ "Dashboard" ] } }, "/dashboard/drill-down": { "get": { "operationId": "GetDashboardDrillDown", "parameters": [ { "description": "HTTP basic authorization. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } }, { "description": "Requested content type and version of recource. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Accept", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "result": { "description": "List of drill down results", "properties": { "group_label": { "description": "Name of drill down group (drill down by website_id => group labels might be e.g. \"My video website\")", "type": "string" }, "id": { "description": "ID of drill down group (drill down by website_id => id might be e.g. \"60678\")", "type": "string" }, "sale_price_amount": { "description": "Amount in sale currency (only available for drill down by currency, otherwise null)", "type": "string" }, "total_amount": { "description": "Amount in requested output currency", "type": "string" } }, "required": [ "group_label", "id", "sale_price_amount", "total_amount" ], "type": "object", "x-order": [ "group_label", "id", "sale_price_amount", "total_amount" ] } }, "required": [ "result" ], "type": "object", "x-order": [ "result" ] } } }, "description": "Success 200" }, "401": { "description": "Unauthorized access" }, "406": { "description": "Missing version" } }, "summary": "Get sale data drilled down by different parameters", "tags": [ "Dashboard" ] } }, "/dashboard/totals": { "get": { "operationId": "GetDashboardTotals", "parameters": [ { "description": "HTTP basic authorization. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } }, { "description": "Requested content type and version of recource. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Accept", "required": true, "schema": { "type": "string" } }, { "description": "The currency you want to get the totals in", "in": "query", "name": "output_currency", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "last_30_days": { "description": "Sales for last 30 days (excl. today)", "type": "number" }, "last_365_days": { "description": "Sales for last 365 days (excl. today)", "type": "number" }, "last_7_days": { "description": "Sales for last 7 days (excl. today)", "type": "number" }, "prior_30_days_diff": { "description": "Percent change comparing last 30 days and its previous period", "type": "number" }, "prior_365_days_diff": { "description": "Percent change comparing last 365 days and its previous period", "type": "number" }, "prior_7_days_diff": { "description": "Percent change comparing last 7 days and its previous period", "type": "number" }, "today": { "description": "Sales for today", "type": "number" }, "yesterday": { "description": "Sales for yesterday", "type": "number" } }, "required": [ "today", "yesterday", "last_7_days", "last_30_days", "last_365_days", "prior_7_days_diff", "prior_30_days_diff", "prior_365_days_diff" ], "type": "object", "x-order": [ "today", "yesterday", "last_7_days", "last_30_days", "last_365_days", "prior_7_days_diff", "prior_30_days_diff", "prior_365_days_diff" ] } } }, "description": "Success 200" }, "401": { "description": "Unauthorized access" }, "406": { "description": "Missing version" } }, "summary": "Get sale totals for fixed date ranges", "tags": [ "Dashboard" ] } }, "/sale/{id}": { "get": { "operationId": "GetSale", "parameters": [ { "description": "HTTP basic authorization. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } }, { "description": "Requested content type and version of recource. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Accept", "required": true, "schema": { "type": "string" } }, { "description": "Sale unique ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "address": { "description": "Buyer street address, if it was required for the sale", "properties": { "address_line1": { "description": "1st line of address", "type": "string" }, "address_line2": { "description": "2nd line of address", "type": "string" }, "city": { "description": "City (municipality)", "type": "string" }, "company": { "description": "Company associated with the address", "type": "string" }, "country": { "description": "Country 2-chars ISO 3166-1 code, e.g. DK = Denmark, DE = Germany", "type": "string" }, "full_name": { "description": "Name associated with the address", "type": "string" }, "state": { "description": "State, only in case of US, ISO 3166-2 code e.g. US-CA = California", "type": "string" }, "zip": { "description": "Postal/ZIP code", "type": "string" } }, "required": [ "full_name", "company", "address_line1", "address_line2", "city", "zip", "state", "country" ], "type": "object", "x-order": [ "full_name", "company", "address_line1", "address_line2", "city", "zip", "state", "country" ] }, "buyer_email": { "description": "Email of the buyer", "type": "string" }, "buyer_ip": { "description": "IP address of the buyer", "type": "string" }, "buyer_name": { "description": "Name of the buyer", "type": "string" }, "country": { "description": "Country from which the sale has been made; 2-chars ISO 3166-1 code, e.g. DK = Denmark, DE = Germany", "type": "string" }, "created_at": { "description": "Date and time when the sale has been created", "type": "string" }, "custom1": { "description": "Custom merchant field #1", "type": "string" }, "custom2": { "description": "Custom merchant field #2", "type": "string" }, "custom3": { "description": "Custom merchant field #3", "type": "string" }, "description": { "description": "Description of the subscription or purchase", "type": "string" }, "id": { "description": "Unique sale ID", "type": "number" }, "is_approved": { "description": "Indicates if the transaction has been approved i.e. the price was paid", "type": "boolean" }, "is_testing": { "description": "Indicates if the transaction was processed using a testing credit card number; such transaction does not represent real money", "type": "boolean" }, "payment_method": { "type": "string" }, "price": { "description": "Applies to both purchases and subscriptions (i.e. rebill price)", "properties": { "amount": { "type": "string" }, "currency": { "description": "Price currency as ISO 4217 code, e.g. `USD`, `EUR`, `GBP`", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object", "x-order": [ "amount", "currency" ] }, "reference_id": { "description": "Custom identifier posted by merchant", "type": "string" }, "sale_type": { "type": "string" }, "subscription": { "description": "If the sale is a subscription, this contains detailed information about it", "properties": { "cancel_discount": { "description": "Discount applied when buyer tried to cancel subscription. This object replaces simple `is_discounted` field in previous version", "properties": { "applied_on": { "description": "If applied = true, this is the date when the buyer accepted the discount; ISO-8601 format e.g. 2016-04-27", "type": "string" }, "is_applied": { "description": "Indicates if the buyer has been offered and accepted a discount when they tried to cancel the subscription", "type": "boolean" }, "percent": { "description": "If applied = true, this is the amount of the discount in percent i.e. 10 - 50 %", "type": "number" }, "price_after_discount": { "description": "If applied = true, this is the price after the discount was applied; this field does not reflect any subsequent changes to the price, it is a snapshot in time", "properties": { "amount": { "type": "string" }, "currency": { "description": "Price currency as ISO 4217 code", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object", "x-order": [ "amount", "currency" ] } }, "required": [ "is_applied" ], "type": "object", "x-order": [ "is_applied", "percent", "applied_on", "price_after_discount" ] }, "expiration_date": { "description": "When the subscription expires", "type": "string" }, "is_cancelled": { "description": "Indicates if the subscription has been cancelled, i.e. future recurring has been stopped, but it may still be active", "type": "string" }, "is_expired": { "description": "Indicates if the subscription is not active anymore", "type": "string" }, "is_recurring": { "description": "Indicates if the subscription will be automatically rebilled", "type": "string" }, "next_charge_on": { "description": "Date on which next charge will be made for the subscription", "type": "string" }, "period": { "description": "Subscription period in ISO-8601 format, eg. P2Y = 2 years", "type": "string" } }, "required": [ "is_recurring", "period", "is_expired", "next_charge_on", "is_cancelled", "expiration_date", "cancel_discount" ], "type": "object", "x-order": [ "is_recurring", "period", "is_expired", "next_charge_on", "is_cancelled", "expiration_date", "cancel_discount" ] }, "trial_price": { "description": "If the subscription has trial period, this is its price", "properties": { "amount": { "type": "string" }, "currency": { "description": "Price currency as ISO 4217 code, e.g. `USD`, `EUR`,", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object", "x-order": [ "amount", "currency" ] }, "website_id": { "description": "Website ID", "type": "number" } }, "required": [ "id", "website_id", "sale_type", "price", "description", "reference_id", "created_at", "buyer_name", "buyer_email", "buyer_ip", "country", "custom1", "custom2", "custom3", "payment_method", "is_approved", "is_testing" ], "type": "object", "x-order": [ "id", "website_id", "sale_type", "price", "trial_price", "description", "reference_id", "created_at", "buyer_name", "buyer_email", "buyer_ip", "country", "address", "subscription", "custom1", "custom2", "custom3", "payment_method", "is_approved", "is_testing" ] } } }, "description": "Success 200" }, "401": { "description": "Unauthorized access" }, "406": { "description": "Missing version" } }, "summary": "Get sale", "tags": [ "Sales" ] } }, "/sale/{id}/cancel": { "post": { "operationId": "CancelBilling", "parameters": [ { "description": "HTTP basic authorization. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } }, { "description": "Requested content type and version of recource. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Accept", "required": true, "schema": { "type": "string" } }, { "description": "Sale unique ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "is_success": { "description": "Indicates if the operation succeeded", "type": "boolean" } }, "required": [ "is_success" ], "type": "object", "x-order": [ "is_success" ] } } }, "description": "Success 200" }, "401": { "description": "Unauthorized access" }, "406": { "description": "Missing version" }, "412": { "description": "Invalid parameter" } }, "summary": "Cancel future billing", "tags": [ "Sales" ] } }, "/sale/{id}/downgrade": { "post": { "operationId": "DowngradeSale", "parameters": [ { "description": "HTTP basic authorization. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } }, { "description": "Requested content type and version of recource. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Accept", "required": true, "schema": { "type": "string" } }, { "description": "Sale unique ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "is_success": { "description": "Indicates if the operation succeeded", "type": "boolean" }, "sale_id": { "description": "Unique sale ID", "type": "number" } }, "required": [ "is_success", "sale_id" ], "type": "object", "x-order": [ "is_success", "sale_id" ] } } }, "description": "Success 200" }, "401": { "description": "Unauthorized access" }, "406": { "description": "Missing version" } }, "summary": "Downgrade sale", "tags": [ "Sales" ] } }, "/sale/{id}/extend": { "post": { "description": "Extends subscription period of the sale", "operationId": "ExtendSale", "parameters": [ { "description": "HTTP basic authorization. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } }, { "description": "Requested content type and version of recource. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Accept", "required": true, "schema": { "type": "string" } }, { "description": "Sale unique ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "is_success": { "description": "Indicates if the operation succeeded", "type": "boolean" }, "new_expiration_date": { "description": "The new expiration date, after it has been extended", "type": "string" }, "sale_id": { "description": "Unique sale ID", "type": "number" } }, "required": [ "is_success", "sale_id", "new_expiration_date" ], "type": "object", "x-order": [ "is_success", "sale_id", "new_expiration_date" ] } } }, "description": "Success 200" }, "401": { "description": "Unauthorized access" }, "406": { "description": "Missing version" } }, "summary": "Extend sale", "tags": [ "Sales" ] } }, "/sale/{id}/terminate": { "post": { "operationId": "TerminateSale", "parameters": [ { "description": "HTTP basic authorization. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } }, { "description": "Requested content type and version of recource. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Accept", "required": true, "schema": { "type": "string" } }, { "description": "Sale unique ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "is_success": { "description": "Indicates if the operation succeeded", "type": "boolean" }, "sale_id": { "description": "Unique sale ID", "type": "number" } }, "required": [ "is_success", "sale_id" ], "type": "object", "x-order": [ "is_success", "sale_id" ] } } }, "description": "Success 200" }, "401": { "description": "Unauthorized access" }, "406": { "description": "Missing version" } }, "summary": "Terminate sale", "tags": [ "Sales" ] } }, "/sale/{id}/transactions": { "get": { "description": "Returns all transactions for sale `id` sorted by `created_at` in ascending order", "operationId": "GetSaleTransactions", "parameters": [ { "description": "HTTP basic authorization. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } }, { "description": "Requested content type and version of recource. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Accept", "required": true, "schema": { "type": "string" } }, { "description": "Sale unique ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "number" } }, { "description": "Indicates if only approved (i.e. transactions whose price was paid) or not approved transactions should be returned. If omitted, both approved and not approved transactions are returned.", "in": "query", "name": "is_approved", "required": false, "schema": { "type": "boolean" } }, { "description": "Indicates if only testing (i.e. transactions processed using a testing credit card number; such transaction do not represent real money) or not testing transactions should be returned. If omitted, both testing and not testing transactions are returned.", "in": "query", "name": "is_testing", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "description": "Date and time when the transaction was created", "type": "string" }, "id": { "description": "Unique transaction identifier", "type": "number" }, "is_approved": { "description": "Indicates if the transaction has been approved i.e. the price was paid", "type": "boolean" }, "is_testing": { "description": "Indicates if the transaction was processed using a testing credit card number; such transaction does not represent real money", "type": "boolean" }, "payment_instrument": { "description": "Indicates the payment instrument used to pay the price of this transaction", "properties": { "masked_identifier": { "description": "Identification of the payment instrument", "type": "object" }, "type": { "description": "Type of payment instrument (credit card, bank account etc.)", "type": "string" } }, "required": [ "type", "masked_identifier" ], "type": "object", "x-order": [ "type", "masked_identifier" ] }, "payment_method": { "type": "string" }, "price": { "description": "Price of the transaction", "properties": { "amount": { "description": "Price amount", "type": "string" }, "currency": { "description": "Price currency as ISO 4217 code, e.g. `USD`, `EUR`, `GBP`", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object", "x-order": [ "amount", "currency" ] }, "transaction_subtype": { "type": "string" }, "transaction_type": { "type": "string" }, "website_id": { "description": "Unique identifier of the website the transaction belongs to", "type": "number" } }, "required": [ "created_at", "id", "price", "website_id", "is_approved", "is_testing", "payment_method", "transaction_subtype", "transaction_type", "payment_instrument" ], "type": "object", "x-order": [ "created_at", "id", "price", "website_id", "is_approved", "is_testing", "payment_method", "transaction_subtype", "transaction_type", "payment_instrument" ] } } }, "description": "Success 200" }, "401": { "description": "Unauthorized access" }, "406": { "description": "Missing version" }, "412": { "description": "Missing query parameter" } }, "summary": "Get sale transactions", "tags": [ "Sales" ] } }, "/transaction/{id}": { "get": { "operationId": "GetTransaction", "parameters": [ { "description": "HTTP basic authorization. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } }, { "description": "Requested content type and version of recource. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Accept", "required": true, "schema": { "type": "string" } }, { "description": "Transaction unique ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "description": "Date and time when the transaction was created", "type": "string" }, "decline_reason": { "description": "If the transaction was declined, i.e. not approved, this will contain the reason why it wasn't approved", "properties": { "description": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "description" ], "type": "object", "x-order": [ "id", "description" ] }, "id": { "description": "Unique transaction identifier", "type": "number" }, "is_approved": { "description": "Indicates if the transaction has been approved i.e. the price was paid", "type": "boolean" }, "is_testing": { "description": "Indicates if the transaction was processed using a testing credit card number; such transaction does not represent real money", "type": "boolean" }, "original_debit_transaction_id": { "description": "If the transaction is a reversal (refund or chargeback), this field contains reference to the reversed debit transaction", "type": "number" }, "payment_instrument": { "description": "Indicates the payment instrument used to pay the price of this transaction", "properties": { "masked_identifier": { "description": "Identification of the payment instrument", "type": "object" }, "type": { "description": "Type of payment instrument (credit card, bank account etc.)", "type": "string" } }, "required": [ "type", "masked_identifier" ], "type": "object", "x-order": [ "type", "masked_identifier" ] }, "payment_method": { "type": "string" }, "price": { "description": "Price of the transaction", "properties": { "amount": { "description": "Price amount", "type": "string" }, "currency": { "description": "Price currency as ISO 4217 code, e.g. `USD`, `EUR`, `GBP`", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object", "x-order": [ "amount", "currency" ] }, "reversal_extent": { "description": "Indicates if transaction was fully, partially or not yet been reversed", "type": "string" }, "reversals": { "description": "If the transaction is reversed (refunded or chargebacked), the reversals are listed here", "properties": { "id": { "description": "Reversal transaction ID", "type": "number" }, "price": { "description": "Price of the reversal transaction", "properties": { "amount": { "description": "Price amount", "type": "string" }, "currency": { "description": "Price currency as ISO 4217 code, e.g. `USD`, `EUR`, `GBP`", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object", "x-order": [ "amount", "currency" ] }, "type": { "type": "string" } }, "required": [ "id", "type", "price" ], "type": "object", "x-order": [ "id", "type", "price" ] }, "sale": { "description": "Information about the sale this transaction belongs to", "properties": { "custom1": { "description": "Custom merchant field #1", "type": "number" }, "custom2": { "description": "Custom merchant field #2", "type": "number" }, "custom3": { "description": "Custom merchant field #3", "type": "number" }, "id": { "description": "Unique sale identifier", "type": "number" }, "reference_id": { "description": "Custom identifier posted by merchant", "type": "string" }, "type": { "type": "string" } }, "required": [ "custom1", "custom2", "custom3", "id", "reference_id", "type" ], "type": "object", "x-order": [ "custom1", "custom2", "custom3", "id", "reference_id", "type" ] }, "transaction_subtype": { "type": "string" }, "transaction_type": { "type": "string" }, "website_id": { "description": "Unique identifier of the website the transaction belongs to", "type": "number" } }, "required": [ "id", "created_at", "sale", "website_id", "price", "reversal_extent", "original_debit_transaction_id", "is_approved", "is_testing", "payment_method", "transaction_subtype", "transaction_type", "payment_instrument" ], "type": "object", "x-order": [ "id", "decline_reason", "created_at", "sale", "website_id", "price", "reversal_extent", "reversals", "original_debit_transaction_id", "is_approved", "is_testing", "payment_method", "transaction_subtype", "transaction_type", "payment_instrument" ] } } }, "description": "Success 200" }, "401": { "description": "Unauthorized access" }, "406": { "description": "Missing version" } }, "summary": "Get transaction", "tags": [ "Transactions" ] } }, "/transaction/{id}/refund": { "post": { "operationId": "RefundTransaction", "parameters": [ { "description": "HTTP basic authorization. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } }, { "description": "Requested content type and version of recource. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Accept", "required": true, "schema": { "type": "string" } }, { "description": "Id of the transaction to be refunded.", "in": "path", "name": "id", "required": true, "schema": { "type": "number" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "partial_refund_amount": { "description": "If you only want to refund part of the amount, indicate it here. Minimum amount to refund is the same as your regular transaction minimum amount.", "type": "number" } }, "type": "object", "x-order": [ "partial_refund_amount" ] } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "is_success": { "description": "Indicates if the operation succeeded", "type": "boolean" }, "refund_transaction_id": { "description": "Id of the created refund transaction", "type": "number" }, "warning": { "description": "If there have been some problems", "properties": { "message": { "description": "Message, describing the problem", "type": "string" } }, "type": "object", "x-order": [ "message" ] } }, "required": [ "is_success", "refund_transaction_id" ], "type": "object", "x-order": [ "is_success", "refund_transaction_id", "warning" ] } } }, "description": "Success 200" }, "401": { "description": "Unauthorized access" }, "406": { "description": "Missing version" }, "412": { "description": "Transaction has linker / too large partial refund amount etc." } }, "summary": "Refund sale transaction", "tags": [ "Transactions" ] } }, "/website/{id}/sales": { "get": { "description": "Returns all sales for website `id` sorted by `created_at` in ascending order\n\n This call is limited to 5000 sales. If the selected filters result in a larger number of sales, HTTP error 412 - Precondition Failed will be returned and you wil have to narrow down your filtering criteria (reduce date range etc.)", "operationId": "GetWebsiteSales", "parameters": [ { "description": "HTTP basic authorization. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } }, { "description": "Requested content type and version of recource. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Accept", "required": true, "schema": { "type": "string" } }, { "description": "Website unique ID", "in": "path", "name": "id", "required": true, "schema": { "type": "number" } }, { "description": "Indicates if only approved or not approved sales should be returned. If omitted, both approved and not approved records are returned.", "in": "query", "name": "is_approved", "required": false, "schema": { "type": "boolean" } }, { "description": "Indicates if only testing or not testing transactions should be returned. If omitted, both testing and not testing records are returned.", "in": "query", "name": "is_testing", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "address": { "description": "Buyer street address, if it was required for the sale", "properties": { "address_line1": { "description": "1st line of address", "type": "string" }, "address_line2": { "description": "2nd line of address", "type": "string" }, "city": { "description": "City (municipality)", "type": "string" }, "company": { "description": "Company associated with the address", "type": "string" }, "country": { "description": "Country 2-chars ISO 3166-1 code, e.g. DK = Denmark, DE = Germany", "type": "string" }, "full_name": { "description": "Name associated with the address", "type": "string" }, "state": { "description": "State, only in case of US, ISO 3166-2 code e.g. US-CA = California", "type": "string" }, "zip": { "description": "Postal/ZIP code", "type": "string" } }, "required": [ "full_name", "company", "address_line1", "address_line2", "city", "zip", "state", "country" ], "type": "object", "x-order": [ "full_name", "company", "address_line1", "address_line2", "city", "zip", "state", "country" ] }, "buyer_email": { "description": "Email of the buyer", "type": "string" }, "buyer_name": { "description": "Name of the buyer", "type": "string" }, "country": { "description": "Country from which the sale has been made; 2-chars ISO 3166-1 code, e.g. DK = Denmark, DE = Germany", "type": "string" }, "created_at": { "description": "Date and time when the sale was created", "type": "string" }, "custom1": { "description": "Custom merchant field #1", "type": "number" }, "custom2": { "description": "Custom merchant field #2", "type": "number" }, "custom3": { "description": "Custom merchant field #3", "type": "number" }, "description": { "description": "Description of the subscription or purchase", "type": "string" }, "id": { "description": "Unique sale identifier", "type": "number" }, "is_approved": { "description": "Indicates if the sale has been approved i.e. the price was paid", "type": "boolean" }, "is_subscription": { "description": "Indicates if the sale represents a subscription or a one-off sale", "type": "boolean" }, "is_testing": { "description": "Indicates if the sale was processed using a testing credit card number; such sale does not represent real money", "type": "boolean" }, "payment_method": { "type": "string" }, "price": { "description": "Price of the sale / recurring price (for recurring subscription)", "properties": { "amount": { "description": "Price amount", "type": "string" }, "currency": { "description": "Price currency", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object", "x-order": [ "amount", "currency" ] }, "reference_id": { "description": "Custom identifier posted by merchant", "type": "string" }, "subscription": { "description": "If the sale is a subscription, this contains detailed information about it", "properties": { "cancel_discount": { "description": "Discount applied when buyer tried to cancel subscription. This object replaces simple `is_discounted` field in previous version", "properties": { "applied_on": { "description": "If applied = true, this is the date when the buyer accepted the discount; ISO-8601 format e.g. 2016-04-27", "type": "string" }, "is_applied": { "description": "Indicates if the buyer has been offered and accepted a discount when they tried to cancel the subscription", "type": "boolean" }, "percentage": { "description": "If applied = true, this is the amount of the discount in percent i.e. 10 - 50 %", "type": "number" }, "price_after_discount": { "description": "If applied = true, this is the price after the discount was applied; this field does not reflect any subsequent changes to the price, it is a snapshot in time", "properties": { "amount": { "type": "string" }, "currency": { "description": "Price currency as ISO 4217 code", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object", "x-order": [ "amount", "currency" ] } }, "required": [ "is_applied" ], "type": "object", "x-order": [ "is_applied", "percentage", "applied_on", "price_after_discount" ] }, "expiration_date": { "description": "When the subscription expires", "type": "string" }, "is_cancelled": { "description": "Indicates if the subscription has been cancelled, i.e. future recurring has been stopped, but it may still be active", "type": "string" }, "is_expired": { "description": "Indicates if the subscription is not active anymore", "type": "string" }, "is_recurring": { "description": "Indicates if the subscription will be automatically rebilled", "type": "string" }, "next_charge_on": { "description": "Date on which next charge will be made for the subscription", "type": "string" }, "period": { "description": "Subscription period in ISO-8601 format, eg. P2Y = 2 years", "type": "string" }, "trial_period": { "description": "Subscription trial period in ISO-8601 format, eg. P2Y = 2 years", "type": "string" }, "trial_price": { "description": "Price of the trial period", "properties": { "amount": { "description": "Price amount", "type": "string" }, "currency": { "description": "Price currency", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object", "x-order": [ "amount", "currency" ] } }, "required": [ "is_recurring", "period", "trial_period", "is_expired", "next_charge_on", "is_cancelled", "expiration_date", "cancel_discount" ], "type": "object", "x-order": [ "trial_price", "is_recurring", "period", "trial_period", "is_expired", "next_charge_on", "is_cancelled", "expiration_date", "cancel_discount" ] }, "type": { "type": "string" } }, "required": [ "id", "created_at", "is_approved", "is_testing", "is_subscription", "price", "custom1", "custom2", "custom3", "reference_id", "description", "buyer_name", "buyer_email", "country", "type", "payment_method" ], "type": "object", "x-order": [ "id", "created_at", "is_approved", "is_testing", "is_subscription", "price", "custom1", "custom2", "custom3", "reference_id", "description", "buyer_name", "buyer_email", "country", "address", "subscription", "type", "payment_method" ] } } }, "description": "Success 200" }, "401": { "description": "Unauthorized access" }, "406": { "description": "Missing version" }, "412": { "description": "Invalid date range" } }, "summary": "Get website sales", "tags": [ "Website" ] } }, "/website/{id}/transactions": { "get": { "description": "Returns all transactions for website `id` sorted by `created_at` in ascending order\n\n This call is limited to 5000 transactions. If the selected filters result in a larger number of transactions, HTTP error 412 - Precondition Failed will be returned and you wil have to narrow down your filtering criteria (reduce date range etc.)", "operationId": "GetWebsiteTransactions", "parameters": [ { "description": "HTTP basic authorization. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } }, { "description": "Requested content type and version of recource. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Accept", "required": true, "schema": { "type": "string" } }, { "description": "Website unique ID", "in": "path", "name": "id", "required": true, "schema": { "type": "number" } }, { "description": "ISO date (e.g. 2016-12-31) Transactions with this date or earlier will be returned", "in": "query", "name": "to_date", "required": false, "schema": { "type": "string" } }, { "description": "Indicates if only approved (i.e. transactions whose price was paid) or not approved transactions should be returned. If omitted, both approved and not approved transactions are returned.", "in": "query", "name": "is_approved", "required": false, "schema": { "type": "boolean" } }, { "description": "Indicates if only testing (i.e. transactions processed using a testing credit card number; such transaction do not represent real money) or not testing transactions should be returned. If omitted, both testing and not testing transactions are returned.", "in": "query", "name": "is_testing", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "description": "Date and time when the transaction was created", "type": "string" }, "id": { "description": "Unique transaction identifier", "type": "number" }, "is_approved": { "description": "Indicates if the transaction has been approved i.e. the price was paid", "type": "boolean" }, "is_testing": { "description": "Indicates if the transaction was processed using a testing credit card number; such transaction does not represent real money", "type": "boolean" }, "payment_instrument": { "description": "Indicates the payment instrument used to pay the price of this transaction", "properties": { "masked_identifier": { "description": "Identification of the payment instrument", "type": "object" }, "type": { "description": "Type of payment instrument (credit card, bank account etc.)", "type": "string" } }, "required": [ "type", "masked_identifier" ], "type": "object", "x-order": [ "type", "masked_identifier" ] }, "payment_method": { "type": "string" }, "price": { "description": "Price of the transaction", "properties": { "amount": { "description": "Price amount", "type": "string" }, "converted_amount": { "description": "If `convert_to_currency` parameter is used, this contains the converted amount", "type": "string" }, "converted_currency": { "description": "If `convert_to_currency` parameter is used, this contains the converted currency", "type": "string" }, "currency": { "description": "Price currency as ISO 4217 code, e.g. `USD`, `EUR`, `GBP`", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object", "x-order": [ "amount", "converted_amount", "converted_currency", "currency" ] }, "sale": { "description": "Information about the sale this transaction belongs to", "properties": { "custom1": { "description": "Custom merchant field #1", "type": "number" }, "custom2": { "description": "Custom merchant field #2", "type": "number" }, "custom3": { "description": "Custom merchant field #3", "type": "number" }, "id": { "description": "Unique sale identifier", "type": "number" }, "reference_id": { "description": "Custom identifier posted by merchant", "type": "string" }, "type": { "description": "Type of the sale", "type": "string" } }, "required": [ "custom1", "custom2", "custom3", "id", "reference_id", "type" ], "type": "object", "x-order": [ "custom1", "custom2", "custom3", "id", "reference_id", "type" ] }, "transaction_subtype": { "type": "string" }, "transaction_type": { "type": "string" } }, "required": [ "created_at", "id", "price", "sale", "is_approved", "is_testing", "payment_method", "transaction_subtype", "transaction_type", "payment_instrument" ], "type": "object", "x-order": [ "created_at", "id", "price", "sale", "is_approved", "is_testing", "payment_method", "transaction_subtype", "transaction_type", "payment_instrument" ] } } }, "description": "Success 200" }, "401": { "description": "Unauthorized access" }, "406": { "description": "Missing version" }, "412": { "description": "Invalid date range" } }, "summary": "Get website transactions", "tags": [ "Website" ] } }, "/websites": { "get": { "description": "Returns list of merchant's websites, optionally filtered", "operationId": "GetWebsites", "parameters": [ { "description": "HTTP basic authorization. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } }, { "description": "Requested content type and version of recource. See [description on top of this page](#requiredHeaders).", "in": "header", "name": "Accept", "required": true, "schema": { "type": "string" } }, { "description": "Show only visible / hidden websites", "in": "query", "name": "hidden", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "description": { "description": "Website description", "type": "string" }, "id": { "description": "Unique website identifier", "type": "number" }, "is_hidden": { "description": "Indicates whether the website is hidden or not", "type": "boolean" }, "is_testing_mode": { "description": "Indicates whether the website is in testing mode or not", "type": "boolean" }, "name": { "description": "Website name", "type": "string" }, "status_description": { "description": "Status of the website as a readable text", "type": "string" }, "type": { "description": "Type of the website", "type": "string" }, "url": { "description": "URL of the website", "type": "string" } }, "required": [ "description", "id", "is_hidden", "is_testing_mode", "name", "status_description", "type", "url" ], "type": "object", "x-order": [ "description", "id", "is_hidden", "is_testing_mode", "name", "status_description", "type", "url" ] } } }, "description": "Success 200" }, "401": { "description": "Unauthorized access" }, "406": { "description": "Missing version" }, "412": { "description": "Missing query parameter" } }, "summary": "Get list of merchant websites", "tags": [ "Website" ] } } }, "servers": [ { "url": "https://controlcenter.verotel.com/api" } ] }