Developer

English

简体中文

English

简体中文

Appearance

Create Payment order

Updated: 2026-08-03 00:12
POST

Create a Payment order and return payer continuation information. If a create result is unclear, query by merchantOrderNo before resending the same request.

Request parameters

Content-Type / Accept / Api-Key / Timestamp / Nonce / Signature
BODY

Request body

Maximum body size: 64 KiB
merchantOrderNoRequiredstring(32)

Merchant order number: merchant-side unique order number. It must be unique under the same merchant number and is used for idempotency when creating an order.

  • Example:DEMO_PAY_202606010001
productCodeRequiredstring(32)

Product code: catalog code enabled for the merchant. Select it from supported product codes; it determines transaction currency and amount precision. Do not assemble or parse it yourself.

  • Example:PH_PHP_PAYMENT_QRPH_GCASH
amountRequiredobject

Order amount: amount object for create requests. Send only value; transaction currency is determined by productCode.

orderDescriptionRequiredstring(128)

Order description: short product or order description. It may be shown to the payer when the selected checkout, wallet or channel supports display. Do not include sensitive data.

payerOptionalobject

Payer information: optional payer contact data for a Payment order. Send it when your integration needs to attach payer contact details.

customDataOptionalobject

Custom data: optional merchant-defined key-value object echoed on the order and final-status Webhook. Use it only for merchant-side correlation. It supports at most 20 keys; each key must use lowerCamelCase and at most 40 characters; each value must be a string with at most 256 characters. Do not send secrets, signatures, bank card numbers, identity numbers, phone numbers, email addresses or other sensitive data.

  • Example:{"cartId":"CART-10001","customerRef":"CUST-90001"}

Response parameters

Content-Type / Request-Id / Timestamp / Nonce / Signature
BODY

Response body

platOrderNoRequiredstring(32)

Platform order number: platform-side order number used for technical troubleshooting and reconciliation; business query still uses merchantOrderNo.

  • Example:PHI112606010000000001001
merchantOrderNoRequiredstring(32)

Merchant order number: merchant-side unique order number. It must be unique under the same merchant number and is used for idempotency when creating an order.

  • Example:DEMO_PAY_202606010001
statusRequiredstring

Order status: current business lifecycle status of the Payment or Payout.

  • Enum values:
    PROCESSINGOrder is being processed.
    SUCCEEDEDThe order has succeeded.
    CANCELEDThe Payment order expired or was closed before success.
failReasonOptionalstring(256)

Failure reason: merchant-safe reason returned when the order reaches a non-success final status such as FAILED or CANCELED. Use status as the only order-state decision field.

productCodeRequiredstring(32)

Product code: catalog code selected for this order. It determines the order country, currency and amount precision. See supported product codes.

  • Example:PH_PHP_PAYMENT_QRPH_GCASH
countryRequiredstring

Country code: transaction or balance country, using ISO 3166-1 alpha-2 uppercase code. See supported countries and currencies.

  • Example:PH
amountRequiredobject

Order amount: amount object carrying value and transaction currency.

referenceNoOptionalstring(64)

Reference number: upstream payment network, payment institution or receiving institution reference returned when available. It is used to match payer proof or recipient institution investigation results; it is not the merchant order number, platform order number or channel order number.

  • Example:REF-20260601-0001
nextActionOptionalobject

Next action: checkout or channel continuation information returned when the payer needs a redirect, QR code or client-side payment parameters.

payerSummaryOptionalobject

Payer summary: payer contact summary returned for Payment reconciliation and support when available.

customDataOptionalobject

Custom data: merchant-defined key-value object echoed from the create request, when provided.

  • Example:{"cartId":"CART-10001","customerRef":"CUST-90001"}
createTimeRequiredtimestamp

Created time: Unix timestamp in seconds since 1970-01-01T00:00:00Z, returned as a JSON number and independent of time zones, when the resource was created. Convert it only when displaying a local time.

updateTimeRequiredtimestamp

Updated time: Unix timestamp in seconds since 1970-01-01T00:00:00Z, returned as a JSON number and independent of time zones. For Payment and Payout orders, it is when the current status became effective; for balances, it is when the balance data was updated. Convert it only when displaying a local time.

Error codes

This table lists the error codes this API may return. For the error body shape, see Basic rules.

HTTP status codeError codeDescriptionHow merchants handle
400INVALID_REQUESTThe request cannot be parsed or does not match the API contract.Check requestMethod, requestUrl, query, headers and JSON body.
400INVALID_JSONThe request body is not valid JSON.Send a valid JSON object encoded as UTF-8.
400PARAMETER_INVALIDA request parameter value is invalid.Correct the invalid request field according to the API field description and retry.
400PARAMETER_MISSINGA required request parameter is missing.Fill the required field and retry.
400AMOUNT_FORMAT_INVALIDamount.value format is invalid.Send amount.value as a positive decimal string in major currency units, for example 100.50.
401INVALID_API_KEYAPI Key is missing, disabled or unknown.Check the API Key configured in the merchant portal.
401INVALID_SIGNATURERequest signature verification failed.Rebuild the signing payload and Signature with the API Secret.
401TIMESTAMP_INVALIDTimestamp is missing, malformed or outside the allowed window.Sync server time and send a new Timestamp, Nonce and Signature.
401NONCE_REPLAYEDNonce was already used under the same API Key.Generate a fresh Nonce and Signature before retrying.
403PERMISSION_DENIEDMerchant or credential does not have permission for this operation.Check credential scope, merchant status and production access.
403PRODUCT_NOT_ENABLEDMerchant has not enabled the requested product.Enable the product before sending this request.
409MERCHANT_ORDER_NO_CONFLICTmerchantOrderNo conflicts with an existing business order.Stop changed-parameter retries and query the existing merchantOrderNo.
413REQUEST_BODY_TOO_LARGERequest body exceeds 64 KiB.Reduce the JSON body size and retry.
415UNSUPPORTED_MEDIA_TYPEPOST body is not UTF-8 JSON.Send UTF-8 application/json.
422BUSINESS_REJECTEDBusiness validation rejected the request.Read error.message and correct the rejected business condition.
422AMOUNT_LIMIT_EXCEEDEDAmount is outside the enabled product or merchant limit.Adjust amount or product configuration.
422AMOUNT_PRECISION_INVALIDamount.value has more decimal places than allowed by the selected product and currency.Use the amountScale documented for the country and currency, then retry with a supported decimal precision.
422COUNTRY_UNSUPPORTEDThe requested country is not supported for this merchant or resource.Use a supported country from the product or balance catalog.
422CURRENCY_UNSUPPORTEDThe requested currency is not supported for this country, product or merchant.Use a supported currency from the product or balance catalog.
422PRODUCT_UNSUPPORTEDProduct is not available for the requested country, currency or merchant.Use an enabled product code from the product catalog.
429FREQUENCY_LIMITEDRequests are too frequent.Slow down and retry later; query before retrying uncertain create attempts.
503ORDER_RESULT_UNKNOWNThe platform could not confirm whether the create request produced an order; the ErrorResponse has no platOrderNo.Query the same order type by the original merchantOrderNo. If repeated lookup with short waits still finds no order, retry only the unchanged request with that same merchantOrderNo.