Payment methods

There are four, and method takes exactly one of them. You choose how the customer pays; you never choose who clears it.

Read those four side by side and the contract is the whole story: the bodies are identical but for one word, and only QR answers differently. Nothing names a rail, a service or a flow, because none of those are yours to choose.

Three of the four end with the customer somewhere else and coming back. The response carries paymentLinkUrl; you send them there, and then your server asks the API for the outcome — EcashPay does not call your server when a payment finishes, so there is no webhook to wait for.

QR is the exception, and it is the one difference worth building for. A QR payment is completed by scanning, so the response carries the payload itself in qrString and paymentLinkUrl is null. Render the payload as a QR code on your own page — the customer never leaves it.

The payload is a string to render, not an address to fetch. Never request it, and never put a URL inside a QR code you drew from it.

A method can be switched off — EcashPay routes each method onto a payment rail per environment, and an operator can turn one off or leave it unrouted. It is a platform-wide setting, not something enabled per merchant account. That is answered with 503 PAYMENT_METHOD_UNAVAILABLE, naming the method.

The status is deliberate: 503 says the request was fine and the capability was not there. There is no retryAfter on it and no retry window: a method that is switched off comes back when someone switches it on, not on a timer, so fall back to another method rather than looping. A misspelled method is a different thing and answers 400 INVALID_PAYMENT_METHOD, which retrying will never fix.

If you offer a picker, offer the four. If you offer one method, offer EWALLET — it is the dominant consumer rail in the Philippines and the fastest to settle.

The create-payment body is the same whichever method you send, so there is one shape to write against. Reading a payment, the ledger and the payer directory do not vary by method at all. Refunding and capture are the exception: the request and response shapes are identical, but whether a payment can be refunded or captured through the API depends on how it was charged, so read the answer back rather than assuming it is accepted.

The payment you get back reports the method it was charged as, in method. It is recorded at the moment of the charge, so a payment made today keeps its method in your reports even if we route that method somewhere else tomorrow.