Authentication

Basic Auth mechanism

Construct the Authorization header by base64-encoding your Shop ID and API token, separated by a colon:

Authorization: Basic base64(YOUR_SHOP_ID:YOUR_API_TOKEN)

Your Shop ID is the numeric shop identifier used as your API username. Your API token is the password provided by your account manager.

curl

curl -X POST https://api.payretailers.com/data-api/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'YOUR_SHOP_ID:YOUR_API_TOKEN' | base64)" \
  -d '{"query": "{ ping }"}'

Python

import requests
from requests.auth import HTTPBasicAuth

response = requests.post(
    "https://api.payretailers.com/data-api/graphql",
    json={"query": "{ ping }"},
    auth=HTTPBasicAuth("YOUR_SHOP_ID", "YOUR_API_TOKEN"),
    headers={"Content-Type": "application/json"},
)

print(response.json())
# {"data": {"ping": "pong"}}

TypeScript

import axios from "axios";

const credentials = Buffer.from("YOUR_SHOP_ID:YOUR_API_TOKEN").toString("base64");

const response = await axios.post(
  "https://api.payretailers.com/data-api/graphql",
  { query: "{ ping }" },
  {
    headers: {
      "Content-Type": "application/json",
      Authorization: `Basic ${credentials}`,
    },
  }
);

console.log(response.data);
// {"data": {"ping": "pong"}}

Credential validation

The API validates your credentials on every request. There is no session, token refresh, or token caching. Each request is stateless.

When credentials are valid, the API resolves your Shop ID to a merchant account. All queries are then automatically scoped to your merchant data. You cannot query another merchant's data.

PII access with X-Pii-Access

Some fields contain personally identifiable information (PII), such as customer email, phone number, and personal ID. By default, these fields are returned in masked form.

To access unmasked PII fields, include the X-Pii-Access header set to true:

curl -X POST https://api.payretailers.com/data-api/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'YOUR_SHOP_ID:YOUR_API_TOKEN' | base64)" \
  -H "X-Pii-Access: true" \
  -d '{"query": "{ payins(first: 1, filter: { createdDateFrom: \"2026-01-01\", createdDateTo: \"2026-01-31\" }) { edges { node { transactionId customerEmail customerPhone } } } }"}'

Note: Your account must be authorized for PII access. Contact your account manager if you need access to unmasked PII data.

Correlation ID

You can include an X-Correlation-ID header to trace requests through the system. If omitted, the API generates one automatically.

The correlation ID is returned in:

• The X-Correlation-ID response header
• The correlationId field in any error extensions

Use this value when contacting support about a specific request.

curl -X POST https://api.payretailers.com/data-api/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'YOUR_SHOP_ID:YOUR_API_TOKEN' | base64)" \
  -H "X-Correlation-ID: my-custom-trace-id-001" \
  -d '{"query": "{ ping }"}'

Token lifecycle

• Credentials are validated on every request. There is no token to manage or refresh.
• If your API token is rotated, the old token stops working immediately.
• Contact your account manager to rotate or revoke API tokens.

Security best practices

1. Never expose credentials in client-side code. Make API calls from your backend server only.
2. Use HTTPS for all requests. The API enforces TLS encryption.
3. Store credentials securely. Use environment variables or a secrets manager. Never hard-code credentials in source code.
4. Rotate tokens periodically. Contact your account manager to request a token rotation.
5. Use the minimum PII access needed. Only send X-Pii-Access: true when your use case requires unmasked personal data.
6. Monitor for unauthorized access. If you receive unexpected UNAUTHORIZED errors, your credentials may have been compromised. Rotate them immediately.

Common authentication errors

The UNAUTHORIZED error returns HTTP 401 with a JSON body:

{
  "error": "Unauthorized",
  "message": "Valid Basic Auth credentials required."
}

All other errors use the standard GraphQL error envelope (HTTP 200). See Error Handling for details.