> 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/hosted-checkout/create-checkout.md).

# Create Checkout

This page explains how to create your checkout with Ping.

***

## **Create Checkout Session**

The `POST /checkout/sessions` endpoint is used to create a new hosted checkout session.<br>

A checkout session represents a pending payment intent that a customer can complete using the Pingpay hosted checkout experience. Once created, the API returns a `sessionUrl` that the user should be redirected to in order to complete payment.

***

### **Endpoint**

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

***

### **Headers**

```http
x-api-key: pk_test_123456
Content-Type: application/json
```

***

### **Request Body**

The request body follows the structure defined in the OpenAPI specification:

```json
{
  "amount": "1000000",
  "asset":{
    "chain":"NEAR",
    "symbol":"USDC",
  },
  "successUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "customRecipientMsg": "happy hacking",
  "metadata": {
    "orderId": "12345"
  }
}
```

#### **Required fields**

* `amount`
* `recipient`

All other fields are optional.

**Optional fields Note**

`customRecipientMsg` *(string, max 256 characters)*

A message passed to the recipient when sending NEAR fungible tokens. This maps to the `msg` parameter in the NEP-141 `ft_transfer_call` function.

> **Only use this field if the recipient is a NEAR smart contract** that implements the `ft_on_transfer` callback. If the recipient contract does not implement `ft_on_transfer`, the transfer will be rejected by the token contract and the funds may be lost permanently.
>
> If you are sending to a regular NEAR wallet address, omit this field.

***

### **Response**

A successful request returns:

```json
{
  "session": {
    "sessionId": "cs_123",
    "status": "CREATED",
    "paymentId": null,
    "amount": {
      "assetId": "nep141:wrap.near",
      "amount": "1000000000000000000000000"
    },
    "recipient": {
      "address": "example.near",
    },
    "successUrl": "https://example.com/success",
    "cancelUrl": "https://example.com/cancel",
    "createdAt": "2025-01-01T00:00:00.000Z",
    "expiresAt": "2025-01-01T00:15:00.000Z",
    "metadata": {
      "orderId": "12345",
    }
  },
  "sessionUrl": "https://checkout.pingpay.io/session/cs_123"
}
```

#### **Key fields**

* `sessionId` — Unique identifier for the checkout session
* `sessionUrl` — URL to redirect the user to complete payment
* `status` — Initial value is `CREATED`
* `paymentId` — Identifier of the resulting payment, if and when one is created
* `expiresAt` — Optional expiration timestamp for the checkout session

> **Note:**\
> The `sessionUrl` should be treated as an **opaque value** and used exactly as returned by the API. Do not attempt to construct this URL manually.

***

#### Notes

* Creating a checkout session does **not** execute a payment immediately
* The payment is completed by the user via the Pingpay-hosted checkout page
* The `paymentId` field may be `null` until the checkout flow has completed
* Checkout sessions may expire if not completed within the configured time window

***

### **Error Response Example**

```json
{
  "code": "INVALID_PUBLISHABLE_KEY",
  "message": "Publishable key is invalid."
}
```

***