openapi: '3.0.3'
info:
  title: Merchant Transaction API
  version: '1.1.0'
servers:
  - url: https://apitest.paymark.nz
    variables:
      version:
        default: '2'
tags:
  - name: Authorization
  - name: Transactions


paths:
  /bearer:
    post:
      tags:
        - Authorization
      summary: Request Bearer Token
      description: Request a bearer token using merchant's credentials to use for authorization
      operationId: bearerToken
      parameters:
        - in: header
          name: Authorization
          required: true
          description: >-
            Basic Authorization header. Contains base64 encoded "key:secret"
          example: a2V5OnNlY3JldAo=
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/tokenResponse"
  /oe/transactions/v{version}/payments/create-intent:
    post:
      tags:
        - Transactions
      summary: Create Payment Intent
      description: |
        Request to register a customer's intent to pay on a merchant's website. This request sets the payments
        details through a server-to-server call to ensure they cannot be modified through the browser.
        
        This request is also idempotent through the use of the field `merchantTransactionId`.

        **Note**: the response bodies for regular and trust-enabled payment intents are the same.
      operationId: createPaymentIntent
      parameters:
        - in: path
          name: version
          schema:
            type: string
          required: true
          description: API version
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/paymentIntentRequest"
                - $ref: "#/components/schemas/trustEnabledPaymentIntentRequest"
            examples:
              "Regular":
                $ref: "#/components/examples/ExamplePaymentIntentRequest"
              "Trust Enabled":
                $ref: "#/components/examples/ExampleTrustEnablePaymentIntentRequest"
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                oneOf:
                 - $ref: "#/components/schemas/hostedPaymentIntentResponse"
                 - $ref: "#/components/schemas/customPaymentIntentResponse"
              examples:
                "Hosted":
                  $ref: "#/components/examples/ExampleHostedPaymentIntentResponse"
                "Custom":
                  $ref: "#/components/examples/ExampleCustomPaymentIntentResponse"
        '400':
          description: Validation
        '401':
          description: Not Authorised
        '404':
          description: Not found
        '429':
          description: Too many requests
        '500':
          description: Internal server error
      security:
        - BearerAuth: []
  /oe/transactions/v{version}/payments/{paymentId}:
    get:
      tags:
        - Transactions
      summary: Retrieve Payment by ID
      description: Retrieve Payment by ID
      operationId: retrievePaymentById
      parameters:
        - in: path
          name: version
          schema:
            type: string
          required: true
          description: API version
        - in: path
          name: paymentId
          required: true
          schema:
            type: string
            format: uuid
            description: ID of payment
            example: fb171c5c-90c2-47e4-81c0-df931f40a20b
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/regularPaymentResponse"
                  - $ref: "#/components/schemas/trustedPaymentResponse"
              examples:
                "Regular payment":
                  $ref: "#/components/examples/ExampleRegularPaymentResponse"
                "TrustsetupTrusted payment":
                  $ref: "#/components/examples/ExampleTrustedPaymentResponse"
        '401':
          description: Not Authorised
        '404':
          description: Not found
        '429':
          description: Too many requests
        '500':
          description: Internal server error
      security:
        - BearerAuth: []
  /oe/transactions/v{version}/refunds:
    post:
      tags:
        - Transactions
      summary: Issue a refund for a payment
      description: |
        Issue a refund for a payment that has been `AUTHORISED` or partially `REFUNDED` before.

        This request is also idempotent through the use of the field `merchantTransactionId`.
      operationId: issueRefund
      parameters:
        - in: path
          name: version
          schema:
            type: string
          required: true
          description: API version
      requestBody:
        description: Issue a refund for a payment
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/refundRequest"
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/refundResponse"
        '400':
          description: Validation
        '403':
          description: Forbidden
        '404':
          description: Not found
        '500':
          description: Internal server error
      security:
        - BearerAuth: []
  /oe/transactions/v{version}/refunds/{refundId}:
    get:
      tags:
        - Transactions
      summary: Retrieve Refund by ID
      description: Retrieve Refund by ID
      operationId: retrieveRefundById
      parameters:
        - in: path
          name: version
          schema:
            type: string
          required: true
          description: API version
        - in: path
          name: refundId
          required: true
          description: ID of the refund
          schema:
            type: string
            format: uuid
            example: 2acb56a3-fe23-43f1-9d71-c9824ad50a1f
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/refundResponse"
        '400':
          description: Validation
        '403':
          description: Forbidden
        '404':
          description: Not found
        '500':
          description: Internal server error
      security:
        - BearerAuth: []
 
components:
  schemas:
    refundRequest:
      type: object
      required:
        - merchantTransactionId
        - merchant
        - oerefund
        - risk
      properties:
        merchantTransactionId:
          type: string
          format: uuid
          description: ID in format UUID supplied by merchant for idempotency
        merchant:
          type: object
          required:
            - merchantId
          properties:
            merchantId:
              type: string
              pattern: ^\d{9}$
              description: 9 digit number that uniquely identifies a merchant
              example: 300107804
        oerefund:
          type: object
          required:
            - refundAmount
            - description
            - originalPaymentId
            - risk
          properties:
            refundAmount:
              type: integer
              description: The amount of the refund in cents
              example: 1000
            description:
              type: string
              description: Merchant description for refund
              example: Product returned
            originalPaymentId:
              type: string
              format: uuid
              description: The ID of the oe payment being refunded
        risk:
          $ref: "#/components/schemas/riskBase"
    refundResponse:
      allOf:
        - $ref: "#/components/schemas/refundRequest"
        - type: object
          properties:
            refundId:
              type: string
              format: uuid
              description: id to identify the refund
            transactionTime:
              type: string
              format: date-time
              description: Time transaction was created
            status:
              type: string
              description: Status of the transaction
              example: REFUNDED
              enum:
                - UNSUBMITTED
                - REFUNDED
                - DECLINED
                - ERROR
            createdBy:
              type: string
              format: email
              description: >-
                Email of the merchant/system issuing refund
              example: chris.li@icecreamshop.co.nz
    paymentBase:
      type: object
      properties:
        merchantTransactionId:
          type: string
          format: uuid
          description: ID in format UUID supplied by merchant for idempotency
        integrationMode:
          $ref: "#/components/schemas/integrationMode"
        merchant:
          type: object
          required:
            - url
            - notificationUrl
            - merchantId
          properties:
            url:
              type: string
              format: uri
              description: Merchant's base url where the Custom plugin will be embedded/hosted
              example: https://www.icecreamshop.co.nz
            redirectUrl:
              type: string
              format: uri
              description: Merchant's url to return customer to after payment completion
              example: https://www.icecreamshop.co.nz/redirect
            notificationUrl:
              type: string
              format: uri
              description: Merchant url to send result of payment to
              example: https://www.icecreamshop.co.nz/notification
            merchantId:
              type: string
              pattern: ^\d{9}$
              description: 9 digit number that uniquely identifies a merchant
              example: 300007886
        oepayment:
          type: object
          required:
            - amount
            - currency
            - reference
          properties:
            amount:
              type: integer
              description: The amount of the payment
              example: 1000
            currency:
              type: string
              enum:
                - NZD
            reference:
              type: string
              pattern: ^[A-Za-z0-9 -]{0,100}$
              description: Reference of transaction on customer's statement. Only first 12 characters will be displayed
              example: Customer reference
            description:
              type: string
              description: Internal merchant description of the transaction
              example: Merchant description
        risk:
          type: object
          description: >-
            Will only be persisted and returned in responses until the payment status
            becomes terminal
          properties:
            userAgentInfo:
              type: object
              properties:
                userAgent:
                  type: string
                  description: User agent of the browser
                userIpAddress:
                  type: string
                  description: User IP address of the browser
    paymentIntentRequest:
      allOf:
        - $ref: "#/components/schemas/paymentBase"
        - type: object
          required:
            - merchantTransactionId
            - integrationMode
            - merchant
            - oepayment
            - risk
          properties:
            risk:
              $ref: "#/components/schemas/risk"
    trustEnabledPaymentIntentRequest:
      allOf:
        - $ref: "#/components/schemas/paymentIntentRequest"
        - type: object
          required:
            - merchantTransactionId
            - integrationMode
            - trusted
            - merchant
            - oepayment
            - risk
          properties:
            trusted:
              $ref: "#/components/schemas/trusted"
    customPaymentIntentResponse:
      type: object
      properties:
        paymentId:
          type: string
          format: uuid
          description: >-
            ID of payment. This ID is also supplied to the initialise plugin function when the
            integrationMode is CUSTOM
        merchantTransactionId:
          type: string
          format: uuid
          description: ID in format UUID supplied by merchant for idempotency
    hostedPaymentIntentResponse:
      allOf:
        - $ref: "#/components/schemas/customPaymentIntentResponse"
        - type: object
          properties:
            paymentUrl:
              type: string
              format: uri
              example: "https://oe.hosted.demo.wordline.co.nz?paymentId=e73defa9-b9a6-4d36-9973-c824ce311234"
              description: >-
                Url returned is to the hosted payment form the merchant is to redirect the customer to,
                to complete their payment. This field is returned if the integrationMode supplied is HOSTED
    regularPaymentResponse:
      description: Regulay Payment Response
      allOf:
        - $ref: "#/components/schemas/paymentBase"
        - type: object
          properties:
            payerDetails:
              $ref: "#/components/schemas/payerDetails"
            transactionType:
              $ref: "#/components/schemas/transactionType"
            paymentId:
              type: string
              format: uuid
              description: >-
                ID of payment. This ID is also supplied to the initialise plugin function when the
                integrationMode is CUSTOM
            status:
              $ref: "#/components/schemas/transactionStatus"
            errorMessage:
              type: string
              description: >-
                This field is only returned if the status of the payment is ERROR. This field will
                contain the reason for the ERROR.
            declinedMessage:
              type: string
              description: >-
                This field is only returned if the status of the payment is DECLINED. This field will
                contain the reason for the DECLINED.
            transactionTime:
              type: string
              format: date-time
              description: Time transaction was created
            lastModifiedTime:
              type: string
              format: date-time
              description: Time transaction was last modified
            risk:
              $ref: "#/components/schemas/riskBase"
    trustedPaymentResponse:
      description: Trustsetup/Trusted Payment Response
      allOf:
        - $ref: "#/components/schemas/regularPaymentResponse"
        - type: object
          properties:
            trusted:
              allOf:
                - $ref: "#/components/schemas/trusted"
                - type: object
                  properties:
                    trustId:
                      type: string
                      format: uuid
                      description: >-
                        ID of trust used in TRUSTED Payment or created in TRUSTSETUP payment
                    trustStatus:
                      $ref: "#/components/schemas/trustStatus"
                    trustType:
                      $ref: "#/components/schemas/trustType"
    payerDetails:
      type: object
      description: Details of the customer making the payment
      properties:
        payerId:
          type: string
          description: Customer's mobile number or banking username
          example: 0213046398
        payerIdType:
          type: string
          description: Type of payerId supplied by customer
          enum:
            - MOBILE
            - CUSTOMERID
        bankId:
          $ref: "#/components/schemas/bankId"
    trusted:
      type: object
      properties:
        merchantCustomerId:
          type: string
          pattern: "^[a-zA-Z0-9-_]*$"
          minimum: 1
          maximum: 50
          example: 293bc8b9-ec79-4752-b7ce-7e50f59e2768
          description: The unique customer identifier of the Customer with the merchant
    integrationMode:
      type: string
      description: How the payment request will be presented to the customer
      enum:
        - HOSTED
        - CUSTOM
    transactionType:
      type: string
      description: Transaction type of the payment
      enum:
        - REGULAR
        - TRUSTSETUP
        - TRUSTED
    transactionStatus:
      type: string
      description: Status of the transaction
      enum:
        - NEW
        - SUBMITTED
        - AUTHORISED
        - DECLINED
        - EXPIRED
        - ERROR
        - REFUNDED
    trustStatus:
      type: string
      description: Status of the trust
      enum:
        - PENDING
        - ACTIVE
        - CANCELLED
    trustType:
      type: string
      description: >-
        Type of trusts available for use in TRUSTED payments based on the supplied integrationMode
        during the create payment intent request
      enum:
        - TRUSTED
    bankId:
      type: string
      example: ASB
      enum:
        - ANZ
        - ASB
        - BNZ
        - COOPERATIVE
        - WESTPAC
    riskBase:
      type: object
      description: >-
        Minimum risk fields
      required:
        - userAgentInfo
      properties:
        userAgentInfo:
          type: object
          required:
            - userAgent
            - userIpAddress
          properties:
            userAgent:
              type: string
              description: >-
                The raw user agent string of the client making the request. Typically identifies the browser,
                operating system, and device type.
            userIpAddress:
              type: string
              description: >-
                The public IP address of the end user or device initiating the request. Used for geolocation
                and fraud analysis.
    risk:
      type: object
      description: >-
        Will only be persisted and returned in responses until the payment status
        becomes terminal
      required:
        - userAgentInfo
      properties:
        userAgentInfo:
          type: object
          required:
            - userAgent
            - userIpAddress
          properties:
            userAgentType:
              type: string
              description: A high-level classification of the device type inferred from the user agent.
              enum:
                - DESKTOP
                - MOBILE
                - TABLET
                - POS_TERMINAL
                - EMBEDDED_DEVICE
                - BOT
                - SMART_TV
                - GAME_CONSOLE
                - WEARABLE
                - UNKNOWN
            userAgent:
              type: string
              description: >-
                The raw user agent string of the client making the request. Typically identifies the browser,
                operating system, and device type.
            userIpAddress:
              type: string
              description: >-
                The public IP address of the end user or device initiating the request. Used for geolocation
                and fraud analysis.
            latitude:
              type: number
              description: >-
                The approximate geographic latitude of the user/device at the time of the request, if available.
              example: 0.0
            longitude:
              type: number
              description: >-
                The approximate geographic longitude of the user/device at the time of the request, if available.
              example: 0.0
        customerType:
          type: string
          description: Indicates the general classification of the customer.
          enum:
            - NEW
            - REGULAR
            - ANONYMOUS
        serviceType:
          type: string
          description: Describes the category of service or product associated with the payment.
          enum:
            - ECCOMERCE_GOODS
            - ECCOMERCE_SERVICE
            - OTHER
        deliveryAddress:
          description: >-
            Information that locates and identifies a specific address, as
            defined by postal services or in free format text.
          type: object
          properties:
            addressType:
              description: Identifies the nature of the postal address.
              type: string
              enum:
                - DeliveryTo
            addressLine:
              description: >-
                The full, free-form address line provided for delivery. May contain street, building, and unit
                details.
              type: array
              items:
                type: string
                minLength: 1
                maxLength: 70
              minItems: 0
              maxItems: 5
            streetName:
              description: Name of a street or thoroughfare component of the delivery address.
              type: string
              minLength: 1
              maxLength: 70
            buildingNumber:
              description: The building number or unit number in the delivery address.
              type: string
              minLength: 1
              maxLength: 16
            postCode:
              description: The postal or ZIP code of the delivery address.
              type: string
              minLength: 1
              maxLength: 16
            townName:
              description: The town or city name for the delivery address.
              type: string
              minLength: 1
              maxLength: 35
            countrySubDivision:
              description: The state, province, or region within the country for the delivery address.
              type: string
              minLength: 1
              maxLength: 35
            country:
              description: The 2-letter ISO country code (e.g., NZ) for the delivery address.
              type: string
              pattern: '^[A-Z]{2,2}$'
          required:
            - Country
          additionalProperties: false
      additionalProperties: false
    tokenResponse:
      type: object
      description: Response of request to get a bearer token
      properties:
        issued_at:
          type: string
          description: Epoch time in seconds when token was issued
          example: 1724722243944
        expires_in:
          type: string
          description: Time in seconds when token will expire
          example: 3599
        access_token:
          type: string
          description: Token to be supplied in authorization header
          example: wLXcakyfadxnPNp6w23N90ht9SUa
  examples:
    ExamplePaymentIntentRequest:
      summary: Regular payment intent
      value:
        merchantTransactionId: "e07afb6b-7f6e-41b4-98eb-f7ae7df25bf6"
        integrationMode: "HOSTED"
        merchant:
          url: "https://www.icecreamshop.demo.paymark.co.nz"
          redirectUrl: "https://www.icecreamshop.demo.paymark.co.nz/redirect"
          notificationUrl: "https://www.icecreamshop.demo.paymark.co.nz/notification"
          merchantId: "300007886"
        oepayment:
          amount: 1000
          currency: "NZD"
          reference: "ics002431"
          description: "chocolate"
        risk:
          userAgentInfo:
            userAgent: "Mozilla/5.0"
            userIpAddress: "192.168.1.1"
            userAgentType: "DESKTOP"
            latitude: -36.8485
            longitude: 174.7633
          customerType: "CONSUMER"
          serviceType: "ECOMMERCE_GOODS"
          deliveryAddress: 
            addressType: "DELIVERY_TO"
            addressLine:
              - "88 Shortland Street"
              - "CBD"
            streetName: "Shortland St."
            buildingNumber: "18"
            postCode: "1010"
            townName: "Auckland"
            countrySubDivision: "Auckland"
            country: "NZ"
    ExampleTrustEnablePaymentIntentRequest:
      summary: Trust enabled payment intent
      value:
        merchantTransactionId: "e07afb6b-7f6e-41b4-98eb-f7ae7df25bf6"
        integrationMode: "HOSTED"
        merchant:
          url: "https://www.icecreamshop.demo.paymark.co.nz"
          redirectUrl: "https://www.icecreamshop.demo.paymark.co.nz/redirect"
          notificationUrl: "https://www.icecreamshop.demo.paymark.co.nz/notification"
          merchantId: "300007886"
        trusted:
          merchantCustomerId: "66bd5917-cb01-4daa-9098-abbba6d19383"
        oepayment:
          amount: 1000
          currency: "NZD"
          reference: "ics002431"
          description: "chocolate"
        risk:
          userAgentInfo:
            userAgent: "Mozilla/5.0"
            userIpAddress: "192.168.1.1"
            userAgentType: "DESKTOP"
            latitude: -36.8485
            longitude: 174.7633
          customerType: "CONSUMER"
          serviceType: "ECOMMERCE_GOODS"
          deliveryAddress: 
            addressType: "DELIVERY_TO"
            addressLine:
              - "88 Shortland Street"
              - "CBD"
            streetName: "Shortland St."
            buildingNumber: "18"
            postCode: "1010"
            townName: "Auckland"
            countrySubDivision: "Auckland"
            country: "NZ"
    ExampleHostedPaymentIntentResponse:
      summary: Hosted payment intent
      value:
        merchantTransactionId: "e07afb6b-7f6e-41b4-98eb-f7ae7df25bf6"
        paymentId: "b5cebe53-3480-4c85-bea5-87c28b59fcb6"
        paymentUrl: "https://oe.hosted.demo.wordline.co.nz?paymentId=b5cebe53-3480-4c85-bea5-87c28b59fcb6"
    ExampleCustomPaymentIntentResponse:
      summary: Custom payment intent
      value:
        merchantTransactionId: "e07afb6b-7f6e-41b4-98eb-f7ae7df25bf6"
        paymentId: "b5cebe53-3480-4c85-bea5-87c28b59fcb6"
    ExampleRegularPaymentResponse:
      summary: Regular Payment
      value:
        merchantTransactionId: "e07afb6b-7f6e-41b4-98eb-f7ae7df25bf6"
        paymentId: "b5cebe53-3480-4c85-bea5-87c28b59fcb6"
        integrationMode: "HOSTED"
        transactionType: REGULAR
        status: "AUTHORISED"
        transactionTime: "2025-06-16T03:16:11.397Z"
        lastModifiedTime: "2025-06-16T03:16:32.397Z"
        merchant:
          url: "https://www.icecreamshop.demo.paymark.co.nz"
          redirectUrl: "https://www.icecreamshop.demo.paymark.co.nz/redirect"
          notificationUrl: "https://www.icecreamshop.demo.paymark.co.nz/notification"
          merchantId: "300007886"
        oepayment:
          amount: 1000
          currency: "NZD"
          reference: "ics002431"
          description: "chocolate"
        payerDetails:
          payerId: "0212067183"
          payerIdType: "MOBILE"
          bankId: "ASB"
        risk:
          userAgentInfo:
            userAgent: "Mozilla/5.0"
            userIpAddress: "192.168.1.1"
    ExampleTrustedPaymentResponse:
      summary: Trustsetup/Trusted Payment
      value:
        merchantTransactionId: "e07afb6b-7f6e-41b4-98eb-f7ae7df25bf6"
        paymentId: "b5cebe53-3480-4c85-bea5-87c28b59fcb6"
        integrationMode: "HOSTED"
        transactionType: TRUSTED
        status: "AUTHORISED"
        transactionTime: "2025-06-16T03:16:11.397Z"
        lastModifiedTime: "2025-06-16T03:16:32.397Z"
        merchant:
          url: "https://www.icecreamshop.demo.paymark.co.nz"
          redirectUrl: "https://www.icecreamshop.demo.paymark.co.nz/redirect"
          notificationUrl: "https://www.icecreamshop.demo.paymark.co.nz/notification"
          merchantId: "300007886"
        trusted:
          merchantCustomerId: "66bd5917-cb01-4daa-9098-abbba6d19383"
          trustId: "0757b7a9-e732-47ef-9218-8c6e928797f6"
          trustStatus: "ACTIVE"
          trustType: "TRUSTED"
        oepayment:
          amount: 1000
          currency: "NZD"
          reference: "ics002431"
          description: "chocolate"
        payerDetails:
          payerId: "0212067183"
          payerIdType: "MOBILE"
          bankId: "ASB"
        risk:
          userAgentInfo:
            userAgent: "Mozilla/5.0"
            userIpAddress: "192.168.1.1"
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
