Quickstart: your first invoice in sandbox

New to Truss? Read the Introduction first. It explains the words used on this page.

This quickstart uses the Foundation API. For the Corex API, start with the Corex integration guide.

This quickstart uses the sandbox environment. Sandbox is for testing. Its app host is named staging: app.staging.trusspayments.com.

The quickstart has two parts. You do the setup once. Then you make your first API call.

One-time setup

1. Request access

Ask Truss for sandbox access.

2. Get credentials and register your `redirect_uri`

Truss gives you a client_id and a client_secret for sandbox. Tell Truss the URL in your app that receives users after they approve access. This URL is your redirect_uri. Truss must register it before you can use it.

You now have:

export TRUSS_CLIENT_ID='your-client-id'
export TRUSS_CLIENT_SECRET='your-client-secret'
export TRUSS_REDIRECT_URI='https://partner.example.com/oauth/callback'

Keep client_secret on your server only.

3. Onboard a test company

Open https://app.staging.trusspayments.com, sign up and complete the onboarding application. See Sandbox Test Account for each screen.

4. Set up the Payment Portal

In the Truss app, set up the test company's Payment Portal link. Do this before step 8. Until the portal is set up, checkout_link_id is null and invoice create fails with 422. See Partner Payment Portal.

Your first API call

Each step hands one value to the next: the code becomes a token, and the token opens every API call.

5. Authorize your app

Send the user's browser to this URL. The user signs in as the test company and approves your app.

https://app.staging.trusspayments.com/oauth/authorize
  ?client_id=your-client-id
  &redirect_uri=https://partner.example.com/oauth/callback
  &response_type=code
  &scope=company:read+payment_intent.inbound:read+payment_intent.inbound:write+transactions:read+offline_access
  &state=8f3a1c9e5b7d4f20a6c1e9b3d5f7a2c4

Expected result:

https://partner.example.com/oauth/callback?code=AUTH_CODE&state=8f3a1c9e5b7d4f20a6c1e9b3d5f7a2c4

Check that state is the value you sent. Then copy code.

In your app, generate a new random state for each authorization, store it with the user's session, and reject the callback if the returned value does not match.

6. Exchange the code for tokens

Send this request from your server.

curl --request POST "https://auth.foundation.sandbox.trusspayments.com/v1/oauth2/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=AUTH_CODE" \
  --data-urlencode "redirect_uri=${TRUSS_REDIRECT_URI}" \
  --data-urlencode "client_id=${TRUSS_CLIENT_ID}" \
  --data-urlencode "client_secret=${TRUSS_CLIENT_SECRET}"

Expected JSON (values shortened):

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "Xq3vJ8...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "company:read payment_intent.inbound:read payment_intent.inbound:write transactions:read offline_access"
}

Save access_token as TRUSS_ACCESS_TOKEN. It expires after 60 minutes.

7. Call `GET /v1/company/`

curl "https://api.foundation.sandbox.trusspayments.com/v1/company/" \
  --header "Authorization: Bearer ${TRUSS_ACCESS_TOKEN}"

Expected JSON:

{
  "uid": "7c1f2d3e-8a9b-4c5d-9e0f-1a2b3c4d5e6f",
  "name": "Sample Test Co",
  "checkout_link_id": "a1b2c3d4"
}

The response is one object: the company that your token acts for. If checkout_link_id is null, go back to step 4.

8. Create an invoice

curl --request POST "https://api.foundation.sandbox.trusspayments.com/v1/payment-intents/inbound/" \
  --header "Authorization: Bearer ${TRUSS_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "total": "100.00",
    "addenda": "Invoice INV-1001",
    "contact": { "name": "Alex Customer", "email": "alex@example.com" }
  }'

Expected JSON (shortened):

{
  "uid": "3dba9d05-bb20-423e-924e-4b19e50d6f3c",
  "direction": 0,
  "status": "Pending",
  "total": "100.00",
  "balance_paid": "0.00",
  "addenda": "Invoice INV-1001",
  "checkout_url": null,
  "transactions": []
}

Store uid. Next, send the customer to the Payment Portal to pay. See Partner Payment Portal.

Introduction

Overview