Operate payments

Payment operations begin after checkout has created a Payment Intent. Support and finance teams need to distinguish customer navigation, Paybytoken resource state, webhook delivery and on-chain evidence instead of treating them as one status.

Use the right source for each question

A browser return, embedded completion event or transaction hash alone is not a fulfillment decision. If two signals disagree, retrieve the Paybytoken resource from your server and preserve the disagreement for investigation.

Build a support lookup

Accept one of your own order IDs and resolve its stored Checkout Session and Payment Intent IDs. Retrieve the complete Payment Intent rather than asking a customer to provide a payment address, client secret or hosted URL.

Show authorized support users:

• amount, asset, chain and canonical status;
• Checkout Session and Payment Intent IDs;
• received, remaining, overpaid and refunded amounts;
• transaction hash and payment activity when available;
• linked refund and Balance Transaction IDs; and
• Event and webhook delivery state.

Do not expose API keys, webhook secrets, signatures, hosted fragment capabilities, complete embedded client secrets or internal risk details. Resource IDs and X-Request-Id values are the normal references to include in an escalated support case.

Refund a successful payment

Create a Refund from a trusted server with a stable idempotency key. Omit amount only when the operator explicitly intends to refund the complete remaining refundable amount.

const refund = await paybytoken.refunds.create(
  {
    payment_intent: paymentIntent.id,
    amount: '10.00',
    reason: 'requested_by_customer',
    metadata: { case_id: supportCase.id },
  },
  { idempotencyKey: `refund:${supportCase.id}:v1` },
)

The refund method follows the original payment method. Customer-balance and Paybytoken Pay refunds return to the original balance relationship. Crypto-transfer refunds follow the original-sender safety policy and do not accept an arbitrary destination address.

A pending Refund is not complete. Reverse goods, access or accounting only through an idempotent workflow driven by verified refund.* events and the canonical Refund state.

Reconcile ledger movement

Merchant Balances are exact chain-and-asset projections. Balance Transactions explain individual credits, debits and fees. Never sum Base USDC and Ethereum USDC as if they were one spendable balance merely because their display currency is similar.

For each financial resource:

1. retrieve its related Balance Transaction;
2. compare resource amount, fee and signed ledger total;
3. verify chain and asset match the intended balance row;
4. record the resource and ledger IDs in your accounting export; and
5. alert rather than auto-correct when the relationship is missing or inconsistent.

Payment Request reconciliation adds allocation state: review unapplied payments and aggregate drift separately from ordinary merchant Balance Transactions.

Investigate asynchronous transfers

Payouts, customer withdrawals and crypto-transfer refunds can remain pending while chain work is submitted and confirmed.

• pending means processing continues; do not create a replacement automatically.
• succeeded is the terminal success state.
• failed is terminal for that resource; inspect the safe error and balance outcome before retry.
• requires_attention, where supported, belongs in an operator queue.

The appearance of a transaction hash does not override resource state. A missing browser return does not imply failure. Use the resource ID to correlate Core state, Events, webhook delivery and chain activity.

Retry delivery, not the business event

An Event is an immutable business fact. A Webhook Event is one delivery attempt. Retrying a failed delivery must not create another payment, Refund, Payout or merchant order transition.

Deduplicate your handler by Event ID even when operators retry delivery. If a handler already committed business state but its response was lost, the repeated delivery should return success without applying the operation again.

Incident checklist

• Stop creating replacement financial resources until canonical state is known.
• Record order, Session, Payment Intent, Event and request IDs.
• Retrieve current resource state with a server key in the correct mode.
• Inspect webhook response code, attempts and last error.
• Compare the related Balance Transaction and exact chain/asset balance.
• Check chain activity without treating explorer data as the ledger.
• Preserve evidence and escalate rather than editing financial tables manually.

See API errors, Events, Refunds, Balance Transactions and Payouts for resource contracts.