API
Send payment events
Send server-side payments, refunds and corrections to Premely's revenue ledger with the Payment Events API.
What it is
The Payment Events API lets a server-side payment system append payments, refunds, disputes, dispute reversals and corrections to the canonical Premely revenue ledger when a native provider connection is not the right fit.
Why use it
Use this API for a custom payment flow or provider that needs reliable revenue context in Premely without exposing payment credentials or customer identity in the browser.
Before you start
- Use a secure server environment. Never send a workspace API token from browser code or publish it in a client application.
- Create a workspace token with only the
revenue:writescope and identify the Premely site that should receive the event.
How to use it
- 1
Create a revenue-only token
In Settings, open API and create a named token with the
revenue:writescope. Copy it when shown and store it in your server's secret manager.Product screenshot placeholderDeveloper settings - Payment Events API
Capture focus: Token scope, endpoint and event delivery
1revenue:write2Endpoint3Event statusReplace this slot with the matching production surface and numbered callouts before publishing. - 2
Send the event to the site endpoint
From your server, send a
POSTrequest to/v1/sites/{siteId}/revenue/eventsusing the workspace token for the matching Premely site. - 3
Include a safe, retry-ready payload
Use a UUIDv7
Idempotency-Key, an allowed event type, a signed integer amount in minor units, one uppercase three-letter currency and the event time. Add an attribution hash only when you have one from Premely. - 4
Handle the response before retrying
Keep the same request body and idempotency key for a network retry. An identical repeat is returned as
duplicate; changing a reused identifier causes a conflict instead of changing the recorded event.
Payment request example
Send the request from a trusted server. The same UUIDv7 Idempotency-Key must be reused only when retrying this exact method, path and body.
curl --request POST 'https://api.premely.io/v1/sites/SITE_ID/revenue/events' \
--header "Authorization: Bearer $PREMELY_API_TOKEN" \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 0198f8f0-1234-7abc-8def-0123456789ab' \
--data '{
"source_provider": "custom",
"provider_account_id": "account_123",
"provider_event_id": "event_123",
"provider_ledger_entry_id": "ledger_123",
"transaction_id": "order_123",
"kind": "payment",
"amount_minor": 4900,
"currency": "GBP",
"occurred_at": "2026-08-10T12:00:00Z"
}'Payment event fields
| Field | Required | What to send |
|---|---|---|
source_provider | Yes | Lowercase provider name, such as custom or your provider identifier. |
provider_account_id | Yes | Stable provider account identifier. Premely hashes it before storage and never returns it. |
provider_event_id | Yes | Unique identifier for the source event. |
provider_ledger_entry_id | Yes | Unique identifier for the financial ledger entry. |
transaction_id | Yes | Your stable order, payment or transaction identifier. |
kind | Yes | payment, refund, dispute, dispute_reversal or correction. |
amount_minor | Yes | Signed minor units. Payments and dispute reversals are positive. Refunds and disputes are negative. Zero is rejected. |
currency | Yes | Uppercase three-letter currency code, such as GBP or USD. |
occurred_at | Yes | ISO 8601 event time. |
attribution_hash | No | A 64-character Premely attribution hash. Never substitute customer identity or personal data. |
What to expect
Revenue entries are immutable
Accepted payment events append to the revenue ledger. Send a refund, dispute reversal or correction event when a later business event changes the revenue story.
Currencies remain separate
Premely does not silently combine currencies. Send each event in its actual currency and review reporting in the relevant currency context.
Customer identity is not accepted
Do not send raw visitor or customer identifiers. Payment event attribution accepts an optional Premely attribution hash instead.
Useful ways to apply this
A custom checkout
Record a completed server-confirmed payment after the payment provider reports the final outcome to your backend.
A finance correction
Append a refund, dispute or correction event so reports reflect the commercial event without rewriting the original payment.