API Overview

The YardPay Pro REST API for creating checkout sessions, managing subscriptions, and processing payments.

Base URL

https://dev-payment-gateway.mplex.net

All API endpoints are relative to this base URL. All requests must use HTTPS.

Authentication

YardPay uses two types of API keys. Pass the key as a Bearer token in theAuthorization header.

Key Type	Prefix	Use	Access
Server Key	sk_live_...	Server-side only	Full API access (create sessions, manage subscriptions, verify webhooks)
Publishable Key	pk_live_...	Client-side (browsers, mobile apps)	Scoped to a single checkout session. Requires the `X-Client-Secret` header.

Publishable-key scopes

Publishable keys are issued with a fixed scope set covering the client-safe checkout flow. Every request must also carry the X-Client-Secret header matching the session the action targets.

Scope	Endpoint
checkout.session.read	GET /api/v1/checkout-sessions/{id}
checkout.session.confirm	POST /api/v1/checkout-sessions/{id}/confirm
checkout.session.confirm	POST /api/v1/checkout-sessions/{id}/withdraw-qr
checkout.session.tokenize	POST /api/v1/checkout-sessions/{id}/tokenize
checkout.session.cancel	POST /api/v1/checkout-sessions/{id}/cancel
checkout.session.status	GET /api/v1/checkout-sessions/{id}/status
checkout.session.cards.read	GET /api/v1/checkout-sessions/{id}/saved-cards
checkout.session.cards.verify	POST /api/v1/checkout-sessions/{id}/saved-cards/verify
checkout.session.cards.confirm_otp	POST /api/v1/checkout-sessions/{id}/saved-cards/confirm-otp
checkout.session.src.lookup	POST /api/v1/checkout-sessions/{id}/src/lookup
checkout.session.src.authenticate	POST /api/v1/checkout-sessions/{id}/src/authenticate

Server-key-only scopes

Scope	Endpoint
checkout.session.create	POST /api/v1/checkout-sessions
checkout.session.refund	POST /api/v1/checkout-sessions/{id}/refund
subscriptionplan.create / .read / .update / .delete	/api/v1/plans
subscription.read	GET /api/v1/subscriptions*
subscription.update	POST /api/v1/subscriptions/{id}/cancel · pause · resume
portal.session.create	POST /api/v1/portal-sessions
client_token.generate	Not available — `POST /api/v1/client-token` returns 501. Use the publishable key with the session's client secret.

Server Key Authentication

curl -X POST https://dev-payment-gateway.mplex.net/api/v1/checkout-sessions \
  -H "Authorization: Bearer sk_live_your_server_key" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50.00, "currency": "USD"}'

Publishable Key + Client Secret

Client-side requests use the publishable key for authentication and the client secret (returned when creating a checkout session) to scope access to that specific session.

curl -X POST https://dev-payment-gateway.mplex.net/api/v1/checkout-sessions/cs_live_abc123/confirm \
  -H "Authorization: Bearer pk_live_your_publishable_key" \
  -H "X-Client-Secret: cs_live_abc123_secret_xyz789" \
  -H "Content-Type: application/json" \
  -d '{"paymentMethodId": "pm_card_visa_1234"}'

Response Format

All responses are JSON. Successful responses return the resource object directly. List endpoints return a paginated wrapper.

Single resource

{
  "id": "cs_live_abc123",
  "object": "checkout_session",
  "status": "open",
  "amount": 50.00,
  "currency": "USD",
  "clientSecret": "cs_live_abc123_secret_xyz789",
  "createdAt": "2025-01-15T10:30:00Z"
}

Paginated list

{
  "object": "list",
  "data": [
    { "id": "sub_abc123", "object": "subscription", "status": "active" }
  ],
  "hasMore": true,
  "totalCount": 42
}

Error Handling

Errors return an appropriate HTTP status code with a JSON body describing the problem.

{
  "error": {
    "type": "invalid_request",
    "code": "amount_too_small",
    "message": "Amount must be at least 1.00 USD.",
    "param": "amount"
  }
}

HTTP Status	Error Type	Description
400	invalid_request	Missing or invalid parameters
401	authentication	Invalid or missing API key
403	permission_denied	Key does not have access to this resource
404	not_found	Resource does not exist
409	conflict	Resource is in an invalid state for this operation
429	rate_limit	Too many requests
500	server_error	Internal server error (retry with backoff)

Rate Limits

The API enforces rate limits to ensure fair usage and protect service stability.

Plan	Rate Limit	Burst
Standard	100 requests/second	200 requests
Enterprise	500 requests/second	1000 requests

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312200

429 responses

When rate limited, wait for the number of seconds indicated in theRetry-After header before retrying. Implement exponential backoff for production applications.

Idempotency

For POST requests, pass an Idempotency-Key header to safely retry requests without risk of duplicate operations.

curl -X POST https://dev-payment-gateway.mplex.net/api/v1/checkout-sessions \
  -H "Authorization: Bearer sk_live_your_server_key" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50.00, "currency": "USD"}'