Woolworths Group Refunds API

openapi: 3.2.0
info:
  title: Wpay NPP PayTo Merchant Refunds API
  description: API endpoints to manage agreements and initiate and view PayTo payments.
  contact:
    name: Wpay
    url: https://wpay.com.au/
  version: v1
servers:
- url: https://uat-api.wpay.com.au/wpay-npp-payto/merchant-gateway/
  description: UAT
- url: https://pt-api.wpay.com.au/wpay-npp-payto/merchant-gateway/
  description: PT - Production Test
- url: https://api.wpay.com.au/wpay-npp-payto/merchant-gateway/
  description: Production
tags:
- name: Refunds
paths:
  /merchants/{merchantId}/refunds/{refundId}:
    get:
      tags:
      - Refunds
      summary: Refunds Details
      description: Used to retrieve detailed information for a single refund transaction.
      parameters:
      - name: x-request-id
        in: header
        description: Unique identifier for the request (GUID).<br/> This id will be used for tracking and troubleshooting problems associated with the request.
        required: true
        schema:
          type: string
      - name: merchantId
        in: path
        description: 'ID of the merchant. This unique value will be provided by Wpay as part of on-boarding.<br/>Note: Wpay uses the UUID v4 format for all the unique IDs we provide.'
        required: true
        schema:
          type: string
      - name: refundId
        in: path
        description: ID of the refund for which details are being retrieved.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchant.API.Application.Queries.ViewModels.RefundDetailsByRefundIdViewModel'
              example:
                merchantId: aa899c1d-a581-47fb-ad76-8a55111e1db5
                refundId: 47532536-7acd-498d-9c99-b4772500b446
                paymentId: 27532536-7acd-498d-9c99-b4772300b444
                amount: 100
                reference: '912'
                description: Thank you Jane Jones for shopping at the AP+ store
                merchantWebhooksUrl: https://merchant.com/webhooks
                createdTimestamp: '2024-02-02T00:00:38.561Z'
                statusTimestamp: '2024-02-02T00:01:38.561Z'
                status: Completed
                merchantDefinedData:
                  Uid: dd270c40-db9b-4843-b2b5-a7be5b1a4db5
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchant.API.Swagger.Examples.BadRequestExamples.ProblemDetails404ResponseModel'
              example:
                type: https://tools.ietf.org/html/rfc7231#section-6.5.4
                title: Not Found
                status: 404
                traceId: 00-727bc5c3f2dd3612ddbfc67565ad7c00-341dba53b23bb75f-00
        '500':
          description: Internal Server Error
      security:
      - bearerAuth: []
      operationId: getMerchantsByMerchantIdRefundsByRefundId
      x-operation-id-source: derived
  /merchants/{merchantId}/payments/{paymentId}/refund:
    post:
      tags:
      - Refunds
      summary: Make Refund
      description: Used to make full or partial refunds.
      parameters:
      - name: x-request-id
        in: header
        description: Unique identifier for the request (GUID).<br/> This id will be used for tracking and troubleshooting problems associated with the request.
        required: true
        schema:
          type: string
      - name: merchantId
        in: path
        description: 'ID of the merchant. This unique value will be provided by Wpay as part of on-boarding.<br/>Note: Wpay uses the UUID v4 format for all the unique IDs we provide.'
        required: true
        schema:
          type: string
      - name: paymentId
        in: path
        description: ID of the original payment for which this refund is being initiated.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Merchant.API.Application.Commands.MerchantInitiateRefund.MerchantInitiateRefundCommand'
            example:
              refundId: 47532536-7acd-498d-9c99-b4772500b446
              amount: 100
              reference: '912'
              description: Thank you Jane Jones for shopping at the AP+ store
              merchantWebhooksUrl: https://merchant.com/webhooks
          text/json:
            schema:
              $ref: '#/components/schemas/Merchant.API.Application.Commands.MerchantInitiateRefund.MerchantInitiateRefundCommand'
            example:
              refundId: 47532536-7acd-498d-9c99-b4772500b446
              amount: 100
              reference: '912'
              description: Thank you Jane Jones for shopping at the AP+ store
              merchantWebhooksUrl: https://merchant.com/webhooks
          application/*+json:
            schema:
              $ref: '#/components/schemas/Merchant.API.Application.Commands.MerchantInitiateRefund.MerchantInitiateRefundCommand'
            example:
              refundId: 47532536-7acd-498d-9c99-b4772500b446
              amount: 100
              reference: '912'
              description: Thank you Jane Jones for shopping at the AP+ store
              merchantWebhooksUrl: https://merchant.com/webhooks
      responses:
        '201':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchant.API.Application.Queries.ViewModels.RefundDetailsViewModel'
              example:
                merchantId: aa899c1d-a581-47fb-ad76-8a55111e1db5
                paymentId: 27532536-7acd-498d-9c99-b4772300b444
                refundId: 47532536-7acd-498d-9c99-b4772500b446
                amount: 100
                reference: '912'
                description: Thank you Jane Jones for shopping at the AP+ store
                createdTimestamp: '2024-02-02T00:00:38.561Z'
                statusTimestamp: '2024-02-02T00:01:38.561Z'
                status: Completed
                merchantWebhooksUrl: https://merchant.com/webhooks
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchant.API.Swagger.Examples.BadRequestExamples.ProblemDetails400ResponseModel'
              example:
                type: https://tools.ietf.org/html/rfc7231#section-6.5.1
                title: One or more validation errors occurred.
                status: 400
                traceId: 00-d2eb5dc766296047344081d3de1e17e7-63809d2f07f7ea22-00
                errors:
                  merchantId:
                  - Merchant Id is required
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchant.API.Swagger.Examples.BadRequestExamples.ProblemDetails404ResponseModel'
              example:
                type: https://tools.ietf.org/html/rfc7231#section-6.5.4
                title: Not Found
                status: 404
                traceId: 00-727bc5c3f2dd3612ddbfc67565ad7c00-341dba53b23bb75f-00
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchant.API.Swagger.Examples.BadRequestExamples.UnprocessableEntityResponseModel'
              example:
                type: https://tools.ietf.org/html/rfc4918#section-11.2
                title: One or more validation errors occurred.
                status: 422
                traceId: 00-d2eb5dc766296047344081d3de1e17e7-63809d2f07f7ea22-00
                errors:
                  merchantId:
                  - title: Payment exceeds limit
                    detail: This payment exceeds the limit amount set in the PayTo Agreement.
                    code: MP005
        '500':
          description: Internal Server Error
      callbacks:
        Refund.Completed:
          <MerchantWebhooksUrl>:
            post:
              description: The refund was completed successfully.
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/Merchant.API.Application.Webhooks.RefundCompleted.RefundCompletedWebhook'
                    example: '{"EventId":"d0e226c4-238b-41f7-bf0a-cfffb02d7dc0","EventType":"Refund.Completed","Payload":{"RefundId":"47532536-7acd-498d-9c99-b4772500b446","PaymentId":"27532536-7acd-498d-9c99-b4772300b444","Amount":100,"Reference":"12059546438f56","Description":"Thank you Jane Jones for shopping at the AP\u002B store","NppPublishedAt":"2024-11-19T03:02:00.0013501Z","MerchantDefinedData":{"Uid":"dd270c40-db9b-4843-b2b5-a7be5b1a4db5"},"SchemaVersion":"1.0.0"},"PublishedAt":"2024-11-19T03:02:00.0017434Z","SchemaVersion":"1.0.0"}'
              responses:
                '200':
                  description: Your server implementation should return this HTTP status code if the data was received successfully
        Refund.Rejected:
          <MerchantWebhooksUrl>:
            post:
              description: The refund was rejected.
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/Merchant.API.Application.Webhooks.RefundRejected.RefundRejectedWebhook'
                    example: '{"EventId":"d0e226c4-238b-41f7-bf0a-cfffb02d7dc0","EventType":"Refund.Rejected","Payload":{"RefundId":"47532536-7acd-498d-9c99-b4772500b446","PaymentId":"27532536-7acd-498d-9c99-b4772300b444","Amount":100,"RejectionReason":{"Code":"AM04","Title":"Insufficient Funds","Detail":"The specified Payer Customer Account has insufficient funds"},"NppPublishedAt":"2024-11-19T03:02:00.0248391Z","MerchantDefinedData":{"Uid":"dd270c40-db9b-4843-b2b5-a7be5b1a4db5"},"SchemaVersion":"1.0.0"},"PublishedAt":"2024-11-19T03:02:00.0251998Z","SchemaVersion":"1.0.0"}'
              responses:
                '200':
                  description: Your server implementation should return this HTTP status code if the data was received successfully
      security:
      - bearerAuth: []
      operationId: postMerchantsByMerchantIdPaymentsByPaymentIdRefund
      x-operation-id-source: derived
components:
  schemas:
    Merchant.API.Swagger.Examples.BadRequestExamples.ProblemDetails404ResponseModel:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type: integer
          format: int32
        traceId:
          type:
          - string
          - 'null'
      additionalProperties: false
    Merchant.API.Application.Queries.ViewModels.Enums.MerchantStatus:
      title: Status
      enum:
      - Processing
      - Completed
      - Rejected
      type: string
      description: Latest payment status. <br/>Processing indicates the payment is still being processed by the NPP. <br/>Completed indicates the payment has been successfully settled and funds transfer is complete.<br/>Rejected indicates the payment has failed and funds transfer was not performed.
    Merchant.API.Swagger.Examples.BadRequestExamples.ErrorModel:
      required:
      - detail
      - title
      type: object
      properties:
        title:
          minLength: 1
          type: string
          description: The error title.
        detail:
          minLength: 1
          type: string
          description: The error description.
        code:
          type:
          - string
          - 'null'
          description: The error code.
      additionalProperties: false
    Merchant.API.Application.Queries.ViewModels.RefundDetailsViewModel:
      title: RefundDetailsViewModel
      required:
      - amount
      - createdTimestamp
      - merchantId
      - paymentId
      - refundId
      - status
      - statusTimestamp
      type: object
      properties:
        merchantId:
          minLength: 1
          type: string
          description: ID of the merchant.
        paymentId:
          minLength: 1
          type: string
          description: ID of the original payment for which this refund was initiated.
        refundId:
          minLength: 1
          type: string
          description: ID of the refund which was initiated.
        amount:
          maximum: 100000000
          minimum: 1
          type: integer
          description: Refund amount in cents.
          format: int32
        reference:
          maximum: 35
          minimum: 1
          type:
          - string
          - 'null'
          description: 'The refund reference that was provided to buyer.<br/>Note: this value is visible to buyers in their banking statements.'
        description:
          maximum: 280
          minimum: 1
          type:
          - string
          - 'null'
          description: 'The additional free form refund description that was provided to the buyer.<br/>Note: this value is visible to buyers in their banking statements.'
        createdTimestamp:
          type: string
          description: Refund record creation date and time stamp. Value is in UTC
          format: date-time
        statusTimestamp:
          type: string
          description: Refund transaction status latest update date and time stamp. Value is in UTC
          format: date-time
        status:
          minLength: 1
          type: string
          description: Latest refund transaction status. <br/>Processing indicates the refund transaction is still being processed by the NPP. <br/>Completed indicates the refund transaction has been successfully settled and funds transfer is complete.<br/>Rejected indicates the refund transaction has failed and funds transfer was not performed. Reason for failure has been provided.
        rejectionReason:
          $ref: '#/components/schemas/Merchant.API.Application.Queries.ViewModels.RefundRejectionReasonViewModel'
        merchantWebhooksUrl:
          type:
          - string
          - 'null'
          description: The Merchant's supplied URL that should receive webhooks for this refund.
        merchantDefinedData:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: An optional object for passing any additional key-value pairs that might be useful to the merchant.
      additionalProperties: false
      description: The refund details.
    Merchant.API.Application.Commands.MerchantInitiateRefund.MerchantInitiateRefundCommand:
      title: InitiateRefund
      required:
      - refundId
      type: object
      properties:
        refundId:
          minLength: 1
          type: string
          description: Merchant's unique refund transaction identifier.
        amount:
          type:
          - integer
          - 'null'
          description: Refund amount in cents. Omit value when performing a full payment refund, and provide a value when performing a partial refund.
          format: int32
        reference:
          type:
          - string
          - 'null'
          description: 'A refund reference can be provided to the buyer.<br/>Note: this value is visible to buyers in their banking statements.'
        description:
          type:
          - string
          - 'null'
          description: 'An additional free form refund description can also be provided to the buyer.<br/>Note: this value is visible to buyers in their banking statements.'
        merchantWebhooksUrl:
          type:
          - string
          - 'null'
          description: The Merchant's supplied URL that should receive webhooks for this refund.
        merchantDefinedData:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: An optional object for passing any additional key-value pairs that might be useful to the merchant.
        simulation:
          $ref: '#/components/schemas/Merchant.API.Application.Commands.MerchantInitiateRefund.RefundSimulationDto'
      additionalProperties: false
      description: The refund details.
    Merchant.API.Application.Commands.MerchantInitiateRefund.RefundSimulationDto:
      required:
      - simulate
      type: object
      properties:
        simulate:
          minLength: 1
          type: string
          description: The simulation being requested. Please refer to the developer guide for a list of all available simulations.
        delay:
          type:
          - integer
          - 'null'
          description: The delay in seconds before the requested simulation is executed.
          format: int32
      additionalProperties: false
      description: A sandbox only parameter than allows you to simulate the outcome of this refund. Please refer to the developer guide for more info.
    Merchant.API.Application.Queries.ViewModels.RefundDetailsByRefundIdViewModel:
      required:
      - amount
      - createdTimestamp
      - merchantId
      - paymentId
      - status
      - statusTimestamp
      type: object
      properties:
        merchantId:
          minLength: 1
          type: string
          description: ID of the merchant.
        refundId:
          type:
          - string
          - 'null'
          description: ID of the refund which was initiated.
        paymentId:
          minLength: 1
          type: string
          description: ID of the original payment for which this refund was initiated.
        amount:
          maximum: 100000000
          minimum: 1
          type: integer
          description: Refund amount in cents.
          format: int32
        reference:
          maximum: 35
          minimum: 1
          type:
          - string
          - 'null'
          description: 'The refund reference that was provided to buyer.<br/>Note: this value is visible to buyers in their banking statements.'
        description:
          maximum: 280
          minimum: 1
          type:
          - string
          - 'null'
          description: 'The additional free form refund description that was provided to the buyer.<br/>Note: this value is visible to buyers in their banking statements.'
        merchantWebhooksUrl:
          type:
          - string
          - 'null'
          description: The Merchant's supplied URL that should receive webhooks for this refund.
        createdTimestamp:
          type: string
          description: Refund record creation date and time stamp. Value is in UTC
          format: date-time
        statusTimestamp:
          type: string
          description: Refund transaction status latest update date and time stamp. Value is in UTC
          format: date-time
        status:
          $ref: '#/components/schemas/Merchant.API.Application.Queries.ViewModels.Enums.MerchantStatus'
        rejectionReason:
          $ref: '#/components/schemas/Merchant.API.Application.Queries.ViewModels.RefundRejectionReasonViewModel'
        merchantDefinedData:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: An optional object for passing any additional key-value pairs that might be useful to the merchant.
      additionalProperties: false
    Merchant.API.Application.Queries.ViewModels.RefundRejectionReasonViewModel:
      title: object
      required:
      - code
      - detail
      - title
      type: object
      properties:
        code:
          minLength: 1
          type: string
          description: 'Refund rejection reason code. Note: this is an internal value and is not intended to be displayed to consumers.'
        title:
          minLength: 1
          type: string
          description: 'Refund rejection reason title. Note: this value can be displayed to consumers.'
        detail:
          minLength: 1
          type: string
          description: 'Refund rejection reason details. Note: this value may be displayed to consumers.'
      additionalProperties: false
      description: Rejection reason details in case of refund failure.
    Merchant.API.Application.Webhooks.RefundCompleted.RefundCompletedWebhook:
      required:
      - eventId
      - eventType
      - payload
      - publishedAt
      - schemaVersion
      type: object
      properties:
        eventId:
          minLength: 1
          type: string
          description: The unique event identifier. This value does not change when we attempt to resend the same Webhook notification.
        eventType:
          minLength: 1
          type: string
          description: The type of the event.
        payload:
          $ref: '#/components/schemas/Merchant.API.Application.Webhooks.RefundCompleted.RefundCompletedWebhookPayload'
        publishedAt:
          type: string
          description: The time we sent the event to you. This value will change when we attempt to resend the same Webhook notification.
          format: date-time
        schemaVersion:
          minLength: 1
          type: string
          description: The schema version of the event.
      additionalProperties: false
    Merchant.API.Application.Webhooks.RefundRejected.RefundRejectedWebhookPayload:
      required:
      - amount
      - nppPublishedAt
      - paymentId
      - refundId
      - schemaVersion
      type: object
      properties:
        schemaVersion:
          minLength: 1
          type: string
          description: The schema version of this payload object.
        refundId:
          minLength: 1
          type: string
          description: ID of the refund which was initiated.
        paymentId:
          minLength: 1
          type: string
          description: ID of the original payment for which this refund was initiated.
        amount:
          type: integer
          description: Refund amount in cents.
          format: int32
        rejectionReason:
          $ref: '#/components/schemas/Merchant.API.Application.Webhooks.RefundRejected.RefundRejectionReason'
        nppPublishedAt:
          type: string
          description: The time this event was executed in the NPP infrastructure.
          format: date-time
        merchantDefinedData:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: An optional object for passing any additional key-value pairs that might be useful to the merchant.
      additionalProperties: false
    Merchant.API.Swagger.Examples.BadRequestExamples.ProblemDetails400ResponseModel:
      required:
      - errors
      - status
      - title
      - traceId
      - type
      type: object
      properties:
        type:
          minLength: 1
          type: string
          description: A URI reference [RFC3986] that identifies the problem type.
        title:
          minLength: 1
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          description: The HTTP status code([RFC7231], Section 6) generated by the origin server for this occurrence of the problem
          format: int32
        traceId:
          minLength: 1
          type: string
          description: ID for the request.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: ID of the PayTo instrument.
      additionalProperties: false
    Merchant.API.Application.Webhooks.RefundRejected.RefundRejectedWebhook:
      required:
      - eventId
      - eventType
      - payload
      - publishedAt
      - schemaVersion
      type: object
      properties:
        eventId:
          minLength: 1
          type: string
          description: The unique event identifier. This value does not change when we attempt to resend the same Webhook notification.
        eventType:
          minLength: 1
          type: string
          description: The type of the event.
        payload:
          $ref: '#/components/schemas/Merchant.API.Application.Webhooks.RefundRejected.RefundRejectedWebhookPayload'
        publishedAt:
          type: string
          description: The time we sent the event to you. This value will change when we attempt to resend the same Webhook notification.
          format: date-time
        schemaVersion:
          minLength: 1
          type: string
          description: The schema version of the event.
      additionalProperties: false
    Merchant.API.Application.Webhooks.RefundCompleted.RefundCompletedWebhookPayload:
      required:
      - amount
      - nppPublishedAt
      - paymentId
      - refundId
      - schemaVersion
      type: object
      properties:
        schemaVersion:
          minLength: 1
          type: string
          description: The schema version of this payload object.
        refundId:
          minLength: 1
          type: string
          description: ID of the refund which was initiated.
        paymentId:
          minLength: 1
          type: string
          description: ID of the original payment for which this refund was initiated.
        amount:
          type: integer
          description: Refund amount in cents.
          format: int32
        reference:
          type:
          - string
          - 'null'
          description: 'The refund reference that was provided to buyer.<br/>Note: this value is visible to buyers in their banking statements.'
        description:
          type:
          - string
          - 'null'
          description: 'The additional free form refund description that was provided to the buyer.<br/>Note: this value is visible to buyers in their banking statements.'
        nppPublishedAt:
          type: string
          description: The time this event was executed in the NPP infrastructure.
          format: date-time
        merchantDefinedData:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: An optional object for passing any additional key-value pairs that might be useful to the merchant.
      additionalProperties: false
    Merchant.API.Swagger.Examples.BadRequestExamples.UnprocessableEntityResponseModel:
      required:
      - errors
      - status
      - title
      - traceId
      - type
      type: object
      properties:
        type:
          minLength: 1
          type: string
          description: A URI reference [RFC3986] that identifies the problem type.
        title:
          minLength: 1
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          description: The HTTP status code([RFC7231], Section 6) generated by the origin server for this occurrence of the problem
          format: int32
        traceId:
          minLength: 1
          type: string
          description: ID for the request.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/Merchant.API.Swagger.Examples.BadRequestExamples.ErrorModel'
          description: ID of the PayTo instrument.
      additionalProperties: false
    Merchant.API.Application.Webhooks.RefundRejected.RefundRejectionReason:
      type: object
      properties:
        code:
          type:
          - string
          - 'null'
          description: 'Refund rejection reason code. Note: this is an internal value and is not intended to be displayed to consumers.'
        title:
          type:
          - string
          - 'null'
          description: 'Refund rejection reason title. Note: this value can be displayed to consumers.'
        detail:
          type:
          - string
          - 'null'
          description: 'Refund rejection reason details. Note: this value may be displayed to consumers.'
      additionalProperties: false
      description: Rejection reason details.
x-readme:
  explorer-enabled: true
  proxy-enabled: true
x-assembled-from:
  note: Merged verbatim from the per-operation OpenAPI definitions Wpay (Woolworths Group payments business) embeds in each ReadMe reference page; raw pages saved under openapi/_original/wpay-developerhub/.
  retrieved: '2026-10-22'
  sources:
  - https://developerhub.wpay.com.au/payto/reference/get_merchants-merchantid-buyers-buyerid-instruments.md
  - https://developerhub.wpay.com.au/payto/reference/get_merchants-merchantid-instruments-instrumentid.md
  - https://developerhub.wpay.com.au/payto/reference/get_merchants-merchantid-payments-paymentid.md
  - https://developerhub.wpay.com.au/payto/reference/get_merchants-merchantid-refunds-refundid.md
  - https://developerhub.wpay.com.au/payto/reference/get_merchants-merchantid-sessions-sessionid.md
  - https://developerhub.wpay.com.au/payto/reference/post_merchants-merchantid-instruments-instrumentid-cancel.md
  - https://developerhub.wpay.com.au/payto/reference/post_merchants-merchantid-instruments-instrumentid-payment.md
  - https://developerhub.wpay.com.au/payto/reference/post_merchants-merchantid-payments-paymentid-refund.md
  - https://developerhub.wpay.com.au/payto/reference/post_merchants-merchantid-session-checkout.md
  - https://developerhub.wpay.com.au/payto/reference/post_merchants-merchantid-session-instrument.md
  - https://developerhub.wpay.com.au/payto/reference/post_merchants-merchantid-session-payment.md