> ## Documentation Index > Fetch the complete documentation index at: https://docs.zafapay.com/llms.txt > Use this file to discover all available pages before exploring further. # 決済作成 > 新しい決済を作成します ## OpenAPI ````yaml /api-reference/openapi.ja.json post /v1/payments openapi: 3.1.0 info: title: ZAFA PAY API description: 複数のPSPを統合した決済APIプラットフォーム version: 1.0.0 servers: - url: https://api.sandbox.zafapay.com description: Sandbox環境 - url: https://api.zafapay.com description: 本番環境 security: - bearerAuth: [] paths: /v1/payments: post: tags: - Payments summary: 決済作成 description: 新しい決済を作成します operationId: createPayment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePaymentRequest' responses: '201': description: 決済作成成功 content: application/json: schema: $ref: '#/components/schemas/PaymentResponse' '400': description: >- リクエストバリデーションエラー、または決済失敗。バリデーションエラーは `ErrorResponse` 形式、決済失敗（カード拒否、残高不足など）は統一された `PaymentError` を含む `PaymentFailedResponse` 形式で返されます。 content: application/json: schema: oneOf: - $ref: '#/components/schemas/PaymentFailedResponse' - $ref: '#/components/schemas/ErrorResponse' '401': description: 認証エラー content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: 加盟店が無効 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: フローまたは設定が見つからない content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: CreatePaymentRequest: type: object required: - amount - currency properties: amount: type: number description: 決済金額（正の数値、小数点以下2桁まで対応） example: 17.62 currency: type: string description: '3文字の通貨コード（例: usd, sgd, jpy）' example: usd capture_method: type: string enum: - automatic - manual description: キャプチャ方式（省略時はフローの設定に従う） external_id: type: string description: 加盟店側の注文ID example: order_12345 flow_id: type: string description: 使用するフローID（省略時はデフォルトフロー） example: flow_abc123 payment_method: oneOf: - type: string description: 決済方法（depot, card等） example: card - type: object description: 決済方法オブジェクト properties: type: type: string description: 決済タイプ example: card token: type: string description: 決済プロバイダのPaymentMethodトークン example: pmi_xxx description: 決済方法（文字列またはオブジェクト形式） metadata: type: object description: トランザクションに保存する追加データ additionalProperties: true save_card: type: boolean description: trueの場合、カードを将来の継続決済用に保存します example: true payment_method_id: type: string description: 保存済みの決済方法を使用して継続決済を行う（/v1/customers/{id}/payment-methodsから取得） example: pmi_abc123 name: type: string description: カード名義（一部の決済方法では必須） example: 山田 太郎 customer_id: type: string description: 顧客ID（決済方法の保存・取得に使用） example: cust_abc123 email: type: string description: 顧客のメールアドレス example: customer@example.com tel: type: string description: 顧客の電話番号 example: 090-1234-5678 token: type: string description: >- JavaScript SDKで取得したトークンID（`tok_` プレフィックス）。サーバー間決済に使用。トークンは1回のみ使用可能で、30分で有効期限切れとなります。 example: tok_xxxxxxxxxxxxxxxxxxxxxx return_url: type: string description: >- 3Dセキュア認証後に顧客をリダイレクトするURL。`token` パラメータ使用時は必ず指定してください。指定しない場合、3DS後のリダイレクト先がなくなります。 example: https://your-site.com/payment-complete PaymentResponse: type: object properties: id: type: string description: 決済リクエストID example: req_abc123 status: type: string description: ステータス example: pending amount: type: number description: 決済金額 example: 17.62 currency: type: string description: 通貨コード example: usd external_id: type: string nullable: true description: 加盟店側の注文ID example: order_12345 metadata: type: object description: 追加データ（未指定の場合は空オブジェクト） additionalProperties: true example: {} flow_id: type: string description: 使用された決済フローID example: flow_default payment_type: type: string enum: - single - initial - recurring - token description: >- 決済タイプ。`single`: 通常決済、`initial`: カード保存を伴う初回決済、`recurring`: 保存済みカードを使用した継続決済、`token`: トークンを使用したサーバー間決済 example: single payment_url: type: string description: チェックアウトページのURL（署名付き）。ホスト型チェックアウト決済時に返されます。 example: https://pay.sandbox.zafapay.com/checkout/req_abc123?token=xxxxxxxx redirect_url: type: string description: 3Dセキュア認証URL。`status` が `requires_action` の場合に返されます（トークン決済のみ）。 example: https://pay.sandbox.zafapay.com/3ds/req_abc123?token=xxxxxxxx created_at: type: string format: date-time description: 作成日時（ISO 8601形式） example: '2025-01-01T00:00:00.000Z' PaymentFailedResponse: type: object description: 決済失敗時のレスポンスボディ（HTTP 400）。決済失敗理由を説明する統一された PaymentError オブジェクトを含みます。 required: - status - error properties: id: type: string description: 決済リクエストID example: req_abc123 transaction_id: type: string description: トランザクションID example: tx_xyz789 status: type: string enum: - failed example: failed payment_type: type: string enum: - token - recurring - hosted example: token error: $ref: '#/components/schemas/PaymentError' ErrorResponse: type: object properties: error: type: object properties: type: type: string description: エラーの種類 enum: - authentication_error - authorization_error - invalid_request_error - payment_error - rate_limit_error - api_error example: invalid_request_error code: type: string description: エラーコード example: validation_error message: type: string description: エラーメッセージ example: Invalid request parameters param: type: string description: エラーの原因となったパラメータ名 example: amount details: type: array description: バリデーションエラーの詳細 items: type: object properties: path: type: array items: type: string message: type: string request_id: type: string description: リクエストID example: req_abc123xyz789 PaymentError: type: object description: 統一された決済エラー構造。失敗した決済のAPIレスポンスおよび payment.failed マーチャントWebhookで返されます。 required: - code - category - message - recommended_action properties: code: type: string description: >- 統一エラーコード（例: card_declined, insufficient_funds, expired_card）。全コードはエラーコードリファレンスを参照してください。 example: card_declined category: type: string description: >- 処理判断用のエラーカテゴリ。`validation` エラーはマーチャントWebhookを発火しません（400 APIレスポンスのみに表示）。 enum: - authentication - soft_decline - hard_decline - gateway_error - validation example: soft_decline message: type: string description: 人間が読めるエラーメッセージ（エンドユーザー表示用） example: カードが拒否されました recommended_action: type: string description: マーチャントが取るべき推奨アクション enum: - retry - contact_customer - use_different_card - none example: use_different_card securitySchemes: bearerAuth: type: http scheme: bearer description: アクセストークンを使用したBearer認証 ````