API conventions

These rules apply to every Foundation API endpoint, unless a page says otherwise.

Errors

Error bodies do not all have the same shape. Check the status code first. Then read the body.

Status	Meaning	What to do
`401`	The access token is missing, expired or not valid.	Refresh the token. If the refresh fails, ask the user to authorize your app again.
`403`	The token does not have a required scope, or the company cannot do this action.	Check Scopes. Read `message`.
`404`	The object was not found.	Check the `uid`, and check that the token acts for the right company.
`422`	The request is not valid. One field is wrong, or the request as a whole is wrong.	Fix the request. Do not send it again unchanged.
`429`	Too many requests.	Wait for the number of seconds in `Retry-After`. See Rate Limiting.

The five body shapes seen on a running server:

401

{ "detail": "…", "error_code": "…" }

403

{ "code": "…", "message": "…", "error_code": "…" }

404 (no error_code)

{ "detail": "…" }

422, one field is wrong: each key is a field name

{ "wallet_uid": ["…"] }

422, the request as a whole is wrong

{ "non_field_errors": ["…"] }

Pagination

List endpoints use limit and offset.

limit is the page size. The default is 25. The maximum is 100: limit=1000 returns 100 items.
A limit that is not valid falls back to 25, with no error.
offset is the number of items to skip.
The order of items in a list is not guaranteed. Do not rely on it. Sort on your side if you need an order.

curl "https://api.foundation.sandbox.trusspayments.com/v1/payment-intents/inbound/?limit=100&offset=100" \
  --header "Authorization: Bearer ${TRUSS_ACCESS_TOKEN}"

Corex uses a different method. See Corex.

Money

All amounts are in US dollars. The two APIs write them differently:

API	Format	Example
Foundation	Decimal string	`"total": "100.00"`
Corex	JSON number	`"minimumPaymentAmount": 25.0`

Send Foundation amounts as strings too. Read Corex amounts with a decimal type, not a float, to keep cents exact.

Retries and duplicates

The API has no idempotency key. If you send the same POST twice, Truss creates two objects. For example, a retried create made a second invoice.

If a create request times out, list the objects and look for the new one before you send the request again.

Correlation IDs

Payment Intents