Payments

There is no payments endpoint in v2. Payments are written in exactly two ways: a secret key can record one or more payments when it creates an order, and a shopper can pay through a hosted checkout session. Payment state is read back off the order, and observed in real time through webhooks.

There is no POST /api/v2/payments, no GET /api/v2/payments, no refunds endpoint, and no way to update or void a payment over the API. The payments:read and payments:write scopes exist in the scope enum but back no endpoint, and are not offered when you create an API key.

Recording a payment on order create

Attach a payment (single) or payments (array) block to the order create body. This is secret-key only; the orders endpoint does not accept publishable keys. Each recorded payment updates the order's amount_paid / balance_due, derives its payment_status, and auto-confirms a fully paid order.

Payment fields

Name
amount
Type
number
Description
Required. Greater than 0 and no greater than 100000000.
Name
method
Type
string
Description
card, cash, bank_transfer, check, paypal, apple_pay, google_pay, afterpay, klarna, store_credit, imported, or other. Aliases: credit_card to card, wire_transfer to bank_transfer, cheque to check. Matching is case-insensitive, and an unknown or omitted value maps to other.
Name
status
Type
string
Description
Default completed. Only pending, completed and approved may be created; any other value is rejected with 400. Adverse states (failed, cancelled, refunded, partially_refunded, disputed) and the intermediate ones (processing, pending_verification) are lifecycle transitions owned by the payment service and cannot be set from a create body. completed and approved both count toward amount_paid; pending does not.
Name
paid_date
Type
string
Description
ISO 8601. Used as the completion timestamp for a completed payment, defaulting to now. Ignored for a non-completed payment, which carries no completion timestamp.
Name
currency
Type
string
Description
Optional. If given it must match pricing.currency (case-insensitive) or the request is rejected with 400. Defaults to the order currency.
Name
tip_amount / fee_amount
Type
number
Description
Optional tip and gateway fee. A tip is added to the amount counted as paid.
Name
reference / transaction_id
Type
string
Description
Optional internal reference and external gateway transaction id.
Name
description / notes
Type
string
Description
Optional free text. description defaults to API payment.

Do not send a top-level payment_status together with a payment - it is ignored, and the recorded payments derive it. Payment recording is non-fatal: a failure returns 201 with the order plus payment_errors[] (each entry carries the failing block's index). Recording more than the order total is allowed but returns a warnings[] entry.

Request

POST

/api/v2/orders

curl -X POST https://au.api.ibakepro.com/api/v2/orders \
  -H "Authorization: Bearer {secret_key}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-paid-0001" \
  -d '{
    "customer": { "first_name": "Jane", "email": "jane@example.com" },
    "items": [ { "name": "Chocolate Birthday Cake", "quantity": 1,
                 "unit_price": 85.00 } ],
    "pricing": { "subtotal": 85.00, "total": 85.00, "currency": "AUD" },
    "payments": [
      { "amount": 35.00, "method": "card", "paid_date": "2026-05-20T00:00:00Z" },
      { "amount": 50.00, "method": "cash", "paid_date": "2026-06-01T00:00:00Z" }
    ]
  }'

Response (201, excerpt)

{
  "id": "HR7Pcz4Arg6kvZKseSil",
  "payment_status": "paid",
  "amount_paid": 85.00,
  "balance_due": 0,
  "payment_ids": ["kQ2mA8f1XbTn0pLdWc7e", "vT7bR2mYqL5nD8XwC3fJ"]
}

payment_ids is present only when at least one payment was recorded, in the order the blocks were supplied.

Payment data on orders

Retrieving an order (GET /api/v2/orders/:id) returns payment_status, amount_paid (the order's stored totalPaid, maintained transactionally by the payment writer) and balance_due, computed as max(0, pricing.total - amount_paid). Individual payment records are not exposed by the API; use these fields to reconcile payment state.

Payment events

To react to payments in real time, subscribe to the payment webhook events: payment.created, payment.updated, payment.completed, payment.failed, and payment.refunded. See Webhooks.

Emission rules worth knowing:

A payment created as completed or approved emits both payment.created and payment.completed, so an integration subscribed only to payment.completed still sees the money land.
A refund emits payment.refunded only. It does not also emit created or completed.
Payments recorded on order create emit nothing by default. Set emit_webhooks: true on the order create body if you want them to fire. The default exists so that bulk imports of historical orders do not replay years of payment events. Payments taken through a hosted checkout session are unaffected and always emit.

Webhook delivery is fire-and-forget: a failed emit never fails the payment write.

Taking a payment from a customer

To actually charge a card, use Checkout. POST /api/v2/checkout creates a hosted, pay-first session; ibakepro mints the order and records the payment when the shopper pays. There is no API surface for creating a charge directly.