Payments

This guide covers money through the API as an integrator meets it: how a buyer's payment becomes a paid order, how your share reaches you as payouts, how refunds and reversals unwind a sale, and the records your integration keeps so any amount can be explained. Endpoint detail is in Payments Endpoints. The legal basis for how the Platform handles sale proceeds is the Selling Terms of Service, summarized below; the amounts your account is charged are in your account's fee terms, not in this guide.

Goal and prerequisites

Goal: for any order, your integration can answer "show me the flow of funds": what the buyer paid, what was deducted, what you received or will receive, and what was reversed and why: from records, not from reconstruction.

Prerequisites: an account in good standing with payout details completed in the Seller Center (buyers' payments cannot settle to an account whose payout setup is unfinished), orders flowing in (Orders), and a subscription to payment events (Webhooks).

How money moves

1. The buyer pays the Platform at checkout. The order is created in a payment-pending state; its line items carry the prices as charged, and those frozen values are the record of the sale (Orders).
2. The Platform confirms payment. Confirmation arrives through the Platform's payment processing: never through the buyer's return to a success page, which proves nothing. On confirmation the order moves to paid, and only then does fulfillment begin (Fulfillment).
3. Your share settles as a payout. Under the Selling Terms of Service, each seller appoints the Platform as its limited payment collection agent: the Platform accepts the buyer's payment on your behalf, deducts the amounts your terms provide for (platform fees, and any reserves or adjustments those terms allow), and pays the remainder to your payout account on the payout schedule in your terms. Payment by the buyer to the Platform is payment to you: the buyer's obligation is satisfied at that point, and settlement to you follows the schedule.
4. Payout timing is deliberate. Payouts settle after a delay stated in your terms. The delay is the dispute window made mechanical: funds remain reachable for refunds and reversals while a buyer can still dispute the sale, instead of being clawed back from an empty balance.

Keep the three records distinct in your own books: the buyer's charge, the deductions, and your payout are three facts, and collapsing them into one net figure is how reconciliation fails.

Reading payment state

Use Payments Endpoints to read, per order or per payout: the amount charged, the currency, the amounts deducted, the amount payable to you, the payout state, and any reversals. Money is always a decimal string with a currency (Overview): reconcile in decimal arithmetic, in the stated currency, and never assume a payout equals an order total: fees, reserves, and adjustments sit between them by design.

Refunds and reversals

When a sale unwinds: a return (Returns), a cancellation, a fulfilled-never-delivered order, a buyer dispute: the money unwinds with it

• Refunds to the buyer are issued through the returns and orders flows and recorded against the original payment. Issue them with an Idempotency-Key (Idempotency Keys); a retried refund must never pay twice.
• Reversals against your balance recover amounts already earmarked or paid to you when the Platform makes the buyer whole: the reversal is recorded against the original sale with its reason, and appears in your payment records: read it there rather than discovering it in a short payout.
• Reserves and holds may apply under your terms: for elevated dispute rates, new accounts, or specific orders. A hold is visible in the payment record with its ground; if your integration reconciles payouts, it must read holds as data, not treat every shortfall as an error.
• Capability consequences follow sustained problems: an account whose disputes or fraud signals stay high can have payouts paused while the underlying issue is remediated, under the Seller Enforcement Policy and Governance.

Card data never touches your integration

Buyers' card details are collected and processed by the Platform's payment processing; they never pass through the API, and they must never pass through your systems. Your integration receives payment identifiers, amounts, and states: never card numbers, never security codes. If any part of your system finds itself accepting, logging, or transmitting raw card data, stop that flow and contact support@aapawz.com: handling raw card data forfeits payment-related scopes under the API Access Tiers and creates liability no integration benefit justifies.

Reconciliation

Reconcile on a short cadence: daily beats monthly, because drift is cheap to find the day it happens

1. Pull payouts and their component sales through Payments Endpoints with cursor pagination (Pagination & Filtering).
2. Match each component to an order in your records by Platform id; match amounts in decimal, in currency.
3. Account for every difference with a named category: fee, reserve, reversal, refund, timing (earned, not yet payable). A difference without a category is an open item, not a rounding note.
4. Investigate open items older than one payout cycle with support@aapawz.com, quoting the payment and order identifiers.

Failure handling

• Order paid but no payout line appears: check the payout schedule first (settlement is delayed by design), then holds, then read the payment record directly before escalating.
• Amount mismatch: re-read the payment record; the frozen line items on the order (Orders), not the current catalog price, are what the buyer was charged.
• 5xx on a refund or a payment write: retry with the same idempotency key after backoff; never issue the same refund under a fresh key to "make it go through."
• Webhook received for an unknown payment id: fetch it through Payments Endpoints under your account's scope; an id that does not resolve under your account is not yours to act on.

What to persist

For every sale: the order id, the payment identifier the API returns, amounts charged, deducted, and payable, the payout it settled in, and every reversal with its reason. Keep these records for at least the dispute and tax windows your terms state. "Show me the flow of funds" must have a one-lookup answer in your system, because a buyer, an auditor, or a dispute will eventually ask it.