> 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/api-payment-examples.md).

# API Payment Examples

This page provides end-to-end examples of integrating the Pingpay API, using both supported integration paths, Hosted Checkout and Headless Payments.

***

### Example 1: Hosted Checkout Flow

This example shows the full flow for accepting a payment using **Pingpay Hosted Checkout**.

#### Step 1: Create a Checkout Session

```http
POST https://pay.pingpay.io/api/checkout/sessions
x-publishable-key: pk_test_123456
Content-Type: application/json
```

```json
{
  "amount": {
    "assetId": "nep141:wrap.near",
    "amount": "1000000000000000000000000"
  },
  "recipient": {
    "address": "example.near",
    "chainId": "near-mainnet"
  },
  "successUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel"
}
```

#### Step 2: Redirect the User

From the response, retrieve the `sessionUrl` and redirect the user to it:

```
https://checkout.pingpay.io/session/cs_123
```

The user completes the payment on the Pingpay-hosted checkout page.

***

#### Step 3: Retrieve the Checkout Session

After the user is redirected back to your `successUrl`, retrieve the session to confirm final status.

```http
GET https://pay.pingpay.io/api/checkout/sessions/cs_123
x-publishable-key: pk_test_123456
```

```json
{
  "session": {
    "sessionId": "cs_123",
    "status": "COMPLETED",
    "paymentId": "pay_456"
  }
}
```

Once the session status is `COMPLETED`, the payment can be considered successful.

***

### Example 2: Headless Payment Flow

This example shows how to execute a payment using **Headless Payments** without a hosted checkout.

***

#### Step 1: Prepare a Payment

```http
POST https://pay.pingpay.io/api/payments/prepare
x-publishable-key: pk_test_123456
Content-Type: application/json
```

```json
{
  "payer": {
    "address": "payer.near",
    "chainId": "near-mainnet"
  },
  "recipient": {
    "address": "example.near",
    "chainId": "near-mainnet"
  },
  "asset": {
    "assetId": "nep141:wrap.near",
    "amount": "1000000000000000000000000"
  },
  "idempotencyKey": "order_12345"
}
```

Response:

```json
{
  "payment": {
    "paymentId": "pay_456",
    "status": "PENDING"
  }
}
```

***

#### Step 2: Submit the Payment

After preparing the payment and collecting the required signature or authorisation from the payer, submit the payment for execution.

```http
POST https://pay.pingpay.io/api/payments/submit
x-publishable-key: pk_test_123456
Content-Type: application/json
```

```json
{
  "paymentId": "pay_456",
  "idempotencyKey": "order_12345",
  "signedPayload": "0xabcdef..."
}
```

Response:

```json
{
  "payment": {
    "paymentId": "pay_456",
    "status": "PENDING"
  }
}
```

***

#### Step 3: Retrieve the Payment

Poll the payment until it reaches a final state.

```http
GET https://pay.pingpay.io/api/payments/pay_456
x-publishable-key: pk_test_123456
```

```json
{
  "payment": {
    "paymentId": "pay_456",
    "status": "SUCCESS"
  }
}
```

Once the status is `SUCCESS`, the payment is complete and can be fulfilled.

***