Skip to content

OAuth apps

Let other sellers connect your integration to their store with only the permissions they approve.

An OAuth app lets your integration work with other sellers’ stores. The seller approves your app on a Paysum page and picks one store; your app then receives a store API key (sk_…) limited to the permissions they allowed. That key works on every Store API endpoint and the MCP server. For your own store only, an API key is simpler.

1. Create the app

In the dashboard, open Integrations → OAuth apps and click New app.

  • App name: sellers see it when they approve.
  • Redirect URLs: where sellers return after they decide. Use https:// (or http://localhost while you build). Up to 10.
  • Permissions: everything your app may ask for. Sellers can untick any of them.

You get a client ID (pca_…) and a client secret (pcs_…). The secret is shown once. Keep it on your server. Click New secret to replace it; the old one stops working at once.

2. Send the seller to approve

https://dashboard.paysum.io/oauth/authorize?client_id=pca_…&redirect_uri=https://yourapp.com/paysum/callback&state=RANDOM
ParameterRequiredWhat it is
client_idYesYour app’s client ID.
redirect_uriYesExactly one of the app’s redirect URLs.
stateRecommendedA random value. Check that it comes back unchanged.
code_challenge, code_challenge_method=S256OptionalPKCE, for apps that also run on a device.

The seller signs in, picks a store, reviews the permissions and clicks Allow or Deny. We send them back to your redirect URL with ?code=…&state=…, or ?error=access_denied.

3. Swap the code for a key

Do this from your server within 5 minutes. Each code works once.

curl -X POST https://api.paysum.io/api/oauth-apps/token \
  -d grant_type=authorization_code \
  -d code=CODE_FROM_REDIRECT \
  -d redirect_uri=https://yourapp.com/paysum/callback \
  -d client_id=pca_… \
  -d client_secret=pcs_…
{
  "access_token": "sk_…",
  "token_type": "Bearer",
  "scope": "products:read orders:read",
  "store": { "id": "…", "name": "Nova Supply", "slug": "nova-supply" }
}

Send the key as Authorization: Bearer sk_… on Store API requests. Keep one key per store. If the seller approves your app again for the same store, the old key is replaced.

Access ends when

  • the seller clicks Disconnect under Integrations → OAuth apps, or deletes the key under API keys;
  • the seller who approved it loses access to the store;
  • you delete the app (every store’s key stops working).

Requests with a revoked key get 401 api_key_disabled or invalid_api_key. Ask the seller to connect again.