Skip to main content

Chaining IDs across API calls

Paystand uses several ID types. Store the right ID from each response to avoid broken links in your ERP.

ID reference​

IDWhere you get itUse for
Merchant customer_idDashboard → IntegrationsX-CUSTOMER-ID header on every call
payerCustomer.idCreate/List/Get CustomerpayerCustomerId on receivables; credit memo customer scope. Not the same as payment.payerId unless that payer is listed under your merchant — wrong IDs return 401 on Get Customer.
extCustomerIdYour ERP customer key (sent on create)Alternative to payerCustomerId on receivable create/update
receivable.idCreate/Get/List ReceivableAttachments, cancel, receivable transactions
extId / invoice keyYour ERP invoice numberReceivable create; filter helpers on receivable list
payment.idPayment webhooks or List PaymentsMerchant fee lookup (fees[]), payer fee split (feeSplit), refunds, reconciliation
fee.idFee webhooks or List FeesGL lines for merchant processing fees (not payer recoup)
feeSettingPlan.idGet Fee Setting Plan when you have an ID; or infer rates via Split FeesPre-payment payer fee estimates
creditMemo.idCredit memo APIsCancel/activate credit memos. Create requires extKey, status, numeric amount / amountRemaining, and MM-DD-YYYY dates — see Create Credit Memo
transfer.idList/Get TransferPayout reconciliation

Example flow​

  1. POST /payerCustomers → save id as payerCustomerId.
  2. POST /receivables/create with payerCustomerId (or extCustomerId) → save receivable.id.
  3. Payment webhook includes payment.id → GET /payments/{id} for details.
  4. Merchant processing fee webhook references payment → GET /fees with filter on resourceId when authorized, GET /payments/{id} embedded fees[], or use fee id from the event payload. For payer-side split, read feeSplit on the same Get Payment response.
  5. Pre-payment payer fee split → POST /feeSplits/splitFees with payment subtotal and optional payerId / invoiceId / feeSettingPlanId — see Split Fees. For single-rail estimates only, POST /feeSplits/computeFees accepts feeType + subtotal + currency (no payer/invoice context).

ERP keys vs Paystand IDs​

Prefer storing both your ERP key (extCustomerId, invoice extId) and Paystand’s id. If you re-sync from ERP, match on ERP keys; use Paystand id for all subsequent API paths (/receivables/{id}/cancel, etc.).