REST API Reference — Documentation Aventopay

Exhaustive documentation of Aventopay REST endpoints: session creation, status, transactions, webhooks.

Production base URL: https://avento-pay.com/api. All requests use HTTPS and JSON.

Authentication

Three elements make up the authentication of an outgoing request to the Aventopay API:

Header Authorization: Bearer <api_key> — identifies your account
Header X-Aventopay-Signature — HMAC-SHA256 of the raw body, signed with api_secret
Field merchant_id in the body — cross-checked with api_key

Endpoints

POST/payment/sessionCreate a payment session

GET/payment/session/:tokenRetrieve a session status

POST/payment/confirmConfirm a session (called by the payment page)

POST /payment/session

Creates a session and returns the payment URL + iframe.

Field	Type	Required	Description
`merchant_id`	string	✓	Your merchant identifier
`user_id`	string	✓	Your internal customer ID
`amount`	integer	✓	Amount in cents
`currency`	string	optional	ISO 4217 currency, default `EUR`
`transaction_id`	string	optional	Your transaction ID (idempotency)
`customer`	object	optional	`{email, name}` — pre-fills the form
`return_url`	string	optional	Redirect after payment
`callback_url`	string	optional	Webhook endpoint for this session
`metadata`	object	optional	Free fields returned in the webhook

Response 200

{
  "session_token": "sess_...",
  "payment_url": "https://avento-pay.com/pay/sess_...",
  "iframe_url": "https://avento-pay.com/iframe-host/index.html?session=sess_...",
  "expires_at": "2026-07-22T14:53:11Z",
  "signature": "<hmac of response body, signed with webhook_secret>"
}

GET /payment/session/:token

Returns the current status of a session.

{
  "session_token": "sess_...",
  "status": "success" | "pending" | "cancelled",
  "amount": 5000,
  "currency": "EUR",
  "provider_reference": "apy_ref_a1b2c3d4e5f6"
}

Rate limits

Resource	Limit
Session creation	60 requests / minute / merchant
Session consultation	600 requests / minute / merchant
IP anti-fraud	Dynamic limit — `429` return with `retry_after_minutes`

Error codes

All errors follow the {error, message} structure. Full details: error catalog.

Resources

Quickstart 15 minutes
Webhooks — signature, retry, idempotency
OpenAPI 3 specification: /docs/openapi.yaml (coming soon)