> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments

> Collect one-off payments from your customers

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.

<Info>
  For recurring billing and subscription management, see [Customer Lifecycle](/platform/billing/customer-lifecycle).
</Info>

## 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](/platform/payments/portal)
4. **Receive a webhook** confirming the payment status

## Create a payment

<Info>
  **API Reference**: See the [Create Payment endpoint](/api-reference/payments/create-payment) for the complete request and response schema.
</Info>

<CodeGroup>
  ```bash cURL theme={null}
  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
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```typescript TypeScript SDK theme={null}
  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);
  ```

  ```python Python theme={null}
  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"])
  ```

  ```python Python SDK theme={null}
  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)
  ```
</CodeGroup>

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.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.paygentic.io/v0/payments/pay_a1b2c3d4e5f6g7h8i9j0 \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```typescript TypeScript SDK theme={null}
  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);
  ```

  ```python Python theme={null}
  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"])
  ```

  ```python Python SDK theme={null}
  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)
  ```
</CodeGroup>

## 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                                        |

<Note>
  Most payments follow the path: `pending` → `processing` → `completed`. If the customer doesn't pay before the expiration, the payment transitions to `expired`.
</Note>

## 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](mailto: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](/platform/developers/webhooks) for setup instructions and verification examples.

## Next steps

* [Payment Portal](/platform/payments/portal) — Embed the payment page in your application
* [Create Payment API Reference](/api-reference/payments/create-payment) — Full endpoint documentation
* [Accounts](/platform/payments/accounts) — How funds are managed and settled