購入画面の API
メールアドレスを固定した購入画面を、サーバーから作る。
購入画面の API はアプリのサーバーから購入画面の URL を作ります。購入画面のメールアドレスはアプリにログインしている人のものに固定されます。機能フラグの商品を売るときに使い、購入者限定ページの商品でも使えます。
使いどころ
- 機能フラグの商品を、アプリにログインしている人のメールアドレスで買ってもらうとき。
- 購入者限定ページの商品でも、同じようにメールアドレスを固定して売れます。
- 購入画面のメールアドレスは変更できません。そのため、購入の記録のメールアドレスと、機能フラグの照会で使うメールアドレスが一致します。
公開の 購入リンク でも購入できますが、サーバーで購入画面を作る方法を勧めます。
商品IDを確かめる
購入画面を作るには、商品ID(prd_ で始まる値)が要ります。
- 購入者限定ページの商品:管理画面の商品詳細にある「プロダクトID」タブで確かめます。
- 機能フラグの商品:商品詳細には「プロダクトID」タブがありません。商品詳細の「アプリとつなぐ」にある組み込みプロンプトに、商品IDが書かれています。
- 外部 API:商品一覧(
GET /products)のidが商品IDです。スコープはproducts:readです。
作り方
購入画面を作る
アプリのサーバーで、商品IDとログイン中のメールアドレスを渡して、購入画面を作ります。
URL を本人に渡す
返った URL を本人に渡します。URL は30分で失効します。
失効したら作り直す
失効したら、もう一度作り直します。
失効した URL をお客様が開くと、購入画面には「購入画面の有効期限が切れました」と表示され、支払いに進めません。カードの認証などで購入画面の外へ移ったあと、決済に失敗して戻ったときも、お客様には「お支払いを確認できませんでした」と表示され、同じ URL ではやり直せません。購入画面の中でカードが拒否されたときは、そのまま別のカードで支払えます。どちらの画面にもボタンは無く、アプリに戻ってもう一度進むよう案内が出ます。アプリのサーバーで購入画面を作り直してください。
SDK(@nulogic/cozeni-sdk/next)では createCheckout() を使います。
import { createCheckout } from "@nulogic/cozeni-sdk/next";
const PRODUCT_ID = "prd_...";
export async function POST() {
// アプリのログイン情報から取る
const email = await loginEmail(); // アプリ側のログイン処理に置き換える
const { url, expiresAt } = await createCheckout({
productId: PRODUCT_ID,
email,
});
// expiresAt は作成から30分後
return Response.redirect(url, 303);
}
createCheckout() は checkoutId・url・expiresAt を返します。url は Cozeni の購入画面の URL で、購入の試行を指す値を含みます。メールアドレスは URL に含まれません。
メールアドレスは前後の空白を除いて小文字に揃えて保存されます。
API で作る場合は、POST /checkout/sessions に product_id と email を送ります。仕様は 購入画面を作成 を参照してください。
失敗したとき
失敗は CozeniError として投げられます。code で分岐できます。
code |
HTTP | 意味 | 扱い |
|---|---|---|---|
already_purchased |
409 | そのメールアドレスで購入済み | 購入画面へ進めず、購入済みとして扱う |
creator_not_ready |
409 | 販売の準備が整っていない | 売上の受け取り を確認する |
product_archived |
410 | 商品がアーカイブ済み | 商品の状態を確認する |
checkout_link_disabled |
410 | 商品の購入リンクが無効 | 管理画面で状態を確認する |
product_not_found |
404 | 商品がない、他の販売者の商品、または標準の購入リンクが無い商品 | 商品IDを確認する |
sandbox_recipient_not_allowed |
422 | サンドボックスで、管理画面のサインインに使うメールアドレス以外を指定した | 管理画面のサインインに使うメールアドレスで試す |
rate_limited |
429 | 呼び出し回数の上限を超えた | Retry-After の秒数をおいてから再試行する |
必要なスコープ
checkouts:write(管理画面の表示名は「購入画面を作る」)