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

Changelog

[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

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

Overview

Direct Payment Overview

Payment request examples

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
payment_method
required
string (paymentMethod)

Use payment_method: CARD for payments with subscription.

Enum: "CARD" "AIRCASH" "ALIPAY" "ALIPAY_PLUS" "APPLE_PAY" "BANK_APP" "BINANCE_PAY" "BLIK" "CARDEXTERNAL" "CODI" "CRYPTO" "EPS" "GIROPAY" "GOOGLE_PAY" "IDEAL" "INSTANT_BANK_TRANSFER" "KAKAO_PAY" "MBWAY" "MPESA" "MULTIBANCO" "MYBANK" "NUPAY" "PAGOEFECTIVO" "PAYCONIQ" "PAYPAL" "PIX" "PSE" "SATISPAY" "SOFORT" "SPEI" "UPI" "WECHAT"
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

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

Authorize 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 (paymentMethod)

Use payment_method: CARD for payments with subscription.

Enum: "CARD" "AIRCASH" "ALIPAY" "ALIPAY_PLUS" "APPLE_PAY" "BANK_APP" "BINANCE_PAY" "BLIK" "CARDEXTERNAL" "CODI" "CRYPTO" "EPS" "GIROPAY" "GOOGLE_PAY" "IDEAL" "INSTANT_BANK_TRANSFER" "KAKAO_PAY" "MBWAY" "MPESA" "MULTIBANCO" "MYBANK" "NUPAY" "PAGOEFECTIVO" "PAYCONIQ" "PAYPAL" "PIX" "PSE" "SATISPAY" "SOFORT" "SPEI" "UPI" "WECHAT"
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

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 (paymentMethod)

Use payment_method: CARD for payments with subscription.

Enum: "CARD" "AIRCASH" "ALIPAY" "ALIPAY_PLUS" "APPLE_PAY" "BANK_APP" "BINANCE_PAY" "BLIK" "CARDEXTERNAL" "CODI" "CRYPTO" "EPS" "GIROPAY" "GOOGLE_PAY" "IDEAL" "INSTANT_BANK_TRANSFER" "KAKAO_PAY" "MBWAY" "MPESA" "MULTIBANCO" "MYBANK" "NUPAY" "PAGOEFECTIVO" "PAYCONIQ" "PAYPAL" "PIX" "PSE" "SATISPAY" "SOFORT" "SPEI" "UPI" "WECHAT"
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

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 (paymentMethod)

Use payment_method: CARD for payments with subscription.

Enum: "CARD" "AIRCASH" "ALIPAY" "ALIPAY_PLUS" "APPLE_PAY" "BANK_APP" "BINANCE_PAY" "BLIK" "CARDEXTERNAL" "CODI" "CRYPTO" "EPS" "GIROPAY" "GOOGLE_PAY" "IDEAL" "INSTANT_BANK_TRANSFER" "KAKAO_PAY" "MBWAY" "MPESA" "MULTIBANCO" "MYBANK" "NUPAY" "PAGOEFECTIVO" "PAYCONIQ" "PAYPAL" "PIX" "PSE" "SATISPAY" "SOFORT" "SPEI" "UPI" "WECHAT"
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

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 (paymentMethod)

Use payment_method: CARD for payments with subscription.

Enum: "CARD" "AIRCASH" "ALIPAY" "ALIPAY_PLUS" "APPLE_PAY" "BANK_APP" "BINANCE_PAY" "BLIK" "CARDEXTERNAL" "CODI" "CRYPTO" "EPS" "GIROPAY" "GOOGLE_PAY" "IDEAL" "INSTANT_BANK_TRANSFER" "KAKAO_PAY" "MBWAY" "MPESA" "MULTIBANCO" "MYBANK" "NUPAY" "PAGOEFECTIVO" "PAYCONIQ" "PAYPAL" "PIX" "PSE" "SATISPAY" "SOFORT" "SPEI" "UPI" "WECHAT"
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

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

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": {
    }
}
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 examples
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": {
    }
}
Checkout request examples
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
 
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": {
    }
}
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;
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;
  url: 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.


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



Property theme overrides theme type defined in backoffice, 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.





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