# UpGate API documentation 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. Version: 1.2 ## Servers Sandbox UpGate API ``` https://api.sandbox.upgate.com/v1 ``` ## Security ### X-Api-Key Type: apiKey In: header Name: X-Api-Key ## Download OpenAPI description [UpGate API documentation](https://docs.upgate.com/_bundle/openapi.yaml) ## Example ### Sale request - [POST /checkout](https://docs.upgate.com/openapi/sale-request-examples/checkout_request.md): This endpoint allows the creation of a single, one-time payment. Upon successful completion, the system will return a payment token in the callback response. This token can later be used to initiate subsequent Merchant-Initiated Transactions (MIT) or Customer-Initiated Transactions (CIT) associated with the original payment. ## Examples ### Subscription request - [POST /checkout ](https://docs.upgate.com/openapi/subscription-request-examples/subscription_request.md): This endpoint allows you to create a subscription within the Upgate system. Once the subscription is successfully created, the user will be charged automatically according to the schedule specified in the request. You can also combine recurring (rebill) payments with a one-time payment in the same flow. Refer to the Use Cases section for detailed examples and implementation guidance. After a successful request, you will receive two callback notifications, one for the initial transaction (TRANSACTION type) and one for the subscription update (SUBSCRIPTION type) ### Update subscription by merchant product id - [PATCH /subscription](https://docs.upgate.com/openapi/subscription-request-examples/updatesubscriptionbymerchantproductid.md): Update an existing subscription identified by merchant_product_id. Use this endpoint to change the recurring billing details of a subscription: toggle automatic rebilling (is_rebill_enabled), set a new rebill amount, change the rebill cycle (charge_interval and charge_interval_value), and reschedule the next charge (next_rebill_at). Optional fields are applied only when included in the request. After a successful update you receive a SUBSCRIPTION type postback notification reflecting the new subscription state. ### Get subscription by transaction ID - [GET /subscription](https://docs.upgate.com/openapi/subscription-request-examples/getsubscriptionbyfilters.md) ### Get subscription by subscription id - [GET /subscription/{subscriptionId}](https://docs.upgate.com/openapi/subscription-request-examples/getsubscriptionbysubscriptionid.md) ### Update subscription by subscription id - [PATCH /subscription/{subscriptionId}](https://docs.upgate.com/openapi/subscription-request-examples/updatesubscriptionbysubscriptionid.md): Update an existing subscription identified by subscriptionId. Use this endpoint to change the recurring billing details of a subscription: toggle automatic rebilling (is_rebill_enabled), set a new rebill amount, change the rebill cycle (charge_interval and charge_interval_value), and reschedule the next charge (next_rebill_at). Optional fields are applied only when included in the request. After a successful update you receive a SUBSCRIPTION type postback notification reflecting the new subscription state. ## Subsequent request examples ### MIT Sale request - [POST /mit-sale](https://docs.upgate.com/openapi/subsequent-request-examples/mit_sale_request.md): This endpoint allows you to create a subsequent transaction using an existing payment token. It is typically used when you want to manage recurring or rebill payments on your side, or when you want to enable one-click payments for your customers without requiring them to re-enter their payment details. To initiate a subsequent transaction, provide the payment token ID received from a previous Sale request. Note that the combination of payment_token_id and merchant_customer_id should match the initial sale values. ### MIT Authorize request - [POST /mit-authorize](https://docs.upgate.com/openapi/subsequent-request-examples/mit_authorize_request.md) ### CIT Sale request - [POST /cit-sale](https://docs.upgate.com/openapi/subsequent-request-examples/cit_sale_request.md): This endpoint allows you to create a subsequent transaction that triggers a 3-D Secure (3DS) authentication flow for your users. It can be used when you want customers to actively confirm and provide consent for the charge, ensuring additional security and compliance with authentication requirements. Similar to the standard subsequent transaction, this endpoint enables you to manage rebills on your end or offer one-click payments without requiring users to re-enter their card details. Use the payment token ID received from the original Sale request to initiate this transaction. Note that the combination of payment_token_id and merchant_customer_id should match the initial sale values ## Example ### Fetch transactions by filters - [GET /transaction](https://docs.upgate.com/openapi/transactions-history-requests-examples/transaction_list.md): When you request a list of transactions, the response is limited to the maximum number of records you specified in the query. If there are more transactions available beyond that limit, you don’t need to start over. Instead, you can continue fetching results from where you left off by including the prev_id parameter in your next request. ## Negative database requests examples ### Create Negative Database record - [POST /merchant-negative-entry](https://docs.upgate.com/openapi/negative-database-requests-examples/merchant_negative_entry_create.md): Users can be added to the negative database either manually via the UpGate Backoffice or programmatically using this endpoint. When adding a record, the type parameter defines the attribute used for blocking. If any value in an incoming transaction request matches an entry in the negative database, the transaction will be automatically rejected with one of the following error codes: - 2309 — Customer blacklisted - 2310 — Card blacklisted - 2311 — IP blacklisted - 2312 — Email blacklisted - 2313 — BIN blacklisted - 2314 — Country blacklisted Example If a transaction is submitted with an email address that matches an existing Email type entry in the negative database, the transaction will be rejected with error code 2312 / Email blacklisted. ### Fetch Negative Database records - [GET /merchant-negative-entry](https://docs.upgate.com/openapi/negative-database-requests-examples/merchant_negative_entry_list.md): Returns the list of the Negative Database records filtered by repeated type query parameters and paginated with limit/cursor ### Delete Negative Database record - [DELETE /merchant-negative-entry/{id}](https://docs.upgate.com/openapi/negative-database-requests-examples/merchant_negative_entry_delete.md): Delete a Negative Database record by identifier. ## Card management requests examples ### Delete saved card - [POST /customer/{merchantCustomerId}/payment-token/{paymentTokenId}/delete](https://docs.upgate.com/openapi/card-management-requests-examples/customer_payment_token_delete.md): Hides a saved card (soft delete) for the given customer and payment token. The card stops appearing in the prefill list on the payment form. Card-on-File (COF) consent is not removed by this call, so merchant-initiated (MIT) payments on this token remain possible until the consent is revoked via the revoke-cof-consent endpoint. ### Revoke COF consent - [POST /customer/{merchantCustomerId}/payment-token/{paymentTokenId}/revoke-cof-consent](https://docs.upgate.com/openapi/card-management-requests-examples/customer_payment_token_revoke_cof_consent.md): Revokes Card-on-File (COF) consent for the given customer and payment token. Deletes all consent records matching the customer and payment token across every payment method. After this call, the merchant can no longer initiate merchant-initiated (MIT) transactions on this token. Note that the saved card itself is not removed — use the delete endpoint to hide the card from the prefill list. ## Example ### Refund Request - [POST /refund](https://docs.upgate.com/openapi/refund-request-examples/refund_request.md): Use this request to refund a settled transaction. Refunds can also be issued manually from the UpGate back office. Partial refunds are supported only for card, Apple Pay, and Google Pay payments, and only with certain processors. For all other payment methods, the full amount must be refunded. ## Example ### Token request - [POST /token](https://docs.upgate.com/openapi/payout-requests-examples/token_request.md): This endpoint retrieves a payment token for a customer’s card. Before using this endpoint, ensure that the corresponding setting is enabled in the UpGate Backoffice. The payment token returned by this endpoint can be used in card payout requests. ### Payout request - [POST /payout](https://docs.upgate.com/openapi/payout-requests-examples/payout_request.md): Use this endpoint to execute a payout. Prerequisites depend on the payout method. Before calling this endpoint, make sure the corresponding requirement below is met: | Payout method | Prerequisite | |---------------|--------------------------------------------------------------------------------------------------| | Card | A valid token obtained through the Token request | | Crypto | A crypto wallet configured in the UpGate back office | | Paxum | A Paxum processor configured in the UpGate back office | | Bank transfer | A processor that supports the bank transfer payment method, configured in the UpGate back office | | ACH | A Spayce processor configured in the UpGate back office | ## Other request examples ### Authorize request (deprecated) - [POST /authorize](https://docs.upgate.com/openapi/other-request-examples/authorize_request.md) ### Recurring transaction - [POST /recurring](https://docs.upgate.com/openapi/other-request-examples/recurring.md) ### Sale request (deprecated) - [POST /sale](https://docs.upgate.com/openapi/other-request-examples/sale_request.md)