Creating a payment

One endpoint creates every payment — POST /v1/payments — and one field decides how it behaves:

• method — one of CARD_CREDIT, CARD_DEBIT, QR or EWALLET. It says how the customer pays, and it is the only choice you make about the payment itself.
• customerEmail — required. The receipt and any payment instructions go there.

We answer with a paymentLinkUrl to send the customer to — or, for a QR payment, the code itself, because a QR is completed by scanning and the customer never has to leave.

Four required fields — referenceId, method, amount and customerEmail — and the rest is polish:

• referenceId — your order id. Required, and unique per payment; see below.
• amount — in the major unit. 1500 is ₱1,500.00, not ₱15.00. There are no minor units anywhere in this API.
• currency — ISO-4217. Defaults to your account's currency; send it anyway, so the intent is in your own logs.
• description — shown to the customer during checkout. Write it for them, not for your database.
• successReturnUrl / cancelReturnUrl — where the customer lands afterwards. Read Confirming the outcome before you rely on either.

method and customerEmail are required alongside referenceId and amount. There is no flow to choose and no rail to name: those were fields once, and sending them now changes nothing.

A payment comes back in one of two shapes, and which one you get follows from the method — so branch on the field that is present, never on the method itself.

Redirect the customer to paymentLinkUrl — do not iframe it, because the pages behind it redirect to banks and wallet apps that refuse to be framed.

A QR payment is completed by scanning, so it publishes qrString and sets paymentLinkUrl to null. Render the payload as a QR code on your own page; the customer never leaves it. The payload is a string to draw, not an address to fetch.

Either way the payment starts PENDING. Nothing about the response tells you it succeeded — read Confirming the outcome for the one source of truth on that.

referenceId is the double-charge guard, and it is the one field worth designing deliberately. Sending one you have used before is refused with DUPLICATE_REFERENCE_ID (409) rather than creating a second payment.

That makes the safe pattern for an unreliable network: reuse the same reference when you retry. Either you get the payment, or you get a 409 that proves it already exists — and in both cases your customer is charged once. Generating a fresh reference per attempt gives away exactly this protection.

status is what you act on. Everything else on a payment is detail:

Treat this list as open. A rail we add later may introduce a status you have not seen, so write the check as "is it SUCCEEDED" and "is it one of the terminal failures I know" — never as an exhaustive switch that throws on the unexpected.