Create Payment

Create a new payment session and get a checkout URL to redirect your customer.

POST/api/v1/payments/create

Request Body

Field	Type	Required	Description
`amount`	integer	Required	Amount in cents (5000 = $50.00)
`currency`	string	Required	3-letter code: `usd`, `eur`, `gbp`, etc.
`successUrl`	string	Required	Redirect URL after successful payment
`cancelUrl`	string	Required	Redirect URL if customer cancels
`customerEmail`	string	Optional	Customer's email address
`customerName`	string	Optional	Customer's full name
`description`	string	Optional	Payment description (shown in dashboard)
`webhookUrl`	string	Optional	URL to receive payment status updates
`metadata`	object	Optional	Custom data (e.g., order ID)

Example Request

json

{
  "amount": 9999,
  "currency": "usd",
  "customerEmail": "john@example.com",
  "customerName": "John Doe",
  "description": "Order #12345",
  "successUrl": "https://yoursite.com/thank-you?order=12345",
  "cancelUrl": "https://yoursite.com/checkout",
  "webhookUrl": "https://yoursite.com/api/webhooks/ultrapay",
  "metadata": {
    "orderId": "12345",
    "productName": "Premium Plan"
  }
}

Success Response

json

{
  "success": true,
  "data": {
    "transactionId": "550e8400-e29b-41d4-a716-446655440000",
    "paymentUrl": "https://checkout.stripe.com/c/pay/cs_live_xxx...",
    "sessionId": "cs_live_a1b2c3d4...",
    "expiresAt": "2025-01-01T12:30:00.000Z"
  }
}

Response Fields

Field	Description
`transactionId`	UltraPay transaction ID (save this!)
`paymentUrl`	Stripe Checkout URL - redirect customer here
`sessionId`	Stripe Checkout Session ID
`expiresAt`	When the payment link expires (usually 30 min)

URL Privacy

Your successUrl and cancelUrl are hidden from Stripe. After payment, customers are redirected through our servers first, then to your URL. This keeps your domain private.

Important: Never Use Iframes

⚠️ Warning: Never embed the paymentUrl in an iframe. Always use a full page redirect.

Payment URLs must be opened via window.location.href or a standard link. Iframes are blocked because:

Stripe actively blocks checkout pages from loading in iframes
Most browsers block third-party cookies in iframes, breaking payments
Iframe embedding is a common phishing technique that payment processors prevent
3D Secure authentication cannot complete properly in an iframe

cURL Example

bash

curl -X POST https://pay.ultrapay.cc/api/v1/payments/create \
  -H "X-Public-Key: upp_your_public_key" \
  -H "X-Secret-Key: ups_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "usd",
    "customerEmail": "customer@example.com",
    "successUrl": "https://yoursite.com/thank-you",
    "cancelUrl": "https://yoursite.com/checkout"
  }'