Authentication

Your system signs in with an API key: a key id (mk_…) and a secret (ms_…). It exchanges them for an access token, and sends that token with every request.

Create an API key

In the portal, open Settings → API keys. Only Owners and Admins see it.
Give the key a name that says which system uses it, such as QuickBooks sync.
Under What it can do, tick only what that system needs (permissions).
Select Create key, then copy the key id and the secret. The secret is shown once. Mojo Payments keeps only a fingerprint of it, so a lost secret can’t be recovered: create a new key and revoke the old one.

An API key belongs to your organization, not to the person who made it: it keeps working when they leave.

Treat the secret like a password. Keep it in your system’s secret store, never in code, a URL, an email or a log.

Get an access token

Send the key to POST /oauth/token (the OAuth 2.0 client credentials grant):

curl https://api.paymentsmojo.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=mk_0123456789abcdef0123 \
  -d client_secret=ms_…

The body can also be JSON, or the key id and secret can go in an HTTP Basic Authorization header, as OAuth client libraries send them.

{
  "access_token": "eyJhbGciOiJSUzI1NiIs…",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "payments.create payments.view",
  "organization_id": "0b8f2d4e-5c1a-4e7b-9a63-2f1d8c4e7a90"
}

The token lasts 10 minutes (expires_in, in seconds). Keep using it until it expires, then get a new one; don’t get a new token for every request.
scope lists what the key can do. organization_id is your organization’s id.

Use the token

curl https://api.paymentsmojo.com/deposits -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs…"

Permissions

A key can do only what was ticked when it was made. A request for anything else gets 403.

Permission	In the portal	Lets the key
`payments.view`	Read invoices, card payments and deposits	List and read invoices, deposits and card payments
`payments.create`	Create, send and cancel invoices…	Create, send and cancel invoices, and remove customers’ saved cards
`locations.view`	Read locations	List and read locations
`accounts.view`	Read MIDs (merchant accounts)	List MIDs
`portfolio.view`	Read the merchants in your portfolio…	Resellers: list the merchants in the portfolio
`applications.view`	Read merchant applications submitted through you	Resellers: list and read those applications

You can give a key only what you can do yourself across the whole organization. Merchant permissions appear for merchants and reseller permissions for reseller partners.

Revoke a key

In Settings → API keys, select Revoke. New tokens are refused at once, and tokens already issued stop working within a minute (401 with the title API key revoked). Revoked keys stay in the list, marked with the date.

Token errors

Answer	Means
`401` `invalid_client`	Unknown key id, the wrong secret, a revoked key, or a suspended organization.
`400` `unsupported_grant_type`	Use `grant_type=client_credentials`.
`400` `invalid_request`	The key id and secret weren’t sent.
`429`	More than 30 token requests a minute from one address. Reuse tokens until they expire.

Get started

Using the API

Guides

API reference

Create an API key

Get an access token

Use the token

Permissions

Revoke a key

Token errors

​Create an API key

​Get an access token

​Use the token

​Permissions

​Revoke a key

​Token errors

Create an API key

Get an access token

Use the token

Permissions

Revoke a key

Token errors