1. Declare your purpose

When you register an API key you choose what you are building. That choice decides which endpoints you can call, how settlement works, and what your own system must provide in return. A key may carry one purpose or both.

Unsure which applies? Ask whether the customer ends up holding something you deliver (goods and services) or a balance inside your platform (in-platform tokens). A game selling tournament entries is the second. A shop selling headphones is the first. An application that does both selects both.

2. Two sets of credentials

These are different things, used at different moments. Confusing them is the most common integration failure.

Both are issued together when you create an API key. The client id is shown permanently in your dashboard; both secrets are shown once. If you lose the OAuth client secret, regenerate it — there is no way to read it back.

3. Goods and services

Escrow settlement

Payment is initialised server-to-server with your API key. VeightCoin™ is held in Atomic Escrow from the moment the customer pays until delivery is confirmed. Confirmation is manual: the buyer confirms receipt, or the confirmation window expires and escrow releases automatically. Both parties are notified at every step.

The protocol does not handle shipping or delivery tracking. It holds the funds and releases them.

POST /api/merchant/payment/initialize
Authorization: Bearer <api_key>
X-API-Signature: <hmac_sha256(raw_body, signing_key)>

No OAuth2 is required here. The customer authorises the payment on VeightPay™'s own hosted flow, not through a wallet link.

4. In-platform tokens

Paired ledgers

Two ledgers move together: VeightCoin™ between VeightPay™ wallets, and your own in-platform balance between your accounts. Every operation touches both, and the two must agree afterwards.

Read the direction column carefully. A deposit moves VeightCoin™ away from the user and gives them platform credit in exchange. A payout is the reverse.

5. Deposit — the user pays in

1. The user chooses an amount on your platform. Nothing has moved yet.
2. You send them to VeightPay™ to authorise, using the OAuth2 flow below. If their wallet is already linked, you hold an access token for them.
3. VeightPay™ calls your verification endpoint. If you decline or do not answer, nothing moves.
4. VeightCoin™ moves from the user's wallet to yours. Both wallets are locked and the balance checked; the transfer completes in full or not at all.
5. On a success response, credit the user's in-platform balance with the same amount.

POST /api/v1/add
Authorization: Bearer <user_access_token>
X-API-Signature: <hmac_sha256(raw_body, signing_key)>
Idempotency-Key: <your_unique_reference>

{ "amount": "25.00" }

6. Payout — the user cashes out

You approve this, not the user — manually, automatically, or both, however you configure your platform. Because you are the approving party, you must check that the user holds enough eligible in-platform balance. VeightPay™ cannot see your balances and will not check them for you. It checks that your VeightPay™ wallet can cover the payout.

1. The user requests a payout. You verify their in-platform balance is sufficient and eligible under your own rules.
2. You approve, by hand or by rule.
3. You debit their in-platform balance to your own account, so your books balance before any VeightCoin™ moves.
4. VeightPay™ calls your verification endpoint to confirm the payout is authorised.
5. VeightCoin™ moves from your wallet to theirs.

POST /api/v1/withdrawal
Authorization: Bearer <user_access_token>
X-API-Signature: <hmac_sha256(raw_body, signing_key)>
Idempotency-Key: <your_unique_reference>

{ "amount": "25.00" }

7. Your verification endpoint

In-platform token integrations must expose an endpoint VeightPay™ calls before completing any transfer. It keeps both ledgers in step: we do not move VeightCoin™ unless your system confirms it expects the movement. It also carries your authorisation for payouts.

POST https://your-app.example/veightpay/verify
X-VeightPay-Signature: <hmac_sha256(raw_body, signing_key)>
X-VeightPay-Timestamp: 1787512201

{
  "event_id":        "...",
  "operation":       "deposit",
  "idempotency_key": "...",
  "amount":          "25.00",
  "user_id":         "...",
  "timestamp":       1787512201
}

Respond 200:
{ "approved": true, "reference": "your-internal-ref" }

• Verify the signature on every call before acting on the contents. The timestamp is inside the signed body — reject anything more than five minutes old, or a captured request replays forever.
• Approval must be explicit. A bare 200 does not count. A misconfigured catch-all route returns 200 for anything, so we require "approved": true.
• Answer within 5 seconds. A user is watching a spinner; slower and you have traded a security control for an abandoned checkout.
• Expect at most two retries — 1s then 3s — on timeout, transport failure or 5xx only, never on a clean refusal. Each carries the same idempotency_key, so return your cached answer rather than treating it as a new authorisation.
• No answer means no transfer. We fail closed.

POST <your transfer settlement webhook URL>
X-VeightPay-Signature: <hmac_sha256(raw_body, signing_key)>
X-VeightPay-Event: transfer.settled
{
  "event":                 "transfer.settled",
  "idempotency_key":       "...",
  "operation":             "deposit",
  "amount":                "25.00",
  "status":                "completed",
  "transaction_reference": "...",
  "user_id":               "...",
  "timestamp":             1787512201
}

Reconciling a missed settlement

Query any transfer with the idempotency key you sent. Authenticated with your REST API key, and scoped to your own transfers — you cannot see another merchant's.

GET https://www.veightpay.com/api/v1/transfers/<idempotency_key>
X-API-Key: <your_api_key>
{
  "success": true,
  "data": {
    "idempotency_key":       "...",
    "operation":             "payout",
    "status":                "completed",
    "status_code":           200,
    "transaction_reference": "...",
    "amount":                "25.00"
  }
}

8. Linking a wallet with OAuth2

A standard authorization-code flow. The two parts people get wrong are the redirect URI and the state parameter.

1. Generate a state value — random and unguessable — and store it in the user's session. This is what stops an attacker feeding your callback a code of their choosing.
2. Send the user to the authorize endpoint with your client id, registered redirect URI, response_type=code, the scopes you need, and the state.
3. The user approves. They see exactly which permissions you requested and choose whether to grant them.
4. Verify the returned state against the session value and abandon the flow if they differ. Only then exchange the code.
5. Store the tokens against the user. You receive an access token, a refresh token and an expiry.

GET https://veightpay.com/oauth/authorize
      ?client_id=<your_client_id>
      &redirect_uri=<your_registered_uri>
      &response_type=code
      &scope=get-balance+withdraw-balance
      &state=<state>

POST https://veightpay.com/oauth/token

grant_type=authorization_code
client_id=<your_client_id>
client_secret=<your_client_secret>
redirect_uri=<the same URI, byte for byte>
code=<code>

Matching the wallet to the right person

A linked wallet is where a user's money leaves your platform. Before you store that link, confirm the VeightPay™ account belongs to the same person as the account on your side.

POST /api/v1/balance returns the account holder's name and email under the get-balance scope. Compare both against your own record, and refuse the link if either differs.

POST /api/v1/balance
Authorization: Bearer <user_access_token>

{
  "data": {
    "name":    "Ada Lovelace",
    "email":   "ada@example.com",
    "phone":   "+44...",
    "balance": "125.00"
  }
}

Where the link comes from

A user who completes a deposit has already signed in to VeightPay™ and consented, so their wallet is linked from that moment — there is no separate linking step to ask them for.

At payout time, check whether a link exists before you debit anything. If it does not, send the user through the authorization flow rather than failing the request: a payout with no linked wallet has nowhere to send money, and approving one debits your books against a transfer that cannot happen.

9. Scopes

Scopes describe what a user is granting you. Request only what you need — the consent screen lists them, and a narrower request is more likely to be approved and less damaging if a token leaks.

Each API key carries an allowlist of the scopes it may request. Asking for a scope outside your allowlist fails at the authorize step, before any code is issued — not later with a confusing permission error.

Changing a key's purpose changes its allowlist. Adding a purpose has no effect on existing tokens: new scopes become requestable, but a token never widens on its own — the user must consent again. Removing a purpose takes effect immediately, including for tokens already issued, and we notify you so you learn from a message rather than a wave of 401s.

10. Idempotency, revocation and failures

Idempotency

Send an Idempotency-Key on every transfer, unique per logical operation and stable across retries — your own reference for that deposit or payout is usually right. Without one, a timed-out request leaves you unable to tell whether the transfer happened: retrying may move the money twice, not retrying may leave a user paid but uncredited.

Revocation

Revoking or deleting an API key revokes its OAuth2 client and every token issued through it, immediately. A user can also withdraw consent from their own account without telling you — treat a 401 on a previously working token as "this user unlinked", not as an outage.

Common failures

Documentation and support

Endpoint reference, request and response examples and your credentials live inside your dashboard once you register as a merchant. Need help? Use in-app support or the Help Center.