NAV Navbar
Partpay logo 625x135

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://payflex-live.eu.auth0.com/oauth/token \
  -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.....",
    "scope": "merchant read:me",    
    "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

  Sandbox Production
Token Endpoint https://payflex.eu.auth0.com/oauth/token https://payflex-live.eu.auth0.com/oauth/token
Audience https://auth-dev.payflex.co.za https://auth-production.payflex.co.za

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

TODO: Image

Each of these steps is described in more detail below:

  1. User selects Payflex
    This is typically offered as a payment option for users when they are at the stage of checkout on the merchant site.
  2. Merchant Server POSTs to Payflex API
    The merchant server creates an API call to the Payflex ‘Create Order’ endpoint. This contains:
  3. Customer details (email, name, phone number)
  4. Order details (what the customer is purchasing from the merchant site)
  5. Billing and Shipping addresses
  6. Amount (plus optional information regarding discounts / shipping / tax)
  7. RedirectUrl - this is a merchant hosted URL, to return the customer to once they have completed the Payflex process.
  8. Payflex API returns a token and a Redirect URL The Payflex API returns a unique token for the order and the URL to redirect the user to.
  9. Redirect User to Payflex payment page Redirect the user to the URL returned in step 3 from the API
  10. (As above)
  11. User Completes Payment Steps at Payflex User completes their payment information on payflex site. This will result in a user being able to pay via Payflex or not.
  12. User is returned to the Merchant page when complete Once user has completed the Payflex process, they are redirected to the Merchant page. When the user is returned back to the merchant page, the URL will have the following parameters appended to the URL:
  13. paymentStatus indicates 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 Payflex process and returned to merchant site.
  14. orderId used to uniquely identify the order
  15. (Optional) Merchant Server queries Payflex API for order information This can be used to reconcile any orders that have started, but users have not returned to the merchant site, for whatever reason.
  16. As Above
  17. Merchant site reconciles payment On receipt of a payment status (successful or otherwise), it is expected 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.

AML / Credit Scenarios

Scenario Full Name DOB Address D/L D/L Version
Pass Credit / AML (anything) (any DOB over 18 yo) (any valid address) AB123456 111
Fail AML (anything) (any DOB over 18 yo) (any valid address) FA123456 111
Fail Credit (anything) (any DOB over 18 yo) (any valid address) AB000012 111

Payment Scenarios

To test a successful payment, you will need to use: 4111111111111111 as the card no, any (future dated expiry) and any CVV. If you want to test a failing payment, set the order amount to $87.04

Emails

We do not send out emails from the sandbox enviornment, but if you would like accounts activated (so you can login with user/pass each time) then please contact Payflex tech support to enable this.

Phone Numbers / SMS

We do not send out SMS’s from the sandbox environment. In order to complete a signup process, enter and valid NZ phone number. When prompted to input the SMS verification code, use 999999.

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": 10.0,
  "maximumAmount": 200000.0
}
Field Type Description
minimumAmount integer Minimum order amount
maximumAmount integer Maximum order amount

Response Codes

Code Reason
200 OK
401 Unauthorized

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": "http://merchantsite.com/confirm",
      "redirectCancelUrl": "http://merchantsite.com/cancel",
      "statusCallbackUrl": "http://merchantsite.com/callback"
    },
    "merchantReference": "test",
    "taxAmount": 0,
    "shippingAmount": 5
  }'

Endpoint

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

Request Parameters

Field Type Description
amount number Amount for order to be charged to consumer.
consumer
    phoneNumber string optional
    givenNames string optional
    surname string optional
    email string optional
billing
    addressLine1 string optional
    addressLine2 string optional
    suburb string optional
    city string optional
    postcode string optional
    state string optional
shipping
    addressLine1 string optional
    addressLine2 string optional
    suburb string optional
    city string optional
    postcode string optional
    state string optional
description string optional A description of the order
    description string optional
    name string optional
    sku string optional
    quantity integer optional
    price number optional
merchant
    redirectConfirmUrl string required
    redirectCancelUrl string required
    statusCallbackUrl string optional Merchant will get notification on this URL on Order Status Change
POST Request
{
"OrderId":"guid",
"OrderStatus":" Initiated | Approved | Created | Abandoned "
}
merchantReference string required The merchant’s id/reference that this order corresponds to
taxAmount number optional The included tax amount after applying all discounts. ,
shippingAmount number optional The shipping amount.

Response

Example Response

{
      "token": "00fbfe84-600f-44e6-9894-953ccd42a2d1",
      "expiryDateTime": "2017-08-02T03:35:32.9915516Z",
      "redirectUrl": "https://checkout.payflex.co.za//embedded/?orderItemCacheKey=OrderItem-6cf812d1...",
      "orderId": "2f549b62-5e66-4f2e-8c7c-f5497fa17142",
      "orderItemCacheKey": "OrderItem-FX3M",
      "orderOrigin": "MerchantWebsite"
  }
Field Type Description
token string The order token, used to poll order status from Payflex GET /order operation
expiryDateTime dateTime The time (utc) the token expires
redirectUrl string The URL to redirect the user to, in order to complete the Payflex payment process
orderId Id to identify order
orderItemCacheKey Key to indentify temporary storage of order

Response Codes

Code Reason
200 OK
400 The request is malformed
401 Unauthorised

Product Select

Code sample

curl -X post https://api.payflex.co.za/order/productSelect
  -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": "http://merchantsite.com/confirm",
    "redirectCancelUrl": "http://merchantsite.com/cancel",
    "statusCallbackUrl": "http://merchantsite.com/callback"
  },
  "merchantReference": "test",
  "taxAmount": 0,
  "shippingAmount": 5
}'

Endpoint

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

Request Parameters

Field Type Description
amount number Amount for order to be charged to consumer.
consumer
    phoneNumber string optional
    givenNames string optional
    surname string optional
    email string optional
billing
    addressLine1 string optional
    addressLine2 string optional
    suburb string optional
    city string optional
    postcode string optional
    state string optional
shipping
    addressLine1 string optional
    addressLine2 string optional
    suburb string optional
    city string optional
    postcode string optional
    state string optional
description string optional A description of the order
    description string optional
    name string optional
    sku string optional
    quantity integer optional
    price number optional
merchant
    redirectConfirmUrl string required
    redirectCancelUrl string required
    statusCallbackUrl string optional Merchant will get notification on this URL on Order Status Change
POST Request
{
"OrderId":"guid",
"OrderStatus":" Initiated | Approved | Created | Abandoned "
}
merchantReference string required The merchant’s id/reference that this order corresponds to
taxAmount number optional The included tax amount after applying all discounts. ,
shippingAmount number optional The shipping amount.

Response

Example Response

{
    "token": "00fbfe84-600f-44e6-9894-953ccd42a2d1",
    "expiryDateTime": "2017-08-02T03:35:32.9915516Z",
    "redirectUrl": "https://checkout.payflex.co.za//embedded/?orderItemCacheKey=OrderItem-4b51c0ee...",
    "orderId": "2f549b62-5e66-4f2e-8c7c-f5497fa17142",
    "orderItemCacheKey": "OrderItem-FX3M",
    "orderOrigin": "MerchantWebsite" 
  }
Field Type Description
token string The order token, used to poll order status from Payflex GET /order operation
expiryDateTime dateTime The time (utc) the token expires
redirectUrl string The URL to redirect the user to, in order to complete the Payflex payment process
orderId Id to identify order
orderItemCacheKey Key to indentify temporary storage of order

Response Codes

Code Reason
200 OK
400 The request is malformed
401 Unauthorised

Product Select Order

Code sample

curl -X post https://api.payflex.co.za/order/productSelectOrder
  -H 'content-type: application/json' 
  -H 'authorization: Bearer [access_token]'
  -d '{
  { 
    "orderItemCacheKey": "OrderItem-8919512b...",
    "productType": "partPayClassic",
    "isNewCustomer": true,
    "customerId": "15dd1d7d-83b9-4757..."  
  }
}'

Endpoint

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

Request Parameters

Field Type Description
orderItemCacheKey string required Unique Order key to identify an order,
productType string required Type defined for payment option,
isNewCustomer bool required To identify customer is new or existing.

Response

Example Response

{
    "token": "6af12d91-1d73-48a8-a5fd-16b7c1f7e7b3",
    "expiryDateTime": "2019-05-17T10:03:43.9852741Z",
    "redirectUrl": "/checkout?token=6af12d91-1d73-48a8-a5fd-16b7c1f7e7b3&...",
    "orderId": "2f549b62-5e66-4f2e-8c7c-f5497fa17142",
    "orderItemCacheKey": null,
    "orderOrigin": "MerchantWebsite",
}
Field Type Description
token string The order token, used to poll order status from Payflex GET /order operation
expiryDateTime dateTime The time (utc) the token expires
redirectUrl string The URL to redirect the user to, in order to complete the Payflex payment process
orderId Id to identify order

Response Codes

Code Reason
200 OK
400 The request is malformed
401 Unauthorised

Get Order

Request Sample

curl -X get https://api.payflex.co.za/order/2f549b62-5e66-4f2e-8c7c-f5497fa17142
  -H 'Accept: application/json'
  -H 'Authorization: Bearer [access_token]'

Endpoint

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

Request Parameters

Field Type Description
OrderId guid (required) order id when creating the order during the Create Order step

Response

Example Response

{
    "orderId": "8eb068f..",
    "orderStatus": "Created",
    "orderNumber": "123456-789012",
    "redirectUrl: "https://checkout.payflex.co.za/embedded/?orderItemCacheKey=OrderItem-7AIA&amount=100&token=cf23e2fe-5a41-441e-beab-538fdcb63487&email=sms00037@GMAIL.com&phone=0722313869&firstname=Abc&lastname=Xyz",
    "capturedAmount: 0.0,
    "refundedAmount: 0.0,
    "declineReason": null,
    "bin": null,
    "cardScheme": null,
    "cardLastFourDigit": null,
    "is3DSInvoked": false,
    "threeDSecureEci": null,
    "expiredReason": null,
    "amount": 105.00,
    "createdDateTime: "2020-07-08T09:55:09.5376853+02:00",
    "consumer": {
        "phoneNumber": "123456",
        "givenNames": "abc",
        "surname": "xyz",
        "email": "abc@xyz.com",     
    },
    "billing": {
        "addressLine1": "23 Duncan Tce",
        "addressLine2": "",
        "suburb": "Kilbirnie",
        "city": "",
        "postcode": "1000",
        "state": null
        "country": null
    },
    "shipping": {
        "pickup": null,
        "addressLine1": "23 Duncan Tce",
        "addressLine2": "",
        "suburb": "Kilbirnie",
        "city": "",
        "postcode": "1000",
        "state": null,
        "country": null
    },
    "description": null,
    "items": [
        {
            "description": null,
            "name": "test",
            "sku": "test",
            "quantity": 1,
            "price": 100.00,
            "merchantChannel": null
        }
    ],
    "merchant": {
        "redirectConfirmUrl": "https://www.payflex.co.za/...",
        "redirectCancelUrl": "https://www.payflex.co.za/...",
        "statusCallbackUrl": "https://www.payflex.co.za/..."
    },
    "merchantReference": "test",
    "taxAmount": 10.00,
    "shippingAmount": 5.00,
    "token": "1eea52..."
    "couponCode": null,
    "offerCodeType": 0,
    "discountAmount": null,
    "promotions": null,
    "redisKey": null,
    "metadata": {
        "h": "234"
    }
}
Field Type Description
amount number Amount for order to be charged to consumer.
orderId string A unique reference for the order. This value will need to be persisted onto the client side, for the purposes of refunds
orderStatus string A status representing the status of an order on Payflex.
Created: The order has been created on Payflex, but not yet completed.
Initiated: The order has been Initiated on Payflex, but customer has not logged in yet.
Approved: Payment has been successfuly taken/approved on Payflex.
Abandoned: User abandoned Payflex process before first payment is taken. Orders will tranisition to this state after a maximum of one hour.
consumer
    phoneNumber string optional
    givenNames string optional
    surname string optional
    email string optional
billing
    addressLine1 string optional
    addressLine2 string optional
    suburb string optional
    city string optional
    postcode string optional
    state string optional
shipping
    addressLine1 string optional
    addressLine2 string optional
    suburb string optional
    city string optional
    postcode string optional
    state string optional
description string optional A description of the order
    description string optional
    name string optional
    sku string optional
    quantity integer optional
    price number optional
merchant
    redirectConfirmUrl string required
    redirectCancelUrl string required
merchantReference string required The merchant’s id/reference that this order corresponds to
taxAmount number optional The included tax amount after applying all discounts. ,
shippingAmount number optional The shipping amount.

Response Codes

Code Reason
200 OK
400 The request is malformed
401 Unauthorised
404 Order is not found

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 Get Order operation

Request Parameters

Field Type Description
amount number required The refund amount. The refund amount can not exceed the associated order
merchantRefundReference string required Merchant refund reference.

Response Body

N/A

Response Codes

Code Reason
200 OK
400 The request is malformed
401 Unauthorised
404 Order Not found
422 A 422 occurs when the request was well formed, but the system is unable to process the request. Scenarios:
The sum of all refunds, including the new refund, exceed the (original) order amount. OR
The refund with merchantRefundReference has already been applied. OR
The refund request is otherwise invalid.
e.g. merchantRefundReference is required OR the refund amount is invalid OR the order was never completed and is not eligible for a refund

Update Merchant Reference

Example Request

curl -X PUT 
  https://api.payflex.co.za/order/{orderId}/merchantReference
  -H 'authorization: Bearer [access_token]' 
  -H 'content-type: application/json' 
  -d '{
        "merchantReference": "03942300934"
    }'

This endpoint allows an order have it’s merchantReference changed after the order has been accepted and payment taken via Payflex.

Endpoint

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

orderId is the orderId returned from the Get Order operation

Request Parameters

Field Type Description
merchantReference New merchant reference for the order

Response Body

N/A

Response Codes

Code Reason
200 OK
401 Unauthorised
404 Order Not found

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@payflex.co.za

Simple Usage - Caluclator / 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

Name Description
min Your minimum Payflex amount
max Your maximum Payflex amount
amount The order or cart amount

Demo

(*item / cart worth $300)

Shopify

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

Parameters

Shopify Page Value
Cart {{ cart.total_price | divided_by: 100.0 }}
Product {{ current_variant.price | divided_by: 100.0 }}

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

WooCommerce Page Value
Cart WC()->cart->cart_contents_total;
Product WC()->product-> get_price();

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>

Errors

Error codes are returned in the following format:

Basic Errors

Basic Error Response

{
  "message": "The request is invalid",
  "isValid": false,
  "errors": []
}

The most basic error has a message and an indication that the request was invalid.

Errors with Error Codes

Error Response with Error Code

400 Bad Request

Payflex-Error: AboveMaximumPreApprovalAmount


{
  "errorCode": "AboveMaximumPreApprovalAmount",
  "message": "The request is invalid",
  "isValid": false,
  "errors": []
}

Some errors can include an error code. If an error code is present, it will be provided in the body of the response as well as a custom Payflex-Error header.

The following is an error from POST /pos/order where the customer approval code entered has been approved for an amount that is less than the requested order amount.

Other validation errors.

Validation Error Response

400 Bad Request

{
  "message": "'Amount' must be greater than '0'.",
  "isValid": false,
  "errors": [
    {
      "propertyName": "createOrderModel.amount",
      "errorMessages": [
        "'Amount' must be greater than '0'."
      ]
    }
  ]
}

A generic validation error can be a 400 Bad Request or a 422 Unprocessable Entity

The following is an error from POST /pos/order where the order amount was incorrect.

Please note that if there are multiple validation errors, the message property is populated with just the first message.