Getting started

Welcome to the Tilt partner integration docs. Tilt is a payment infrastructure platform. As an integration partner you can:

• Process payments — create orders and accept card payments on behalf of your users
• Receive status notifications — register webhook endpoints and receive real-time payment.* events
• Embed the hosted payment form — redirect customers to a Tilt-hosted card capture page (no PCI scope on your side)
• Deep-link into the Tilt POS — launch a pre-authenticated POS session from your application
• Pull inventory from your DMS — let Tilt pull vehicle data directly from your DMS API

Authentication

OAuth 2.0 client_credentials flow — mint tokens, manage scopes, rotate secrets.

API reference

Orders, Payments, Refunds, Locations — full request/response schemas.

Webhooks

Register endpoints and receive payment.* events with HMAC signature verification.

Sandbox

Test cards and sandbox environment — run end-to-end flows without real money.

Quick start

1. Get invited to the admin portal

   Your Tilt account manager will create a partner record and send you an invitation to admin.dev.apps.myfinterra.com. Accept the invite and sign in as partner_admin.

2. Provision an API client

   In the admin portal, open your partner page and click the Integrations tab. Under API clients, click New client.

   • Give it a name (e.g. my-app-production)
   • Select scopes: payments:create, payments:read, locations:read are the minimum for charging
   • Click Create — the client_secret is shown once; copy it now

   client_id:     abc123…
   client_secret: s3cr3t…   ← copy this now; it will not be shown again

3. Exchange credentials for an access token

   curl -s -X POST \
     https://tilt-m2m-dev.auth.us-east-1.amazoncognito.com/oauth2/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=abc123…" \
     -d "client_secret=s3cr3t…" \
     -d "scope=tilt/payments:create tilt/payments:read tilt/locations:read"

   Response:

   {
     "access_token": "eyJraWQi…",
     "expires_in": 3600,
     "token_type": "Bearer"
   }

   Tokens are valid for 1 hour. Cache them; re-mint when they expire.

4. Create an order and charge

   curl -s -X POST \
     https://pos-api.dev.apps.myfinterra.com/pos/v1/orders \
     -H "Authorization: Bearer eyJraWQi…" \
     -H "Content-Type: application/json" \
     -d '{
       "location_id": "<your-location-uuid>",
       "total_cents": 5000,
       "description": "Fleet service — invoice #INV-001",
       "external_reference": "INV-001",
       "customer_name": "Alice Example",
       "customer_email": "alice@example.com"
     }'

   Response includes order_id. Use that to initiate a payment.

5. View the charge in the admin portal

   Open admin.dev.apps.myfinterra.com, navigate to your partner → Transactions. The charge appears immediately.

Tip

The Postman collection at /pos/v1/.well-known/openapi.json can be imported directly into Postman via File → Import → Link. The collection includes pre-request scripts that auto-refresh the access token.

Base URLs

Environment	API base	Admin portal	Docs
dev	https://pos-api.dev.apps.myfinterra.com	https://admin.dev.apps.myfinterra.com	https://docs.dev.apps.myfinterra.com
prod	https://pos-api.apps.myfinterra.com	https://admin.apps.myfinterra.com	https://docs.apps.myfinterra.com

Machine-readable specs

The live API exposes its own OpenAPI and AsyncAPI specs at stable URLs:

GET /pos/v1/.well-known/openapi.json    # OpenAPI 3.1
GET /pos/v1/.well-known/asyncapi.json   # AsyncAPI 2.6 (webhook events)

These are unauthenticated. Import them into Postman, Stoplight, or any OpenAPI-compatible code generator.