DOCSEARCHbyAlgolia
Submit Docs

Peak Gateway Documentation

website·Indexed 30 days ago

https://docs.peakgateway.co

Developer documentation for the Peak Gateway Public API (v1.0.0) and SDKs. Provides tools for online checkout, direct transactions, recurring billing, tokenization, and settlement reports. Includes guides for TypeScript, Kotlin, and Android SDKs, as well as integration paths for digital wallets (Apple Pay, Google Pay), POS gift cards, and webhook event management.

Tokens
45.4K
Snippets
186
Records
308
Agent score
49%

What's inside Peak Gateway

  1. Overview of Peak Gateway Public API Capabilities

    Peak Gateway provides public APIs and SDKs (TypeScript and Kotlin) covering the following functional areas:

    • OAuth 2.0 client credentials and API-key token exchange
    • Hosted checkout sessions and shopper payment
    • Transaction lifecycle: Sale, authorization, capture, refund, and void
    • Payment storage and recurring subscriptions
    • Digital wallets: Apple Pay and Google Pay configuration
    • Webhook management and delivery inspection
    • Reporting: Settlement, transaction, recurring-revenue, and monthly reports
    • SAML and OAuth client administration

  2. Reference the Transaction object schema

    The Transaction object represents a financial transaction within the Peak Gateway system. It includes details about the payment amount, status, payment method, and merchant attribution.
    {
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "SALE",
  "status": "APPROVED",
  "amount": 0,
  "tipAmount": 0,
  "transactionChannel": "VIRTUAL_TERMINAL",
  "totalAmount": 0,
  "currency": "USD",
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reference": "string",
  "approvalCode": "string",
  "cardBrand": "VISA",
  "lastFour": "string",
  "cardholderName": "string",
  "deviceId": "string",
  "metadata": {},
  "createdAt": "2024-07-29T15:51:28.071Z",
  "updatedAt": "2024-07-29T15:51:28.071Z"
}

  3. Peak Gateway Public API General Standards

    The Peak Gateway Public API (Version 1.0.0) provides endpoints for authentication, checkout, subscriptions, tokenization, webhooks, reporting, SAML management, and management portal proxy operations. When integrating with the API, adhere to the following data standards:

    • Amounts: All monetary amounts are represented as integers in cents (e.g., 100 for $1.00).
    • Currencies: Use ISO 4217 uppercase codes (e.g., "USD", "EUR").
    • Identifiers: Resource identifiers are opaque strings and must be preserved exactly as returned by the API.

  4. Understand Organization and Location authorization boundaries

    In Peak Gateway, an Organization serves as the business and authorization boundary. A Location belongs to exactly one organization and represents a concrete payment work site.

    • Use organizationId when interacting with shared resources and policies.
    • Use locationId for work specific to a single location.
    • Organization-scoped access automatically covers all descendant locations.
    • Location-scoped users and OAuth clients are restricted to their explicitly assigned locations.

  5. Understand the WalletTransactionData schema

    The WalletTransactionData object provides detailed information about a wallet transaction. It includes the transaction identifier, current status, response codes for debugging or auditing, and flags indicating if the transaction was partially approved or automatically voided.
    {
  "transactionId": "string",
  "status": "string",
  "responseCode": "string",
  "responseMessage": "string",
  "approvalCode": "string",
  "processedAmount": 0,
  "partiallyApproved": true,
  "autoVoided": true,
  "metadata": {}
}

  6. WebhookDelivery object schema reference

    The WebhookDelivery object provides details about a specific webhook delivery attempt, including its current status, the target URL, and retry information.

    Field Definitions:

    • id (string <uuid>, required): Unique identifier for the delivery record.
    • merchantId (string <uuid>, required): Identifier of the merchant associated with the webhook.
    • eventType (string, required): The type of event that triggered the webhook.
    • status (string, required): The current delivery state. Possible values: SUCCESS, FAILED, RETRYING.
    • targetUrl (string <uri>, required): The destination URL where the webhook was sent.
    • responseCode (integer, nullable): The HTTP response code returned by the target server. Valid range: 100 to 599.
    • attemptCount (integer, required): Number of delivery attempts made. Must be >= 1.
    • nextRetryAt (string <date-time>, nullable): The scheduled time for the next delivery attempt.
    • createdAt (string <date-time>, required): Timestamp when the delivery record was created.
    • updatedAt (string <date-time>, required): Timestamp when the delivery record was last updated.
    {
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "eventType": "string",
  "status": "SUCCESS",
  "targetUrl": "string",
  "responseCode": 0,
  "attemptCount": 0,
  "nextRetryAt": "2024-07-29T15:51:28.071Z",
  "createdAt": "2024-07-29T15:51:28.071Z",
  "updatedAt": "2024-07-29T15:51:28.071Z"
}

  7. Understand Checkout session tokens

    Shopper-facing payment requests use a session token associated with a specific checkout session. This token only authorizes that specific checkout flow and cannot be used for management access or as an OAuth client credential.

  8. Handle gift card lifecycle webhook events

    The gateway emits eight JSON payloads for gift card lifecycle events. All currency amounts are represented as integer cents in the gift card's currency (e.g., USD). Identifiers include string giftCardId and UUID strings for transaction IDs. You can subscribe via the merchant dashboard or the WebhookSubscriptionsApi in the SDK.

  9. Implement least-privilege authentication in Peak Gateway

    To maintain security and follow the principle of least privilege, exchange a location API key for a short-lived OAuth 2.0 token. When requesting the token, specify only the scopes required for the specific integration being implemented.

  10. Connect Claude Code to Peak Gateway docs MCP

    Add the Peak Gateway documentation MCP server to Claude Code using the following command. This provides an unauthenticated, read-only search surface for published documentation.
    claude mcp add --transport http peak-gateway-docs https://docs.peakgateway.co/mcp

  11. Install and initialize the Peak Gateway TypeScript SDK

    The @gateway/sdk package provides two clients: GatewayAdminClient for management, reporting, and webhooks (api.* boundary), and GatewayPayClient for hosted checkout and payment APIs (pay.* boundary). It supports server and modern web JavaScript runtimes with no runtime dependencies.

    Security Warning: Never place the clientSecret in browser-side code. Use a backend or a checkout session token for shopper-facing flows.

    npm install @gateway/sdk
    import { GatewayPayClient } from '@gateway/sdk'

const client = new GatewayPayClient({
  clientId: process.env.PEAK_CLIENT_ID!,
  clientSecret: process.env.PEAK_CLIENT_SECRET!,
  environment: 'production',
})

const session = await client.checkoutSessions.create({
  amount: 2500,
  currency: 'USD',
  locationId: process.env.PEAK_LOCATION_ID!,
  successUrl: 'https://example.com/checkout/success',
  cancelUrl: 'https://example.com/checkout/cancel',
})

console.log(`Send the shopper to ${session.checkoutUrl}`)

  12. Choose the correct Gateway SDK client

    The SDK provides two primary clients based on the target domain:

    • GatewayPayClient: Used for the payment domain, including checkout and machine integrations.
    • GatewayAdminClient: Used for the management domain for authorized organization administration.

    Warning: Do not use an admin client as a payment proxy. For browser-based sessions with authorized users, provide a tokenProvider to the GatewayAdminClient instead of embedding machine credentials.