# 03. API & Integration Reference
## 1. Authentication
All API requests must be authenticated using a custom header and IP whitelisting.
- **Header**: `X-Customer-Token` (The unique token assigned to each ERP/Customer).
- **IP Whitelisting**: The request must originate from an IP address registered in the `incoming_host_validation` table for that specific customer.
- **Response Signing**: All successful responses include an `X-PB-Signature` header, which is an HMAC-SHA256 hash of the response body using the customer's token as the secret.
---
## 2. API Endpoints (v1)
### A. Create Payment Intent
Used by the ERP to initiate the payment process.
- **Endpoint**: `POST /api/v1/create-payment-intent`
- **Request Body**:
```json
{
"erp_reference_id": "STU12345",
"erp_module": "Admission",
"amount": 5000.00,
"currency": "INR",
"event": "ADMISSION_2024",
"return_url": "https://erp.institution.edu/payment/callback",
"notify_url": "https://erp.institution.edu/api/payment/webhook"
}
```
- **Success Response**: Returns a `token` and a `redirect_url` for the user.
### B. Get Payment Status
Retrieves the current status of a payment and triggers a gateway sync if necessary.
- **Endpoint**: `GET /api/v1/payment/status`
- **Query Params**: `erp_reference_id`
- **Logic**: If the transaction is still `INITIATED` or `PENDING`, the system performs a real-time inquiry with the Payment Gateway (Razorpay/CCAvenue) to fetch the latest status.
### C. Webhook Receiver
Receives asynchronous updates from Payment Gateways.
- **Endpoint**: `POST /api/v1/webhooks/{gateway}`
- **Note**: Handled via a background job (`ProcessWebhookJob`) to ensure rapid response to the gateway (PG).
---
## 3. Third-Party Integrations
### Razorpay Integration
- **SDK**: `razorpay/razorpay`
- **Flow**: Server-side Order creation -> Client-side Checkout -> Webhook verification.
- **Features**: Supports automatic signature verification for callbacks and webhooks.
### CCAvenue Integration
- **Flow**: Request encryption -> Redirect -> Response decryption.
- **Driver**: Custom-built PHP driver handling encryption/decryption using the vendor-provided `working_key` and `access_code`.
---
## 4. ERP Notification (Webhook)
When a payment reaches a final state (`SUCCESS` or `FAILED`), the system sends a POST request to the ERP's `notify_url`.
- **Payload**:
```json
{
"intent_id": "uuid-here",
"event": "ADMISSION_2024",
"erp_reference_id": "STU12345",
"amount": 5000.00,
"status": "SUCCESS",
"gateway_transaction_id": "pay_xyz123"
}
```
- **Security**: Includes `X-PB-Signature` for the ERP to verify the message integrity.