Skip to content
TrapGod
Sign in Create profile

TrapGod / Documentation / Create a payment

Create a payment

POST once or monthly. TrapGod uses the Backout key and structure saved on the app and returns a pay link.

Create a payment

This call opens a Backout checkout for one app. TrapGod loads the Backout key saved on that app and sends it to Backout. The caller sends the TrapGod application id and the TrapGod API key. Do not send the Backout key. The response does not include it.

frequency is once or monthly. structure_public_id is STRUCTURE_PUBLIC_ID from the Backout env packet. portal_public_id is PORTAL_PUBLIC_ID from that same packet. The structure must already be saved on the TrapGod app. Leave both ids off to use the default structure saved on the app.

The card is charged on Backout when the payer opens hosted_pay_url. TrapGod writes a pending ledger row with backout_ref set to transaction_id. When Backout later marks the charge paid, failed, or refunded, post the ledger again with that same transaction_id.

Request

POST https://trapgod.net/api/link_app_checkout.php
X-Trapgod-Application: tgaid_0123456789abcdef01234567
X-Trapgod-Key: TRAPGOD_KEY
Content-Type: application/json

{
  "description": "Membership",
  "amount_cents": 500,
  "currency": "usd",
  "frequency": "monthly",
  "structure_public_id": "0123456789abcdef0123456789abcdef",
  "portal_public_id": "abcdef0123456789abcdef0123456789",
  "handle": "name_on_this_app",
  "username": "theirtrapgodname"
}

frequency once is a single charge. monthly is a monthly Backout checkout. Leave structure_public_id and portal_public_id off to use the default structure saved on the app.

FieldRequiredRule
descriptionyesWhat the payer is paying for. Up to 140 characters.
amount_centsyesWhole cents, 50 through 10000000. A string of digits is accepted.
currencynousd only. Omitted means usd.
frequencynoonce or monthly. Omitted means once.
handlenoLetters, numbers, _, or -, up to 40 characters.
usernamenoIf that TrapGod user exists, the ledger row stores their numeric id.
structure_public_idno32 hex. STRUCTURE_PUBLIC_ID from the Backout env packet. structure_id is the same field. Must already be saved on the app.
portal_public_idno32 hex. PORTAL_PUBLIC_ID from the Backout env packet. portal_id is the same field.
success_urlnohttps link, up to 300 characters. Sent to Backout when present.
cancel_urlnoSame rule as success_url.
idempotency_keyno8 to 64 letters, numbers, _, or -. The same key returns the same Backout checkout.

Body max is 4096 bytes. Both the application id and the TrapGod key are required, the same way as the badge and ledger calls.

Success

HTTP 200.

{"ok":true,"hosted_pay_url":"https://payment.backout.net/pay/example","transaction_id":"abc123def456abc123def456abc123de","structure_id":"0123456789abcdef0123456789abcdef","frequency":"monthly","amount_cents":500,"ledger_id":123,"trace_id":"TRACE_ID"}

hosted_pay_url is on payment.backout.net or backout.net. Send the payer there. ledger_id is present when the pending row was saved. Staff see that row on /admin/apps/ledger/?id=APP_ID with status pending.

Errors

ConditionHTTPerror
Not POST405POST only.
Body is not JSON400Send JSON.
Body larger than 4096 bytes413That body is too large.
No application id, or no TrapGod key401That key was rejected.
No Backout key or no default structure saved400Save a Backout key and a default structure on this app before creating a payment.
structure_id is not saved on this app400That structure is not saved on this app.
Amount under 50 cents400amount_cents must be a whole number of cents, at least 50.
frequency is not once or monthly400frequency must be once or monthly.
portal_id is not 32 hex400portal_id must be 32 hex characters.
Backout rejects the saved key502The Backout key saved on this app was rejected.
The structure cannot open a checkout409That structure is not ready for checkout on Backout.
Backout does not return a pay link502Backout did not create the payment.

A failed create does not write a ledger row. The error body does not include the Backout key.

Payment ledger