コンテンツにスキップ
アカウント作成/サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成サインイン
概要構築済みのシステムをアップグレード
オンライン決済
概要ユースケースを見つけるManaged Payments を使用する
対面決済
決済手段
決済シナリオ
決済以外の機能

メモ

このページはまだ日本語ではご利用いただけません。より多くの言語で文書が閲覧できるように現在取り組んでいます。準備が整い次第、翻訳版を提供いたしますので、もう少しお待ちください。

Boleto 支払い

ブラジルで一般的な支払い方法である Boleto を受け付ける方法をご紹介します。

ブラジルの Stripe ユーザーは、Payment Intents API および Payment Methods API を使用して、ブラジルの顧客から Boleto での支払いを受け付けることができます。顧客は ATM、銀行、オンラインバンクポータル、または公認の代理店のいずれかで、生成された番号が記載された Boleto の支払い票を使用して支払います。

Stripe を設定する
サーバ側

まず、Stripe アカウントが必要です。今すぐ登録してください。

アプリケーションから Stripe API にアクセスするには、Stripe の公式ライブラリを使用します。

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

PaymentIntent を作成する
サーバ側

Stripe は PaymentIntent オブジェクトを使用して、顧客から支払いを回収するお客様の意図を示し、Boleto 支払い票の作成から支払いの完了までの状態の変化を追跡します。

サーバーで金額とbrl通貨を使用して PaymentIntent を作成します (Boleto は他の通貨をサポートしていません)。すでにPayment Intents APIを使用した統合がある場合は、PaymentIntentの決済手段タイプのリストにboletoを追加します。

返される PaymentIntent には client secret が含まれ、これを使用して安全に決済プロセスを完了しなければなりません。後のステップで使用できるように、client secret をクライアントに送り返します。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=brl \
  -d "payment_method_types[]"=boleto

その他の支払い方法オプション

PaymentIntent の決済手段オプションでオプションの expires_after_days パラメータを指定すると、Boleto 支払い票の有効期限が切れるまでの暦日数を設定できます。たとえば、月曜日に Boleto の支払い票を作成し、expires_after_days を 2 に設定した場合、Boleto の支払い票は水曜日のアメリカ/サンパウロ時間 (UTC-3) の 23:59 に有効期限が切れます。0 に設定すると、その日の終わりに Boleto の支払い票の有効期限が切れます。expires_after_days パラメーターは 0 日から 60 日までの範囲で設定できます。既定値は 3 日です。アカウントのデフォルトの有効期限は、決済手段の設定でカスタマイズできます

支払い方法の詳細を収集する
クライアント側

クライアントで支払いフォームを作成し、必要な請求先情報を顧客から収集します。

フィールド値
name顧客の氏名。
email顧客のメールアドレス。
tax_id顧客の CPF (個人の場合) または CNPJ (ビジネスの場合)。CPF は 11 桁で、000.000.000-00 または 00000000000 の形式にする必要があります。CNPJ は 14 桁で、00.000.000/0000-00 または 00000000000000 の形式にする必要があります。
address顧客の住所の町名と番地。
city顧客の住所の市区町村。
state顧客住所のブラジルの 2 文字の州 コード (ISO_3166-2:BR)。
postal_code顧客住所の郵便番号。郵便番号の形式は、XXXXX-XXX または XXXXXXXX にする必要があります。

メモ

name、address、city のフィールドには、基本ラテン文字 (ASCII) ユニコードブロックの英数字を 1 文字以上含める必要があります。

checkout.html
<form id="payment-form">
  <div class="form-row">
    <label for="name">
      Name
    </label>
    <input id="name" name="name" required>
  </div>

  <div class="form-row">
    <label for="tax_id">
      CPF/CNPJ
    </label>
    <input id="tax_id" name="tax_id" required>
  </div>

  <div class="form-row">
    <label for="email">
      Email
    </label>
    <input id="email" name="email" required>
  </div>

  <div class="form-row">
    <label for="address">
      Address
    </label>
    <input id="address" name="address" required>
  </div>

  <div class="form-row">
    <label for="city">
      City
    </label>
    <input id="city" name="city" required>
  </div>

  <div class="form-row">
    <label for="state">
      State
    </label>
    <input id="state" name="state" required>
  </div>

  <div class="form-row">
    <label for="postal_code">
      Postal Code
    </label>
    <input id="postal_code" name="postal_code" required>
  </div>

  <!-- Used to display form errors. -->
  <div id="error-message" role="alert"></div>

  <button id="submit-button">Pay with Boleto</button>
</form>

Stripe に支払いを送信する
クライアント側

顧客が Boleto による決済をクリックしたら、Stripe.js を使用してその支払いを Stripe に送信します。Stripe.js は、支払いフローを構築するための Stripe の基本的な JavaScript ライブラリです。

Stripe.js スクリプトを決済ページに含めるには、このスクリプトを HTML ファイルの head に追加します。

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

決済ページで以下の JavaScript を使用して、Stripe.js のインスタンスを作成します。

client.js
// Set your publishable key. Remember to switch to your live publishable key in production!
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
);

stripe.confirmBoletoPayment と、ステップ 2 で作成した PaymentIntent オブジェクトの client secret を使用して、顧客の請求先情報を送信します。

確定されると、Stripe はモーダルを自動的に開き、顧客に Boleto の取引詳細を表示します。

client.js
var form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const result = await stripe.confirmBoletoPayment(
    '{{PAYMENT_INTENT_CLIENT_SECRET}}',
    {
      payment_method: {
        boleto: {
          tax_id: document.getElementById('tax_id').value,
        },
        billing_details: {
          name: document.getElementById('name').value,
          email: document.getElementById('email').value,
          address: {
            line1: document.getElementById('address').value,
            city: document.getElementById('city').value,
            state: document.getElementById('state').value,
            postal_code: document.getElementById('postal_code').value,
            country: 'BR',
          },
        },
      },
    }
  );
  // Stripe.js will open a modal to display the Boleto voucher to your customer
  // This async function finishes when the customer closes the modal

  if (result.error) {
    // Display error to your customer
    const errorMsg = document.getElementById('error-message');
    errorMsg.innerText = result.error.message;
  }
});

メモ

stripe.confirmBoletoPayment の完了には数秒かかる場合があります。この間、フォームが再送信されないように無効化し、スピナーのような待機中のインジケータを表示します。エラーが発生した場合は、それを顧客に表示し、フォームを再度有効化し、待機中のインジケータを非表示にします。

Boleto の取引の詳細が正常に作成されると、返された PaymentIntent の status プロパティの値が requires_action になります。ダッシュボードまたはオブジェクトのステータスプロパティを調べて、PaymentIntent のステータスを確認します。Boleto の取引の詳細が正常に作成されなかった場合は、返された error を調べて原因を特定します (メールアドレス形式が無効であるなど)。

オプション: 顧客に取引の詳細へのリンクをメールで送信する

Stripe は、Boleto の支払い票が正常に作成されると、payment_intent.requires_action イベントを送信します。顧客に取引の詳細へのリンクをメールで送信する必要がある場合は、payment_intent.next_action.boleto_display_details の hosted_voucher_url に記載されています。

オプション: 取引の詳細をカスタマイズする

Stripe では、ブランディング設定ページで、顧客に表示される UI をカスタマイズできます。

取引の詳細には、以下のブランド設定を適用できます。

  • アイコン: ブランド画像と公開ビジネス名
  • アクセント— 番号コピーボタンのカラーとして使用されます
  • ブランドカラー: 背景色として使用されます

支払い後のイベントを処理する
サーバ側

Boleto による支払いは非同期型であるため、売上はすぐには利用可能になりません。決済後、顧客が直ちに Boleto の支払いを行わないことがあります。

Stripe は、支払われた Boleto の支払い票ごとに、翌営業日 (ブラジルの祝日を除く月曜日から金曜日) に payment_intent.succeeded イベントを送信します。ダッシュボードまたはカスタム webhook を使用して、これらのイベントを受信し、アクションを実行します (顧客への注文確認メールの送信、データベースへの販売の記録、配送ワークフローの開始、など)。

Boleto が有効期限日のアメリカ/サンパウロ時間の 23:59 (UTC-3) までに支払われなかった場合、Stripe は 1 営業日後に payment_intent.payment_failed イベントを送信します。たとえば、Boleto の有効期限が木曜日に切れた場合、イベントは金曜日に送信されます。Boleto の有効期限が金曜日に切れた場合、イベントは次の月曜日に送信されます。

イベント説明次のステップ
payment_intent.succeeded顧客が有効期限前に Boleto の支払いを行いました。顧客が購入した商品またはサービスのフルフィルメントを行います。
payment_intent.payment_failed顧客が有効期限までに Boleto の支払いを行いませんでした。顧客にメールまたはプッシュ通知で連絡し、別の決済手段をリクエストします。

組み込みをテストする

サンドボックスで、stripe.confirmBoletoPayment を呼び出すときに payment_method.billing_details.email に次の値を設定して、さまざまなシナリオをテストします。

メールアドレス説明

{any_prefix}@{any_domain}

顧客が 3 分後に支払い、約 3 分後に payment_intent.succeeded Webhook を受信する Boleto の支払いをシミュレーションします。本番環境では、1 営業日後にこの Webhook が届きます。

例: fulaninho@example.com

{any_prefix}succeed_immediately@{any_domain}

顧客が即座に支払い、数秒以内に payment_intent.succeeded Webhook を受信する Boleto の支払い方法をシミュレーションします。本番環境では、1 営業日後にこの Webhook が届きます。

例: succeed_immediately@example.com

{any_prefix}expire_immediately@{any_domain}

顧客が支払う前に期限切れになり、数秒以内に payment_intent.payment_failed Webhook を受信する Boleto の支払いをシミュレーションします。

決済手段オプションで expires_after_days パラメータに設定された値に関係なく、next_action.boleto_display_details の expires_at フィールドには、現在時刻が設定されます。

例: expire_immediately@example.com

{any_prefix}expire_with_delay@{any_domain}

顧客が支払う前に期限切れになり、約 3 分後に payment_intent.payment_failed Webhook を受信する Boleto の支払いをシミュレーションします。

決済手段オプションで expires_after_days パラメータに設定された値に関係なく、next_action.boleto_display_details の expires_at フィールドが 3 分後に設定されます。

例: expire_with_delay@example.com

{any_prefix}fill_never@{any_domain}

成功することなく、決済手段オプションで指定されたパラメータに基づき、next_action.boleto_display_details の expires_at フィールドに従って有効期限が切れ、その後 payment_intent.payment_failed Webhook を受け取る Boleto 支払い票をシミュレートします。

例: fill_never@example.com

納税者番号説明

CPF 000.000.000-00

CNPJ 00.000.000/0000-00

サンドボックスで、tax_id にこれらの値を設定し、納税者番号の検証を回避します。

オプション独自に取引の詳細ページを構築する
クライアント側

confirmBoletoPayment で Boleto の取引詳細の表示を処理するには、Stripe.js を利用することをお勧めします。ただし、取引詳細を手動で顧客に表示することもできます。

ステップ 4 で stripe.confirmBoletoPayment を呼び出す際に handleActions: false を指定して、顧客に Boleto の詳細を表示するための次のアクションをお客様が処理するように指定できます。

client.js
var form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const result = await stripe.confirmBoletoPayment(
    '{{PAYMENT_INTENT_CLIENT_SECRET}}',
    {
      payment_method: {
        boleto: {
          tax_id: document.getElementById('tax_id').value,
        },
        billing_details: {
          name: document.getElementById('name').value,
          email: document.getElementById('email').value,
          address: {
            line1: document.getElementById('address').value,
            city: document.getElementById('city').value,
            state: document.getElementById('state').value,
            postal_code: document.getElementById('postal_code').value,
            country: 'BR',
          },
        },
      },
    }, {handleActions: false},
  );
  if (result.error) {
    // Display error to your customer
    const errorMsg = document.getElementById('error-message');
    errorMsg.innerText = result.error.message;
  } else {
    // An Boleto voucher was successfully created
    const amount = result.paymentIntent.amount;
    const currency = result.paymentIntent.currency;

    const details = result.paymentIntent.next_action.boleto_display_details;
    const number = details.number;
    const expires_at = details.expires_at;

    // Handle the next action by displaying the Boleto details to your customer

    // You can also use the generated hosted voucher
    const hosted_voucher_url = details.hosted_voucher_url;
  }
});

少なくとも、以下を含めます。

詳細説明
番号Boleto の番号は、顧客が簡単にクリップボードにコピーできるようにして表示します。next_action.boleto_display_details.number にある PaymentIntent オブジェクトの番号を見つけます。
有効期限Boleto 支払い票の有効期限を表示します。next_action.boleto_display_details.expires_at の PaymentIntent で Boleto 支払い票が期限切れになる UNIX タイムスタンプを見つけます。
PDF をダウンロードするダウンロードボタンを表示して、顧客が Boleto の PDF をダウンロードできるようにします。顧客が Boleto の取引詳細の PDF をダウンロードできる場所は、next_action.boleto_display_details.pdf の PaymentIntent にあります。

オプションサーバ側で Payment Intent を確定する
サーバ側

confirmBoletoPayment で Boleto の Payment Intent を確定するには、Stripe.js を使用することをお勧めします。Stripe.js を使用することで、組み込みを他の支払い方法に容易に拡張できます。ただし、サーバー側で以下のようにして Payment Intent を確定することもできます。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=brl \
  -d confirm=true \
  -d "payment_method_types[]"=boleto \
  -d "payment_method_data[type]"=boleto \
  -d "payment_method_data[billing_details][name]"="João da Silva" \
  --data-urlencode "payment_method_data[billing_details][email]"="joao@exemplo.com" \
  -d "payment_method_data[billing_details][address][line1]"="1234 Av. Paulista" \
  -d "payment_method_data[billing_details][address][city]"="São Paulo" \
  -d "payment_method_data[billing_details][address][state]"=SP \
  -d "payment_method_data[billing_details][address][postal_code]"=01310-000 \
  -d "payment_method_data[billing_details][address][country]"=BR \
  -d "payment_method_data[boleto][tax_id]"="000.000.000-00"

オプション支払い手順メールを送信する

ダッシュボードのメール設定ページで Boleto 決済の手順のメールを有効にできます。有効にすると、Stripe は、PaymentIntent の確定時に支払い手順のメールを送信します。メールには、Boleto 番号と Stripe の店舗支払いページへのリンクが含まれます。

メモ

テスト環境では、手順メールは Stripe アカウントに関連付けられたメールアドレスにのみ送信されます。

有効期限とキャンセル

Boleto バウチャーは expires_at UNIX タイムスタンプを過ぎると期限切れになり、顧客は有効期限が切れた Boleto バウチャーの支払いはできません。有効期限前に Boleto バウチャーをキャンセルすることはできません。

Boleto の有効期限が切れると、PaymentIntent のステータスは requires_payment_method に変わります。この時点では、別の支払い方法を指定して PaymentIntent を確定するか、キャンセルすることができます。