Skip to content
TrapGod
Sign in Create profile

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.

FieldRequiredRule
amount_centsyesWhole cents, 0 through 10000000. A string of digits is accepted.
statusyespending, paid, failed, or refunded.
backout_refyes8 to 64 characters: letters, numbers, _, or -. This is the idempotency key.
currencynousd only. Omitted means usd.
handlenoLetters, numbers, _, or -, up to 40 characters. The badge handle does not allow a hyphen. This field does.
usernamenoIf that TrapGod user exists, the row stores their numeric id as actor_id. A missing user does not fail the post.
structure_idnoMust 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

  1. Save id and trace_id from the response on the partner server, next to the Backout id.
  2. Open /admin/apps/ledger/?id=APP_ID. Staff, a sub admin, and a super admin can read it.
  3. Each row shows Eastern time, handle, structure label and id, amount, status, backout_ref, actor id, and trace id.
  4. The page lists the latest 100 rows for that app. Older rows stay in link_app_pay_ledger.
  5. Actor 0 is shown as -. That means the post did not name a TrapGod user that exists.
  6. Usage traces for the post use action link_app.pay_record or link_app.pay_deny, role partner, and the same trace_id.

The ledger page does not show the Backout key or the TrapGod API key.

Errors

ConditionHTTPerror
Not POST405POST only.
Body is not JSON400Send JSON.
Body larger than 4096 bytes413That body is too large.
No application id, or no key401That key was rejected.
Application id and key are not the same active app401That key was rejected.
Header and body application ids differ401That key was rejected.
Bad status400Status must be pending, paid, failed, or refunded.
Amount is not a whole number of cents, or is above 10000000400amount_cents must be a whole number of cents.
Paid, pending, or refunded under 50 cents400A paid, pending, or refunded row must be at least 50 cents.
Bad backout_ref400backout_ref must be 8 to 64 letters, numbers, _ or -.
Currency is not usd400Currency is usd.
No structure saved, and none was sent400Save a Backout structure on this app before recording a payment.
structure_id is not one saved on this app400That structure is not saved on this app.

Create a payment