Beginner Merchant Guide

How to add XPayLink to a merchant website

Choose one integration path. For most PHP merchants, use the 1-file PHP kit. For WordPress stores, use the WooCommerce plugin. For developers, use the full SDK or direct API. All paths use the same safe rule: redirect to XPayLink first, then mark paid only after a signed webhook.

1. Setup merchant
Create merchant account, save GCash number, pair Android phone, copy API keys, set webhook URL.

2. Create payment
Merchant backend calls https://synthwave.space/api/create-session.php using public + secret keys, then redirects customer to payment_url.

3. Receive webhook
XPayLink sends signed payment.paid webhook after auto verification or manual approval.

Easiest

Option A: 1-File PHP Kit

Best for Hostinger, cPanel, plain PHP, and non-technical merchants.

Download xpaylink_one_file_php_kit.zip.
Upload xpaylink.php to merchant website.
Edit CONFIG: Base URL, Public Key, Secret Key.
Set webhook URL to xpaylink.php?action=webhook.
Connect Pay button to xpaylink.php?action=create_payment.

Download 1-File Kit

Developer

Option B: Full PHP SDK

Best if the merchant wants separate checkout, webhook, SDK class, and demo store.

Upload xpaylink_merchant_sdk folder.
Edit xpaylink_config.php.
Open index.php inside the SDK folder.
Create a test order and pay.
Replace demo storage with real database update.

Download Full SDK

WordPress Store

Option C: WooCommerce Plugin

Best for WordPress online stores that use WooCommerce checkout.

Upload xpaylink-woocommerce.zip in WordPress Plugins.
Enable XPayLink GCash in WooCommerce Payments.
Enter Base URL, Public Key, and Secret Key.
Set webhook URL to /wp-json/xpaylink/v1/webhook.
Run a real test checkout.

Download WooCommerce Plugin

Advanced

Option D: Direct API

Best for Laravel, Node, Python, WordPress custom plugins, LMS, or billing systems.

Call /api/create-session.php.
Redirect customer to payment_url.
Receive signed webhook.
Verify HMAC with Secret Key.
Mark local order paid by external_bill_id.

Open API Docs

Merchant setup checklist

Create and activate merchant account.
Add merchant GCash receiving number.
Install Android app on the merchant receiver phone.
Enable Android Notification Access.
Pair phone using code from merchant dashboard.
Copy Public Key and Secret Key from dashboard.
Set webhook URL or pass callback_url when creating sessions.
Run a test payment and confirm local order becomes PAID only after webhook.

The most important rule

After create-session, always redirect the customer to payment_url. This page collects or confirms payer details and shows the exact generated amount. The merchant website should never mark paid from the return page alone.

Correct flow:
Customer clicks Pay
→ Merchant creates XPayLink session
→ Merchant redirects to payment_url
→ XPayLink verifies payment
→ XPayLink sends signed webhook
→ Merchant verifies signature
→ Merchant marks local order PAID

Webhook quick test

The merchant webhook URL must be public online. Do not use localhost for live testing.

Webhook URL examples:
https://merchant-site.com/xpaylink.php?action=webhook
https://merchant-site.com/xpaylink_merchant_sdk/webhook.php
https://merchant-site.com/api/xpaylink/webhook
https://merchant-site.com/wp-json/xpaylink/v1/webhook

Final testing checklist

create-session returns success: true and payment_url.
Customer is redirected to hosted XPayLink page.
Customer sends exact generated amount.
Merchant Android phone receives GCash notification.
XPayLink marks session paid automatically or after manual approval.
Merchant webhook receives payment.paid. For WooCommerce, this is /wp-json/xpaylink/v1/webhook.
Merchant verifies X-PayLink-Signature.
Merchant local order becomes PAID by external_bill_id.