ファイルアップロードガイド

API を使用して Stripe にファイルをアップロードすると、ファイルトークンとファイルに関するその他の情報が返されます。このトークンは、他の API コールに使用できます。このガイドでは、このプロセスの詳細を説明します。

ファイルのアップロード

ファイルをアップロードするには、multipart/form-data リクエストを https://files.stripe.com/v1/files に送信します。サブドメインの files.stripe.com は、Stripe の多くの API エンドポイントとは異なることに注意してください。リクエストで、purpose と file を指定する必要があります。以下の例は、お客様のローカルファイルシステムにあるファイル /path/to/a/file.jpg を、purpose を dispute_evidence としてアップロードします。

curl https://files.stripe.com/v1/files \
  -u 
sk_test_09l3shTSTKHYCzzZZsiLl2vA
: \
  -F "file"="@/path/to/a/file.jpg" \
  -F "purpose"="dispute_evidence"

以下の例は、Stripe の Android SDK を使用し、目的を dispute_evidence としてファイルをアップロードします。

class CheckoutActivity : AppCompatActivity() {
    private val stripe: Stripe by lazy {
        Stripe(this, 
"pk_test_46zswMCbz39W2KAqKj43vDRu")
    }

    private fun uploadFile(file: File) {
        stripe.createFile(
            StripeFileParams(
                file,
                StripeFilePurpose.DisputeEvidence
            ),
            callback = object : ApiResultCallback<StripeFile> {
                override fun onSuccess(result: StripeFile) {
                    // File upload succeeded
                }

                override fun onError(e: Exception) {
                    // File upload failed
                }

            }
        )
    }
}

いくつかの有効な目的値があり、それぞれにファイル形式とサイズの要件があります。

アップロードするファイルの MIME タイプは、そのファイル形式に対応している必要があります。

リクエストが成功すると、File (ファイル) オブジェクトが返されます。

File API リソースを取得する

File の API リソースを取得するには、ファイルアップロード ID を指定して、files.stripe.com サブドメインの /v1/files エンドポイントに対して GET リクエストを実行します。

curl https://files.stripe.com/v1/files/
{{FILE_ID}} \
  -u 
sk_test_09l3shTSTKHYCzzZZsiLl2vA

制限付き API キーを使用する際は、Files リソースへの事前アクセス権を受ける必要があります。

ファイルコンテンツをダウンロードする

ファイルの目的で、ファイルコンテンツのダウンロードが許可されている場合は、File (ファイル) にコンテンツへのアクセス方法を示す null 以外の url フィールドが含まれています。この url は、お客様の Stripe API キーでの認証を必要とします。

curl https://files.stripe.com/v1/files/
{{FILE_ID}}
/contents
  -u 
sk_test_09l3shTSTKHYCzzZZsiLl2vA

目的でダウンロードが許可されている場合に、そのファイルへの未認証のアクセスを許可するには、file_link を作成して匿名のダウンロードリンクを生成します。

curl https://api.stripe.com/v1/file_links \
  -u 
sk_test_09l3shTSTKHYCzzZZsiLl2vA
  -d file=
{{FILE_ID}}

file_link リソースには、ファイルのコンテンツへの未認証アクセスを許可する url フィールドがあります。

ファイルを使用する

ファイルをアップロードしたら、そのファイルアップロード ID を他の API リクエストで使用できます。たとえば、アップロードしたファイルを特定の不審請求の申請に反証資料として関連付けることができます。

curl https://api.stripe.com/v1/disputes/
{{DISPUTE_ID}}
  -u 
sk_test_09l3shTSTKHYCzzZZsiLl2vA
  -d "evidence[receipt]"=
{{FILE_ID}}

アップロードされたファイルは、1 つの API リクエストのみで使用できることに注意してください。

アップロードエラーを処理する

File API を使用して PDF ドキュメントをアップロードすると、一連のチェックが行われ、そのドキュメントが正しくフォーマットされ、PDF 仕様を満たしていることが検証されます。いずれかのチェックに失敗した場合には、アップロードエラーが返されます。

以下を試し、検出されたエラーを修正してください。

• ドキュメントに追加された注釈や追加メディアを削除します。
• 注釈やメディアを削除できない場合、または複数の PDF を 1 つにまとめた場合には、お使いのコンピュータの「PDF に印刷」機能を使用して、新しいドキュメントを作成してください。
  • macOS で PDF に印刷する
  • Adobe Acrobat で PDF に印刷する