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 three short-lived tokens involved in a payment:

  1. SDK token (sdk_token, ~1h) — obtained from POST /v1/auth (backend) or POST /v1/tokenize (frontend). Sent as Authorization: Bearer <jwt>. Carries an integrationType (frontend | backend), a set of permissions and modules.
  2. 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

  • frontend — may link existing products (product:link) and verify a customer via OTP. Cannot set product prices inline.
  • backend — may additionally create inline/ad-hoc products (product:create) and pre-set a locked customer (customer:create / customer:select).

Auth

Token issuance for backend and frontend integrations.

Exchange API keys for an SDK token (backend)

Backend integrations exchange their public/secret API key pair for an SDK token. 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"
}

Exchange a client token for an SDK token (frontend)

Frontend integrations exchange a publishable client token (tk_*) for a short-lived SDK token scoped to the calling origin. 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",
  • "modules": [
    ],
  • "permissions": [
    ]
}

Checkout

Payment session lifecycle.

Create a payment session

Creates a payment session for one or more products.

Product rules

  • Linked products ({ storeCode, quantity }) require the product:link permission.
  • Inline products ({ name, price, quantity, ... }) require a backend integration and the product:create permission. Frontend tokens may not set prices.

Customer rules

  • A customer object may only be supplied by backend integrations holding customer:create or customer:select. When provided, the resulting session has a locked, pre-verified customer.
Authorizations:
SdkToken
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. Requires any valid SDK token belonging to the same application.

Authorizations:
SdkToken
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

Authorizations:
SdkToken
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

Authorizations:
SdkToken
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

Authorizations:
SdkToken

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