# Hosted Checkout

- 服务地址（示例，真实 Host 由接入团队提供）：`https://checkout.psp.example.com`
- 认证：无需凭证
- 版本：1.0.0
- OpenAPI 规范：https://docs.potabank.com/openapi/proof.openapi.yaml

Consumer checkout for an existing Gateway PaymentIntent. Use the
psp_checkout_url returned by the Invoice API. Checkout access requires a
token bound to the payment and tenant in X-Checkout-Session-Token or ?t=.
Merchant Gateway credentials do not apply.

## Hosted Checkout

### Read hosted payment and saved instructions

**GET** `/checkout/hosted/payments/{payment_id}`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `payment_id` | `string<uuid>` | 必填 | — |

**查询参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `t` | `string` | 可选 | Checkout token; provide this parameter or X-Checkout-Session-Token. |

**请求头**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `X-Checkout-Session-Token` | `string` | 可选 | Checkout token; provide this header or t. |

**请求示例**

```bash
curl -X GET 'https://checkout.psp.example.com/checkout/hosted/payments/{payment_id}'
```

**响应**

#### 响应 200 OK

Hosted payment detail and instructions

### Read payment status

**GET** `/checkout/hosted/payments/{payment_id}/status`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `payment_id` | `string<uuid>` | 必填 | — |

**查询参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `t` | `string` | 可选 | Checkout token; provide this parameter or X-Checkout-Session-Token. |

**请求头**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `X-Checkout-Session-Token` | `string` | 可选 | Checkout token; provide this header or t. |

**请求示例**

```bash
curl -X GET 'https://checkout.psp.example.com/checkout/hosted/payments/{payment_id}/status'
```

**响应**

#### 响应 200 OK

Payment status

### Read the validated return redirect

**GET** `/checkout/hosted/payments/{payment_id}/success-redirect`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `payment_id` | `string<uuid>` | 必填 | — |

**查询参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `t` | `string` | 可选 | Checkout token; provide this parameter or X-Checkout-Session-Token. |

**请求头**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `X-Checkout-Session-Token` | `string` | 可选 | Checkout token; provide this header or t. |

**请求示例**

```bash
curl -X GET 'https://checkout.psp.example.com/checkout/hosted/payments/{payment_id}/success-redirect'
```

**响应**

#### 响应 200 OK

Redirect decision

### Submit hosted credit card payment

**POST** `/checkout/creditcard/payment-intents/{payment_id}/pay`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `payment_id` | `string<uuid>` | 必填 | — |

**查询参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `t` | `string` | 可选 | Checkout token; provide this parameter or X-Checkout-Session-Token. |

**请求头**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `X-Checkout-Session-Token` | `string` | 可选 | Checkout token; provide this header or t. |

**请求体** (application/json · 必填)

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `card_token` | `string` | 可选 | — |
| `card_cvv` | `string` | 可选 | — |
| `card_info` | `object` | 可选 | — |
| `card_info.card_number` | `string` | 必填 | — |
| `card_info.cvv` | `string` | 必填 | — |
| `card_info.expiry_month` | `integer` | 必填 | ≥ 1 · ≤ 12 |
| `card_info.expiry_year` | `integer` | 必填 | — |
| `card_info.cardholder_name` | `string` | 必填 | — |
| `billing_address` | `object` | 可选 | — |
| `payer_info` | `object` | 可选 | — |
| `payer_info.name` | `string` | 可选 | — |
| `payer_info.email` | `string<email>` | 可选 | — |
| `payer_info.phone` | `string` | 可选 | — |
| `require_3ds` | `boolean` | 可选 | — |

**请求示例**

```bash
curl -X POST 'https://checkout.psp.example.com/checkout/creditcard/payment-intents/{payment_id}/pay' \
  -H 'Content-Type: application/json' \
  -d '{
    "card_token": "string",
    "card_cvv": "string",
    "card_info": {
      "card_number": "string",
      "cvv": "string",
      "expiry_month": 1,
      "expiry_year": 0,
      "cardholder_name": "string"
    },
    "billing_address": {},
    "payer_info": {
      "name": "string",
      "email": "user@example.com",
      "phone": "string"
    },
    "require_3ds": false
  }'
```

**响应**

#### 响应 200 OK

Payment submitted

### Complete card 3DS authentication

**POST** `/checkout/creditcard/payment-intents/{payment_id}/complete-3ds`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `payment_id` | `string<uuid>` | 必填 | — |

**查询参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `t` | `string` | 可选 | Checkout token; provide this parameter or X-Checkout-Session-Token. |

**请求头**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `X-Checkout-Session-Token` | `string` | 可选 | Checkout token; provide this header or t. |

**请求体** (application/json · 必填)

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `authorization_id` | `string<uuid>` | 必填 | — |
| `transaction_id` | `string` | 必填 | — |
| `auth_value` | `string` | 必填 | — |
| `eci` | `string` | 必填 | — |
| `cres_nonce` | `string` | 必填 | — |

**请求示例**

```bash
curl -X POST 'https://checkout.psp.example.com/checkout/creditcard/payment-intents/{payment_id}/complete-3ds' \
  -H 'Content-Type: application/json' \
  -d '{
    "authorization_id": "00000000-0000-7000-8000-000000000000",
    "transaction_id": "string",
    "auth_value": "string",
    "eci": "string",
    "cres_nonce": "string"
  }'
```

**响应**

#### 响应 200 OK

3DS completed