Checkout API

The Checkout API is how developers integrate Seev's payment gateway directly into their own application. Developer checkout payments are initiated through SeevPlus so the organization, environment, and transaction can be recorded before the customer is redirected to checkout.

Who it's for

The Checkout API is the right choice if:

• You are building a web or mobile app and need payments as part of your own product flow
• You need to pass payment data programmatically — amount or items, customer info, payment channels, redirect URL, and gateway metadata
• You want to control the redirect and run your own post-payment logic (update a database, send confirmation emails, provision access)
• You're building a platform or marketplace where multiple merchants or customers transact through your app
• You need programmatic access to checkout initiation, status checks, and transaction history

If you just need to send someone a link or sell a product without writing code, use Payment Links or the Storefront instead.

API key requirement

Checkout API requests must be authenticated with a Checkout API key from the same environment you are using.

If you generate keys for multiple products, make sure you use the key created for Checkout API. Product keys are scoped to their own Seev services.

Before your first request

• Create checkout from a backend or server function, never directly from browser code.
• Keep your secret API key in server-side environment variables.
• Create and save your own order before requesting a checkout session.
• Choose a stable internal order ID for idempotency and reconciliation if you want retry protection.
• Prepare a callback route and a signed webhook endpoint.
• Start in sandbox and test success, failure, and repeated submission.

How it works

Your server          Seev API           Customer
    │                    │                  │
    │── create session ─▶│                  │
    │◀── checkout_url ───│                  │
    │                    │                  │
    │─── redirect ───────────────────────▶ │
    │                    │◀── pays ─────────│
    │                    │── redirect ─────▶│
    │                    │ (to redirect URL)│
    │◀── session ref ────────────────────── │
    │                    │                  │
    │── verify session ─▶│                  │
    │◀── result ─────────│                  │
    │                    │                  │
    │─── fulfil order ───────────────────▶ │

1. Your server creates a checkout session with the customer and order details.
2. Seev returns a checkout URL — redirect the customer there.
3. The customer completes payment using a method enabled on the hosted checkout page.
4. Seev redirects the customer back to your redirect_url with a session reference.
5. Your server verifies the session before fulfilling the order.

API routes

Use these routes from your backend.

Use https://api.seevplus.com as the base URL for Checkout API integrations.

Create a checkout session

curl -X POST "https://api.seevplus.com/api/v1/developer/payments" \
  -H "Authorization: Bearer $SEEV_CHECKOUT_API_KEY" \
  -H "Idempotency-Key: order_123_attempt_1" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "checkout",
    "recipient": {
      "name": "Kwame Asante",
      "email": "kwame@example.com"
    },
    "items": [
      {
        "name": "Web Development",
        "description": "Landing page design",
        "quantity": 1,
        "price": 800,
        "image": "https://example.com/web-development.png"
      },
      {
        "name": "Hosting (1 year)",
        "description": "Cloud hosting plan",
        "quantity": 1,
        "price": 200,
        "image": ""
      }
    ],
    "currency": "GHS",
    "channels": ["mobile_money", "crypto"],
    "redirect_url": "https://yourapp.com/payment/callback",
    "meta": {
      "orderId": "order_123"
    }
  }'

{
    "success": true,
    "data": {
        "amount": 1000,
        "channels": ["mobile_money", "crypto"],
        "checkout_url": "https://pay.seevplus.com/PAY-20260718-f23159df-9df8-4e69-8306-c11d71ead351",
        "currency": "GHS",
        "env": "production",
        "expires_at": "2026-07-18T21:08:46.776302Z",
        "items": [
            {
                "id": "f0c72f6b-59fc-4371-b68b-540f54d12f5b",
                "session_id": "d636387f-6872-469e-be31-76a79301fcb1",
                "name": "Web Development",
                "description": "Landing page design",
                "quantity": 1,
                "price": 800,
                "image": "https://example.com/web-development.png"
            },
            {
                "id": "62342bee-7eeb-4f31-984a-96718e2fd997",
                "session_id": "d636387f-6872-469e-be31-76a79301fcb1",
                "name": "Hosting (1 year)",
                "description": "Cloud hosting plan",
                "quantity": 1,
                "price": 200,
                "image": ""
            }
        ],
        "recipient": {
            "email": "kwame@example.com",
            "name": "Kwame Asante"
        },
        "redirect_url": "https://yourapp.com/payment/callback",
        "reference": "PAY-20260718-f23159df-9df8-4e69-8306-c11d71ead351",
        "status": "pending"
    },
    "request_id": "fb4f88c-9429-41d7-b3ca-5e4226a50736",
    "timestamp": "2026-07-18T20:38:46.779595765Z"
}

Payment initiation parameters

Idempotency behavior

If an initiation failed before checkout was created, use a new idempotency key for a deliberate retry.

Existing keys

SeevPlus stores only a one-way hash of newly issued checkout secrets. Checkout keys created before this route was introduced must be rotated once before they can authenticate here. Plaintext secret keys are never persisted.

This endpoint currently records and initiates payments only. Production outbound developer webhooks and durable gateway-event processing are intentionally outside this phase.

Verify the payment

Use the SeevPlus wrapper for gateway session lookup. Developers should use the gateway reference returned during initiation, or the corresponding session reference received after redirect.

No API key or Authorization header is required for this GET endpoint. A successful request returns the current gateway session payload, allowing clients to check payment status without calling the gateway API directly.

curl -X GET \
  "https://api.seevplus.com/api/v1/developer/payments/$SESSION_REF"

{
    "success": true,
    "data": {
        "id": "checkout_xyz",
        "reference": "PAY-20260701-abc123",
        "status": "completed",
        "amount": 10000,
        "final_amount": 10000,
        "currency": "GHS"
    }
}

Treat completed or success as paid. Treat pending, failed, or cancelled as not fulfilled.

For webhook-based verification (recommended for fulfilment), see Webhooks.

Supported payment methods

By default, all methods enabled for the checkout are shown. Mobile money is currently available for live checkout.

Card, direct bank-transfer checkout, and crypto should not be offered to a customer until they are selectable on the live checkout page.

See Payment Methods for current availability and customer instructions.

Common integration problems

The API returns unauthorized

Confirm that the key is a Checkout API key, belongs to the selected organization, and matches sandbox or production. A rotated, deleted, or partially copied secret will not work.

Checkout is created but the customer is not fulfilled

Do not fulfil from the redirect alone. Verify the session on your server and process a valid signed success webhook idempotently.

A retry creates another checkout

Generate one stable idempotency key for the logical order and reuse it for retries. Do not generate a new random key on every attempt.

Production is blocked

Complete organization verification, switch the Developer Dashboard to production, and create a separate production key. Sandbox credentials cannot process production activity.