Skip to main content

Security

What the protocol protects, what it leaves to you, and how to keep both sides honest.

Secrets​

  • The cash desk secret signs every request and every callback. It is shown once, at creation or rotation, and stored encrypted on our side: nobody at the platform can read it back.
  • Keep it in a secret store or an environment variable on the server that signs. It must never reach a browser, a mobile app, a repository, or a log line.
  • The key is not a secret. It may be logged and appears in the cabinet. Leaking it lets nobody do anything.
  • Rotate when a person with access leaves, when the secret may have been logged, or on a schedule. Rotation is immediate: sign with the new secret from the moment it is issued, and verify callbacks with it. A callback signed with the old secret is not sent again by the platform, so rotate at a quiet moment or accept both secrets for a few minutes.

Requests​

  • The signature covers the method, the path, a timestamp, a nonce and the body hash. A captured request cannot be replayed after 300 seconds, cannot be replayed at all within them, and cannot be redirected to another endpoint or altered on the way.
  • Use HTTPS. The signature does not encrypt: an http:// request exposes the body, and the body contains customer data.
  • Keep the server clock synchronised. Skew over 300 seconds fails every request.

Callbacks​

  • Verify the signature against the raw body before you act. Without this, anyone who learns your callback URL, which is not secret, can mark your orders paid.
  • Use a constant-time comparison for the signature.
  • Drop repeated event ids. The same event may be delivered more than once.
  • Check the timestamp if you want protection against a replay of an old, genuine callback: reject X-Gate-Ts older than, say, ten minutes.
  • Do not trust the body for money. The callback says the order completed; the amounts in it match the order, but if you reconcile balances, use GET /gw/v1/orders/{id} or the cabinet export as the source and the callback as the trigger.
  • Prefer an https:// callback URL with a valid certificate. We accept http:// but the event and its signature then travel in the clear.

Customer data​

  • The payment page shows only what the customer needs to pay. It never shows the merchant, the provider, or internal identifiers.
  • The gateway never returns the customer's own details; it returns the details the customer must pay to.
  • Card numbers shown to customers belong to providers, not to customers, and are not PAN data in your systems unless you copy them there. Do not.

What the platform does on its side​

  • Every balance change is an atomic database update with an audit row; there is no read-modify-write anywhere in the money path.
  • A completed order is claimed atomically, so a duplicate provider confirmation cannot credit twice.
  • Live orders wait for the platform to confirm that funds actually arrived before the credit and the callback.
  • Callback URLs are checked for private and internal addresses at creation and again before every delivery.
  • Provider webhooks are either signed by the provider or accepted only from allowlisted addresses; the cascade refuses an unsigned webhook from an unknown source.

Support accounts​

A support account is a separate login for a colleague. It sees orders, cash desks, appeals and the balance, can open appeals and resend callbacks, but cannot manage other accounts or withdraw. Support accounts can create cash desks and rotate secrets; give them to people who should be able to.