Getting Started
Welcome to the WHITESTONES API documentation. This guide will help you integrate our payment solutions into your application quickly and securely.
🚀 Quick Setup
Get up and running in less than 30 minutes with our streamlined integration process.
Base URLs
Production: https://api.whitestones.com/v1
Sandbox: https://sandbox-api.whitestones.com/v1
Prerequisites
- WHITESTONES merchant account
- API credentials (API Key & Secret)
- HTTPS endpoint for webhooks (recommended)
- Basic knowledge of REST APIs and HTTP
Authentication
WHITESTONES API uses API key authentication. All requests must include your API credentials in the request headers.
Headers Required
Authorization: Bearer YOUR_API_KEY
X-WS-Secret: YOUR_API_SECRET
Content-Type: application/json
⚠️ Security Notice
Never expose your API credentials in client-side code. Always make API calls from your secure backend servers.
Example Authentication
curl -X GET https://api.whitestones.com/v1/merchant/profile \
-H "Authorization: Bearer ws_live_abc123..." \
-H "X-WS-Secret: ws_secret_def456..." \
-H "Content-Type: application/json"
Payin API
Accept payments from customers worldwide using our comprehensive payin solutions.
Create Payment Intent
Initialize a payment session for your customer.
Request Body
{
"amount": 1000,
"currency": "USD",
"description": "Order #12345",
"customer": {
"email": "customer@example.com",
"name": "John Doe"
},
"metadata": {
"order_id": "12345",
"user_id": "user_789"
},
"return_url": "https://yoursite.com/success",
"cancel_url": "https://yoursite.com/cancel"
}
Response
{
"id": "pi_1234567890",
"status": "requires_payment_method",
"amount": 1000,
"currency": "USD",
"client_secret": "pi_1234567890_secret_abc123",
"payment_url": "https://checkout.whitestones.com/pi_1234567890",
"created": 1640995200
}
Payout API
Send money to recipients worldwide with flexible scheduling and routing options.
Create Payout
Send funds to a recipient's bank account or digital wallet.
Request Body
{
"amount": 5000,
"currency": "USD",
"recipient": {
"type": "individual",
"name": "Jane Smith",
"email": "jane@example.com",
"bank_account": {
"account_number": "1234567890",
"routing_number": "021000021",
"account_type": "checking"
}
},
"description": "Freelance payment - Project ABC",
"metadata": {
"project_id": "proj_123",
"contractor_id": "cont_456"
}
}
Response
{
"id": "po_9876543210",
"status": "pending",
"amount": 5000,
"currency": "USD",
"estimated_arrival": "2024-01-15T10:00:00Z",
"fee": 25,
"created": 1640995200
}
Webhooks
Stay informed about payment status changes with real-time webhook notifications.
📡 Real-time Updates
Receive instant notifications when payment statuses change, ensuring your system stays synchronized.
Webhook Events
payment.succeeded- Payment completed successfullypayment.failed- Payment attempt failedpayment.processing- Payment is being processedpayout.created- Payout initiatedpayout.completed- Payout completedpayout.failed- Payout failed
Error Codes
Understanding API error responses and how to handle them.
| Code | Status | Description |
|---|---|---|
400 |
Bad Request | Invalid request parameters |
401 |
Unauthorized | Invalid API credentials |
403 |
Forbidden | Access denied to resource |
429 |
Rate Limited | Too many requests |
500 |
Server Error | Internal server error |
Need Help?
Our technical team is available 24/7 to assist with your integration.