> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Chargeback file upload

> Upload an evidence file and obtain the fileId used by the Chargeback update API. Send the request as multipart/form-data with two parts: meta (the file metadata as a JSON string) and file (the file binary). X-SIGNATURE is the signature of the meta string only; the file is not signed and is bound to the signature through meta.sha256. Note: serialize meta once, sign that string, and send the same string unchanged as the meta part. Re-serializing, pretty-printing or appending a newline after signing makes the signature check fail. The response carries no X-SIGNATURE.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/chargeback/file/upload
openapi: 3.1.0
info:
  title: acquiring-order
  description: 接口文档
  termsOfService: https://www.waffo.com
  version: 1.0.0
servers:
  - url: https://waffo.com
    description: Sandbox API (auto-signed via waffo.com signing proxy)
security: []
tags:
  - name: VCC account inquiry
    description: Query VCC accounts.
  - name: VCC card create
    description: Create a VCC card.
  - name: Subscription inquiry
    description: Subscription inquiry api description
  - name: Subscription manage
    description: >
      This API allows the merchant to request a subscription management URL from
      Waffo

      Waffo will generate a subscription management URL which merchant can
      redirect user to this URL for managing subscription details (e.g. view
      subscription detail and cancel subscription). This management URL has a
      fixed expiration time (e.g., 1 day).
  - name: Subscription change inquiry
    description: >
      This API allows merchants to query the status of a subscription change
      (upgrade/downgrade) request.

      此接口允许商户查询订阅升降级请求的状态。
  - name: Cashier Waffo token config
    description: Cashier Waffo token config api description
  - name: Subscription resume
    description: >
      Revoke a scheduled cancellation before it takes effect, so that the
      subscription keeps renewing. The next billing date stays unchanged.
  - name: Subscription update
    description: ' Subscription update api description'
  - name: Payment session update
    description: Payment session update api description
  - name: VCC funding order inquiry
    description: Query a VCC funding order.
  - name: VCC Secure Fetch session generation
    description: Generate a VCC Secure Fetch session for PCI DSS-validated merchants.
  - name: VCC card update
    description: Update VCC card status or limits.
  - name: Payout beneficiary fields inquiry
    description: Payout beneficiary fields inquiry api description
  - name: Order inquiry
    description: Order inquiry api description
  - name: Payout inquiry
    description: Payout inquiry api description
  - name: Order create
    description: ' Order create api description'
  - name: Pay Method Config Inquiry
    description: Pay Method Config Inquiry api description
  - name: Payment session create
    description: Payment session create api description
  - name: Order cancel
    description: Order cancel api description
  - name: VCC funding refund
    description: Submit a VCC account funding refund request.
  - name: Order capture
    description: Order capture api description
  - name: Subscription session create
    description: Subscription session create api description
  - name: Chargeback list
    description: Chargeback list api description
  - name: Payout create
    description: Payout create api description
  - name: Subscription session update
    description: Subscription session update api description
  - name: Chargeback file download
    description: Chargeback file download api description
  - name: VCC transaction list
    description: List VCC card transactions.
  - name: VCC card terminate
    description: Terminate a VCC card.
  - name: VCC funding top-up
    description: Submit a VCC account top-up request.
  - name: Subscription change
    description: >
      This API allows merchants to upgrade or downgrade a user's subscription
      plan. The change request will create a new subscription based on the
      original subscription, applying any remaining amount from the original
      subscription.


      此接口允许商户升级或降级用户的订阅计划。升降级请求将基于原订阅创建新订阅，并将原订阅的剩余金额应用到新订阅中。
  - name: Chargeback accept
    description: Chargeback accept api description
  - name: VCC account create
    description: Create a VCC account.
  - name: Chargeback file upload
    description: Chargeback file upload api description
  - name: Chargeback update
    description: Chargeback update api description
  - name: VCC funding order list
    description: List VCC funding orders.
  - name: VCC non-sensitive card details inquiry
    description: Query non-sensitive VCC card details and limits.
  - name: VCC card widget session generation
    description: Generate a VCC card display session.
  - name: Wallet inquiry
    description: Wallet inquiry api description
  - name: VCC card list
    description: List VCC cards.
  - name: Order refund
    description: Order refund api description
  - name: Refund inquiry
    description: Refund inquiry api description
  - name: Subscription cancel
    description: >
      Cancel an active subscription when the merchant no longer wishes to
      continue the recurring billing cycle. This endpoint can only be invoked
      when the subscription status is active
  - name: Merchant config inquiry
    description: Merchant config inquiry api description
  - name: Chargeback inquiry
    description: Chargeback inquiry api description
  - name: Subscription create
    description: Subscription create api description
  - name: Reported Fraud list
    description: Reported Fraud list api description
paths:
  /api/v1/chargeback/file/upload:
    post:
      tags:
        - Chargeback file upload
        - 收单争议文件api接口
      summary: Chargeback file upload
      description: >-
        Upload an evidence file and obtain the fileId used by the Chargeback
        update API. Send the request as multipart/form-data with two parts: meta
        (the file metadata as a JSON string) and file (the file binary).
        X-SIGNATURE is the signature of the meta string only; the file is not
        signed and is bound to the signature through meta.sha256. Note:
        serialize meta once, sign that string, and send the same string
        unchanged as the meta part. Re-serializing, pretty-printing or appending
        a newline after signing makes the signature check fail. The response
        carries no X-SIGNATURE.
      operationId: chargebackFileUpload
      parameters:
        - name: X-API-KEY
          in: header
          description: >-
            API key assigned by Waffo. The key must be allowed to call the
            Chargeback update API
          required: true
          schema:
            type: string
        - name: X-SIGNATURE
          in: header
          description: >-
            Signature of the meta string: sign its UTF-8 bytes with your RSA
            private key using SHA256withRSA, then Base64-encode the result. Same
            key pair and algorithm as the other APIs
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ChargebackFileUploadForm'
            encoding:
              meta:
                contentType: text/plain
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ResponseChargebackFileUploadResponse'
components:
  schemas:
    ChargebackFileUploadForm:
      type: object
      description: multipart/form-data request of the Chargeback file upload API
      properties:
        meta:
          $ref: '#/components/schemas/ChargebackFileUploadMeta'
          description: >-
            File metadata as a JSON string. X-SIGNATURE is computed over this
            string, so send it exactly as signed
        file:
          type: string
          format: binary
          description: >-
            The binary data of the evidence file. Supported formats: JPG, JPEG,
            PNG and PDF. Maximum size: 10 MB
      required:
        - file
        - meta
    ResponseChargebackFileUploadResponse:
      type: object
      description: response data
      properties:
        code:
          type: string
          example: 0
        msg:
          type: string
          example: success
        data:
          $ref: '#/components/schemas/ChargebackFileUploadResponse'
    ChargebackFileUploadMeta:
      type: object
      description: File metadata. X-SIGNATURE is computed over the raw string of this part
      properties:
        merchantId:
          type: string
          description: >-
            Merchant Id assigned by Waffo. Must match the merchant bound to the
            API key
          example: 1000000201
        filename:
          type: string
          description: >-
            File name, used in the returned fileId. 1-128 characters, must not
            contain ',', '\', '/' or control characters. The extension must be
            jpg, jpeg, png or pdf and must match the file content
          example: receipt.pdf
        sha256:
          type: string
          description: >-
            SHA-256 of the file content, 64 hex characters (case-insensitive).
            The server recomputes it from the uploaded file and rejects the
            request if it does not match
          example: <64-hex-sha256-of-your-file>
        timestamp:
          type: integer
          format: int64
          description: >-
            Unix timestamp in seconds, not milliseconds. Must be within 5
            minutes of the server time
          example: 1791853200
      required:
        - filename
        - merchantId
        - sha256
        - timestamp
    ChargebackFileUploadResponse:
      type: object
      description: Chargeback file upload response
      properties:
        fileId:
          type: string
          description: >-
            The unique ID of the file, e.g. 1766043193910/receipt.pdf. It
            contains a slash, so URL-encode it when passing it as a query
            parameter
          example: 1766043193910/receipt.pdf
          minLength: 1
      required:
        - fileId

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.