# UrontoPay Secure Integration Guide for AI Coding Assistants

This file is designed to be given directly to ChatGPT, Claude, Gemini, Copilot, Cursor, or another coding assistant.

## Authoritative resources

- Human documentation: `https://urontopay.com/developers/docs`
- OpenAPI: `https://urontopay.com/openapi.json`
- API base URL: `https://pay1.urontopay.com`

## Security boundary

All UrontoPay API calls must originate from a trusted backend server.

Never put these values in HTML, browser JavaScript, a mobile app, a public repository, screenshots, logs, error responses, or generated client code:

- `URONTOPAY_CLIENT_ID`
- `URONTOPAY_SECRET_KEY`
- `URONTOPAY_BRAND_KEY`

Use server-side environment variables:

```env
URONTOPAY_BASE_URL=https://pay1.urontopay.com
URONTOPAY_CLIENT_ID=YOUR_CLIENT_ID
URONTOPAY_SECRET_KEY=YOUR_SECRET_KEY
URONTOPAY_BRAND_KEY=YOUR_BRAND_KEY
```

Every API request requires:

```http
Content-Type: application/json
CLIENT-ID: YOUR_CLIENT_ID
SECRET-KEY: YOUR_SECRET_KEY
BRAND-KEY: YOUR_BRAND_KEY
```

## Required payment architecture

1. The customer clicks Pay on the merchant website.
2. The frontend sends the order information to the merchant backend.
3. The backend validates the order, calculates the amount from trusted server-side data, and saves the order as `pending`.
4. The backend calls `POST /api/payment/create`.
5. The backend redirects the customer to the returned `payment_url`.
6. UrontoPay returns the customer to `success_url` or `cancel_url`, and may also send a notification to `webhook_url`.
7. The merchant backend extracts `transactionId` and calls `POST /api/payment/verify`.
8. The backend marks the order paid only when the verified response has `status: COMPLETED`, the amount matches, and `metadata.order_id` matches the local order.
9. The update must be idempotent so repeated callbacks cannot fulfill an order twice.

## Create Payment

**Endpoint**

```http
POST https://pay1.urontopay.com/api/payment/create
```

**JSON body**

```json
{
  "amount": 500,
  "cus_name": "Customer Name",
  "cus_email": "customer@example.com",
  "success_url": "https://merchant.example/payment/success",
  "cancel_url": "https://merchant.example/payment/cancel",
  "webhook_url": "https://merchant.example/webhooks/urontopay",
  "return_type": "GET",
  "metadata": {
    "order_id": "ORDER-1001"
  }
}
```

Required fields:

- `amount`: number between 0.01 and 1,000,000
- `success_url`: valid HTTPS URL
- `cancel_url`: valid HTTPS URL

Optional fields:

- `cus_name`
- `cus_email`
- `webhook_url`
- `metadata`
- `return_type`: `GET` or `POST`; default `GET`

**Success response**

```json
{
  "status": 1,
  "message": "Payment Link",
  "payment_url": "https://pay1.urontopay.com/api/execute/59522f..."
}
```

Redirect to `payment_url`. Do not mark the order paid yet.

## Verify Transaction

**Endpoint**

```http
POST https://pay1.urontopay.com/api/payment/verify
```

**JSON body**

```json
{
  "transaction_id": "UP123456"
}
```

**Example response**

```json
{
  "cus_name": "Customer Name",
  "cus_email": "customer@example.com",
  "amount": "500.000",
  "transaction_id": "UP123456",
  "metadata": {
    "order_id": "ORDER-1001"
  },
  "payment_method": "bkash",
  "status": "COMPLETED"
}
```

Verification acceptance rules:

- The HTTP request succeeded.
- `status` is exactly `COMPLETED`.
- Parse the amount safely as a decimal and compare it with the local expected amount.
- `metadata.order_id` matches the local order.
- The transaction ID has not already been used for a different order.
- The order has not already been fulfilled.

## Return URL and webhook

Typical fields may include:

```text
paymentMethod=bkash
transactionId=UP123456
paymentAmount=500
paymentFee=0
status=completed
```

These fields are untrusted. They are only a signal to start server-side verification.

A webhook handler should:

1. Accept the configured HTTP method.
2. Extract `transactionId`.
3. Return quickly.
4. Verify the transaction with UrontoPay.
5. Update the order inside a transaction or other idempotent operation.
6. Safely handle repeated delivery.

## Error handling

- `400`: invalid or missing request fields
- `401`: invalid/missing keys, keys do not belong together, credential disabled, or plan inactive
- `404`: unknown payment or transaction
- `500`: unexpected server processing error

Implementation requirements:

- Use a connect timeout and total request timeout.
- Treat every non-2xx response as a failure.
- Keep the order pending if the API result is ambiguous.
- Log a request correlation ID and safe context, but never log credentials.
- Escape user-visible error messages.
- Avoid automatically retrying Create Payment in a way that could create multiple payment links without tracking them.
- Verification can be retried safely when the local update is idempotent.

## Prompt template

```text
Read https://urontopay.com/openapi.json and https://urontopay.com/ai-integration.md.
Integrate UrontoPay into my [FRAMEWORK] application.

Create:
- environment configuration
- a server-side create-payment endpoint
- a checkout form that posts only to my backend
- success and cancel pages
- a webhook handler
- a reusable verify-payment service
- database-safe, idempotent order updates
- validation, timeouts, secure error handling, and tests

Never expose or log the Secret Key. Calculate the payable amount from trusted server-side order data. Mark an order paid only after server-side verification returns COMPLETED and the amount and metadata.order_id match.
```