> ## Documentation Index
> Fetch the complete documentation index at: https://beta-developers.mizaniyapay.dz/llms.txt
> Use this file to discover all available pages before exploring further.

# VTPE Integration: Architecture and Component Overview

> VTPE calls your Product Information API for payment details and POSTs webhooks for lifecycle events. Learn the two-component integration model, configuration, and end-to-end flow.

VTPE is a payment orchestration platform that delegates payment information to you and notifies you of payment state changes. As a partner, you build two endpoints so VTPE can retrieve payment details and deliver event notifications. This page explains the architecture, configuration, and flow between your systems and VTPE.

## Integration Components

To integrate with VTPE, you must build and expose two endpoints:

1. **Product Information API** VTPE calls your GET endpoint to retrieve payment details before initiating a payment session. You return the amount, currency, and optional details to present to the customer.
2. **Webhook Endpoint** VTPE POSTs payment lifecycle events to your Webhook URL. You receive events such as `payment.initialized`, `payment.success`, and `payment.fail`, and update your order records accordingly.

## Configuration

You provide VTPE with the following two URLs during setup:

| Field       | Purpose                                         | Example                                 |
| ----------- | ----------------------------------------------- | --------------------------------------- |
| API URL     | Endpoint VTPE calls to retrieve payment details | `https://api.example.com/payments`      |
| Webhook URL | Endpoint that receives payment events           | `https://api.example.com/webhooks/vtpe` |

Both URLs must be publicly accessible over HTTPS. VTPE will append a reference identifier to the API URL when making payment detail requests.

## End-to-End Flow

The following flow describes a full VTPE payment:

1. The customer initiates a payment through a VTPE-powered experience.
2. VTPE calls `GET {API_URL}/{reference}` to retrieve payment details from your system.
3. Your Product Information API returns the total amount, currency, and optional details.
4. VTPE presents the payment experience to the customer using the returned information.
5. The customer completes, fails, or cancels the payment.
6. VTPE sends a `payment.success` or `payment.fail` webhook to your Webhook URL.

<Note>
  If the customer has already paid for a reference, return `409 Conflict` with code `ALREADY_PAID` so VTPE can surface a clear error message.
</Note>

## Authentication Flow

Both API calls from VTPE include authentication headers:

* `Authorization: Bearer YOUR_API_SECRET`
* `X-Timestamp: 1717344000`

Webhook requests also include an HMAC signature for verification:

* `X-Signature: GENERATED_SIGNATURE`

<Tip>
  For details on setting up your API URL, Webhook URL, and authentication credentials, see the [Configuration guide](/guides/configuration).
</Tip>