openapi: 3.0.3
info:
  title: Paidy Payments Tokens API
  description: 'Paidy is a Japanese buy now, pay later (BNPL) and digital payment service that enables Japanese consumers to make purchases and pay later via monthly consolidated billing. Merchants integrate Paidy Checkout (JavaScript) and the Paidy REST API to accept deferred payments, manage authorizations, capture funds, issue refunds, and handle recurring payments via stored tokens.

    '
  version: '2018-04-10'
  contact:
    name: Paidy Developer Support
    url: https://paidy.com/merchant/
  termsOfService: https://paidy.com/merchant/
  license:
    name: Proprietary
    url: https://paidy.com/merchant/
servers:
- url: https://api.paidy.com
  description: Production server
security:
- BearerAuth: []
tags:
- name: Tokens
  description: Manage recurring payment tokens for subscription billing.
paths:
  /tokens/:
    get:
      tags:
      - Tokens
      summary: Retrieve all tokens
      description: 'Retrieves all tokens associated with the merchant. Returns only tokens with "active" or "suspended" status (not deleted tokens).

        '
      operationId: listTokens
      parameters:
      - $ref: '#/components/parameters/PaidyVersion'
      responses:
        '200':
          description: List of tokens retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Token'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /tokens/{id}:
    get:
      tags:
      - Tokens
      summary: Retrieve a token
      description: Retrieves a specific token by its unique ID.
      operationId: getToken
      parameters:
      - $ref: '#/components/parameters/TokenId'
      - $ref: '#/components/parameters/PaidyVersion'
      responses:
        '200':
          description: Token retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /tokens/{id}/suspend:
    post:
      tags:
      - Tokens
      summary: Suspend a token
      description: 'Suspends an active token, preventing it from being used for new payments. The token status changes to "suspended".

        '
      operationId: suspendToken
      parameters:
      - $ref: '#/components/parameters/TokenId'
      - $ref: '#/components/parameters/PaidyVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenActionRequest'
            example:
              wallet_id: default
              reason:
                code: merchant.requested
                description: Pausing subscription at merchant request
      responses:
        '200':
          description: Token suspended successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Token not found or deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /tokens/{id}/resume:
    post:
      tags:
      - Tokens
      summary: Resume a token
      description: 'Resumes a suspended token, allowing it to be used for payments again. The token status changes to "active".

        '
      operationId: resumeToken
      parameters:
      - $ref: '#/components/parameters/TokenId'
      - $ref: '#/components/parameters/PaidyVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenActionRequest'
            example:
              wallet_id: default
              reason:
                code: merchant.requested
                description: Resuming subscription
      responses:
        '200':
          description: Token resumed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Token not found or deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /tokens/{id}/delete:
    post:
      tags:
      - Tokens
      summary: Delete a token
      description: 'Permanently deletes a token. Deleted tokens cannot be recovered. The token status changes to "deleted" and the deleted_at timestamp is populated.

        '
      operationId: deleteToken
      parameters:
      - $ref: '#/components/parameters/TokenId'
      - $ref: '#/components/parameters/PaidyVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenDeleteRequest'
            example:
              wallet_id: default
              reason:
                code: consumer.requested
                description: Consumer requested cancellation
      responses:
        '200':
          description: Token deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Token not found or already deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Suspension:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when suspension occurred
          example: '2026-06-13T00:00:00Z'
        authority:
          type: string
          description: Entity that performed the suspension
          example: merchant
    TokenReason:
      type: object
      required:
      - code
      - description
      properties:
        code:
          type: string
          description: Reason code for token suspension or resumption
          enum:
          - consumer.requested
          - merchant.requested
          - fraud.suspected
          - general
          example: merchant.requested
        description:
          type: string
          description: Explanation for the action
          example: Pausing subscription at merchant request
    Metadata:
      type: object
      description: Key-value map for arbitrary data; maximum 20 keys
      additionalProperties:
        type: string
      maxProperties: 20
      example:
        custom_field: value
    Address:
      type: object
      properties:
        line1:
          type: string
          description: Building or apartment information
          example: Shibuya 1-1
        line2:
          type: string
          description: District or land details
          example: Apartment 301
        city:
          type: string
          description: Municipality name
          example: Tokyo
        state:
          type: string
          description: Prefecture name
          example: Tokyo
        zip:
          type: string
          description: Postal code in format NNN-NNNN; required with at least one other field
          example: 150-0001
    TokenDeleteReason:
      type: object
      required:
      - code
      - description
      properties:
        code:
          type: string
          description: Reason code for token deletion
          enum:
          - consumer.requested
          - subscription.expired
          - merchant.requested
          - fraud.detected
          - general
          example: consumer.requested
        description:
          type: string
          description: Explanation for the deletion
          example: Consumer requested cancellation
    TokenDeleteRequest:
      type: object
      required:
      - reason
      properties:
        wallet_id:
          type: string
          description: Merchant wallet identifier; defaults to "default"
          example: default
        reason:
          $ref: '#/components/schemas/TokenDeleteReason'
    ConsumerOrigin:
      type: object
      properties:
        name:
          type: string
          description: Consumer name
          example: Taro Yamada
        email:
          type: string
          format: email
          description: Consumer email address
          example: taro@example.com
        phone:
          type: string
          description: Consumer phone number
          example: 090-1234-5678
        address:
          $ref: '#/components/schemas/Address'
    TokenActionRequest:
      type: object
      required:
      - reason
      properties:
        wallet_id:
          type: string
          description: Merchant wallet identifier; defaults to "default"
          example: default
        reason:
          $ref: '#/components/schemas/TokenReason'
    Token:
      type: object
      properties:
        id:
          type: string
          description: Unique token ID (begins with `tok_`)
          example: tok_example123456
        merchant_id:
          type: string
          description: Paidy-assigned merchant ID (begins with `mer_`)
          example: mer_example123456
        wallet_id:
          type: string
          description: Grouping identifier for tokens; defaults to "default"
          example: default
        status:
          type: string
          description: Current token status
          enum:
          - active
          - suspended
          - deleted
          example: active
        origin:
          $ref: '#/components/schemas/ConsumerOrigin'
        description:
          type: string
          description: Merchant-provided token description
          example: Monthly plan token
        kind:
          type: string
          description: Token type; always "recurring"
          example: recurring
        metadata:
          $ref: '#/components/schemas/Metadata'
        consumer_id:
          type: string
          description: Paidy-generated consumer ID (begins with `con_`)
          example: con_example123456
        suspensions:
          type: array
          description: Suspension history records
          items:
            $ref: '#/components/schemas/Suspension'
        test:
          type: boolean
          description: Indicates if this is a test token
          example: false
        version_nr:
          type: number
          description: Increments with each update
          example: 1
        created_at:
          type: string
          format: date-time
          description: ISO 8601 creation timestamp
          example: '2026-06-13T00:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 last update timestamp
          example: '2026-06-13T00:00:00Z'
        activated_at:
          type: string
          format: date-time
          description: ISO 8601 activation timestamp
          example: '2026-06-13T00:00:00Z'
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: ISO 8601 deletion timestamp; null if not deleted
          example: null
    Error:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 400
        code:
          type: string
          description: Paidy error code
          example: request_content.malformed
        message:
          type: string
          description: Human-readable error description
          example: Missing or incorrectly formatted required fields
  parameters:
    PaidyVersion:
      name: Paidy-Version
      in: header
      required: false
      description: API version date. Recommended value is 2018-04-10.
      schema:
        type: string
        example: '2018-04-10'
    TokenId:
      name: id
      in: path
      required: true
      description: Unique token ID (begins with `tok_`)
      schema:
        type: string
        example: tok_example123456
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Use your Paidy secret key (prefixed with `sk_`) as the bearer token. Never share your secret key. Use test keys for sandbox testing.

        '
externalDocs:
  description: Paidy API Reference
  url: https://paidy.com/docs/api/en/