TrapGod / Documentation / Payment ledger
Payment ledger
Post a Backout charge to the app ledger. The same backout_ref updates one row.
Payment ledger
The ledger is the list of charges this app reported. Backout still holds the card charge. TrapGod does not charge the card and does not pull a statement from Backout. A row appears only after the partner server posts it.
When to post
After Backout accepts, fails, or refunds a charge for this app, post one row. Use the Backout charge, session, or intent id as backout_ref. Post again with the same backout_ref when the status changes. That updates the same row.
Request
POST https://trapgod.net/api/link_app_payment.php
X-Trapgod-Application: tgaid_0123456789abcdef01234567
X-Trapgod-Key: TRAPGOD_KEY
Content-Type: application/json
{
"handle": "name_on_this_app",
"username": "trapgod username",
"amount_cents": 500,
"currency": "usd",
"status": "paid",
"backout_ref": "chg_12345678"
}Leave structure_id off to use the default structure saved on the app. Send it only when the charge used a different structure that is also saved on that app. It is 32 hex characters.
| Field | Required | Rule |
|---|---|---|
amount_cents | yes | Whole cents, 0 through 10000000. A string of digits is accepted. |
status | yes | pending, paid, failed, or refunded. |
backout_ref | yes | 8 to 64 characters: letters, numbers, _, or -. This is the idempotency key. |
currency | no | usd only. Omitted means usd. |
handle | no | Letters, numbers, _, or -, up to 40 characters. The badge handle does not allow a hyphen. This field does. |
username | no | If that TrapGod user exists, the row stores their numeric id as actor_id. A missing user does not fail the post. |
structure_id | no | Must already be saved on the app. Omitted uses the default structure. |
pending, paid, and refunded must be at least 50 cents. failed may be 0 cents.
Success
HTTP 200. A new row and an update of an existing ref both return this shape:
{"ok":true,"id":123,"trace_id":"TRACE_ID"}TrapGod writes an alert only when the row is new or the status changed. Posting the same status again still returns 200 and does not send another alert.
How to track it
- Save
idandtrace_idfrom the response on the partner server, next to the Backout id. - Open
/admin/apps/ledger/?id=APP_ID. Staff, a sub admin, and a super admin can read it. - Each row shows Eastern time, handle, structure label and id, amount, status,
backout_ref, actor id, and trace id. - The page lists the latest 100 rows for that app. Older rows stay in
link_app_pay_ledger. - Actor
0is shown as-. That means the post did not name a TrapGod user that exists. - Usage traces for the post use action
link_app.pay_recordorlink_app.pay_deny, rolepartner, and the sametrace_id.
The ledger page does not show the Backout key or the TrapGod API key.
Errors
| Condition | HTTP | error |
|---|---|---|
| Not POST | 405 | POST only. |
| Body is not JSON | 400 | Send JSON. |
| Body larger than 4096 bytes | 413 | That body is too large. |
| No application id, or no key | 401 | That key was rejected. |
| Application id and key are not the same active app | 401 | That key was rejected. |
| Header and body application ids differ | 401 | That key was rejected. |
| Bad status | 400 | Status must be pending, paid, failed, or refunded. |
| Amount is not a whole number of cents, or is above 10000000 | 400 | amount_cents must be a whole number of cents. |
| Paid, pending, or refunded under 50 cents | 400 | A paid, pending, or refunded row must be at least 50 cents. |
Bad backout_ref | 400 | backout_ref must be 8 to 64 letters, numbers, _ or -. |
| Currency is not usd | 400 | Currency is usd. |
| No structure saved, and none was sent | 400 | Save a Backout structure on this app before recording a payment. |
structure_id is not one saved on this app | 400 | That structure is not saved on this app. |
