Obtaining Your Access Details

Before making use of the PayGenius web service, you will need your Access Token and Secret Key. This can be found on the Settings page on your admin dashboard.

Be to sure to use the correct token for the production and development environments.

Making Requests

The PayGenius web service operates as a RESTFul service transmitting JSON payloads over HTTP.

All requests require the following HTTP request headers:

Header	Description
`Content-Type`	application/json
`Accept`	application/json
`X-Token`	The PayGenius application token provided
`X-Signature`	The signature generated for the request (see `Request Signing`)

The following optional headers can be provided.

Header	Description
`X-Forwarded-For`	The IP address of the client the request is made on behalf of. This can be used to identify fraud for example.

See our developer resources for examples on how to send requests.

Request Signing

All web service calls require a hex encoded HMAC-SHA256 API signature to be generated and sent using the X-Signature HTTP request header.

The signature can be generated using the following steps:

Prepare the data to be signed
1. For GET requests, only the full request URI is needed.
2. For POST requests, the full request URI needs to be concatenated with the POST data, separated by a single newline (\n) character.
Trim all whitespace from either end of the data.
Generate a SHA-256 HMAC, using the prepared data, and the provided secret key.
Hex encode the result HMAC. (note: In some cases (like PHP's hash_hmac function), the returned value is hex encoded by default, and this step is not required).
1. This will result in a 64 character length string.

See our developer resources for examples on how to sign requests.

Solving problems - Signing issues and HTTP 403 responses

The PayGenius server will calculate the expected signature from the received payload and URL. If the calculated signature does not match the X-Signature HTTP request header, it will respond with an HTTP 403 error. There could be many reasons for this, including but not limited to the following:

The merchant is using your develop secret key or auth token on production, or vise versa.
The signature was generate from a different payload then the payload received by PayGenius:
1. This could be because there is an underlying layer that alters and formats the request JSON body after generating the signature and before sending it to PayGenius. This will always result in 403 errors.
2. White space char encoding issues can result in this, if the charset is different to what PayGenius is expecting.

It is therefor very important that merchants use the exact trimmed post body that they send to PayGenius when generating the hmac signature. PayGenius recommends removing all white space chars and special chars (excluding actual key values with special chars) from the json body (no tabs, spaces, new lines inside the json structure). This must be done BEFORE signing AND sending it to PayGenius to ensure that the signature generation and PayGenius validation uses exactly the same values. This way, what the merchant used for signing and generating the signature is EXATLY the same as what PayGenius received.

Also take note of JSON parameter types. cvv is a string, while expiryYear and expiryMonth and amount are numbers. The below is invalid JSON:

"expiryMonth":07,
"amount":100.00,
"cvv":519

Solving problems - Response parsing

Some merchants may experience low level JSON parsing problems, depending on the technology used by their integration plaform. In some instances, the merchant's JSON parsing framework can replace part of the key/values if the value contains text like value=\"eyAidGhyZWVEU1Nl ....... This kind of value is typically found in the 3DSecure step 1 response threeDSecureV2->tdsMethodContent

Make sure that the iFrame is rendered exactly as returned in the JSON response and as described in Create Payment ZAR section (Note tdsMethodContent)

Request Validation

PayGenius provides a web service endpoint to validate that requests are signed correctly, and all required information is provided.

It is recommended to test both GET and POST requests before continuing with the rest of the integration.

HTTP Request

GET /pg/api/v2/util/validate

POST /pg/api/v2/util/validate

Request Body

If POST is used, any valid JSON string can be used to test the signature generation.

Response Body

Validate Response

{  
   "success":true,
   "merchant":"Your Merchant Name"
}

Attribute	Type	Description
success	boolean	If the API call succeeded
merchant	string	The merchant name that was found for the valid request

Handling Responses

The PayGenius API's response to any API request contains a boolean "success" object (true / false). From this flag the merchant should derive whether the request was successful or not.

For failed API responses, ( "success": false) there will always be a "message" string object in the root response payload, which describes to error. This message is typically what the merchant would display to the end user.

For success API responses, the message could be set, but not always. This means that for successful responses, the message could be something like "message": "Approved", or it could be empty or not present at all. The fact that the reponse is success is enough feddback and there is no real need for a any additional message to be displayed to the user.

Exceptions

Some if the Card Payments ZAR API's can return "success": true and "code": 2 with a 3DSecure object. In this case, the transaction should be seen as pending, and the merchant should direct the user according to the flow described in these API's. API's that can return "threeDSecureV2" response object: Create Payment ZAR Continue 3D Secure V2 Step 2

Examples

Success Response with Message

{  
   "success":true,
   "message":"Approved"
}

Success Response with empty Message

{  
   "success":true,
   "message":""
}

Success Response without Message

{  
   "success":true
}

Success Response with 3DSecure Object

{
  "success": true,
  "transactionDate": "2023-09-06T09:17:02",
  "threeDSecureV2": {
    "tdsMethodContent": null,
    "txId": null,
    "transactionId": "9dFK70g23ZJenr39OLvdtz8qkm8=",
    "sessionData": "OWRGSzcwZzIzWkplbnIzOU9MdmR0ejhxa204PQ",
    "acsUrl": "https://acsabsatest.bankserv.co.za/mdpayacs/creq",
    "creq": "ewogICAiYA6I....."
  },
  "reference": "703da38f-68b1-4f64-94ef-cc470225bbee",
  "code": 2,
  "message": "3D Secure authentication required"
}

Card Payments - ZAR

The Card Payment API provides a facility to perform credit card transactions on a user's card in ZAR. For other currencies, refer to Card Payment Other curr

Create Payment ZAR

Creating a payment attempts to authorize funds on the user's card.

HTTP Request

POST /pg/api/v2/payment/create

Request Data

Request with Card Data

{  
   "creditCard":{  
      "number":"4038220000353021",
      "cardHolder":"B Baggins",
      "expiryYear":2023,
      "expiryMonth":7,
      "type": "visa",
      "cvv":"019"
   },
   "transaction":{  
      "reference":"Invoice #1871",
      "currency":"ZAR",
      "amount":100
   },
   "threeDSecure":true,
   "supports3dsV2":true,
   "autoExecute":false,
   "callbackUrl":"https:\/\/merchant.com\/payment\/3ds\/callback\/merchant_payment_reference_001",
   "clientIp":"41.0.24.3",
   "screenWidth":"1024",
   "screenHeight":"600"
}

Request using a card token

{  
   "creditCard":{  
    "token": "8a86c511-14e2-4981-b13a-041d53ff4f62"
   },
   "transaction":{  
      "reference":"Invoice #1871",
      "currency":"ZAR",
      "amount":100
   },
   "threeDSecure":true,
   "supports3dsV2":true,
   "autoExecute":false,
   "callbackUrl":"https:\/\/merchant.com\/payment\/3ds\/callback\/merchant_payment_reference_001",
   "clientIp":"41.0.24.3",
   "screenWidth":"1024",
   "screenHeight":"600"
}

Request using a transaction reference

{
   "creditCard":{  
    "transactionReference": "8a86c511-14e2-4981-b13a-041d53ff4f62"
   },
   "transaction":{  
      "reference":"Invoice #1871",
      "currency":"ZAR",
      "amount":100
   },
   "threeDSecure":true,
   "supports3dsV2":true,
   "callbackUrl":"https:\/\/merchant.com\/payment\/3ds\/callback\/merchant_payment_reference_001",
   "clientIp":"41.0.24.3",
   "screenWidth":"1024",
   "screenHeight":"600"
}

Request using a payment reference

{
   "creditCard":{  
    "paymentReference": "8a86c511-14e2-4981-b13a-041d53ff4f62"
   },
   "transaction":{  
      "reference":"Invoice #1871",
      "currency":"ZAR",
      "amount":100
   },
   "threeDSecure":true,
   "supports3dsV2":true,
   "autoExecute":false,
   "callbackUrl":"https:\/\/merchant.com\/payment\/3ds\/callback\/merchant_payment_reference_001",
   "clientIp":"41.0.24.3",
   "screenWidth":"1024",
   "screenHeight":"600"
}

Request payment for affiliate merchant

{  
   "creditCard":{  
      "number":"4038220000353021",
      "cardHolder":"B Baggins",
      "expiryYear":2023,
      "expiryMonth":7,
      "type": "visa",
      "cvv":"010"
   },
   "transaction":{  
      "reference":"Invoice #1871",
      "currency":"ZAR",
      "amount":100
   },
   "threeDSecure":false,
   "affiliateMerchantId":186,
   "clientIp":"41.0.24.3",
   "screenWidth":"1024",
   "screenHeight":"600"
}

Request recurring payment (initial transaction)

{  
   "creditCard":{  
      "number":"4038220000353021",
      "cardHolder":"B Baggins",
      "expiryYear":2023,
      "expiryMonth":7,
      "type": "visa",
      "cvv":"019"
   },
   "transaction":{  
      "reference":"Invoice #1871",
      "currency":"ZAR",
      "amount":100
   },
   "threeDSecure":false,
   "affiliateMerchantId":186,
   "recurring":true,
   "clientIp":"41.0.24.3",
   "screenWidth":"1024",
   "screenHeight":"600"
}

Request recurring payment (subsequent transaction)

{  
   "creditCard":{  
      "paymentReference":"9a772981-12dde-332ab-129e-9023f89ef341",
      "initialTransactionReference":"9a772981-12dde-332ab-129e-9023f89ef341",
   },
   "transaction":{  
      "reference":"Invoice #1871",
      "currency":"ZAR",
      "amount":100
   },
   "threeDSecure":false,
   "affiliateMerchantId":186,
   "recurring":true,
   "initialRef":"9a772981-12dde-332ab-129e-9023f89ef341"
}

Request payment with subscription (using a card token)

{  
   "creditCard":{  
      "token": "8a86c511-14e2-4981-b13a-041d53ff4f62"
   },
   "transaction":{  
      "reference":"Invoice #1871",
      "currency":"ZAR",
      "amount":100
   },
   "threeDSecure":false,
   "subscription":{
      "reference": "13",
      "interval":"MONTHLY",
      "trialDays":30,
      "email": "bilbo@shire.com",
      "firstname":"Bob",
      "lastname":"Biggens"
   }
}

Property	Type	Description
creditCard	Credit Card	The card object
transaction	Transaction	The transaction object
threeDSecure	boolean	Forces 3D Secure to always be enabled
supports3dsV2	boolean	Tell PayGenius whether the merchant supports 3DSecure Version 2
autoExecute	boolean	(optional: default - false) Tell PayGenius to authorize the funds and execute the transactions. In this case, the merchant won't need to call Execute Payment for this transaction
callbackUrl	string	The URL that the browser will POST the 3DSecure V2 response to (required for 3DSecure V2)
clientIp	string	The IP address of the browser client (required for VISA cards for 3DS routing and 3DS policy decisions)
screenWidth	string	The pixle width of the client browser window (required for VISA cards)
screenHeight	string	The pixle height of the client browser window (required for VISA cards)
subscription	Subscription	(optional) The subscription object
affiliateMerchantId	integer	(optional) The affiliated merchant id that this payment should be done for (Retrieved from Get Affiliate Merchants)
recurring	boolean	(optional) Indicate that this transaction is the initial or subsequent recurring transaction. For the first transaction, cvv must be sent, for subsequent transactions, the cvv can be set as 000 or omitted
initialRef	string	(optional) The transaction reference of the initial transaction. If recurring is true, but initialRef is not sent, then PayGenius will attempt to find the first recurring reference against the tokenized card to use for the transaction. If initialRef is provided, then CVV can be sent as 000

3D secure behaviour can optionally be altered/controlled by administrator. Setting the threeDSecure property to true overrides this behavious and forces 3D secure to always be enabled.

The threeDSecureV2 response will only ever exist in the response, if the merchant specified the `supports3dsV2` flag as `true`. If the response contains the threeDSecureV2 object, and tdsMethodContent, txId and transactionId is set, then the merchant needs to direct the user to a page where the tdsMethodContent is rendered inside a frame. From the above, you can see that the tdsMmethodForm will immediately be submitted:
document.getElementById("tdsMmethodForm").submit(); The merchant page must then automatically do the next step in the 3DSecure V2 process, after 3 seconds: (eg:)


         window.onload = function {
                setTimeout(function () {
                    console.log('Sumitting 3DS V2 form');
                    document.getElementById('threedsv2_step2-form').submit();
                }, 3000);
            }

If the response contains the threeDSecureV2 object, and acsUrl, sessionData and transactionId is set, then it means that the merchant must skip Step 2, and go directly to 3DSecure V2 step 3 (as would be done if the response is challenged in the call to ## Continue 3D Secure V2 Step 2)

Response Data

Non-3DS Response

{
    "success": true,
    "transactionDate": "2023-09-06T09:17:02",
    "reference": "f5750da2-89f7-49b0-a38d-020951b9ddaa",
    "code": 1,
    "message": "Approved"
}

3DS Response

{
    "success": true,
    "threeDSecure": {
        "acsUrl": "https://acstest.bankserv.co.za/V3DSStart?osb=visa-default&VAA=B",
        "transactionId": "l2SUAS4PMJYpMzZfIql0",
        "paReq": "eNpVUttygjAQfc9XOH4AAcRLnTUzKNXCjI4V7FjfYoyFioABvH19E4Xavu3Z3Tk552wgCAXnjs9ZKTiBKc9z+sUb0XbQjE1/afvWfOp9ZtPbeuceY71JYG4v+JHAiYs8ShNiaLpmAq4hkhSChTQpCFB2HLoz0mlbLdMAXEEEBy5chxhmy2p3uj3AD4wgoQdOhjTZ51yc7J2IGG3UbIDvUwQsLZNCXEnX0AHXAEEpYhIWRdbH+Hw+a5uKRWOpdqOA1RgBfmqbl6rKpeVLtCUbxws+luNgNh7O/Dg+B6uMrvfxZePYA8BqA8GWFpyYutHVX/RWwzT6ZrtvSVv3PgJ6UFrIQuYhhVUIQabesR/IUJO/DemmFIInrLZTIwT8kqUJlzsy299aOnjqHr2phFkho3sPAzYZLTxv3TIn4ekWTpOr+zr6Xq32Kvb7zp0yklkZPfVUBSSj4sHVUXF1f1n9+xc/Emm0ng=="
    },
    "transactionDate": "2023-09-06T09:17:02",
    "reference": "38424fc9-d7de-4215-9e9d-93e40bd94160",
    "code": 2,
    "message": "3D Secure authentication required"
}

3DS V2 Response

{
  "success": true,
  "transactionDate": "2023-09-06T09:17:02",
  "threeDSecureV2": {
    "tdsMethodContent": "<iframe id=\"tdsMmethodTgtFrame\" name=\"tdsMmethodTgtFrame\" style=\"width: 1px; height: 1px; visibility: hidden;\" src=\"javascript:false;\" xmlns=\"http://www.w3.org/1999/xhtml\"> <!--.--> </iframe><form id=\"tdsMmethodForm\" name=\"tdsMmethodForm\" action=\"https://acsabtest.bankserv.co.za/mdpayacs/3ds-method\" method=\"post\" target=\"tdsMmethodTgtFrame\" xmlns=\"http://www.w3.org/1999/xhtml\"> <input type=\"hidden\" name=\"3DSMethodData\" value=\"eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogImFiODAwNGU2LTJmYWEtNWNiZC04MDAwLTAwMDAwNmU3ZWQzOSIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovL21zZ3Rlc3QuYmFua3NlcnZhZnJpY2EuY29tL21kcGF5bXBpL01lcmNoYW50U2VydmVyP21uPVkmdHhpZD0xMTU4NjI4NDEmZGlnZXN0PSUyRjdqcSUyRjg1bmp2cDZhREttRCUyRjJ3YnFZOW9xJTJCelVWUkZFY2g0SktrYU53NCUzRCIgfQ\"/> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogImFiODAwNGU2LTJmYWEtNWNiZC04MDAwLTAwMDAwNmU3ZWQzOSIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovL21zZ3Rlc3QuYmFua3NlcnZhZnJpY2EuY29tL21kcGF5bXBpL01lcmNoYW50U2VydmVyP21uPVkmdHhpZD0xMTU4NjI4NDEmZGlnZXN0PSUyRjdqcSUyRjg1bmp2cDZhREttRCUyRjJ3YnFZOW9xJTJCelVWUkZFY2g0SktrYU53NCUzRCIgfQ\"/> </form><script type=\"text/javascript\" xmlns=\"http://www.w3.org/1999/xhtml\"> document.getElementById(\"tdsMmethodForm\").submit(); </script>",
    "txId": "115862841",
    "transactionId": "9dFK70g23ZJenr39OLvdtz8qkm8=",
    "sessionData": null,
    "acsUrl": null,
    "creq": null
  },
  "reference": "703da38f-68b1-4f64-94ef-cc470225bbee",
  "code": 2,
  "message": "3D Secure authentication required"
}

3DS V2 Response (go directly to step 3)

{
  "success": true,
  "transactionDate": "2023-09-06T09:17:02",
  "threeDSecureV2": {
    "tdsMethodContent": null,
    "txId": null,
    "transactionId": "9dFK70g23ZJenr39OLvdtz8qkm8=",
    "sessionData": "OWRGSzcwZzIzWkplbnIzOU9MdmR0ejhxa204PQ",
    "acsUrl": "https://acsabsatest.bankserv.co.za/mdpayacs/creq",
    "creq": "ewogICAiYWNzVHJhbnNJRCIgOiAiMmUzNmJiZmMtZTI2NS00Y2U0LTg1YjQtOTVhOWU3NjhhMTE0IiwKICAgImNoYWxsZW5nZVdpbmRvd1NpemUiIDogIjAzIiwKICAgIm1lc3NhZ2VUeXBlIiA6ICJDUmVxIiwKICAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiYWI4MDA0ZTYtMmZhYS01Y2JkLTgwMDAtMDAwMDA2ZTdlZDM5Igp9"
  },
  "reference": "703da38f-68b1-4f64-94ef-cc470225bbee",
  "code": 2,
  "message": "3D Secure authentication required"
}

Error Response

{
    "success": false,
    "message": "Failed to authenticate card using 3D Secure",
    "originalErrorCode": "fin006",
    "code":3
}

Property	Type	Description
success	boolean	`true` on success
code	integer	The response code
reference	string	The transaction reference
message	string	A response message
threeDSecure	3D Secure	If 3D secure is required, this object will be present containing the required data to complete the process
threeDSecureV2	3D Secure V2	If 3D secure is required, this object will be present containing the required data to complete the process
transactionDate	string	transaction creation date (format - 'yyyy-MM-ddTHH:mm:ss')

You can view the sample 3D Secure V1 form here. The implementation varies upon preference, the form is only meant to operate as a guideline to the parameter structure required by the 3D secure verification party. The response received after this operation should contain a paRes parameter which is subsequently used to verify payment.

Confirm 3D Secure V1 Response

HTTP Request

POST /pg/api/v2/payment/{reference}/confirm

Request Data

Request

{  
   "paRes":"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"
}

Property	Type	Description
paRes	string	The authentication response provided by the bank's access control server

Response Data

Response

{
    "success": true,
    "message": "Approved",
    "transactionDate": "2023-09-06T09:17:02",
    "originalErrorCode": "fin000",
    "code":1
}

Error Response

{
    "success": false,
    "message": "Insufficient funds",
    "originalErrorCode": "fin051",
    "code":-1
}

Error Response

{
    "success": false,
    "message": "Insufficient funds",
    "originalErrorCode": "fin051",
    "code":-1
}

Property	Type	Description
success	boolean	`true` on success
transactionDate	string	transaction creation date (format - 'yyyy-MM-ddTHH:mm:ss')

Continue 3D Secure V2 Step 2

Three seconds after rendering tdsMethodContent (which submits the form to the bank), the merchant must make this API call to see if the transaction will follow the challenged flow, or the non-challenged 3D Secure V2 flow. If response is challenged, then the user should be redirected to a page (Step 3) where the creq and sessionData is submitted to the acsUrl.

HTTP Request

POST /pg/api/v2/payment/3dsv2/{reference}/confirm

Request Data

Request

{
  "reference": "703da38f-68b1-4f64-94ef-cc470225bbee",
  "txId": "115862841",
  "transactionId": "9dFK70g23ZJenr39OLvdtz8qkm8="
}

Property	Type	Description
reference	string	The transaction reference
txId	string	The txId from the 3D Secure V2 response
transactionId	string	The transactionId from the 3D Secure V2 response

Response Data

Non-challenged Response

{
    "success": true,
    "transactionDate": "2023-09-06T09:17:02",
    "reference": "703da38f-68b1-4f64-94ef-cc470225bbee",
    "code": 1,
    "message": "Approved"
}

Challenged Response

{
  "success": true,
  "transactionDate": "2023-09-06T09:17:02",
  "message": "3D Secure authentication required",
  "threeDSecureV2": {
    "tdsMethodContent": null,
    "txId": null,
    "transactionId": "9dFK70g23ZJenr39OLvdtz8qkm8=",
    "sessionData": "OWRGSzcwZzIzWkplbnIzOU9MdmR0ejhxa204PQ",
    "acsUrl": "https://acsabsatest.bankserv.co.za/mdpayacs/creq",
    "creq": "ewogICAiYWNzVHJhbnNJRCIgOiAiMmUzNmJiZmMtZTI2NS00Y2U0LTg1YjQtOTVhOWU3NjhhMTE0IiwKICAgImNoYWxsZW5nZVdpbmRvd1NpemUiIDogIjAzIiwKICAgIm1lc3NhZ2VUeXBlIiA6ICJDUmVxIiwKICAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiYWI4MDA0ZTYtMmZhYS01Y2JkLTgwMDAtMDAwMDA2ZTdlZDM5Igp9"
  },
  "code": 2
}

If the threeDSecureV2 object exists, and creq, sessionData, transactionId and acsUrl is present, then the merchant must redirect the user to a page where the sessionData and creq is automatically submitted in a form to the acsUrl (very simular to 3DSecure V1) :

Example here

You can view the sample 3D Secure V2 (Step 3) form here. The implementation varies upon preference, the form is only meant to operate as a guideline to the parameter structure required by the 3D secure verification party for Version 2. The response received on the callbackUrl should contain a cres parameter which is subsequently used to verify payment.

Error Response

{
    "success": false,
    "message": "Failed to authenticate card using 3D Secure",
    "originalErrorCode": "fin006",
    "code":3
}

Property	Type	Description
success	boolean	`true` on success
code	integer	The response code
reference	string	The transaction reference
message	string	A response message
threeDSecureV2	3D Secure V2	If 3D secure is required (Challenged flow), this object will be present containing the required data to complete the process
transactionDate	string	transaction authorization date (format - 'yyyy-MM-ddTHH:mm:ss')

Confirm 3D Secure V2 Response

Note that confirm 3DS v2 and v1 uses the same API endpoint, but expect different content. For V1, paRes is required. For V2, cres is required.

For V2, the bank will do a POST to the merchant callbackUrl (from create payment) , after which case the merchant must send the cres to PayGenius to do final payment auth.

HTTP Request

POST /pg/api/v2/payment/{reference}/confirm

Request Data

Request (v2)

{  
   "paRes":null,
   "cres":"ewogICJhY3NUcmFuc0lEIiA6ICIyZTM2YmJmYy1lMjY1LTRjZTQtODViNC05NWE5ZTc2OGExMTQiLAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInNka1RyYW5zSUQiIDogIjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIiA6ICJhYjgwMDRlNi0yZmFhLTVjYmQtODAwMC0wMDAwMDZlN2VkMzkiLAogICJ0cmFuc1N0YXR1cyIgOiAiWSIKfQ",
}

Property	Type	Description
cres	string	The authentication response provided by the bank's access control server (and pas posted to the merchant's callbackUrl)

Response Data

Response

{
    "success": true,
    "transactionDate": "2023-09-06T09:17:02",
    "message": "Approved",
    "originalErrorCode": "fin000",
    "code":1
}

Error Response

{
    "success": false,
    "message": "Insufficient funds",
    "originalErrorCode": "fin051",
    "code":-1
}

Error Response 3DS Auth Failure

{
  "success": false,
  "error": {
    "code": 3,
    "message": "Failed to authenticate card using 3D Secure. Authentication errors"
  },
  "message": "Failed to authenticate card using 3D Secure. Authentication errors",
  "originalErrorCode": "fin006"
}

Property	Type	Description
success	boolean	`true` on success
transactionDate	string	transaction creation date (format - 'yyyy-MM-ddTHH:mm:ss')

Execute Payment

Partial Payment Request

{  
   "transaction":{  
      "currency":"ZAR",
      "amount":100
   }
}

Reversal Request. (Amount = 0)

{  
   "transaction":{  
      "currency":"ZAR",
      "amount":0
   }
}

Response

{
    "success": true,
    "transactionDate": "2023-09-06T09:17:02"
}

Error Response

{
    "success": false,
    "transactionDate": "2023-09-06T09:17:02",
    "message": "Insufficient funds",
    "originalErrorCode": "fin051",
    "code":-1
}

This executes a payment that was previously created. The user's money will be transfered from their bank account, and the transaction will be complete.

If a zero amount is executed, the funds will effectively be reversed and the authorization is cleared.

HTTP Request

GET /pg/api/v2/payment/{{reference}}/execute

A GET request will authorize the full amount that was previously authorized.

POST /pg/api/v2/payment/{{reference}}/execute

A POST request allows executing part of the amount authorized. If executing with amount 0, the funds will be reversed.

Request Data

Property	Type	Description
transaction	Transaction	Transaction information with the amount to execute

Response Data

Property	Type	Description
success	boolean	`true` on success
transactionDate	string	transaction execution date (format - 'yyyy-MM-ddTHH:mm:ss')

Refund Payment

Partial Refund Request

{  
   "transaction":{  
      "reference":"MERCHANT_REFX121",
      "currency":"ZAR",
      "amount":20000
   }
}

Response

{
    "success": true,
    "transactionDate": "2023-09-06T09:17:02"
}

Error Response

{
    "success": false,
    "message": "Card blocked",
    "originalErrorCode": "fin051",
    "code":-1
}

Pending Refund Response

{
    "success": false,
    "message": "We are processing the refund manually and will let you know when it is approved by the bank. The refund can take up to 8 working days to reflect on the customer's card.",
    "originalErrorCode": "fin012",
    "code": 7
}

This method is used to refund a payment that was previously settled.

Note that it is possible that the refund goes into a pending status. Code - 7 is a special response code which means pending refund.

In this case it is not successful, but might (probably will) be successful in future. The merchant will be notified on the transaction payment notify URL (if it exists) when the pending refund was completed.

HTTP Request

GET /pg/api/v2/payment/{{reference}}/refund

A GET request will refund the full amount that was previously settled.

POST /pg/api/v2/payment/{{reference}}/refund

A POST request allows refunding part of the settled amount. The merchant can supply their own reference for the refund payment. The merchant reference is optional.

Request Data

Property	Type	Description
transaction	Transaction	Transaction information with the amount to refund and an optional reference

Response Data

Property	Type	Description
success	boolean	`true` on success
transactionDate	string	Refund transaction date (format - 'yyyy-MM-ddTHH:mm:ss')

Card Payments - Other

The Card payment for Other Currencies API provides a facility to perform credit card transactions on a user’s card for non-ZAR (non South African Rand) transaction.

The merchant is required to pass through transaction details, an authorize flag and a set of URL’s. The PayGenius response will contain a payment page redirect URL, which the merchant needs to redirect the consumer to. After payment is completed, the merchant will be notified, and the consumer will be redirected back the the success/ error / cancel URL (as provided by the merchant in the payment request) depending on the outcome of the transaction.

If the authorize flag was set to true (meaning that the funds were reserved on the cards), then the merchant will need to execute the payment for the funds to be transferred to the merchant bank account.

If the authorize flag was set to false, the payment will automatically be executed, and funds transferred to the merchant.

The 3D Secure authorization is done directly on the PayGenius payment page.

Create Payment - Other

Creating a payment to authorize fund from the user's card (if authorize is set to true) or transfer funds funds from the user's card if authorize is set to false. The response contains the redirectUrl, to which the user will be redirected to fill in card details (and any other consumer details) and proceed with the autorization/payment.

Note that no credit card data is allowed on this version of the Create Payment request, and the urls are required (success/cancel/error). Consumer data, including address, is optional. If the consumer details is not provided in the API call, it will have to be supplied by the user on the payment page.

Transfer

This API method now allows merchants to transfer up to 90% of the payment amount to affiliated merchants for foreign currency (non-ZAR). Such transfers are prepared with this API method and executed on successful payment. To transfer a portion of the payment to an affiliated merchant (or multiple affiliated merchants), include the transfer object with the API payload.

HTTP Request

POST /pg/api/v3/payment/create

Request Data

Request with authorize = true

{  
   "transaction":{  
      "reference":"MERCHANTREFERENCE01",
      "currency":"USD",
      "amount":1000
   },
   "urls":{  
      "cancel":"https://merchant.com/payment/MERCHANTREFERENCE01/cancel",
      "error":"https://merchant.com/payment/MERCHANTREFERENCE01/error",
      "success":"https://merchant.com/payment/MERCHANTREFERENCE01/success",
      "notify":"https://merchant.com/payment/MERCHANTREFERENCE01/notify"
   },
   "consumer": {
    "name": "Bilbo",
    "surname": "Baggins",
    "email": "bilbo@shire.com",
    "consumerAddress": {
      "addressLineOne": "1 Main Street",
      "city": "Cape Town",
      "postCode": "8000",
      "country": "ZA"
      }
   },
   "threeDSecure":true,
   "authorize":true,
   "allowMultiCurrencyPurchase":false,
   "transactionDate": "2021-09-20",
   "description":"Hop on Hop off Rome sightseeing tour",
   "destinationCountry": "IT",
   "pax": 1
}

Request with automatic execution

{  
   "transaction":{  
      "reference":"MERCHANTREFERENCE01",
      "currency":"USD",
      "amount":2000
   },
   "urls":{  
      "cancel":"https://merchant.com/payment/MERCHANTREFERENCE01/cancel",
      "error":"https://merchant.com/payment/MERCHANTREFERENCE01/error",
      "success":"https://merchant.com/payment/MERCHANTREFERENCE01/success",
      "notify":"https://merchant.com/payment/MERCHANTREFERENCE01/notify"
   },
   "consumer": {
    "name": "Bilbo",
    "surname": "Baggins",
    "email": "bilbo@shire.com",
    "consumerAddress": {
      "addressLineOne": "1 Main Street",
      "city": "Cape Town",
      "postCode": "8000",
      "country": "ZA"
      }
   },
   "threeDSecure":true,
   "allowMultiCurrencyPurchase":false,
   "description":"7 day tour to Egypt including airport transfers",
   "transactionDate": "2021-09-20",
   "destinationCountry": "EG",
   "pax": 1
}

Request using minimum parameters (everything else will default)

{  
   "transaction":{  
      "reference":"MERCHANTREFERENCE01",
      "currency":"USD",
      "amount":2500
   },
   "urls":{  
      "cancel":"https://merchant.com/payment/MERCHANTREFERENCE01/cancel",
      "error":"https://merchant.com/payment/MERCHANTREFERENCE01/error",
      "success":"https://merchant.com/payment/MERCHANTREFERENCE01/success",
      "notify":"https://merchant.com/payment/MERCHANTREFERENCE01/notify"
   },
   "threeDSecure":false
}

Request payment for affiliate merchant

{  
   "transaction":{  
      "reference":"MERCHANTREFERENCE01",
      "currency":"USD",
      "amount":2500
   },
   "urls":{  
      "cancel":"https://merchant.com/payment/MERCHANTREFERENCE01/cancel",
      "error":"https://merchant.com/payment/MERCHANTREFERENCE01/error",
      "success":"https://merchant.com/payment/MERCHANTREFERENCE01/success",
      "notify":"https://merchant.com/payment/MERCHANTREFERENCE01/notify"
   },
   "threeDSecure":false,
   "affiliateMerchantId":186
}

Request payment with transfer to affiliate merchant

{
  "transaction": {
    "reference": "REF04271322221",
    "currency": "EUR",
    "amount": 16000
  },
  "consumer": {
    "name": "Bilbo",
    "surname": "Baggins",
    "email": "bb.bb@paygenius.co.za",
    "consumerAddress": {
      "addressLineOne": "1 Main street",
      "city": "Cape Town",
      "postCode": "8000",
      "country": "ZA"
    }
  },
  "threeDSecure": true,
  "urls": {
    "cancel":"https://merchant.com/payment/MERCHANTREFERENCE01/cancel",
    "error": "https://merchant.com/payment/MERCHANTREFERENCE01/error",
    "success": "https://merchant.com/payment/MERCHANTREFERENCE01/success",
    "notify": "https://merchant.com/payment/MERCHANTREFERENCE01/notify",
  },
  "allowMultiCurrencyPurchase": true,
  "description": "Travel to Paris, Eiffel Tower, sight-seeing",
  "transactionDate": "2023-12-22",
  "destinationCountry": "FR",
  "pax": 2,
  "affiliateMerchantId": 189,
  "transfer": {
    "reference": "Transfers-FROM-ref-20220721",
    "toMerchants": [
      {
        "currency": "EUR",
        "amount": 11000,
        "merchantId": 188,
        "merchantReference": "Transfers-TO-ref-20220721"
      }
    ]
  }
}

Property	Type	Description
transaction	Transaction	The transaction object
threeDSecure	boolean	Forces 3D Secure to always be requested on the payment page
urls	URLs	The redirect urls that the user will be redirected on payment outcome.
consumer	Consumer	(optional) The consumer details
consumer.consumerAddress	Consumer Address	(optional) The consumer's address.
authorize	boolean	(optional) If set to true, the funds will only be authorized, but not transfered (default false)
allowMultiCurrencyPurchase	boolean	(optional) Specify whether the consumer is allowed to pay in a different currency than the merchant base currency (in the transaction object currency) (default false)
description	string	(required for travel payments in foreign currency : non-ZAR) Full description of what this payment is for. Must be descriptive enough for travel insurance purposes. Eg. Hop on Hop off Rome sightseeing tour
transactionDate	string	(optional for normal merchants, required for travel merchants) The end date of travel or delivery date (format - 'yyyy-MM-dd') (default today)
destinationCountry	string	(required for travel payments in foreign currency : non-ZAR) Country travelling to or product destination country. Eg. ZA
pax	number	(optional for normal merchants, required for travel merchants) The number of people travelling (if travel booking) or the number of items / packages (default 1)
affiliateMerchantId	integer	(optional) The affiliated merchant id that this payment should be done for (Retrieved from Get Affiliate Merchants)
transfer	Transfer	(optional) The forex transfer, with amount(s) to be allocated to affiliate(s)

3D secure behaviour can optionally be altered/controlled by administrator. Setting the threeDSecure property to true overrides this behavious and forces 3D secure to always be enabled.

Response Data

Response

{
    "success": true,
    "reference": "f5750da2-89f7-49b0-a38d-020951b9ddaa",
    "code": 1,
    "redirectUrl": "https://www.paygenius.co.za/pay/merchantpage/en/5da5758b-ad58-487f-99d5-996950440e21",
    "message": "Success"
}

Error Responses

{
    "success": false,
    "message": "Please provide URL's (urls)",
    "originalErrorCode": "",
    "code":3
}

{
    "success": false,
    "message": "You do not have a payment page set up for PayGenius payments. Please contact PayGenius support.",
    "originalErrorCode": "",
    "code":19
}

Property	Type	Description
success	boolean	`true` on success
code	integer	The response code
reference	string	The transaction/transaction reference
message	string	A response message
redirectUrl	string	The URL that the merchant must redirect the consumer to, in order to provide card details and complete the payment

Execute Payment - Other

Partial Payment Request.

{  
   "transaction":{  
      "currency":"USD",
      "amount":100
   }
}

Reversal Request. (Amount = 0)

{  
   "transaction":{  
      "currency":"USD",
      "amount":0
   }
}

Response

{
    "success": true,
    "transactionDate": "2023-09-06T09:17:02"
}

Error Response

{
    "success": false,
    "message": "Insufficient funds",
    "originalErrorCode": "fin051",
    "code":-1
}

This executes a payment that was previously authorized in the Create Payment Request (with authorize = true flag). The user’s funds will be transferred from their bank account, and the transaction will be complete.

If the funds were already switched (with authorize = false) in the original payment request, then the execute request is not required to complete the payment (although it is allowed).

If a zero amount is executed, the funds will effectively be reversed and the authorization is cleared.

HTTP Request

GET /pg/api/v3/payment/{{reference}}/execute

A GET request will authorize the full amount that was previously authorized.

POST /pg/api/v3/payment/{{reference}}/execute

A POST request allows executing part of the amount authorized. If executing with amount 0, the funds will be reversed.

Request Data

Property	Type	Description
transaction	Transaction	Transaction information with the amount to execute

Response Data

Property	Type	Description
success	boolean	`true` on success
transactionDate	string	Transaction execution date (format - 'yyyy-MM-ddTHH:mm:ss')

Refund Payment - Other

Partial Refund Request.

{  
   "transaction":{  
      "reference":"MERCHANT_REFX121",
      "currency":"USD",
      "amount":20000
   }
}

Response

{
    "success": true,
    "transactionDate": "2023-09-06T09:17:02"
}

Error Response

{
    "success": false,
    "message": "Card blocked",
    "originalErrorCode": "fin051",
    "code":-1
}

Pending Refund Response

{
    "success": false,
    "message": "We are processing the refund manually and will let you know when it is approved by the bank. The refund can take up to 8 working days to reflect on the customer's card.",
    "originalErrorCode": "fin012",
    "code": 7
}

This method is used to refund a payment that was previously settled.

Note that it is possible that the refund goes into a pending status. Code - 7 is a special response code which means pending refund.

HTTP Request

GET /pg/api/v3/payment/{{reference}}/refund

A GET request will refund the full amount that was previously settled.

POST /pg/api/v3/payment/{{reference}}/refund

A POST request allows refunding part of the settled amount. The merchant can supply their own reference for the refund payment. The merchant reference is optional.

Request Data

Property	Type	Description
transaction	Transaction	Transaction information with the amount to refund and an optional reference

Response Data

Property	Type	Description
success	boolean	`true` on success
transactionDate	string	Refund transaction date (format - 'yyyy-MM-ddTHH:mm:ss')

Edit Payment - Other

Change transaction date, consumer details and description

{
  "consumer": {
    "name": "Bilbo",
    "surname": "Baggins",
    "email": "bb.bb@paygenius.co.za",
    "consumerAddress": {
      "addressLineOne": "1 Main street",
      "city": "Cape Town",
      "postCode": "8000",
      "country": "ZA"
    }
  },
  "description": "Travel to Paris, Eiffel Tower, sight-seeing",
  "transactionDate": "2024-02-12"
}

Change transaction date, transfer and other details

{
  "consumer": {
    "name": "Bilbo",
    "surname": "Baggins",
    "email": "bb.bb@paygenius.co.za",
    "consumerAddress": {
      "addressLineOne": "1 Main street",
      "city": "Cape Town",
      "postCode": "8000",
      "country": "ZA"
    }
  },
  "description": "Travel to Paris, Eiffel Tower, sight-seeing",
  "transactionDate": "2024-02-12",
  "destinationCountry": "FR",
  "pax": 2,  
  "transfer": {
    "reference": "Transfers-FROM-ref-20220721",
    "toMerchants": [
      {
        "currency": "EUR",
        "amount": 11000,
        "merchantId": 188,
        "merchantReference": "Transfers-TO-ref-20220721"
      }
    ]
  }
}

Response

{
    "success": true,
    "reference": "f5750da2-89f7-49b0-a38d-020951b9ddaa",
    "message": "Success"
}

Error Response

{
    "success": false,
    "reference": "f5750da2-89f7-49b0-a38d-020951b9ddaa",
    "code": 1,
    "message": "You are not allowed to change payment details after or on the day the the payment is executed."
}

This method is used to change the booking, activity date or transfers of an existing payment, as well as other details related to the payment. This can only be done up to the day before the transaction date.

Note that the same rules apply for the portion of the payment that can be transferred: Up to 90% of the payment amount can be transferred to affiliated merchants for foreign currency (non-ZAR).

HTTP Request

POST /pg/api/v3/payment/{{reference}}/edit

Request Data

Property	Type	Description
consumer	Consumer	(optional) The consumer details
consumer.consumerAddress	Consumer Address	(optional) The consumer's address.
description	string	(optional) Full description of what this payment is for. Must be descriptive enough for travel insurance purposes. Eg. Hop on Hop off Rome sightseeing tour
transactionDate	string	The end date of travel or delivery date (format - 'yyyy-MM-dd')
destinationCountry	string	Country travelling to or product destination country. Eg. ZA
pax	number	The number of people travelling (if travel booking) or the number of items / packages (default 1)
transfer	Transfer	(optional) The new forex transfer, with amount(s) to be allocated to affiliate(s). Will override the previous transfer(s) linked to this payment

Response Data

Property	Type	Description
success	boolean	`true` on success
reference	string	Payment reference

Add Payment Transfer - Other

Add additional transfer

{  
  "transfer": {
    "reference": "Transfers-FROM-ref-20220721",
    "toMerchants": [
      {
        "currency": "EUR",
        "amount": 11000,
        "merchantId": 188,
        "merchantReference": "Transfers-TO-ref-20220721"
      }
    ]
  }
}

Response

{
    "success": true,
    "reference": "f5750da2-89f7-49b0-a38d-020951b9ddaa",
    "message": "Success"
}

Error Response

{
    "success": false,
    "reference": "f5750da2-89f7-49b0-a38d-020951b9ddaa",
    "code": 1,
    "message": "You are not allowed to create transfers after or on the day that the payment is executed."
}

This method is used to add more transfers to an existing payment. The payment's existing transfer(s), if any, will not be cancelled or altered.

Note that the same rules apply for the portion of the payment that can be transferred: Up to 90% of the payment amount can be transferred to affiliated merchants for foreign currency (non-ZAR).

HTTP Request

POST /pg/api/v3/payment/{{reference}}/transfer/create

Request Data

Property	Type	Description
transfer	Transfer	(required) New forex transfer(s), with amount(s) to be allocated to affiliate(s). Will be added on top of any previous transfer(s) linked to this payment

Response Data

Property	Type	Description
success	boolean	`true` on success
reference	string	Payment reference

Cancel Payment Transfer

Response

{
    "success": true,
    "reference": "f5750da2-89f7-49b0-a38d-020951b9ddaa",
    "message": "Success"
}

Error Response

{
    "success": false,
    "reference": "f5750da2-89f7-49b0-a38d-020951b9ddaa",
    "code": 1,
    "message": "You are not allowed to cancel payment transfer(s) after or on the day that the payment is executed."
}

Error Response

{
    "success": false,
    "reference": "f5750da2-89f7-49b0-a38d-020951b9ddaa",
    "code": 1,
    "message": "No existing transfers linked to this payment."
}

This method is used to cancel the transfer(s) linked to a payment. The payment will still be executed on the transaction date, but no transfer will be allocated to an affiliate. This can only be done up to the day before the transaction date.

HTTP Request

GET /pg/api/v3/payment/{{reference}}/transfer/cancel

Request Data

Property	Type	Description

Response Data

Property	Type	Description
success	boolean	`true` on success
reference	string	Payment reference

Card Vault Methods

Register Card

POST /pg/api/v2/card/register

This registers a card and stores it in a secure card vault. A token is returned as a reference to the card, which can be used for future payment requests.

Request Data

Request

{
    "creditCard": {
        "number": "4550270020473018",
        "cardHolder": "B Baggins",
        "expiryYear": 2023,
        "expiryMonth": 8,
        "cvv": "017",
        "type": "visa"
    }
}

Property	Type	Description
creditCard	Credit Card	The card object

Response Data

Response

{
    "success": true,
    "token": "f8d5b7a3-3851-43bf-a499-afda33c38dd6"
}

Property	Type	Description
token	string	The card token which can be used for future transactions
success	boolean	`true` on success

Lookup Card

POST /pg/api/v2/card/lookup

Looks up a card previously registered in the vault. Either the token, or the credit card number can be provided.

Request Data

Request using card number

{
  "cardNumber": "4550270020473018"
}

Request using card token

{
  "token": "f8d5b7a3-3851-43bf-a499-afda33c38dd6"
}

Request using a transaction reference

{
  "transactionReference": "1d48229e-123f-f456-78fd-afda33c38dd6"
}

Property	Type	Description
cardNumber	string	The user's card number
token	string	The stored card's token
transactionReference	string	The reference for a previous successful transaction

Response Data

Response

{
    "success": true,
    "card": {
        "number": "455027XXXXXX3018",
        "cardHolder": "TT",
        "expiryYear": 2023,
        "expiryMonth": 7,
        "type": "visa",
        "token": "f8d5b7a3-3851-43bf-a499-afda33c38dd6"
    }
}

Property	Type	Description
card	Credit Card	The card object
success	boolean	`true` on success

Unregister Card

Unregisters a card from the system.

POST /pg/api/v2/card/unregister

Request Data

Request

{
  "token": "f8d5b7a3-3851-43bf-a499-afda33c38dd6"
}

Property	Type	Description
token	string	The stored card's token

Response Data

Response

{
    "success": true
}

Property	Type	Description
success	boolean	`true` on success

Instant EFT Methods

Create Payment

POST /pg/api/v2/payment/create/eft

Creates a eft payment request.

Request Data

Request

{  
  "transaction":{
    "reference":"Invoice #1871",
    "currency":"ZAR",
    "amount":100
  },
  "consumer": {
    "name": "Bilbo",
    "surname": "Baggins",
    "email": "bilbo@shire.com"
  },
  "urls": {
    "success": "https://merchant.com/success-page",
    "cancel": "https://merchant.com/cancel-page",
    "error": "https://merchant.com/error-page"
  }
}

Property	Type	Description
transaction	Transaction	The transaction details
consumer	Consumer	The consumer details
urls	URLs	The redirect urls

Response Data

Response

{
    "success": true,
    "reference": "ec901313-23e1-4504-9380-332b260ff2c6",
    "redirectUrl": "https://www.paygenius.co.za/pg/eft/ec901313-23e1-4504-9380-332b260ff2c6"
}

Property	Type	Description
success	boolean	`true` on success

Transaction Methods

Lookup a Transaction

GET /pg/api/v2/payment/{reference}

Looks up the status of a transaction.

Response Data

Response

{
    "success": true,
    "reference": "38424fc9-d7de-4215-9e9d-93e40bd94160",
    "amount": 100,
    "currency": "ZAR",
    "status": "SETTLED",
    "date": "2023-07-21T19:16:24.000Z"
}

Property	Type	Description
success	boolean	`true` on success
reference	string	The transaction reference
amount	integer	The transaction amount in cents
currency	string	The transaction currency
status	string	The transaction status

Transaction Statuses

Status	Description
`AUTHORIZED`	Funds have been reserved on the user's account
`SETTLED`	The transaction has been completed
`CANCELLED`	The transaction was cancelled by the user
`REFUNDED`	A completed refund transaction
`THREE_D_SECURE`	Awaiting 3D secure confirmation
`FAILED`	Indicates a failed transaction
`REVERSED`	The transaction has been reversed

Lookup by Merchant Reference

GET /pg/api/v2/payment/lookup/merchantReference/{merchantReference}

Do a lookup of the status of a transaction or refund using the original merchant reference that was used in the create/refund request. eg: pg/api/v2/payment/lookup/merchantReference/MERCHANT_REFX121

Response Data

Response

{
    "success": true,
    "reference": "ab6a2161-f1b8-4fd6-afec-2ee67165c585",
    "amount": -20000,
    "currency": "ZAR",
    "status": "REFUNDED",
    "date": "2023-05-05T13:46:24.000Z"
}

Property	Type	Description
success	boolean	`true` on success
reference	string	The transaction reference (PayGenius Reference)
amount	integer	The transaction or refund amount in cents (Refund have negative amount)
currency	string	The transaction currency
status	string	The transaction status

Get Filtered Transactions

POST /pg/api/v2/payment/list

Look up all transactions according to various filters. All filters are optional. If not set, or set to null, then filters will be ignored. Multiple filters are applied simultaneously.

Request Data

Request

{
  "merchantReference": "38424fc938424fc938424fc9",
  "paymentReference": null,
  "fromDate": "2020-03-01T00:00:00.000Z",
  "toDate": "2020-07-01T00:00:00.000Z",
  "consumerFirstname": "",
  "consumerSurname": "",
  "consumerEmail": "",
  "amount": 20000,
  "merchantId": 111,
  "status": "SETTLED",
  "paymentMethod": "CC"
}

Property	Type	Description
merchantReference	string	The unique merchant reference used in Create Payment , etc. (optional)
paymentReference	string	The unique PayGenius reference (optional)
fromDate	string	From date (format - yyyy-MM-dd'T'HH:mm:ss.SSS'Z') (optional)
toDate	string	To date (format - yyyy-MM-dd'T'HH:mm:ss.SSS'Z') (optional)
consumerFirstname	string	The consumer firstname or part thereof (optional)
consumerSurname	string	The consumer lastname or part thereof (optional)
consumerEmail	string	The consumer email or part thereof (optional)
amount	integer	The transaction amount to filter by (in cents) (optional)
merchantId	integer	The affiliated merchant id for which you want to filter the transactions (Retrieved from Get Affiliate Merchants) (optional)
status	string	The status filter. Possible values: `NEW` `AUTHORIZED` `SETTLED` `CANCELLED` `REVERSED` `REFUNDED` `THREE_D_SECURE` `MISSING` `FAILED`
paymentMethod	string	The payment method filter. Possible values: `CC` `EFT` `PAYOUT` `TRANSFER` `CHARGE` `OPENING` `POS` `POS_BATCH` `CHARGE_TERMINAL`

Response Data

Response

{
    "success": true,
    "message": "Successful",
    "transactions": [
        {
            "id": 31055,
            "reference": "9f0f9951-0fcf-45d1-b0f8-a594a17e6d2a",
            "currency": "ZAR",
            "amount": 25000,
            "date": "2020-03-29T18:03:04.000Z",
            "source": "SUBS_13",
            "merchantReference": "2199632178aa",
            "paymentMethod": "CC",
            "status": "SETTLED",
            "message": "Success",
            "suspended": false,
            "merchant": "My merchant",
            "consumerFirstname": "Bilbo",
            "consumerLastname": "Baggins",
            "consumerEmail": "bilbo@shire.com",
            "fees": 1000,
            "feesVat": 1150,
            "feesPercentage": 4.0
        },
        {
            "id": 32020,
            "reference": "20ddcd34-cdb1-4d57-ad28-c0e4d9f854a2",
            "currency": "ZAR",
            "amount": 1000,
            "date": "2020-07-29T15:11:51.000Z",
            "source": null,
            "merchantReference": "INV0071",
            "paymentMethod": "TRANSFER",
            "status": "SETTLED",
            "message": null,
            "suspended": true,
            "merchant": "Test Merchant",
            "consumerFirstname": null,
            "consumerLastname": null,
            "consumerEmail": null,
            "fees": 0,
            "feesVat": 0,
            "feesPercentage": 0.0
        },
        {
            "id": 32020,
            "reference": "df9da076-f60f-477a-b6b0-4f2e8275cf94",
            "currency": "ZAR",
            "amount": 15500,
            "date": "2020-07-30T19:23:52.000Z",
            "source": null,
            "merchantReference": "TR7657685",
            "paymentMethod": "TRANSFER",
            "status": "SETTLED",
            "message": null,
            "suspended": true,
            "merchant": "Affiliated Merchant 1 ",
            "consumerFirstname": null,
            "consumerLastname": null,
            "consumerEmail": null,
            "fees": 0,
            "feesVat": 0,
            "feesPercentage": 0.0
        }
    ],
    "code": 1
}

Property	Type	Description
success	boolean	`true` on success
code	integer	1 is successful
message	string	The response message
transactions	array TransactionDetails	An array of transfers

Transfer Methods

Our API allows merchants to transfer ZAR funds between affiliated merchant. Affiliated merchants are set up by a PayGenius system administrator on request.

Create Transfer

POST /pg/api/v2/transfer/create

Create a ZAR transfer to affiliated merchant(s). Note that forex transfers are not allowed with this API method. To prepare Forex transfers, rather use the Payment V3 API (/pg/api/v3/payment/create), or the Create Redirect method.

Request Data

Request

{  
  "fromMerchant":{
    "merchantId":186,
    "currency":"ZAR",
    "amount":7000,
    "merchantReference":"TRANSFER-TO-INV0071",
    "source": "transfer.com"
  },
  "toMerchants": [
    {
      "merchantId":182,
      "currency":"ZAR",
      "amount":7000,
      "transferDate":"2020-04-20T07:09:51.000Z",
      "merchantReference":"TRANSFER-TO-INV0071",
      "source": "transfer.com"
    }
  ],
  "reference": "TRANS #0071"
}

Property	Type	Description
fromMerchant	MerchantTransfer	The affiliate merchant that the funds should be transferred from
toMerchants	array MerchantTransfer	An array of affiliate merchants that the funds should split and transferred to (amounts must sum correctly)
reference	string	(max length: 99) The transfer reference for this transaction

Response Data

Response

{
  "success": true,
  "message": "Successful transfer",
  "transfers": [
    {
      "merchantId": 182,
      "merchantReference": "TRANSFER-MerchantTwo-TRANSFERINV0071",
      "transferDate": 1587420711000,
      "amount": 7000,
      "currency": "ZAR",
      "source": null,
      "reference": "680015a2-453e-4aab-add9-e0d5e923bf60"
    }
  ],
  "code": 1,
  "fromMerchantId": 186
}

Property	Type	Description
success	boolean	`true` on success
code	integer	1 is successful
message	string	The transfer message
transfers	array MerchantTransfer	An array of transfers matching the request with PayGenius transaction reference included (to be used when cancelling)
fromMerchantId	integer	The merchant id from where the funds were transferred

Cancel Transfer

POST /pg/api/v2/transfer/cancel

Cancels a transfer before transfer date.

Request Data

Request

{  
  "reference":"680015a2-453e-4aab-add9-e0d5e923bf60"
}

Property	Type	Description
reference	string	The original PayGenius transfer reference from response in Create Transfer Request)

Response Data

Response

{
  "success": true,
  "message": "Successful cancel",
  "reference": "499a1e01-106a-4173-a3a8-7eafc0f0da82",
  "code": 1
}

Property	Type	Description
success	boolean	`true` on success
code	integer	1 is successful
message	string	The transfer message
reference	string	The transfer cancellation reference

Get Affiliate Merchants

GET /pg/api/v2/transfer/merchants/get

Looks up all affiliated merchants. Funds can be transferred between your affiliated merchants.

Response Data

Response

{

  "success": true,
  "message": "Successful",
  "merchants": [
    {
      "id": 182,
      "dateCreated": 1579775253000,
      "dateUpdated": 1587326351000,
      "name": "My affiliated merchant one",
      "email": "bilbo+1@shire.com",
      "enabled": true,
      "settings": {},
      "logo": ""
    },
    {
      "id": 186,
      "dateCreated": 1579775253000,
      "dateUpdated": 1587326351000,
      "name": "My affiliated merchant two",
      "email": "bilbo+2@shire.com",
      "enabled": true,
      "settings": {},
      "logo": ""
    }
  ],
  "code": 1
}

Property	Type	Description
success	boolean	`true` on success
code	integer	1 is successful
message	string	The response message
merchants	array Merchant	An array of affiliate merchants

Get Outstanding Transfers

GET /pg/api/v2/transfer/list/get

Looks up all outstanding transfers for the next 90 days. Suspended = true is an indication that the transfer is pending.

Response Data

Response

{
    "success": true,
    "message": "Successful",
    "transactions": [
        {
            "id": 32020,
            "reference": "20ddcd34-cdb1-4d57-ad28-c0e4d9f854a2",
            "currency": "ZAR",
            "amount": 1000,
            "date": "2020-07-29T15:11:51.000Z",
            "source": null,
            "merchantReference": "INV0071",
            "paymentMethod": "TRANSFER",
            "status": "SETTLED",
            "message": null,
            "suspended": true,
            "merchant": "Affiliated Merchant",
            "consumerFirstname": null,
            "consumerLastname": null,
            "consumerEmail": null,
            "fees": 0,
            "feesVat": 0,
            "feesPercentage": 0.0
        }
    ],
    "code": 1
}

Property	Type	Description
success	boolean	`true` on success
code	integer	1 is successful
message	string	The response message
transactions	array TransactionDetails	An array of transfers

Subscription Methods

Our API allows merchants to edit and remove monthly/yearly/daily subscriptions.

Edit Subscription

POST /pg/api/v2/subscription/edit

Use this method to link a new card to a subscription (eg. when old card expired)

Request Data

Request

{  
  "subscriptionReference":"12",
  "creditCard":{  
      "token": "8a86c511-14e2-4981-b13a-041d53ff4f62"
   }
}

Property	Type	Description
subscriptionReference	string	You unique subscription reference used to create this subscription in Create Payment
creditCard	Credit Card	The new card object to be linked to this subscription

Response Data

Response

{
  "success": true,
  "message": ""
}

Property	Type	Description
success	boolean	`true` on success
message	string	The transfer message

Cancel Subscription

POST /pg/api/v2/subscription/cancel

summary

Request Data

Request

{  
  "subscriptionReference":"12"
}

Property	Type	Description
subscriptionReference	string	You unique subscription reference used to create this subscription in Create Payment

Response Data

Response

{
  "success": true,
  "message": ""
}

Property	Type	Description
success	boolean	`true` on success
message	string	The transfer message

Payment Page Methods

Our hosted payment pages allows merchants to accept payments, without having to worry about security, installing SSL certificates or PCI compliance.

Create Redirect

POST /pg/api/v2/redirect/create

This API call makes use of PayGenius hosted payment pages. To create a payment, you need to send a signed request to create a payment. This call will return a payment URL that you can redirect your clients to. Once they have concluded their transactions, they will be returned to your website on one of the three pages specificed in the original request.

Transfer

This API method now allows merchants to transfer up to 90% of the payment amount to affiliated merchants for foreign currency (non-ZAR). Such transfers are prepared with this API method and executed on successful payment. It can not be cancelled after payment. To transfer a portion of the payment to an affiliated merchant (or multiple affiliated merchants), include the transfer object with the API payload.

Request Data

Request

{  
  "transaction":{
    "reference":"Invoice #1871",
    "currency":"ZAR",
    "amount":100
  },
  "consumer": {
    "name": "Bilbo",
    "surname": "Baggins",
    "email": "bilbo@shire.com",
    "consumerAddress": {
       "addressLineOne" : "10 Test Avenue",
       "city" : "Cape Town",
       "postCode": "7441",
       "country": "ZA"
    }
  },
  "urls": {
    "success": "https://merchant.com/success-page",
    "cancel": "https://merchant.com/cancel-page",
    "error": "https://merchant.com/error-page",
    "notify": "https://merchant.com/notif-page"
  },
  "auth": false,
  "pageUrlKey": "demo_page",
  "threeDSecure": true,
  "description":"7 day tour to Egypt including airport transfers",
  "destinationCountry": "EG",
  "transactionDate": "2022-10-20",
  "pax": 2,
  "affiliateMerchantId":186,
  "recurring" : false
}

Request redirect with prepared transfer to affiliate merchant

{
  "transaction": {
    "reference": "REF04271322221",
    "currency": "EUR",
    "amount": 16000
  },
  "consumer": {
    "name": "Bilbo",
    "surname": "Baggins",
    "email": "bb.bb@paygenius.co.za",
    "consumerAddress": {
      "addressLineOne": "1 Main street",
      "city": "Cape Town",
      "postCode": "8000",
      "country": "ZA"
    }
  },
  "threeDSecure": true,
  "urls": {
    "cancel":"https://merchant.com/payment/MERCHANTREFERENCE01/cancel",
    "error": "https://merchant.com/payment/MERCHANTREFERENCE01/error",
    "success": "https://merchant.com/payment/MERCHANTREFERENCE01/success",
    "notify": "https://merchant.com/payment/MERCHANTREFERENCE01/notify",
  },
  "allowMultiCurrencyPurchase": true,
  "description": "Travel to Paris, Eiffel Tower, sight-seeing",
  "transactionDate": "2023-12-22",
  "destinationCountry": "FR",
  "pax": 2,
  "affiliateMerchantId": 189,
  "transfer": {
    "reference": "Transfers-FROM-ref-20220721",
    "toMerchants": [
      {
        "currency": "EUR",
        "amount": 11000,
        "merchantId": 188,
        "merchantReference": "Transfers-TO-ref-20220721"
      }
    ]
  }
}

Property	Type	Description
transaction	Transaction	The transaction details
consumer	Consumer	The consumer details
consumer.consumerAddress	Consumer Address	The consumer's address. Required for non ZAR currencies
urls	URLs	The redirect urls
auth	boolean	(optional: `false`) If set to `true`, only authorizes the amount on the user's account
pageUrlKey	string	(optional: `null`) The payment page url key to be used to process the payment. The pageUrlKey string is the section of the payment page URL coming after https://www.paygenius.co.za/pay/ (for example, for the payment page: https://developer.paygenius.co.za/pay/demo_page, the pageUrlKey string is demo_page
threeDSecure	boolean	(optional) If set, forces 3D Secure to always be enabled or disable for this payment request. If not set, then the sytem will use the existing merchant settings to determine if the payment should be 3DSecure or not.
description	string	(required for travel payments in foreign currency : non-ZAR) Full description of what this payment is for. Must be descriptive enough for travel insurance purposes. Eg. Hop on Hop off Rome sightseeing tour
destinationCountry	string	(required for travel payments in foreign currency : non-ZAR) Country travelling to or product destination country. Eg. ZA
pax	number	(optional for normal merchants, required for travel merchants) The number of people travelling (if travel booking) or the number of items / packages (default 1)
transactionDate	string	(optional for normal merchants, required for travel merchants) The end date of travel or delivery date (format - 'yyyy-MM-dd') (default today)
affiliateMerchantId	integer	(optional) The affiliated merchant id that this payment should be done for (Retrieved from Get Affiliate Merchants)
recurring	boolean	(optional) Indicate that the resulting tansaction fom this payment request could be used for subsequent recurring payments against the stored card. PayGenius will store the card upon successful payment, which means that this payment reference can then be used to switch future recurring payments against the card.
transfer	Transfer	(optional) The forex transfer, with amount(s) to be allocated to affiliate(s)

Response Data

Response

{
    "success": true,
    "redirectUrl": "https://www.paygenius.co.za/pay/merchant/en/bc367bd5-ccd8-4e4c-a2b4-8b68e914ed8a",
    "reference": "bc367bd5-ccd8-4e4c-a2b4-8b68e914ed8a"
}

Property	Type	Description
success	boolean	`true` on success
redirectUrl	string	The URL to redirect the user to
reference	string	The payment reference for this transaction

Lookup Payment

GET /pg/api/v2/redirect/{payment_reference}

Looks up the status of a transaction using the payment reference.

Response Data

Response

{
    "success": true,
    "reference": "38424fc9-d7de-4215-9e9d-93e40bd94160",
    "amount": 100,
    "currency": "ZAR",
    "status": "SETTLED",
    "date": "2023-05-05T13:46:24.000Z"
}

Property	Type	Description
success	boolean	`true` on success
reference	string	The transaction reference
amount	integer	The transaction amount in cents
currency	string	The transaction currency
status	string	The transaction status

Object Definitions

Credit Card Object

The credit card object is used to represent card information.

Using Raw Card Data

{  
  "number":"4550270020473018",
  "cardHolder":"B Baggins",
  "expiryYear":2023,
  "expiryMonth":6,
  "type": "visa",
  "cvv":"019"
}

Using a Tokenized Card

{  
  "token": "8a86c511-14e2-4981-b13a-041d53ff4f62"
}

Using a Transaction Reference

{  
  "transactionReference": "8a86c511-14e2-4981-b13a-041d53ff4f62"
}

Using a Payment Reference

{  
  "paymentReference": "8a86c511-14e2-4981-b13a-041d53ff4f62"
}

Property	Type	Description
number	string	The credit card number
cardHolder	string	The card holder's name
expiryMonth	integer	One or two digit number representing the card’s expiration month (NB: No leading zeros)
expiryYear	integer	Four digit number representing the card’s expiration year
cvv	string	The card cvv. CVV can be any 3 numbers for Visa and MasterCard or 4 number for American Express
type	string	The credit card type
token	string	The token for a stored card
paymentReference	string	A payment reference to transact against
transactionReference	string	A transaction reference to transact against

Data	Description
Raw Card Data	Send through all card data to make a payment request
Tokenized Card	Transact using a card registered in the card vault
Payment Reference	Transact using a hosted payment page reference
Transaction Reference	Transact using a previous transaction reference, obtained when first creating a payment

Transaction Object

The transaction object contains information about the transaction.

Transaction Object

{  
  "reference":"Invoice #1871",
  "currency":"ZAR",
  "amount":100,
  "source": "shire.com"
}

Property	Type	Description
reference	string	(max length: 99) The merchant reference for this transaction
currency	string	The payment currency `ZAR` `USD`
amount	integer	The amount in cents for the transaction
source	string	(optional) A freeform text field to help merchants distinguish where the transaction came from (e.g. a mobile app / website)

3D Secure Object

If 3D secure is required to authorize a payment, this object will be provided containing the information to post to the bank's access control server.

3D Secure Object

{
  "acsUrl": "https://acstest.bankserv.co.za/V3DSStart?osb=visa-default&VAA=B",
  "transactionId": "l2SUAS4PMJYpMzZfIql0",
  "paReq": "eNpVUttygjAQfc9XOH4AAcRLnTUzKNXCjI4V7FjfYoyFioABvH19E4Xavu3Z3Tk552wgCAXnjs9ZKTiBKc9z+sUb0XbQjE1/afvWfOp9ZtPbeuceY71JYG4v+JHAiYs8ShNiaLpmAq4hkhSChTQpCFB2HLoz0mlbLdMAXEEEBy5chxhmy2p3uj3AD4wgoQdOhjTZ51yc7J2IGG3UbIDvUwQsLZNCXEnX0AHXAEEpYhIWRdbH+Hw+a5uKRWOpdqOA1RgBfmqbl6rKpeVLtCUbxws+luNgNh7O/Dg+B6uMrvfxZePYA8BqA8GWFpyYutHVX/RWwzT6ZrtvSVv3PgJ6UFrIQuYhhVUIQabesR/IUJO/DemmFIInrLZTIwT8kqUJlzsy299aOnjqHr2phFkho3sPAzYZLTxv3TIn4ekWTpOr+zr6Xq32Kvb7zp0yklkZPfVUBSSj4sHVUXF1f1n9+xc/Emm0ng=="
}

Property	Type	Description
acsUrl	string	The bank's access control server to post the authorization request to
transactionId	string	The transaction id to post through to the access control server
paReq	integer	The payment authentication request to post through to the access control server

3D Secure V2 Object

If 3D secure V2 is required to authorize a payment, this object will be provided containing the content of the iframe that will automatically send information about the user's browser to the bank (Step 2), or the information to post to the bank's access control server. (Step 3)

3D Secure V2 Object (Step 2)

{
    "tdsMethodContent": "<iframe id=\"tdsMmethodTgtFrame\" name=\"tdsMmethodTgtFrame\" style=\"width: 1px; height: 1px; visibility: hidden;\" src=\"javascript:false;\" xmlns=\"http://www.w3.org/1999/xhtml\"> <!--.--> </iframe><form id=\"tdsMmethodForm\" name=\"tdsMmethodForm\" action=\"https://acsabtest.bankserv.co.za/mdpayacs/3ds-method\" method=\"post\" target=\"tdsMmethodTgtFrame\" xmlns=\"http://www.w3.org/1999/xhtml\"> <input type=\"hidden\" name=\"3DSMethodData\" value=\"eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogImFiODAwNGU2LTJmYWEtNWNiZC04MDAwLTAwMDAwNmU3ZWQzOSIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovL21zZ3Rlc3QuYmFua3NlcnZhZnJpY2EuY29tL21kcGF5bXBpL01lcmNoYW50U2VydmVyP21uPVkmdHhpZD0xMTU4NjI4NDEmZGlnZXN0PSUyRjdqcSUyRjg1bmp2cDZhREttRCUyRjJ3YnFZOW9xJTJCelVWUkZFY2g0SktrYU53NCUzRCIgfQ\"/> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogImFiODAwNGU2LTJmYWEtNWNiZC04MDAwLTAwMDAwNmU3ZWQzOSIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovL21zZ3Rlc3QuYmFua3NlcnZhZnJpY2EuY29tL21kcGF5bXBpL01lcmNoYW50U2VydmVyP21uPVkmdHhpZD0xMTU4NjI4NDEmZGlnZXN0PSUyRjdqcSUyRjg1bmp2cDZhREttRCUyRjJ3YnFZOW9xJTJCelVWUkZFY2g0SktrYU53NCUzRCIgfQ\"/> </form><script type=\"text/javascript\" xmlns=\"http://www.w3.org/1999/xhtml\"> document.getElementById(\"tdsMmethodForm\").submit(); </script>",
    "txId": "115862841",
    "transactionId": "9dFK70g23ZJenr39OLvdtz8qkm8=",
    "sessionData": null,
    "acsUrl": null,
    "creq": null
  }

3D Secure V2 Object (Step 3)

{
    "tdsMethodContent": null,
    "txId": null,
    "transactionId": "9dFK70g23ZJenr39OLvdtz8qkm8=",
    "sessionData": "OWRGSzcwZzIzWkplbnIzOU9MdmR0ejhxa204PQ",
    "acsUrl": "https://acsabsatest.bankserv.co.za/mdpayacs/creq",
    "creq": "ewogICAiYWNzVHJhbnNJRCIgOiAiMmUzNmJiZmMtZTI2NS00Y2U0LTg1YjQtOTVhOWU3NjhhMTE0IiwKICAgImNoYWxsZW5nZVdpbmRvd1NpemUiIDogIjAzIiwKICAgIm1lc3NhZ2VUeXBlIiA6ICJDUmVxIiwKICAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiYWI4MDA0ZTYtMmZhYS01Y2JkLTgwMDAtMDAwMDA2ZTdlZDM5Igp9"
  }

Property	Type	Description
acsUrl	string	The bank's access control server to post the authorization request to
transactionId	string	The transaction id
creq	string	The payment authentication request to post through to the access control server
sessionData	string	The payment session data to post through to the access control server

URLs Object

If a redirect from and to the merchant's site is required, this object represents the different URLs available.

URLs Object

{
  "success": "https://merchant.com/success-page",
  "cancel": "https://merchant.com/cancel-page",
  "error": "https://merchant.com/error-page",
  "notify": "https://merchant.com/notify-webhook-api-endpoint"
}

Property	Type	Description
success	string	The URL to redirect the user back to when a transaction succeeds
cancel	string	The URL to redirect the user back to when a transaction is cancelled by the user
error	string	The URL to redirect the user back to when a transaction fails
notify	string	The API endpoint that the merchant want to be notified on if the payment was successful.

Consumer Object

Represents consumer personal information.

Consumer Object

{
  "name": "Bilbo",
  "surname": "Baggins",
  "email": "bilbo@shire.com"
}

Property	Type	Description
name	string	The consumer's name
surname	string	The consumer's first name
email	string	The consumer's email address

Consumer address object

Represents consumer personal information.

Consumer Address Object

{
  "addressLineOne": "10 Test Street",
  "city": "Cape Town",
  "postCode": "7441",
  "country": "ZA"
}

Property	Type	Description
addressLineOne	string	Consumer's addres
city	string	City
postCode	string	Postal Code
country	string	Consumer's country of resindence

Subscription Object

The subscription object contains information about the subscription (when added to payment/create, a subscription will be created).

Subscription Object

{  
  "reference":"12",
  "interval":"MONTHLY",
  "trialDays": 30,
  "firstname": "Bilbo",
  "lastname": "Baggins",
  "email": "bilbo@shire.com"
}

Property	Type	Description
reference	string	(max length: 99) Your unique system reference for this subscription (eg. subscription id or user id)
interval	string	(optional) (default MONTHLY) The subscription interval. Possible values: `MONTHLY` `DAILY` `YEARLY`
trialDays	integer	(optional) (default 0) The number of days for trial period (if any) before subscription payment will be collected every month/year/day
firstname	string	The subscriber's first name
lastname	string	The subscriber's last name
email	string	The subscriber's email address (success/failure emails will sent to this email every interval)

Merchant object

The merchant object contains information about your affiliated merchants (eg. id).

Merchant Object

{
  "id": 186,
  "dateCreated": 1579775253000,
  "dateUpdated": 1587326351000,
  "name": "My affiliated merchant one",
  "email": "bilbo+2@shire.com",
  "enabled": true
}

Property	Type	Description
id	integer	The merchant identifier (to be used when doing transfers or affiliate payment requests)
dateCreated	integer	epoch timestamp (ms) that this merchant was created
dateUpdated	integer	epoch timestamp (ms) that this merchant was updated
name	string	The merchant name
email	string	The merchant contact email
enabled	boolean	`true` if this merchant is active

Merchant transfer object

The merchant transfer object contains information about the amounts, dates and merchant for from/to merchant.

Merchant Transfer Object

{ 
  "merchantId":186,
  "merchantReference":"TRANSFER #1871", 
  "currency":"ZAR",
  "amount":100,
  "transferDate":"2020-04-20T07:09:51.000Z",
  "source": "transfer.com",
  "reference": "680015a2-453e-4aab-add9-e0d5e923bf60"
}

Property	Type	Description
merchantId	integer	The affiliate merchant merchant identifier (Retrieved from Get Affiliate Merchants)
merchantReference	string	The reference for the affiliate merchant
currency	string	The payment currency `ZAR` `USD`
amount	integer	The amount in cents for the transfer
transferDate	string	The effective date (in future) when the transfer must take place. (format - yyyy-MM-dd'T'HH:mm:ss.SSS'Z') (optional for fromMerchant)
source	string	(optional) A freeform text field to help merchants distinguish where the transfer came from (e.g. a mobile app / website)
reference	string	(read-only) The PayGenius reference for the transfer

Transaction details object

The transaction details object contains information about the amounts, dates, fees, consumer and payment method. This includes charges, payments (EFT/Credit card), transfers and payouts.

Transaction Details Object

{
  "id": 31055,
  "reference": "9f0f9951-0fcf-45d1-b0f8-a594a17e6d2a",
  "currency": "ZAR",
  "amount": 25000,
  "date": "2020-03-29T18:03:04.0",
  "source": "SUBS_13",
  "merchantReference": "13",
  "paymentMethod": "CC",
  "status": "SETTLED",
  "message": null,
  "suspended": true,
  "merchant": "Merchant Name",
  "consumerFirstname": "James",
  "consumerLastname": "Anderson",
  "consumerEmail": "jadr@james.co.za",
  "fees": 1000,
  "feesVat": 1150,
  "feesPercentage": 4.0
}

Property	Type	Description
id	integer	The identifier for this transaction
reference	string	The PayGenius reference for the transaction
currency	string	The payment currency `ZAR` `USD`
amount	integer	The amount in cents for the transaction
date	string	The date that the transaction took place. (format - yyyy-MM-dd'T'HH:mm:ss.SSS'Z')
source	string	(optional) A freeform text field to help merchants distinguish where the transaction came from (e.g. a mobile app / website)
merchantReference	string	The merchant reference for the transaction
paymentMethod	string	The payment method `CC` `EFT` `PAYOUT` `TRANSFER` `CHARGE` `OPENING` `POS` `POS_BATCH` `CHARGE_TERMINAL`
status	string	The PayGenius status for the transaction `NEW` `AUTHORIZED` `SETTLED` `CANCELLED` `REVERSED` `REFUNDED` `THREE_D_SECURE` `MISSING` `FAILED`
message	string	A message (usually contains failure message in case if unsuccessful transaction)
suspended	boolean	`true` if this transaction is in suspended state
merchant	string	The merchant that this transaction is linked to
consumerFirstname	string	The consumer first name (could be null)
consumerLastname	string	The consumer last name (could be null)
consumerEmail	string	The consumer email (could be null)
fees	integer	The fees in cents for the transaction
feesVat	integer	The fees (incl VAT) in cents for the transaction
feesPercentage	float	The fees percentage for the transaction

Prepared transfer object

The prepared forex transfer object contains from reference, and transfer receiver(s) information.

Prepared Transfer Object

{
  "reference": "Transfers-FROM-ref-20220721",
  "toMerchants": [
    {
      "currency": "EUR",
      "amount": 11000,
      "merchantId": 188,
      "merchantReference": "Transfers-TO-ref-20220721"
    }
  ]
}

Property	Type	Description
reference	string	The from merchant transfer reference
toMerchants	array	Array of affiliate receivers containing amount, currency, affiliate merchant id and receiver transfer reference

Webhook Definitions

Payout Webhook

PayGenius allow merchents to provide PayGenius with a webhook URL that will be called whenever a payout is done for that merchant or any of its affiliate merchants. PayGenius will post the details, including the paid out transactions, in a POST request with Content-Type 'application/json' to the merchant webhook. If a merchant wants to enable this functionality, he must provide his Webhook URL to PayGenius support.

Payout webhook example payload

{
  "payoutDate": "2022-07-23 08:43:31",
  "totalAmount": 178200,
  "totalFees": 2556,
  "netTotal": 175644,
  "payoutId": 64,
  "currency": "ZAR",
  "hash": "f90743bd011f1deca087e27e0e5e3782",
  "merchantName": "Merchat affiliate name",
  "merchantId": 189,
  "channelId": 188,
  "transactions": [
    {
      "merchantReference": "TRANS-MT-3MJU-63LD-IY6E-UGZF-EAGK",
      "amount": 55600,
      "fees": 0,
      "feesVat": 0,
      "netAmount": 55600,
      "currency": "ZAR",
      "paymentReference": "8a401bb5-298e-4811-8f9c-1baf9294121c",
      "status": "SETTLED",
      "consumerEmail": null,
      "consumerFirstname": null,
      "consumerSurname": null,
      "threeDomainSecure": "",
      "dateCreated": "2022-03-02 10:50:20",
      "dateExecuted": "2022-03-07 02:00:00",
      "paymentMethod": "TRANSFER"
    },
    {
      "merchantReference": "Transfers20220721-ACT-TEST",
      "amount": -11000,
      "fees": 0,
      "feesVat": 0,
      "netAmount": -11000,
      "currency": "ZAR",
      "paymentReference": "16b70b09-e84c-41b3-803c-e02f3a93237d",
      "status": "SETTLED",
      "consumerEmail": null,
      "consumerFirstname": null,
      "consumerSurname": null,
      "threeDomainSecure": "",
      "dateCreated": "2022-07-23 08:23:44",
      "dateExecuted": "2022-07-23 08:23:44",
      "paymentMethod": "TRANSFER"
    },
    {
      "merchantReference": "TRANS-MT-4FVH-KJ3E-HYFR-RCKM-AEIZ",
      "amount": 55600,
      "fees": 0,
      "feesVat": 0,
      "netAmount": 55600,
      "currency": "ZAR",
      "paymentReference": "f0526001-2f3e-4099-b8d0-2d707a9bad73",
      "status": "SETTLED",
      "consumerEmail": null,
      "consumerFirstname": null,
      "consumerSurname": null,
      "threeDomainSecure": "",
      "dateCreated": "2022-03-02 09:57:34",
      "dateExecuted": "2022-03-08 02:00:00",
      "paymentMethod": "TRANSFER"
    },
    {
      "merchantReference": "ACTB-5682-CCD6-MT-2KMN-YZBC-S2G6",
      "amount": 78000,
      "fees": 2223,
      "feesVat": 2556,
      "netAmount": 75444,
      "currency": "ZAR",
      "paymentReference": "3b0455ac-87bc-4cce-b3b6-79bd649bc70c",
      "status": "SETTLED",
      "consumerEmail": null,
      "consumerFirstname": null,
      "consumerSurname": null,
      "threeDomainSecure": "USED",
      "dateCreated": "2021-02-03 09:56:36",
      "dateExecuted": "2021-02-03 09:57:01",
      "paymentMethod": "CC"
    }
  ]
}

Property	Type	Description
hash	string	This is used by the merchant to validate that the payload comes from Paygenius. It will be equal to the MD5 of the payoutId and merchant secret concatenated (eg. var payoutId = 64; var hash = md5( payoutId + '--merchantSecret--'); )

Merchants should use their own merchant secret to validate the hash, even if the payout is for one of their affiliates.

Success / Failed / Pending Payment Webhook (Notify URL)

A merchant can set the Notify URL or Webhook URL for any payment created via the Create Redirect or Create Payment - Other API methods. (urls->notify object). PayGenius will then notify merchants of any successful payments on this URL. PayGenius will retry these notifications if an HTTP response code other that 20X (success) is received, up to 20 times or for three days.

Depending on merchant configuration in the PayGenius system, PayGenius can also notify merchants of failed, pending and refunded payments against this Notify URL. If a merchant wants the pending / failed / refund option to be enabled, they should get in touch with PayGenius Support (these options are disabled by default for all merchants)

PayGenius will post the details of above mentioned transactions in a POST request with Content-Type 'application/json' to the merchant webhook (notify url).

Successful payment webhook/notify example payload

{
  "success": true,
  "amount": 10600,
  "currency": "ZAR",
  "paymentReference": "18461a9f-f102-1752-b3e7-1612e35e5541",
  "paymentDate": "2024-11-22 12:14:46",
  "merchantReference": "Merchant_TRN-REF-0001",
  "status": "SETTLED",
  "date": "2024-11-22T12:14:46.000Z",
  "hash": "7118de0bcbecbab3de24290e0c28c8bd",
  "bin": "525676XXXXXX1131"
}

Failed payment webhook example payload

{
  "success": false,
  "amount": 10600,
  "currency": "ZAR",
  "paymentReference": "18461a9f-f102-1752-b3e7-1612e35e5541",
  "paymentDate": "2024-11-22 12:14:46",
  "merchantReference": "Merchant_TRN-REF-0001",
  "status": "FAILED",
  "date": "2024-11-22T12:14:46.000Z",
  "hash": "7118de0bcbecbab3de24290e0c28c8bd",
  "bin": "525676XXXXXX1131"
}

Pending payment webhook example payload

{
  "success": false,
  "amount": 10600,
  "currency": "ZAR",
  "paymentReference": "18461a9f-f102-1752-b3e7-1612e35e5541",
  "paymentDate": "2024-11-22 12:14:46",
  "merchantReference": "Merchant_TRN-REF-0001",
  "status": "NEW",
  "date": "2024-11-22T12:14:46.000Z",
  "hash": "7118de0bcbecbab3de24290e0c28c8bd",
  "bin": ""
}

Refund webhook example payload

{
  "success": true,
  "amount": -10600,
  "currency": "ZAR",
  "paymentReference": "18461a9f-f102-1752-b3e7-1612e35e5541",
  "paymentDate": "2024-11-22 12:14:46",
  "merchantReference": "Merchant_TRN-REF-0001",
  "status": "REFUNDED",
  "date": "2024-11-22T12:14:46.000Z",
  "hash": "7118de0bcbecbab3de24290e0c28c8bd",
  "bin": "525676XXXXXX1131"
}

Property	Type	Description
success	boolean	States whether the transaction was successful or not
amount	integer	The transaction amount in cents
currency	string	The transaction currency
paymentReference	string	The transaction reference (PayGenius Reference)
merchantReference	string	The merchant reference used in Create Redirect
paymentDate	string	The transaction execution date (format yyyy-MM-dd HH:mm:ss)
status	string	The PayGenius status for the transaction `NEW` `SETTLED` `CANCELLED` `REFUNDED` `FAILED`
bin	string	The masked transaction card number (only for Credit and debit card)
date	string	The transaction execution date (format yyyy-MM-dd'T'HH:mm:ss.S)
hash	string	This is used by the merchant to validate that the webhook payload comes from Paygenius and not a 3rd party pretending to be PayGenius. It will be equal to the MD5 of the paymentReference and merchant secret concatenated (eg. var paymentReference = '18461a9f-f102-1752-b3e7-1612e35e5541'; var hash = md5( paymentReference + '--merchantSecret--'); )

Super merchants should use the sub-merchant's secret to validate the hash.

Constants

Transaction Statuses

Status	Description
`AUTHORIZED`	Funds have been reserved on the user's account
`SETTLED`	The transaction has been completed
`CANCELLED`	The transaction was cancelled by the user
`REFUNDED`	A completed refund transaction
`THREE_D_SECURE`	Awaiting 3D secure confirmation
`FAILED`	Indicates a failed transaction
`REVERSED`	The transaction has been reversed

Card Types

Type	Description
`visa`	Visa
`mastercard`	Mastercard
`diners`	Diners Club
`amex`	American Express