Saliw Pay guide

Set up your workspace, test a QRPh payment, and connect Saliw Pay to your own website.

Use your dashboard

Create a merchant account or sign in. Use Test or Live in the dashboard header to choose which payments you are working with.

Overview
Check confirmed payment volume, balances and recent webhook activity for the selected mode.
Payment links
Create a single-use link and share it with your customer. Add an invoice URL if you want checkout to send them back after confirmation.
Payments and Transactions
Find orders by reference, open a payment, and check its amount, status and fee breakdown.
Business settings and Team members
Set the checkout name and logo and invite staff. These settings apply to your workspace in both modes.

Test a payment

Test Mode uses simulated payments, its own API keys, and test webhook subscriptions. An active workspace can start testing while its live application is under review.

  1. Open Sandbox testing → QRPh. Enter ₱1.00, create the payment, then select Open checkout.
  2. Confirm the checkout displays TEST MODE. Select Start test checkout to see the sample QR image.
  3. Return to the same payment in Sandbox testing. Select Success and press Run. The checkout updates to the confirmed state. Use a test invoice URL to try the return after 10 seconds.
  4. Open Test → Overview to inspect the test balance. Try Failure or Expired on a fresh order to check how your checkout handles those results.

On a ₱1.00 hosted test invoice, checkout shows ₱1.02 after the processing fee, VAT and rounding. A confirmed simulation credits ₱1.00 to the test balance.

For a shareable test link, open Payment links in Test Mode. For an embedded checkout, create a gw_test_… key in Test API keys.

Accept live payments

  1. Verify your account email. In Live mode, open Live setup, submit your business details and wait for activation.
  2. After approval, open Payment links. Enter the invoice amount, select QRPh and create a link. For invoice returns, enter the complete HTTPS invoice URL for that order.
  3. Share the link. The customer scans the QRPh code in a supported bank or wallet app. Find the order in Payments and check the confirmed status before releasing goods or services.
  4. For a website integration, issue a scoped gw_live_… key in API keys under Live mode. Register a Live webhook if your site will receive payment events.

Approved QRPh checkout pricing adds the processing fee (1.34%) and VAT on fee (12%). On a ₱1.00 invoice, the QR charges ₱1.02. If confirmed proceeds cover the invoice, the merchant balance credits ₱1.00. See Pricing and API amount fields.

Embed QRPh on your website

Your website controls the modal, buttons, timer and success screen. Your server creates the payment, asks Saliw Pay for the QR, and returns the image URL and expiry to your page.

  1. Issue a test key with payments:write and payments:read. Store it in your server configuration. Use integer centavos for amount, so 100 means ₱1.00.
  2. Call POST /api/v1/payments and store data.id with your order. Then call POST /api/v1/payments/{payment_id}/qr using that ID.
  3. Set your checkout image’s src to qr_image_url when present. Use qr_expires_at for the timer. Display charge_amount as the customer total when present and use checkout_fees for the fee breakdown. Match the invoice with amount.
  4. Run a scenario in the sandbox and verify the result on your server. When your workspace is approved, use the Live key and omit source or use provider for live orders. Set require_qrph_checkout_fees to true on live orders that require the customer-paid QRPh quote.
Server-side cURL walkthrough
# Set GATEWAY_BASE_URL to your Saliw Pay origin and SALIW_TEST_KEY to your test key.
# Use a fresh idempotency key for each new order and save it for retries.
curl -sS "$GATEWAY_BASE_URL/api/v1/payments" \
  -H "Authorization: Bearer $SALIW_TEST_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-qrph-1001' \
  --data '{"amount":100,"currency":"PHP","payment_method":"qrph","source":"mock"}'

# Set PAYMENT_ID to data.id from the response.
curl -sS -X POST "$GATEWAY_BASE_URL/api/v1/payments/$PAYMENT_ID/qr" \
  -H "Authorization: Bearer $SALIW_TEST_KEY"

# Retrieve the payment status from your server.
curl -sS "$GATEWAY_BASE_URL/api/v1/payments/$PAYMENT_ID" \
  -H "Authorization: Bearer $SALIW_TEST_KEY"

Use a fresh payment after expiry. Keep the gateway key on your server and treat the QR image URL like an expiring checkout link.

Confirm payments and webhooks

  1. Choose the same mode as your orders and open Webhooks. Save your server’s HTTPS URL and subscribe to payment.paid. Store the signing secret when it appears.
  2. Verify X-Gateway-Signature against the raw body and check that its environment matches the receiver. Use a staging URL and its test signing secret for test events.
  3. Match the payment ID, invoice amount and currency to your order. Use the event ID to make the update once. Return a 2xx response after recording the event.

Your server can also call GET /api/v1/payments/{id} and verify the same order details with status paid. See the signature example and delivery details.

Request a payout

In Live mode, open Payouts. Save a GCash or Maya account with its registered name and number. Enter an amount within your available balance and review the fee and wallet amount before submitting.

Track your request in Payout history. The administrator reviews and sends approved payouts manually. The estimated payout time is 12–24 hours.

Troubleshooting

401 or 403 from the API
Check the key, its scopes and the workspace mode. Live payment creation requires an activated workspace.
QR expired or payment still pending
Read the original payment status from your server. Create a new payment only when the old order has closed and you have confirmed it was unpaid.
Test webhook is queued
Check the delivery in Test Mode. The site’s scheduled worker sends events. Review failed attempts for the HTTP status and confirm your server accepts the signed request.

Confirm this action