WinPay Integration — Getting Started

Welcome. These pages contain everything you need to add deposits and withdrawals with WinPay to your site. Ten minutes to read, about half a day of work for one developer.

Who am I?

Manager / product owner → read System workflow (5 minutes), then share it with your team.

Backend developer → the Integration guide walks through the code step by step; field definitions are in the API reference.

QA / testing → run the list on Testing, FAQ, troubleshooting top to bottom.

The 30-second version

Member clicks "Deposit" on your site
        ↓
Your site sends WinPay one request → gets a payment link back
        ↓
You redirect the member to that link; they see an IBAN and a QR code and pay from their bank
        ↓
Once the payment is verified, WinPay sends your site a signed notification (callback)
        ↓
Your site credits the member's balance ✅

Withdrawals work the same way: your site sends a withdrawal request with the member's IBAN, the money is sent, a callback arrives, your site marks the withdrawal as completed.

8 things to know

Topic	In short
Base URL	`https://api.win-pay.co`
Endpoints	Only two: `POST /api/v1/deposits/init` (deposit), `POST /api/v1/withdrawals/init` (withdrawal)
Identity	Your `api_key` goes in a header on every request
Signature	You sign every request with `api_secret` using HMAC-SHA256 (10 lines of code, ready in the guide)
Callback	WinPay sends the result to you; you never poll. You verify callbacks with `callback_secret`
Idempotency	The same notification may arrive twice; never credit twice (dedupe on `event_id`)
Limits	600 requests per minute per API key; a payment link lives 20 minutes
HTTPS	Your callback URL must be HTTPS and publicly reachable

Implementation checklist

Receive credentials from WinPay (api_key, api_secret, callback_secret)
Give WinPay your callback URL and your server's outbound IP
Implement the callback endpoint (HTTPS, signature-verifying)
Implement the signing function and check it against the offline test vectors
Implement the deposit flow (request → link → redirect)
Implement the withdrawal flow
Run the test list
Go live

Pages

Page	For	Time
System workflow	Everyone — what happens, in order	5 min
Integration guide	Developer — code, step by step	30 min
API reference	Developer — every field, every error	20 min
Testing, FAQ, troubleshooting	QA + developer	15 min

What you give us / what we give you

We give you	You give us
`api_key` — identifies you	Your callback URL (HTTPS)
`api_secret` — signs your requests	Your server's outbound IP (all of them, if several)
`callback_secret` — verifies our notifications

All three keys live only on your server. Never in a browser, a mobile app or HTML.