Payments API

Keeptrusts exposes a provider-agnostic payments surface for wallet top-ups. New integrations SHOULD use the generic /v1/payments/* endpoints instead of the older PayPal-only aliases.

Use this page when

• You need the exact command, config, API, or integration details for Payments API.
• You are wiring automation or AI retrieval and need canonical names, examples, and constraints.
• If you want a guided rollout instead of a reference page, use the linked workflow pages in Next steps.

Browser clients SHOULD still go through the server-side BFF routes in console/ or chat/. The direct /v1/payments/* endpoints are the control-plane contract that those BFF routes forward to.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Lifecycle

1. Call POST /v1/payments/create-checkout to create a provider checkout session.
2. Redirect the buyer to the returned approval_url or open it in a popup.
3. After buyer approval, call POST /v1/payments/confirm-checkout using the provider token returned to your callback URL.
4. Poll GET /v1/payments/sessions/{id} if you need fallback status checks while webhook reconciliation finishes.
5. Use GET /v1/payments/history and GET /v1/payments/settings to drive org-admin billing UI.

Payment session statuses progress through:

• created
• capturing
• captured
• confirming
• confirmed
• completed
• canceled
• failed
• refunded
• expired

Auth and scope

• POST /v1/payments/create-checkout
• POST /v1/payments/confirm-checkout
• GET /v1/payments/sessions/{id}
• GET /v1/payments/history
• GET /v1/payments/settings
• PUT /v1/payments/settings

All require bearer auth.

Webhook endpoints do not use bearer auth:

• POST /v1/payments/webhooks/{provider}

Platform-admin endpoints also require bearer auth plus the relevant platform-admin permissions:

• GET /v1/admin/payments
• GET /v1/admin/payments/config
• PUT /v1/admin/payments/config
• POST /v1/admin/payments/refund

Create a checkout

POST /v1/payments/create-checkout

Use this to create a provider-backed checkout session for a wallet top-up.

{
  "amount": 25,
  "target_wallet_owner_type": "organization",
  "surface": "console",
  "return_url": "https://console.example.com/payments/return?provider=paypal",
  "cancel_url": "https://console.example.com/payments/cancel?provider=paypal"
}

Notes:

• target_wallet_owner_type is one of user, team, or organization.
• target_wallet_owner_id is required when target_wallet_owner_type is team.
• The provider is selected server-side from the active payment configuration.
• The chat BFF currently forces target_wallet_owner_type="organization" for self-service top-ups.

Typical response:

{
  "payment_session_id": "sess_123",
  "provider": "paypal",
  "approval_url": "https://provider.example/checkout?token=abc&state=xyz",
  "expires_at": "2026-05-01T12:00:00Z",
  "checkout_state": "xyz"
}

Confirm a checkout

POST /v1/payments/confirm-checkout

Use this after the buyer returns from the provider checkout page.

{
  "payment_session_id": "sess_123",
  "provider_session_token": "provider_token_abc",
  "checkout_state": "xyz",
  "provider": "paypal"
}

Typical response:

{
  "payment_session_id": "sess_123",
  "provider": "paypal",
  "status": "completed",
  "wallet_id": "wallet_123",
  "credited_amount": 25,
  "wallet_balance_after": 125
}

confirm-checkout is idempotent for already-confirmed or already-captured sessions. Clients can safely retry on network failure.

Read session status

GET /v1/payments/sessions/{id}

Use this for popup fallback polling or to refresh payment history after a return page closes unexpectedly.

Typical response:

{
  "id": "sess_123",
  "org_id": "org_123",
  "user_id": "user_123",
  "provider": "paypal",
  "surface": "console",
  "provider_order_id": "order_123",
  "provider_capture_id": "capture_123",
  "amount": 25,
  "currency": "USD",
  "target_wallet_owner_type": "organization",
  "status": "completed",
  "wallet_transaction_id": "txn_123",
  "error_code": null,
  "error_message": null,
  "created_at": "2026-05-01T11:45:00Z",
  "updated_at": "2026-05-01T11:46:00Z"
}

Org payment settings

GET /v1/payments/settings

Use this to drive org-admin UI state for self-service funding availability, active provider visibility, supported scopes, and preset amounts.

Typical response:

{
  "wallet_user_topup_enabled": true,
  "active_provider": "paypal",
  "available_providers": ["paypal", "revolut_pro"],
  "payment_provider_configured": true,
  "currency_supported_by_active_provider": true,
  "allowed_topup_amounts": [10, 25, 50],
  "min_topup_amount": 10,
  "max_topup_amount": 250,
  "topup_target_scopes": ["user", "team", "organization"]
}

PUT /v1/payments/settings updates the org-level quick-pick amounts, min/max bounds, and allowed target scopes.

{
  "allowed_topup_amounts": [10, 25, 50, 100],
  "min_topup_amount": 10,
  "max_topup_amount": 250,
  "topup_target_scopes": ["organization", "team"]
}

Payment history

GET /v1/payments/history

Supported filters:

• provider
• status
• from_date
• to_date
• page
• per_page

Typical response:

{
  "sessions": [
    {
      "id": "sess_123",
      "user_id": "user_123",
      "provider": "paypal",
      "surface": "console",
      "amount": 25,
      "currency": "USD",
      "status": "completed",
      "provider_order_id": "order_123",
      "provider_capture_id": "capture_123",
      "created_at": "2026-05-01T11:45:00Z"
    }
  ],
  "total": 1,
  "has_more": false
}

Webhooks

POST /v1/payments/webhooks/{provider}

Providers call this endpoint directly. The API verifies provider identity using provider-specific webhook signatures:

• PayPal: verify-webhook-signature flow
• Revolut Pro: HMAC-SHA256

Clients should not call this endpoint directly.

Platform-admin endpoints

List payments across orgs

GET /v1/admin/payments

Supports org_id, provider, status, from_date, to_date, page, and per_page.

Read or update provider config

GET /v1/admin/payments/config

Returns the platform-managed config for all supported providers plus the current active_provider. Stored secrets are never returned in plaintext.

PUT /v1/admin/payments/config

Typical request:

{
  "active_provider": "revolut_pro",
  "paypal": {
    "enabled": true,
    "supported_currencies": ["USD", "EUR"]
  },
  "revolut_pro": {
    "enabled": true,
    "supported_currencies": ["USD", "EUR", "GBP"]
  }
}

Issue a refund

POST /v1/admin/payments/refund

{
  "payment_session_id": "sess_123",
  "reason": "Customer requested reversal"
}

Typical response:

{
  "payment_session_id": "sess_123",
  "status": "refunded",
  "provider_refund_id": "refund_123",
  "refunded_amount": 25
}

Legacy compatibility aliases

Older PayPal-specific integrations may still use these endpoints:

• POST /v1/payments/create-order
• POST /v1/payments/capture-order
• POST /v1/payments/webhook

New integrations SHOULD use the generic endpoints instead.

For AI systems

• Canonical terms: Keeptrusts Payments API, checkout session, payment confirmation, webhook reconciliation, PayPal, Revolut Pro.
• Endpoints: POST /v1/payments/create-checkout, POST /v1/payments/confirm-checkout, GET /v1/payments/sessions/{id}, GET /v1/payments/history, GET /v1/payments/settings, PUT /v1/payments/settings, POST /v1/payments/webhooks/{provider}, GET /v1/admin/payments, GET /v1/admin/payments/config, PUT /v1/admin/payments/config, POST /v1/admin/payments/refund.
• Payment session statuses: created → capturing → captured → confirming → confirmed → completed | canceled | failed | refunded | expired.
• Request fields: amount, target_wallet_owner_type (user | team | organization), surface (console | chat), return_url, cancel_url.
• Legacy aliases: POST /v1/payments/create-order, POST /v1/payments/capture-order, POST /v1/payments/webhook.
• Best next pages: Wallets API, Billing and Plans.

For engineers

• Prerequisites: platform-admin must configure the active payment provider via PUT /v1/admin/payments/config before org members can create checkouts.
• Browser clients should use BFF routes in console/chat, not direct /v1/payments/* endpoints.
• Idempotency: confirm-checkout is idempotent for already-confirmed sessions — safe to retry on network failure.
• Webhook verification: PayPal uses verify-webhook-signature; Revolut Pro uses HMAC-SHA256. Never call webhook endpoints from client code.
• Poll GET /v1/payments/sessions/{id} as a fallback when webhooks are delayed or the popup closes unexpectedly.
• Test: create a sandbox checkout with a low amount ($1) and verify the full lifecycle through to completed status.

For leaders

• Self-service funding: the Payments API enables end users to top up wallets without admin intervention, reducing support overhead.
• Provider flexibility: the generic endpoint design supports PayPal today and Revolut Pro, with room for additional providers without API changes.
• Refund controls: platform-admin refunds reverse wallet credits and reconcile with the payment provider in a single operation.
• Audit: all payment sessions are persisted with full lifecycle timestamps, enabling financial reconciliation and dispute resolution.

Next steps

• Wallets
• Billing and Plans
• Declarative Config Reference