Getting Started
Prerequisites and common concepts for integrating with WiPay APIs
Prerequisites
The two WiPay API products use different credentials and onboarding requirements.
| API | Primary prerequisites | How they are used |
|---|---|---|
| WAPIs | • Verified WiPay account • WiPay email and password for OAuth bearer-token authentication • BUSINESS-account WAPI Key for integrations that use key-based authentication • Conditional WAPI Configuration for endpoints that depend on Main Merchant Account behavior | • PERSONAL accounts must use the auth endpoints to obtain bearer tokens • BUSINESS accounts can bearer tokens, or create and manage WAPI Keys for protected requests |
| Payments API | • Verified WiPay BUSINESS Account • Live account_number• API Key kept on the server for response-hash verification | • account_number identifies the merchant account on requests• The API Key is used only for server-side response-hash verification |
Product-Specific Prerequisites
WAPIs
- Use a verified WiPay account.
- Authenticate protected routes with bearer tokens obtained from your WiPay email and password, or with a WAPI Key created and managed on your WiPay BUSINESS account.
- For some endpoints, especially Main Merchant Account account-management flows, WiPay must provision a WAPI Configuration for your account.
Bearer tokens are issued by the WAPI auth endpoints. Access tokens last 12 hours; the refresh token remains usable for 6 hours after the access token expires. WAPI Keys are created and managed on the Developer page — see WAPI Keys for format, creation, and lifecycle details. Live keys use the wapi_live_... prefix and sandbox keys use the wapi_test_... prefix. WiPay PERSONAL accounts can use only the OAuth bearer-token flow.
Payments API
- Use a verified WiPay BUSINESS Account.
- Use the merchant
account_numberfor live requests. - Use the account's API Key only for server-side response-hash verification.
The Payments API request endpoint does not use authentication headers. Your account_number identifies the merchant account, while the API Key remains server-side and is used only to verify successful transaction responses. Never expose the API Key in client-side code.
For base URLs, sandbox credentials, and country routing, see Platforms and Environments.
Common Concepts
Request Headers
- Use
Accept: application/jsonwhenever you want a JSON response. - For the Payments API, omitting
Accept: application/jsoncauses the browser-oriented redirect flow instead of a JSON bootstrap response. - Protected WAPI endpoints require exactly one of
Authorization: Bearer <access_token>orX-WAPI-Key: <wapi_key>. - Some WAPI endpoints are intentionally public metadata endpoints. For example,
GET /wapi/withdrawals/metadoes not require authentication.
HTTP Status Codes
| Code | Meaning |
|---|---|
200 | Success |
201 | Resource created |
400 | Bad request — validation error or request cannot be processed |
401 | Unauthorized — invalid or missing credentials |
403 | Forbidden — insufficient scope, permissions, or account state |
405 | Method not allowed |
409 | Conflict — resource already exists |
500 | Internal server error |
Hosted Redirect Handling
Hosted redirect flows are shared between the Payments API and WAPI Trusted Card create and charge flows. In those cases, WiPay redirects the browser to your response_url with query-string parameters appended.
See Hosted Checkout Flows for the shared behavior.
Transaction Verification (Response Hash)
For Payments API transactions, and for WAPI payment-style hosted checkout flows that reuse the Payments response model, always verify successful transactions server-side using the response hash returned in the successful transaction response.
Use the original total supplied in the API request, not the customer-facing response total, when validating the response hash. See Transaction Response for the current calculation and validation details.