Quickstart — first payment in 15 minutes

Step-by-step guide to integrate Aventopay and process your first payment in test mode.

What you'll do

Create an account, get your credentials, create a payment session, pay it with a test card, receive a webhook, verify the signature. In 15 minutes.

1. Create your account

Go to avento-pay.com/auth/signin to create your account. Your test API keys are available immediately — regulatory verification is only required before going to production.

2. Get your 4 credentials

From your dashboard, section Settings → API Keys, note:

merchant_id — your merchant identifier
api_key — for the Authorization header
api_secret — to sign your requests (HMAC)
webhook_secret — to verify our callbacks

3. Create a payment session

From your server, POST to /api/payment/session with signed headers:

import crypto from 'crypto';

const API_KEY = process.env.AVENTOPAY_API_KEY;
const API_SECRET = process.env.AVENTOPAY_API_SECRET;

const body = JSON.stringify({
  merchant_id: 'your_merchant_id',
  user_id: 'client_123',
  amount: 5000,             // 50.00 € in cents
  currency: 'EUR',
  customer: { email: 'client@example.com', name: 'Marie Dupont' },
  return_url: 'https://your-site.com/success',
  callback_url: 'https://your-site.com/webhooks/aventopay',
});

const signature = crypto
  .createHmac('sha256', API_SECRET)
  .update(body, 'utf8')
  .digest('hex');

const res = await fetch('https://avento-pay.com/api/payment/session', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${API_KEY}`,
    'X-Aventopay-Signature': signature,
  },
  body,
});

const { payment_url, iframe_url, session_token } = await res.json();

The response contains payment_url (to open/redirect the customer) and iframe_url (to embed).

4. Make a test payment

Open payment_url in your browser. Use the test card:

Card	Number	Expiration	CVC
Visa	`4242 4242 4242 4242`	Any future date	Three digits
Mastercard	`5555 5555 5555 4444`	Any future date	Three digits
3DS Challenge	`4000 0027 6000 3184`	Any future date	Three digits

5. Receive & verify the webhook

Once the payment is made, Aventopay sends a POST to your callback_url. Verify the signature on the raw body, then process the transaction idempotently.

import express from 'express';
import crypto from 'crypto';

const app = express();
const WEBHOOK_SECRET = process.env.AVENTOPAY_WEBHOOK_SECRET;

// IMPORTANT: express.raw to read the raw (unparsed) body
app.post('/webhooks/aventopay',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const sig = req.headers['x-aventopay-signature'] || '';
    const raw = req.body.toString('utf8');
    const expected = crypto.createHmac('sha256', WEBHOOK_SECRET)
      .update(raw, 'utf8').digest('hex');

    if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
      return res.status(401).send('Invalid signature');
    }

    const payload = JSON.parse(raw);

    // Idempotency: process at most once per reference
    if (await alreadyProcessed(payload.provider_reference)) {
      return res.status(200).send('OK');
    }

    switch (payload.status) {
      case 'success':
        await fulfillOrder(payload.external_user_id, payload.amount);
        break;
      case 'cancelled':
        await markCancelled(payload.transaction_id);
        break;
      case 'pending':
        // another callback will follow
        break;
    }

    res.status(200).send('OK');
  }
);

You're done