AVP API Documentation

Guida completa per integrazione API e uso del portale merchant.

Regione: eu-south-1 Auth: API Key (server) Scarica PDF

Base URL

https://otfxkl5czg.execute-api.eu-south-1.amazonaws.com

Autenticazione

Genera una SERVER KEY dal Merchant Portal e inviala come header x-api-key.

Headers:
  x-api-key: <SERVER_KEY>
  content-type: application/json

Le API del merchant portal usano JWT Cognito (OAuth code flow).

Flusso rapido (verifica)

Genera una SERVER KEY dal Merchant Portal
POST /v1/session per creare una sessione
/v1/liveness/start → /v1/liveness/complete
/v1/age-check per valutazione età
/v1/token/issue per emettere token
/v1/token/verify per verifica token lato merchant

Endpoint principali

POST /v1/session

{
  "client_id": "client_YYYYMMDD_xxxxxx",
  "session_ttl_sec": 600
}

POST /v1/liveness/start

{
  "session_id": "sess_..."
}

POST /v1/liveness/complete

{
  "session_id": "sess_...",
  "face_image_b64": "data:image/jpeg;base64,..."
}

POST /v1/age-check

{
  "session_id": "sess_...",
  "face_image_b64": "data:image/jpeg;base64,..."
}

POST /v1/token/issue

{
  "session_id": "sess_..."
}

POST /v1/token/verify

{
  "token": "eyJhbGciOi..."
}

Ricariche crediti

Due modalità:

Manuale: il merchant crea una Checkout Session con importo minimo 50€.
Auto‑ricarica: il merchant imposta importo e soglia. Quando il saldo scende sotto la soglia, un pagamento off‑session ricarica i crediti.

Gli accrediti vengono registrati nel ledger con type=CREDIT e reason=TOPUP.

Merchant Portal API

POST /v1/merchant/me

Ritorna client, saldo e stato billing. Usa JWT Cognito.

POST /v1/merchant/billing/get

POST /v1/merchant/billing/update

POST /v1/merchant/ledger

POST /v1/merchant/api-keys/list

POST /v1/merchant/api-keys/create

POST /v1/merchant/api-keys/update

POST /v1/merchant/api-keys/delete

POST /v1/merchant/topup/create-checkout

POST /v1/merchant/topup/auto/get

POST /v1/merchant/topup/auto/update

POST /v1/merchant/topup/auto/setup

Errori comuni

401 UNAUTHORIZED
403 NOT_PROVISIONED
403 CLIENT_DISABLED
409 BILLING_REQUIRED
409 ALREADY_CLAIMED
409 KEY_LIMIT

Stripe + EventBridge

Gli accrediti sono basati sugli eventi Stripe. Se usi EventBridge (partner event source), imposta come target la Lambda avp_stripeWebhook. Non serve signature webhook.

Eventi gestiti: checkout.session.completed, payment_intent.succeeded.

Se vuoi usare un webhook HTTP, l’endpoint è:

POST /v1/stripe/webhook