SDKs & code samples

There is no official SDK yet — the API is plain JSON over HTTPS and works with any HTTP client. Below is the same flow — log in, read a list, create a record — in the languages integrations most commonly use. Switch tabs to see each one; the calls are identical apart from syntax.

1. Log in for a token

Exchange credentials for an access token. In every non-shell sample the token is read from data.accessToken in the response envelope.

curl -X POST https://gulfpay-production.up.railway.app/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@company.com", "password": "your-password" }'

2. Read a list

Send the token as a bearer credential and select the company with X-Company-Id. List endpoints accept pagination and filter query parameters.

curl https://gulfpay-production.up.railway.app/api/v1/customers?limit=20 \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Company-Id: cmp_123"

3. Create a record (idempotently)

Attach a unique Idempotency-Key to any write so a retry after a dropped connection never creates a duplicate — see idempotent requests.

curl -X POST https://gulfpay-production.up.railway.app/api/v1/customers \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Company-Id: cmp_123" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0b2b1e-8a1c-4c2b-9f3a-0d1e2f3a4b5c" \
  -d '{ "name": "Acme Trading LLC", "email": "ap@acme.example" }'