Skip to main content
The Payments API lets you create standalone one-off charges and collect payments through a hosted payment page. Use it for orders, service fees, or any ad-hoc charge that isn’t part of a recurring subscription.
For recurring billing and subscription management, see Customer Lifecycle.

​
How it works

  1. Create a payment via the API with an amount, currency, and optional details
  2. Share the payment URL with your customer — via link, email, or embedded in your app
  3. Customer pays on the hosted payment portal
  4. Receive a webhook confirming the payment status

​
Create a payment

API Reference: See the Create Payment endpoint for the complete request and response schema.
curl -X POST https://api.paygentic.io/v0/payments \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.99",
    "currency": "USD",
    "reference": "ORD-12345",
    "successRedirectUrl": "https://yourapp.com/success",
    "expiresIn": "P7D",
    "lineItems": [
      {
        "description": "Pro Widget",
        "amount": "39.99",
        "quantity": 1
      },
      {
        "description": "Shipping",
        "amount": "10.00",
        "quantity": 1
      }
    ]
  }'
The response includes a paymentUrl that you can share with your customer to complete the payment.

​
Check payment status

You can poll payment status as a fallback if webhooks are delayed. 
curl https://api.paygentic.io/v0/payments/pay_a1b2c3d4e5f6g7h8i9j0 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

​
Payment lifecycle

Every payment moves through these statuses:
StatusDescription
pendingPayment created, waiting for customer to pay
processingCustomer submitted payment, processing with payment provider
completedPayment successfully collected
expiredPayment link expired before the customer paid
cancelledPayment was cancelled
Most payments follow the path: pending → processing → completed. If the customer doesn’t pay before the expiration, the payment transitions to expired.

​
Key features

  • Currency — Payments use your account currency, chosen during onboarding (USD, EUR, GBP, or AUD)
  • Line items — Optional itemized breakdown displayed on the payment page (up to 100 items)
  • Idempotency — Use idempotencyKey to safely retry requests without creating duplicate payments
  • Metadata — Attach arbitrary key-value pairs to payments for your own tracking
  • Custom expiration — Set expiresIn as an ISO 8601 duration (e.g., P7D for 7 days). Default is 30 days, maximum is 31 days
  • Redirect URLs — Specify successRedirectUrl and failureRedirectUrl for the hosted payment page
  • Save payment method — Set savePaymentMethod: true to store the customer’s card for future use (requires customerId)
  • Amount range — Minimum 1.00, maximum 5,000.00 (in your account currency). Contact support@paygentic.io for higher limits

​
Webhooks

Payment status changes fire webhook events. Listen for these to confirm payments server-side:
EventDescription
payment.completed.v0Payment was successfully completed
payment.failed.v0Payment attempt failed (includes error code and message)
payment.expired.v0Payment expired before the customer completed it
See Webhooks for setup instructions and verification examples.

​
Next steps