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.
| Field | Required | Rule |
|---|---|---|
description | yes | What the payer is paying for. Up to 140 characters. |
amount_cents | yes | Whole cents, 50 through 10000000. A string of digits is accepted. |
currency | no | usd only. Omitted means usd. |
frequency | no | once or monthly. Omitted means once. |
handle | no | Letters, numbers, _, or -, up to 40 characters. |
username | no | If that TrapGod user exists, the ledger row stores their numeric id. |
structure_public_id | no | 32 hex. STRUCTURE_PUBLIC_ID from the Backout env packet. structure_id is the same field. Must already be saved on the app. |
portal_public_id | no | 32 hex. PORTAL_PUBLIC_ID from the Backout env packet. portal_id is the same field. |
success_url | no | https link, up to 300 characters. Sent to Backout when present. |
cancel_url | no | Same rule as success_url. |
idempotency_key | no | 8 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
| 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 TrapGod key | 401 | That key was rejected. |
| No Backout key or no default structure saved | 400 | Save a Backout key and a default structure on this app before creating a payment. |
structure_id is not saved on this app | 400 | That structure is not saved on this app. |
| Amount under 50 cents | 400 | amount_cents must be a whole number of cents, at least 50. |
frequency is not once or monthly | 400 | frequency must be once or monthly. |
portal_id is not 32 hex | 400 | portal_id must be 32 hex characters. |
| Backout rejects the saved key | 502 | The Backout key saved on this app was rejected. |
| The structure cannot open a checkout | 409 | That structure is not ready for checkout on Backout. |
| Backout does not return a pay link | 502 | Backout did not create the payment. |
A failed create does not write a ledger row. The error body does not include the Backout key.
