API Documentation

Our set of API allows you to integrate our services, manage organisations, users in a simple and programmatic way, using conventional HTTP requests. The endpoints are intuitive and powerful, allowing you to easily make calls to retrieve information or to execute actions.

The API documentation will start with a general overview about the design and technology that has been implemented, followed by reference information about specific endpoints.

Types of integration

  1. Service Redirect
    • This method requires minimal development time as most of the logic is hosted on our service page you are redirecting to.
    • This method will still require the setup of a auth token before redirecting.
    • Services that supports redirect: Agent Assist, Agent Monitor and Agent Request.
  2. Service Enterprise
    • Most of the API's are straight forward REST.
    • Some services like ASSIST/MONITOR/REQUEST are event driven. This will require you to setup Websocket event listeners using the WAMP2 protocol. You can use a cross platform library like Autobahn to connect to our endpoint.
    • This type of integration requires you to setup your own UI logic.
    • Services that supports enterprise integration: Agent Assist, Agent Monitor, Agent Request, Express and POS.
  3. Webhooks
    • Used for recon.
    • Will send you related information right after a transaction is completed.
    • Configurable under Settings→Integration in the admin console.
    • Response log can be viewed here: Webhook Logs
    • Important Notice: Webhooks will exclusively originate from the following two IP addresses. It is important to whitelist them:
    • 54.72.191.28
    • 54.194.139.201

Webhook payload example

In settings you can configure your success, refund and error webhook urls. The result will be sent as an HTTP POST request in the following format:

We do not have static IPs to whitelist and we recommend doing lookup api calls:
Payments: /api/v1/gateway-transaction/$GATEWAY_TRANSACTION_ID
Payouts: /api/v1/payout/100/$PAYOUT_TRANSACTION_ID

Webhook success/error sample post request 

                
                POST = [
                    'success' => {1 or 0}
                    'status' => {statusString}
                    'organisation_id' => {merchant_id}
                    'amount' => {amount}
                    'callpay_transaction_id' => {gateway_transaction_id}
                    'reason' => ‘{reasonForFailureIfApplicable}’
                    'user' => ‘{paymentUser}’
                    'merchant_reference' => ‘{merchant_reference}’
                    'gateway_reference' => ‘{psp_reference}'
                    'gateway_response' => ‘{additionalDataFromPSP}’
                    'currency' => ‘{currency}’
                    'payment_key' => ‘{payment_key}’
                ]

Refund webhook url post request differs slightly, refunded_amount set instead of amount 

                
                POST = [
                    'success' => {1 or 0}
                    'organisation_id' => {merchant_id}
                    'refunded_amount' => {amountRefunded}
                    'callpay_transaction_id' => {gateway_transaction_id}
                    'reason' => ‘{reasonForFailureIfApplicable}’
                    'user' => ‘{paymentUser}’
                    'merchant_reference' => ‘{merchant_reference}’
                    'gateway_reference' => ‘{psp_reference}'
                    'currency' => ‘{currency}’
                    'payment_key' => ‘{payment_key}’
                    'gateway_response' => ‘{additionalDataFromPSP}’
                ]

Payment Method Types


This document is filtered by services & Payment Method types assigned for: Peach Payments - South Africa
Your account currently has the following Payment Methods activated:
Payment Methods Integration methods Activated
Agent Assist
A call center service for taking payment details while on call.		 Redirect & Enterprise Yes
Agent Monitor
A call center service for taking payment details by forwarding the customer on the call to an IVR		 Redirect & Enterprise No
Agent Request
A call center service for taking payment details over network initiated USSD.		 Enterprise Yes
Credit Card Payments
A website or mobile service for accepting credit card payments via a redirect.		 Checkout & Redirect & Enterprise Yes
EFTsecure
A website or mobile service for accepting instant EFT		 Checkout & Redirect & Enterprise Yes
Notify Express (Pay by Link)
A notification service for Pay Direct and EFTsecure. Email, SMS and Link supported.		 Enterprise Yes
Snapscan
Accept Snapscan payments by scanning a QR Code as an option through the checkout widget.		 Checkout & Redirect No
Zapper
Accept Zapper payments by scanning a QR Code as an option through the checkout widget.		 Checkout & Redirect No
OTT-Voucher
Accept Voucher payments as an option through the checkout widget.		 Checkout & Redirect No
1Voucher
Accept Voucher payments as an option through the checkout widget.		 Checkout & Redirect No
BluVoucher
Accept Voucher payments as an option through the checkout widget.		 Checkout & Redirect No
EasyPay Voucher (Kazang Voucher)
Accept Voucher payments as an option through the checkout widget.		 Checkout & Redirect No
Scan To Pay
Accept payments by scanning a QR code using any Scan To Pay app.		 Checkout & Redirect No
Mobicred
Accept payments through a Micro loans provider, as and option from the checkout widget.		 Checkout & Redirect No
Fasta
Accept payments through a Micro loans provider, as and option from the checkout widget.		 Checkout & Redirect No
Epos
Accept data payloads for validation.		 No
Chinapay
 Checkout & Redirect No
Pay just Now
Accept payments through a Micro loans provider, as and option from the checkout widget.		 Checkout & Redirect No
Payflex
Accept payments through a Micro loans provider, as and option from the checkout widget.		 Checkout & Redirect No
Crypto
Accept Crypto payments as an option through the checkout widget.		 Checkout & Redirect No
Vfd
Accept Vfd payments as an option through the checkout widget.		 Checkout & Redirect No
EasyLoad (Shop2Shop)
Accept Voucher payments as an option through the checkout widget.		 Checkout & Redirect No
Capitec Pay
Accept Capitec Pay payments as an option through the checkout widget.		 Checkout & Redirect Yes
Fivewest
Accept Fivewest payments as an option through the checkout widget.		 Checkout & Redirect No
Capitec EFT
Accept Capitec EFT payments as an option through the checkout widget.		 Checkout & Redirect No
RealPay Capitec Pay
Accept RealPay Capitec Pay payments as an option through the checkout widget.		 Checkout & Redirect No

Requests

Any tool that is fluent in HTTP can communicate with the API simply by requesting the correct URI. Requests should be made using the HTTPS protocol so that traffic is encrypted. The interface responds to different methods depending on the action required.

Method Usage
GET

For simple retrieval of information you should use the GET method. The information you request will be returned to you as a JSON object.
DELETE

To destroy a resource and remove it from your account and environment, the DELETE method should be used.
PUT

To update the information about a resource in your account, the PUT method is available.
POST

To create a new object, your request should specify the POST method.

The POST request includes all of the attributes necessary to create a new object. When you wish to create a new object, send a POST request to the target endpoint.

HTTP Statuses

Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes.

In the event of a problem, the status will contain the error code, while the body of the response will usually contain additional information about the problem that was encountered.

In general, if the status returned is in the 200 range, it indicates that the request was fulfilled successfully and that no error was encountered.

Return codes in the 400 range typically indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, that the object you are requesting does not exist, or that your request is malformed.

If you receive a status in the 500 range, this generally indicates a server-side problem. This means that we are having an issue on our end and cannot fulfill your request currently.

HTTP status example

RESPONSE


{
    "name": "Unauthorized",
    "message": "",
    "code": 0,
    "status": 401,
    "type": "yii\\web\\UnauthorizedHttpException"
}

Responses

When a request is successful, a response body will typically be sent back in the form of a JSON object.

For example, if you send a GET request to /api/v1/user/$USER_ID you will get back an object for that user. If you send the GET request /api/v1/organisation/$ORGANISATION_ID/user you will get back an array of objects.

Examples

Single Object


{
    "id": 1,
    "name": "John",
    ...
}

Object Collection


[
    {
        "id": 1,
        "name": "John",
        ...
    },
    {
        "id": 2,
        "name": "Joe",
        ...
    },
    {
        "id": 3,
        "name": "Jane",
        ...
    }
]

Authentication API V1 (Basic Auth)

A token must be sent in the headers of a request for authentication

A token can be created for a user by making an API call with basic authentication (a valid user's username and password must be sent as credentials) to following URL:

Keep in mind that Agent users are limited to service api calls that they are authorised to use.

Fetch token example

Request

curl -X POST  -u validusername:validpassword https://eft.ppay.io/api/v1/token

Response


{
    "token": "b5cfaae0e94e79d0073f4925143dca2c",
    "expires": "2016-09-07 08:46:16"
}

Constants

Some of these constants are required for certain API calls.

Available Service IDs

These are the service IDs available to your organisation.

ID Service
2 Agent Assist
10 Agent Request
11 Notify Express
5 Inbound
4 POS
12 EftX
13 Direct
14 Payouts
17 Manual Payments
26 Realtime EFT
43 Capitec Pay

Available Gateway IDs

List of available gateways

ID Gateway
6 Peach Payments

User roles

List of available user roles Post with string value
eg. User[role] = 'agent'

Role Description
administrator User that can manage the organisation and users
agent Call centre agent that uses our services

Contract types

List of available contract types for newly created organisation
eg. Organisation[contract_type_id] = 1

Contract type id Description
1 24 month contract
2 Pre Paid contract

Using services

Allows agents and apps to make use of our services through the API.

Agent Assist

Initialise Assist transaction. Organisation id is required in url

Request Method: POST

Url: https://eft.ppay.io/api/v1/organisation/$ORGANISATION_ID/assist/init

Will return websocket url, token and extension to transfer call to.

For authentication use BasicAuth with agent's username and password.

Post parameters:

Attribute Type Description Required
amount decimal ie. 10.00 Yes
reference string custom reference No

This can then be used for monitoring the IVR progress with websockets. See example html and javascript on assist_example.html page on how to use the response parameter values to get IVR progress in realtime. NB: Websockets can only be streamed from HTTP and not HTTPS. The limitation is set as SSL certificates needs to be in place to use WSS

assist/init example

cURL Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/organisation/10/assist/init -d "amount=25.00&reference=your_reference"

Response


{
"wsUrl": "wss://services.callpay.com",
"wsToken": "{$ORGANISATION_ID}_{$AGENTCH}_{$ONE_TIME_TOKEN}",
"transferExtension": "11*1*1111"
}

Edit assist step

Request Method: POST

Url: https://eft.ppay.io/api/v1/assist/edit-step

This sends a request to server to reset current step. No response sent back.

For authentication use BasicAuth with agent's username and password.

Post parameters:

Attribute Type Description Required
step integer The number of the step to edit Yes

See example html and javascript on assist_example.html page on how to integrate.

assist/edit-step example

cURL Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/assist/edit-step

Response


200 OK

Next assist step

Request Method: POST

Url: https://eft.ppay.io/api/v1/assist/next-step

See example html and javascript on assist_example.html page on how to integrate.

For authentication use BasicAuth with agent's username and password.

assist/next-step example

cURL Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/assist/next-step

Response


200 OK

Reset all assist steps

Request Method: POST

Url: https://eft.ppay.io/api/v1/assist/reset-all

This sends a request to server to reset all steps. No response sent back.

See example html and javascript on assist_example.html page on how to integrate.

For authentication use BasicAuth with agent's username and password.

assist/reset-all example

cURL Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/assist/reset-all

Response


200 OK

Process payment

Request Method: POST

Url: https://eft.ppay.io/api/v1/assist/process-payment

Post parameters:

Attribute Type Description Required
callId integer valid call id Yes

See example html and javascript on assist_example.html page on how to integrate.

assist/process-payment example

cURL Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/assist/process-payment -d "callId=$CALL_ID"

Response


{
    "success": "1",
    "detail": {
        "displaymessage": "Successful",
        "merchantreference": "ref_1425983543",
        "reference": "389451136137",
        "paymentmethodsused": {
            "amountincents": "1055",
            "cardexpiry": "122015",
            "cardnumber": "511112******1349",
            "gatewayreference": "37588444",
            "information": "MASTERCARD",
            "nameoncard": "John Doe"
        },
        "resultcode": "00",
        "resultmessage": "Successful",
        "successful": "true"
    }
}

Agent Request

Initialise Request transaction

Request Method: POST

Url: https://eft.ppay.io/api/v1/request/init

Will return websocket url and token.

For authentication use BasicAuth with agent's username and password.

Post parameters:

Attribute Type Description Required
amount decimal ie. 10.00 Yes
mobile_number integer A valid mobile number Yes
reference string custom reference No

request/init example

cURL Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/request/init -d "amount=25.00&reference=your_reference"

Response


{
    "wsUrl": "wss://services.callpay.com",
    "wsToken": "{$ORGANISATION_ID}_{$AGENTCH}_{$ONE_TIME_TOKEN}"
}

Request Card

Send USSD request for card number

Request Method: POST

Url: https://eft.ppay.io/api/v1/request/card

For authentication use BasicAuth with agent's username and password.

request/card example

cURL Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/request/card

Response


{
    "result": "{\"code\":200,\"description\":\"OK\",\"message\":\"OK\"}"
}

Request CVV

Send USSD request for cvv number

Request Method: POST

Url: https://eft.ppay.io/api/v1/request/cvv

For authentication use BasicAuth with agent's username and password.

request/cvv example

cURL Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/request/cvv

Response


{
    "result": "{\"code\":200,\"description\":\"OK\",\"message\":\"OK\"}"
}

Set expiry date

Save expiry date for current request transaction

Request Method: POST

Url: https://eft.ppay.io/api/v1/request/expiry-date

For authentication use BasicAuth with agent's username and password.

Post parameters:

Attribute Type Description Required
expiry_date String Must be formatted MMYYYY ie. 032017 for March 2017 Yes

request/expiry-date example

cURL Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/request/expiry-date -d "expiry_date=032017"

Response


{
    "result": "true"
}

Process payment

Request Method: POST

Url: https://eft.ppay.io/api/v1/request/process-payment

For authentication use BasicAuth with agent's username and password.

request/process-payment example

cURL Agent Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/request/process-payment

Response


{
    "success": "1",
    "detail": {
        "displaymessage": "Successful",
        "merchantreference": "ref_1425983543",
        "reference": "389451136137",
        "paymentmethodsused": {
            "amountincents": "1055",
            "cardexpiry": "122015",
            "cardnumber": "511112******1349",
            "gatewayreference": "37588444",
            "information": "MASTERCARD",
            "nameoncard": "John Doe"
        },
        "resultcode": "00",
        "resultmessage": "Successful",
        "successful": "true"
    }
}

Service Redirect

Request Method: POST

Monitor Url: https://eft.ppay.io/monitor-web-view

Assist Url: https://eft.ppay.io/assist-web-view

Request Url: https://eft.ppay.io/request-web-view

Integration Type: Service Redirect

This sends a request to the relevant service web view

NB: Authentication Token must be posted with params

Post parameters:

Attribute Type Description Required
X-Token string A valid auth token Yes
amount decimal ie. 10.00 Yes
redirect_url string Url to redirect to after transaction No
payment_success_url string Url to post transaction result to after successful transaction No
payment_failed_url string Url to post transaction result to after unsuccessful transaction No
reference string custom reference for transaction No

Credit Card Token Redirect

Once all credit card fields have validated on our redirect service pages the process payment button will become available to click. If tokenization is enabled on the payment gateway a "Save Card" button will also appear. Instead of processing payment as normal this would tokenize the card details for usage later. See image below:

Image of Save card button

Once card details have been tokenized the page will redirect to your redirect url with the result in the GET parameters. To make payment using the saved token you will use the unique reference that you submitted to the redirect web view. See Scheduled Payments and and Real-time Token Payments for more information on how to pay by token.

Express transaction sms

Send sms with express transaction link.

Request Method: POST

Url: https://eft.ppay.io/api/v1/express/sms

Will send an sms with express transaction link to user's mobile phone.

Post parameters:

Attribute Type Description Required
amount decimal ie. 10.00 Yes
reference string custom reference No
number string valid mobile number Yes
expiry_date date DD-MM-YYYY No
organisation_id integer Partners only No

Sms example

cURL Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/express/sms -d "amount=25.00&reference=test&number=27821112222"

Response


{
    "id": 96,
    "recipient": "https://eft.ppay.io/u/331e902aa"
}

Express transaction Email

Send email with express transaction link.

Request Method: POST

Url: https://eft.ppay.io/api/v1/express/email

Will send an email with express transaction link to user's email address.

Post parameters:

Attribute Type Description Required
amount decimal ie. 10.00 Yes
reference string custom reference No
email string valid email address Yes
expiry_date date DD-MM-YYYY No
organisation_id integer Partners only No
files[] post array of files File attachments should be posted as array No

Email example

cURL Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/express/email -d "amount=25.00&reference=test&email=jondoe@domain.com"

Response


{
    "id": 96,
    "link": "http://eft.ppay.io/u/331e902aa"
}

Cancel Express transaction

Cancel a express transaction via the API.

Request Method: DELETE

Url: https://eft.ppay.io/api/v1/express

Parameters:

Attribute Type Description Required
id integer 100 OR→reference
reference string merchant unique reference OR→id
organisation_id integer Partners only No

Examples

Cancel From ID 

curl --request DELETE  -u validusername:validpassword --url https://eft.ppay.io/api/v1/express --header 'content-type: application/x-www-form-urlencoded' --data id={expressTransactionID}

Cancel from Merchant Ref 

curl --request DELETE   -u validusername:validpassword --url https://eft.ppay.io/api/v1/express --header 'content-type: application/x-www-form-urlencoded' --data reference={yourReference}

Response


{
	"id": {expressTransactionID},
	"status": "deleted"
}

Payment Setup

The payment key is a setup identifier for each payment and required by EFTsecure and Checkout integrations.

Url: https://eft.ppay.io/api/v1/payment-key

The response will contain a key that can be used for the checkout widget or redirect.

Important notes for EFT payments

  • If sending custom beneficiary bank details the hash field is required.
    You must add an API salt in your organisation's settings under the general tab for this.
    To generate the hash concatenate the beneficiary_account_number, beneficiary_name, beneficiary_account_type,
    beneficiary_bank fields and your API salt in that order. Convert the string to lower case then hash that string using SHA-256 algorithm.
    See code examples below on how to generate in different programming languages.
  • Listed beneficiary account can be set as a string or an associative array to set a different account per bank eg. listed_beneficiary_account[absa] = 'value1'; listed_beneficiary_account[fnb] = 'value2';

Shared parameters:

Attribute Type Description Required
token Auth token ie. c8e542542bcd6b35a5bb708a6df66f08 If no basic auth
amount decimal[10,2] 10.00 Yes
merchant_reference string transaction reference for merchant Yes
customer_reference string transaction reference for customer No
success_url string Redirect url for success No
error_url string Redirect url on error No
cancel_url string Redirect url on cancel No
notify_url string Webhook for getting notified about results No
payment_type string Which payment type to offer the customer
eg. [eft,credit_card,capitec_pay]
Will determine hosted endpoint in response.		 No
currency_code string Country currency code, will return supported services for that currency
eg. [ZAR, NGN]
Will default to the organisation default currency		 No

EFT payment parameters:

Attribute Type Description Required
customer_bank string For pre-selecting a bank for the first step No
listed_beneficiary_account string OR associative array(see above**) The account number reference for the customer if merchant is public listed beneficiary at the bank No
default_beneficiary_reference string The default reference when creating the beneficiary. Useful for account numbers. No
beneficiary_account_number string To override beneficiary account number. No
beneficiary_name string To override beneficiary name. No *required if beneficiary account number set
beneficiary_account_type string Beneficiary account type
[cheque, savings, transmission]		 No *required if beneficiary account number set
beneficiary_bank string Beneficiary account number bank
[ABSA, Nedbank, Capitec, FNB, Standard, Investec] 		No *required if beneficiary account number set
hash string A sha256 hash of account details and API salt No *required if beneficiary account number set
eft_token guid Eft Token to be used for recurring transactions
Note: This can only be sent if payment_type is eft		 No
customer_id string For pre-populating a customer national South African ID for the first step via Capitec Pay No *required if customer national South African ID set via service Capitec Pay only

Credit Card payment parameters:

Attribute Type Description Required
card_token guid Credit Card Token to be used for recurring transactions
Note: This can only be sent if payment_type is credit_card		 No
card_token_3ds boolean(0 or 1) Enable/Disable 3ds for Credit Card token payment if gateway supports it No (will default to backend setting)

Fetch payment key example

Request example

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/payment-key -d "amount=1&merchant_reference=testref123"

Response


{
    "key": "4ea1ea853463dab5b24f7066c1fc8f4b",
    "url": "https://eft.ppay.io/eft?payment_key=4ea1ea853463dab5b24f7066c1fc8f4b",
    "origin": "https://eft.ppay.io"
}

EFT beneficiary hash examples


// PHP
$stringToHash = $beneficiary_account_number.$beneficiary_name.$beneficiary_account_type.$beneficiary_bank.$api_salt;
$hash = hash('sha256', strtolower($stringToHash));

// RUBY
require 'digest'
stringToHash = beneficiary_account_number+beneficiary_name+beneficiary_account_type+beneficiary_bank+api_salt;
hash = Digest::SHA256.hexdigest(stringToHash.downcase);

// PYTHON
import hashlib
string_to_hash = beneficiary_account_number+beneficiary_name+beneficiary_account_type+beneficiary_bank+api_salt
hash = hashlib.sha256(string_to_hash.lower()).hexdigest()

EFTsecure Introduction

The EFTsecure service is our instant EFT payment method. It requires a customer to login as if on their internet banking system and automates the rest of the payment process and notifies to merchant through web hooks or enterprise api's that the payment has been made. A merchants banking details can be setup under settings→eft in the admin console.

Integration methods:

  • Hosted: Redirect to a secure payment page hosted on our system. We manage the security and redirect back with a result.
  • Self Hosted: EFTsecure's enterprise integration, allows you to change the styling and host on your own pages. Requires a SSL certificate.
  • Checkout: EFTsecure's on page payment popup. Allows payments to be processed on page without leaving the site and still being descoped from PCI compliance. Requires a SSL certificate.

Requirements

  • A unique payment-key securely generated server side.
  • The self hosted and checkout integration requires JQuery 1.* and a SSL certificate hosted page for production.
  • At the moment this is a web based service, if you require a in-app solution you will need to see if your framework supports web views.

EFTsecure Hosted (Redirect)

Our hosted method for instant EFT's requires minimal development.

It requires a redirect to a endpoint which will in turn be the payment page hosted on our platform.

After a payment is complete we can notify your system through our web hooks or you can do a lookup of the transaction.

First you will need to create a payment key. This will be used to setup the payment.

EFTsecure Hosted Example

Sample url to redirect to 


https://eft.ppay.io/eft?payment_key={generatedPaymentKey}

EFTsecure Self Hosted (Enterprise)

This integration method gives you more flexibility and allows you to host it on your own website/platform.

You can apply your own stylesheet or use our bootstrap stylesheet. See framework option in the javascript library.

After a payment is complete we can notify your system through our web hooks or you can do a lookup of the transaction.

First you will need to create a Payment key. This will be used by the library to authenticate every jsonp call and save your initial data.

Then you will need to copy a code snippet (see example below) onto your page which will invoke a EFTsecure javascript plugin. Link to javascript plugin

EFTsecure javascript plugin parameters:

Attribute Type Description Required
key string Payment key generated server side Yes
baseUrl string
Default:https://eft.ppay.io		 Overrides base url for plugin api calls (eg. for white labelled domains) No
formId string
default:"eftx-form"		 The html ID of the form to populate No
titleId string
default:"eftx-title"		 The html ID of the primary heading to populate No
subTitleId string
default:"eftx-subtitle"		 The html ID of the secondary heading to populate No
cssFramework string[plain,bootstrap]
default:"plain"		 How to format the html for the form No
buttonContainerId string Override to specify a specific button container No
onLoadStart callback Executed when form is submitted on each step No
onLoadStop callback Executed when result is received for each step No

Examples

Unstyled example

Add the following to your <head> tag:

                
<!-- If you do not already use jQuery include it  -->
<script type="text/javascript" src="https://code.jquery.com/jquery-1.12.4.min.js"></script>
<script type="text/javascript" src="https://eft.ppay.io/js/eft-secure.min.js"></script>

Copy and paste the following html and insert the dynamic {{parameters}}:


                    

<!-- Eftx plain START -->
<h1 id="eftx-title">Initialising Transaction</h1>
<div>Merchant: {{merchantName}} ({{merchantBank}}), Amount: {{currencyFormattedAmount}}</div>
<h2 id="eftx-subtitle"></h2>
<div id="loader" style="display: none;">Loading...</div>
<form id="eftx-form" autocomplete="false"></form>
<div style="clear:both"></div>
<div id="eftx-button-container"></div>
<script>
    $(document).ready(function() {
        new Eftx({
            key: "{{paymentKey}}",
            formId: "eftx-form",
            titleId: "eftx-title",
            subTitleId: "eftx-subtitle",
            cssFramework: "plain",
            buttonContainerId: "eftx-button-container",
            //onCancelUrl: "{{yourCancelUrl}}",
            //onCompleteUrl: "{{yourCompleteUrl}}",
            onLoadStart: function(){
                $("#loader").hide();
                $("#eftx-form").hide();
                $("#eftx-button-container").hide();
                //Do other stuff here
            },
            onLoadStop: function(){
                $("#loader").addClass("hide");
                $("#eftx-form").show();
                $("#eftx-button-container").show();
                //Do other stuff here
            }
        });
    });
</script>
<!-- Eftx plain END -->

Boostrap styled example

Add the following to your <head> tag:

                
<!-- If you do not already use jQuery include it  -->
<script type="text/javascript" src="https://code.jquery.com/jquery-1.12.4.min.js"></script>
<script type="text/javascript" src="https://eft.ppay.io/js/eft-secure.min.js"></script>
<link rel="stylesheet" type="text/css" href="https://eft.ppay.io/css/eftx.css">

Copy and paste the following html and insert the dynamic {{parameters}}:


                    

<!-- Eftx boostrap START -->
<div class="eft modal" id="eftxModal" tabindex="-1" role="dialog" aria-labelledby="title">
    <div class="modal-dialog" role="document">
        <div class="modal-content">
            <div class="modal-header">
                <h4 class="modal-title pull-left" id="eftx-title">Initialising Transaction</h4>
                <h4 class="modal-title pull-right">Amount: {{currencyFormattedAmount}}</h4>
                <div class="clearfix"></div>
                <div>Merchant: {{merchantName}} ({{merchantBank}})</div>
            </div>
            <div class="modal-body">
                <h4 id="eftx-subtitle"></h4>
                <div class="eftx-loader">
                    <div class="container">
                        <div class="loader">
                            <div class="loader--dot"></div>
                            <div class="loader--dot"></div>
                            <div class="loader--dot"></div>
                            <div class="loader--dot"></div>
                            <div class="loader--dot"></div>
                            <div class="loader--dot"></div>
                            <div class="loader--text"></div>
                        </div>
                    </div>
                </div>
                <form id="eftx-form" autocomplete="false"></form>
                <div class="clearfix"></div>
            </div>
            <div class="modal-footer" id="eftx-button-container">
            </div>
        </div>
    </div>
</div>
<script type="text/javascript">
    $(document).ready(function() {
        new Eftx({
            key: "{{paymentKey}}",
            //enum[bootstrap, none]
            cssFramework: "bootstrap",
            buttonContainerId: "eftx-button-container",
            //onCancelUrl: "{{yourCancelUrl}}",
            //onCompleteUrl: "{{yourCompleteUrl}}",
            backgroundEnabled: true,
            onLoadStart: function(){
                $(".eftx-loader").removeClass("hide"); $("#eftx-form").hide();
                $(".modal-footer button").hide();
                //Do other stuff here
            },
            onLoadStop: function(){
                $(".eftx-loader").addClass("hide"); $("#eftx-form").show();
                $(".modal-footer button").show();
                //Do other stuff here
            }
        });
    });
</script>
<!-- Eftx bootstrap END -->

Credit Card Payments

A service for accepting Credit Card payments via Redirect, Checkout, Server to Server.

Integration methods:

  • Redirect: Redirect to a secure payment page hosted on our system. We manage the security and redirect back with a result.
  • Checkout: The on page payment popup. Allows payments to be processed on page without leaving the site and still being descoped from PCI compliance. Requires a SSL certificate.
  • Server to Server: a Self hosted option for Credit Card payments, Note that this will place you in scope for PCI Compliance.

Requirements

  • A unique payment-key securely generated server side.
  • The self hosted and checkout integration requires JQuery 1.* and a SSL certificate hosted page for production.
  • At the moment this is a web based service, if you require a in-app solution you will need to see if your framework supports web views.

Credit Card Hosted (Redirect)

Our hosted method for instant Credit Cards requires minimal development.

It requires a redirect to a endpoint which will in turn be the payment page hosted on our platform.

After a payment is complete we can notify your system through our web hooks or you can do a lookup of the transaction.

First you will need to create a payment key. This will be used to setup the payment.

Server to Server

Server to server ZAR credit card payments

Request Method: POST

Url: https://eft.ppay.io/api/v1/pay/direct

Responses of type "result":
Transaction result received and can be details directly available in the response.

You must check the status of the transaction in api result or webhook body by checking the "status" field

Available statuses:

Status Description
complete has been completed/settled succesfully
failed transaction has failed
refunded transaction has been refunded
partially-refunded transaction has been partially refunded

Responses of type "3ds_redirect":
3D authentication is required by the gateway. Customer will need to be redirected to the specified url and transaction can be reconciled using the redirect or webhook response..

NB: We strongly recommend implementing webhooks since redirects can fail for a variety of reasons. If using only using the redirect result we strongly recommend confirming the status and amount via the View Transaction API call

Post parameters:

Attribute Type Description Required
pan number Credit card number Yes
expiry string {m}{y} ie 1220 yes
cvv number 3 to 5 digits yes
amount decimal (ZAR) ie. 10.00 Yes
merchant_reference string max 20 chars yes
first_name string max 20 chars no
last_name string max 20 chars no
return_url string to return from auth if 3ds enabled
notify_url string Server to server webhook no

Fields for 3D Secure 2:
These fields are optional, however might be required when using certain payment gateways with 3D Secure 2.

Post parameters:

Attribute Type Example
screen_color_depth string 24
java_enabled string True
navigator_language string en-US
window_inner_height string 390
window_inner_width string 1848
timezone string -120
navigator_user_agent string Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:90.0) Gecko/20100101 Firefox/90.0

Pay Direct examples

cURL: Non 3Ds enabled Card/Payment 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/pay/direct -d "amount=1.00&merchant_reference=yourReference&pan=4242424242424242&expiry=1223&cvv=123&first_name=John&last_name=Doe"

Response

                
{
  "type": "result",
  "transaction": {
    "id": 1356875,
    //Payment success flag
    "successful": 1,
    "status": "complete",
    "amount": "1.00",
    //Reason to be used if not successfull
    "reason": "n/a",
    "displayAmount": "R1.00",
    "currency": "ZAR",
    "merchant_reference": "yourReference",
    "gateway_reference": "8ac7a4a068f0543a0169050233c8335c",
    "payment_key": "0cd95fd9adabdc00275fdf6eef675950",
    "created": "2019-02-19 09:07:02",
    "refunded_amount": "0.00",
    "refunded": 0,
    "service": "Direct",
    "gateway": "Peach Payments",
    //Dynamic gateway response. Different per gateway
    "gateway_response_parameters": {...}
  }
}

cURL: 3Ds enabled Card/Payment 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/pay/direct -d "amount=1.00&merchant_reference=yourReference&pan=4242424242424242&expiry=1223&cvv=123&first_name=John&last_name=Doe&return_url=http://myreturnurl.com"

Response

                
{
  "type": "3ds_redirect",
  "redirect_url": "https://eft.ppay.io/gatewaytransactions/3ds/?transactionID=1356876",
  "gateway_transaction_id": "1356876"
}

Credit Card Tokenisation

Token Payment Methods:

Token Payments

Tokenisation Methods:

  • Server to Server (non 3Dsecure): Self hosted option, only available for non #d payments.
  • Checkout: Pass card token parameter to payment key Api call, and skip first card collection step for payment.
  • Redirect: Pass card token parameter to payment key Api call, and skip first card collection step for payment.

Realtime EFT Introduction

The RealtimeEFT service is a bank account monitoring service to automatically recon any payments made to that account. It does not instantly confirm interbank payments but works on the same principals as EFTsecure. It requires a customer to login into their internet banking platform, make a payment to the required banking details and notifies to merchant through web hooks or enterprise api's that the payment has been made. A merchants monitoring banking details can be setup under Settings → Service Settings →Realtime Eft in the admin console.

Integration methods:

  • Checkout: Realtime EFT's on page payment popup. Allows payments to be processed on page without leaving the site and still being descoped from PCI compliance. Requires a SSL certificate.

Requirements

  • A unique payment-key securely generated server side.
  • The checkout integration requires JQuery 1.* and a SSL certificate hosted page for production.
  • At the moment this is a web based service, if you require a in-app solution you will need to see if your framework supports web views.

Checkout Widget

This integration method allows you to host EFT, Credit Card, Capitec Pay payments on your own website/platform and still descope you from PCI compliance.

NB: A SSL certificate is required to ensure compatibility with the frame.

First you will need to create a Payment key. This will be used by the widget to authenticate the payment in the frame.

NB: When creating a payment key you must specify the redirect success and error urls, if not set page will redirect to default receipt page after transaction

You will need to copy a code snippet (see example below) onto your page which will invoke a EFTsecure checkout widget. Click here to view a live example

Checkout widget parameters:

Attribute Type Description Required
paymentKey string Payment key generated server side Yes
paymentType string
 Force payment type [eft,credit_card,capitec_pay] No
onLoad event Override for example re-enable payment button No
cardOptions object Enable Card options Eg. "rememberCard" default value 0 No

Checkout Example

Add the following to your <head> tag:

                
<!-- If you do not already use jQuery include it  -->
<script type="text/javascript" src="https://code.jquery.com/jquery-1.12.4.min.js"></script>
<!-- The data-origin attribute value is the origin value returned from the payment key API call  -->
<!-- Also ensure that the id attribute is set to og-checkout -->
<script type="text/javascript" src="https://eft.ppay.io/ext/checkout/v3/checkout.js" id="og-checkout" data-origin="https://eft.ppay.io"></script>

Copy and paste the following html and insert the dynamic {{parameters}}:


                    

<form id="#payment-form" action="/checkout?confirm=1" style="margin-top: 50px">
    <div class="text-center">
        <button id="pay-button" class="btn btn-primary btn-sx" type="button" data-payment-key="{{paymentKey}}">Pay</button>
    </div>
</form>
<script type="text/javascript">

        $(function() {
            $('#pay-button').on('click', function() {
                $(this).hide();
                var paymentKey = $(this).data('payment-key');
                eftSec.checkout.init({
                    paymentKey: paymentKey,
                    paymentType: 'credit_card', // optional: force payment type
                    onLoad: function() {
                        $('#pay-button').show();
                    },
                    cardOptions: { //optional for Tokenizing Card
                        rememberCard: false,
                        rememberCardDefaultValue: 0
                    },
                });
            });
        });
</script>

Capitec Pay

This payment type requires a user to input personal information after being selected. When user details are submitted, a redirect to the Capitec-Pay application will occur to complete the transaction process.

Accept payments as an option through the checkout widget.

First you will need to create a payment key. This will be used to setup the payment.

Then you will need to initialise the checkout widget with either all payment methods or specify a payment type by passing the paymentType parameter: checkout.

This integration method allows you to host Capitec Pay payments on your own website/platform and still descope you from PCI compliance.

NB: A SSL certificate is required to ensure compatibility with the frame.


Checkout widget parameters:

Attribute Type Description Required
paymentKey string Payment key generated server side Yes
paymentType string
 capitec_pay Yes

Alternative parameters:

Attribute Type Description Required
paymentKey string Payment key generated server side Yes
paymentType string
 eft Yes
customer_bank string For pre-selecting a bank for the first step => capitec_pay Yes

Please note: The below values can be used when doing DEMO/TEST transactions.

Attribute Value Description Type
mobile_number 0834414411 For populating a mobile number on the first step via Capitec Pay string
customer_id 6602025800084 For pre-populating a customer national South African ID on the first step via Capitec Pay string
Description of "status" string:

You can view the status of the transaction in the redirect URL, via lookup API or webhook body by examining the "status" field.

Available statuses:

Status Description
complete The transaction has been completed or settled successfully.
failed The transaction has failed.
aborted The transaction has been aborted or timed out.

Capitec Pay webhook payload examples

In settings you can configure your success, refund and error webhook urls. The result will be sent as an HTTP POST request in the following format:

Webhook success/failed sample post request 

                
                POST = [ 
                    'success' => {1 or 0}
                    'status' => {statusString}
                    'organisation_id' => {merchant_id}
                    'amount' => {amount}
                    'callpay_transaction_id' => {gateway_transaction_id}
                    'reason' => ‘{reasonForFailureIfApplicable}’
                    'user' => ‘{paymentUser}’
                    'merchant_reference' => ‘{merchant_reference}’
                    'gateway_reference' => ‘{psp_reference}'
                    'gateway_response' => ‘{additionalDataFromPSP}’
                    'currency' => ‘{currency}’
                    'payment_key' => ‘{payment_key}’
                ]

Capitec Pay redirect examples

Redirect success/failed sample response:

Successful Redirect 

                
                    
URL: 'your_endpoint_url'?status=complete&merchant_reference=‘{merchant_reference}’&transaction_id={gateway_transaction_id}&organisation_id={merchant_id}

Failed Redirect 

                
                    
URL: 'your_endpoint_url'?status=failed&merchant_reference=‘{merchant_reference}’&transaction_id={gateway_transaction_id}&organisation_id={merchant_id}&reason=capitec%20pay%20transaction%20failed

Aborted Redirect 

                
                    
URL: 'your_endpoint_url'?status=aborted&merchant_reference=‘{merchant_reference}’&transaction_id={gateway_transaction_id}&organisation_id={merchant_id}&reason=capitec%20pay%20transaction%20timed%20out

Capitec Pay lookup examples

We do not have static IPs to whitelist and we recommend doing lookup api calls:
Payments: /api/v1/gateway-transaction/$GATEWAY_TRANSACTION_ID

Lookup success/failed sample response 

                
                POST = [
                    'id' {gateway_transaction_id},
                    'successful' => {1 or 0},
                    'status' => {statusString},
                    'amount' => {amount},
                    'reason' => '{reasonForFailureIfApplicable}’,
                    'displayAmount' => '{displayAmount}',
                    'currency' => '{currency}',
                    'gateway_reference' => ‘{psp_reference}',
                    'payment_key' => ‘{payment_key}’,
                    'created' => '{date and time of transaction}',
                    'refunded_amount' => '{refundedAmount}',
                    'refunded' => '{refundedAmount}',
                    'service' => '{service type}',
                    'gateway' => '{gateway}',
                    'gateway_response_parameters' => '{additionalDataFromPSP}',
                    'call' => '{call}',
                    'location' => '{location}',
                    'signature' => '{signature}',
                    'is_demo_transaction' => '{1 (enabled) or 0 {disabled}}',
                    ]

Recon payment

Create Recon payment

Request Method: POST

Url: https://eft.ppay.io/api/v1/pay/manual

Will add a recon payment entry to the database, payment for each recon payment will have to be confirmed manually by an Administrator in the admin area.

Post parameters:

Attribute Type Description Required
amount decimal ie. 10.00 Yes
merchant_reference string custom merchant reference No
bank_reference string custom reference that appears on customer statement No
payment_date string Must be formatted YYYY-MM-DD HH:MM ie. 2018-03-01 12:30 No

pay/manual example

cURL Recon Payment 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/pay/manual -d "amount=25.00&merchant_reference=your_reference&bank_reference=your_bank_ref&payment_date=2018-03-01 12:30"

Response


{
    "amount":"25.00",
    "reference":"your_reference",
    "bank_reference":"your_bank_ref",
    "payment_date":"2018-03-01 12:30"
}

Payouts (Withdrawals)

Process withdrawals to customer bank accounts. This is batched on intervals or manually.

Note: Cut-off time for same day payouts is 14:30 SAST.

Validate Account

Validate accounts/payouts before queuing.

Request Method: POST

Url: https://eft.ppay.io/api/v1/payout/validate-account

NB: Following are valid banks for transaction[bank] field:
[FNB, ABSA, Standard, Nedbank, Capitec, Investec, Mercantile, Bidvest, Tyme, Windhoek, African Bank, Oldmutual, Discovery, Grindrod, Ubank, Imperial, Firstrand, HSBC, Sasfin, Access, Stdchartered]

NB: Following universal banking branch codes can be used for the transaction[branch] field:
[
fnb => 250655
absa => 632005
standard => 051001
nedbank => 198765
capitec => 470010
investec => 580105
mercantile => 450105
bidvest => 462005
tyme => 678910
windhoek => 483872
afribank => 430000
oldmutual => 462005
discovery => 679000
grindrod => 584000
ubank => 431010
imperial => 39001
firstrand => 201419
hsbc => 587000
sasfin => 683000
access => 410506
stdchartered => 730020
]

A reference is required, this alphanumeric value must be unique. An account will not validate if an existing record has this reference

See curl examples for posting single or multiple transaction on the right

Post parameters:

Attribute Type Description Required
transaction array A single eft transaction for refund, required fields: bank, branch, account, customer_name. optional: reference No
transactions array Multiple eft transactions for refund, required fields bank, branch, account, customer_name. optional field: reference Transactions index must be set No

Validate example

cURL Request for single 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/payout/validate-account -d "transaction[bank]=ABSA&transaction[branch]=632005&transaction[account]=4062221111&transaction[customer_name]=jon%20doe"

Response


    {
        "success": true,
        "message": "Accounts validated successfully",
        "transactions": [
            {
                "bank": "ABSA",
                "branch": "632005",
                "account_type": "cheque",
                "customer_name": "jon doe",
                "account": "4062221111"
            }
        ]
    }

cURL Validate multiple 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/payout/validate-account -d "transactions[0][bank]=ABSA&transactions[0][branch]=632005&transactions[0][account]=4062229111&transactions[0][customer_name]=jon%20doe& transactions[1][bank]=Nedbank&transactions[1][branch]=198765&transactions[1][account]=113622222&transactions[1][customer_name]=jane%20doe"

Response


    {
        "success": true,
        "message": "Accounts validated successfully",
        "transactions": [
            {
                "branch": "632005",
                "account": "4062229551",
                "account_type": "cheque",
                "customer_name": "jon doe",
                "bank": "ABSA"
            },
            {
                "bank": "Nedbank",
                "branch": "198765",
                "account": "113622222",
                "account_type": "savings",
                "customer_name": "jane doe"
            }
        ]
    }

Verify Account

Verify accounts/payouts before queuing.

Request Method: POST

Url: https://eft.ppay.io/api/v1/payout/verify-account

NB: Following universal banking branch codes can be used for the branchCode field:
[
fnb => 250655
absa => 632005
standard => 051001
nedbank => 198765
capitec => 470010
investec => 580105
mercantile => 450105
bidvest => 462005
tyme => 678910
windhoek => 483872
afribank => 430000
oldmutual => 462005
discovery => 679000
grindrod => 584000
ubank => 431010
imperial => 39001
firstrand => 201419
hsbc => 587000
sasfin => 683000
access => 410506
stdchartered => 730020
]

identification_type possible values are:

  • SID – South African ID
  • SPP – Passport number
  • SBR – Business registration number
  • TRN – Trust number

See curl examples for posting a single transaction on the right

Post parameters:

Attribute Type Description Required
transaction array A single eft transaction for verification, required fields: account_type, account_number, branch_code, identification_type, identification_number, name .optional fields: initials, email_address, cell_number Yes

Verify example

cURL Request for single 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/payout/verify-account -d "transaction[account_type]=current&transaction[account_number]=1002301378&transaction[branch_code]=145710&transaction[identification_type]=SPP&transaction[identification_number]=HG7072J76211&transaction[name]=DOE&transaction[initials]=JD"

Response


    {
        "success": true,
        "transactions": [
            {
                "status": "Success",
                "customerReference": "Ref1698652238",
                "accountExists": "Yes",
                "identificationNumberMatched": "No",
                "initialsMatched": "No",
                "nameMatched": "No",
                "accountActive": "Yes",
                "accountDormant": "No",
                "accountActive3Months": "Yes",
                "canDebitAccount": "Yes",
                "canCreditAccount": "Yes",
                "taxReferenceMatch": "Unprocessed",
                "accountTypeMatch": "Yes",
                "emailMatched": "Unprocessed",
                "cellNumberMatched": "Unprocessed",
                "completeMatch": "Unprocessed"
            }
        ]
    }

Queue Payout

Queues a payout for batching.
Batching can be done periodically by the merchant or partner as required. Batching cut off times for same day payouts is 13:30 SAST.

Request Method: POST

Url: https://eft.ppay.io/api/v1/payout/queue

NB: Following are valid banks for transaction[bank] field:
[FNB, ABSA, Standard, Nedbank, Capitec, Investec, Mercantile, Bidvest, Tyme, Windhoek, African Bank, Oldmutual, Discovery, Grindrod, Ubank, Imperial, Firstrand, HSBC, Sasfin, Access, Stdchartered]

NB: Following universal banking branch codes can be used for the transaction[branch] field:
[
fnb => 250655
absa => 632005
standard => 051001
nedbank => 198765
capitec => 470010
investec => 580105
mercantile => 450105
bidvest => 462005
tyme => 678910
windhoek => 483872
afribank => 430000
oldmutual => 462005
discovery => 679000
grindrod => 584000
ubank => 431010
imperial => 39001
firstrand => 201419
hsbc => 587000
sasfin => 683000
access => 410506
stdchartered => 730020
]

NB: Following are valid account types for transaction[account_type] field:
[cheque, savings, transmission]

A reference is required, this alphanumeric value must be unique. An account will not be saved if an existing record has this reference

See curl examples for posting single or multiple transaction on the right

Post parameters:

Attribute Type Description Required
transaction array A single eft transaction for refund, required fields bank, branch, account, customer_name, amount. optional field: reference No
transactions array Multiple eft transactions for refund, required fields bank, branch, account, customer_name, amount. optional field: reference. Transactions index must be set No

Payouts queue accounts example

cURL Request for single 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/payout/queue -d "transaction[bank]=ABSA&transaction[amount]=100&transaction[branch]=632005&transaction[account]=4062221111&transaction[customer_name]=jon%20doe&transaction[reference]=1234"

Response


    {
        "success": true,
        "message": "Accounts successfully saved",
        "total_amount": 100,
        "transactions": [
            {
                "bank": "ABSA",
                "amount": "100",
                "branch": "632005",
                "customer_name": "jon doe",
                "account_type": "cheque",
                "reference": "1234",
                "account": "4062221111",
                "id": 19721
            }
        ]
    }

cURL Request for multiple 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/payout/queue -d "transactions[0][bank]=ABSA&transactions[0][amount]=100&transactions[0][branch]=632005&transactions[0][account]=4062229111&transactions[0][customer_name]=jon%20doe&transactions[1][bank]=Nedbank&transactions[1][amount]=50.50&transactions[1][branch]=198765&transactions[1][account]=113622222&transactions[1][customer_name]=jane%20doe"

Response


    {
        "success": true,
        "message": "Accounts successfully saved",
        "total_amount": 150.50,
        "transactions": [
            {
                "branch": "632005",
                "account": "4062229551",
                "amount": "100",
                "customer_name": "jon doe",
                "account_type": "cheque",
                "bank": "ABSA",
                "id": 19722
            },
            {
                "bank": "Nedbank",
                "branch": "198765",
                "amount": "50.50",
                "account": "113622222",
                "account_type": "savings",
                "customer_name": "jane doe",
                "id": 19723
            }
        ]
    }

View payout

Retrieves information about a payout by ID.

NB: Payouts are not realtime. They are sent in batches to the banks and are considered paid out until the bank let us know otherwise. This API call is mainly to confirm information for the payout and could also be used to know when it was batched.

Request Method: GET

Url: https://eft.ppay.io/api/v1/payout/$PAYOUT_TRANSACTION_ID

Returned attributes:

Attribute Type Description
bank string Customer bank eg. Nedbank
branch integer Bank branch number
account integer Customer account number
amount integer Amount to be paid out
customer_name string Customer name
external_reference string batch reference, if not batched yet will be null
batch_date date The date batched, if not batched yet will be null
status string The status of the Payout, possible statuses pending, batched, processing and rejected.
payout_estimated_date date an estimate of the payout date, if not batched yet will be null

View payout transaction example

cURL Request 

curl -X GET -u validusername:validpassword https://eft.ppay.io/api/v1/payout/100

Response


    {
        "bank": "Nedbank",
        "branch": "198765",
        "account": "1136236759",
        "amount": "120.00",
        "customer_name": "John Doe",
        "external_reference": "3CALLFINRE000126",
        "batch_date": "2017-02-16 06:35:17",
        "status": "batched",
        "payout_estimated_date": "2017-02-16"
    }

Payout widget link

This API call creates a payout key and link for the payout widget. This widget allows a customer to fill in a their bank account details and save it. The payout that is saved will be queued and can be batched from the admin area..

Request Method: POST

Url: https://eft.ppay.io/api/v1/payout/key

Post parameters:

Attribute Type Description Required
amount decimal[10,2] Amount of payout Yes
customer_name string The customer name Yes
reference string The unique reference for payout Yes
redirect_url string URL to redirect to after payout successfully captured by customer Yes
cancel_url string URL to redirect to if transaction cancelled Yes

Get payout widget link example

cURL Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/payout/key

Response


    {
      "key": "a05a9b4e8922c698d05916027d666b38",
      "url": "https://eft.ppay.io/payouts/widget?key=a05a9b4e8922c698d05916027d666b38"
    }

Webhook

This webhook is only for rejection notices. This can happen after a payout has a batched status to the bank and days later we get a notification from the bank that the payout was indeed rejected.


Notes:

  • Webhook needs to be configured statically in Settings > Payouts
  • Currently there is no simulation mode for payouts, see example payload below.

Rejection webhook payload (POST variables, not JSON):


    {
      "success" : true,
      "action" : 'Rejections',
      "message" : 'Rejections received',
      "transactions" : [
        {
          "amount": 1,
          "customer_name":'john doe',
          "reference": 'your payout reference',
          "batch_date": '2018-08-30 18:31:17',
          "bank": 'Nedbank',
          "account": '0123123123123',
          "reason": 'ACCOUNT BLOCKED'
       }
      ]
    }

cURL simulation: 

curl -X POST {webhook_url} -d "success=1&action=Rejections&message=Rejections+received&transactions%5B0%5D%5Bamount%5D=50&transactions%5B0%5D%5Bcustomer_name%5D=T+Testing&transactions%5B0%5D%5Breference%5D=MYTEST1&transactions%5B0%5D%5Bbank%5D=Absa&transactions%5B0%5D%5Baccount%5D=9270445366&transactions%5B0%5D%5Breason%5D=Incorrect+Account+Code"

Transaction, Recon & Exports

Allows you to view/confirm or list a organisation transactions.

List organisation transactions

Fetch all transactions for an organisation by organisation id.' Organisation id is required in url

Request Method: GET

Url: https://eft.ppay.io/api/v1/organisation/$ORGANISATION_ID/gateway-transaction

Returned attributes per transaction:

Attribute Type Description
id integer unique primary key for transaction
successful integer integer indicating whether transaction was successful or not (1 being true 0 being false)
amount decimal transaction amount
gateway_reference text payment gateway reference number
created date date and time of transaction
service text name of service used by agent
from_date date (dd-mm-yyyy) Where date >=
to_date date (dd-mm-yyyy) Where date <=

List organisation transactions example

cURL Request 

curl -X GET -u validusername:validpassword https://eft.ppay.io/api/v1/organisation/$ORGANISATION_ID/gateway-transaction

Response


[
    {
        "id": 166,
        "successful": 1,
        "amount": "123.00",
        "gateway_reference": "Gateway_merchant_ref_1434026074",
        "created": "2015-06-11 12:34:34",
        "service": "Scan Card"
    },
    {
        "id": 167,
        "successful": 1,
        "amount": "123.00",
        "gateway_reference": "Gateway_merchant_ref_1434026303",
        "created": "2015-06-11 12:38:23",
        "service": "POS"
    },
    {
        "id": 168,
        "successful": 1,
        "amount": "123.00",
        "gateway_reference": "Gateway_merchant_ref_1434027451",
        "created": "2015-06-11 12:57:31",
        "service": "POS"
    }
]

Export transactions (CSV)

Download a csv containing transactions. Can be filtered by the parameters in the table below.

Request Method: GET

Url: https://eft.ppay.io/api/v1/export/gateway-transactions

Filtering attributes:

Parameter Type Description
from_date date (dd-mm-yyyy) Where date >=
to_date date (dd-mm-yyyy) Where date <=

Export CSV example

cURL Request 

curl -X GET  -u validusername:validpassword https://eft.ppay.io/api/v1/export/gateway-transactions?from_date=25-03-2024&to_date=25-04-2024

List transactions by User

Fetch all transactions for user by user id.User id is required in url

Request Method: GET

Url: https://eft.ppay.io/api/v1/user/$USER_ID/gateway-transaction

Returned attributes per transaction:

Attribute Type Description
id integer unique primary key for the transaction
successful integer integer indicating whether transaction was successful or not (1 being true 0 being false)
amount decimal transaction amount
gateway_reference text payment gateway reference number
created date date and time of transaction
service text name of service used by agent

List gateway transactions by user example

cURL Request 

curl -X GET -u validusername:validpassword https://eft.ppay.io/api/v1/user/$USER_ID/gateway-transaction

Response


[
    {
        "id": 166,
        "successful": 1,
        "amount": "123.00",
        "gateway_reference": "Gateway_merchant_ref_1434026074",
        "created": "2015-06-11 12:34:34",
        "service": "Scan Card"
    },
    {
        "id": 167,
        "successful": 1,
        "amount": "123.00",
        "gateway_reference": "Gateway_merchant_ref_1434026303",
        "created": "2015-06-11 12:38:23",
        "service": "POS"
    },
    {
        "id": 168,
        "successful": 1,
        "amount": "123.00",
        "gateway_reference": "Gateway_merchant_ref_1434027451",
        "created": "2015-06-11 12:57:31",
        "service": "POS"
    }
]

View Transaction

View transaction by id. Will be sent back as single object and status 200. Transaction id is required

Request Method: GET

Url: https://eft.ppay.io/api/v1/gateway-transaction/$GATEWAY_TRANSACTION_ID

Returned attributes:

Attribute Type Description
id integer unique primary key for transaction
successful integer integer indicating whether transaction was successful or not (1 being true 0 being false)
amount decimal transaction amount
gateway_reference text payment gateway reference number
created date date and time of transaction
service text name of service used by agent

Fetch transaction example

cURL By ID 

curl -X GET -u validusername:validpassword https://eft.ppay.io/api/v1/gateway-transaction/$GATEWAY_TRANSACTION_ID
OR

cURL By merchant reference 

curl -X GET -u validusername:validpassword https://eft.ppay.io/api/v1/gateway-transaction/?reference=$MERCHANT_REFERENCE
OR

cURL By payment key 

curl -X GET -u validusername:validpassword https://eft.ppay.io/api/v1/gateway-transaction/?key=$PAYMENT_KEY

Response


{
  "id": 11111,
  "successful": 1,
  "status": "complete",
  "amount": "5.00",
  "reason": "n/a",
  "displayAmount": "R5.00",
  "currency": "ZAR",
  "merchant_reference": "1111111-11111-1111",
  "gateway_reference": "11111111-0000-0000-0000-000000000000",
  "payment_key": "19440ff6006e2179ea4bbd6b470693ee",
  "created": "2021-02-18 11:59:58",
  "refunded_amount": "0.00",
  "refunded": 0,
  "service": "Direct",
  "gateway_response_parameters": {
    "accountFrom": "30",
    "accountTo": "00",
    "amount": 500,
    "authCode": "843199",
    "card": "424242*****4242",
    "cardName": "Diners",
    "cardToken": "1111111-1111-1111-1111-1111111",
    "currency": "710",
    "dmsIndicator": false,
    "echo": "52857350-dd49-46df",
    "pos": "00173138",
    "reference": "22117406-0000-0000-0000-000000000000",
    "responseCode": "00",
    "responseText": "Approved",
    "rrn": "00001111111",
    "seq": "1111111",
    "store": "000000001111111",
    "storeDetails": {
      "city": "Cape Town    ",
      "country": "ZA",
      "name": "Store name",
      "region": "WC"
    },
    "tran": "00",
    "tranQualifier": "008601",
    "gatewayCardToken": "1111111-1111-1111-1111-1111111",
    "card_token": "1111111-1111-1111-1111-1111111", // Token to be re-used
    "bin": "424242"
  },
  "call": "",
  "location": "",
  "signature": null,
  "is_demo_transaction": 1,
  "token": "1111111-1111-1111-1111-1111111", // Token to be re-used
}

Refund a transaction

Some gateways supports refund capability of the full amount.

Request Method: PUT

Url: https://eft.ppay.io/api/v1/gateway-transaction/refund/{$transaction_id}

By default this will refund the complete transaction amount.

Attribute Type Description
amount float Optional. Amount lower or equal to the transaction amount.

Refund a transaction

cURL Request 

curl -X PUT -u validusername:validpassword https://eft.ppay.io/api/v1/gateway-transaction/refund/12345678

Response


{
    "result": true
}

Resend a webhook

This API call allows you to resend a webhook for a transaction.

Request Method: POST

Url: https://eft.ppay.io/api/v1/gateway-transaction/resend-webhook/{$gateway_transaction_id}

This will allow you to resend your webhook and the API call requires a custom URl to attribute

Attribute Type Description Required
url string URL to post webhook data to Yes

Resend webhook example

cURL Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/gateway-transaction/resend-webhook/{$gateway_transaction_id} -d 'url=https://yoursite.com/webhook-endpoint'

Response


{
  "success": true,
  "message": "Webhook has been queued successfully"
}

User

Allows you manage organisation users.

List all Users

Fetch all users for an organisation by organisation id.' Organisation id is required in url

Request Method: GET

Url: https://eft.ppay.io/api/v1/organisation/$ORGANISATION_ID/user

Returned attributes per user:

Attribute Type Description
id integer unique primary key for user
name text user first name
lastname text user last name
username text user username
email valid email address user email address
contact_number integer user contact number
organisation_id integer user organisation id
created date date user was created
extension integer If user is type agent will return an extension for him/her

List all example

cURL Request 

curl -X GET -u validusername:validpassword https://eft.ppay.io/api/v1/organisation/$ORGANISATION_ID/user

Response


[
    {
        "id": 2,
        "name": "John",
        "lastname": "Doe",
        "username": "johndoe",
        "email": "johndoe@merchantcompany.co.za",
        "contact_number": 0821234567,
        "organisation_id": 3,
        "created": "2015-02-03 14:19:39",
        "extension": "4444"
    },
    {
        "id": 3,
        "name": "Joe",
        "lastname": "Doe",
        "username": "joedoe",
        "email": "joedoe@merchantcompany.co.za",
        "contact_number": 0821234567,
        "organisation_id": 3,
        "created": "2015-02-03 14:19:39",
        "extension": "5555"
    }
]

View User

View existing user by User id. Will be sent back as single object and status 200. User id is required

Request Method: GET

Url: https://eft.ppay.io/api/v1/user/$USER_ID

Returned attributes:

Attribute Type Description
id integer unique primary key for user
name text user first name
lastname text user last name
username text user username
email valid email address user email address
contact_number integer user contact number
organisation_id integer user organisation id
created date date user was created
extension integer If user is type agent will return an extension for him/her

View example

cURL Request 

curl -X GET -u validusername:validpassword https://eft.ppay.io/api/v1/user/3

Response


{
    "id": 3,
    "name": "Joe",
    "lastname": "Doe",
    "username": "joedoe",
    "email": "joedoe@merchantcompany.co.za",
    "contact_number": 0821234567,
    "organisation_id": 3,
    "created": "2015-02-03 14:19:39",
    "extension": "5555"
}

Create User

Create new user Will be send back a single object (see View User for returned attributes) and status 201 (Created).

Request Method: POST

Url: https://eft.ppay.io/api/v1/user

User Post parameters: post as User[$ATTRIBUTE]

Attribute Type Description Required
username text user username Yes
role valid user role See list of user roles Yes
password text user password No
name text user first name No
lastname text user last name No
email valid email address user email address No
contact_number integer user contact number No

Create example

cURL Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/user -d "User[username]=unique&User[role]=agent"

Response


{
    "id": 8,
    "name": null,
    "lastname": null,
    "username": "unique",
    "email": null,
    "contact_number": null,
    "organisation_id": 3,
    "created": "2015-02-03 14:19:39",
    "extension": null
}

Update User

Update existing organisation by User id.User id is required in url'); ?>

Request Methods: PUT

Url: https://eft.ppay.io/api/v1/user/$USER_ID

User Put parameters: post as User[$ATTRIBUTE]

Attribute Type Description
username text user username
password text user password
role valid user role See list of user roles
name text user first name
lastname text user last name
email valid email address user email address
contact_number integer user contact number

Update example

cURL Request 

curl -X PUT -u validusername:validpassword https://eft.ppay.io/api/v1/user/8 -d "User[name]=Jason"

Response


{
    "id": 8,
    "name": "Jason",
    "lastname": null,
    "username": "unique",
    "email": null,
    "contact_number": null,
    "organisation_id": 3,
    "created": "2015-02-03 14:19:39",
    "extension": null
}

Organisation

Allows you manage your merchant organisations.

List all organisations

Fetch all merchant organisations belonging to your company. Will be sent back as an array of objects

Request Method: GET

Url: https://eft.ppay.io/api/v1/organisation

Returned attributes per organisation:

Attribute Type Description
id integer unique primary key for organisation
name text name of organisation
company_registration text company registration number of organisation
vat_number integer company vat number of organisation
website text company vat number of organisation
contact_email text contact email for organisation
billing_email text billing email for organisation
contact_number integer contact number for organisation

List example

cURL Request 

curl -X GET -u validusername:validpassword https://eft.ppay.io/api/v1/organisation

Response


[
    {
        "id": 1,
        "name": "merchant company",
        "company_registration": null,
        "website": null,
        "vat_number": null,
        "contact_email": "joe@merchantcompany.com",
        "contact_number": null,
        "billing_email": "billing@merchantcompany.com"
    },
    {
        "id": 2,
        "name": "merchant company 2",
        "company_registration": null,
        "website": null,
        "vat_number": null,
        "contact_email": "joe@merchantcompany2.com",
        "contact_number": null,
        "billing_email": "billing@merchantcompany2.com"
    }
]

List all organisation services

Fetch all services belonging to your company. Will be sent back as an array of service slugs

Request Method: GET

Url: https://eft.ppay.io/api/v1/organisation/$ORGANISATION_ID/services

List example

cURL Request 

curl -X GET -u validusername:validpassword https://eft.ppay.io/api/v1/organisation/$ORGANISATION_ID/services

Response


["eft","credit_card","capitec_pay"]

View Organisation

View existing organisation by Organisation id. Will be sent back as single object and status 200. Organisation id is required

Request Method: GET

Url: https://eft.ppay.io/api/v1/organisation/$ORGANISATION_ID

Returned attributes:

Attribute Type Description
id integer unique primary key for organisation
name text name of organisation
company_registration text company registration number of organisation
vat_number integer company vat number of organisation
website text company vat number of organisation
contact_email text contact email for organisation
billing_email text billing email for organisation
contact_number integer contact number for organisation

View example

cURL Request 

curl -X GET -u validusername:validpassword https://eft.ppay.io/api/v1/organisation/2

Response


{
    "id": 2,
    "name": "merchant company 2",
    "company_registration": null,
    "website": null,
    "vat_number": null,
    "contact_email": "joe@merchantcompany2.com",
    "contact_number": null,
    "billing_email": "billing@merchantcompany2.com"
}

Create Organisation

Create new organisation by Organisation id. Will be send back a single object (see View Organisation for returned attributes) and status 201 (Created).

WHEN CREATING A NEW ORGANISATION A DEFAULT ADMIN USER MUST BE CREATED AS WELL. NEW USER PARAMETERS MUST BE POSTED WITH PAYLOAD, SEE CREATE USER

Request Method: POST

Url: https://eft.ppay.io/api/v1/organisation

Services for organisation:
post as array eg.
Organisation[serviceList][] = $SERVICEID1;
Organisation[serviceList][] = $SERVICEID2;
etc.
See list of available services

A physical and billing address is also required
example post:
billingAddress[address_line_1] = '45 Fifth Avenue';
billingAddress[address_line_2] = 'Suburb';
billingAddress[address_line_3] = 'City';
billingAddress[postal_code] = 1234;
Post physical address in same way, eg. physicalAddress[address_line_1]

Organisation Post parameters: post as Organisation[$ATTRIBUTE]

Attribute Type Description Required
name text name of organisation Yes
serviceList array of service ids List of services for organisation posted as array, at least one must be posted on creation of organisation, see available services Yes
billingAddress text See how to post above table Yes
physicalAddress text See how to post above table Yes
contract_type_id integer See contract types Yes
contract_start_date valid date Must be a valid date in the following format MM-YYYY (eg June 2015 will be 06-2015).
NB* must be after current month (eg if it is February 2015 minimum contract date must be March 2015)		 Yes
company_registration text company registration number of organisation No
vat_number integer company vat number of organisation No
website Valid website url company vat number of organisation No
contact_email Valid email address contact email for organisation No
billing_email Valid email address billing email for organisation No
contact_number integer contact number for organisation No
contact_number integer contact number for organisation No

Create example

cURL Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/organisation -d "Organisation[name]=organisation%20name&User[username]=unique&User[password]=password&Organisation[serviceList][]=1&billingAddress[address_line_1]=address%20line%201&billingAddress[address_line_2]=address%20line%202&billingAddress[postal_code]=1234&physicalAddress[address_line_1]=address%20line%201&physicalAddress[address_line_2]=address%20line%202&physicalAddress[postal_code]=1234"  -u validusername:validpassword

Response


{
    "id": 14,
    "name": "organisation name",
    "company_registration": null,
    "website": null,
    "vat_number": null,
    "contact_email": null,
    "contact_number": null,
    "billing_email": null,
    "serviceList": [
        "1"
    ]
}

Add bank details

Add organisation banking details. Organisation id is required in url

Request Method: POST

Url: https://eft.ppay.io/api/v1/organisation/$ORGANISATION_ID/eft-banking-details

Will add banking details for EFT secure.

Limited to one account per bank.

Post parameters:

Attribute Type Description Required
account_number decimal ie. 4061112222 Yes
account_type string bank account type
[cheque, savings, transmission]		 Yes
account_name string Account name eg. My account Yes
branch_code decimal The bank account branch code Yes
bank string The name of the bank
[ABSA, Nedbank, Capitec, FNB, Standard, Investec]		 Yes

example

cURL Request 

curl -X POST -u validusername:validpassword https://eft.ppay.io/api/v1/organisation/10/eft-banking-details -d "account_name=My%20Account&account_number=4062221111&bank=absa&branch_code=632005&account_type=cheque"

Response


{
    "account_name":"My Account",
    "account_number":"4062221111",
    "branch_code":"632005",
    "bank":"absa",
    "bank_account_type":"cheque"
}

Update Organisation

Update existing organisation by Organisation id.Organisation id is required in url'); ?>

Request Methods: PUT

Url: https://eft.ppay.io/api/v1/organisation/$ORGANISATION_ID

Organisation Put parameters: post as Organisation[$ATTRIBUTE]

Attribute Type Description Required
name text name of organisation No
serviceList array of service ids List of services for organisation posted as array No
company_registration text company registration number of organisation No
vat_number integer company vat number of organisation No
website Valid website url company vat number of organisation No
contact_email Valid email address contact email for organisation No
billing_email Valid email address billing email for organisation No
contact_number integer contact number for organisation No
contact_number integer contact number for organisation No

Update example

cURL request 

curl -X PUT -u validusername:validpassword https://eft.ppay.io/api/v1/organisation/5 -d "Organisation[name]=new%20organisation%20name"

Response


{
    "id": 5,
    "name": "New organisation name",
    "company_registration": null,
    "website": null,
    "vat_number": null,
    "contact_email": "joe@merchantcompany2.com",
    "contact_number": null,
    "billing_email": "billing@merchantcompany2.com"
}

Organisation Settings

Allows you update organisation settings.

Update Organisation Settings

Update existing organisation settings by Organisation id. Organisation id is required in url

Request Methods: PUT

Url: https://eft.ppay.io/api/v1/organisation/{$ORGANISATION_ID}/settings

Gateway credentials can be updated in the settings, for example you might want to set your gateway api key and secret for example
OrganisationSetting[gatewayCredentials]['{gateway_parameter}'] eg. OrganisationSetting[gatewayCredentials]['safeKey'] = 'xxx-xxx-xx; '

Settings PUT parameters: post as OrganisationSetting[$ATTRIBUTE]

Attribute Type Description Required
payment_success_uri valid url Successful transaction redirect URI No
payment_error_uri valid url Unsuccessful transaction redirect URI No
gatewayCredentials array of gateway credentials See above No
demo_mode integer 2 options for demo mode: 0 or 1 (Off or On) No
gateway_id integer See list of available gateways No

Update Organisation Settings

cURL Example 

curl -X PUT -u validusername:validpassword https://eft.ppay.io/api/v1/organisation/3/settings -d "OrganisationSetting[demo_mode]=1"

Response Body Example


{
    "organisation_id": 3,
    "payment_success_uri": null,
    "payment_error_uri": null,
    "gateway_id": 2,
    "demo_mode": "1",
    "inbound_did": "*********"
}

Licenses

Allows you to update organisation licenses and activate/deactivate agent licenses.

Update organisation licenses

Update amount of licenses organisation has for a service by Organisation id.Organisation id is required in url

Request Method: PUT

Url: https://eft.ppay.io /api/v1/organisation/$ORGANISATION_ID/licenseupdate

Put parameters: post array of service ids with service id as key and amount of licenses as value
eg. serviceId[$SERVICE_ID_ONE]=$AMOUNT_OF_LICENSES
eg. serviceId[$SERVICE_ID_TWO]=$AMOUNT_OF_LICENSES
See available service IDs

Update example

cURL Request

curl -X PUT -u validusername:validpassword https://eft.ppay.io/api/v1/organisation/10/licenseupdate -d "serviceId[1]=25&serviceId[2]=35"

Response


{
    "Organisation": "Organisation name",
    "Services": {
        "serviceId": {
            "1": "25",
            "2": "35"
        }
    }
}

Activate user

Activate user license for service/s by user id.User id is required in url

Request Method: PUT

Url: https://eft.ppay.io/api/v1/user/$USER_ID/activate

Put parameters: post array of service ids
eg. serviceId[]=$SERVICE_ID_ONE
serviceId[]=$SERVICE_ID_TWO
See available service IDs

Activate user example

cURL Request

curl -X PUT -u validusername:validpassword https://eft.ppay.io/api/v1/user/2/activate -d "serviceId[]=1&serviceId[]=2"

Response


{
    "services": {
            "service_one": "Activated",
            "service_two": "Activated"
        },
    "User": {
            "id": 2,
            "name": "4315",
            "lastname": "4315",
            "email": "4315@yourdomain.co.za",
            "username": "4315"
        }
}

Deactivate user

Deactivate user license for service/s by user id.User id is required in url

Request Method: PUT

Url: https://eft.ppay.io/api/v1/user/$USER_ID/deactivate

Put parameters: post array of service ids
eg. serviceId[]=$SERVICE_ID_ONE
eg. serviceId[]=$SERVICE_ID_TWO
See available service IDs

Deactivate user example

cURL Request 

curl -X PUT -u validusername:validpassword https://eft.ppay.io/api/v1/user/3/deactivate -d "serviceId[]=1&serviceId[]=2"

Response


{
    "services": {
            "service_one": "Deactivated",
            "service_two": "Deactivated"
        },
    "User": {
            "id": 3,
            "name": "4315",
            "lastname": "4315",
            "email": "4315@yourdomain.co.za",
            "username": "4315"
        }
}

Receipts

Send a payment receipt via email or sms

Send a SMS/Email receipt

Use this api call to notify a customer of a successful transaction.
Templates can be set in settings.

Request Method: POST

Url: https://eft.ppay.io/api/v1/notification/send

POST parameters:

Attribute Type Description
recipient text a valid mobile number or email address
type text [Sms, Email]
transactionID bigint a valid transction ID

Example(s)

cURL Request 

curl -X GET -u validusername:validpassword https://eft.ppay.io/api/v1/organisation/1/gateway-transaction -d "recipient=0720000000&type=Sms&transactionID=1"

Response


{
    "result": true
}

Accounts

Fetch account data for the inbound service.

Get account details

Get account data using field key and value where the key is field name and value is the field value. eg. clid would be the key and 0821234567 would be the value.

Request Method: GET

Url: https://eft.ppay.io/api/v1/organisation/ $ORGANISATION_ID/account/$KEY/$VALUE

Get parameters:

Attribute Type Description Required
key String this value is limited to either clid or external_reference Yes
value String The value of this field depends on the key, if the key is clid then the value will be a contact number eg. 0821234567. If the key is external_reference it will be whatever the reference value is (id number, policy number, etc) Yes

Example

Request 

curl -X GET -u validusername:validpassword https://eft.ppay.io/api/v1/organisation/1/account/clid/0836112027

Response


{
    "id": 1,
    "name": "John",
    "surname": "Doe",
    "clid": "0831234567",
    "balance": "0.00",
    "external_reference": null
}

List all Accounts

Fetch all accounts for an organisation by organisation id. Organisation id is required in url

Request Method: GET

Url: https://eft.ppay.io/api/v1/organisation/$ORGANISATION_ID/account

Returned attributes per account:

Attribute Type Description
name text Account user first name
surname text Account user last name
clid integer Contact number for account
balance decimal Remaining balance for account eg. 125.00
external_reference string This is the unique reference or account number for the account

Example

Request 

curl -X GET -u validusername:validpassword https://eft.ppay.io/api/v1/organisation/$ORGANISATION_ID/account

Response


[
    {
        "name": "John",
        "surname": "Doe",
        "clid": "0831234567",
        "balance": "0.00",
        "external_reference": 125455582
    },
    {
        "name": "Jane",
        "surname": "Doe",
        "clid": "0731234567",
        "balance": "10.00",
        "external_reference": 125455836
    }
]

Import Accounts

Import accounts from a CSV file. Organisation id is required in url

Request Method: POST

Url: https://eft.ppay.io/api/v1/organisation/$ORGANISATION_ID/account/import

NB: Rules for CSV format are as follows:

  • Be sure your file upload form has attribute enctype="multipart/form-data" otherwise the file upload will not work.
  • Must be a minimum of five columns in the CSV file
  • The first five columns of the CSV must correspond with the following fields as that is how these columns will be saved in the database:
    • First column -> name
    • Second column -> surname
    • Third column -> balance
    • Fourth column -> clid (Contact number)
    • Fifth column -> external_reference (Unique account number

POST parameters:

Attribute Type Description
file comma-separated values (CSV) file A csv file with accounts to be imported

Example

Request 

curl -X POST -u validusername:validpassword -F "file=@/var/imports/youraccounts.csv" https://eft.ppay.io/api/v1/organisation/$ORGANISATION_ID/account/import

Response


{"message":"Spreadsheet has been uploaded successfully, will be processed shortly"}