Woolworths Group Key Management API

openapi: 3.2.0
info:
  title: Wpay Payment Key Management API
  description: 'Getting Started


    Wpay payment API allows you to create a new purchase, refund or a cancel request to the Wpay platform. All APIs are IP restricted and require accepted authentication mechanism as listed below within the Encryption section of the document to make successful API requests.


    Environments


    Production: https://spay.payments.wpay.com.au

    Sandbox: https://spay.nonprod.payments.wpay.com.au


    Encryption


    Following encryption methods are required to make a successful API call to the Wpay payment platform.


    | Encryption Type |Description |

    |----------------|---------------------------------------------------------------- |

    | MTLS | Client certificate generated by Wpay. |

    | BDK | Required for AES DUKPT to generate PIN BLOCK. |

    | HMAC Key | Required to generate a hash of the payload issued by Wpay. |


    In addition to the above, IP Whitelisting is also required to identify authorised users to make the API calls.


    For detailed instructions on how the MAC and Field level encryption are generated please refer to this document.'
  contact:
    name: Wpay
    url: https://wpay.io/
  version: 1.0.0-beta
servers:
- url: https://spay.payments.wpay.com.au/v1
tags:
- name: Key Management
  description: Create and manage API keys.
paths:
  /api-key:
    post:
      tags:
      - Key Management
      summary: Create API key
      description: This end point allows you to generate a new API key. If a temporary single-use key is used to generate a new API key, the temporary key will alo be disabled
      operationId: create-key
      parameters:
      - $ref: '#/components/parameters/X-Authorization'
      - $ref: '#/components/parameters/X-Authorization-Timestamp'
      - $ref: '#/components/parameters/X-Authorization-Content-SHA256'
      requestBody:
        description: Generate a new API key
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyRequest'
        required: true
      responses:
        '200':
          description: The API key has been created
          headers:
            X-Server-Authorization-HMAC-SHA256:
              $ref: '#/components/headers/X-Server-Authorization-HMAC-SHA256'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateKeyResponse'
        '400':
          description: The request was invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - Key Management
      summary: Get API keys
      description: This endpoint allows you to retrieve list of active keys. Inactive keys are not returned in the response.
      operationId: get-keys
      parameters:
      - $ref: '#/components/parameters/X-Authorization'
      - $ref: '#/components/parameters/X-Authorization-Timestamp'
      - $ref: '#/components/parameters/X-Authorization-Content-SHA256'
      responses:
        '200':
          description: The key has been created
          headers:
            X-Server-Authorization-HMAC-SHA256:
              $ref: '#/components/headers/X-Server-Authorization-HMAC-SHA256'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKeyDetails'
        '400':
          description: The request was invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api-key/{keyId}:
    delete:
      tags:
      - Key Management
      summary: Delete API key
      description: This endpoint allows you to disable a previously created key.
      operationId: delete-key
      parameters:
      - $ref: '#/components/parameters/X-Authorization'
      - $ref: '#/components/parameters/X-Authorization-Timestamp'
      - $ref: '#/components/parameters/X-Authorization-Content-SHA256'
      - required: true
        name: keyId
        in: path
        description: Key ID
        schema:
          type: string
        example: 0000-0000-0000-0000
      responses:
        '200':
          description: The key has been disabled
          headers:
            X-Server-Authorization-HMAC-SHA256:
              $ref: '#/components/headers/X-Server-Authorization-HMAC-SHA256'
        '400':
          description: The request was invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/keys/credential/{keyId}/public:
    get:
      tags:
      - Key Management
      summary: Get the public key associated with a client credential
      description: This endpoint is used to retrieve the public key for a client credential.
      operationId: GetCredentialPublicKeyAsync
      parameters:
      - name: keyId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested credential public key is returned.
          content:
            text/json:
              schema:
                $ref: '#/components/schemas/PublicKey'
              example:
                key: '----Public JWK key material as a JSON object----'
                expiry: '2026-01-26T03:59:36.542905+00:00'
        '401':
          description: The user is not authorized to make this request.
          content:
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/keys/current/public:
    get:
      tags:
      - Key Management
      summary: Get the current public key
      description: The current public key is used to verify message signatures and encrypt request data elements
      operationId: GetPublicKeyAsync
      responses:
        '200':
          description: The current public key is returned.
          content:
            text/json:
              schema:
                $ref: '#/components/schemas/PublicKey'
              example:
                key: '----Public JWK key material as a JSON object----'
                expiry: '2026-01-26T03:59:36.542207+00:00'
        '401':
          description: The user is not authorized to make this request.
          content:
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/keys/{keyId}/public:
    get:
      tags:
      - Key Management
      summary: Get a public key by key ID
      description: This endpoint can be used when a specific key ID is required, or example the response signature contains a key id not already retrieved.
      operationId: GetPublicKeyByIdAsync
      parameters:
      - name: keyId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested public key is returned.
          content:
            text/json:
              schema:
                $ref: '#/components/schemas/PublicKey'
              example:
                key: '----Public JWK key material as a JSON object----'
                expiry: '2026-01-26T03:59:36.542561+00:00'
        '401':
          description: The user is not authorized to make this request.
          content:
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/keys/credential/rotate-to/{keyId}:
    put:
      tags:
      - Key Management
      summary: Rotate the current credential
      description: Creates a new credential and updates the expiration date of the current credential.The current credential is the one used to sign the request.
      parameters:
      - name: keyId
        in: path
        description: The key ID of the new credential.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RotateCredentialDto'
          text/json:
            schema:
              $ref: '#/components/schemas/RotateCredentialDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/RotateCredentialDto'
      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: putApiV1KeysCredentialRotateToByKeyId
      x-operation-id-source: derived
components:
  schemas:
    ApiKeyRequest:
      type: object
      required:
      - description
      properties:
        description:
          type: string
          description: Description of the key
          example: 'Development token #1'
          minLength: 1
    CreateKeyResponse:
      type: object
      properties:
        keyId:
          type: string
          description: The key ID
          example: 6e52f37c-4939-4c92-8771-bcb7c219fc59
        key:
          type: string
          description: The key value
          example: myS3r3tK3y
        created:
          type: string
          description: Timestamp of when key was generated.
          format: date-time
          example: '2023-06-28T12:24:11.652Z'
        description:
          type: string
          description: Echoed from the request
          example: 'Development token #1'
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: Error status Code
          example: 400
        description:
          type: string
          description: error message
          example: Validation failed on the request payload
        errors:
          $ref: '#/components/schemas/Errors'
    ErrorMessage:
      type: object
      properties:
        title:
          type: string
          description: title of value that is faulty
          example: amount
        details:
          type: string
          description: Error message
          example: amount must not be greater than 10
    ApiKeyDetails:
      type: object
      properties:
        keyId:
          type: string
          description: The key ID
          example: 6e52f37c-4939-4c92-8771-bcb7c219fc59
        created:
          type: string
          description: Timestamp of when key was created
          format: date-time
          example: '2023-06-28T12:24:11.652Z'
        description:
          type: string
          description: The description provided when the key was created
          example: 'Development token #1'
    Errors:
      type: array
      items:
        $ref: '#/components/schemas/ErrorMessage'
    RotateCredentialDto:
      required:
      - currentKeyExpiry
      - expiration
      - publicKey
      type: object
      properties:
        publicKey:
          $ref: '#/components/schemas/ClientPublicKey'
        expiration:
          type: string
          description: The UTC expiration date of the new credential. Must be less than 365 days into the future
          format: date-time
        currentKeyExpiry:
          type: string
          description: Update the expiration date of the current credential. The current credential is the one used to make this API request. Must be within 14 days.
          format: date-time
      additionalProperties: false
    ClientPublicKey:
      required:
      - crv
      - kid
      - kty
      - x
      - y
      type: object
      properties:
        kty:
          minLength: 1
          pattern: EC
          type: string
          description: The key type. Only EC is currently supported.
        kid:
          type: string
          description: The key identifier. Must be a GUID with high entropy
          format: uuid
        use:
          type:
          - string
          - 'null'
          description: The key use. Only sig is supported.
        crv:
          minLength: 1
          pattern: P-256
          type: string
          description: The EC key curve. Only P-256 is supported.
        x:
          maxLength: 44
          minLength: 42
          pattern: ^[A-Za-z0-9\-_]+={0,2}$
          type: string
          description: The EC key X coordinate.
        y:
          maxLength: 44
          minLength: 42
          pattern: ^[A-Za-z0-9\-_]+={0,2}$
          type: string
          description: The EC key Y coordinate.
      additionalProperties: false
    PublicKey:
      type: object
      properties:
        key:
          description: The current public key.
        expiry:
          type: string
          description: The expiry date of the public key.
          format: date-time
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
      additionalProperties: {}
  parameters:
    X-Authorization-Timestamp:
      name: X-Authorization-Timestamp
      in: header
      description: If this value differs by more than 900 seconds (15 minutes) from the time of the server, the request will be rejected.
      required: true
      style: simple
      explode: false
      example: '2023-10-23T03:30:42.619Z'
      schema:
        type: string
        description: If this value differs by more than 900 seconds (15 minutes) from the time of the server, the request will be rejected.
    X-Authorization:
      name: X-Authorization
      in: header
      description: Mac of the payload
      required: true
      style: simple
      explode: false
      schema:
        type: string
        description: HMAC signature of the payload. Refer to the HTTP HMAC documentation for more information.
    X-Authorization-Content-SHA256:
      name: X-Authorization-Content-SHA256
      in: header
      description: The base64 encoded SHA-256 hash value used to generate the signature base string. This is analogous to the standard Content-MD5 header. Required for any request where Content-Length is not 0 (for example, a POST request with a body).
      required: true
      style: simple
      explode: false
      example: '2023-10-23T03:30:42.619Z'
      schema:
        type: string
        description: The base64 encoded SHA-256 hash value used to generate the signature base string.
  headers:
    X-Server-Authorization-HMAC-SHA256:
      description: This header includes the Wpay response signature which must be verified by the client.
      style: simple
      required: true
      explode: false
      schema:
        type: string
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/cardsconnect/reference/cancel-transaction-1.md
  - https://developerhub.wpay.com.au/cardsconnect/reference/create-key.md
  - https://developerhub.wpay.com.au/cardsconnect/reference/create-transaction-1.md
  - https://developerhub.wpay.com.au/cardsconnect/reference/delete-key.md
  - https://developerhub.wpay.com.au/cardsconnect/reference/get-keys.md