Skip to main content

Credit memo lifecycle: end-to-end guide

This guide walks a Paystand X API-connector developer through the full credit memo path: create a credit memo via the public API, confirm it's available at checkout, and observe the webhook events once a payer applies it.

Prerequisites​

  1. A payer customer must already exist. Credit memos link to a payer customer by extCustomerId — create one first via Create Customer if it doesn't exist yet.
  2. Credit memo checkout must be enabled for the merchant. This is the standard credits_v3 plan feature — ask your Paystand account contact to confirm it's enabled if credit memos aren't appearing at checkout. It's not something your connector configures via the API.
  3. Optional — subscribe to webhooks. Configure a webhook URL in Dashboard → Integrations → Webhook Event URLs if you want event notifications instead of polling. See Webhook setup.

1. Create the credit memo​

POST /v3/creditMemos
Authorization: Bearer {access_token}
X-CUSTOMER-ID: {merchant_customer_id}
Content-Type: application/json

{
  "extId": "CM-1001",
  "extKey": "CM-1001",
  "extCustomerId": "CUST-001",
  "amount": 100,
  "amountRemaining": 100,
  "currency": "USD",
  "status": "active",
  "extCreationDate": "07-30-2026",
  "extPostedDate": "07-30-2026"
}

See Create Credit Memo for the full field reference, date format requirements, and the exact error contracts for a duplicate extId, an unknown extCustomerId, or a disallowed currency.

This is a strict-create endpoint, not an upsert. If you retry after a timeout without checking first, a second call with the same extId returns an explicit rejection rather than silently succeeding or creating a duplicate — see the reference page's idempotency section before wiring retry logic.

2. Confirm it's available at checkout​

Fetch it back to confirm it persisted with the fields you expect:

GET /v3/creditMemos/{creditMemoId}

Or list your merchant's own credit memos with List Credit Memos (f.querytype=own, the default).

A credit memo is eligible to appear at a payer's checkout when all of the following hold — the same rules that already apply to CSV-imported credit memos:

  • status is active
  • amountRemaining is greater than zero
  • currency matches the currency of the invoice(s) the payer is checking out — a credit memo in a currency your merchant isn't provisioned for will have been rejected at creation (see step 1)

No separate "publish" or "activate for checkout" call is needed — a credit memo created via the API becomes available the moment it's persisted, indistinguishably from one imported via CSV.

3. Payer applies it at checkout​

This step happens on the payer's side, not via an API call from your connector. When the payer checks out an eligible invoice, they see the credit memo(s) available to them and can select one or more to apply:

  • If the selected credit memo(s) fully cover the invoice, no payment method is required.
  • If they only partially cover it, the payer pays the remainder through a payment method as usual.
  • Convenience fees are never applied to the portion covered by credit memos.

4. Observe the resulting webhook events​

Once the payer applies the credit memo, two independent event signals fire:

  1. credit_memo.updated — the credit memo's own amountRemaining (and status, if fully consumed) changes.
  2. receivable_transactions.created — the payment-application signal. If the payment was covered entirely by credit memo(s), you'll get one such event per credit memo consumed. If it was a mixed credit + cash/card payment, you'll get a Payment-typed event plus a CreditMemo-typed event per contributing credit memo, correlated by a shared paymentId.

See Credit Memo Events for the exact payload shapes, including the async delivery lag between a Payment-typed event and its CreditMemo-typed sibling(s) on a mixed payment.

If you're not using webhooks, re-fetch the credit memo via Get Credit Memo after the payer completes checkout and check amountRemaining/status directly.

5. Update, cancel, or reactivate as the ERP record changes​

  • Amount or other field changes (not status): Update Credit Memo (PUT /creditMemos/:id). Do not send status here.
  • Void from the ERP side: Cancel Credit Memo (PATCH /creditMemos/:id/cancel). A canceled credit memo stops appearing as available at checkout immediately.
  • Restore a previously canceled credit memo: Activate Credit Memo (PATCH /creditMemos/:id/activate).

Each of these fires its own webhook event (credit_memo.updated, credit_memo.canceled, credit_memo.activated respectively) — see Credit Memo Events.