Skip to main content

Documentation Index

Fetch the complete documentation index at: https://waffo.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Integration

DIRECT_PAYMENT is an early product that is largely unused today. New merchants should integrate ONE_TIME_PAYMENT directly.At the system level, the two are identical. The difference is in the business relationship:
  • ONE_TIME_PAYMENT: Waffo acts as PSP, providing full acquiring services (information flow + fund settlement)
  • DIRECT_PAYMENT: Waffo acts as ISV/PG, providing only system connectivity (no fund handling)
To avoid floating-point precision issues. For example, 0.1 + 0.2 = 0.30000000000000004, which is unacceptable in financial scenarios.
  • Same-currency orders: Most currencies require 2 decimal places per ISO 4217, but IDR, COP, KES, and TWD must not have decimals
  • Cross-currency orders: All currency amounts must conform to ISO 4217 precision, with no exceptions
Use a tunneling tool such as cloudflared or ngrok to expose your local port as a public URL.

​
Parameters

  • Omit both: The user selects a payment method on the Waffo checkout page
  • Card payments: Pass payMethodType="CREDITCARD,DEBITCARD" and omit payMethodName. Waffo automatically determines the card network from the card BIN the user enters, supporting Visa/Mastercard and credit/debit cards in a single order
  • VA (virtual account): Pass payMethodType="VA" and omit payMethodName; the user selects a bank on the checkout page
  • Specify a particular method: Pass both payMethodType and payMethodName. You can look up the exact values on the Payin page in the Portal
For detailed parameter rules, see Cashier integration - Customization options.
Yes. If you have not collected the user’s email, you have two options:
  1. Send a fixed-format value such as userId@examples.com (replace with the actual userId)
  2. Contact Waffo to have Waffo overwrite it to userId@examples.com format on your behalf (requires merchant authorization)
After going live, passing the user’s real email is recommended. Avoid using strings like test or reusing the same email across multiple users, as this may trigger risk controls.
It is optional. The field controls the time window within which the user can submit an order on the checkout page (must be UTC+0). Once the order is submitted to the payment channel, the expiry is controlled by the payment method itself. A small number of payment methods support passing a channel-side expiry time; check the Payin page in the Portal for details.
  • Same-currency: The merchant’s pricing currency matches the user’s local currency (e.g., IDR pricing → Indonesian user pays in IDR)
  • Cross-currency: The merchant’s pricing currency differs from the user’s payment currency (e.g., USD pricing → Indonesian user pays in IDR via DANA)
Cross-currency orders require passing payMethodCountry when either payMethodType or payMethodName is not specified. userCurrency is optional.
Pass it when you want the checkout to display only the payment methods of a specific country. If omitted, all available payment methods across all countries in the merchant’s contract are shown.
  • Global cards (CREDITCARD/DEBITCARD): Do not pass this field—global cards do not belong to any specific country.
For detailed parameter rules, see Cashier integration - Customization options.

​
Payments

Determine based on orderAction.actionType:
  • actionType = "WEB" → use webUrl
  • actionType = "DEEPLINK" → use deeplinkUrl
In most cases only webUrl is present. If you pass userTerminal=APP, some wallet payment methods that require external authorization return a deeplink.
In the sandbox, deeplinks cannot launch real wallet apps because a simulator is used. Verify this behavior in production.
Redirect the user to the external authorization page. The URL comes from orderAction; use webUrl or deeplinkUrl based on actionType.
This exception occurs because of a network timeout when calling the payment channel—it is unclear whether the order was created successfully.
  • When creating an order: If you can confirm the user cannot complete payment under the error condition (e.g., payment methods that require returning a checkout URL), you may abandon the order.
  • When refunding: You must retry with the same refundRequestId. Do not abandon the request.
See Error handling.
  1. Verify that notifyUrl is HTTPS and publicly reachable
  2. Verify that the callback port is 80 or 443 (Waffo production only accepts standard ports)
  3. Verify that the response body is {"message": "success"} and Content-Type is application/json
  4. Verify that the response includes the X-SIGNATURE header
  5. Proactively call the inquiry API to get the latest status
  6. If you still don’t receive it, contact Waffo technical support
Strongly recommended. Use cases:
  • Query proactively when the user lands on a success/failure page to give the smoothest experience
  • Retrieve the result for historical orders
  • Fall back to the inquiry API when Webhook signature verification fails
If you do not specify payMethodType / payMethodName, the checkout displays all available payment methods for the user to choose from.

​
Signature & security

  1. Incorrect private key format: The key must be in PKCS#8 format
  2. Incorrect signing content: The entire HTTP body must be signed; you cannot sign only selected fields
A 2048-bit RSA key pair using the SHA256WithRSA (RSASSA-PKCS1-v1_5 + SHA-256) signature algorithm.
Not recommended. Sandbox and production should use different API keys and RSA key pairs.

​
App integration

  • Confirm that the App and WebView allow opening external Apps or external browser pages
  • Confirm that the App and WebView support download, copy, and long-press save behavior. QR, OTC, and bank-transfer style payment methods may depend on these capabilities
  • Confirm that query parameters are preserved when URLs are passed between the native App and WebView
  • When loading via WebView, set userTerminal to APP
  • For detailed limitations, see Payment method integration notes
Not recommended. Use the GP/AP capabilities built into the Waffo checkout directly.
ComparisonUsing Waffo checkoutSelf-integration
GP/AP developer accountNot requiredRequired
Domain registration and verificationRequiredRequired
Managing encryption certificates/keysHandled by WaffoManaged by merchant
Server-side token processing/decryptionHandled by WaffoManaged by merchant
PCI DSS complianceNot requiredMay be required
Checkout UIProvided by WaffoBuilt by merchant
Integration complexityLowHigh
If you have a specific requirement to self-integrate, contact Waffo technical support for a detailed integration guide.
Yes, it launches the PayMe App. If the user does not have it installed, they will be prompted to download it.