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

Introduction

Demo payment page

Checkout Overview

Example

Operations

Examples

Operations

Google Payâ„¢

Override theme

Other request examples

Operations

Embedded flow

Build a checkout page on the client

  • Load Upgate.js

    Leverage Upgate.js to maintain PCI compliance by ensuring that payment information is transmitted directly to Upgate without accessing your server. To stay compliant, consistently load Upgate.js from js.upgate.com. Avoid incorporating the script into a bundle or hosting it independently. Create ./public folder and create index.html with code below:
<html lang="en">
  <head>
    <script type="module" src="https://js.upgate.com/upgate.js"></script>
    <script type="module" src="/main.js"></script>
    <style>
      body {
        min-height: 100vh;
        justify-content: center;
        width: 350px;
        margin: 0 auto;
        display: flex;
        flex-direction: column;
        gap: 32px;
      }
    </style>
  </head>
  <body>
    <div id="payment"></div>
    <button id="buy" onclick="submit()">Buy</button>
  </body>
</html>

  • Mount Checkout element

    Upon loading your checkout page, promptly initiate a request to the endpoint on your server to generate a new Checkout. The URL provided by your endpoint is utilized for rendering the embedded checkout element. Create a CheckoutElement and mount it to the element <div id="payment"> in your payment form. This incorporates an iframe containing a dynamic form that showcases configured payment method types available from the Checkout, enabling your customer to choose a payment method. The form autonomously gathers the relevant payment details for the chosen payment method type. Create main.js file with code below in ./public folder:
let upgate;
const elementId = "payment";
async function mount() {
  const { url } = await fetch("/checkout", { method: "POST" }).then((res) =>
    res.json()
  );
  upgate.mountPaymentElement(elementId, url);
  upgate.onResult(elementId, console.log); // use this method for handle result
}
function submit() {
  upgate.submit(elementId);
}
window.onload = async () => {
  upgate = new Upgate();
  mount();
};

Invoke submit('%elementId%'), providing the CheckoutElement and a success_url to specify the destination where Upgate should redirect the user upon completing the payment. For payments necessitating authentication, Upgate presents a modal for 3D Secure authentication or directs the customer to an authentication page, contingent on the payment method utilized. Following the completion of the authentication process, the customer is redirected to the specified success_url.

  • Handle response after submit

    Pass callback parameter in upgate.onResult function for handle TResult type object.
export type TResult = {
  success: boolean;
  url?: string;
  error_message?: string;
  error_code?: number;
  retry?: boolean;
};

All types of Upgate.js you can find in index.d.ts.

  • If success: true - payment processed successful.
  • If success: false; retry: false - payment was not processed, and form must be unmounted with unmountPaymentElement('payment').
  • If retry: true; success: false you can submit same form again (form not valid for example).
  • If payment was failed user will be redirected to failure_url with query parameters ?error_code=&error_message=

Config payment form

In mountPaymentElement function you can pass third config parameter.

declare type TConfig = Partial<{
  theme?: "LIGHT" | "DARK" | "BROWSER";
  onTimeout?: () => void;
}>;

Property theme overrides theme type defined in back office, and you can call embedded form with dynamically changed theme. Callback onTimeout will call when form time limit exceed. After timeout you need to remount component. Theme type BROWSER renders theme depending on system theme.

upgate.mountPaymentElement("%elementId%", "%checkoutUrl%", { theme: "LIGHT" });

Checkout form timeout

After 15 minutes, a timeout will occur in the checkout process. The handling differs based on whether the form is embedded or non-embedded:

  • For non-embedded form, when the checkout session times out, the user will be redirected to the failure URL.
  • For embedded form for handle form timeout you can use timeout callback in mount config:
upgate.mountPaymentElement("%elementId%", "%checkoutUrl%", {
  theme: "LIGHT",
  onTimeout: handleTimeOutFn,
});

Or call onTimeout method after mount with timeout handler function as a parameter:

upgate.onTimeout("%elementId%", handleTimeOutFn);

When timeout handler was called you need to remount payment element.

FAQ