API v1

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.

  1. Verify your merchant email and complete Live setup in your dashboard. Wait for QRPh activation.
  2. Create a live key with payments:write and payments:read in Dashboard → API keys. Save the key on your server.
  3. Create the payment from your server. Store its returned ID with your local order and send the customer to checkout_url.
  4. Fulfill the order after your server verifies a paid status through the API or a signed payment.paid event. 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 amount as integer centavos, currency set to PHP, and an enabled payment_method such as qrph.
  • Send a unique reference to use your own order number. Saliw Pay generates one when it is omitted or blank.
  • Optional fields include description, success_url, cancel_url and a customer_id from the same workspace. Return URLs use HTTPS.
  • expires_in is optional. It accepts 60–1800 seconds, with a minimum of 100 for live QRPh. The payment method provides the default.
Live JSON request
{
    "amount": 10000,
    "currency": "PHP",
    "payment_method": "qrph",
    "description": "Order payment",
    "success_url": "https://merchant.example/invoices/INV-1001",
    "cancel_url": "https://merchant.example/cancel"
}
HTTP 201 example
{
    "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

  • amount is the original invoice amount. Use it to match the order and handle fulfillment.
  • Use charge_amount as the QR total when present. Use amount when 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.vat and checkout_fees.rounding show 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": true for live QRPh orders that must include the customer-paid fees. If authorization is missing, a new order returns HTTP 403 with qrph_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 fees are 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 webhook signature verification
<?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.

StatusMeaning and next step
400Bad RequestThe request format or a required header is invalid. Check the JSON and send Content-Type: application/json with JSON requests.
401UnauthorizedThe API key is missing, invalid, or revoked. Send a valid bearer key for your workspace.
403ForbiddenThe action requires a different key scope or an active workspace. Check permissions and Live setup.
404Not FoundThe route or resource is unavailable to this key. Check the endpoint, ID, workspace, and Test or Live environment.
405Method Not AllowedThe endpoint uses a different HTTP method. Check the endpoint reference or the Allow header.
409ConflictThe operation conflicts with an existing reference, idempotency key, or resource state. Check the original record before trying again.
410GoneThe checkout, QR attempt, or receipt has expired. Check the payment status before creating a replacement.
413Content Too LargeThe request exceeds the body size limit. Reduce the body to 256 KiB or less.
421Misdirected RequestThe request reached the gateway on the wrong origin. Use the configured HTTPS domain or subdomain.
422Unprocessable ContentThe request is readable but one or more values fail validation. Use the error details to correct the amount, currency, or other input.
429Too Many RequestsA rate limit was reached. Wait for the number of seconds in the Retry-After header.
500Internal Server ErrorThe gateway hit an unexpected error. Record the request ID and retry if the failure is temporary.
502Bad GatewayA hosting proxy received an invalid response from an upstream server. Check the service status and retry after a delay.
503Service UnavailableThe gateway or a required service is temporarily unavailable. Check the error details and retry after a delay.
504Gateway TimeoutA 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.

HTTP 422 error response
{
  "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 us

HTTP specifications RFC 9110 and RFC 6585.

Security

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.

Create a payment with cURL
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 server request
<?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'];
JavaScript server request
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);

Confirm this action