---
title: "Tạo phiên thanh toán và link thu tiền"
method: POST
path: "/api/v1/checkouts"
tags: ["Hosted checkout"]
---

# Tạo phiên thanh toán và link thu tiền

`POST /api/v1/checkouts`

## Request

- Base URL: `https://api.monapay.vn`
- URL: `https://api.monapay.vn/api/v1/checkouts`
- Auth: HTTP bearer and API key in header `X-Client-Secret`

Tạo VietQR động và trả checkout_url. Nếu chưa có hồ sơ trả 422 detail=payment_profile_missing.

## Headers

- `Idempotency-Key` string, required

## Request body

- CheckoutCreate
  - `amount` integer, required: Số tiền VND.
  - `order_code` string, required
  - `description` string
  - `return_url` string, uri, required
  - `cancel_url` string, uri
  - `payer_email` string, email
  - `payer_name` string
  - `expires_in` integer
  - `metadata` object: JSON tối đa 2 KB sau khi encode.
  - `virtual_account_id` string, uuid
  - `sandbox` boolean: true để dùng VA sandbox SBX và không chuyển tiền thật.

## Response `201`

Envelope với data là Checkout.

- object
  - `success` boolean, required
  - `message` string, required
  - `data` Checkout, required
    - `id` string, uuid, required
    - `token` string, required: Token URL-safe dùng cho trang public.
    - `checkout_url` string, uri, required
    - `status` 'pending' | 'paid' | 'expired' | 'cancelled', required
    - `amount` integer, required
    - `currency` 'VND', required
    - `order_code` string, required
    - `description` string, required
    - `payer_email` string, email, nullable
    - `payer_name` string, nullable
    - `metadata` object, nullable
    - `qr_code_id` string, uuid, required
    - `qr_data_url` string, required
    - `qr_image_url` string, uri, required
    - `bank` object, required
      - `code` string, required
      - `name` string, required
      - `account_number` string, required
      - `account_name` string, required
      - `transfer_content` string, required
    - `return_url` string, uri, required
    - `cancel_url` string, uri, nullable
    - `expires_at` string, date-time, required
    - `paid_at` string, date-time, nullable
    - `transaction_code` string, nullable
    - `paid_amount` integer, nullable
    - `partial_amount` integer, nullable
    - `paid_late` boolean
    - `sandbox` boolean
    - `created_at` string, date-time, required

## Other responses

- `409`: Trùng order_code đang pending hoặc Idempotency-Key khác body.
- `422`: payment_profile_missing hoặc dữ liệu không hợp lệ.
- `502`: Ngân hàng không tạo được QR.

---

[API](https://skmtc.dev/monapay/apis/mona-pay-api-v1.md) · [All operations](https://skmtc.dev/monapay/apis/mona-pay-api-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/monapay/apis/mona-pay-api-v1/revisions/ed3fbd821dce?raw)