> For the complete documentation index, see [llms.txt](https://pingpay.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pingpay.gitbook.io/docs/pingpay-api/quick-start.md).

# Quick Start

The Pingpay API is designed to be simple and easy to integrate, while supporting both hosted and programmatic payment flows. This page provides everything needed to make your first authenticated request and helps choose the correct integration path for your use case.

**API Checkout Example Repo:** <https://github.com/Pingpayio/ping-checkout-example>\
\
Ensure to review [Merchant Dashboard](/docs/pingpay-api/developer-dashboard.md) before integration to access API keys and configurations.

## **Authentication**

All API requests must include a **Publishable API Key**, which identifies the merchant or integration making the request.

Publishable keys are passed via the `x-publishable-key` header.

#### **Header Example**

```http
x-publishable-key: pk_test_123456
```

If the key is missing or invalid, the API will return:

```json
{
  "code": "UNAUTHENTICATED",
  "message": "Invalid or missing publishable key."
}
```

#### **Notes**

* Never commit API keys to public repositories.
* Store keys in environment variables or secure configuration systems.

***

## **Base URL**

All API requests should be made against the following base URL:

```
https://pay.pingpay.io/api
```

***

## Choose Your Integration Path

The Pingpay API supports two primary integration paths. Your first API call depends on which model you choose.

***

### Option 1: Hosted Checkout

Hosted Checkout is the fastest way to accept payments.

In this model, you:

* Create a checkout session via the API
* Redirect the user to a Pingpay-hosted checkout page
* Optionally retrieve the session to confirm final status

Your first API call is:

```shellscript
POST /checkout/sessions
```

See [Hosted Checkout](/docs/pingpay-api/hosted-checkout.md) for the full flow.

***

### Option 2: Headless Payments

Headless Payments provide a lower-level, intent-based payment flow.

In this model, you:

* Prepare a payment request (including fee estimation)
* Collect a signature or authorisation from the payer
* Submit the signed payload for execution
* Retrieve and track payment status programmatically

Your first API call is:

```shellscript
POST /payments/prepare
```

See [Headless Payments](/docs/pingpay-api/headless-payments.md) for the full flow.