支払い方法の管理

Payment Method (支払い方法)APIAPI を使うと、顧客の決済手段を安全に管理することができます。加盟店側でカード情報などを直接扱うことなく、再利用可能な決済手段として管理できます。

支払い方法とは

Payment MethodAPIは顧客がどのように支払いを行うかを表すオブジェクトで、複数の支払い方法を統一的なインターフェースで管理できます。

支払い方法はCustomerAPI オブジェクトに紐付けることで再利用可能になり、Payment FlowAPI で実際の決済処理を行う際に使用されます。

基本的な使い方

支払い方法を作成する

支払い方法は通常、フロントエンド（ブラウザ）で payments-js を使って作成します。これにより、カード情報などの機密データがサーバーを経由せずに PAY.JP に送信されます。

フロントエンドでの作成（payments-js）

まず、HTML に payments-js を読み込みます。

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

次に、JavaScript で決済処理を実装します。

// payments-js を初期化
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 にリダイレクトされます

支払い方法を顧客に紐付ける

作成した支払い方法を顧客に紐付けることで、その顧客に保存された支払い方法として利用できるようになります。

curl https://api.pay.jp/v2/payment_methods/pm_xxxxx/attach \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "cus_xxxxx"}'

紐付けの制約

支払い方法は1つの顧客にのみ紐付けられます。
1度顧客に紐付いた支払い方法は、別の顧客に紐付けることはできません。
顧客に紐付いた支払い方法は、削除すると以降の決済では使用できず、削除した支払い方法は再度使用することはできません。

保存された支払い方法を使用する

顧客に紐付けられた支払い方法を使って決済を行うには、Payment Flow の作成時に payment_method パラメータを指定します。

server.ts

// 顧客の支払い方法を取得
const { data: paymentMethods } = await getCustomerPaymentMethods({
  client,
  path: { customer_id: 'cus_xxxxx' }
})

// Payment Flow を作成し、保存された支払い方法を指定
const { data: paymentFlow } = await createPaymentFlow({
  client,
  body: {
    amount: 1000,
    customer: 'cus_xxxxx',
    payment_method: paymentMethods.data[0].id   
  }
})

API を使った支払い方法の管理

支払い方法を一覧表示する

顧客が保存している支払い方法を一覧表示できます。

# 特定の顧客の支払い方法一覧を取得
curl https://api.pay.jp/v2/payment_methods?customer_id=cus_xxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

支払い方法を更新する

支払い方法の請求先情報やメタデータを更新できます。

curl https://api.pay.jp/v2/payment_methods/pm_xxxxx \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "billing_details": {
      "email": "new-email@example.com"
    },
    "metadata": {
      "updated_by": "admin"
    }
  }'

支払い方法を削除する

顧客から支払い方法を削除するには detach API を使用します。削除すると以降の決済では使用できなくなります。

curl https://api.pay.jp/v2/payment_methods/pm_xxxxxx/detach \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -X POST