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

MIT Sale request

Request

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 productSale (object) or productSubscription (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)

Customizing Payment Form Appearance. All these parameters will override existing configuration in Upgate back office if any

curl -i -X POST \
  'https://docs.upgate.com/_mock/openapi/mit-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",
    "amount": "9.99",
    "currency_code": "USD",
    "email": "john_doe@upgate.com",
    "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:
typestringrequired
Value"PAYMENT"
dataobject(payment)required
data.​payment_idstring[ 1 .. 64 ] charactersrequired
data.​initial_subscription_idstring[ 1 .. 64 ] characters
data.​payment_typestringrequired
Enum"SALE""AUTHORIZE""MIT_SALE""MIT_AUTHORIZE""RECURRING"
data.​payment_methodstringrequired
data.​created_atstring[ 1 .. 64 ] charactersrequired

UTC date time format

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

Country Code (ISO 3166-2)

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

Currency code (ISO 4217)

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

Currency code (ISO 4217)

data.​forced_3dboolean

If needs to initiate 3d secure from merchant side

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

required only for SALE | AUTHORIZE | RECURRING

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

required only for SALE | AUTHORIZE | RECURRING

data.​payment_token_idstring[ 1 .. 64 ] characters

Token from original payment. Used for MIT_SALE | MIT_AUTHORIZE

data.​shop_namestring[ 1 .. 128 ] characters

Shop name

data.​shop_urlstring[ 1 .. 128 ] characters

Shop URL with protocol HTTP or HTTPS

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

Expected at least 1 product

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

Product ID in Upgate env

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

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

data.​products[].​product_pricestring^\d{1,18}(?:\.\d{1,2})?$required
data.​products[].​product_transaction_pricestring^\d{1,18}(?:\.\d{1,2})?$
data.​products[].​product_namestring[ 1 .. 256 ] charactersrequired
data.​products[].​product_descriptionstring[ 1 .. 256 ] characters
data.​products[].​product_typestringrequired
Value"SALE"
Response
application/json
{
  "type": "PAYMENT",
  "data": {
    "payment_id": "2E2CL5R3KC7K3",
    "payment_type": "MIT_SALE",
    "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",
    "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": [ … ]
  }
}

Callbacks

Transaction notification
post

MIT Authorize request

Request

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 productSale (object) or productSubscription (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)

Customizing Payment Form Appearance. All these parameters will override existing configuration in Upgate back office if any

curl -i -X POST \
  'https://docs.upgate.com/_mock/openapi/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:
typestringrequired
Value"PAYMENT"
dataobject(payment)required
data.​payment_idstring[ 1 .. 64 ] charactersrequired
data.​initial_subscription_idstring[ 1 .. 64 ] characters
data.​payment_typestringrequired
Enum"SALE""AUTHORIZE""MIT_SALE""MIT_AUTHORIZE""RECURRING"
data.​payment_methodstringrequired
data.​created_atstring[ 1 .. 64 ] charactersrequired

UTC date time format

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

Country Code (ISO 3166-2)

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

Currency code (ISO 4217)

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

Currency code (ISO 4217)

data.​forced_3dboolean

If needs to initiate 3d secure from merchant side

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

required only for SALE | AUTHORIZE | RECURRING

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

required only for SALE | AUTHORIZE | RECURRING

data.​payment_token_idstring[ 1 .. 64 ] characters

Token from original payment. Used for MIT_SALE | MIT_AUTHORIZE

data.​shop_namestring[ 1 .. 128 ] characters

Shop name

data.​shop_urlstring[ 1 .. 128 ] characters

Shop URL with protocol HTTP or HTTPS

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

Expected at least 1 product

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

Product ID in Upgate env

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

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

data.​products[].​product_pricestring^\d{1,18}(?:\.\d{1,2})?$required
data.​products[].​product_transaction_pricestring^\d{1,18}(?:\.\d{1,2})?$
data.​products[].​product_namestring[ 1 .. 256 ] charactersrequired
data.​products[].​product_descriptionstring[ 1 .. 256 ] characters
data.​products[].​product_typestringrequired
Value"SALE"
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

Recurring transaction

Request

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_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 productSale (object) or productSubscription (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)

Customizing Payment Form Appearance. All these parameters will override existing configuration in Upgate back office if any

curl -i -X POST \
  https://docs.upgate.com/_mock/openapi/recurring \
  -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",
    "currency_code": "USD",
    "email": "john_doe@upgate.com",
    "language": "en-us",
    "country_code": "US",
    "forced_3d": false,
    "success_url": "https://example.com/success",
    "failure_url": "https://example.com/failure",
    "shop_name": "my shop",
    "shop_url": "https://shop.com",
    "products": [
      {
        "merchant_product_id": "R_001",
        "product_type": "SUBSCRIPTION",
        "product_price": "9.99",
        "product_name": "Test product name",
        "product_description": "Test product description",
        "charge_interval": "DAY",
        "charge_interval_value": 30,
        "is_trial": false
      }
    ]
  }'

Responses

OK

Bodyapplication/json
typestringrequired
Value"PAYMENT"
dataobject(payment)required
data.​payment_idstring[ 1 .. 64 ] charactersrequired
data.​initial_subscription_idstring[ 1 .. 64 ] characters
data.​payment_typestringrequired
Enum"SALE""AUTHORIZE""MIT_SALE""MIT_AUTHORIZE""RECURRING"
data.​payment_methodstringrequired
data.​created_atstring[ 1 .. 64 ] charactersrequired

UTC date time format

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

Country Code (ISO 3166-2)

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

Currency code (ISO 4217)

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

Currency code (ISO 4217)

data.​forced_3dboolean

If needs to initiate 3d secure from merchant side

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

required only for SALE | AUTHORIZE | RECURRING

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

required only for SALE | AUTHORIZE | RECURRING

data.​payment_token_idstring[ 1 .. 64 ] characters

Token from original payment. Used for MIT_SALE | MIT_AUTHORIZE

data.​shop_namestring[ 1 .. 128 ] characters

Shop name

data.​shop_urlstring[ 1 .. 128 ] characters

Shop URL with protocol HTTP or HTTPS

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

Expected at least 1 product

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

Product ID in Upgate env

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

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

data.​products[].​product_pricestring^\d{1,18}(?:\.\d{1,2})?$required
data.​products[].​product_transaction_pricestring^\d{1,18}(?:\.\d{1,2})?$
data.​products[].​product_namestring[ 1 .. 256 ] charactersrequired
data.​products[].​product_descriptionstring[ 1 .. 256 ] characters
data.​products[].​product_typestringrequired
Value"SALE"
Response
application/json
{
  "type": "PAYMENT",
  "data": {
    "payment_id": "2JWYCAOYS67K2",
    "payment_type": "RECURRING",
    "payment_method": "CARD",
    "created_at": "2023-03-02T14:51:50.779Z",
    "merchant_id": "UpGate",
    "merchant_payment_id": "P_001",
    "merchant_customer_id": "U_001",
    "amount": "9.99",
    "currency_code": "USD",
    "base_amount": "9.46",
    "base_currency_code": "EUR",
    "email": "john_doe@upgate.com",
    "language": "en-us",
    "country_code": "US",
    "forced_3d": true,
    "success_url": "https://example.com/success",
    "failure_url": "https://example.com/failure",
    "shop_name": "my shop",
    "shop_url": "https://shop.com",
    "session": { … },
    "products": [ … ]
  }
}

Callbacks

Transaction notification
post
Notifications about new subscriptions
post

Embedded flow