Integration Flow

A complete Spayon integration requires 7 steps. Steps 1–4 happen server-side; steps 5–7 handle the async payment result.

Step-by-Step

Step	Action	Endpoint	Notes
1	Obtain Credentials	Admin Panel	Retrieve Client ID and Client Secret from Settings
2	Generate Token	POST /api/tokens	Bearer token valid for 1 hour — cache it server-side
3	Create Session	POST /api/product/session	Submit product and customer details; receive session_url
4	Redirect User	session_url	Immediately redirect the user to the Spayon-hosted payment page
5	Handle Callback	Your callback_url	Receive signed POST notification; verify X-Signature before processing
6	User Returns	Your return_url	User lands on your page; session_id is in the query string
7	Verify Status (optional)	GET /api/product/session/{id}	Cross-check session status if the callback was not received

Sequence Diagram

Your Server                    Spayon API                User Browser
     |                              |                          |
     |-- POST /api/tokens --------->|                          |
     |<-- access_token -------------|                          |
     |                              |                          |
     |-- POST /api/product/session->|                          |
     |<-- session_url, session_id---|                          |
     |                              |                          |
     |-- redirect to session_url -------------------------------->|
     |                              |<-- user completes payment--|
     |                              |                          |
     |<-- POST callback (signed) ---|                          |
     |-- 200 OK ------------------->|                          |
     |                              |-- redirect to return_url -->|

Key Behaviors to Implement

• Token caching: Store the Bearer token and refresh it before the 1-hour expiry. Do not generate a new token per request.
• Signature verification: Always verify the X-Signature on every incoming callback before acting on it.
• Idempotency: Callbacks may be delivered more than once (up to 3 retries). Use sessionId + status to make your handler idempotent.
• Cancel URL handling: A cancel redirect does not cancel the session — the session stays active for 15 minutes.
• Status check fallback: If your callback endpoint was unreachable, poll GET /api/product/session/{id} to recover the final status.