Quickstart

Updated: 2026-09-08 14:00

Integration path

Complete the integration in this order:

1. After international access is approved, create API credentials in Merchant Portal and store the API Secret securely.
2. Separately create one or more Webhook endpoints and select their events.
3. Generate request signatures.
4. Create payment or payout orders.
5. Query by merchant order number.
6. Process notification events.
7. Handle create results safely.
8. Complete go-live checks and switch to production credentials.

1. Create API credentials in Merchant Portal

A merchant administrator or explicitly authorized technical user enters a credential name in International Payments → API Access. The platform generates the API Key and API Secret, and the new Key is always disabled. The API Secret is shown only once in the current page session after creation. It can be copied again from that page until the operator confirms it was saved; after a browser refresh or close, it cannot be viewed or recovered. Store it immediately in a server-side secret manager and never place it in frontend code, mobile apps, repositories, logs or support tickets. If the Secret was not saved or may have been exposed, create a replacement Key and rotate traffic to it.

Use the test environment credentials for integration first. Production credentials must remain disabled until onboarding, product, account, channel and funds failure tests are complete and the production outbound IP is approved in the platform operations security group.

API Base URL

The API Reference displays endpoints as {apiBaseUrl} plus the versioned interface Path, for example POST {apiBaseUrl}/intl/v1/payment/order/create. Do not send {apiBaseUrl} literally. Replace it with the HTTPS API domain for the target environment:

Environment	{apiBaseUrl}
Test	https://test-api.paysea.global
Production	https://api.paysea.global

For example, create payment order:

• Test: POST https://test-api.paysea.global/intl/v1/payment/order/create
• Production: POST https://api.paysea.global/intl/v1/payment/order/create

Complete integration with the test environment first, then switch to the production {apiBaseUrl}, production merchant number, API Key and API Secret at go-live.

The test environment here means the integration domain and credentials issued by the platform. It is separate from the API Key test mode: public endpoints currently use live mode Keys, while test mode is reserved for a future isolated Sandbox.

The examples use:

INTL_API_BASE_URL
INTL_MERCHANT_NO
INTL_API_KEY
INTL_API_SECRET

INTL_API_BASE_URL stores the HTTPS API domain for {apiBaseUrl} and must not include the /intl/v1 path prefix. INTL_MERCHANT_NO is used for reconciliation, support and idempotency ownership checks. It is not sent as an extra request header because the API Key is already bound to the merchant number.

2. Configure Webhook endpoints and their Secrets

Webhook configuration is independent from API credentials: an endpoint can be created before or after an API Key, and enabling, disabling or revoking a Key does not change Webhook delivery. Each endpoint has one HTTPS URL, one current Webhook Secret and one or more subscribed event types. A merchant can create multiple endpoints, and the same event type can be delivered to more than one endpoint.

A new endpoint is disabled by default. The platform displays its Webhook Secret and Webhook Secret ID for 60 seconds after creation. Store both values, deploy the receiver, and confirm it can verify signatures and durably accept events before enabling that endpoint. An authorized merchant administrator can reveal the current Secret again only after a fresh Google verification. Changing the URL disables the endpoint and skips its pending deliveries until it is reviewed and enabled again. API create requests neither require an enabled Webhook nor accept a per-order notification URL.

To route different events to different receivers, create separate endpoints and select the event types for each endpoint. To send one event type to multiple receivers, subscribe that event type on every intended endpoint.

The receiver must:

• Verify signatures with the raw Body.
• Deduplicate locally by notification Body eventId or merchant order number.
• Return consistent results for duplicate deliveries.
• Reject business processing when signature verification fails.

3. Review supported products

Use only the country, currency, product and bank-code values enabled by the platform for the merchant. The public docs list the current product catalog and the API Reference lists supported PH/PHP bank codes for payout recipient fields. Do not invent product codes, channel identifiers or products that have not been enabled for the merchant.

4. Generate request signatures

Every request must be sent from the merchant backend with separate signing Headers:

Accept: application/json
Content-Type: application/json
Api-Key: ik_live_xxx
Timestamp: 1780272000
Nonce: nonce_xxx
Signature: v1=<64 lowercase hex>

Api-Key identifies the merchant, Secret and permissions. Request-source access is enforced by the platform operations security group. Timestamp is Unix timestamp text in seconds. Timestamp and Nonce provide replay protection. Signature proves that the caller holds the API Secret and protects the request method, request URL and request body. The API Secret is used only locally on the merchant server and is never sent. Accept and Content-Type declare the JSON media format and are not included in the signing payload. GET requests do not send Content-Type. Header names are case-insensitive. The documentation shows canonical unprefixed Header names; do not add product, company or brand prefixes.

The signing payload has exactly five lines. Append one newline byte \n after every line, including the last line:

requestMethod
requestUrl
timestamp
nonce
requestBody

requestMethod is the uppercase HTTP request method, such as POST or GET. requestUrl is the request address without the domain name, including Path and the original Query. requestBody is the exact UTF-8 raw Body sent on the wire; for GET, the fifth line is empty but the final newline byte is still present. Independent signing implementations must pass the signing test vectors before launch.

5. Create payment or payout orders

Generate and save merchantOrderNo before sending a create request. It is a merchant-side unique order number and must be unique under the same merchant number. The platform identifies one business order by merchant number plus merchant order number.

{
  "amount": {
    "value": "100.50"
  },
  "productCode": "PH_PHP_PAYMENT_QRPH_GCASH",
  "merchantOrderNo": "DEMO_PAY_202606010001",
  "orderDescription": "Virtual order"
}

PH_PHP_PAYMENT_QRPH_GCASH is an example product code, not an availability promise. Send it only after the platform enables that product for your merchant. The selected productCode determines the transaction currency and allowed amount precision; do not send amount.currency in create requests.

Save the response platOrderNo and merchantOrderNo. A create HTTP 200 contains the actual core platform order number. Treat it as opaque. HTTP 4xx and 5xx responses contain error instead and never contain platOrderNo.

6. Query by merchant order number

A 200 response means the API call succeeded. For create requests, it means a core order exists or an existing idempotent order was returned; it does not mean the payment or payout succeeded. The merchant system must store merchantOrderNo and be able to query order status by merchant order number. Query results and notification events can both arrive; use the merchant order database for final idempotent business handling.

7. Process notification events

Notifications are final order-status events sent from the platform to the merchant. Process them in this order:

1. Read and retain the raw UTF-8 Body.
2. Select the locally stored Webhook Secret by Webhook-Secret-Id.
3. Verify the raw Body, Timestamp, Nonce and Signature.
4. Parse JSON only after signature verification succeeds.
5. Deduplicate by notification Body eventId or merchant order number.
6. Persist the handling result, then return HTTP 200 OK. The platform treats any 2xx response as successful receipt.

Notifications can be delivered more than once. Duplicate notifications must not trigger duplicate funds, fulfillment or status updates.

8. Handle create results safely

Handle every create outcome without changing the saved order identity:

Create result	Merchant action
HTTP 200	API call succeeded; use response status, query API or Webhook for the business result.
HTTP 4xx	Handle according to error.code; do not blindly retry. Correct parameters, signature or permissions, or wait according to the rate-limit policy before resubmitting.
HTTP 5xx, network exception or response timeout	You may not know whether the order was created. Do not place another order with a new number; query with the original merchantOrderNo first.

Never resolve uncertainty by changing merchant order numbers, amounts or products. If repeated queries still find no order, resend the unchanged create request with the original merchantOrderNo; never send it concurrently or use a new number. A Payout must never be resent only because the first call timed out.

9. Configure production outbound IPs

Submit the fixed outbound IPs that call the International API to platform operations. Operations must add the approved addresses to the gateway security group before traffic is enabled. Application credentials contain no source-IP field and the application does not perform credential-level IP admission.

10. Enable the live-mode Key and complete go-live checks

After onboarding and integration checks pass, enable the live-mode API Key in Merchant Portal. API credential lifecycle and Webhook endpoint lifecycle are independent; an unavailable Webhook never changes API authentication status.

Before the first production request, confirm that:

• Production country, currency, products and limits are enabled.
• Production outbound IPs are approved by platform operations at the gateway security group, WAF or API Gateway.
• Every required production Webhook endpoint is configured, subscribed and enabled independently from the API Key.
• merchantOrderNo generation is unique under the production merchant number.
• Create requests are not automatically retried.

Support data checklist

Provide only these values when opening a technical support case:

• API environment: test or production Base URL.
• API Key mode: currently fixed as live for public endpoints; test is reserved for a future isolated Sandbox.
• UTC time.
• Merchant number.
• Merchant order number.
• HTTP status.
• Request-Id response Header.
• Response body error.code.

Never send API Secrets, Webhook Secrets, signing Header values, full request bodies, full notification bodies or full recipient account numbers.

Before production traffic, complete the go-live checklist.

Continue with signing and verification and idempotency.