openapi: 3.0.1
info:
  title: Invoice webhooks OpenAPI specification
  description: >-
    This is the documentation for the Ratepay invoice webhooks. The webhooks are
    still in development and subject to change. This documentation will evolve
    as the development of the webhooks progresses.
  contact:
    name: Ratepay
    url: https://www.ratepay.com/
    email: info@ratepay.com
  version: version
paths:
  /webhook-invoice(to be defined):
    parameters:
      - name: x-signature
        in: header
        description: the hashed (SHA-512) payload
        required: true
        schema:
          type: string
        example: >-
          1be8ca419d1969085fba97228a5eeb55683cc5442cb475ffd9d8a40419ead40d3d82bea3209b6f4fdcce51c9ce6eb43a025faaf05b09bb90e4cb3c143143adec
      - name: Authorization
        in: header
        description: >-
          For each request, a valid access token must be provided in the
          Authorization header. See                       [Authentication
          API](/docs/developer/authentication/authentication/) for obtaining a
          valid token.
        required: true
        schema:
          type: string
    post:
      summary: Webhook for invoice communications
      description: Payload for invoice webhooks
      operationId: InvoiceWebhookCall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: number
                  description: Unique identifier of the webhook event.
                  example: 92
                shop_transaction_id:
                  type: string
                  description: >-
                    The order ID generated by the shop. This ID must be known to
                    the buyer and is used for buyer communication, e.g. emails
                    and buyer support.
                  example: shop-transaction-id-1234
                  maxLength: 50
                  minLength: 1
                ratepay_payment_reference:
                  type: string
                  minLength: 10
                  maxLength: 127
                  description: >-
                    Reference to be indicated in the bank transfer (generated by
                    Ratepay).
                  example: GD1234567890
                ratepay_transaction_id:
                  type: string
                  description: Ratepay transaction ID.
                  example: 32-201411251340634
                invoice_id:
                  type: string
                  description: The billing ID of the order.
                  example: DG0627731Z7-001
                eml_url:
                  type: string
                  description: The URL to fetch the email document.
                  example: >-
                    https://api.ratepay.com/api/order/123/correspondences/invoices/456/eml
                pdf_url:
                  type: string
                  description: The URL to fetch the PDF document.
                  example: >-
                    https://api.ratepay.com/api/order/123/correspondences/invoices/456/pdf
      responses:
        '200':
          description: Success
components: {}
