openapi: 3.2.0
info:
  title: Ppro Refund Endpoints API
  version: v1
  description: 'Operations tagged Refund Endpoints across 2 of this provider''s published API definitions: ppro-payment-charges-openapi.yml, ppro-payment-charges.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.sandbox.eu.ppro.com
  description: Production - Sandbox environment for integration testing
- url: https://api.eu.ppro.com
  description: Production endpoint for EU customers
security:
- bearer_token: []
tags:
- name: Refund Endpoints
paths:
  /v1/payment-charges/{paymentChargeId}/refunds:
    get:
      tags:
      - Refund Endpoints
      summary: List refunds
      description: Return all refunds associated with the payment charge.
      operationId: getRefunds
      parameters:
      - name: paymentChargeId
        in: path
        required: true
        schema:
          type: string
      - name: Merchant-Id
        in: header
        description: The merchant identifier.
        required: true
        schema:
          type: string
        example: merch_cb6RQnZbBwSBkn34QYXhr
      - name: Request-Reference
        in: header
        description: Unique request reference to facilitate debugging.
        schema:
          type: string
        example: abc-unique-value-for-tracing
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/GetRefundsResponse'
        '409':
          description: Duplicate request received with the same idempotency key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseBody'
        '504':
          description: Call to the upstream dependency timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseBody'
    post:
      tags:
      - Refund Endpoints
      summary: Create refund
      description: Refund all or part of an authorization on a payment charge that has been captured.
      operationId: refund
      parameters:
      - name: paymentChargeId
        in: path
        required: true
        schema:
          type: string
      - name: Merchant-Id
        in: header
        description: The merchant identifier.
        required: true
        schema:
          type: string
        example: merch_cb6RQnZbBwSBkn34QYXhr
      - name: Request-Reference
        in: header
        description: Unique request reference to facilitate debugging.
        schema:
          type: string
        example: abc-unique-value-for-tracing
      - name: Request-Idempotency-Key
        in: header
        description: Optional Idempotency Key for the request. Sending duplicate requests will result in 409 HTTP status code.
        schema:
          type: string
        example: xyz-unique-value-for-idempotency
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PaymentChargeRefundResponse'
        '409':
          description: Duplicate request received with the same idempotency key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseBody'
        '504':
          description: Call to the upstream dependency timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseBody'
    servers:
    - url: https://api.sandbox.eu.ppro.com
      description: Production - Sandbox environment for integration testing
    - url: https://api.eu.ppro.com
      description: Production endpoint for EU customers
  /v1/payment-charges/{paymentChargeId}/refunds/{refundId}:
    get:
      tags:
      - Refund Endpoints
      summary: Get refund
      description: Returns a specific refund operation associated with the payment charge
      operationId: getRefund
      parameters:
      - name: paymentChargeId
        in: path
        required: true
        schema:
          type: string
      - name: refundId
        in: path
        required: true
        schema:
          type: string
      - name: Merchant-Id
        in: header
        description: The merchant identifier.
        required: true
        schema:
          type: string
        example: merch_cb6RQnZbBwSBkn34QYXhr
      - name: Request-Reference
        in: header
        description: Unique request reference to facilitate debugging.
        schema:
          type: string
        example: abc-unique-value-for-tracing
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PaymentChargeRefundResponse'
        '409':
          description: Duplicate request received with the same idempotency key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseBody'
        '504':
          description: Call to the upstream dependency timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponseBody'
    servers:
    - url: https://api.sandbox.eu.ppro.com
      description: Production - Sandbox environment for integration testing
    - url: https://api.eu.ppro.com
      description: Production endpoint for EU customers
components:
  schemas:
    GatewayProcessingFailureResponse:
      type: object
      properties:
        failureType:
          type: string
          description: The failure type.
          enum:
          - INTERNAL_ERROR
          - INTERNAL_DECLINE
          - PROVIDER_ERROR
          - PROVIDER_DECLINE
        failureCode:
          type: string
          description: The failure code.
        providerFailureCode:
          type: string
          description: The payment provider failure code.
        failureMessage:
          type: string
          description: The failure message.
        isRetryable:
          type: boolean
          description: Indicates whether the merchant should create a fresh new attempt, where initiating a fresh new attempt at a later time may potentially result in a successful outcome.
        additionalData:
          $ref: '#/components/schemas/AdditionalData'
    AdditionalData:
      type: object
      properties:
        merchantAdviceCode:
          type: string
          description: Merchant Advice Code (MAC) returned by the payment network on decline, indicating whether and when the payment may be retried.
        merchantAdviceCodeText:
          type: string
          description: Human-readable explanation of the Merchant Advice Code (MAC).
    PaymentChargeRefundResponse:
      type: object
      properties:
        id:
          type: string
          description: The refund identifier.
          example: 5c019979-0751-469e-96e0-b67f1d95c577
        amount:
          type: integer
          format: int64
          description: The refund amount in the payment charge currency's smallest unit.
          example: 1000
        status:
          type: string
          description: The refund status.
          enum:
          - REFUNDED
          - PENDING
          - FAILED
        merchantRefundReference:
          type: string
          description: The merchant provided refund reference.
          example: 5c019979-0751-469e-96e0-b67f1d95c577
        refundReason:
          type: string
          description: The reason for the refund request.
          enum:
          - RETURN
          - DUPLICATE
          - FRAUD
          - CUSTOMER_REQUEST
          - PRE_DISPUTE
          - OTHER
        refundDescriptor:
          type: string
          description: The refund descriptor (arbitrary string). To provide consumer's bank account details
          example: 'Name: Jamie Shopper CPF:12345678909 Bank Name: Scotland Bank Agency Number: 1234 Account Number: 123456789'
        failure:
          $ref: '#/components/schemas/GatewayProcessingFailureResponse'
          description: The refund processing failure if the refund operation failed.
        createdAt:
          type: string
          format: date-time
          description: The refund creation timestamp in ISO 8601 format.
          example: '2022-11-03T11:23:47.123Z'
        updatedAt:
          type: string
          format: date-time
          description: The refund update timestamp in ISO 8601 format.
          example: '2022-11-03T11:23:47.123Z'
        _links:
          $ref: '#/components/schemas/Links'
          readOnly: true
        labels:
          type: object
          additionalProperties:
            type: string
          description: Custom labels associated with the refund.
          example:
            consumer_origin: GTM_Campaign
    RefundRequest:
      type: object
      properties:
        merchantRefundReference:
          type: string
          description: The merchant provided refund reference.
          example: 5c019979-0751-469e-96e0-b67f1d95c577
        amount:
          type: integer
          format: int64
          description: The refund amount in the payment charge currency's smallest unit.
          example: 1000
          minimum: 1
        refundDescriptor:
          type: string
          description: The refund descriptor (arbitrary string). To provide consumer's bank account details
          example: 'Name: Jamie Shopper CPF:12345678909 Bank Name: Scotland Bank Agency Number: 1234 Account Number: 123456789'
        refundReason:
          type: string
          description: The reason for the refund request.
          enum:
          - RETURN
          - DUPLICATE
          - FRAUD
          - CUSTOMER_REQUEST
          - PRE_DISPUTE
          - OTHER
        labels:
          type: object
          additionalProperties:
            type: string
          description: Custom labels associated with the refund.
      required:
      - amount
    Links:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Link'
    GetRefundsResponse:
      type: object
      properties:
        data:
          type: array
          description: The payment charge refunds.
          items:
            $ref: '#/components/schemas/PaymentChargeRefundResponse'
        _links:
          $ref: '#/components/schemas/Links'
          readOnly: true
    ExceptionResponseBody:
      type: object
      properties:
        status:
          type: integer
          format: int32
        failureMessage:
          type: string
        timestamp:
          type: string
          format: date-time
        extensions:
          type: object
          additionalProperties: {}
    Link:
      type: object
      properties:
        href:
          type: string
        hreflang:
          type: string
        title:
          type: string
        type:
          type: string
        deprecation:
          type: string
        profile:
          type: string
        name:
          type: string
        templated:
          type: boolean
  securitySchemes:
    bearer_token:
      type: http
      scheme: bearer
x-refined-from:
- ppro-payment-charges-openapi.yml
- ppro-payment-charges.json