Introduction

Welcome to the Payflex Developer documentation. Here you will find documentation for integrating Payflex as a payment option onto your e-commerce site, as well as a number of helpful marketing widgets.
Note : Provided URLs are required to start with https://

Authentication

E.g. To obtain an access token:

curl -X POST \
  https://auth.payflex.co.za/auth/merchant \
  -H 'content-type: application/json' \
  -d '{
  "client_id":"[client id]",
  "client_secret":"[client secret]", 
  "audience":"https://auth-production.payflex.co.za",
  "grant_type":"client_credentials"
}'

Example response

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciO.....",
    "expires_in": 86400,    
    "token_type": "Bearer"
}

Payflex uses OAuth2 Client Credentials Flow as the primary means for authorising requests when interacting with the Merchant API

This is a multiple step process, in that the client must obtain an access token via the OAuth token endpoint, and then use this bearer token to access the Payflex API endpoints.

Authorisation Endpoints

Client Id & Secret

These will be issued to you from the Payflex support team.

Merchant API

Base Urls

Sandbox

https://api.uat.payflex.co.za/

Production

https://api.payflex.co.za/

Payment Flow

The payment process involves the following steps:

1. Customer Selection of Payflex
   The customer opts for Payflex as their preferred payment method during the checkout stage on the merchant site.
2. Merchant Server Initiates API Call to Payflex
   The merchant server triggers an API call to the Payflex 'Create Order' endpoint, providing:
   * Customer details (email, name, phone number)
   * Order details (items purchased from the merchant site)
   * Billing and Shipping addresses
   * Amount (with optional details on discounts, shipping, and tax)
   * RedirectUrl: A merchant-hosted URL for users to return to after completing the Payflex process.
   The Payflex API responds with a unique order token and the URL for redirecting the user.
3. Redirect User to Payflex URL
   Redirect the user to the URL returned in the previous step from the Payflex API.
4. User Completes Payment on Payflex Site
   The user finalizes their payment on the Payflex site.
   
5. User Redirected to Merchant Page
   Once the user completes the Payflex process, they are redirected back to the Merchant page. This redirect should not be used to confirm or decline an order. The URL will include the following parameters:
   - paymentStatus indicating the status of the payment. Possible values are:
   * success: Payment via Payflex completed.
   * failure: Payment not taken - Payflex service not offered, or payment declined.
   * cancelled: User cancelled out of the Payflex process and returned to the merchant site.
   - orderId used to uniquely identify the order.
   
6. Payflex send order status update to statusCallbackUrl
   Payflex will send the order information when it changes to any state (Approved, Abandoned) to the specified statusCallbackUrl with the same payload as the reponse for GET /order.
   
7. Optional: Query Payflex API for Order Information
   The Merchant Server can optionally query the Payflex API for order information. This is useful for reconciling any orders that have started but users have not returned to the merchant site.
8. Merchant Site Reconciles Payment
   On receipt of a payment status (successful or otherwise), it is expected that the merchant server will reconcile the order status.

Testing

In the sandbox environment, we allow simulation of a number of scenarios with the following test cases.

Credit Scenarios

Payment Scenarios

To test a successful payment, you will need to use: 4111 1111 1111 1111 as the card number, any future expiry date and 123 as the CVV.

Emails

Duplicate email accounts are not permitted. We suggest using a Gmail account and incorporating aliases into the address for each registration attempt, such as payflextest+xyz@gmail.com. The "xyz" part can be modified for each registration, but all emails will be directed to the same account.

Phone Numbers / SMS

We check duplicate phone numbers to be registered in Testing, only 0123456789 is whitelisted to be used multiple times. The universal OTP for UAT is set as 911911

Configuration

Get Configuration

Code sample

curl -X get https://api.payflex.co.za/configuration 
  -H 'Accept: application/json' 
  -H 'Authorization: Bearer [access_token]

Endpoint

GET https://api.payflex.co.za/configuration

Request Parameters

(none)

Response Values

Example Response

{
  "minimumAmount": 50,
  "maximumAmount": 950
}

Response Codes

Order

Place Order

Code sample

curl -X post https://api.payflex.co.za/order
  -H 'content-type: application/json' 
  -H 'authorization: Bearer [access_token]'
  -d '{
  "amount": 105.00,
  "consumer": {
    "phoneNumber": "64274123456",
    "givenNames": "James",
    "surname": "Smith",
    "email": "abc123.test@payflex.co.za"
  },
  "billing": {
    "addressLine1": "23 Duncan Tce",
    "addressLine2": "",
    "suburb": "Kilbirnie",
    "city": "Wellilngton",
    "postcode": "1000",
    "state": ""
  },
  "shipping": {
    "addressLine1": "23 Duncan Tce",
    "addressLine2": "",
    "suburb": "Kilbirnie",
    "city": "Wellilngton",
    "postcode": "1000",
    "state": ""
  },
  "description": "",
  "items": [
    {
      "description": "test",
      "name": "test",
      "sku": "test",
      "quantity": 1,
      "price": 100.00
    }
  ],
  "merchant": {
    "redirectConfirmUrl": "https://merchantsite.com/confirm",
    "redirectCancelUrl": "https://merchantsite.com/cancel",
    "statusCallbackUrl": "https://merchantsite.com/callback"
  },
  "merchantReference": "test",
  "taxAmount": 0,
  "shippingAmount": 5
}'

Endpoint

POST https://api.payflex.co.za/order

Request Parameters

Response

Example Response

{
    "token": "00fbfe84-600f-44e6-9894-953ccd42a2d1",
    "expiryDateTime": "2017-08-02T03:35:32.9915516Z",
    "redirectUrl": "https://checkout.payflex.co.za/checkout?token=00fbfe84...",
    "orderId": "2f549b62-5e66-4f2e-8c7c-f5497fa17142",
    "orderItemCacheKey": "OrderItem-FX3M"
}

Response Codes

Get Order

Request Sample

curl -X get https://api.payflex.co.za/order/8eb068f..
  -H 'Accept: application/json'
  -H 'Authorization: Bearer [access_token]'

Endpoint

GET https://api.payflex.co.za/order/{orderId}

Request Parameters

Response

Example Response

{
    "orderId": "8eb068f..",
    "orderStatus": "Created",
    "amount": 105,
    "consumer": null,
    "billing": {
        "addressLine1": "23 Duncan Tce",
        "addressLine2": "",
        "suburb": "Kilbirnie",
        "city": "",
        "postcode": "1000",
        "state": null
    },
    "shipping": {
        "addressLine1": "23 Duncan Tce",
        "addressLine2": "",
        "suburb": "Kilbirnie",
        "city": "",
        "postcode": "1000",
        "state": null
    },
    "description": null,
    "items": [
        {
            "description": null,
            "name": "test",
            "sku": "test",
            "quantity": 1,
            "price": 100
        }
    ],
    "merchant": {
        "redirectConfirmUrl": null,
        "redirectCancelUrl": null,
        "statusCallbackUrl": null
    },
    "merchantReference": "test",
    "taxAmount": 10,
    "shippingAmount": 5,
    "token": "1eea52..."
}

Response Codes

Refund

Example Request

curl -X post https://api.payflex.co.za/order/{orderId}/refund \
  -H 'Content-Type: application/json'
  -H 'authorization: Bearer [access_token]'
  -d '{
    "requestId": "c6f32647-03b1-4206-818f-c2e2fe8ae7f8",
    "amount": 1,
    "merchantRefundReference": "c6f32647-03b1-4206-818f-c2e2fe8ae7f8"
    }'

The resource is idempotent if a unique requestId is provided.

Endpoint

POST https://api.payflex.co.za/order/{orderId}/refund

orderId is the orderId returned from the Place Order operation

Request Parameters

Response Body

N/A

Response Codes

Checkout Integration

There are two ways to implement the checkout process from the merchant site:
1. As a Redirect URL
2. As an Embedded iFrame

Redirect URL

The merchant can implement a Redirect URL Checkout Process as below mentioned steps.

STEP 1: Place an order on Payflex API.

Place Order on Payflex API

STEP 2: Open the redirect URL in a browser tab to start the Payflex checkout process.

In the response of the above API call the merchant will get a redirectUrl. Redirect to this URL for the customer to complete the checkout.

STEP 3: Handle the response of Call Back URLs.

The merchant will have to handle the redirectConfirmUrl and redirectCancelUrl that was specified in Place Order

The checkout portal will redirect back to the merchant's site according to the checkout status. Payflex will add the order status, token and orderId

redirectConfirmUrl?status=confirmed&token=2eeaa086-07f1- 4ca5-b6c2-7944675b3cb7&orderId=a0e253a7-e30c-4770-93e4-c4044f50d4dd

redirectCancelUrl?status=cancelled&token=2eeaa086-07f1- 4ca5-b6c2-7944675b3cb7&orderId=a0e253a7-e30c-4770-93e4-c4044f50d4dd

This will be called in the following cases.

• If the customer wants to cancel the transaction.
• If the customer's payment fails for any reason
• If the customer abandon the order
• If the checkout session times-out.
  

Embedded iFrame

The merchant can implement an Embedded iframe Checkout Process as below mentioned steps :

STEP 1: Place an order on Payflex API.

Place Order on Payflex API

STEP 2: Add the redirect URL as iFrame source in merchant’s site to do payflex checkout process.

In the response of the above API call the merchant will get a redirectUrl, then follow the below steps :

1. Now, append two more parameters in redirectUrl as mentioned below :
a. embeddediframe=true

Note : embeddediframe is a mandatory parameter and its value must be true. It will send a callback status to the top most parent. The merchant can handle the callback status anywhere on their site.

b. statussendtoparent=true

Note : statussendtoparent is an optional parameter, if merchant wants to send a callback status to the immediate parent control then only need to append this parameter in redirectUrl and its value must be true and they will have to add an EventListener before their iFrame.

2. Add one iFrame in merchant’s site.
3. Pass this redirect URL as merchant’s iFrame’s source.
4. The below screen will be loaded in merchant’s iFrame.

5. Now, the customer will be able to do checkout process.

Example of Merchant's iFrame :

For API without 'statussendtoparent' :
<iframe src="https://checkout.payflex.co.za/embedded/?orderItemCacheKey=OrderItem-2b86008e-dada-43f1-bb68-193474fb7bbb&amount=120&token=2eeaa086-07f1-4ca5-b6c2-7944675b3cb7&embeddediframe=true"></iframe>

For API with 'statussendtoparent' :
<iframe src="https://checkout.payflex.co.za/embedded/?orderItemCacheKey=OrderItem-2b86008e-dada-43f1-bb68-193474fb7bbb&amount=120&token=2eeaa086-07f1-4ca5-b6c2-7944675b3cb7&embeddediframe=true&statussendtoparent=true"></iframe>

STEP 3: Handle the response of Call Back Status.

Here, merchant will have to handle the below 3 Call Back Statuses to complete, success & cancel Checkout Process.

1. Cancel an order(Cancel Transaction) : payflex-checkout-close-window
   • This will be called in below cases.
   • If the customer want to cancel transaction.
   • If the customer's payment fail with any reason or abandoned checkout.
   • Checkout Session time-out.
2. Successfully make payment : payflex-checkout-order-success
3. Complete the checkout process & give control to Merchant : payflex-checkout-order-success-complete
   

We are sending all above 3 call back statuses with Post-Message Event Listener from Merchant’s iFrame to Merchant's Parent Controls.

Merchant will have to add Event Listener to handle all above call back statuses to their side as mentioned below :

Event Listener to handle call back statuses in Merchant's site
<script> window.addEventListener('message', event => { console.log("Merchant's site AddEventListener Message => ", event.data); if (event.data === 'payflex-checkout-order-success' || event. data === 'payflex-checkout-close-window' || event.data === 'payflex- checkout-order-success-complete') { alert("Merchant's site AddEventListener Message => " + event.data); } }); </script>
Merchant's iFrame with Checkout URL
<iframe src="https://checkout.payflex.co.za/embedded/? orderItemCacheKey=OrderItem-2b86008e-dada-43f1-bb68- 193474fb7bbb&amount=120&token=2eeaa086-07f1-4ca5-b6c2- 7944675b3cb7&email=john.doe@gmail. com&phone=0123456789&firstname=John&lastname=Doe&embeddediframe=true&sta tussendtoparent=true"></iframe>

Note : embeddediframe=true is a mandatory param for embedded iFrame Checkout Process & statussendtoparent=true is an optional param. If merchant is appending statussendtoparent=true , then they will have to add an EventListener before their iFrame.

Widgets

Payflex offers merchants a number of helpful & informative widgets, which display more information about the product to site customers. The widgets are really easy to load onto the relevant pages, and should be able to completed by most merchant site admins.

If you are having any issues implementing these on your site, please contact support@partpay.co.za

Simple Usage - Calculator / More Info

Example script tag

<script async src="https://widgets.payflex.co.za/your-merchant-name/partpay-widget-0.1.2.js?type=calculator&min=50&max=400&amount=300" type="application/javascript"></script>

Simply insert a <script> tag, as defined below, onto the part of the page that is the right place for this to be displayed.

Base Url : https://widgets.payflex.co.za/your-merchant-name/partpay-widget-0.1.2.js?type=calculator

Parameters

Demo

(*item / cart worth $300)

Shopify

When using this widget in Shopify, you can pass the following values for the amount parameters.

Parameters

i.e. <script async src="https://widgets.payflex.co.za/partpay-widget-0.1.2.js?type=calculator&min=50&max=400&amount={{ current_variant.price | divided_by: 100.0 }}" type="application/javascript"></script>

WooCommerce

When using this widget on WooCommerce, you can pass the following values for the amount parameters.

Parameters

i.e (product page). <script async src="https://widgets.payflex.co.za/partpay-widget-0.1.2.js?type=calculator&min=50&max=400&amount=<?php echo $product->get_price(); ?>" type="application/javascript"></script>