Skip to main content
API docs by Redocly

PayUp Public Payment API (1.0.0)

Download OpenAPI specification:Download

The PayUp public payment surface. These endpoints power both the hosted checkout experience (frontend integrations, via the SDK token) and direct backend integrations (via API keys).

Token model

There are four short-lived tokens involved in a payment:

  1. Creation SDK token (sdk_token, ~1h) — used only to create a payment session. Never placed in the browser redirect URL.
    • Frontend — from POST /v1/tokenize (integrationType=frontend). Used by the web SDK on POST /v1/checkout/web/session.
    • Backend — from POST /v1/auth (integrationType=backend). Used by server integrations on POST /v1/checkout/backend/session.
  2. Checkout token (sdk_token, ~1h, session-scoped) — minted when a session is created and appended to redirectUrl as ?sdk_token=…. This is the only token the hosted checkout page receives. It is bound to a single sessionId and carries only payment:send_otp and payment:verify_otp — it cannot create sessions or set product prices.
  3. Payment verification token (payment_verification, ~5m) — returned by POST /v1/checkout/verification/verify after the customer proves ownership of their email or phone via OTP. Sent as Authorization: Bearer <jwt> to POST /v1/payments/process.

Integration types

Creation tokens carry integrationType (frontend | backend):

  • frontend — may link existing products (product:link) on /checkout/web/session. Cannot set product prices inline or pre-set a customer. Requires a verified merchant Origin header.
  • backend — may additionally create inline/ad-hoc products (product:create) and pre-set a locked customer (customer:create / customer:select) on /checkout/backend/session. Server-to-server; no Origin required.

Health checks

Liveness endpoints live outside this spec's server prefix: GET /health and GET /api/health.

Auth

Token issuance for backend and frontend integrations.

Exchange API keys for a backend creation SDK token

Backend integrations exchange their public/secret API key pair for a creation SDK token (integrationType=backend). Use this token on POST /v1/checkout/backend/session only — do not pass it to the browser.

The secret key is sent as a Bearer token and the public key via the x-public-key header (or the publicKey body field).

Authorizations:
ApiKeyPair
Request Body schema: application/json
publicKey
string

Public key (pk_*). Alternative to the x-public-key header.

Responses

Request samples

Content type
application/json
{
  • "publicKey": "pk_live_8f3a..."
}

Response samples

Content type
application/json
{
  • "success": true,
  • "token": "string",
  • "expiresIn": "1h",
  • "environment": "sandbox",
  • "integrationType": "frontend",
  • "permissions": [
    ],
  • "modules": [
    ]
}

Exchange a client token for a frontend creation SDK token

Frontend integrations exchange a publishable client token (tk_*) for a short-lived creation SDK token (integrationType=frontend). Use this token on POST /v1/checkout/web/session only — the hosted checkout page receives a separate session-scoped checkout token via redirectUrl.

The request must include an Origin (or Referer) header that matches an allowed, verified domain.

Authorizations:
ClientToken

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "token": "string",
  • "expiresIn": "1h",
  • "environment": "sandbox",
  • "integrationType": "frontend",
  • "permissions": [
    ],
  • "modules": [
    ]
}

Checkout

Payment session lifecycle.

Create a payment session (web / frontend)

Creates a payment session from the merchant storefront via the web SDK.

Requires a frontend creation SDK token from POST /v1/tokenize and a verified merchant Origin (or Referer) header.

Product rules

  • Only linked products ({ storeCode, quantity }) are allowed. Inline products with a price are rejected — frontend integrations cannot set prices.

Customer rules

  • A customer object may not be supplied. Frontend customers are established through OTP verification on the checkout page.

Redirect

  • The response redirectUrl includes a session-scoped checkout token (?sdk_token=…), not the caller's creation token.
Authorizations:
FrontendSdkToken
Request Body schema: application/json
required
Array of objects (LinkProduct) non-empty

Linked catalog products only.

object
returnUrl
string <uri>
cancelUrl
string <uri>
gateway
string (GatewayName)
Enum: "paypal" "stripe" "moyasar" "myfatoorah"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "message": "string",
  • "sessionId": "string",
  • "redirectUrl": "string",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "status": "init",
  • "amount": 0,
  • "currency": "string",
  • "customer": {
    }
}

Create a payment session (backend)

Creates a payment session from a merchant backend (server-to-server).

Requires a backend creation SDK token from POST /v1/auth. No Origin header is required.

Product rules

  • Linked products ({ storeCode, quantity }) require product:link.
  • Inline products ({ name, price, quantity, ... }) require product:create.

Customer rules

  • A customer object may be supplied when holding customer:create or customer:select. When provided, the resulting session has a locked, pre-verified customer.

Redirect

  • The response redirectUrl includes a session-scoped checkout token (?sdk_token=…), not the caller's backend creation token.
Authorizations:
BackendSdkToken
Request Body schema: application/json
required
Array of LinkProduct (object) or InlineProduct (object) non-empty

A mix of linked and/or inline products.

object

Backend-only pre-set customer. Locks the checkout customer field.

object
returnUrl
string <uri>
cancelUrl
string <uri>
gateway
string (GatewayName)
Enum: "paypal" "stripe" "moyasar" "myfatoorah"

Responses

Request samples

Content type
application/json
{
  • "products": [
    ],
  • "customer": {
    },
  • "metadata": { },
  • "returnUrl": "http://example.com",
  • "cancelUrl": "http://example.com",
  • "gateway": "paypal"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "sessionId": "string",
  • "redirectUrl": "string",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "status": "init",
  • "amount": 0,
  • "currency": "string",
  • "customer": {
    }
}

Get checkout session details

Returns the full session payload used to render the hosted checkout page.

Authenticated with the checkout token from the session's redirectUrl (?sdk_token=…). When the token carries a sessionId claim, it must match the requested session — a checkout token for session A cannot read session B.

Authorizations:
CheckoutToken
path Parameters
token
required
string

The payment session token.

Responses

Response samples

Content type
application/json
{
  • "sessionId": "string",
  • "applicationName": "string",
  • "customerName": "string",
  • "customer": {
    },
  • "totalAmount": 0,
  • "totalTax": 0,
  • "currency": "string",
  • "method": "card",
  • "gateway": "moyasar",
  • "gatewayPublicKey": "string",
  • "gatewayPublicConfigs": {
    },
  • "status": "init",
  • "returnUrl": "string",
  • "error": {
    },
  • "orderNumber": "string",
  • "expiresAtUtc": "2019-08-24T14:15:22Z",
  • "metadata": { },
  • "showProducts": true,
  • "showCurrencySelector": true,
  • "showTaxElement": true,
  • "showCustomerElement": true,
  • "showAddressElement": true,
  • "showShipping": true,
  • "showPayment": true,
  • "products": [
    ],
  • "brandName": "string",
  • "brandLogo": "string",
  • "supportedPaymentMethods": [
    ],
  • "paymentMethodGatewayMap": {
    }
}

List supported currencies

Responses

Response samples

Content type
application/json
{
  • "currencies": [
    ]
}

List available payment gateways

Responses

Response samples

Content type
application/json
{
  • "gateways": [
    ]
}

Verification

Customer email/phone OTP verification.

Send an OTP to an email or phone

Requires the session-scoped checkout token from the session redirectUrl.

Authorizations:
CheckoutToken
Request Body schema: application/json
method
required
string
Enum: "email_otp" "mobile_otp"
identifier
required
string non-empty

Email address (for email_otp) or phone number (for mobile_otp).

object

Responses

Request samples

Content type
application/json
{
  • "method": "email_otp",
  • "identifier": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "expiresIn": 600,
  • "verificationId": "string"
}

Verify an OTP and obtain a payment verification token

Requires the session-scoped checkout token from the session redirectUrl.

Authorizations:
CheckoutToken
Request Body schema: application/json
method
required
string
Enum: "email_otp" "mobile_otp"
identifier
required
string non-empty
code
required
string non-empty

Responses

Request samples

Content type
application/json
{
  • "method": "email_otp",
  • "identifier": "string",
  • "code": "123456"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "verificationToken": "string",
  • "identifier": "string",
  • "method": "email_otp",
  • "expiresIn": "5m"
}

List available verification methods

Requires the session-scoped checkout token from the session redirectUrl.

Authorizations:
CheckoutToken

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "methods": [
    ]
}

Payments

Payment processing.

Process a payment for a verified session

Charges the session. Authenticated with the payment verification token returned by /checkout/verification/verify, passed as Authorization: Bearer <token>.

Optionally include the other contact channel (customerEmail / customerPhone) as supplementary data — some gateways require a phone even when the customer verified by email.

Authorizations:
PaymentVerificationToken
Request Body schema: application/json
sessionToken
required
string
method
required
string
gateway
required
string
required
object

Gateway/method specific payload.

customerEmail
string

Supplementary email (when the customer verified by phone).

customerPhone
string

Supplementary phone (when the customer verified by email).

Responses

Request samples

Content type
application/json
{
  • "sessionToken": "string",
  • "method": "card",
  • "gateway": "moyasar",
  • "methodPayload": {
    },
  • "customerEmail": "string",
  • "customerPhone": "string"
}

Response samples

Content type
application/json
{
  • "status": "init",
  • "message": "string",
  • "sessionId": "string",
  • "paymentId": "string",
  • "gateway": "string",
  • "redirectUrl": "string",
  • "error": {
    }
}

Confirm a payment (deprecated) Deprecated

Deprecated. The hosted checkout now returns through GET /payments/callback/{sessionToken}. Retained for SDK / backward compatibility.

Authorizations:
PaymentVerificationToken
Request Body schema: application/json
sessionToken
required
string

Responses

Request samples

Content type
application/json
{
  • "sessionToken": "string"
}

Response samples

Content type
application/json
{
  • "status": "init",
  • "message": "string",
  • "sessionId": "string",
  • "paymentId": "string",
  • "gateway": "string",
  • "redirectUrl": "string",
  • "error": {
    }
}

Gateway return callback (browser redirect)

Browser redirect target used by gateways after an off-site payment. Returns an HTML status page and then redirects to the checkout page. Not intended for programmatic use.

path Parameters
sessionToken
required
string
query Parameters
outcome
string
Enum: "success" "cancel"

Responses