Payments

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

Create a payment via the API with an amount, currency, and optional details
Share the payment URL with your customer — via link, email, or embedded in your app
Customer pays on the hosted payment portal
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
      }
    ]
  }'

const response = await fetch("https://api.paygentic.io/v0/payments", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    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 },
    ],
  }),
});

const payment = await response.json();
console.log("Payment URL:", payment.paymentUrl);

import { Paygentic } from "@paygentic/sdk";

const client = new Paygentic({
  bearerAuth: "sk_live_YOUR_API_KEY",
});

const payment = await client.payments.create({
  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 },
  ],
});

console.log("Payment URL:", payment.paymentUrl);

import requests

response = requests.post(
    "https://api.paygentic.io/v0/payments",
    headers={
        "Authorization": "Bearer sk_live_YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "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},
        ],
    },
)

payment = response.json()
print("Payment URL:", payment["paymentUrl"])

from paygentic_sdk import Paygentic

client = Paygentic(bearer_auth="sk_live_YOUR_API_KEY")

payment = client.payments.create(
    amount="49.99",
    currency="USD",
    reference="ORD-12345",
    success_redirect_url="https://yourapp.com/success",
    expires_in="P7D",
    line_items=[
        {"description": "Pro Widget", "amount": "39.99", "quantity": 1},
        {"description": "Shipping", "amount": "10.00", "quantity": 1},
    ],
)

print("Payment URL:", payment.payment_url)

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"

const response = await fetch(
  "https://api.paygentic.io/v0/payments/pay_a1b2c3d4e5f6g7h8i9j0",
  {
    headers: {
      "Authorization": "Bearer sk_live_YOUR_API_KEY",
    },
  }
);

const payment = await response.json();
console.log("Status:", payment.status);

import { Paygentic } from "@paygentic/sdk";

const client = new Paygentic({
  bearerAuth: "sk_live_YOUR_API_KEY",
});

const payment = await client.payments.get({
  id: "pay_a1b2c3d4e5f6g7h8i9j0",
});

console.log("Status:", payment.status);

import requests

response = requests.get(
    "https://api.paygentic.io/v0/payments/pay_a1b2c3d4e5f6g7h8i9j0",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
)

payment = response.json()
print("Status:", payment["status"])

from paygentic_sdk import Paygentic

client = Paygentic(bearer_auth="sk_live_YOUR_API_KEY")

payment = client.payments.get(id="pay_a1b2c3d4e5f6g7h8i9j0")

print("Status:", payment.status)

Payment lifecycle

Every payment moves through these statuses:

Status	Description
`pending`	Payment created, waiting for customer to pay
`processing`	Customer submitted payment, processing with payment provider
`completed`	Payment successfully collected
`expired`	Payment link expired before the customer paid
`cancelled`	Payment 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:

Event	Description
`payment.completed.v0`	Payment was successfully completed
`payment.failed.v0`	Payment attempt failed (includes error code and message)
`payment.expired.v0`	Payment expired before the customer completed it

See Webhooks for setup instructions and verification examples.

Next steps

Payment Portal — Embed the payment page in your application
Create Payment API Reference — Full endpoint documentation
Accounts — How funds are managed and settled

Getting Started

Authentication

Platform

Integrations

Legal

How it works

Create a payment

Check payment status

Payment lifecycle

Key features

Webhooks

Next steps

​How it works

​Create a payment

​Check payment status

​Payment lifecycle

​Key features

​Webhooks

​Next steps

How it works

Create a payment

Check payment status

Payment lifecycle

Key features

Webhooks

Next steps