Powered by Redocly

UpGate API documentation (v1.2)

Download OpenAPI specification:Download

License: UpGate LTD

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.

Changelog

[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

Merchant callback URL

URL for callback's (postback's) should be set with the merchant account (during the registration) & can be updated in any time using admin panel

Domains

environment domain
Sandbox api.sandbox.upgate.com
Prod api.upgate.com

Postback IP addresses

production sandbox
18.195.228.88 35.159.56.107
3.68.255.126 18.153.214.226
3.127.95.240 18.194.246.210
18.198.146.231 52.28.150.254

Constants

Transaction status

status description
SUCCESS Transaction completed success
DECLINE Transaction declined by some reason
ERROR Some error were produced during the process

Transaction type

status
SALE
AUTHORIZE
THREE_DS
TOKEN
PAYOUT
REFUND
VOID
FRAUD_ALERT
CHARGEBACK
CHARGEBACK_REVERSAL

Response Codes

code message
1000 Success
1200 Pending
1300 3DS verification successful (challenged)
1301 3DS verification successful (frictionless)
1302 3DS verification attempted
1320 3DS verification denied
1321 3DS could not be performed
1322 3DS rejected by issuer
1323 3DS invalid cardholder account number
1324 3DS version not supported
1325 3DS timeout
1390 3DS integration error
1400 3DS is required
2000 Decline
2001 Refer to card issuer
2002 Do not honor
2003 Bank decline
2004 Insufficient funds
2005 Card not supported
2006 Restricted card
2007 Over limit
2008 Merchant limit exceeded
2009 Invalid transaction
2010 Duplicate transaction
2011 transaction has already chargeback
2012 Crypto transaction decline
2013 Crypto insufficient funds
2014 Crypto smart contract insufficient funds
2015 Crypto transaction replaced
2101 Invalid CVV or expiry date
2102 CVV missing
2103 Invalid expiry date
2130 3DS verification denied
2131 3DS could not be performed
2132 3DS rejected by issuer
2133 3DS timeout
2138 3DS SCA required
2139 3DS integration error
2140 Low value rejected
2141 Incorrect card data
2142 Incorrect data
2143 Missing parameters
2144 3DS version not supported
2200 Pick up card
2201 Pick up card (stolen or fraud)
2202 Expired card
2203 Unsupported card type
2204 No such issuer
2205 Decline by Card Scheme Advise Code
2299 Closed account
2300 Processor risk
2301 Velocity limit exceeded
2302 Suspected Fraud
2309 Customer blacklisted
2310 Card blacklisted
2311 IP blacklist
2312 Email blacklist
2313 BIN blacklist
2314 Country blacklist
2315 Fraud rule
2900 System malfunction
2901 Integration error
2902 Processor not supported feature
2903 Processor malfunction
2904 Timeout
2905 Refund is not supported for this method or transaction type
2906 Missing payment token
2907 Payment type not supported for payment method
3000 Unknown error

Card flow

Supported Payment methods

name
CARD
APPLE_PAY
GOOGLE_PAY

Supported card schemes

name
VISA
Mastercard
Maestro
Discover
Diners
UnionPay
RuPay
American Express
JCB

Process diagram

Alternative payment methods (APM)

Support payment methods

name
AIRCASH
ALIPAY
ALIPAY_PLUS
BANK_APP
BINANCE_PAY
BLIK
CARDEXTERNAL
CODI
CRYPTO
EPS
GIROPAY
IDEAL
INSTANT_BANK_TRANSFER
KAKAO_PAY
MBWAY
MPESA
MULTIBANCO
MYBANK
NUPAY
PAGOEFECTIVO
PAYCONIQ
PAYPAL
PIX
PSE
SATISPAY
SOFORT
SPEI
UPI
WECHAT

Process diagram

Demo payment page

Checkout Overview

Example

Sale request

SecurityX-Api-Key
Request
header Parameters
X-Idempotency-Key
string

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}

Request Body schema: application/json
required
required
Payment data (object) or Payment data embedded (object)
required
object
required
object

Specifies the URLs to which the customer will be redirected after completing a payment transaction. The success_url is used for redirection upon successful payment, and the failure_url is used in case of payment failure.

required
Array of objects (checkoutProduct)
object
object (paymentFormOverride)

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

Responses
200

OK

400

Request validation error

401

Authorization error

429

Too many requests error

500

Internal server error

Callbacks
postCheckout notification
post/checkout
Request samples
application/json
{
  • "payment_data": {
    },
  • "customer": {
    },
  • "callback": {},
  • "products": [
    ]
}
Response samples
application/json
{
  • "id": "2E2CL5R3KC7K3",
  • "created_at": "2022-04-15T10:54:03.633Z",
  • "merchant_id": "upgatetests",
  • "payment_data": {
    },
  • "customer": {
    },
  • "callback": {},
  • "products": [
    ],
  • "session": {}
}
Callback payload samples
POST: Checkout notification
application/json
{
  • "type": "TRANSACTION",
  • "data": {
    }
}

Examples

Subscription request

SecurityX-Api-Key
Request
header Parameters
X-Idempotency-Key
string

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}

Request Body schema: application/json
required
required
object (subscriptionPaymentData)
required
object
required
object

Specifies the URLs to which the customer will be redirected after completing a payment transaction. The success_url is used for redirection upon successful payment, and the failure_url is used in case of payment failure.

required
Array of objects (subscriptionProduct)
object
object (paymentFormOverride)

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

Responses
200

OK

400

Request validation error

401

Authorization error

429

Too many requests error

500

Internal server error

Callbacks
postCheckout notification
post/checkout
Request samples
application/json
{
  • "value": {
    }
}
Response samples
application/json
{
  • "id": "2E2CL5R3KC7K3",
  • "created_at": "2022-04-15T10:54:03.633Z",
  • "merchant_id": "upgatetests",
  • "payment_data": {
    },
  • "customer": {
    },
  • "callback": {},
  • "products": [
    ],
  • "session": {}
}
Callback payload samples
POST: Checkout notification
application/json
{
  • "type": "TRANSACTION",
  • "data": {
    }
}

Update subscription by merchant product id

SecurityX-Api-Key
Request
query Parameters
merchant_product_id
required
string
Example: merchant_product_id=2JZGULPNK27K2
header Parameters
X-Idempotency-Key
string

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}

Request Body schema: application/json
required
is_rebill_enabled
required
boolean
Responses
200

OK

400

Request validation error

401

Authorization error

500

Internal server error

patch/subscription
Request samples
application/json
{
  • "is_rebill_enabled": true
}
Response samples
application/json
{
  • "type": "SUBSCRIPTION",
  • "data": {
    }
}

Get subscription by transaction ID

SecurityX-Api-Key
Request
query Parameters
transaction_id
string
Example: transaction_id=2U5T2MIX22EK3
page
integer <int32> >= 1
Default: 1
Example: page=1
size
integer <int32> [ 1 .. 100 ]
Default: 100
Example: size=100
Responses
200

OK

401

Authorization error

500

Internal server error

get/subscription
Request samples 
Response samples 
application/json
{
  • "type": "SUBSCRIPTION",
  • "data": [
    ],
  • "meta": {
    }
}
Get subscription by subscription id
SecurityX-Api-Key 
Request 
path Parameters
subscriptionId
required
string
 
 Example:  2E2CL5R3KC7K3
Responses 
200
OK


401
Authorization error


404
Not found


500
Internal server error


get/subscription/{subscriptionId}
Request samples 
Response samples 
application/json
{
  • "type": "SUBSCRIPTION",
  • "data": {
    }
}
Update subscription by subscription id
SecurityX-Api-Key 
Request 
path Parameters
subscriptionId
required
string
 
 Example:  2E2CL5R3KC7K3
header Parameters
X-Idempotency-Key
string
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}


 
Request Body schema: application/json
required
is_rebill_enabled
required
boolean
 
Responses 
200
OK


400
Request validation error


401
Authorization error


500
Internal server error


Callbacks 
postNotifications about new subscriptions
patch/subscription/{subscriptionId}
Request samples 
application/json
{
  • "is_rebill_enabled": true
}
Response samples 
application/json
{
  • "type": "SUBSCRIPTION",
  • "data": {
    }
}
Callback payload samples 
POST: Notifications about new subscriptions
application/json
{
  • "type": "SUBSCRIPTION",
  • "data": {
    }
}
Google Pay™
Overview the Google Pay™
Google Pay™ is a convenient and secure payment method that allows your customers to quickly and easily make purchases on your website.


To integrate Google Pay™  into Checkout form, we follow the guidelines specified in Google Pay Android brand guidelines or Google Pay Web brand guidelines.


Setup the Google Pay™
To setup Google Pay™ into your website, follow these steps:


    

  1. Include the Google Pay™ method in the request as the payment method
    2. 



{
  "payment_data": {
    "merchant_payment_id": "P_001",
    "methods": ["CARD", "GOOGLE_PAY"],
    "type": "SALE",
    "amount": 9.99,
    "currency_code": "EUR"
  },
  "customer": {
    "merchant_customer_id": "U_001"
  },
  "callback": {
    "success_url": "https://example.com/success",
    "failure_url": "https://example.com/failure"
  },
  "products": [
    {
      "type": "SALE",
      "name": "Test product name",
      "description": "Test product description",
      "price": 9.99
    }
  ]
}



    

  1. Configure Transaction Routing for Google Pay™ method, specify card schemes, currency and processor
    

    2. 

  2. Add information to your site that you support the Google Pay™ payment method and that you accept the terms defined in the Google Pay API Terms of Service.
    

    3. 



Additional Guidelines and Requirements
Understand Google Pay Integration:



Integration Checklist for Web:



Brand Guidelines:



Configure Gateway Settings:


    

  • Use the "upgate" value for the gateway property and enter your unique gatewayMerchantId. To obtain your gatewayMerchantId, contact our team at info@upgate.com. If you would like to use your own Google merchant id, you need to register for a merchant id at Google, refer to setup Google Account guide and send it to you team at info@upgate.com.
    • 



Billing Address Requirements:


    

  • The customer billing address does not need to be sent if you use the UpGate Checkout page.
    • 



Accepted Payment Card Types:



Supported Card Networks:


    

  • Depending on the processor, the international card networks Visa, MasterCard, Diners and American Express are supported.
    • 



3DS Authentication:


    

  • Google Pay integration via the UpGate Checkout page supports processing with and without 3DS authentication. To use 3DS, enable 3DS for "PAN_ONLY" and contact our team at info@upgate.com.
    • 



Authorization Methods by Country of Settlement:


    

  • Default authorization methods are PAN_ONLY and 3DS (3-D Secure). For specific country requirements, contact our team at info@upgate.com.
    • 



Override theme
Customizing Payment Form Appearance
The payment form offers visual customization options, enabling you to align its design with your website’s style. While the overall layout of each form remains consistent, you can adjust elements like colors, fonts, borders, padding, and more.


    

  1. Begin by selecting a theme.
    2. 

  2. Adjust the theme using customizable variables.
    3. 

  3. If necessary, refine specific components and states through theme rules.
    4. 



In a checkout request, you can override the payment form settings configured in the back office by defining the payment_form_override object.


    

  • color: This property allows you to define payment button color.
    • 

  • theme_type: This property allows you to define theme.
    • 

  • theme_variables: This property enables you to override specific CSS variables to define custom styles for the payment form.
    • 

  • theme_rules: This property allows you to define additional custom CSS rules to further tailor the design.
    • 



Themes
Begin customizing the payment form by selecting one of the available themes below:


    

  • LIGHT
    • 

  • DARK
    • 

  • BROWSER
    • 



Note: BROWSER theme it's a automatically switch theme between LIGHT and DARK depends of system OS color scheme.


Variables
The theme_variables property is used to override default CSS variables of the payment form. This allows you to quickly and easily customize specific aspects of the design. The variables option functions similarly to CSS variables. You can assign CSS values to each variable and reference them using the var(--myVariable) syntax. Additionally, you can use your browser’s DOM explorer to inspect the applied styles in the resulting DOM.


Commonly used variables






Variable
Description





primaryColor
Defines the primary color used across the application.




backgroundColor
Background color of the component.




formBackground
Background color of the form.




fontSizeBase
Base font size.




fontFamily
Font family used across the application.




loaderColor
Color for loader.





Rest Variables






Variable
Description





maxWidth
Maximum width of the container or component.




primaryColorHover
Primary color when hovered.




primaryColorActive
Primary color when active.




payBtnColor
Color of the payment button.




payBtnColorDisabled
Color of the payment button when disabled.




payBtnFontSize
Font size for the payment button.




payBtnLineHeight
Line height for the payment button.




payBtnPadding
Padding for the payment button.




textColor
Default color for text.




formBorderColor
Border color for forms.




formPadding
Padding inside forms.




formBorderRadius
Border radius for forms.




m_formPadding
Mobile-specific padding for forms.




inputBackground
Background color for input fields.




inputBorderColor
Border color for input fields.




inputBorderColorHover
Border color for input fields when hovered.




inputBorderColorFocus
Border color for input fields when focused.




inputBorderColorError
Border color for input fields in error state.




inputBorderWidth
Border width for input fields.




inputBorderWidthHover
Border width for input fields when hovered.




inputBorderWidthFocus
Border width for input fields when focused.




inputBorderWidthError
Border width for input fields in error state.




borderRadius
Border radius applied across components.




inputPadding
Padding for input fields.




inputFontSize
Font size for input fields.




inputLineHeight
Line height for input fields.




inputFontWeight
Font weight for input fields.




placeHolderColor
Color for placeholder text in input fields.




cardBackground
Background color for cards.




cardBorderColor
Border color for cards.




cardBorderRadius
Border radius for cards.




cardPadding
Padding for cards.




cardSelectColorSelected
Color of selected card during selection.




inputIconColor
Color of icons inside input fields.




descriptionColor
Color for descriptive text.




dividerColor
Color of dividers or separators.




fontSizeXl
Font size for extra-large text.




fontSizeLg
Font size for large text.




fontSizeSm
Font size for small text.




fontSizeXs
Font size for extra-small text.




fontSize2Xs
Font size for ultra-small text.




lineHeight
Line height for text.




fontCss
Custom CSS applied to fonts.




lineHeightXl
Line height for extra-large text.




lineHeightLg
Line height for large text.




fontWeight
General font weight for text.




buttonPadding
Padding for buttons.




buttonFontWeight
Font weight for button text.




buttonBackground
Background color for buttons.




buttonFontSize
Font size for buttons.




buttonLineHeight
Line height for button text.




buttonColor
Text color for buttons.




buttonBackgroundHover
Background color for buttons when hovered.




buttonColorHover
Text color for buttons when hovered.




buttonBackgroundActive
Background color for buttons when active.




buttonColorActive
Text color for buttons when active.




linkColor
Color for hyperlinks.




fontWeightLight
Font weight for lighter text styles.




fontWeightMedium
Font weight for medium text styles.




fontWeightBold
Font weight for bold text styles.




labelFontSize
Font size for labels.




labelLineHeight
Line height for labels.




labelFontWeight
Font weight for labels.




labelColor
Color for labels.




errorColor
Color for error messages or indicators.




selectBackgroundHover
Background color for select elements when hovered.




selectBackgroundActive
Background color for select elements when active.




cardSelectDeleteColor
Color for delete option in card selection.




transitionDuration
Duration for transition effects.




transitionStyle
Style for transition effects.




buttonOutlineColor
Outline color for buttons.




buttonOutlineBorderColor
Border color for button outlines.




buttonOutlineBorderWidth
Border width for button outlines.




buttonOutlineBackgroundHover
Background color for outlined buttons when hovered.




buttonOutlineBackgroundActive
Background color for outlined buttons when active.




tabBorderRadius
Border radius for tabs.




tabPadding
Padding for tabs.




tabHeight
Height for tabs.




tabColor
Text color for tabs.




tabBackground
Background color for tabs.




tabBorderColor
Border color for tabs.




tabBorderColorActive
Border color for tabs when active.




tabBackgroundActive
Background color for tabs when active.




tabColorSelected
Text color for selected tabs.




tabBackgroundSelected
Background color for selected tabs.




tabBorderColorSelected
Border color for selected tabs.




tabBorderColorHover
Border color for tabs when hovered.




tabBackgroundHover
Background color for tabs when hovered.




tabBorderWidth
Border width for tabs.




tabBorderWidthHover
Border width for tabs when hovered.




tabBorderWidthActive
Border width for tabs when active.




tabBorderWidthSelected
Border width for selected tabs.




tabFontWeight
Font weight for tabs.




tabFontWeightSelected
Font weight for selected tabs.




languageSelectColor
Color for language selection dropdown.




subscriptionColor
Color used for subscription-related text or buttons.




subscriptionFontSize
Font size for subscription-related text.




subscriptionLineHeight
Line height for subscription-related text.




subscriptionFontWeight
Font weight for subscription-related text.




buttonColorDisabled
Text color for disabled buttons.




buttonBackgroundDisabled
Background color for disabled buttons.




footerColor
Color of text in the footer.




footerIconColor
Color of icons in the footer.




footerFontWeight
Font weight for text in the footer.




footerFontSize
Font size for text in the footer.




footerLineHeight
Line height for text in the footer.




footerPadding
Padding for the footer.




m_footerPadding
Mobile-specific padding for the footer.




badgeFontSize
Font size for badges.




badgeBackground
Background color for badges.




badgeColor
Text color for badges.




methodIconWidth
Width for payment method icons.




methodIconHeight
Height for payment method icons.




iconSize
General size for icons.




searchInputBackground
Background color for search inputs.




searchInputBackgroundHover
Background color for search inputs when hovered.




messageInfoColor
Text color for informational messages.




messageInfoBorderColor
Border color for informational messages.




messageInfoBackground
Background color for informational messages.




messageErrorColor
Text color for error messages.




messageErrorBorderColor
Border color for error messages.




messageErrorBackground
Background color for error messages.





Rules
The theme_rules option is a mapping of CSS-like selectors to CSS properties, enabling precise customization of individual components. Once you’ve defined your theme and variables, you can use these rules to seamlessly align the payment form with your website’s design.


Selectors in a rule can target any public class names within the payment form, as well as supported states, pseudo-classes, and pseudo-elements associated with each class.  For example, the following are valid selectors: .form-control > input


Other request examples
Authorize request (deprecated)
SecurityX-Api-Key 
Request 
header Parameters
X-Idempotency-Key
string
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}


 
Request Body schema: application/json
required
payment_method
required
string
 
merchant_payment_id
string  [ 1 .. 64 ] characters 
Optional field, might be used as a reference from the merchant side


 
merchant_customer_id
required
string  [ 1 .. 64 ] characters 
 
email
required
string  [ 1 .. 320 ] characters 
 
amount
required
string^\d{1,18}(?:\.\d{1,2})?$
can't be zero for SALE | MIT_SALE


 
language
string^[a-z]{2}-[a-z]{2}$
required only for SALE | AUTHORIZE | RECURRING


 
country_code
required
string^[A-Z]{2}$
Country Code (ISO 3166-2)


 
currency_code
required
string^[A-Z]{3}$
Currency code (ISO 4217)


 
forced_3d
boolean
 Default:  false
If needs to initiate 3d secure from merchant side.


 
success_url
string <url>   [ 1 .. 512 ] characters 
required only for SALE | AUTHORIZE | RECURRING


 
failure_url
string <url>   [ 1 .. 512 ] characters 
required only for SALE | AUTHORIZE | RECURRING


 
shop_name
string  [ 1 .. 128 ] characters 
Shop name


 
shop_url
string  [ 1 .. 128 ] characters 
Shop URL with protocol HTTP or HTTPS


 
required
Array of productSale (object) or productSubscription (object)  [ 0 .. 10 ] items 
Expected at least 1 product


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


 
Responses 
200
OK


400
Request validation error


401
Authorization error


429
Too many requests error


500
Internal server error


Callbacks 
postTransaction notification
post/authorize
Request samples 
application/json
{
  • "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": true,
  • "success_url": "https://example.com/success",
  • "failure_url": "https://example.com/failure",
  • "shop_name": "my shop",
  • "shop_url": "https://shop.com",
  • "products": [
    ]
}
Response samples 
application/json
{
  • "type": "PAYMENT",
  • "data": {
    }
}
Callback payload samples 
POST: Transaction notification
application/json
{
  • "type": "TRANSACTION",
  • "data": {
    }
}
MIT Sale request
SecurityX-Api-Key 
Request 
query Parameters
mode
string
 Default:  "ASYNC"
 Enum: "SYNC" "ASYNC"  
header Parameters
X-Idempotency-Key
string
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}


 
Request Body schema: application/json
required
payment_token_id
required
string  [ 1 .. 64 ] characters 
Token from original payment


 
payment_method
required
string
 
merchant_payment_id
string  [ 1 .. 64 ] characters 
Optional field, might be used as a reference from the merchant side


 
merchant_customer_id
required
string  [ 1 .. 64 ] characters 
 
email
required
string  [ 1 .. 320 ] characters 
 
amount
required
string^\d{1,18}(?:\.\d{1,2})?$
can't be zero for SALE | MIT_SALE


 
language
string^[a-z]{2}-[a-z]{2}$
required only for SALE | AUTHORIZE | RECURRING


 
country_code
required
string^[A-Z]{2}$
Country Code (ISO 3166-2)


 
currency_code
required
string^[A-Z]{3}$
Currency code (ISO 4217)


 
forced_3d
boolean
 Default:  false
If needs to initiate 3d secure from merchant side.


 
success_url
string <url>   [ 1 .. 512 ] characters 
required only for SALE | AUTHORIZE | RECURRING


 
failure_url
string <url>   [ 1 .. 512 ] characters 
required only for SALE | AUTHORIZE | RECURRING


 
shop_name
string  [ 1 .. 128 ] characters 
Shop name


 
shop_url
string  [ 1 .. 128 ] characters 
Shop URL with protocol HTTP or HTTPS


 
required
Array of productSale (object) or productSubscription (object)  [ 0 .. 10 ] items 
Expected at least 1 product


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


 
Responses 
200
OK


400
Request validation error


401
Authorization error


429
Too many requests error


500
Internal server error


Callbacks 
postTransaction notification
post/mit-sale
Request samples 
application/json
{
  • "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": [
    ]
}
Response samples 
application/json
{
  • "type": "PAYMENT",
  • "data": {
    }
}
Callback payload samples 
POST: Transaction notification
application/json
{
  • "type": "TRANSACTION",
  • "data": {
    }
}
MIT Authorize request
SecurityX-Api-Key 
Request 
query Parameters
mode
string
 Default:  "ASYNC"
 Enum: "SYNC" "ASYNC"  
header Parameters
X-Idempotency-Key
string
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}


 
Request Body schema: application/json
required
payment_token_id
required
string  [ 1 .. 64 ] characters 
Token from original payment


 
payment_method
required
string
 
merchant_payment_id
string  [ 1 .. 64 ] characters 
Optional field, might be used as a reference from the merchant side


 
merchant_customer_id
required
string  [ 1 .. 64 ] characters 
 
email
required
string  [ 1 .. 320 ] characters 
 
amount
required
string^\d{1,18}(?:\.\d{1,2})?$
can't be zero for SALE | MIT_SALE


 
language
string^[a-z]{2}-[a-z]{2}$
required only for SALE | AUTHORIZE | RECURRING


 
country_code
required
string^[A-Z]{2}$
Country Code (ISO 3166-2)


 
currency_code
required
string^[A-Z]{3}$
Currency code (ISO 4217)


 
forced_3d
boolean
 Default:  false
If needs to initiate 3d secure from merchant side.


 
success_url
string <url>   [ 1 .. 512 ] characters 
required only for SALE | AUTHORIZE | RECURRING


 
failure_url
string <url>   [ 1 .. 512 ] characters 
required only for SALE | AUTHORIZE | RECURRING


 
shop_name
string  [ 1 .. 128 ] characters 
Shop name


 
shop_url
string  [ 1 .. 128 ] characters 
Shop URL with protocol HTTP or HTTPS


 
required
Array of productSale (object) or productSubscription (object)  [ 0 .. 10 ] items 
Expected at least 1 product


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


 
Responses 
200
OK


400
Request validation error


401
Authorization error


429
Too many requests error


500
Internal server error


Callbacks 
postTransaction notification
post/mit-authorize
Request samples 
application/json
{
  • "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": [
    ]
}
Response samples 
application/json
{
  • "type": "PAYMENT",
  • "data": {
    }
}
Callback payload samples 
POST: Transaction notification
application/json
{
  • "type": "TRANSACTION",
  • "data": {
    }
}
Recurring transaction
SecurityX-Api-Key 
Request 
header Parameters
X-Idempotency-Key
string
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}


 
Request Body schema: application/json
required
payment_method
required
string
 
merchant_payment_id
string  [ 1 .. 64 ] characters 
Optional field, might be used as a reference from the merchant side


 
merchant_customer_id
required
string  [ 1 .. 64 ] characters 
 
email
required
string  [ 1 .. 320 ] characters 
 
amount
required
string^\d{1,18}(?:\.\d{1,2})?$
can't be zero for SALE | MIT_SALE


 
language
string^[a-z]{2}-[a-z]{2}$
required only for SALE | AUTHORIZE | RECURRING


 
country_code
required
string^[A-Z]{2}$
Country Code (ISO 3166-2)


 
currency_code
required
string^[A-Z]{3}$
Currency code (ISO 4217)


 
forced_3d
boolean
 Default:  false
If needs to initiate 3d secure from merchant side.


 
success_url
string <url>   [ 1 .. 512 ] characters 
required only for SALE | AUTHORIZE | RECURRING


 
failure_url
string <url>   [ 1 .. 512 ] characters 
required only for SALE | AUTHORIZE | RECURRING


 
shop_name
string  [ 1 .. 128 ] characters 
Shop name


 
shop_url
string  [ 1 .. 128 ] characters 
Shop URL with protocol HTTP or HTTPS


 
required
Array of productSale (object) or productSubscription (object)  [ 0 .. 10 ] items 
Expected at least 1 product


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


 
Responses 
200
OK


400
Request validation error


401
Authorization error


429
Too many requests error


500
Internal server error


Callbacks 
postTransaction notification
postNotifications about new subscriptions
post/recurring
Request samples 
application/json
{
  • "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": [
    ]
}
Response samples 
application/json
{
  • "type": "PAYMENT",
  • "data": {
    }
}
Callback payload samples 
application/json
{
  • "type": "TRANSACTION",
  • "data": {
    }
}
Token request
Request to create token


SecurityX-Api-Key 
Request 
Request Body schema: application/json
required
payment_method
required
string
 Value: "CARD"  
merchant_payment_id
string  [ 1 .. 64 ] characters 
Optional field, might be used as a reference from the merchant side


 
merchant_customer_id
required
string  [ 1 .. 64 ] characters 
 
email
required
string  [ 1 .. 320 ] characters 
 
language
required
string^[a-z]{2}-[a-z]{2}$
 
country_code
required
string^[A-Z]{2}$
Country Code (ISO 3166-2)


 
success_url
required
string <url>   [ 1 .. 2048 ] characters 
 
failure_url
required
string <url>   [ 1 .. 2048 ] characters 
 
prefilled_card_holder
string  [ 1 .. 64 ] characters 
Card holder name to show on payment form


 
Responses 
200
OK


400
Request validation error


401
Authorization error


429
Too many requests error


500
Internal server error


Callbacks 
postTransaction notification
post/token
Request samples 
application/json
{
  • "payment_method": "CARD",
  • "merchant_payment_id": "P_001",
  • "merchant_customer_id": "U_001",
  • "email": "john_doe@upgate.com",
  • "language": "en-us",
  • "country_code": "US",
  • "prefilled_card_holder": "John Doe",
  • "success_url": "https://example.com/success",
  • "failure_url": "https://example.com/failure"
}
Response samples 
application/json
{
  • "type": "PAYMENT",
  • "data": {
    }
}
Callback payload samples 
POST: Transaction notification
application/json
{
  • "type": "TRANSACTION",
  • "data": {
    }
}
Payout request
SecurityX-Api-Key 
Request 
header Parameters
X-Idempotency-Key
string
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}


 
Request Body schema: application/json
required
payment_method
required
string (payoutPaymentMethod) 
 Enum: "CARD" "CRYPTO" "SEPA" "PAXUM"  
merchant_payment_id
required
string  [ 1 .. 64 ] characters 
Field, might be uniq for every request (deduplication check)


 
merchant_customer_id
required
string  [ 1 .. 64 ] characters 
 
amount
required
string^\d{1,18}(?:\.\d{0,20})?$
 
currency_code
required
string^[A-Z]{3}$
Currency code (ISO 4217)


 
required
Card payment details (object) or Crypto payment details (object) or Sepa payment details (object) or Paxum payment details (object)
 
description
string  [ 1 .. 256 ] characters 
 
Responses 
200
OK


400
Request validation error


401
Authorization error


500
Internal server error


Callbacks 
postTransaction notification
post/payout
Request samples 
application/json
{
  • "payment_method": "CARD",
  • "merchant_payment_id": "P_001",
  • "merchant_customer_id": "U_001",
  • "amount": "9.99",
  • "currency_code": "USD",
  • "payment_details": {
    }
}
Response samples 
application/json
{
  • "type": "PAYMENT",
  • "data": {
    }
}
Callback payload samples 
POST: Transaction notification
application/json
{
  • "type": "TRANSACTION",
  • "data": {
    }
}
Sale request (deprecated)
SecurityX-Api-Key 
Request 
header Parameters
X-Idempotency-Key
string
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}


 
Request Body schema: application/json
required
payment_method
required
string
 
merchant_payment_id
string  [ 1 .. 64 ] characters 
Optional field, might be used as a reference from the merchant side


 
merchant_customer_id
required
string  [ 1 .. 64 ] characters 
 
email
required
string  [ 1 .. 320 ] characters 
 
amount
required
string^\d{1,18}(?:\.\d{1,2})?$
can't be zero for SALE | MIT_SALE


 
language
string^[a-z]{2}-[a-z]{2}$
required only for SALE | AUTHORIZE | RECURRING


 
country_code
required
string^[A-Z]{2}$
Country Code (ISO 3166-2)


 
currency_code
required
string^[A-Z]{3}$
Currency code (ISO 4217)


 
forced_3d
boolean
 Default:  false
If needs to initiate 3d secure from merchant side.


 
success_url
string <url>   [ 1 .. 512 ] characters 
required only for SALE | AUTHORIZE | RECURRING


 
failure_url
string <url>   [ 1 .. 512 ] characters 
required only for SALE | AUTHORIZE | RECURRING


 
shop_name
string  [ 1 .. 128 ] characters 
Shop name


 
shop_url
string  [ 1 .. 128 ] characters 
Shop URL with protocol HTTP or HTTPS


 
required
Array of productSale (object) or productSubscription (object)  [ 0 .. 10 ] items 
Expected at least 1 product


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


 
Responses 
200
OK


400
Request validation error


401
Authorization error


429
Too many requests error


500
Internal server error


Callbacks 
postTransaction notification
post/sale
Request samples 
application/json
{
  • "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": true,
  • "success_url": "https://example.com/success",
  • "failure_url": "https://example.com/failure",
  • "shop_name": "my shop",
  • "shop_url": "https://shop.com",
  • "products": [
    ]
}
Response samples 
application/json
{
  • "type": "PAYMENT",
  • "data": {
    }
}
Callback payload samples 
POST: Transaction notification
application/json
{
  • "type": "TRANSACTION",
  • "data": {
    }
}
Embedded flow
Overview
Embedded components for checkout refer to a collection of ready-made user interface elements designed to facilitate the construction of your checkout process..


Usage example
Set up the server:


    

  • Install the packages (axios, express in example code) and import them in your code.
    • 



npm install axios express



    

  • Add an endpoint on your server that creates a checkout.
Setup checkout parameters and set success_url and failure_url for redirect customer.
Create index.js file with code bellow:
    • 



const express = require("express");
const axios = require("axios");
const PORT = 5000;
const YOUR_DOMAIN = `http://localhost:${PORT}`;
const API_KEY = "X-api-key";
const app = express();
app.use(express.static("public"));

app.post("/checkout", async (req, res) => {
  const result = await axios.post(
    "https://api.sandbox.upgate.com/v1/checkout",
    {
      payment_data: {
        ui_mode: "EMBEDDED",
        type: "SALE",
        methods: ["CARD", "GIROPAY", "MBWAY"],
        amount: "20.03",
        currency_code: "EUR",
      },
      customer: {
        merchant_customer_id: "test",
      },
      callback: {
        success_url: `${YOUR_DOMAIN}/index.html?success=true`,
        failure_url: `${YOUR_DOMAIN}/index.html`,
      },
      products: [
        {
          type: "SALE",
          price: 55,
          name: "Test product name for SALE",
          description: "Test product description for SALE",
        },
      ],
    },
    {
      headers: {
        "X-Api-Key": API_KEY,
        "Content-Type": "application/json",
      },
    }
  );
  res.json({ url: result.data.session.redirect_url });
});
app.listen(PORT, () => console.log(`Running on port ${YOUR_DOMAIN}`));






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.


Decline Code Mapping
When using the embedded form, the display of errors for customers is managed by the merchant. The table below provides examples of the text we, as the UpGate provider, recommend using for each code to enhance customers experience.





Table of Decline Codes and Messages






code
message





2000
Your transaction was declined. Please try again or use another card.




2001, 2002, 2003
Your transaction was declined by your bank. Please try again or use another card.




2004
Your card has insufficient funds. Please try again or use another card.




2005, 2006, 2203
Your card is not supported. Please try again or use another card.




2007
Your card has exceeded its limit. Please check your card and try again or use another card.




2008, 2009, 2010, 2900, 2901
An error occurred while processing your card. Try again in a little bit.




2101, 2102
Your card's security code is incorrect. Please try again or use another card.




2130, 2131, 2132, 2138, 2139, 2140, 1320, 1321, 1322, 1390
Your 3-D Secure authentication failed. Please try again or use another card.




2202
Your card has expired. Please try again or use another card.




2204, 2299
Your card number is invalid. Please check the card number and try again or use another card.




other codes
Your card has been declined. Please try again or use another card.