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
Sandbox UpGate API
https://api.sandbox.upgate.com/v1/

Changelog

[1.1.48] - 2025-11-19

Added

  • New response code added '2104 Invalid network token expiry date'
  • New response code added '2147 Missing network token cryptogram'
  • New response code added '2148 Invalid network token cryptogram'
  • New response code added '2149 Invalid network token ECI'
  • New response code added '2150 Invalid network token'

[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

Introduction

Demo payment page

Checkout Overview

Example

Operations

Examples

Operations

Subsequent request examples

Operations

MIT Authorize request

Request

Security
X-Api-Key
Query
modestring
Default "ASYNC"
Enum"SYNC""ASYNC"
Headers
X-Idempotency-Keystring

The system supports the query deduplication mechanism. Any system-wide merchant's request after the first one with the same X-Idempotency-Key will return an error. For example, if you have retrying mechanism for payouts and you want to avoid double sending, you can put header with value payout_{your_payout_id}

Bodyapplication/jsonrequired
payment_token_idstring[ 1 .. 64 ] charactersrequired

Token from original payment

payment_methodstringrequired
merchant_payment_idstring[ 1 .. 64 ] characters

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

merchant_customer_idstring[ 1 .. 64 ] charactersrequired
emailstring[ 1 .. 320 ] charactersrequired
amountstring^\d{1,18}(?:\.\d{1,2})?$required

can't be zero for SALE | MIT_SALE

languagestring^[a-z]{2}-[a-z]{2}$

required only for SALE | AUTHORIZE | RECURRING

country_codestring^[A-Z]{2}$required

Country Code (ISO 3166-2)

currency_codestring^[A-Z]{3}$required

Currency code (ISO 4217)

success_urlstring(url)[ 1 .. 512 ] characters

required only for SALE | AUTHORIZE | RECURRING

failure_urlstring(url)[ 1 .. 512 ] characters

required only for SALE | AUTHORIZE | RECURRING

shop_namestring[ 1 .. 128 ] characters

Shop name

shop_urlstring[ 1 .. 128 ] characters

Shop URL with protocol HTTP or HTTPS

productsArray of product (object)[ 0 .. 10 ] itemsrequired

Expected at least 1 product

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

Product ID in Upgate env

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

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

products[].​product_pricestring^\d{1,18}(?:\.\d{1,2})?$required
products[].​product_transaction_pricestring^\d{1,18}(?:\.\d{1,2})?$
products[].​product_namestring[ 1 .. 256 ] charactersrequired
products[].​product_descriptionstring[ 1 .. 256 ] characters
products[].​product_typestringrequired
Value"SALE"
payment_form_overrideobject(paymentFormOverride)
curl -i -X POST \
  'https://api.sandbox.upgate.com/v1/mit-authorize?mode=SYNC' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -H 'X-Idempotency-Key: string' \
  -d '{
    "payment_method": "CARD",
    "merchant_payment_id": "P_001",
    "merchant_customer_id": "U_001",
    "amount": "9.99",
    "email": "john_doe@upgate.com",
    "currency_code": "USD",
    "country_code": "US",
    "payment_token_id": "+wjPh608B8r2B2b3bG8IxARp6c1LqojODr/d19/ZPUE=",
    "shop_name": "my shop",
    "shop_url": "https://shop.com",
    "products": [
      {
        "merchant_product_id": "R_001",
        "product_type": "SALE",
        "product_price": "9.99",
        "product_name": "Test product name",
        "product_description": "Test product description"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
One of:
object paymentResponse Recursive
Response
application/json
{
  "type": "PAYMENT",
  "data": {
    "payment_id": "2E2CL5R3KC7K3",
    "payment_type": "MIT_AUTHORIZE",
    "payment_method": "CARD",
    "created_at": "2022-04-15T10:54:03.633Z",
    "merchant_id": "UpGate",
    "merchant_payment_id": "P_001",
    "merchant_customer_id": "U_001",
    "email": "john_doe@upgate.com",
    "amount": "9.99",
    "country_code": "US",
    "currency_code": "USD",
    "payment_token_id": "+wjPh608B8r2B2b3bG8IxARp6c1LqojODr/d19/ZPUE=",
    "shop_name": "my shop",
    "shop_url": "https://shop.com",
    "products": [ … ]
  }
}

Callbacks

Transaction notification
post

CIT Sale request

Request

This endpoint allows you to create a subsequent transaction that triggers a 3-D Secure (3DS) authentication flow for your users. It can be used when you want customers to actively confirm and provide consent for the charge, ensuring additional security and compliance with authentication requirements. Similar to the standard subsequent transaction, this endpoint enables you to manage rebills on your end or offer one-click payments without requiring users to re-enter their card details. Use the payment token ID received from the original Sale request to initiate this transaction.

Security
X-Api-Key
Query
modestring
Default "ASYNC"
Enum"SYNC""ASYNC"
Headers
X-Idempotency-Keystring

The system supports the query deduplication mechanism. Any system-wide merchant's request after the first one with the same X-Idempotency-Key will return an error. For example, if you have retrying mechanism for payouts and you want to avoid double sending, you can put header with value payout_{your_payout_id}

Bodyapplication/jsonrequired
payment_token_idstring[ 1 .. 64 ] charactersrequired

Token from original payment

payment_methodstringrequired
merchant_payment_idstring[ 1 .. 64 ] characters

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

merchant_customer_idstring[ 1 .. 64 ] charactersrequired
emailstring[ 1 .. 320 ] charactersrequired
amountstring^\d{1,18}(?:\.\d{1,2})?$required

can't be zero for SALE | MIT_SALE

languagestring^[a-z]{2}-[a-z]{2}$

required only for SALE | AUTHORIZE | RECURRING

country_codestring^[A-Z]{2}$required

Country Code (ISO 3166-2)

currency_codestring^[A-Z]{3}$required

Currency code (ISO 4217)

forced_3dboolean

If needs to initiate 3d secure from merchant side.

Default false
success_urlstring(url)[ 1 .. 512 ] characters

required only for SALE | AUTHORIZE | RECURRING

failure_urlstring(url)[ 1 .. 512 ] characters

required only for SALE | AUTHORIZE | RECURRING

shop_namestring[ 1 .. 128 ] characters

Shop name

shop_urlstring[ 1 .. 128 ] characters

Shop URL with protocol HTTP or HTTPS

productsArray of product (object)[ 0 .. 10 ] itemsrequired

Expected at least 1 product

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

Product ID in Upgate env

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

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

products[].​product_pricestring^\d{1,18}(?:\.\d{1,2})?$required
products[].​product_transaction_pricestring^\d{1,18}(?:\.\d{1,2})?$
products[].​product_namestring[ 1 .. 256 ] charactersrequired
products[].​product_descriptionstring[ 1 .. 256 ] characters
products[].​product_typestringrequired
Value"SALE"
payment_form_overrideobject(paymentFormOverride)
curl -i -X POST \
  'https://api.sandbox.upgate.com/v1/cit-sale?mode=SYNC' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -H 'X-Idempotency-Key: string' \
  -d '{
    "payment_method": "CARD",
    "merchant_payment_id": "P_001",
    "merchant_customer_id": "U_001",
    "email": "john_doe@upgate.com",
    "amount": "9.99",
    "currency_code": "EUR",
    "country_code": "CY",
    "payment_token_id": "+wjPh608B8r2B2b3bG8IxARp6c1LqojODr/d19/ZPUE=",
    "forced_3d": true,
    "callback": {
      "success_url": "https://example.com/SUCCESS",
      "failure_url": "https://example.com/ERROR"
    },
    "products": [
      {
        "merchant_product_id": "R_001",
        "product_type": "SALE",
        "product_price": "9.99",
        "product_name": "Test product name",
        "product_description": "Test product description"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
One of:
object paymentResponse Recursive
Response
application/json
{
  "type": "PAYMENT",
  "data": {
    "payment_id": "32ROXKZQS6EK3",
    "payment_type": "SALE",
    "payment_method": "CARD",
    "created_at": "2025-06-16T11:21:57.979Z",
    "merchant_id": "UpGate",
    "merchant_payment_id": "P_001",
    "merchant_customer_id": "U_001",
    "email": "john_doe@upgate.com",
    "amount": "9.99",
    "country_code": "US",
    "base_amount": "9.46",
    "base_currency_code": "EUR",
    "currency_code": "USD",
    "payment_token_id": "+wjPh608B8r2B2b3bG8IxARp6c1LqojODr/d19/ZPUE=",
    "shop_name": "my shop",
    "shop_url": "https://shop.com",
    "products": [ … ],
    "transactions": null,
    "success_url": "https://example.com/SUCCESS",
    "failure_url": "https://example.com/ERROR",
    "session": { … }
  }
}

Callbacks

Transaction notification
post

Example

Operations

Example

Operations

Google Payâ„¢

Override theme

Other request examples

Operations

Embedded flow

Use cases