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/