openapi: 3.1.0
info:
  title: Payflex Merchant Authentication Orders 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/
servers:
- url: https://api.payflex.co.za
  description: Production
- url: https://api.uat.payflex.co.za
  description: Sandbox (UAT)
security:
- bearerAuth: []
tags:
- name: Orders
  description: Create and manage BNPL payment orders
paths:
  /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'
components:
  schemas:
    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
    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
    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
    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'
    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

        '
    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'
    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'
    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'
    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'
    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: ''
  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.

        '
externalDocs:
  description: Payflex Developer Documentation
  url: https://docs.payflex.co.za/