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
- For
GET
requests, only the full request URI is needed. - For
POST
requests, the full request URI needs to be concatenated with the POST data, separated by a single newline (\n
) character.
- For
- 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'shash_hmac
function), the returned value is hex encoded by default, and this step is not required).- 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:
- 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.
- 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"
}
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"
}
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"
}
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"
}
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
}
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
}
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) |
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 |
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') |
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
}
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
}
This method is used to refund a payment that was previously settled.
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) |
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
}
This method is used to refund a payment that was previously settled.
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:
|
paymentMethod | string | The payment method filter. Possible values:
|
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
|
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 |
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:
|
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 |
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 |
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
|
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
|
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
|
status | string | The PayGenius status for the transaction
|
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.
The netTotal is the actual amount that is paid out. netAmount = totalAmount - feesVat
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 |