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,$80is paid out immediately (todestinationwhen provided,
otherwise the merchant payout account) $20remains 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
| Code | Status | Reason | What to do |
|---|---|---|---|
| PAM_SB_PAG_NOT_FOUND_ERROR | 404 | Payment agreement not found | Verify payment_agreement_id and merchant ownership. |
| PAS_AGREEMENT_STATUS_INACTIVE | 422 | Agreement is not active | Activate agreement before initiating payment. |
| R804 | 422 | Duplicate/too-soon payment initiation detected | Wait for cooldown window and retry once eligible. |
| R101 | 422 | Amount exceeds per-transaction/agreement limit | Reduce amount to allowed limit. |
| R103 | 422 | Destination payout not allowed for merchant settings | Enable eligible payout settings or remove destination. |
| R803 | 422 | Upstream initiation failed | Retry; if persistent, contact support with request metadata. |
| CREDITS_EXHAUSTED | 402 | Developer credits exhausted | Top up developer credits and retry. |
| GN-0000 | 422 | Invalid split_percentage_fee | Use a number greater than 0 and less than 100 (e.g. 20 or "20%"). |
| — | 409 | No recovery is pending | Send recover: true only for a payment whose destination payout failed. |
| — | 409 | Payment already settled, in progress, or outcome unknown | Do not send another payout. Wait, or contact support when the outcome is unknown. |
| — | 422 | amount, split_percentage_fee, notes, or destination was sent with recover: true | Retry with only payment_initiation_id and recover: true. |
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||