Integration quick start (Placeholder)

A step-by-step quick start to help you make your first authenticated request, validate connectivity, set up webhooks, and understand the key error patterns before you begin full integration work.

Goal: Make your first authenticated request and confirm your integration setup end to end.

What you’ll need

Your API base URL (example: https://api.example.precium.com)
Your Client ID and Client Secret (or API key, depending on your setup)
A place to receive webhooks (optional for first call, required for most live flows)

‍

1) Get access credentials

Precium will provide your credentials via the onboarding process. Store them securely (do not commit to GitHub or share in tickets).

Environment checklist

Sandbox credentials for testing
Production credentials for going live
Separate webhook endpoints per environment

‍

2) Create an access token

Use your credentials to request an access token.

‍

curl -X POST "{BASE_URL}/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "{CLIENT_ID}",
    "client_secret": "{CLIENT_SECRET}",
    "grant_type": "client_credentials"
  }'

‍

Example response

{
  "access_token": "{ACCESS_TOKEN}",
  "token_type": "Bearer",
  "expires_in": 3600
}

‍

3) Make your first API call

Use the token to call a simple endpoint to confirm connectivity.

curl -X GET "{BASE_URL}/v1/health" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Accept: application/json"

‍

What success looks like

You receive a 200 OK
The response indicates the service is available (for example: status = ok)

‍

4) Confirm request signing (if required)

Some implementations require request signing in addition to bearer auth.

If your integration requires signing:

Include the required signature headers (for example: X-Signature, X-Timestamp
Sign the raw request body using the shared secret agreed during onboarding

Replace this section with the actual signing requirements for your API once confirmed.

‍

5) Set up webhooks (recommended early)

Even if your first call succeeds, most integrations rely on webhooks for status updates and event handling.

Minimum recommended events

Payment or transaction status updates
Refund events
Error or failure events

Webhook security

Validate signatures on incoming webhook requests
Reject unsigned or invalid requests
Log webhook payloads in non-production for debugging

‍

6) Handle errors safely

Your integration should:

Retry transient failures (timeouts, 429, 5xx) with backoff
Fail fast on auth errors (401, 403)
Log a correlation ID if returned in headers (example: X-Request-Id)

Quick mapping

400 invalid request (check payload)
401 missing/expired token
403 permissions
404 incorrect endpoint or resource not found
429 rate limited
5xx upstream error (retry with backoff)

‍

7) Test your integration

Before going live, confirm:

Auth works end to end
Your system handles success and failure states
Webhooks are received and processed correctly
Timeouts and retries behave as expected

‍

Common pitfalls

Using production credentials in sandbox (or vice versa)
Token expiry not handled (no refresh or re-auth)
Webhook endpoint not publicly reachable
No signature validation on webhooks
Missing idempotency protection on retries

‍

‍

Next steps

Read: Technical reference documentation (endpoints and schemas)
Read: Integration guide (recommended flows and implementation details)
Set up: Testing and Going live checklist

Table of contents