Frequently asked questions

Which API should I use?

Use Payments to create payments and payouts, issue refunds, retrieve transactions, and generate reports. Use Billing to create recurring subscriptions. Use Checkout to send customers to a Paybilt-hosted payment, payout, or subscription page.

Does a successful create response mean the payment succeeded?

A successful create response means that Paybilt Gateway accepted or created the transaction; it does not mean the payment succeeded. Persist txid, call status, run lookup when needed, and process callbacks until the transaction reaches a documented final status. Review the transaction lifecycle.

What is udfs[0]?

The first element of the udfs array, udfs[0], is your merchant idempotency reference. Assign a unique value to each financial attempt, persist it before sending, and search by that value after a timeout. Paybilt checks its uniqueness for the site and returns code 1116 with udf1 must be unique for a duplicate, providing duplicate-request protection. Transaction lookup supports searches by udfs[0].

Can I retry a timed-out payment request?

Search by the persisted udfs[0] or query the known txid. If you find the transaction, continue checking its status. Retry with the same udfs[0] only when lookup shows that no transaction exists.

Why did HTTP 200 contain an error?

Some Paybilt Gateway operations return 200 while reporting business failures in the response body. When present, parse errors, message, status, and success. Check for success before reading it because standard create responses include it inconsistently.

Does HTTP 200 from cancellation mean cancelled?

HTTP 200 means that Paybilt accepted the cancellation request for asynchronous processing. Continue checking the original transaction until it reports a documented final status.

What is the difference between expired and process_expired?

expired is a business outcome from the payment or payout flow. process_expired means that Paybilt Gateway stopped checking before it established a supported final outcome. Investigate process_expired as an exception; handle an ordinary customer expiry as expired.

How do I enable a documented method?

Ask your Paybilt account or integration contact to enable the method for your site. Site configuration determines enabled methods, required fields, reports, lookup fields, limits, and cancellation availability.

Does the report endpoint really use a GET body?

Yes. Generate Transaction Report uses GET /api/v2/report/ with a JSON body containing start_date, end_date, and optional types. Configure your HTTP client and proxy to preserve the GET request body.

Should I use Paybilt Gateway for new subscriptions?

Yes. Send Billing requests through the Paybilt Gateway at /api/v3/subscriptions, using the resources in the Billing API reference. The older /api/v2/subscriptions routes forward to the legacy v1 subscription service, which uses a different request contract; use them only if your account team has told you your integration is on v1.