api.yaml

openapi: 3.0.3
info:
  title: STORES Invoice API
  description: Payment with STORES Invoice
  version: 1.0.2
  x-CoineyPayge-Version: 2016-10-25
servers:
- url: /v1
security:
- bearer: []
paths:
  /payments:
    get:
      tags:
      - payment
      description: |
        支払取引の一覧を返します。
      parameters:
      - name: X-CoineyPayge-Version
        in: header
        description: API のマイナーバージョンを指定します。
        schema:
          type: string
      - name: limit
        in: query
        description: |
          返す支払取引の数を指定。
        schema:
          maximum: 100
          minimum: 1
          type: integer
          default: 10
      - name: startingAfter
        in: query
        description: |
          支払取引の一覧を取得する際に、先頭の支払取引の ID を指定します。
          返ってくる一覧は、この ID の次の支払取引からとなります。
          この動きは、次のページを取得したい場合に、前回取得した一覧の最後の ID を
          指定すればよいことになります。
        schema:
          type: string
      - name: endingBefore
        in: query
        description: |
          支払取引の一覧を取得する際に、最後の支払取引の ID を指定します。
          返ってくる一覧は、この ID の前の支払取引からとなります。
          この動きは、前のページを取得したい場合に、前回取得した一覧の最後の ID を
          指定すればよいことになります。
        schema:
          type: string
      responses:
        200:
          description: |
            条件にマッチする支払取引を返します。
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  hasMore:
                    type: boolean
                  totalCount:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
        400:
          description: |
            リクエストパラメータ不正
          headers:
            WWW-Authenticate:
              description: |
                Bearer error="invalid_request"
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        401:
          description: |
            API キーが設定されていない。
            もしくは、不正な API キー
          headers:
            WWW-Authenticate:
              description: |
                Bearer realm="no_api_key" or
                Bearer error="invaid_api_key"
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      tags:
      - payment
      description: |
        支払取引を開始します。
      parameters:
      - name: X-CoineyPayge-Version
        in: header
        description: API のマイナーバージョンを指定します。
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
        required: false
      responses:
        201:
          description: |
            支払い完了
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        400:
          description: |
            リクエストパラメータ不正
          headers:
            WWW-Authenticate:
              description: |
                Bearer error="invalid_request"
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        401:
          description: |
            API キーが設定されていない。
            もしくは、不正な API キー
          headers:
            WWW-Authenticate:
              description: |
                Bearer realm="no_api_key" or
                Bearer error="invaid_api_key"
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      x-codegen-request-body-name: body
  /payments/{PAYMENT_ID}:
    get:
      tags:
      - payment
      description: |
        支払取引の情報を返します。
      parameters:
      - name: X-CoineyPayge-Version
        in: header
        description: API のマイナーバージョンを指定します。
        schema:
          type: string
      - name: PAYMENT_ID
        in: path
        description: 支払取引のID
        required: true
        schema:
          type: string
      responses:
        200:
          description: |
            該当する支払取引を返します。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        400:
          description: |
            リクエストパラメータ不正
          headers:
            WWW-Authenticate:
              description: |
                Bearer error="invalid_request"
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        401:
          description: |
            API キーが設定されていない。
            もしくは、不正な API キー
          headers:
            WWW-Authenticate:
              description: |
                Bearer realm="no_api_key" or
                Bearer error="invaid_api_key"
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        404:
          description: |
            支払取引が見つからない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    patch:
      tags:
      - payment
      description: |
        支払取引の情報を更新します。
      parameters:
      - name: X-CoineyPayge-Version
        in: header
        description: API のマイナーバージョンを指定します。
        schema:
          type: string
      - name: PAYMENT_ID
        in: path
        description: 支払取引のID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePaymentRequest'
        required: false
      responses:
        200:
          description: |
            支払取引の更新完了。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        400:
          description: |
            リクエストパラメータ不正
          headers:
            WWW-Authenticate:
              description: |
                Bearer error="invalid_request"
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        401:
          description: |
            API キーが設定されていない。
            もしくは、不正な API キー
          headers:
            WWW-Authenticate:
              description: |
                Bearer realm="no_api_key" or
                Bearer error="invaid_api_key"
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        404:
          description: |
            支払取引が見つからない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      x-codegen-request-body-name: body
components:
  schemas:
    Payment:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - payment
        mode:
          type: string
          description: |
            本番環境では live、テスト環境では test
          enum:
          - live
          - test
        createdAt:
          type: string
          description: |
            取引の作成日時。ISO 8601 フォーマット
          format: dateTime
        amount:
          type: number
          format: float
        currency:
          type: string
          description: |
            支払に使う通貨。
            ISO 4217 に基づいた 3桁の通貨コードを使います。
          enum:
          - jpy
        locale:
          type: string
          description: |
            STORES 請求書決済の表示言語。
            支払処理前は、支払作成時に設定した表示言語、
            支払処理が行われた場合は、支払時に設定した表示言語となります。
            ISO 639 の言語コード、ISO 3166 の国コードに基づいています。
          enum:
          - ja_JP
          - en_US
          - zh_CN
          - zh_TW
          - ko_KR
          - th_TH
        paidAt:
          type: string
          description: |
            支払処理が完了した日時。ISO 8601 フォーマット
            status が paid or refunded の場合のみ
          format: dateTime
        refundedAt:
          type: string
          description: |
            返金処理が完了した日時。ISO 8601 フォーマット
            status が refunded の場合のみ
          format: dateTime
        validUntil:
          type: string
          description: |
            この支払が有効である日時。ISO 8601 フォーマット
          format: dateTime
        status:
          type: string
          enum:
          - open
          - expired
          - paid
          - refunded
          - cancelled
        subject:
          type: string
          description: |
            STORES 請求書決済 の件名
        remarks:
          type: string
          description: |
            STORES 請求書決済 の備考
        description:
          type: string
          description: |
            STORES 請求書決済に関する内部的なメモ
        metadata:
          type: object
          properties: {}
          description: |
            STORES 請求書決済に関する任意のデータ
            任意の Key/Value が定義できるが、Value は文字列のみ許可
        links:
          type: object
          properties:
            paymentUrl:
              type: string
              description: |
                実際に支払処理する画面へ遷移する URL
                POST `/payment` で作られる
            redirectUrl:
              type: string
              description: |
                支払処理が完了した際に遷移する画面の URL
            cancelUrl:
              type: string
              description: |
                支払処理をキャンセルした際に遷移する画面の URL
            webhookUrl:
              type: string
              description: |
                支払処理中に呼び出す Webhook の URL
    CreatePaymentRequest:
      required:
      - amount
      - currency
      - method
      type: object
      properties:
        amount:
          minimum: 1
          type: number
          description: |
            支払金額
          format: float
        currency:
          type: string
          description: |
            支払に使う通貨を指定します。
            ISO 4217 に基づいた 3桁の通貨コードを使います。
            現状は "JPY" のみ有効です。
          enum:
          - jpy
        locale:
          type: string
          description: |
            STORES 請求書決済の表示言語を指定します。
            指定しない場合は、ブラウザの設定が使われます。
            ISO 639 の言語コード、ISO 3166 の国コードに基づいています。
          enum:
          - ja_JP
          - en_US
          - zh_CN
          - zh_TW
          - ko_KR
          - th_TH
        redirectUrl:
          maxLength: 255
          type: string
          description: |
            支払処理が完了した後に遷移する画面の URL を指定します。
            指定しない場合は STORES 請求書決済の画面が使われます。
        cancelUrl:
          maxLength: 255
          type: string
          description: |
            支払処理をキャンセルした際に遷移する画面の URL を指定します。
            指定しない場合は、ユーザーからのキャンセルができなくなります。
        webhookUrl:
          maxLength: 255
          type: string
          description: |
            この支払でのみ使用する webhook URL を指定します。
            指定しない場合は、アカウントの設定値が使われます。
            アカウントの設定値もない場合は、webhook の通知をしません。
        method:
          type: string
          description: |
            支払に使用する支払方法を指定します。
            通常は、このパラメータを設定せずに使用します。
            パラメータを設定しない場合は、使用できる支払方法から選択する画面が表示されます。
            このパラメータを設定した場合は、支払方法の選択画面を表示せず、直接入力画面へと遷移します。
          enum:
          - creditcard
        subject:
          type: string
          description: |
            STORES 請求書決済の件名
        remarks:
          type: string
          description: |
            STORES 請求書決済の備考
        description:
          type: string
          description: |
            STORES 請求書決済に関する内部的なメモ
        metadata:
          type: object
          properties: {}
          description: |
            STORES 請求書決済に関する任意のデータ
            任意の Key/Value が定義できるが、Value は文字列のみ許可
        expiredOn:
          type: string
          description: |
            支払期限を日付で指定します。
            指定しない場合は、デフォルトで 3ヶ月が設定されます。
          format: date
    UpdatePaymentRequest:
      type: object
      properties:
        expiredOn:
          type: string
          description: |
            支払期限を日付で指定します。
            指定しない場合は、デフォルトで 3ヶ月が設定されます。
          format: date
        description:
          type: string
          description: |
            STORES 請求書決済に関する内部的なメモ
        metadata:
          type: object
          properties: {}
          description: |
            STORES 請求書決済に関する任意のデータ
            任意の Key/Value が定義できるが、Value は文字列のみ許可
    Errors:
      required:
      - type
      type: object
      properties:
        type:
          type: string
          description: エラーの種類
          enum:
          - api_error
          - authentication_error
          - card_error
          - invalid_request_error
        code:
          type: string
          description: エラーコード
        message:
          type: string
          description: エラーの内容
        params:
          type: object
          properties: {}
          description: |
            パラメータに関するエラーの場合に使用する。
            Key としてパラメータ名、Value としてエラーメッセージを含める。
  responses:
    AuthenticationError:
      description: |
        API キーが設定されていない。
        もしくは、不正な API キー
      headers:
        WWW-Authenticate:
          description: |
            Bearer realm="no_api_key" or
            Bearer error="invaid_api_key"
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    InvalidParameter:
      description: |
        リクエストパラメータ不正
      headers:
        WWW-Authenticate:
          description: |
            Bearer error="invalid_request"
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    NotFound:
      description: |
        支払取引が見つからない
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
  parameters:
    payment_id:
      name: PAYMENT_ID
      in: path
      description: 支払取引のID
      required: true
      schema:
        type: string
    x_coiney_version:
      name: X-CoineyPayge-Version
      in: header
      description: API のマイナーバージョンを指定します。
      schema:
        type: string
  securitySchemes:
    bearer:
      type: apiKey
      description: RFC 7235 の Authorization ヘッダを用い、RFC 6750 の Bearer スキームを使用する
      name: Authorization
      in: header