openapi: 3.1.0
info:
  title: Payflex Merchant API
  description: >
    REST API for integrating Payflex Buy Now Pay Later (BNPL) installment
    payments into e-commerce platforms. Supports order creation with hosted or
    embedded checkout flows, order status retrieval, full and partial refunds,
    merchant configuration retrieval, and OAuth2 client-credentials
    authentication. Merchants provide customer details, billing/shipping
    addresses, and order amounts; Payflex returns a redirect URL and order token
    to complete the payment flow. Payflex pays merchants the full purchase
    amount upfront (less a commission) and assumes all credit and fraud risk.
  version: 1.0.0
  contact:
    name: Payflex Merchant Support
    email: merchants@payflex.co.za
    url: https://payflex.co.za/support/
  termsOfService: https://payflex.co.za/terms-conditions/
  license:
    name: Proprietary
    url: https://payflex.co.za/terms-conditions/
externalDocs:
  description: Payflex Developer Documentation
  url: https://docs.payflex.co.za/

servers:
  - url: https://api.payflex.co.za
    description: Production
  - url: https://api.uat.payflex.co.za
    description: Sandbox (UAT)

security:
  - bearerAuth: []

tags:
  - name: Authentication
    description: OAuth2 client credentials token endpoint
  - name: Orders
    description: Create and manage BNPL payment orders
  - name: Refunds
    description: Initiate full or partial refunds on completed orders
  - name: Configuration
    description: Retrieve merchant payment limits and settings

paths:
  /auth/merchant:
    post:
      tags:
        - Authentication
      summary: Obtain an OAuth2 access token
      description: >
        Exchange client credentials (client_id and client_secret) for a
        Bearer access token using the OAuth2 client_credentials grant type.
        Tokens are short-lived and should be cached until near expiry.
        Production auth endpoint: https://auth.payflex.co.za/auth/merchant.
        Sandbox auth endpoint: https://auth-uat.payflex.co.za/auth/merchant.
      operationId: getAccessToken
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
            example:
              client_id: your-client-id
              client_secret: your-client-secret
              audience: https://auth-production.payflex.co.za
              grant_type: client_credentials
      responses:
        '200':
          description: Access token issued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid client credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /order/productSelect:
    post:
      tags:
        - Orders
      summary: Create a new BNPL order
      description: >
        Create a new Payflex installment payment order. Returns a redirectUrl
        for the consumer to complete the payment flow on the Payflex hosted
        checkout, as well as an orderId and token for order tracking. Merchants
        must supply consumer details, billing and shipping addresses, line items,
        total amount, and redirect URLs for confirmed and cancelled states.
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            example:
              amount: "299.99"
              consumer:
                phoneNumber: "+27821234567"
                givenNames: "Jane"
                surname: "Smith"
                email: "jane.smith@example.com"
              billing:
                addressLine1: "12 Main Street"
                addressLine2: "Apt 3"
                suburb: "Cape Town"
                postcode: "8001"
              shipping:
                addressLine1: "12 Main Street"
                addressLine2: "Apt 3"
                suburb: "Cape Town"
                postcode: "8001"
              description: "Order from Example Store"
              items:
                - name: "Blue T-Shirt"
                  sku: "SKU-001"
                  quantity: "2"
                  price: "99.99"
              merchant:
                redirectConfirmUrl: "https://example.com/checkout/confirm?status=confirmed"
                redirectCancelUrl: "https://example.com/checkout/cancel?status=cancelled"
              merchantReference: "12345"
              taxAmount: 0
              shippingAmount: 0
              merchantSystemInformation:
                plugin_version: "2.7.0"
                php_version: "8.1.0"
                ecommerce_platform: "WooCommerce 8.0"
                total_plugin_modules: "25"
                active_plugin_modules: "12"
      responses:
        '200':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — invalid or missing access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /order/{orderId}:
    get:
      tags:
        - Orders
      summary: Retrieve order status
      description: >
        Retrieve the current status and details of a Payflex order by its
        orderId. Possible orderStatus values include: Created, Initiated,
        Approved, Declined, Abandoned, Cancelled.
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
          description: The Payflex-issued order identifier
          example: ord_abc123xyz
      responses:
        '200':
          description: Order details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderStatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /order/{orderId}/refund:
    post:
      tags:
        - Refunds
      summary: Initiate a refund on an order
      description: >
        Submit a full or partial refund request for a completed (Approved)
        Payflex order. A unique requestId must be provided with each refund
        request. Partial refunds are supported by specifying an amount less than
        the original order total.
      operationId: createRefund
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
          description: The Payflex-issued order identifier to refund
          example: ord_abc123xyz
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequest'
            example:
              requestId: "Order #12345-ab3cd4ef"
              amount: 99.99
              isPlugin: true
              merchantRefundReference: "Order #12345-ab3cd4ef"
      responses:
        '200':
          description: Refund processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
        '201':
          description: Refund created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
        '400':
          description: Invalid refund request or business rule violation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /configuration:
    get:
      tags:
        - Configuration
      summary: Retrieve merchant configuration
      description: >
        Retrieve the merchant's Payflex configuration including minimum and
        maximum order amount limits. Used by integrations to enforce eligibility
        rules on the checkout page.
      operationId: getConfiguration
      responses:
        '200':
          description: Configuration retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        OAuth2 Bearer token obtained from the /auth/merchant endpoint using
        the client_credentials grant. Tokens expire and should be refreshed
        automatically before expiry.

  schemas:
    TokenRequest:
      type: object
      required:
        - client_id
        - client_secret
        - audience
        - grant_type
      properties:
        client_id:
          type: string
          description: Merchant client identifier issued by Payflex
          example: your-client-id
        client_secret:
          type: string
          description: Merchant client secret issued by Payflex
          example: your-client-secret
        audience:
          type: string
          description: >
            OAuth2 audience — production: https://auth-production.payflex.co.za,
            sandbox: https://auth-dev.payflex.co.za
          example: https://auth-production.payflex.co.za
        grant_type:
          type: string
          enum:
            - client_credentials
          description: OAuth2 grant type — must be client_credentials
          example: client_credentials

    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: Bearer token for API authentication
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          description: Token lifetime in seconds
          example: 3600

    Consumer:
      type: object
      required:
        - phoneNumber
        - givenNames
        - surname
        - email
      properties:
        phoneNumber:
          type: string
          description: Consumer's phone number (including country code)
          example: "+27821234567"
        givenNames:
          type: string
          description: Consumer's first name(s)
          example: Jane
        surname:
          type: string
          description: Consumer's last name
          example: Smith
        email:
          type: string
          format: email
          description: Consumer's email address
          example: jane.smith@example.com

    Address:
      type: object
      properties:
        addressLine1:
          type: string
          description: Street address line 1
          example: 12 Main Street
        addressLine2:
          type: string
          description: Street address line 2 (apartment, suite, etc.)
          example: Apt 3
        suburb:
          type: string
          description: Suburb or city
          example: Cape Town
        postcode:
          type: string
          description: Postal code
          example: "8001"

    OrderItem:
      type: object
      required:
        - name
        - quantity
        - price
      properties:
        name:
          type: string
          description: Product name
          example: Blue T-Shirt
        sku:
          type: string
          description: Product SKU
          example: SKU-001
        quantity:
          type: string
          description: Quantity ordered (as string)
          example: "2"
        price:
          type: string
          description: Unit price (as string with two decimal places)
          example: "99.99"

    MerchantRedirects:
      type: object
      required:
        - redirectConfirmUrl
        - redirectCancelUrl
      properties:
        redirectConfirmUrl:
          type: string
          format: uri
          description: URL to redirect the consumer after a successful payment
          example: https://example.com/checkout/confirm?status=confirmed
        redirectCancelUrl:
          type: string
          format: uri
          description: URL to redirect the consumer after a cancelled payment
          example: https://example.com/checkout/cancel?status=cancelled

    MerchantSystemInformation:
      type: object
      properties:
        plugin_version:
          type: string
          description: Integration plugin version
          example: "2.7.0"
        php_version:
          type: string
          description: PHP version (for PHP-based integrations)
          example: "8.1.0"
        ecommerce_platform:
          type: string
          description: E-commerce platform name and version
          example: "WooCommerce 8.0"
        total_plugin_modules:
          type: string
          description: Total number of installed modules/plugins
          example: "25"
        active_plugin_modules:
          type: string
          description: Number of active modules/plugins
          example: "12"

    CreateOrderRequest:
      type: object
      required:
        - amount
        - consumer
        - merchant
        - merchantReference
      properties:
        amount:
          type: string
          description: Total order amount formatted to two decimal places
          example: "299.99"
        consumer:
          $ref: '#/components/schemas/Consumer'
        billing:
          $ref: '#/components/schemas/Address'
        shipping:
          $ref: '#/components/schemas/Address'
        description:
          type: string
          description: Order description
          example: Order from Example Store
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
          description: Line items in the order
        merchant:
          $ref: '#/components/schemas/MerchantRedirects'
        merchantReference:
          type: string
          description: Merchant's own order reference number
          example: "12345"
        taxAmount:
          type: number
          format: float
          description: Tax amount included in the order total
          example: 0
        shippingAmount:
          type: number
          format: float
          description: Shipping amount included in the order total
          example: 0
        merchantSystemInformation:
          $ref: '#/components/schemas/MerchantSystemInformation'

    CreateOrderResponse:
      type: object
      properties:
        orderId:
          type: string
          description: Payflex-issued order identifier
          example: ord_abc123xyz
        token:
          type: string
          description: Order token for status tracking
          example: tok_xyz789abc
        redirectUrl:
          type: string
          format: uri
          description: URL to redirect the consumer to complete the Payflex checkout
          example: https://checkout.payflex.co.za/order/ord_abc123xyz
        message:
          type: string
          description: Error or informational message (on failure)
          example: ""

    OrderStatus:
      type: string
      enum:
        - Created
        - Initiated
        - Approved
        - Declined
        - Abandoned
        - Cancelled
      description: >
        Current status of the Payflex order:
        - Created: Order created, consumer not yet started checkout
        - Initiated: Consumer has started the checkout process
        - Approved: Payment approved, funds will be settled
        - Declined: Payment declined
        - Abandoned: Consumer did not complete the checkout
        - Cancelled: Order was cancelled

    OrderStatusResponse:
      type: object
      properties:
        orderId:
          type: string
          description: Payflex-issued order identifier
          example: ord_abc123xyz
        orderStatus:
          $ref: '#/components/schemas/OrderStatus'
        merchantReference:
          type: string
          description: Merchant's own order reference
          example: "12345"
        amount:
          type: number
          format: float
          description: Order total amount
          example: 299.99
        consumer:
          $ref: '#/components/schemas/Consumer'

    RefundRequest:
      type: object
      required:
        - requestId
        - amount
      properties:
        requestId:
          type: string
          description: >
            Unique identifier for the refund request. Must be unique per
            refund attempt to prevent duplicates.
          example: "Order #12345-ab3cd4ef"
        amount:
          type: number
          format: float
          description: Refund amount. May be less than the original order total for partial refunds.
          example: 99.99
        isPlugin:
          type: boolean
          description: Indicates the refund was initiated from a plugin integration
          example: true
        merchantRefundReference:
          type: string
          description: Merchant's reference for this refund
          example: "Order #12345-ab3cd4ef"

    RefundResponse:
      type: object
      properties:
        refundId:
          type: string
          description: Payflex-issued refund identifier
          example: ref_xyz456abc
        orderId:
          type: string
          description: The order that was refunded
          example: ord_abc123xyz
        amount:
          type: number
          format: float
          description: Amount refunded
          example: 99.99
        status:
          type: string
          description: Refund status
          example: Approved

    RefundErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: Machine-readable error code (e.g., MRM007 for business rule violations)
          example: MRM007
        message:
          type: string
          description: Human-readable error description
          example: Refund amount exceeds the remaining refundable balance

    ConfigurationResponse:
      type: object
      properties:
        minimumAmount:
          type: number
          format: float
          description: Minimum order amount eligible for Payflex BNPL
          example: 100.00
        maximumAmount:
          type: number
          format: float
          description: Maximum order amount eligible for Payflex BNPL
          example: 8000.00

    ErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: Machine-readable error code
          example: UNAUTHORIZED
        message:
          type: string
          description: Human-readable error description
          example: Access token is missing or invalid