Developer documentation
Create payments, share hosted checkouts, and receive verified payment updates.
Introduction
Use the REST API at https://merchant.cyberwebsolutions.site/api/v1. Requests and responses use JSON. Currency is PHP and amounts are integer centavos. For example, 10000 represents ₱100.00.
Getting started
For a one-off payment, create a link from your dashboard. To connect a website or app, follow these steps.
- Verify your merchant email and complete Live setup in your dashboard. Wait for QRPh activation.
- Create a live key with
payments:writeandpayments:readin Dashboard → API keys. Save the key on your server. - Create the payment from your server. Store its returned ID with your local order and send the customer to
checkout_url. - Fulfill the order after your server verifies a
paidstatus through the API or a signedpayment.paidevent. To receive events, register your HTTPS URL in Dashboard → Webhooks.
Authentication
Send Authorization: Bearer <key>. A gw_test_… key selects Test Mode on the same API URL. A gw_live_… key selects Live mode. Keep keys on your server. GET /api/v1/health is public.
Sandbox mode
Issue a gw_test_… key in Test API keys. Use the same endpoints with source: "mock" or omit source. Create test checkout links and use Sandbox testing to simulate their outcomes. Test webhooks use their own signing secrets and deliver events with environment: "test".
Follow the test payment walkthrough to check your QR, balance and invoice return.
Live mode
In an enabled workspace, open Dashboard → API keys to issue a gw_live_… key. Call GET /api/v1/payment-methods for available methods. Omit source or send provider. The response provides a checkout on this gateway.
Confirm payment through the status API or signed live webhook before fulfilling an order. Verified QRPh earnings are available for merchant payout requests.
API keys
Keys support payments:read, payments:write, refunds:read, refunds:write, webhooks:read and webhooks:write. A newly issued secret is displayed once. Rotation revokes the previous key.
Payment methods
GET /api/v1/payment-methods lists payment methods for the key’s environment, including live availability, provider limits and default checkout expiry. Codes are qrph, gcash, maya, grabpay, shopeepay, card, and banking.
Create payment
Send POST /api/v1/payments with payments:write, Content-Type: application/json, and an Idempotency-Key. Use a distinct key of 8–120 characters per order. Keys can contain letters, digits, periods, underscores, colons, and hyphens and must start with a letter or digit.
Keep the key and original request for retries. A successful new payment returns HTTP 201. Repeating the same request returns the existing payment with HTTP 200. Reusing a key with different data or creating another payment with an existing reference returns HTTP 409.
- Required fields are
amountas integer centavos,currencyset toPHP, and an enabledpayment_methodsuch asqrph. - Send a unique
referenceto use your own order number. Saliw Pay generates one when it is omitted or blank. - Optional fields include
description,success_url,cancel_urland acustomer_idfrom the same workspace. Return URLs use HTTPS. expires_inis optional. It accepts 60–1800 seconds, with a minimum of 100 for live QRPh. The payment method provides the default.
{
"amount": 10000,
"currency": "PHP",
"payment_method": "qrph",
"description": "Order payment",
"success_url": "https://merchant.example/invoices/INV-1001",
"cancel_url": "https://merchant.example/cancel"
}{
"data": {
"id": "pay_0123456789abcdef01234567",
"reference": "ORD-0123456789ABCDEF01234567",
"amount": 10000,
"currency": "PHP",
"payment_method": "qrph",
"status": "created",
"environment": "live",
"source": "provider",
"charge_amount": 10150,
"checkout_url": "https://merchant.cyberwebsolutions.site/pay/{token}",
"checkout_flow": "qrph",
"expires_at": "2026-11-14T04:30:00+00:00",
"created_at": "2026-11-14T04:00:00+00:00",
"checkout_fees": {
"processing": 134,
"vat": 16,
"rounding": 0
},
"fees": {
"gross_amount": 10000,
"provider_fee": 0,
"provider_vat": 0,
"platform_fee": 0,
"platform_vat": 0,
"estimated_net": 10000,
"bearer": "merchant",
"payment_received_fee_percent": "0.0000",
"estimate_only": true
}
}
}Amounts and fees
amountis the original invoice amount. Use it to match the order and handle fulfillment.- Use
charge_amountas the QR total when present. Useamountwhen the payment has no separate customer charge. Approved QRPh checkout pricing adds the processing fee (1.34%) and VAT on fee (12%), a combined 1.5008%. For a ₱1.00 invoice, ₱1.015008 rounds to ₱1.02. checkout_fees.processing,checkout_fees.vatandcheckout_fees.roundingshow the charge breakdown in centavos. The rounding adjustment reconciles the two rounded fee lines to the QR total. The platform fee and its VAT are zero on new QRPh payments.- Send
"require_qrph_checkout_fees": truefor live QRPh orders that must include the customer-paid fees. If authorization is missing, a new order returns HTTP 403 withqrph_checkout_fees_unavailable. A retry with the original idempotency key returns its saved quote. Verify the quote before requesting the QR. - On a confirmed ₱1.00 QRPh invoice with ₱1.00 in proceeds, the eligible merchant balance credits ₱1.00. When the processor reports a lower net amount, the credit is capped at that amount.
- Payments keep their fee quote when settings change. The merchant dashboard shows confirmed earnings after payment. Provider estimates in
feesare separate from amounts in the actual checkout or reported by the processor.
Retrieve payment
Call GET /api/v1/payments/{id} with payments:read. Match the returned ID, currency and invoice amount to your order and check for status: paid. Use the payment ID in payment_id when you created a link or checkout session.
GET /api/v1/payments and GET /api/v1/transactions return lists with pagination. Filter with q (reference search), status, source, method_code, from and through. Set sort=oldest for ascending order. page starts at 1 and limit supports 1–50. Dates use UTC in YYYY-MM-DD format.
Hosted checkout and payment links
POST /api/v1/checkout-sessions and POST /api/v1/payment-links use the create payment fields and return the checkout or link ID together with a payment_id. Retrieve either resource through its own GET …/{id} endpoint. Links are single use and bound to the original order.
Set the complete invoice’s HTTPS address as success_url. Ten seconds after server confirmation, checkout takes the customer to that invoice. A payment without a return URL shows its receipt. Public access to the paid receipt and invoice return expires ten minutes after confirmation. Configure your webhook separately to receive payment events on your server.
QRPh integration
Select qrph and use the returned checkout URL to show a QR code on the gateway domain. To display the code on your own website, call POST /api/v1/payments/{id}/qr from your server with payments:write. The response provides qr_image_url and qr_expires_at while the code is usable. Simulated QRPh orders return a sample PNG. Live orders return the payable QR when it is ready.
Confirm payment with the signed webhook or status API. See the embedded QRPh walkthrough.
E-wallet and card integration
Checkout opens the processor’s hosted authorization page for supported payment methods. Customers return to checkout for server-confirmed status. Card PAN and CVV are entered only on the authorized hosted page. Online banking uses the direct online banking channel when enabled on the account.
Webhook integration
POST /api/v1/webhooks accepts url and events. It returns the signing secret once. Use GET /api/v1/webhooks or GET /api/v1/webhooks/{id} to inspect configuration. PATCH accepts enabled or events, and DELETE disables and removes the endpoint from listings.
Verify X-Gateway-Signature, which carries t and v1. Compute a SHA-256 HMAC of t + "." + rawBody with the endpoint's signing secret. Accept timestamps within five minutes, use a constant-time comparison, and persist the event ID uniquely before acting. Return a 2xx response after safely recording it. Delivery is at least once.
Events include payment.created, payment.pending, payment.paid, payment.failed, payment.expired, payment.cancelled and refund.completed. Each payload includes id, type, environment, created_at and data.
In PHP, read php://input and $_SERVER['HTTP_X_GATEWAY_SIGNATURE']. Pass them with your endpoint secret to verifyGatewayWebhook(). The default environment is live. Pass 'test' as the fourth argument in your test receiver. Reject a null result. For payment.paid, match data.id, data.amount and data.currency to your order. Record the event ID and update the order in one database transaction.
<?php
declare(strict_types=1);
// Signature verification helper for a merchant receiver.
function verifyGatewayWebhook(string $raw, string $signature, string $secret, string $environment = 'live'): ?array
{
if (!in_array($environment,['live','test'],true) || $secret === '' ||
!preg_match('/^t=([1-9][0-9]{8,10}),v1=([0-9a-f]{64})$/D',$signature,$parts) ||
abs(time()-(int)$parts[1])>300 || !hash_equals(hash_hmac('sha256',$parts[1] . '.' . $raw,$secret),$parts[2])) {
return null;
}
$event=json_decode($raw,true,20);
if (!is_array($event) || ($event['environment'] ?? null)!==$environment || !is_string($event['id'] ?? null) ||
!preg_match('/^evt_[0-9a-f]{24}$/D',$event['id']) || !is_string($event['type'] ?? null)) {
return null;
}
// The caller persists the event ID uniquely and applies local order changes in its own database transaction.
return $event;
}
Refunds
POST /api/v1/refunds receives payment_id, amount and reason with an idempotency header. GET /api/v1/refunds/{id} returns the current result. Treat succeeded or a verified refund.completed as confirmation. The platform administrator enables live refunds and verifies the processor’s refund webhook. Eligibility, amount limits and processing times depend on the original payment method.
HTTP status codes
The HTTP status describes the request outcome. For gateway errors, use error.code in your integration and save error.request_id for troubleshooting.
| Status | Meaning and next step |
|---|---|
400Bad Request | The request format or a required header is invalid. Check the JSON and send Content-Type: application/json with JSON requests. |
401Unauthorized | The API key is missing, invalid, or revoked. Send a valid bearer key for your workspace. |
403Forbidden | The action requires a different key scope or an active workspace. Check permissions and Live setup. |
404Not Found | The route or resource is unavailable to this key. Check the endpoint, ID, workspace, and Test or Live environment. |
405Method Not Allowed | The endpoint uses a different HTTP method. Check the endpoint reference or the Allow header. |
409Conflict | The operation conflicts with an existing reference, idempotency key, or resource state. Check the original record before trying again. |
410Gone | The checkout, QR attempt, or receipt has expired. Check the payment status before creating a replacement. |
413Content Too Large | The request exceeds the body size limit. Reduce the body to 256 KiB or less. |
421Misdirected Request | The request reached the gateway on the wrong origin. Use the configured HTTPS domain or subdomain. |
422Unprocessable Content | The request is readable but one or more values fail validation. Use the error details to correct the amount, currency, or other input. |
429Too Many Requests | A rate limit was reached. Wait for the number of seconds in the Retry-After header. |
500Internal Server Error | The gateway hit an unexpected error. Record the request ID and retry if the failure is temporary. |
502Bad Gateway | A hosting proxy received an invalid response from an upstream server. Check the service status and retry after a delay. |
503Service Unavailable | The gateway or a required service is temporarily unavailable. Check the error details and retry after a delay. |
504Gateway Timeout | A hosting proxy waited too long for an upstream response. Check whether the original operation completed before retrying. |
After a timeout or temporary 5xx during payment or refund creation, retry the original request with the same Idempotency-Key. Check the payment status before fulfilling the order.
The gateway accepts JSON bodies up to 256 KiB and allows 120 requests per minute per key and 240 per minute per IP.
{
"error": {
"code": "invalid_amount",
"message": "Use integer centavos between 1 and 99999999.",
"request_id": "req_example"
}
}Share the request ID, HTTP status, and approximate time when you open a support ticket.
Contact usSecurity
Use HTTPS and server-side secret storage. Restrict gateway scopes, rotate or revoke credentials after exposure, and keep checkout URLs out of analytics and public logs. Verify webhook signatures against raw bytes and reconcile against the payment API.
SDK-free examples
Set GATEWAY_LIVE_KEY to your scoped key in your server environment. For PHP and JavaScript, set GATEWAY_BASE_URL to your Saliw Pay origin. The cURL example uses this site’s URL. Replace the return URLs and idempotency key with values for your order. Run the JavaScript example in a server-side ES module with fetch support.
curl -sS https://merchant.cyberwebsolutions.site/api/v1/payments \
-H "Authorization: Bearer $GATEWAY_LIVE_KEY" \
-H 'Idempotency-Key: order-1001-payment' \
-H 'Content-Type: application/json' \
--data '{"amount":10000,"currency":"PHP","payment_method":"qrph","description":"Order payment","success_url":"https://merchant.example/invoices/INV-1001","cancel_url":"https://merchant.example/cancel"}'<?php
$key = (string) getenv('GATEWAY_LIVE_KEY');
$base = rtrim((string) getenv('GATEWAY_BASE_URL'), '/');
if ($key === '' || $base === '') {
throw new RuntimeException('Set GATEWAY_BASE_URL and GATEWAY_LIVE_KEY.');
}
$payload = array (
'amount' => 10000,
'currency' => 'PHP',
'payment_method' => 'qrph',
'description' => 'Order payment',
'success_url' => 'https://merchant.example/invoices/INV-1001',
'cancel_url' => 'https://merchant.example/cancel',
);
$curl = curl_init($base . '/api/v1/payments');
curl_setopt_array($curl, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 12,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => ['Content-Type: application/json',
'Authorization: Bearer ' . $key, 'Idempotency-Key: order-1001-payment']
]);
$result = curl_exec($curl);
if ($result === false) { throw new RuntimeException('Gateway connection failed.'); }
$status = (int) curl_getinfo($curl, CURLINFO_HTTP_CODE);
$data = json_decode($result, true);
if ($status >= 300 || !isset($data['data']['checkout_url'])) {
throw new RuntimeException($data['error']['code'] ?? 'gateway_error');
}
echo $data['data']['checkout_url'];const base = (process.env.GATEWAY_BASE_URL || '').replace(/\/+$/, '');
const key = process.env.GATEWAY_LIVE_KEY;
if (!base || !key) throw new Error('Set GATEWAY_BASE_URL and GATEWAY_LIVE_KEY.');
const response = await fetch(base + '/api/v1/payments', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer ' + key,
'Idempotency-Key': 'order-1001-payment'
},
body: JSON.stringify({"amount":10000,"currency":"PHP","payment_method":"qrph","description":"Order payment","success_url":"https://merchant.example/invoices/INV-1001","cancel_url":"https://merchant.example/cancel"})
});
const result = await response.json();
if (!response.ok || !result.data?.checkout_url) throw new Error(result.error?.code || 'gateway_error');
console.log(result.data.checkout_url);