Skip to content

UpGate API documentation (1.2)

UpGate is a world-class payment orchestration platform. Our mission is to simplify payments and make it easier for merchants to reach global customers. We use the latest technologies to help you achieve better conversions and global user monetization.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL

https://upgate.com

E-mail

sales@upgate.com

Terms of Service

Languages
Servers
Mock server

https://docs.upgate.com/_mock/openapi/

Sandbox UpGate API

https://api.sandbox.upgate.com/v1/

Changelog

[1.1.47] - 2025-10-09

Added

  • New refund request Refund transaction by id
  • Field transaction_amount has been added to data in transaction postbacks
  • Field transaction_currency_code has been added to data in transaction postbacks

[1.1.46] - 2025-09-17

Added

  • New response codes added '3901 Processor Communication Error'

[1.1.45] - 2025-09-10

Added

[1.1.44] - 2025-08-13

Added

  • New payout method BANK_TRANSFER

[1.1.43] - 2025-08-04

Changed

  • New payment method added
  • New response codes added

[1.1.42] - 2025-07-09

Changed

  • New payment methods added

[1.1.41] - 2025-07-03

Added

  • Field card_bin_country_name has been added to data in transaction postbacks
  • Field card_bin_country_code has been added to data in transaction postbacks
  • Field card_bin_type has been added to data in transaction postbacks

[1.1.40] - 2025-07-02

Added

[1.1.39] - 2025-07-01

Changed

  • New payment methods added
  • FAQ updated

[1.1.38] - 2025-06-20

Added

  • New response code '2120 Invalid amount'

[1.1.37] - 2025-05-29

Added

  • Add new response code group 'PENDING'

Changed

  • Response code 1200 moved to group 'PENDING'

[1.1.36] - 2025-05-26

Added

  • New fields transaction_fee_amount, transaction_tax_amount, transaction_tax_type, transaction_tax_label, transaction_tax_percentage to postback payment
  • New fields rebill_transaction_fee_amount, rebill_transaction_fee_currency_code, rebill_transaction_tax_amount, rebill_transaction_tax_currency_code to postback products
  • New fields transaction_fee_amount, transaction_fee_currency_code, transaction_tax_amount, transaction_tax_currency_code, transaction_tax_type, transaction_tax_label, transaction_tax_percentage to postback subscription
  • New fields transaction_fee_amount, transaction_tax_amount, transaction_tax_type, transaction_tax_label, transaction_tax_percentage to response payment
  • New fields rebill_transaction_fee_amount, rebill_transaction_fee_currency_code, rebill_transaction_tax_amount, rebill_transaction_tax_currency_code to response products
  • New fields transaction_fee_amount, transaction_fee_currency_code, transaction_tax_amount, transaction_tax_currency_code, transaction_tax_type, transaction_tax_label, transaction_tax_percentage to response subscription

[1.1.35] - 2025-05-23

Added

  • New response code '2016 Crypto address is invalid'

[1.1.34] - 2025-05-19

Added

[1.1.33] - 2025-04-25

Added

  • New response code '2908 Payment token is not valid'

[1.1.32] - 2025-04-14

Added

  • New payment methods added

[1.1.31] - 2025-04-03

Added

  • New fields rebill_transaction_amount, rebill_transaction_currency_code to transaction product postback & response

[1.1.30] - 2025-04-07

Added

  • New payment methods added

[1.1.29] - 2025-03-05

Added

  • New field customer_selected_country_code to postback payment details

[1.1.28] - 2025-02-24

Added

  • New transaction types: RDR and RDR_REVERSAL

[1.1.27] - 2025-02-17

Added

  • New fields customer_phone_number, customer_email, customer_first_name, customer_last_name, payment_token_type to postback payment details
  • New fields processor_response_text, cascade_attempt, has_been_cascaded to postback transaction details

[1.1.26] - 2025-01-28

Added

  • New response code '2907 Payment type not supported for payment method'

[1.1.25] - 2025-01-27

Changed

  • Updated the page structure

[1.1.24] - 2025-01-15

Added

[1.1.23] - 2024-12-15

Added

  • New response code '2309 Customer blacklisted'

[1.1.22] - 2024-11-26

Added

  • Field version has been added to data in transaction postbacks
  • Field version has been added to data in subscription postbacks

[1.1.21] - 2024-10-16

Removed

  • Payment detail card_token_id has been removed from data.transactions.payment_details in postbacks
  • Payment detail card_token_id has been removed from data.transactions.payment_details in response to synchronous mit-sale and mit-authorize

[1.1.20] - 2024-10-03

Changed

Updated

[1.1.19] - 2024-09-17

Changed

  • Changed max length for field success_url from 2048 to 512
  • Changed max length for field failure_url from 2048 o 512

[1.1.18] - 2024-07-23

Added

  • Added request subscription by transaction ID

[1.1.17] - 2024-04-12

Added

  • Added Subscription state request by subscription id

[1.1.16] - 2024-04-10

Added

  • For callback added fields transaction_amount, transaction_currency_code and product_transaction_price

[1.1.15] - 2024-04-04

Changed

  • Update response codes

[1.1.14] - 2024-02-20

Added

  • Added Direct payment flow section
  • Added Checkout flow section
  • Added Checkout request examples
  • Added description of Embedded flow for Checkout
  • Added new APM payment methods

[1.1.13] - 2023-12-12

Added

  • Added fields shop_name and shop_url
  • For subscription added fields retry_at, retry_count and created_at
  • Added new APM payment methods

Changed

  • Update response codes

[1.1.12] - 2023-09-05

Added

  • Create token endpoint

Changed

  • Update response codes

[1.1.11] - 2023-03-05

Changed

  • For subscription renamed field customer_id to merchant_customer_id
  • For subscription renamed field is_enabled to is_rebill_enabled
  • Changed max length for field success_url from 64 to 2048
  • Changed max length for field failure_url from 64 to 2048
  • Changed max length for field email from 64 to 320
  • Changed that the amount for Authorize can be 0

Removed

  • Required header X-Merchant-ID from all requests

Demo payment page

Checkout Overview

Example

Operations

Examples

Operations

Subsequent request examples

Operations

Fetch transactions by filters

Request

When you request a list of transactions, the response is limited to the maximum number of records you specified in the query. If there are more transactions available beyond that limit, you don’t need to start over. Instead, you can continue fetching results from where you left off by including the prev_id parameter in your next request.

Security
X-Api-Key
Query
created_at_fromstring

Filter transactions created after this date (inclusive). Format: ISO 8601.

Example: created_at_from=2024-02-15T13:38:47.173Z
created_at_tostring

Filter transactions created before this date (inclusive). Format: ISO 8601.

Example: created_at_to=2024-02-15T13:38:47.173Z
limitinteger

Maximum number of transactions to return (default is 100, maximum is 1000, minimum is 1).

Example: limit=100
prev_idstring

Fetch transactions with IDs less than this value for pagination.

Example: prev_id=2JWZGUKDK2DK2
response_codeinteger

Filter transactions by response code for more specific results.

Example: response_code=1000, 2000
transaction_typestring

Filter transactions by type. Multiple types can be specified, separated by commas. Supported types include TOKEN, THREE_DS, SALE, AUTHORIZE, PAYOUT, CHARGEBACK, CHARGEBACK_REVERSAL, RDR, RDR_REVERSAL, REFUND, VOID and FRAUD_ALERT.

Example: transaction_type=SALE,THREE_DS,REFUND
curl -i -X GET \
  'https://docs.upgate.com/_mock/openapi/transaction?created_at_from=2024-02-15T13%3A38%3A47.173Z&created_at_to=2024-02-15T13%3A38%3A47.173Z&limit=100&prev_id=2JWZGUKDK2DK2&response_code=1000%2C+2000&transaction_type=SALE%2CTHREE_DS%2CREFUND' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
typestringrequired
Value"TRANSACTION"
dataArray of objects(postback)required
data[].​transaction_idstring[ 1 .. 64 ] charactersrequired
data[].​transaction_typestringrequired
Enum"TOKEN""THREE_DS""SALE""AUTHORIZE""PAYOUT""CHARGEBACK""CHARGEBACK_REVERSAL""RDR""RDR_REVERSAL""REFUND"
data[].​transaction_statusstringrequired
Enum"SUCCESS""DECLINE""ERROR"
data[].​created_atstringrequired

UTC date time format

data[].​response_codenumberrequired

Code from response codes

data[].​response_textstringrequired

Message from response codes

data[].​transaction_detailsobject(transactionDetails)required
data[].​transaction_details.​three_ds_authentication_valuestring

Only for 3ds postback

data[].​transaction_details.​three_ds_processorstring

Only for 3ds postback

data[].​transaction_details.​three_ds_server_transaction_idstring

Only for 3ds postback

data[].​transaction_details.​three_ds_ecistring

Only for 3ds postback

data[].​transaction_details.​three_ds_statusstring

Only for 3ds postback

data[].​transaction_details.​three_ds_challenge_typestring

Only for 3ds postback

data[].​transaction_details.​three_ds_versionstring

Only for 3ds postback

data[].​transaction_details.​three_ds_reason_codestring
data[].​transaction_details.​three_ds_reason_textstring
data[].​transaction_details.​three_ds_rule_idstring
data[].​transaction_details.​processor_merchant_account_idstring
data[].​transaction_details.​processor_transaction_idstring
data[].​transaction_details.​processorstringrequired
data[].​transaction_details.​processor_response_codestringrequired
data[].​transaction_details.​processor_response_textstring

Response text from processor

data[].​transaction_details.​processor_response_amountstring
data[].​transaction_details.​processor_response_currency_codestring
data[].​transaction_details.​processor_reference_idstring
data[].​transaction_details.​processor_used_low_valueboolean
data[].​transaction_details.​processor_used_citboolean
data[].​transaction_details.​processor_used_mitboolean
data[].​transaction_details.​processor_requestedboolean
data[].​transaction_details.​fraud_alert_processorstring
data[].​transaction_details.​reasonstring
data[].​transaction_details.​initiated_bystring
data[].​transaction_details.​routing_rule_idstring
data[].​transaction_details.​sticky_processor_usedboolean
data[].​transaction_details.​transaction_hashstring
data[].​transaction_details.​payment_form_has_been_displayedboolean
data[].​transaction_details.​cascade_attemptstring

Sequential number of the cascading attempt to payment processors

data[].​transaction_details.​has_been_cascadedboolean

Indicates whether cascading was performed

data[].​transaction_details.​arnstring
data[].​transaction_details.​reference_transaction_idstring
data[].​payment_contextobject(paymentContext)
data[].​payment_detailsobject(paymentDetails)required
data[].​payment_details.​payment_token_idstring

Only for CARD flow

data[].​payment_details.​payment_token_typestring
data[].​payment_details.​card_schemestring

Only for CARD flow

data[].​payment_details.​card_binstring

Only for CARD flow

data[].​payment_details.​card_bin_country_namestring

Only for CARD flow

data[].​payment_details.​card_bin_country_codestring

Only for CARD flow

data[].​payment_details.​card_bin_typestring

Only for CARD flow

data[].​payment_details.​card_bin_bankstring
data[].​payment_details.​card_bin_categorystring
data[].​payment_details.​card_scheme_typestring
data[].​payment_details.​card_last_four_digitsstring

Only for CARD flow

data[].​payment_details.​customer_full_namestring

Only for CARD flow

data[].​payment_details.​customer_phone_numberstring
data[].​payment_details.​customer_emailstring
data[].​payment_details.​customer_first_namestring
data[].​payment_details.​customer_last_namestring
data[].​payment_details.​card_expiry_monthstring

Only for CARD flow

data[].​payment_details.​card_expiry_yearstring

Only for CARD flow

data[].​payment_details.​card_data_idstring

Only for CARD flow

data[].​payment_details.​customer_selected_country_codestring
data[].​payment_details.​crypto_networkstring
data[].​payment_details.​crypto_addressstring
data[].​payment_details.​crypto_withdrawal_addressstring
data[].​payment_details.​debtor_ibanstring
data[].​payment_details.​debtor_bicstring
data[].​payment_details.​cit_enabledstring
data[].​payment_details.​creditor_namestring
data[].​payment_details.​creditor_bank_accountstring
data[].​payment_details.​creditor_bank_namestring
data[].​payment_details.​creditor_bank_bicstring
data[].​payment_details.​payment_emailstring
data[].​payment_details.​beneficiary_emailstring
data[].​payment_details.​referencestring
data[].​payment_details.​creditor_countrystring
data[].​payment_details.​creditor_emailstring
data[].​payment_details.​creditor_phonestring
data[].​payment_details.​creditor_bank_codestring
data[].​payment_details.​creditor_bank_numberstring
data[].​payment_details.​first_buy_for_merchant_customerboolean
data[].​payment_details.​first_buy_for_payment_tokenboolean
data[].​payment_details.​first_buy_for_merchant_customer_and_payment_tokenboolean
data[].​paymentobjectrequired
data[].​payment.​transaction_amountstring^\d{1,18}(?:\.\d{1,2})?$
data[].​payment.​transaction_currency_codestring^[A-Z]{3}$

Currency code (ISO 4217)

data[].​payment.​payment_idstring[ 1 .. 64 ] charactersrequired
data[].​payment.​initial_subscription_idstring[ 1 .. 64 ] characters
data[].​payment.​payment_typestringrequired
Enum"SALE""AUTHORIZE""MIT_SALE""MIT_AUTHORIZE""RECURRING"
data[].​payment.​payment_methodstringrequired
data[].​payment.​created_atstring[ 1 .. 64 ] charactersrequired

UTC date time format

Example: "2020-20-20T20:00:00.633Z"
data[].​payment.​merchant_idstring[ 1 .. 64 ] charactersrequired
data[].​payment.​merchant_payment_idstring[ 1 .. 64 ] characters
data[].​payment.​merchant_customer_idstring[ 1 .. 64 ] charactersrequired
data[].​payment.​emailstring[ 1 .. 320 ] charactersrequired
data[].​payment.​amountstring^\d{1,18}(?:\.\d{1,2})?$required
data[].​payment.​languagestring[ 1 .. 64 ] characters
data[].​payment.​country_codestring^[A-Z]{2}$required

Country Code (ISO 3166-2)

data[].​payment.​currency_codestring^[A-Z]{3}$required

Currency code (ISO 4217)

data[].​payment.​base_amountstring^\d{1,18}(?:\.\d{1,2})?$
data[].​payment.​base_currency_codestring^[A-Z]{3}$

Currency code (ISO 4217)

data[].​payment.​transaction_fee_amountstring^\d{1,18}(?:\.\d{1,2})?$
data[].​payment.​transaction_fee_currency_codestring^[A-Z]{3}$

Currency code (ISO 4217)

data[].​payment.​transaction_tax_amountstring^\d{1,18}(?:\.\d{1,2})?$
data[].​payment.​transaction_tax_currency_codestring^[A-Z]{3}$

Currency code (ISO 4217)

data[].​payment.​transaction_tax_percentagestring[ 0 .. 100 ]
data[].​payment.​transaction_tax_typestring
Enum"INCLUDED""ON_TOP"
data[].​payment.​transaction_tax_labelstring
Enum"TAX""VAT""GST""SALES_TAX"
data[].​payment.​forced_3dboolean

If needs to initiate 3d secure from merchant side

data[].​payment.​success_urlstring(url)[ 1 .. 2048 ] characters

required only for SALE | AUTHORIZE | RECURRING

data[].​payment.​failure_urlstring(url)[ 1 .. 2048 ] characters

required only for SALE | AUTHORIZE | RECURRING

data[].​payment.​payment_token_idstring[ 1 .. 64 ] characters

Token from original payment. Used for MIT_SALE | MIT_AUTHORIZE

data[].​payment.​shop_namestring[ 1 .. 128 ] characters

Shop name

data[].​payment.​shop_urlstring[ 1 .. 128 ] characters

Shop URL with protocol HTTP or HTTPS

data[].​payment.​sessionobject(session)
data[].​payment.​productsArray of productSale (object) or productSubscription (object)required

Expected at least 1 product

One of:
data[].​payment.​products[].​product_idstring[ 1 .. 64 ] characters

Product ID in Upgate env

data[].​payment.​products[].​merchant_product_idstring[ 1 .. 128 ] characters

Optional field, might be used as a reference from the merchant side

data[].​payment.​products[].​product_pricestring^\d{1,18}(?:\.\d{1,2})?$required
data[].​payment.​products[].​product_transaction_pricestring^\d{1,18}(?:\.\d{1,2})?$
data[].​payment.​products[].​product_namestring[ 1 .. 256 ] charactersrequired
data[].​payment.​products[].​product_descriptionstring[ 1 .. 256 ] characters
data[].​payment.​products[].​product_typestringrequired
Value"SALE"
metaobject(metaTransactionList)required
meta.​next_prev_idstring
Response
application/json
{
  "type": "TRANSACTION",
  "data": [
    { … },
    { … },
    { … }
  ],
  "meta": {
    "next_prev_id": "347ZHDT222H23"
  }
}

Example

Operations

Other request examples

Operations