Skip to main content

​
Bearer tokens

Every request to the Dime Payments API requires an Authorization header with a Bearer token:
Tokens are Laravel Sanctum personal access tokens. They are minted inside the Dime Payments dashboard, not via the API itself.

​
Getting a token

  1. Log into the Dime Payments dashboard
  2. In the sidebar, open Advanced > API keys (/user/api-tokens)
  3. Click to create a token, select its abilities, and generate it
  4. Copy the token immediately — it will not be shown again
API access is gated. If your account does not have API access enabled, the API keys item links out to the developer onboarding page instead of the token screen. If you land on the marketing page rather than a token generator, contact your Dime Payments rep to have API access switched on for your account.

​
Token abilities

Every token carries a set of abilities that control which endpoints it can access. You choose these abilities yourself with checkboxes when you mint the token — there is also a payments quick-select preset that grants the common charging scopes in one click. If a token lacks the ability an endpoint requires, the request is rejected (see Permission errors). Two things about the ability model are easy to get wrong: Reading and charging are separate. transaction:read lets a token list and look up transactions, deposits and recurring payments, and nothing else: it cannot charge, refund or change anything, so it is the one to give a reporting or bookkeeping tool. transaction:charge-card-token gates charging a card, charging ACH, refunds, voids, tokenization and changes to recurring payments. There is no separate charge-ach, charge-card-pan, refund, or void scope.
Before October 2026 the read endpoints asked for transaction:charge-card-token (and deposits for no ability at all). Every token that existed then was given transaction:read, so existing integrations kept working; tokens created since get it only if it is left ticked when they are made (it is ticked by default).
Write scopes are granular, not a single :write. Customer, merchant, and invoice writes are split by operation (create, update, delete), not bundled under one :write ability.

​
Merchant token scopes

A merchant API token (minted under Advanced > API keys) can carry any of these 28 scopes:

​
Affiliate key scopes

Affiliate API keys carry a different set of 24 scopes. They add the merchant:* family (affiliates provision merchants) but do not include any subscription or subscription-plan scopes, and their invoice set is smaller:
When you create an affiliate key, 5 of these scopes are pre-checked as sensible defaults (reading and charging payments, and reading and creating customers). That default selection is just a starting convenience — you can check or uncheck any of the 24 before generating the key.

​
Scopes that are easy to miss

  • Held funds are affiliate-only. funds:read and funds:release are not offered on merchant tokens, and POST /api/funds/release rejects any key that is not an affiliate key, even one that somehow carries the scope. Releasing held funds is the affiliate’s decision. See Held funds.
  • Chargebacks and documents work on both kinds of key. chargeback:read reads disputes; document:create and document:read upload and list a merchant’s documents.
  • The ACH refund override has no scope of its own. override_ach_settlement_wait is a field on POST /api/transaction/refund, so any token with transaction:charge-card-token can send it. See Response Codes for when to use it.

​
Keeping tokens secure

  • Never expose tokens in client-side code or public repositories
  • Use environment variables to store tokens in your application
  • Generate separate tokens for production and staging environments
  • Rotate tokens immediately if you suspect they have been compromised

​
Example request

​
Permission errors

When a token is missing, invalid, or lacks the required ability, the API returns a permission error. The exact shape is not uniform: Handle both shapes when checking for authorization failures. See Response Codes for the full breakdown.

​
Next steps