openapi: 3.2.0
info:
  title: Ppro Internal API
  version: v1
  description: 'Operations tagged Internal across 2 of this provider''s published API definitions: ppro-chargebacks-openapi.yml, ppro-chargebacks.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.sandbox.eu.ppro.com
  description: Sandbox environment for integration testing
- url: https://api.eu.ppro.com
  description: Production
tags:
- name: Internal
paths:
  /v1/chargebacks:
    get:
      tags:
      - Internal
      summary: Get Chargebacks
      description: Returns all chargebacks associated with either a dispute ID or PPRO payment charge ID. Exactly one of [disputeId, paymentChargeId] must be provided.
      operationId: getChargebacks
      parameters:
      - name: disputeId
        in: query
        description: Dispute ID starting with 'dispute_' followed by 21 characters.
        required: false
        schema:
          type: string
          pattern: ^dispute_.{21}
        example: dispute_20240619XYZabcdefghij
      - name: paymentChargeId
        in: query
        description: Payment Charge starting with 'charge_' followed by 21 characters.
        required: false
        schema:
          type: string
          pattern: ^charge_.{21}
        example: charge_7s8FcBoJxMwVkWFR3B41p
      - name: Request-Reference
        in: header
        description: Optional Reference for the request. This is used to identify the request in debugging.
        schema:
          type: string
        example: unique-value-for-request-reference
      responses:
        '200':
          description: Successfully retrieved all chargebacks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargebackResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Duplicate request received with the same idempotency key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    servers:
    - url: https://api.sandbox.eu.ppro.com
      description: Sandbox environment for integration testing
    - url: https://api.eu.ppro.com
      description: Production
  /v1/chargeback-reversals:
    get:
      tags:
      - Internal
      summary: Get Chargeback Reversals
      description: Returns all chargeback reversals associated with either a dispute ID or PPRO payment charge ID. Exactly one of [disputeId, paymentChargeId] must be provided.
      operationId: getChargebackReversals
      parameters:
      - name: disputeId
        in: query
        required: false
        schema:
          type: string
          description: Dispute ID starting with 'dispute_' followed by 21 characters. Exactly one of [disputeId, paymentChargeId] must be provided.
      - name: paymentChargeId
        in: query
        required: false
        schema:
          type: string
          description: Payment Charge ID starting with 'charge_' followed by 21 characters. Exactly one of [disputeId, paymentChargeId] must be provided.
      - name: Request-Reference
        in: header
        description: Optional Reference for the request. This is used to identify the request in debugging.
        schema:
          type: string
        example: unique-value-for-request-reference
      responses:
        '200':
          description: Successfully retrieved all chargeback reversals.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargebackReversalResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Duplicate request received with the same idempotency key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    servers:
    - url: https://api.sandbox.eu.ppro.com
      description: Sandbox environment for integration testing
    - url: https://api.eu.ppro.com
      description: Production
  /v1/chargebacks/{id}:
    get:
      tags:
      - Internal
      summary: Get Chargeback
      description: Fetches chargeback details by id.
      operationId: getChargeback
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: disputeId
        in: query
        description: When set, must match the chargeback's dispute id or the request is rejected.
        required: false
        schema:
          type: string
      - name: Request-Reference
        in: header
        description: Optional Reference for the request. This is used to identify the request in debugging.
        schema:
          type: string
        example: unique-value-for-request-reference
      responses:
        '200':
          description: Successfully retrieved the chargeback
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargebackDetails'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Duplicate request received with the same idempotency key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    servers:
    - url: https://api.sandbox.eu.ppro.com
      description: Sandbox environment for integration testing
    - url: https://api.eu.ppro.com
      description: Production
  /v1/chargeback-reversals/{id}:
    get:
      tags:
      - Internal
      summary: Get Chargeback Reversal
      description: Fetches chargeback reversal details by id.
      operationId: getChargebackReversal
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: disputeId
        in: query
        description: When set, must match the chargeback reversal's dispute id or the request is rejected.
        required: false
        schema:
          type: string
      - name: Request-Reference
        in: header
        description: Optional Reference for the request. This is used to identify the request in debugging.
        schema:
          type: string
        example: unique-value-for-request-reference
      responses:
        '200':
          description: Successfully retrieved the chargeback reversal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargebackReversalDetails'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Duplicate request received with the same idempotency key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    servers:
    - url: https://api.sandbox.eu.ppro.com
      description: Sandbox environment for integration testing
    - url: https://api.eu.ppro.com
      description: Production
components:
  schemas:
    ChargebackResponse:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        data:
          type: array
          items:
            $ref: '#/components/schemas/ChargebackDetails'
    Pagination:
      type: object
      properties:
        totalPages:
          type: integer
          format: int32
        totalCount:
          type: integer
          format: int32
        currentPage:
          type: integer
          format: int32
    Amount:
      type: object
      properties:
        value:
          type: integer
          format: int64
        currency:
          type: string
      required:
      - currency
      - value
    ApiError:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        status:
          type: integer
          format: int32
        failureMessage:
          type: string
        extensions:
          type: object
          additionalProperties:
            type: string
    ChargebackReversalResponse:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        data:
          type: array
          items:
            $ref: '#/components/schemas/ChargebackReversalDetails'
    ChargebackDetails:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier.
          example: cb_20240619XYZabcdefghij or cr_20240619XYZabcdefghij
        amount:
          $ref: '#/components/schemas/Amount'
          description: Defines the value and currency.
        reason:
          type: string
          description: Defines the reason.
          enum:
          - PDSP_AUTH_001
          - PDSP_AUTH_002
          - PDSP_AUTH_003
          - PDSP_AUTH_004
          - PDSP_PROD_001
          - PDSP_PROD_002
          - PDSP_PROD_003
          - PDSP_PROD_004
          - PDSP_PROD_005
          - PDSP_CANC_001
          - PDSP_CANC_002
          - PDSP_CANC_003
          - PDSP_CANC_004
          - PDSP_SUBS_001
          - PDSP_SUBS_002
          - PDSP_SUBS_003
          - PDSP_SUBS_004
          - PDSP_GEN_001
          - PDSP_GEN_002
          - PDSP_GEN_003
        paymentChargeId:
          type: string
          description: The payment charge identifier.
          example: charge_7s8FcBoJxMwVkWFR3B41p
        disputeId:
          type: string
          description: The unique identifier of the associated dispute.
          example: dispute_20240619XYZabcdefghij
        transferStatus:
          type: string
          description: Status of the transfer for settlement tracking.
          enum:
          - EXPECTED
          - FAILED
          - SETTLED
        createdAt:
          type: string
          format: date-time
          description: Date and time when the entity was created in PPRO.
          example: '2025-06-19T12:34:56.789Z'
        updatedAt:
          type: string
          format: date-time
          description: Date and Time when the entity was last updated.
          example: '2025-06-19T12:34:56.789Z'
        _links:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: string
    ChargebackReversalDetails:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier.
          example: cb_20240619XYZabcdefghij or cr_20240619XYZabcdefghij
        amount:
          $ref: '#/components/schemas/Amount'
          description: Defines the value and currency.
        reason:
          type: string
          description: Defines the reason.
          enum:
          - PDSP_AUTH_001
          - PDSP_AUTH_002
          - PDSP_AUTH_003
          - PDSP_AUTH_004
          - PDSP_PROD_001
          - PDSP_PROD_002
          - PDSP_PROD_003
          - PDSP_PROD_004
          - PDSP_PROD_005
          - PDSP_CANC_001
          - PDSP_CANC_002
          - PDSP_CANC_003
          - PDSP_CANC_004
          - PDSP_SUBS_001
          - PDSP_SUBS_002
          - PDSP_SUBS_003
          - PDSP_SUBS_004
          - PDSP_GEN_001
          - PDSP_GEN_002
          - PDSP_GEN_003
        paymentChargeId:
          type: string
          description: The payment charge identifier.
          example: charge_7s8FcBoJxMwVkWFR3B41p
        disputeId:
          type: string
          description: The unique identifier of the associated dispute.
          example: dispute_20240619XYZabcdefghij
        transferStatus:
          type: string
          description: Status of the transfer for settlement tracking.
          enum:
          - EXPECTED
          - FAILED
          - SETTLED
        createdAt:
          type: string
          format: date-time
          description: Date and time when the entity was created in PPRO.
          example: '2025-06-19T12:34:56.789Z'
        updatedAt:
          type: string
          format: date-time
          description: Date and Time when the entity was last updated.
          example: '2025-06-19T12:34:56.789Z'
        _links:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: string
x-refined-from:
- ppro-chargebacks-openapi.yml
- ppro-chargebacks.json