External API - Integration Guide

What is the External API

The Avirato Payments External API lets external integrators (ERPs, e-commerce platforms, management systems, etc.) process online payments and POS payments securely, without needing to know the system's internal infrastructure.

With a single integration you can:

• Create online payment sessions and redirect the customer to a secure payment page
• Process POS payments by sending a charge directly to a physical terminal
• Modify payments: full and partial refunds, pre-authorization captures, cancellations, and pre-authorization extensions
• Query payments: get session details, list sessions with filters and pagination, list modifications

Environments: Live and Test

The External API offers two completely independent environments:

Recommendation: Integrate first in the Test environment to verify that your system works correctly. Once validated, switch to Live by simply using your production API key and removing /test/ from the URLs.

Base URL

Live: https://aviratopayments.com/external/v1/
Test: https://aviratopayments.com/external/v1/test/

All endpoints in this documentation show the full Live environment URL. To use the Test environment, insert /test/ after /v1/. For example:

• Live: POST https://aviratopayments.com/external/v1/payment/session
• Test: POST https://aviratopayments.com/external/v1/test/payment/session

Quick authentication

All requests require an API key in the X-API-KEY header:

X-API-KEY: your_api_key_here

API keys are managed from the Avirato Payments dashboard (Integrations > API Keys section). Each key is linked to a webcode (business identifier) and an environment (Live or Test).

In addition, all POST requests optionally accept the Idempotency-Key header to avoid duplicate operations. We recommend always using it in production. Reusing the same key with a different body or another endpoint returns 409 Conflict (see Authentication and Error handling).

For more detail: Authentication

Response structure

Successful response

All successful responses follow this structure:

{
  "success": true,
  "data": { ... }
}

The content of data varies by endpoint. The success field is always true on 2xx responses.

Error response

{
  "success": false,
  "error": {
    "message": "Error description in English",
    "code": 12001,
    "statusCode": 400,
    "traceId": "abc123..."
  }
}

The traceId is unique per request. Always include it when contacting technical support. See Error handling for the full catalog.

Key concepts before you start

Session vs Payment (for online payments)

It is essential to understand this distinction:

• Session (sessionId): The payment intent your system creates. It contains the amount, return URLs, etc.
• Payment (paymentReference): The real transaction authorized by the processor. It only exists when the customer completes the payment successfully.

Practical rule: Use sessionId to query status. Use paymentReference to modify (refund, capture, cancel, extend).

See Online Payments - Session vs Payment for the full explanation.

Asynchronous operations

Modifications (refund, capture, cancel, extend) are asynchronous. The API accepts the request immediately (HTTP 202) but the operation is processed in the background. The initial status is pending (refunds) or received (capture, cancel, extend) and evolves to success or failed as the processor confirms.

POS payments are synchronous: the request waits until the terminal responds.

In the Test environment: Modifications resolve almost immediately (the backend simulates the processor response). You will receive the confirmation webhook within seconds.

Typical integration flow

1. Online payment

Your system                      Avirato Payments                  Customer
    |                                    |                              |
    |-- POST /payment/session ---------->|                              |
    |<-- 201 { sessionId, paymentUrl } --|                              |
    |                                    |                              |
    |-- Redirect customer -------------->+---------------------------->|
    |                                    |     (secure payment page)    |
    |                                    |<-- Completes payment --------|
    |                                    |                              |
    |                                    |-- Redirect to urlOk -------->|
    |                                    |   (with encrypted data)      |
    |                                    |                              |
    |-- GET /payment/session/{id} ------>|                              |
    |<-- { status: completed,            |                              |
    |      paymentReference: "..." } ----|                              |
    |                                    |                              |
    |   (You can now refund,             |                              |
    |    capture, etc. with paymentRef)  |                              |

2. POS payment

Your system                      Avirato Payments         POS Terminal
    |                                    |                      |
    |-- POST /pos/payment ------------->|                      |
    |                                    |-- Send charge ----->|
    |                                    |    (customer pays    |
    |                                    |     at terminal)     |
    |                                    |<-- Result -----------|
    |<-- 200 { status: success,          |                      |
    |          paymentReference } --------|                      |

Note: These flows work identically in the Test environment, replacing /external/v1/ with /external/v1/test/. The only difference is that in Test the online payment is completed with fictitious cards and the POS payment is simulated with magic amounts (no real terminal).

Key differences between Test and Live

Endpoint index

Online Payments

Modifications (apply to online and POS payments)

POS Payments

Remember: To use any endpoint in the Test environment, add /test/ after /v1/. Example: POST /external/v1/test/payment/session.

Next steps

1. Set up authentication
2. Create your first online payment
3. Or start with POS payments
4. Learn how to modify payments
5. Query payments and modifications
6. Receive notifications via webhooks
7. Error handling
8. Complete end-to-end examples