Powered by Redocly

UpGate API documentation (v1.1)

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.12] - 2023-09-05

Added

  • Create token endpoint

Changed

  • Update response codes
  • Update APM payment methods

[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

Payment

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
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
3000 Unknown error

Card flow

Supported Payment methods

name
CARD

Process diagram

Alternative payment methods (APM)

Support payment methods

name
ALIPAY
EPS
MBWAY
MULTIBANCO
SOFORT
GIROPAY
IDEAL
UPI

Process diagram

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" "ATM_UNION" "EPS" "SOFORT" "GIROPAY" "SEPA" "IDEAL" "UPI" "CRYPTO"
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

required
Array of productSale (object) or productSubscription (object) [ 0 .. 10 ] items

Expected at least 1 product

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

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",
  • "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" "ATM_UNION" "EPS" "SOFORT" "GIROPAY" "SEPA" "IDEAL" "UPI" "CRYPTO"
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

required
Array of productSale (object) or productSubscription (object) [ 0 .. 10 ] items

Expected at least 1 product

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

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",
  • "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" "ATM_UNION" "EPS" "SOFORT" "GIROPAY" "SEPA" "IDEAL" "UPI" "CRYPTO"
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

required
Array of productSale (object) or productSubscription (object) [ 0 .. 10 ] items

Expected at least 1 product

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

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=",
  • "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" "ATM_UNION" "EPS" "SOFORT" "GIROPAY" "SEPA" "IDEAL" "UPI" "CRYPTO"
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

required
Array of productSale (object) or productSubscription (object) [ 0 .. 10 ] items

Expected at least 1 product

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

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=",
  • "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" "ATM_UNION" "EPS" "SOFORT" "GIROPAY" "SEPA" "IDEAL" "UPI" "CRYPTO"
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

required
Array of productSale (object) or productSubscription (object) [ 0 .. 10 ] items

Expected at least 1 product

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

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