Skip to main content
The partner API is for platforms that move money for their own customers through Platnova: payouts, checkouts with itemised bookings, line refunds, travel bookings and bill payments. It adds a few rules to the standard API. These rules apply only to businesses that Platnova has set up as partners.
Partner access is enabled per business and per product by Platnova. If you are not set up as a partner, partner routes answer 403 with data.code partner_product_disabled. Contact [email protected] to be set up.

​
Base URLs

​
Authentication: header only

Send your API key in the X-API-Key header. On /v1/partner/* a key in the URL (?api_key=) is refused with 401 api_key_in_query, because URLs end up in proxy logs, CDN logs and browser history. Elsewhere it still works but is deprecated.
Partner routes accept API keys only. A dashboard session gets 403 api_key_required.

​
Responses

Every response has the same shape:
Switch on data.code, never on message. Codes are a contract and do not change. Messages are written for people and may be reworded. See the error catalogue.

​
Idempotency-Key

Every request that moves money needs an Idempotency-Key header: a payout, a bulk payout, a checkout, a travel order, a travel cancellation, an eSIM purchase or top-up, and an experience order or cancellation.
  • Missing: 400 idempotency_key_required.
  • Same key, same body: you get the first answer again, with the header Idempotent-Replayed: true. Nothing runs twice.
  • Same key, different body: 422 idempotency_key_reused.
  • Same key while the first request is still running: 409 request_in_progress with Retry-After. Nothing ran, so retry with the same key.
Use one key for each action your user takes, and reuse it on every retry of that action.

​
partner_reference

Every partner write carries your own partner_reference. It is 1 to 128 characters with no spaces, and it is unique within your business for each kind of write (checkout, payout, travel order). It is how you look the write up again and how support traces it.
  • Same reference, same body: returns the first result.
  • Same reference, different body: 409 partner_reference_reused.
  • The first request with this reference is still running: 409 request_in_progress.
  • A refused payout or travel order keeps its reference. To try again, send a new reference.
Look a write up by its reference:
  • GET /v1/partner/payouts/{partner_reference}
  • GET /v1/partner/checkouts/{partner_reference}
  • GET /v1/partner/travel/orders/{partner_reference}

​
Limits

Platnova sets these limits for each product (checkout, payout, refund, travel, eSIM, experiences): A refused request moves no money.

​
Products

Payouts

Single and bulk bank payouts with a name check.

Checkout and refunds

Itemised checkouts and refunds by line.

Travel

Book flights and hotels paid from your wallet or a paid checkout.

eSIM

Sell data eSIMs with a single-use install link.

Experiences

Sell event tickets with a single-use ticket link.

Webhooks v2

Signed events with one envelope, history and redelivery.
Betting wallet top-ups are documented in Bills: betting. They use the same API key and webhook endpoint.