コンテンツにスキップ
Docs
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

購入画面の 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(管理画面の表示名は「購入画面を作る」)

次に読むページ

このページは役に立ちましたか?