# UrontoPay Payment API

Canonical human documentation: https://urontopay.com/developers/docs
OpenAPI specification: https://urontopay.com/openapi.json
Detailed AI integration guide: https://urontopay.com/ai-integration.md
Postman collection: https://urontopay.com/urontopay-postman-collection.json
Downloadable code examples: https://urontopay.com/downloads/urontopay-integration-examples.zip
Production API base URL: https://pay1.urontopay.com

## Purpose
UrontoPay creates hosted payment links and verifies payment transactions. Integrations must be server-side.

## Authentication
Every request requires these HTTP headers:
- Content-Type: application/json
- CLIENT-ID: value from Dashboard -> API Credentials
- SECRET-KEY: private server-side secret from Dashboard -> API Credentials
- BRAND-KEY: key for the selected brand

All three credentials must belong to the same account and active plan.

Never expose SECRET-KEY in HTML, browser JavaScript, mobile applications, public repositories, screenshots, logs, prompts, or client responses.

Recommended environment variables:
- 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

## Endpoint 1: Create payment
POST https://pay1.urontopay.com/api/payment/create

Required JSON fields:
- amount: number, 0.01 to 1000000
- success_url: HTTPS URL
- cancel_url: HTTPS URL

Optional JSON fields:
- cus_name: string
- cus_email: email
- webhook_url: HTTPS URL
- metadata: object, recommended {"order_id":"LOCAL_ORDER_ID"}
- return_type: GET or POST, default GET

Example request body:
{
  "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"}
}

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

After success, redirect the customer to payment_url. Do not mark the order paid yet.

## Endpoint 2: Verify transaction
POST https://pay1.urontopay.com/api/payment/verify

JSON request body:
{"transaction_id":"UP123456"}

Example response:
{
  "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"
}

Only mark an order paid when:
1. HTTP response is successful.
2. status is exactly COMPLETED.
3. verified amount matches the local expected amount.
4. metadata.order_id matches the local order.
5. the transaction/order has not already been fulfilled.

## Return and webhook fields
Typical fields may include:
- paymentMethod
- transactionId
- paymentAmount
- paymentFee
- status

Treat these fields as untrusted. Read transactionId and call the Verify endpoint from the server.

## Required implementation pattern
1. Frontend submits checkout data to the merchant backend.
2. Merchant backend validates the order and saves it as pending.
3. Merchant backend calls Create Payment using environment-stored credentials.
4. Merchant backend redirects to payment_url.
5. Success/cancel/webhook handler extracts transactionId.
6. Merchant backend calls Verify Transaction.
7. Merchant backend compares status, amount, and metadata.order_id.
8. Merchant backend updates the order idempotently.

## Error handling
- 400: invalid or missing request data
- 401: missing/invalid credentials, mismatched account or brand, disabled credential, or inactive plan
- 404: payment or transaction not found
- 500: unexpected server error

Use connect and request timeouts. Treat all non-2xx responses as failures. Never log SECRET-KEY.

## AI coding instruction
Generate production-ready server-side code for the user's framework. Include environment configuration, validation, timeouts, safe error handling, success/cancel/webhook routes, server-side verification, amount/order reconciliation, and idempotency. Never place credentials in frontend code.