Authentication

API Keys

All External API requests require a valid API key in the X-API-KEY HTTP header.

Required headers

Example

curl -X POST https://aviratopayments.com/external/v1/payment/session \
  -H "X-API-KEY: your_live_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ ... }'

Environments

The External API has two independent environments: Live and Test. Each environment has its own API keys, its own client secret, and its own data (completely isolated from each other).

Live API Keys

Live API keys process real payments against the processor. Only use Live keys when your integration is fully validated.

Test API Keys

Test API keys let you test the entire integration without moving real money. Payments are simulated, webhooks are generated automatically, and data is stored in complete isolation.

Recommended integration flow: Always start with a Test API key. Develop and validate your entire integration. When everything works correctly, create a Live API key and change the URLs (add or remove /test/).

IP restriction

API keys can have IP restrictions configured from the dashboard. If your IP is not on the allowed list, you will receive a 403 Forbidden error.

Recommendation: Configure IP restrictions in production for greater security. In the Test environment, you can leave IPs unrestricted to simplify development.

Webcode restriction

Each API key is linked to a specific webcode (your business identifier in Avirato Payments). You can only operate with the webcode associated with your key.

The webcode field is required on all requests and must match your API key's webcode.

Scopes

API keys have a scope that determines which endpoints they can access:

A Live key cannot access Test routes, and vice versa.

Idempotency

Write endpoints (create session, modifications, POS payment) support the Idempotency-Key header. If you send the same Idempotency-Key with the same parameters:

1. The first request is processed normally
2. Subsequent requests with the same key return the same response without executing the operation again

Idempotency works identically in both environments (Live and Test). Idempotency records for each environment are isolated from each other.

Idempotency conflicts (409)

If you reuse an Idempotency-Key incorrectly, the API responds with 409 Conflict to avoid inconsistent behavior:

Recommendation: always use Idempotency-Key in production to avoid duplicate charges, but associate a unique key per logical attempt (for example, derived from orderId + retry). If you need to change the body, use a new key.

# First call: creates the payment
curl -X POST .../payment/session \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{ "webcode": "SHOP01", "amount": { "value": 10000, "currency": "EUR" }, ... }'

# Second call with the same key and same body: returns the same response without creating another payment
curl -X POST .../payment/session \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{ "webcode": "SHOP01", "amount": { "value": 10000, "currency": "EUR" }, ... }'

# Third call with the same key but different body: 409 Conflict
curl -X POST .../payment/session \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{ "webcode": "SHOP01", "amount": { "value": 99999, "currency": "EUR" }, ... }'

Client Secret

Each environment has its own client secret. The client secret is used to decrypt encrypted data in the post-payment redirect (the data parameter on urlOk).

• Live client secret: generated when you create the first Live API key.
• Test client secret: generated when you create the first Test API key.

The client secret is only shown once when you create the first key for the environment. If you lose it, you can rotate it from the dashboard (Integrations > API Keys > Rotate Secret).

Important: Live and Test client secrets are different. Make sure you use the correct secret to decrypt redirect data in each environment.

API Key management

API keys are managed from the Avirato Payments Dashboard (Integrations > API Keys section):