PAY.JP v2

https://docs.pay.jp/v2
Admin
PAY.JP is a payment processing service that enables businesses to quickly integrate payment...
Tokens:29,216
Snippets:293
Trust Score:9.8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Create a Setup Flow (Server-side)

Source: https://docs.pay.jp/v2/guide/payments/setupflow

Create a Setup Flow by specifying the customer and allowed payment method types. This is the first step in registering a payment method using the server-side API.

```bash
curl -X POST https://api.pay.jp/v2/setup_flows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_xxxxx",
    "payment_method_types": ["card"]
  }'
```

--------------------------------

### Install payjp-cli with Scoop on Windows

Source: https://docs.pay.jp/v2/guide/developers/payjp-cli

Install the payjp-cli tool on Windows using Scoop after adding the bucket.

```bash
scoop install payjp-cli
```

--------------------------------

### Install and Initialize payments.js with npm

Source: https://docs.pay.jp/v2/guide/developers/paymentsjs-reference

Install the @payjp/payments-js package and use the loadPayments function to initialize the payments object.

```bash
npm install @payjp/payments-js
```

```javascript
import { loadPayments } from '@payjp/payments-js'

const payments = await loadPayments('YOUR_PUBLIC_KEY')
```

--------------------------------

### Initialize PAY.JP Payments.js (npm)

Source: https://docs.pay.jp/v2/guide/payments/setupflow

Install the PAY.JP payments library using npm and initialize it with your public key.

```javascript
npm install @payjp/payments-js
```

```javascript
import { loadPayments } from '@payjp/payments-js'

const payments = await loadPayments('pk_test_xxx')
...
```

--------------------------------

### Verify Setup Flow Status (Front-end)

Source: https://docs.pay.jp/v2/guide/payments/setupflow

Retrieve the Setup Flow using its client secret on the redirect page to verify if the payment method registration was successful. Check the 'status' field for 'succeeded'.

```javascript
const setupFlow = await payments.retrieveSetupFlow(
  "sflw_secret_xxxxx"
);

if (setupFlow.status === 'succeeded') {
  // 登録成功
  const paymentMethodId = setupFlow.payment_method;
  console.log('登録された支払い方法:', paymentMethodId);
} else {
  // 登録失敗時の処理
}
```

--------------------------------

### Install payjp-cli with Homebrew on macOS

Source: https://docs.pay.jp/v2/guide/developers/payjp-cli

Use this command to install the payjp-cli tool on macOS using Homebrew.

```bash
brew install payjp/tap/payjp-cli
```

--------------------------------

### Confirm Setup and Register Payment Method

Source: https://docs.pay.jp/v2/guide/payments/setupflow

Execute the confirmSetup method after the user enters payment information to finalize the registration. This will redirect the user to the return_url upon completion.

```javascript
const result = await widgets.confirmSetup({
  return_url: 'https://example.com/setup-complete'
});

if (result.error) {
  // エラー処理
  console.error(result.error);
}
```

--------------------------------

### Initialize payments.js with npm

Source: https://docs.pay.jp/v2/guide/payments/paymentwidgets

Install the @payjp/payments-js package and use the loadPayments method to initialize the payments object in your project. This is an alternative to using a script tag.

```javascript
npm install @payjp/payments-js
```

```javascript
import { loadPayments } from '@payjp/payments-js'

const payments = await loadPayments('YOUR_PUBLIC_KEY')
...
```

--------------------------------

### Initialize Widgets with Client Secret

Source: https://docs.pay.jp/v2/guide/payments/setupflow

Initialize the Payment Widgets using the client secret obtained from the server-side Setup Flow creation.

```javascript
const widgets = payments.widgets({
  clientSecret: "sflw_secret_xxxxx",
});
```

--------------------------------

### Add payjp-cli Scoop bucket on Windows

Source: https://docs.pay.jp/v2/guide/developers/payjp-cli

Add the PAY.JP Scoop bucket to your Windows environment before installing the CLI tool.

```bash
scoop bucket add payjp https://github.com/payjp/scoop-bucket.git
```

--------------------------------

### Webhook Request Body Example

Source: https://docs.pay.jp/v2/guide/developers/event-webhook

This is an example of the JSON payload structure for a 'payment_flow.succeeded' event. Familiarize yourself with the fields to process event data effectively.

```json
{
  "id": "evt_xxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "event",
  "created_at": "2025-01-15T10:30:00.000Z",
  "updated_at": "2025-01-15T10:30:00.000Z",
  "livemode": true,
  "type": "payment_flow.succeeded",
  "pending_webhooks": 1,
  "data": {
    "id": "pfw_xxxxxxxxxxxxxxxxxxxxxxxx",
    "object": "payment_flow",
    "status": "succeeded",
    "amount": 1000,
    "currency": "jpy",
    "payment_method_types": ["card"],
    "capture_method": "automatic",
    ...
  }
}
```

--------------------------------

### Verify Webhook Token

Source: https://docs.pay.jp/v2/guide/developers/event-webhook

This example demonstrates how to verify the `X-Payjp-Webhook-Token` header to ensure incoming webhooks are from PAY.JP. It requires setting the `PAYJP_WEBHOOK_TOKEN` environment variable.

```javascript
import express from 'express';
const app = express();

app.use(express.json());

const WEBHOOK_TOKEN = process.env.PAYJP_WEBHOOK_TOKEN;

app.post('/webhook', (req, res) => {
  // Webhook Tokenの検証
  const receivedToken = req.headers['x-payjp-webhook-token'];

  if (receivedToken !== WEBHOOK_TOKEN) {
    return res.status(401).json({ error: 'Invalid webhook token' });
  }

  const event = req.body;

  // イベントタイプに応じた処理
  switch (event.type) {
    case 'checkout.session.completed':
      handleCheckoutSessionCompleted(event.data);
      break;
    case 'payment_flow.succeeded':
      handlePaymentFlowSucceeded(event.data);
      break;
    // 他のイベントタイプ...
  }

  // 200ステータスコードを返す
  res.json({ received: true });
});

app.listen(3000);
```

--------------------------------

### Get All Events

Source: https://docs.pay.jp/v2/guide/developers/event-webhook

Use this endpoint to retrieve a list of all events. Replace YOUR_API_KEY with your actual API key.

```curl
curl https://api.pay.jp/v2/events \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Skip 3D Secure Authentication During Card Registration

Source: https://docs.pay.jp/v2/guide/payments/methods/card/3ds

To improve card registration conversion rates, you can skip the 3D Secure authentication step by setting `usage` to `on_session` when creating a Setup Flow API object. Note that the first payment using a card registered this way will still require 3D Secure authentication, necessitating frontend handling of `requires_action`.

```json
{
  "payment_method_data": {
    "type": "card",
    "card": {
      "token": "tok_xxxxxxxxxxxxxxx"
    }
  },
  "usage": "on_session"
}
```

--------------------------------

### Webhook Event Example for Refund Creation

Source: https://docs.pay.jp/v2/guide/status-management/refund

When a refund is created, a `refund.created` event is sent via webhook. This event contains details about the refund, including its ID, status, amount, and associated payment flow.

```json
{
  "type": "refund.created",
  "data": {
    "id": "pyr_xxxxx",
    "status": "succeeded",
    "amount": 1000,
    "payment_flow": "pfw_xxxxx"
  }
}
```

--------------------------------

### Balance Deferral Deadline Example

Source: https://docs.pay.jp/v2/guide/payments-management/balance-deferral-expiration

Illustrates how the deferral deadline is updated when new sales occur. The deadline is extended by one year from the end of the term associated with the new sales statement.

```text
例：2025年1月の売上
├─ Term: 2025/1/1 ~ 2025/2/1
├─ Statement生成: 2025/2/1
└─ 繰延期限: 2026/2/1（Termの終了日から1年後）

その後、2025年6月に新しい売上が発生した場合
├─ Term: 2025/6/1 ~ 2025/7/1
├─ Statement生成: 2025/7/1
└─ 繰延期限更新: 2026/7/1（新しい期限）
```

--------------------------------

### Redirect User to Checkout v2 Payment Page

Source: https://docs.pay.jp/v2/guide/payments/checkout

Client-side form to initiate the checkout process. Submitting this form calls the '/create-checkout-session' endpoint to get the payment URL and redirect the user.

```html
<form action="/create-checkout-session" method="POST">
  <button type="submit">支払う</button>
</form>
```

--------------------------------

### Term Object Example

Source: https://docs.pay.jp/v2/guide/payments-management/settlement-cycles

Represents a settlement period for aggregating sales. It is automatically created at the start of a settlement cycle and associates transactions within its period. The `closed` field indicates if the term has been finalized.

```json
{
  "id": "term_xxx",
  "object": "term",
  "start_at": "2025-01-01T00:00:00Z",
  "end_at": "2025-02-01T00:00:00Z",
  "closed": true,
  .....
}
```

--------------------------------

### Initialize Payments JS and Mount Payment Element (Client-side)

Source: https://docs.pay.jp/v2/guide/status-management/payment-flow-lifecycle

Load the Payments JS library and create a payment element for the user to input their payment details. This requires a `client_secret` obtained from the server.

```javascript
import { loadPayments } from '@payjp/payments-js'

// ページ読み込み時: 決済フォームを表示
const payments = await loadPayments('pk_test_xxxxx')
const elements = payments.elements({ client_secret: clientSecret })
const paymentElement = elements.create('payment')
paymentElement.mount('#payment-element')
```

--------------------------------

### Initialize PAY.JP Payments.js (HTML)

Source: https://docs.pay.jp/v2/guide/payments/setupflow

Load the PAY.JP JavaScript library and initialize it with your public key when using HTML script tags.

```javascript
<script src="https://js.pay.jp/payments.js"></script>
<script>
  const payments = PayjpPayments('pk_test_xxx');
  ...
</script>
```

--------------------------------

### Listen for Webhook Events and Forward

Source: https://docs.pay.jp/v2/guide/developers/payjp-cli

Use this command to receive test mode Webhook events from PAY.JP and forward them to a specified URL. Ensure the events are in test mode.

```bash
payjp-cli listen --forward-to http://localhost:3000/webhooks/payjp
```

--------------------------------

### Initialize Payments Widgets and Mount Form (JavaScript)

Source: https://docs.pay.jp/v2/guide/payments/methods/applepay/implementation

Use the `payments-js` library on the client-side to load Payments Widgets, initialize them with a `client_secret` obtained from the server, and mount the payment form. Apple Pay will only appear if the device and environment support it.

```javascript
import { loadPayments } from '@payjp/payments-js';

// Payment Flow を作成して client_secret を取得
const response = await fetch('/api/create-payment-flow', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ amount: 1000 })
});
const { client_secret } = await response.json();

const payments = await loadPayments('pk_test_xxxxx');
const widgets = payments.widgets({ clientSecret: client_secret });

// Payment Widgets を作成してマウント
const paymentForm = widgets.createForm('payment', {
  paymentMethodOrder: ['card', 'apple_pay']
});

paymentForm.mount('#payment-form');
```

--------------------------------

### Create a Product

Source: https://docs.pay.jp/v2/guide/payments/products-pricing/using-products-prices

Use the Product API to create a new product. The `unit_label` can be set for clearer display on invoices and Checkout.

```curl
curl https://api.pay.jp/v2/products \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tシャツ",
    "description": "オリジナルデザインのTシャツ",
    "unit_label": "枚",
    "active": true
  }'
```

--------------------------------

### Retrieve Payment Transactions by Term ID

Source: https://docs.pay.jp/v2/guide/payments-management/payment-transaction

Get all payment transactions associated with a specific Term ID to review sales for a given settlement cycle.

```Go
package main

import (
	"fmt"

	"github.com/payjp/payjp-go/v2"
	"github.com/payjp/payjp-go/v2/term"
)

func main() {
	// Initialize PAY.JP client
	client := payjp.New("YOUR_SECRET_KEY", nil)

	// Define the Term ID
	termID := "term_xxxxxxxxxxxxxx"

	// Create a filter for payment transactions within the specified Term
	filter := &term.Filter{
		Term: payjp.String(termID),
	}

	// List payment transactions
	resp, err := client.Term.ListPaymentTransactions(filter)
	if err != nil {
		fmt.Printf("Error listing payment transactions: %v\n", err)
		return
	}

	// Process the response
	fmt.Printf("Found %d payment transactions:\n", len(resp.PaymentTransactions))
	for _, pt := range resp.PaymentTransactions {
		fmt.Printf("- ID: %s, Amount: %d, Fee: %d, Type: %s\n", pt.ID, pt.Amount, pt.Fee, pt.Type)
	}
}
```

--------------------------------

### Get Specific Event

Source: https://docs.pay.jp/v2/guide/developers/event-webhook

Use this endpoint to retrieve details for a specific event by its ID. Replace YOUR_API_KEY and evt_xxxxx with your actual API key and event ID.

```curl
curl https://api.pay.jp/v2/events/evt_xxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Login to PAY.JP CLI

Source: https://docs.pay.jp/v2/guide/developers/payjp-cli

Initiate the login process for the payjp-cli tool to authenticate with your PAY.JP account.

```bash
payjp-cli login
```

--------------------------------

### Register PAY.JP CLI for Webhook Listening

Source: https://docs.pay.jp/v2/guide/payments/checkout

Use the PAY.JP CLI to listen for webhooks in local development environments. This forwards webhook events to your local server.

```bash
payjp listen --forward-to http://localhost:3000/webhook/payjp
```

--------------------------------

### Initialize PayjpPayments with Options

Source: https://docs.pay.jp/v2/guide/developers/paymentsjs-reference

Configure the payments object during initialization by passing an options object with parameters like locale.

```javascript
const payments = PayjpPayments('YOUR_PUBLIC_KEY', {
  locale: 'en',
});
```

--------------------------------

### Initialize payments-js and create a payment form

Source: https://docs.pay.jp/v2/guide/status-management/payment-method

Load the payments-js library and initialize it to create a secure payment form on the frontend. This prevents sensitive data from passing through your server.

```html
<script src="https://js.pay.jp/payments.js"></script>
<div id="payment-form"></div>
```

```javascript
import { loadPayments } from '@payjp/payments-js'

const payments = await loadPayments('pk_test_xxxxx')

// サーバーから client_secret を取得
const response = await fetch('/create-payment-flow', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ amount: 5000, currency: 'jpy' })
})
const { client_secret } = await response.json()

// Payment Widgets を作成してマウント
const widgets = payments.widgets({ clientSecret: client_secret })

// 決済フォームを作成・マウント
const paymentForm = widgets.createForm('payment')
paymentForm.mount('#payment-form')

// フォーム送信時に決済を確定
// Payment Method は自動的に作成されます
const result = await widgets.confirmPayment({
  return_url: 'https://your-site.example.com/complete'
})

if (result.error) {
  // エラー処理
  console.error(result.error.message)
}
// 成功時は return_url にリダイレクトされます
```

--------------------------------

### Create a Payment Widget Instance

Source: https://docs.pay.jp/v2/guide/developers/paymentsjs-reference

Create a widget instance using the payments.widgets method, providing a client secret for payment processing.

```javascript
const widgets = payments.widgets({
  clientSecret: 'YOUR_CLIENT_SECRET',
});
```

--------------------------------

### Balance Object Example

Source: https://docs.pay.jp/v2/guide/payments-management/settlement-cycles

Aggregates Statement objects to manage fund transfers and billing status. The `state` field indicates the current status, such as 'collecting', 'transfer', or 'claim'. The `due_date` specifies the expected transfer or claim date. The `closed` field indicates if the balance has been finalized.

```json
{
  "id": "bal_xxx",
  "object": "balance",
  "state": "transfer",
  "closed": false,
  "due_date": "2025-02-28T00:00:00Z",
  "net": 95000,
  "statements": [...],
  .....
}
```

--------------------------------

### Statement Object Example

Source: https://docs.pay.jp/v2/guide/payments-management/settlement-cycles

Represents the financial movements between PAY.JP and merchants. It includes various types such as sales, fees, and transfers. Positive values indicate amounts received by the merchant, while negative values represent amounts paid by the merchant. The `type` field specifies the nature of the transaction.

```json
{
  "id": "st_xxx",
  "object": "statement",
  "type": "sales",
  "net": 95000,
  "term": { "id": "term_xxx" },
  "balance": "bal_xxx",
  .....
}
```

--------------------------------

### Create a Price for a Product

Source: https://docs.pay.jp/v2/guide/payments/products-pricing/using-products-prices

Use the Price API to create a price and associate it with a product. The product ID is a required parameter.

```curl
curl https://api.pay.jp/v2/prices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "jpy",
    "unit_amount": 3000,
    "product": "prod_xxxxx"
  }'
```

--------------------------------

### Create and Confirm Payment Flow (Backend)

Source: https://docs.pay.jp/v2/guide/payments/customer-payment

Use this snippet to create a Payment Flow and confirm the payment simultaneously from your backend. It automatically uses the customer's default payment method if none is specified. Handle success, failure, and actions requiring additional authentication.

```javascript
import { createClient, createPaymentFlow } from '@payjp/payjpv2'

const client = createClient({
  apiKey: process.env.PAYJP_API_KEY!,
})

const { data: paymentFlow, error } = await createPaymentFlow({
  client,
  body: {
    amount: 1000,
    currency: 'jpy',
    customer_id: 'cus_xxxxx',
    confirm: true,
  }
})

if (error) {
  // 決済失敗（カード残高不足、有効期限切れなど）
  console.error('決済に失敗しました:', error)
} else if (paymentFlow.status === 'succeeded') {
  // 決済成功
  console.log('決済が完了しました:', paymentFlow.id)
} else if (paymentFlow.status === 'requires_action') {
  // 追加認証が必要
  console.log('追加認証が必要です:', paymentFlow.next_action)
}
```

--------------------------------

### Create Payment Form with Default Billing Details

Source: https://docs.pay.jp/v2/guide/developers/paymentsjs-reference

Initialize the payment form with pre-filled default values for billing details.

```javascript
const paymentForm = widgets.createForm('payment', {
  defaultValues: {
    billingDetails: {
      name: '山田 太郎',
      email: 'taro@example.com',
    },
  },
});
```

--------------------------------

### Initialize payments.js with Script Tag

Source: https://docs.pay.jp/v2/guide/payments/paymentwidgets

Include the payments.js script in your HTML and initialize it with your public API key. This is one way to prepare the frontend for Payment Widgets.

```html
<script src="https://js.pay.jp/payments.js"></script>
<script>
  const payments = PayjpPayments('YOUR_PUBLIC_KEY');
  ...
</script>
```

--------------------------------

### Initialize Payment Widgets

Source: https://docs.pay.jp/v2/guide/payments/paymentwidgets

Initialize the Payment Widgets with the client_secret obtained from the Payment Flow API. This prepares the widgets for mounting to the DOM.

```javascript
const widgets = payments.widgets({
  clientSecret: "YOUR_PAYMENT_FLOW_CLIENT_SECRET",
});
```

--------------------------------

### Create Checkout Session with Metadata

Source: https://docs.pay.jp/v2/guide/developers/metadata

Set metadata when creating a Checkout Session by providing a JSON object to the `metadata` field.

```shell
curl https://api.pay.jp/v2/checkout/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "success_url": "https://example.com/success", \
    "line_items": [ \
      { \
        "price": "price_xxxxx", \
        "quantity": 1 \
      } \
    ], \
    "mode": "payment", \
    "metadata": { \
      "order_id": "order_12345", \
      "campaign": "summer_sale", \
      "quantity": 3, \
      "is_gift": true \
    } \
  }'
```

--------------------------------

### Listen for Webhooks with a Specific Profile

Source: https://docs.pay.jp/v2/guide/developers/payjp-cli

Receive Webhook events for a specific PAY.JP account by specifying the profile name when using the listen command. This ensures you are receiving events for the correct account.

```bash
payjp-cli listen --profile your-profile-name --forward-to http://localhost:3000/webhooks/payjp
```

--------------------------------

### Create an Inclusive (Tax-Inclusive) Tax Rate

Source: https://docs.pay.jp/v2/guide/payments/products-pricing/taxrate

Define a tax rate that is already included in the price. Set `inclusive` to `true` for tax-inclusive pricing, often used for total price displays.

```bash
curl https://api.pay.jp/v2/tax_rates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "消費税（内税10%）",
    "percentage": 10,
    "inclusive": true
  }'
```

--------------------------------

### Create Payment Flow (Server-side)

Source: https://docs.pay.jp/v2/guide/status-management/payment-flow-lifecycle

Create a Payment Flow object on the server. This requires the amount and currency. The `capture_method` can be set to `manual` to separate authorization and capture.

```typescript
const { data: paymentFlow } = await createPaymentFlow({
  client,
  body: {
    amount: 1000
    // capture_methodはデフォルトで 'automatic' が設定されます
  }
})

// client_secretをフロントエンドに返す
res.json({
  client_secret: paymentFlow.client_secret
})
```

--------------------------------

### Create Payment Form with Tab Layout

Source: https://docs.pay.jp/v2/guide/developers/paymentsjs-reference

Create a payment form with a tab layout and configure billing details and payment method order.

```javascript
const paymentForm = widgets.createForm('payment', {
  layout: 'tab',
  fields: {
    billingDetails: {
      name: 'auto',
      email: 'never',
      phone: 'never',
    },
  },
  paymentMethodOrder: ['card', 'paypay'],
});
paymentForm.mount('#payment-form');
```

--------------------------------

### PAY.JP CLI Authentication Prompt

Source: https://docs.pay.jp/v2/guide/developers/payjp-cli

This output shows the pairing code and authentication URL provided by the payjp-cli during the login process. You will use these to authenticate in your browser.

```text
Your pairing code is: ocean-fancy-smile-glow
To authenticate with PAY.JP, please access to: https://console.pay.jp/payjpcli/auth/confirm?token=payjpcli_auth_XXXXXXXXXXXXXXXXXXXXXXXXX
Waiting for confirmation...
```

--------------------------------

### Confirm Payment (Client-side)

Source: https://docs.pay.jp/v2/guide/status-management/payment-flow-lifecycle

Initiate the payment process using the `confirmPayment` method after the user clicks the submit button. This requires the payment elements and a return URL.

```javascript
document.getElementById('submit-button').addEventListener('click', async (e) => {
  e.preventDefault()

  const result = await payments.confirmPayment({
    elements,
    confirmParams: { return_url: 'https://your-site.example.com/return_url' }
  })
})
```

--------------------------------

### Include payments.js via Script Tag

Source: https://docs.pay.jp/v2/guide/developers/paymentsjs-reference

Add the payments.js script tag to your HTML and initialize the payments object with your public key.

```html
<script src="https://js.pay.jp/payments.js"></script>
<script>
  const payments = PayjpPayments('YOUR_PUBLIC_KEY');
</script>
```

--------------------------------

### Create Refund (Full Refund)

Source: https://docs.pay.jp/v2/guide/status-management/refund

To create a refund, call the Refund API specifying the Payment Flow ID of the payment to be refunded. Omitting the `amount` parameter results in a full refund of the Payment Flow's total amount.

```APIDOC
## Create Refund (Full Refund)

### Description
Creates a full refund for a given payment flow by omitting the `amount` parameter.

### Method
`POST`

### Endpoint
`/v2/payment_refunds`

### Parameters
#### Request Body
- **payment_flow** (string) - Required - The ID of the Payment Flow to refund.

### Request Example
```json
{
  "payment_flow": "pfw_xxxxx"
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the created refund.
- **status** (string) - The status of the refund (e.g., `pending`, `succeeded`).
- **amount** (integer) - The refunded amount.
- **payment_flow** (string) - The ID of the associated Payment Flow.

#### Response Example
```json
{
  "id": "pyr_xxxxx",
  "status": "pending",
  "amount": 1000,
  "payment_flow": "pfw_xxxxx"
}
```
```

--------------------------------

### サーバーサイドで Payment Flow を作成

Source: https://docs.pay.jp/v2/guide/payments/methods/paypay/implementation

加盟店のサイト上で決済フローを管理する場合、サーバーサイドで Payment Flow を作成します。amount と payment_method_types を指定し、レスポンスとして返却される client_secret を取得します。

```typescript
app.post('/api/create-payment-flow', async (req, res) => {
  try {
    const { amount } = req.body

    const { data: paymentFlow } = await createPaymentFlow({
      client,
      body: {
        amount: amount,
        payment_method_types: ['paypay']
      }
    })

    res.json({
      client_secret: paymentFlow.client_secret
    })
  } catch (error) {
    console.error('Payment Flow creation failed:', error)
    res.status(500).json({
      error: 'Payment Flow の作成に失敗しました。'
    })
  }
})
```

--------------------------------

### サーバーサイドで決済ステータス確認エンドポイントを作成

Source: https://docs.pay.jp/v2/guide/payments/methods/paypay/implementation

サーバーに Payment Flow の決済ステータスを取得するエンドポイントを作成します。このエンドポイントは POST リクエストを受け付け、payment_flow_id を使用して決済ステータスを取得し、JSON 形式で返します。

```typescript
app.post('/api/check-payment-status', async (req, res) => {
  try {
    const { payment_flow_id } = req.body

    // Payment Flow のステータスを取得
    const { data: paymentFlow } = await getPaymentFlow({
      client,
      path: { payment_flow_id }
    })

    res.json({
      status: paymentFlow.status
    })
  } catch (error) {
    console.error('Status check failed:', error)
    res.status(500).json({
      error: 'ステータスの確認に失敗しました。'
    })
  }
})
```

--------------------------------

### Mount Payment Form to DOM

Source: https://docs.pay.jp/v2/guide/developers/paymentsjs-reference

Display the created payment form by mounting it to a specified HTML element using a CSS selector or DOM element.

```javascript
paymentForm.mount('#payment-form');
// または
paymentForm.mount(document.getElementById('payment-form'));
```

--------------------------------

### Create Manual Capture Payment Flow

Source: https://docs.pay.jp/v2/guide/status-management/auth-capture

Use this cURL command to create a Payment Flow that requires manual capture. Set `capture_method` to `manual` to disable automatic capture.

```shell
curl https://api.pay.jp/v2/payment_flows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "capture_method": "manual"
  }'
```

--------------------------------

### Checkout v2 で Checkout Session を作成

Source: https://docs.pay.jp/v2/guide/payments/methods/paypay/implementation

Checkout v2 を使用して、PayPay 決済を含む複数の支払い方法に対応する Checkout Session を作成します。このセッションの URL にユーザーをリダイレクトすることで決済が開始されます。

```curl
curl https://api.pay.jp/v2/checkout/sessions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "payment_method_types": ["card"],   
    "payment_method_types": ["card", "paypay"],  
    "line_items": [
      {
        "quantity": 1,
        "price": "price_xxxxx"
      }
    ],
    "mode": "payment",
    "success_url": "https://example.com/success?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://example.com/cancel"
  }'
```

--------------------------------

### Login with a Specific Profile

Source: https://docs.pay.jp/v2/guide/developers/payjp-cli

Log in to the payjp-cli using a specific profile name. This allows you to manage multiple PAY.JP accounts on a single terminal.

```bash
payjp-cli login --profile your-profile-name
```

--------------------------------

### Create an Exclusive (Tax-Exclusive) Tax Rate

Source: https://docs.pay.jp/v2/guide/payments/products-pricing/taxrate

Define a tax rate that is added separately to the price. Set `inclusive` to `false` for standard tax-exclusive pricing.

```bash
curl https://api.pay.jp/v2/tax_rates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "消費税（外税10%）",
    "percentage": 10,
    "inclusive": false
  }'
```

--------------------------------

### Create Payment Flow API

Source: https://docs.pay.jp/v2/guide/payments/paymentwidgets

Use this curl command to create a Payment Flow, specifying amount, currency, and payment method types. This is a backend step to obtain a client_secret.

```curl
curl -X POST https://api.pay.jp/v2/payment_flows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "jpy",
    "payment_method_types": ["card", "paypay", "apple_pay"]
  }'
```

--------------------------------

### Apply Tax Rates to Checkout Session Line Items

Source: https://docs.pay.jp/v2/guide/payments/products-pricing/taxrate

Specify tax rates when creating a Checkout Session by referencing the tax rate IDs in the `tax_rates` field of line items. This ensures taxes are calculated automatically during the payment process.

```bash
curl https://api.pay.jp/v2/checkout/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "success_url": "https://example.com/success",
    "mode": "payment",
    "line_items": [
      {
        "price": "price_xxxxx",
        "quantity": 1,
        "tax_rates": ["txr_xxxxx"]
      }
    ]
  }'
```

--------------------------------

### Create Payment Form and Confirm Payment with Billing Details

Source: https://docs.pay.jp/v2/guide/developers/paymentsjs-reference

Create a payment form where billing details are hidden and provided during payment confirmation.

```javascript
// 加盟店側で取得済みの請求先情報はフォームに表示せず、確定時に渡す
const paymentForm = widgets.createForm('payment', {
  fields: {
    billingDetails: 'never',
  },
});

const result = await widgets.confirmPayment({
  return_url: 'https://example.com/return',
  payment_method_data: {
    billing_details: {
      name: '山田 太郎',
      email: 'taro@example.com',
    },
  },
});
```
Tokens:
Raw