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

Changelog

[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

Constants

Transaction status

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

Response Codes

code message
1000 Success
1200 Pending
1300 DS verification successful (challenged)
1301 DS 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
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
2138 3DS SCA required
2139 3DS integration error
2140 Low value rejected
2141 Incorrect card data
2142 Incorrect data
2143 Missing parameters
2200 Pick up card
2201 Pick up card (stolen or fraud"
2202 Expired card
2203 Unsupported card type
2204 No such issuer
2299 Closed account
2300 Processor risk
2301 Velocity limit exceeded
2302 Suspected Fraud
2310 Card blacklisted
2311 IP blacklist
2312 Email blacklist
2313 BIN blacklist
2314 Country blacklist
2900 System malfunction
2901 Integration error
2902 Processor not supported feature
2903 Processor malfunction
2904 Timeout
2906 Missing payment token
3000 Unknown error

Card flow

Supported Payment methods

name
CARD

Supported card schemes

name
VISA
MasterCard
Maestro
Discover
Diners
UnionPay
RuPay
American Express

Process diagram

Alternative payment methods (APM)

Support payment methods

name
ALIPAY
EPS
SOFORT
GIROPAY
IDEAL
UPI
MULTIBANCO
MBWAY
INSTANT_BANK_TRANSFER
SPEI
CODI
PIX
PAGOEFECTIVO
PSE
WECHAT

Process diagram

Overview

Direct Payment Overview

Payment request examples

Sale request

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

Currently unavailable

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

Use payment_method: CARD for payments with subscription.

Enum: "CARD" "ALIPAY" "UPI" "GIROPAY" "EPS" "SOFORT" "IDEAL" "MULTIBANCO" "MBWAY" "WECHAT" "INSTANT_BANK_TRANSFER" "CODI" "SPEI" "PIX" "PAGOEFECTIVO" "PSE" "CRYPTO" "MYBANK" "SATISPAY" "AIRCASH" "BLIK" "NUPAY" "ALIPAY_PLUS" "MPESA" "KAKAO_PAY"
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 .. 2048 ] characters

required only for SALE | AUTHORIZE | RECURRING

failure_url
string <url> [ 1 .. 2048 ] characters

required only for SALE | AUTHORIZE | RECURRING

payment_token_id
string [ 1 .. 64 ] characters

Token from original payment. Used for MIT_SALE | MIT_AUTHORIZE

shop_name
string [ 1 .. 32 ] 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

Responses
200

OK

400

Request validation error

401

Authorization 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": {
    }
}

Authorize request

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

Currently unavailable

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

Use payment_method: CARD for payments with subscription.

Enum: "CARD" "ALIPAY" "UPI" "GIROPAY" "EPS" "SOFORT" "IDEAL" "MULTIBANCO" "MBWAY" "WECHAT" "INSTANT_BANK_TRANSFER" "CODI" "SPEI" "PIX" "PAGOEFECTIVO" "PSE" "CRYPTO" "MYBANK" "SATISPAY" "AIRCASH" "BLIK" "NUPAY" "ALIPAY_PLUS" "MPESA" "KAKAO_PAY"
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 .. 2048 ] characters

required only for SALE | AUTHORIZE | RECURRING

failure_url
string <url> [ 1 .. 2048 ] characters

required only for SALE | AUTHORIZE | RECURRING

payment_token_id
string [ 1 .. 64 ] characters

Token from original payment. Used for MIT_SALE | MIT_AUTHORIZE

shop_name
string [ 1 .. 32 ] 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

Responses
200

OK

400

Request validation error

401

Authorization 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-Signature
string

Currently unavailable

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

Use payment_method: CARD for payments with subscription.

Enum: "CARD" "ALIPAY" "UPI" "GIROPAY" "EPS" "SOFORT" "IDEAL" "MULTIBANCO" "MBWAY" "WECHAT" "INSTANT_BANK_TRANSFER" "CODI" "SPEI" "PIX" "PAGOEFECTIVO" "PSE" "CRYPTO" "MYBANK" "SATISPAY" "AIRCASH" "BLIK" "NUPAY" "ALIPAY_PLUS" "MPESA" "KAKAO_PAY"
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 .. 2048 ] characters

required only for SALE | AUTHORIZE | RECURRING

failure_url
string <url> [ 1 .. 2048 ] characters

required only for SALE | AUTHORIZE | RECURRING

payment_token_id
string [ 1 .. 64 ] characters

Token from original payment. Used for MIT_SALE | MIT_AUTHORIZE

shop_name
string [ 1 .. 32 ] 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

Responses
200

OK

400

Request validation error

401

Authorization 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-Signature
string

Currently unavailable

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

Use payment_method: CARD for payments with subscription.

Enum: "CARD" "ALIPAY" "UPI" "GIROPAY" "EPS" "SOFORT" "IDEAL" "MULTIBANCO" "MBWAY" "WECHAT" "INSTANT_BANK_TRANSFER" "CODI" "SPEI" "PIX" "PAGOEFECTIVO" "PSE" "CRYPTO" "MYBANK" "SATISPAY" "AIRCASH" "BLIK" "NUPAY" "ALIPAY_PLUS" "MPESA" "KAKAO_PAY"
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 .. 2048 ] characters

required only for SALE | AUTHORIZE | RECURRING

failure_url
string <url> [ 1 .. 2048 ] characters

required only for SALE | AUTHORIZE | RECURRING

payment_token_id
string [ 1 .. 64 ] characters

Token from original payment. Used for MIT_SALE | MIT_AUTHORIZE

shop_name
string [ 1 .. 32 ] 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

Responses
200

OK

400

Request validation error

401

Authorization 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-Signature
string

Currently unavailable

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

Use payment_method: CARD for payments with subscription.

Enum: "CARD" "ALIPAY" "UPI" "GIROPAY" "EPS" "SOFORT" "IDEAL" "MULTIBANCO" "MBWAY" "WECHAT" "INSTANT_BANK_TRANSFER" "CODI" "SPEI" "PIX" "PAGOEFECTIVO" "PSE" "CRYPTO" "MYBANK" "SATISPAY" "AIRCASH" "BLIK" "NUPAY" "ALIPAY_PLUS" "MPESA" "KAKAO_PAY"
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 .. 2048 ] characters

required only for SALE | AUTHORIZE | RECURRING

failure_url
string <url> [ 1 .. 2048 ] characters

required only for SALE | AUTHORIZE | RECURRING

payment_token_id
string [ 1 .. 64 ] characters

Token from original payment. Used for MIT_SALE | MIT_AUTHORIZE

shop_name
string [ 1 .. 32 ] 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

Responses
200

OK

400

Request validation error

401

Authorization 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": {
    }
}

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-Signature
string

Currently unavailable

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": {
    }
}

Update subscription by subscription id

SecurityX-Api-Key
Request
query Parameters
path
required
string
Example: path=2E2CL5R3KC7K3
header Parameters
X-Signature
string

Currently unavailable

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": {
    }
}

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

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",
}
Response samples
application/json
{
  • "type": "PAYMENT",
  • "data": {
    }
}
Callback payload samples
POST: Transaction notification
application/json
{
  • "type": "TRANSACTION",
  • "data": {
    }
}

Checkout request examples

Request

SecurityX-Api-Key
Request
Request Body schema: application/json
required
required
object
required
object
required
object
required
Array of objects (checkoutProduct)
object
Responses
200

OK

400

Request validation error

401

Authorization 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": {
    }
}

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://hub.upgate.com/api/merchant-operations/v4/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;
async function mount() {
  const { url } = await fetch("/checkout", { method: "POST" }).then((res) =>
    res.json()
  );
  upgate.mountPaymentElement("payment", url);
}
function submit() {
  upgate.submit("payment").then(console.log).catch(console.error);
}
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

    Submit function it's async function that returns TResult type object below:
export type TResult = {
  success: boolean;
  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.

export type TConfig = Partial<{
  theme: "LIGHT" | "DARK" | "BROWSER";
}>;

Property theme overrides theme type defined in backoffice, and you can call embedded form with dynamically changed theme. Theme type BROWSER renders theme depending on system theme.

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