Bookkeeper API

Bookkeeper API — PayTo payout with optional split retain on the business ledger.

HTTP: POST /api/public/payment_initiation

When split_percentage_fee is set (for example 20 or "20%"):

  • For amount $100, $80 is paid out immediately (to destination when provided,
    otherwise the merchant payout account)
  • $20 remains on the business ledger and is transferred end of day

split_percentage_fee and destination are both optional on a first settlement.

A failed destination payout is retried with the received payment id, not the PayID address and not the failed settlement id:

{
  "payment_initiation": {
    "payment_initiation_id": "PYIDN01184126905",
    "recover": true
  }
}

recover is optional. Leave it out and the existing PayID or payment-agreement request settles the first unpaid payment as it does today. amount, split_percentage_fee, notes, and destination are not accepted when recover is true. The saved split and destination on that payment are reused. A retry creates a new settlement id. The failed settlement id stays failed.

Error Codes

CodeStatusReasonWhat to do
PAM_SB_PAG_NOT_FOUND_ERROR404Payment agreement not foundVerify payment_agreement_id and merchant ownership.
PAS_AGREEMENT_STATUS_INACTIVE422Agreement is not activeActivate agreement before initiating payment.
R804422Duplicate/too-soon payment initiation detectedWait for cooldown window and retry once eligible.
R101422Amount exceeds per-transaction/agreement limitReduce amount to allowed limit.
R103422Destination payout not allowed for merchant settingsEnable eligible payout settings or remove destination.
R803422Upstream initiation failedRetry; if persistent, contact support with request metadata.
CREDITS_EXHAUSTED402Developer credits exhaustedTop up developer credits and retry.
GN-0000422Invalid split_percentage_feeUse a number greater than 0 and less than 100 (e.g. 20 or "20%").
—409No recovery is pendingSend recover: true only for a payment whose destination payout failed.
—409Payment already settled, in progress, or outcome unknownDo not send another payout. Wait, or contact support when the outcome is unknown.
—422amount, split_percentage_fee, notes, or destination was sent with recover: trueRetry with only payment_initiation_id and recover: true.
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Bookkeeper request body for POST /api/public/payment_initiation.
Send split_percentage_fee inside payment_initiation to retain a share on the ledger for EOD.
Do not send destination when payment_initiation is a payment_initiation_id retry.

payment_initiation
required

Pay from

destination
object

Destination payout account details used when instant payout is enabled.

Responses

Language
Credentials
Bearer
JWT
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json