PayZero API reference

PayZero accepts payments from customers in Japan and reports the outcome back to you. This reference covers the checkout API: the endpoints that list what a customer can pay, open a payment, and confirm whether it settled.

It is arranged to be read in order the first time and searched afterwards. New here? Start with Getting started, then Essentials for how the two payment methods behave, and Guides for testing and going live. Already integrating? The Reference has every endpoint, field by field, with the consolidated error table.

Getting started

Base URL: https://api.payzero.ai

Every endpoint returns JSON. Request bodies are JSON and must be sent with Content-Type: application/json. Responses are never cached.

Requests must come from an allowlisted origin. Send PayZero the origins you will call from before you start; a browser request from any other origin is refused with 403 origin_not_allowed. Server-to-server calls, which send no Origin header, are not subject to the check.

The sandbox

PayZero provisions a sandbox before go-live. It is the same API — the same endpoints, request bodies and response shapes — pointed at the payment provider's test environment, and nothing in it moves real money. Build and test your integration against it, then point the same code at live.

Ask PayZero to set up your sandbox and allowlist your origins to begin. When you are ready to exercise real payments, Testing has the test cards and the authentication PINs, and Sandbox and live covers the one difference between the two environments.

Your first payment

Both methods follow the same shape: create a payment through the API, send the customer to the redirectUrl you get back, and confirm the outcome afterwards. End to end, that is five steps.

1. Ask PayZero to allowlist your origins and set up your sandbox.
2. For bank transfer, call GET /checkout/banks, then GET /checkout/amounts for the bank the customer picked. For card, go straight to step 3.
3. Create the payment with POST /checkout/deposit or POST /checkout/card, and store the reference it returns against your order.
4. Send the customer to redirectUrl.
5. Confirm the outcome with GET /checkout/status?ref=…. The customer's return does not confirm anything by itself.

The smallest single call is GET /checkout/banks: no body, no parameters, just your allowlisted Origin, and it returns live bank availability. Everything else in the flow hangs off the reference you store at step 3.

Essentials

Two payment methods, both redirect flows. This section is how they behave: what the customer does, what the amounts and currencies look like, and why a customer returning from the payment page is not yet a settled payment. The exact request and response shapes are in the Reference.

Authentication

Your secret key authenticates API requests. Send it as a bearer token:

curl -X POST https://api.payzero.ai/checkout/deposit \
  -H 'Authorization: Bearer pz_sk_test_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ...payment fields... }'

The key identifies your merchant and which environment the request runs in: use your test key against the sandbox and your live key in live, so the same request routed with a test key never touches real money. A key looks like pz_sk_test_YOUR_KEY — a prefix that names the environment, then the credential.

Each key is issued from the portal and shown once. Treat it like a password: keep it on your server, never ship it to a browser or commit it to source, and have it reissued from the portal if it leaks. It carries the Authorization header on requests that create or read your own payments; some checkout lookups are public and need no key, so reach for it on server-to-server calls rather than trying to enumerate which endpoints demand it.

Payment methods

Two methods are available. Both are redirect flows: you create the payment through the API, send the customer to the redirectUrl it returns, and confirm the outcome afterwards with GET /checkout/status.

Amounts use the currency's normal decimal form, as documented per endpoint. EUR takes two decimal places — "25.00". JPY has none, so a yen amount is a whole number: 500, never 500.00. No sign, no exponent, no thousands separator, no currency symbol.

Bank transfer: the customer selects an available amount

This is the constraint to design around. With bank transfer the customer does not enter an amount. They choose a bank, then choose one of the exact amounts available for that bank at that moment. There is no rounding, no nearest match, no partial fill and no combining of two amounts.

Availability changes continuously. An amount listed a minute ago may be gone, a bank may have nothing available, and the method as a whole can be temporarily unavailable. Design for that:

• Fetch availability immediately before you show it, and refresh it if the customer pauses.
• Build a "no amounts available" state with real copy and a real next action. Nothing has gone wrong when it appears.
• Offer card as a fallback. For a Japanese customer that fallback is a euro charge.
• Bank transfer suits top-ups, wallet funding and account credit. It cannot collect a fixed cart total unless that exact amount happens to be available.
• Reconcile the amount actually paid against your own order afterwards, using the reference.

Cards are charged in euro

Card payments are processed in EUR only. A Japanese cardholder is charged in euro and their own bank sets the exchange rate, so the yen figure on their statement will not be the figure you displayed. Tell them before they pay.

The minimum card payment is 1.00 EUR and the maximum is 10,000.00 EUR. A postal code is required. Card details are entered by the customer on the secure payment page — POST /checkout/card refuses any request containing a card number, expiry, CVV or similar field.

Status and settlement

Settlement is confirmed asynchronously. When the customer finishes on the payment page they are returned to a PayZero page. That return means a browser came back — nothing more.

A customer returning from the payment page does not mean the payment succeeded. Confirm every payment with GET /checkout/status?ref=… before you release goods or credit an account.

Card payments typically resolve within seconds of the customer finishing on the payment page. Bank transfers take longer, and there is no guaranteed time to settlement. Poll every few seconds while the customer is waiting, then back off to minutes, and treat a pending payment as a normal state in your order flow rather than an error.

Guides

The things worth getting right before you ship: how to test an integration against the sandbox, and what changes when you move to live.

Testing

PayZero provisions a sandbox environment before go-live. It is the same API — the same endpoints, request bodies and response shapes — pointed at the payment provider's test environment. Nothing in it moves real money, and every card number below is a test number that works in sandbox only.

Use a different customer email for each test payment. Repeating the same customer details, bank and amount while an earlier payment is still unfinished can be refused, and it reaches you as psp_error rather than as anything that names the cause.

Bank transfer in sandbox

The amounts a sandbox bank offers are live test inventory, not a fixture. Expect the list to differ between runs, and expect it to be empty sometimes — for one bank, or for every bank at once. Sandbox behaves the way live behaves here, which makes it the place to exercise that constraint rather than something to work around; see Bank transfer: the customer selects an available amount. Do not write a test that depends on a particular amount being available.

Creating a deposit reserves that amount immediately, in sandbox as well as live, whether or not anyone completes it. Looping over POST /checkout/deposit will exhaust the amounts available to your next test.

Confirming a test payment

A customer returning from the payment page means a browser came back and nothing more, in sandbox exactly as in live. GET /checkout/status?ref=… is what confirms a payment: poll it until settled is true, then read status. See Status and settlement.

What sandbox cannot simulate

• A specific card decline reason. You can decline the authentication; you cannot choose the reason an issuer would refuse the charge.
• A dispute. There is no way to raise one against a test payment.
• A settlement notification on demand. A payment notifies when it settles, and there is no way to ask for that notification again.

Sandbox and live

Sandbox and live are the same API pointed at different environments, so anything you build against the checkout endpoints — banks, amounts, deposit, card, status — works the same in both, and bank transfer in particular behaves identically.

The one difference is how a card is captured. In live, card details are entered by the customer on the secure payment page: you call POST /checkout/card and send them to the redirectUrl. The Card API (sandbox) — hosted sessions and direct card — accepts card details through PayZero for building and testing, and does not run in live; a card API request against a live environment is answered 403 card_direct_sandbox_only before its body is read.

PayZero provisions your sandbox before go-live. When your integration is working against it, the same code points at live — nothing in the checkout flow changes but the card-capture path above.

curl -X POST https://api.payzero.ai/checkout/session \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "<your-card-direct-key>",
    "amount": "25.00",
    "currency": "EUR",
    "firstName": "Aoi",
    "lastName": "Tanaka",
    "email": "aoi.tanaka@example.com",
    "dateOfBirth": "1990-04-18",
    "postCode": "100-0001",
    "returnUrl": "https://checkout.example.com/return"
  }'

{
  "sessionId": "0f31c7a89bd44e21a6c05d9e8f3b7a12",
  "url": "https://sandbox.payzero.ai/pay/0f31c7a89bd44e21a6c05d9e8f3b7a12",
  "expiresAt": "2026-07-22T09:15:00.000Z"
}

{
  "amount": "25.00",
  "currency": "EUR",
  "expiresAt": "2026-07-22T09:15:00.000Z",
  "status": "open"
}

{
  "reference": "PZ-MJ4K6D8R-5B2F9C31",
  "status": "PENDING",
  "requires3ds": true,
  "redirectUrl": "https://secure.example-psp.com/3ds?token=41c9e2"
}

curl -X POST https://api.payzero.ai/checkout/card-direct \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "<your-card-direct-key>",
    "amount": "25.00",
    "currency": "EUR",
    "firstName": "Aoi",
    "lastName": "Tanaka",
    "email": "aoi.tanaka@example.com",
    "dateOfBirth": "1990-04-18",
    "postCode": "100-0001",
    "cardNumber": "4012888888881881",
    "expDate": "12-30",
    "cvv": "123",
    "nationalId": "AB123456"
  }'

{
  "reference": "PZ-MJ4K7E3S-8C4A1D62",
  "transactionId": "TR-8842164",
  "amount": "25.00",
  "currency": "EUR",
  "status": "PENDING",
  "requires3ds": true,
  "redirectUrl": "https://secure.example-psp.com/3ds?token=7d20b5"
}

Reference

Every endpoint, field by field, with a runnable example and the errors it can return, then the consolidated error table, what the API does not do, and how to reach support. The flow these fit into is in Getting started.

GET /checkout/banks

Lists the banks available for bank transfer, each with a snapshot of what it currently has on offer. Takes no parameters.

curl https://api.payzero.ai/checkout/banks \
  -H 'Origin: https://checkout.example.com'

{
  "banks": [
    { "swiftCode": "MHCBJPJT", "bankName": "Mizuho Bank", "available": 3, "amounts": [100, 500, 777] },
    { "swiftCode": "BOTKJPJT", "bankName": "MUFG Bank", "available": 0, "amounts": [] }
  ]
}

swiftCode is the bank identifier you pass to the other bank transfer endpoints. available is how many amounts the bank has on offer right now, and amounts lists the distinct ones, ascending. Banks are ordered by available, highest first; available: 0 means that bank has nothing on offer at this moment and is not an error. Use this endpoint to build a bank picker, not to reserve anything — availability is confirmed again when you create the payment.

Errors: origin_not_allowed, rate_limited, psp_error, internal.

GET /checkout/amounts

The exact amounts currently available for one bank.

curl 'https://api.payzero.ai/checkout/amounts?bank=MHCBJPJT' \
  -H 'Origin: https://checkout.example.com'

{
  "swiftCode": "MHCBJPJT",
  "amounts": [
    { "id": 84213, "amount": 100, "currency": "JPY" },
    { "id": 84219, "amount": 777, "currency": "JPY" }
  ]
}

Each entry is one amount the customer can choose: id is what you send as activeAmountId, amount is a whole number of yen, and currency is JPY.

An empty amounts array means the bank has nothing available. It is a normal answer, not an error. Identifiers rotate within minutes, so fetch this immediately before the customer chooses.

Errors: bad_bank, origin_not_allowed, rate_limited, psp_error, internal.

POST /checkout/deposit

Opens a bank transfer payment for one of the available amounts and returns the URL to send the customer to.

Send amount as well as activeAmountId. Identifiers rotate, and if the one you hold has changed since you fetched it, PayZero binds another entry at the same amount instead of failing. Without amount a rotated identifier returns 409 slot_taken. The authoritative amount is always the one PayZero confirms, never the one in your request.

curl -X POST https://api.payzero.ai/checkout/deposit \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://checkout.example.com' \
  -d '{
    "swiftCode": "MHCBJPJT",
    "activeAmountId": 84219,
    "amount": 777,
    "firstName": "Aoi",
    "lastName": "Tanaka",
    "email": "aoi.tanaka@example.com",
    "dateOfBirth": "1990-04-18",
    "city": "Tokyo",
    "address": "1-1 Chiyoda"
  }'

{
  "reference": "PZ-MJ4K2X9A-7F3C1B92",
  "transactionId": "TR-8842119",
  "amount": 777,
  "currency": "JPY",
  "status": "WAITING",
  "redirectUrl": "https://secure.example-psp.com/s/9f2ac1"
}

reference is PayZero's identifier for this payment — store it against your order. transactionId is the payment provider's. amount is the confirmed amount in JPY. status describes the redirect step and is not a payment outcome. Send the customer to redirectUrl to authorise the transfer.

409 slot_taken means the amount was taken between your two calls. The response body carries a fresh amounts array in the same shape as GET /checkout/amounts, so you can re-offer the choice without another round trip.

Errors: bad_json, bad_bank, bad_amount, bad_name, bad_email, bad_dob, slot_taken, invalid, merchant_suspended, unknown_merchant, origin_not_allowed, rate_limited, rejected, psp_error, internal.

POST /checkout/card

Opens a card payment and returns the URL of the secure payment page.

Do not send card details. A request containing a card number, expiry, CVV, PIN or track data — under any spelling, at any nesting depth — is refused whole with 400 card_data_not_accepted, and nothing in it is read or forwarded. In sandbox there is a separate card API that does accept card details, for building and testing only — see Card API (sandbox).

curl -X POST https://api.payzero.ai/checkout/card \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://checkout.example.com' \
  -d '{
    "amount": "25.00",
    "currency": "EUR",
    "firstName": "Aoi",
    "lastName": "Tanaka",
    "email": "aoi.tanaka@example.com",
    "dateOfBirth": "1990-04-18",
    "postCode": "100-0001",
    "country": "JP",
    "city": "Tokyo",
    "address": "1-1 Chiyoda"
  }'

{
  "reference": "PZ-MJ4K3B1Y-2D8E4A07",
  "transactionId": "TR-8842137",
  "amount": "25.00",
  "currency": "EUR",
  "status": "PENDING",
  "redirectUrl": "https://secure.example-psp.com/pay?token=8f21c0"
}

reference is PayZero's identifier for this payment — store it against your order. amount comes back normalised to two decimal places. status is always PENDING here: no card has been entered yet. Send the customer to redirectUrl to enter their card.

Errors: bad_json, card_data_not_accepted, currency_not_supported, bad_amount, bad_name, bad_email, bad_dob, bad_country, bad_post_code, merchant_suspended, unknown_merchant, origin_not_allowed, rate_limited, rejected, psp_error, internal.

GET /checkout/status

The current state of one payment. Works for both methods.

curl 'https://api.payzero.ai/checkout/status?ref=PZ-MJ4K3B1Y-2D8E4A07' \
  -H 'Origin: https://checkout.example.com'

{
  "reference": "PZ-MJ4K3B1Y-2D8E4A07",
  "settled": true,
  "status": "APPROVED",
  "amount": "25.00",
  "currency": "EUR",
  "paymentMethod": "CREDIT_CARD",
  "source": "ipn"
}

source says where the answer came from: ipn — an authenticated settlement notification. deposit — the payment exists and no notification has arrived yet. inbox — no record was found for this reference.

An unrecognised reference is not an error. A typo returns settled: false, status: "PENDING" and source: "inbox", which is indistinguishable from a payment that has not settled yet, so check the reference you stored rather than inferring existence from this endpoint.

This endpoint is not authenticated: anyone holding a reference can read its amount, currency and status. Treat a reference as you would an order number that should not be published.

Errors: bad_reference, origin_not_allowed, rate_limited, internal.

Errors

Every error response carries an error code string, and most also carry a human-readable message — { "error": "bad_amount", "message": "…" }. Some carry extra fields, noted below. Match on error, never on message.

Not currently available

Support

Lead with the reference. It looks like PZ-MJ4K2X9A-7F3C1B92, it is returned when the payment is created, and it identifies that payment everywhere — in the API, at the payment provider, and on the settlement notification. With it a payment can be traced end to end. Without it, very little can be answered.

Email info@payzero.ai and include:

Do not send card numbers. The API refuses them and so do we.