Marseille UPG
Marseille UPG
PlatformWhy MarseilleDevelopersProvidersPricing
Sign inStart integration
API Reference

The currently exposed Marseille UPG gateway API.

This reference is limited to routes that exist in the current repository and are exposed by the running gateway router.

Gateway prefix
/v1/gateway
Public status
/v1/public/status
Return pages
/payment/*
Auth
appSecret or legacy sign
01

Overview

The public gateway currently exposes a small set of routes. Merchant systems primarily usePOST /v1/gateway/pay to create payments and POST /v1/gateway/queryto query them. Provider systems call /v1/gateway/callback/:provider. The public status page reads from GET /v1/public/status.

Not documented because not exposed
There is no public refund route, events route, tenant-header auth flow, OAuth flow, or published OpenAPI contract in the current gateway router. Those are intentionally not described here.
02

Create payment

POST/v1/gateway/pay

Creates a gateway payment order. The request supports two authentication styles: simplified mode with appId + appSecret, or legacy signed mode withtimestamp + nonce + sign.

Request body

  • appId
    string / required
    Merchant application identifier.
  • appSecret
    string / optional
    Simplified authentication mode. If omitted, the legacy signed mode is used.
  • outOrderNo
    string / required
    Merchant order number.
  • amount
    number / required
    Payment amount. Must be greater than 0.
  • currency
    string / required
    Order currency, for example USD or EUR.
  • payCurrency
    string / optional
    Upstream settlement or crypto pay currency when required by the adapter.
  • provider
    string / optional
    If omitted, the gateway uses the app's configured adapter type.
  • subject
    string / optional
    Order subject or display title.
  • productCode
    string / optional
    Passed through into extra metadata for adapters that use it.
  • timestamp
    int64 / legacy mode
    Required only when using legacy signed authentication.
  • nonce
    string / legacy mode
    Required only when using legacy signed authentication.
  • sign
    string / legacy mode
    Required only when using legacy signed authentication.
  • email
    string / optional
    Copied into extra metadata.
  • planType
    string / optional
    Copied into extra metadata.
  • returnUrl
    string / optional
    Overrides the default success return URL used by some adapters.
  • extra
    object / optional
    Free-form extra fields passed through after trimming.
create-payment.json
{
  "appId": "app_demo_001",
  "appSecret": "your-app-secret",
  "outOrderNo": "ORDER-20260426-001",
  "amount": 88,
  "currency": "USD",
  "provider": "stripe",
  "subject": "Pro plan",
  "returnUrl": "https://merchant.example.com/billing/return"
}

Success response

create-payment-response.json
{
  "code": 0,
  "data": {
    "gatewayOrderNo": "ORD-1777027063851",
    "paymentId": "cs_test_xxx",
    "payAddress": "",
    "pay_address": "",
    "payAmount": 0,
    "payUrl": "https://checkout.example.com/session/xxx",
    "pay_url": "https://checkout.example.com/session/xxx",
    "status": 0
  },
  "msg": "操作成功"
}
03

Query order

POST/v1/gateway/query

Queries a gateway order by gatewayOrderNo or outOrderNo. This route uses the legacy signed authentication fields.

  • appId
    string / required
    Merchant application identifier.
  • gatewayOrderNo
    string / optional
    Gateway order number. Provide this or outOrderNo.
  • outOrderNo
    string / optional
    Merchant order number. Provide this or gatewayOrderNo.
  • timestamp
    int64 / required
    Signed request timestamp.
  • nonce
    string / required
    Signed request nonce.
  • sign
    string / required
    Request signature generated from the signed fields.
query-order-response.json
{
  "code": 0,
  "data": {
    "gatewayOrderNo": "ORD-1777027063851",
    "outOrderNo": "ORDER-20260426-001",
    "amount": 88,
    "currency": "USD",
    "payCurrency": "",
    "status": 1,
    "statusText": "success",
    "provider": "stripe",
    "paymentId": "cs_test_xxx",
    "payAddress": "",
    "payAmount": 88
  },
  "msg": "操作成功"
}
04

Provider callback

POST/v1/gateway/callback/:provider

This route is for upstream payment providers, not for merchant systems. The gateway reads the raw request body, verifies the provider-specific callback, and updates the internal order state.

Who should call this route
Merchant systems should not post directly to /v1/gateway/callback/:provider. Providers call this route. Merchants receive a separate downstream notify payload from the gateway after callback verification.

Gateway callback result

provider-callback-response.json
{
  "status": "ok"
}
05

Return pages

Some adapters redirect the customer back through the gateway. These GET routes mark the visible return state for the order and return a compact JSON payload.

GET/payment/success?order={gatewayOrderNo}
Marks a successful return.
GET/payment/cancel?order={gatewayOrderNo}
Marks a canceled return.
GET/payment/pending?order={gatewayOrderNo}
Returns the current pending state.
return-success.json
{
  "status": "success",
  "gatewayOrderNo": "ORD-1777027063851",
  "outOrderNo": "ORDER-20260426-001"
}
06

Public status

GET/v1/public/status

Returns the public system status payload used by the marketing-site status page. It reports current gateway health, retained snapshot history, provider connectivity, and derived incident periods.

public-status.json
{
  "ok": true,
  "data": {
    "summary": {
      "updatedAt": "2026-04-26T07:50:29.836653913Z",
      "refreshSeconds": 60,
      "overallStatus": "degraded",
      "message": "Gateway systems degraded"
    },
    "history": [],
    "providers": [],
    "components": [],
    "incidents": []
  }
}