Skip to main content

Getting Started

This guide creates an OAuth access token and uses it to open a hosted checkout session.

1. Provision OAuth client credentials

Create a test OAuth client in the Peak Gateway dashboard or ask your organization administrator to provision one. Store the returned clientId and one-time clientSecret in a server-side secret manager. Production uses a separate client and secret.

Grant only the scopes your integration needs. The checkout request below needs hosted-payments:write.

2. Mint an access token

Use the OAuth 2.0 client credentials grant from a trusted backend:

curl -sS -X POST "https://api.peakgateway.co/auth/oauth2/token" \
  -u "${PEAK_CLIENT_ID}:${PEAK_CLIENT_SECRET}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=hosted-payments:write"

Read access_token and expires_in from the response. Never put the client secret in browser or mobile code.

If your organization issued a Gateway API key instead, exchange it for a short-lived access token:

curl -sS -X POST "https://api.peakgateway.co/auth/oauth2/api-key/token" \
  -H "X-Api-Key: ${PEAK_API_KEY}"

3. Install an SDK

TypeScript

npm install @gateway/sdk

Kotlin and Android

Published Maven artifacts use group com.myriad.gateway:

  • JVM/KMP: gateway-sdk-core-kmp
  • Android: gateway-sdk-android
  • Optional NearPay Android rail: gateway-sdk-android-nearpay

See SDKs & Libraries before selecting Android dependencies.

4. Create a checkout session

Amounts and line-item prices are integer minor units. This example creates a USD 49.99 checkout:

curl -sS -X POST "https://pay.peakgateway.co/api/v1/checkout/sessions" \
  -H "Authorization: Bearer ${PEAK_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4999,
    "currency": "USD",
    "description": "Starter plan",
    "successUrl": "https://example.com/success",
    "cancelUrl": "https://example.com/cancel",
    "lineItems": [
      {
        "name": "Starter plan",
        "quantity": 1,
        "unitPrice": 4999
      }
    ],
    "locationId": "loc_123"
  }'

currency is required. amount, return URLs, line items, and merchant/location context depend on the checkout you are building; consult the generated request schema before adding optional fields.

5. Continue the payment flow

Redirect the shopper to the hosted checkout URL from the session response. The shopper-facing pay route uses the checkout session token, not your OAuth client secret. Confirm the final outcome through the session response and configured webhooks rather than trusting a browser redirect alone.

Next steps

  • Review Authentication for token and scope boundaries.
  • Review the generated checkout-session and payment schemas.
  • Configure and verify webhook signatures before processing async updates.
  • Use an idempotency key on supported transaction, capture, refund, and void requests.