NAV Navbar
JSON
  • Obtaining Your Access Details
  • Making Requests
  • Card Payments - ZAR
  • Card Payments - Other
  • Card Vault Methods
  • Instant EFT Methods
  • Transaction Methods
  • Transfer Methods
  • Subscription Methods
  • Payment Page Methods
  • Object Definitions
  • Webhook Definitions
  • Constants

    • 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:

    1. 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.
    2. Trim all whitespace from either end of the data.
    3. Generate a SHA-256 HMAC, using the prepared data, and the provided secret key.
    4. 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.

    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

    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":"eNrNWVnPo0iy/Sulnkd3N6uNabk+KZPdGAxm543NLGaxWQzm1w+2q6praurOnZ4rXY0liySIjIzMjBMnEnZm1iYJayTR0CYfOyXpuiBNPuXx518k9MwBWmHTrTHAo4EKzBb95WOngVPSvRRerf9B6560Xd7UH9jv6O/4Dvl6uwzQRllQ9x+7ILpBSf0g15s1udkhX253VdJK7Af65YfhxAZfL4/f4h3yZ39teLa6xekpjz8ME1Yni1ub1qk+8iqmX2hT4WL2yILPO+SpsYuDPvnAUWyDoRj9CSP/INE/SGKHvOS769McqJphsY1RW3wZfId8L9wtK9QmdfT4oLDl0be7XTJdmzpZNJZ5fmvvkD/9uwb1twm9fuR6vdhepDvT/dj1efW9X+uXX9QOecl3XR/0Q/fh7ZAvrV0U3O8fAAAIM86z0qUFDDaGmcGB12+Z70tll0T5B7qM9Ly+eoEybdq8z6qnq/8o2CFPV5DXln7sjDytl8Ha5NNUlXX3+Zes769/IMg4jr+PxO9NmyLPBUJQGlkU4i5P//bLu1cSS/W5+UvdmKBu6jwKynwO+iVIlKTPmvjTN99+ZsY8PS1hyIljfltM/RZhZP3bU4IS2Hqxifzc6Hcz+3dG+dHZtgt+67IAew7wg6GP3Sk5J8+ISD5ZJ+nzL3/7V+hg8zTp+v/Eha/Df2/hqz07KIfkw2+7s6wZhUZPnTCKB75BVO/eUECVPn/t99bcId98/jKh9+59t0pvxaMJ7vowsp2GWpHnjGZ8tcybbxaCMhh3Xi4ujXRTfXf0jyNKZkG+YSksO+5Z0k9PlouWjkvHQqtLV5Hbl6m/L2mZC8gQaXH/OgDLte5NiaMmRUnnIyuk9s0TJkzbl6c+NkqlXp9XuW77dRpc0hFtG8PmjaN7v7ckZB/TXQ0Cij6dHmSvHDTULy964Lhed7iJgmIpx+rYVP75YsqPNQgMfKK60LkQDupXbdBq2VUSY1ET4e2A31LGBKU0b63ADz2XOq3vLk4SGU9IrRH4LTZeA4uqL3e5DTFifwihrtiTqY05CWlelvkkvlJhZ13XiqaER5IaMykBdlQreXX293N7OKodTtnIBPVB//z5uyj6siNy8njvgLtGaTbog3fLGMIiiXo1WDICo36+512wBAL+66ej9flkgOX6mQmueR+Un4518usn5rNl/PrJMD8rwZLPo2zokr7vfv10+AyT+Ny08Q750exrHCZp+/y8wGbJiIok8ZrJMJBxUjBKEKTSCeyDVXRjOWStEKorudZKbrOzPrK6t5cbX8rukQp07gB1MEYmd1DARQCYxcFMYWxbmVgTHGCq2hA0JuT9vYVy02EG/VvWmfvSv0Y4lxrOGvXd/eC5p2uIr7OQgeZyjweOWkocP0c4XQQOjwYOPSiGNErAY21dZ7mpdAJXzSTBZkMc65c+hW/AfUSoWOCsa4lToQJJlzU5XDHBpBTcrJrppJbNU0b+IBvDgtMVQL7nMCmiXtkXv6IfPss5CtRfcgYqquk8feKLQLRn3z2h0fzPc+dZYHydO4OqWSSU6IKl1MTXpaKPI5O+5nDgRtV4rgtnAu2tr5iM+FwXfg4E7rHsC5QKoML0cssuuUCPKFzWnAfgyAB9C57PmVRe2hwgruWWd6/YSJh0ReHoxTSmUuUDLhzR436YhseVnUMBRC0yV9ZxHrOEvfjp+lZv2ePgTyBscNDf43vkMkOG0eyxbR9i7O+zOAWRg96YwW1P4rXa3oLupoD19joq+k3nc5iHrTOGDVqoNy+Z8DojbBcjeaJsZ3cVVqdZy8LWV5Mb9Mg8SAKPmg8CiE/NNDbnSjA547HZ3OiIuSSrnA5a2ZfVYY0X+eniS8UdGfUtrGhK7Rymn7ZM2tgXmcIggj/QJSBdVLV0vg3vCYdcN/s93cjXE3VRcqIhMzzYWqC8q/JsbovSlQlOXNAsoUY7ZpghSaSjwqN/9RG5xWf2tLVlvdAVNznNmVf2/CixQAewISWILvgAETr6uifJowehbonLunOOCV2FsQSG6QSgWzycAcyysonF03jMt/cQV+eIWePPWD1U6j006LtHqKPCkN/3YbJ8/62P76wfIT51h/oVC4VnrIsQRxf50t9BBw+3HwrcPmMulkbdU2AAeBVh5dIaDqi0SS5MfLmxxImo3YJMZAWML11u5OCymowCwJhGzUsmjgYcCwbeZ9A0TJDuJS8PxCWu2eZ+QO0hqugu/OK/h3PL2HR/wN+YW+bzCFkGXm4MLDbLXwpg7kwXzwWbw4Pmw3p/D4VxiKty9pwv8zeb+che7h5O0vZTbsBSX2yGjv3wcCs1XHWOnXLwH5DVjanQbNs8CDSm2X89XxyELW1fSlM36WLRWWT+1cN51Lf3ZVzRxRcbyjI39Av2Y/a9RtySB8WUBfETl6JOcnyqW+EgoUEh5JCbkmPaH2qpH5bSM6vyaDzqC6ZPaApZaVRYMMDUrlNdgWChGYVR/tzrJb/yWfxtr2MiJt77/GVtCdgG5o+Y775gngMuoa/aeEjHqE+C48M3TeFGpEJPQU89Hg5rd3sjs7PQ0oPr6aSBitZcChtYSXk5ma18PFp3J0x7ccimLtLYlBjrUbe67uTixnbcrNbaXVI0zK27Q0sMw12ngvng1Rt4OJkrZXw8GGTTbT3BvaeK3+j7Cjlo500JHwCyhOzMLdn0Jep6gR9s45KBxys74iE9BCsUtTswYIIRaqVuWqnvp54m9yKp65ovGFqDi2PiNOZjpMqSyDxXPVuJXITVsUjP3jrtlK13fGDkWmGjwD6Cqd3G6XkSLDZK1wp9kxRqvVpdl/W5VmcJm3gfmOaZdMe+gAl6KzFJ6cr5sG9FyS9XU+iUtOs1K/f0uKRPgv6RFX9Kk8K80CQ4/kmTaoZ6JoQIO3HNYRZcZ8S3J/BTmgzm/yeaPI2jkH6lSfVnNGmEOI1+oUdMYb2Hyi7XIhrf9Cg9njKlAKNieqOKNf+9FP8XKLK9VMwa1VfCpdIfPk5f5OmKxat6TxL70c0Enwp4HtNyZW2UDGfoOH6zkRICYhQ9T9vmGIUIuu6pMOeJgWw3xeBKIj8W411+8Aq/uVTQc++RHmy1mFrzDFYT57PUZlyxKuOwWk6ms4xm2tl7uJx/Y69idhnq6s5StxmDnCNzlGp5Nn/izs3Vzs+lnNt+5LViTjF7kEDVo+JHeq8kpRatRCTVnjXWtzNS06yun8/2o15neydfawncUrVZ9o/tHBc53hdUDfCVR2gH+bS3iAcmhVF2E8ravU1BIC/18kHtcv9Ga+YoBwvrr4aK6N3zeiCroZxPwtHJcGtlXchD3VcKz4TI4ba/OLVlJ6vvKLIrFooMyFEcX6mwgDAd+QZYvJmz7LztNALMYocJSJoo0pF1RyoaufSlawJdRBZAjTB9pt8FWyxYv1KvAbhXHC50CZ0EgiU9L3Q7SuN3NJxyDo9naCy+aGdJqNGbcr7QZiT011ccvP06w6UNFspDZoA3rJEqjTf+r5SHvaiY1Z3vYtFe6I3QB4/Ydwr7SI83QGaF/4+pvSqH+EcKNOgiqsb7i/4sFfrWk9axMqrU0qroe8ysn8/H1AvS1Dsuf0Y4V/83Wn3bne4LjT5x2oWE9VVvH9anZex1FgvlPaz4TuLVMqqfVGml+kLHSwlzfWOXRJ6lx6JXLdhd9G3Dd/37k1Kf2DWFco5ZcHxT5haC85ZbStoFe94ovunxCKHH/etSZTk4GzfBkEKC1bllzywAltgCOqS9FU/TfSaCYzYt1BOZNBMyTW0zfVgRmVOe8Rru6yHQk+bcx0fZ6QvUO5oFpVmBfHTOYxT6hgg3RKtUh9yuKP8m2XXsTHcITwfMjNJwDFK2PqSg1RVZrD18EPSzVnBL5gN17STe/hyvotPebjYycSJhqAszb4gBnuNBu0Ead5bURzABN24ElGRmXEO1aoMRS8K8FvzDy0sDIZcMmGDmBbmLnVnzI19e6GWLDls7g8GmINFzEPADsjnnNbWVm+uF3qRiDCQV60OA4apatVSoY1erQ2tZzGZdaE5uOngxZXlHOsc71WYwZg0Ifhs317G747qMrwjihq6POEKyac2T1XroNiebJtl/j/bY5gnt5vaV9nSO9DDzhCLwfoArx+IxH0TeP6VhiwcsbBW9Gxn9ldIFbtzb1sypCujeJ6pM4d4VGndXGPQtm5TqPwjNSWRB8PUUxWFv6vkeWhL/gusoZpGqLFWaWkj4cp2OrII7T1nxkqFL9TapBfdwiv8+39OUy3+EyLLOL4iwI3g+l0HzhAtzt+m1I1abDK+YqWTOB57uRI1keHObR33PoiGKaFVcZPh2L7nsrTuamijit8O+QFv1bEudL0JwIbnyylMdq43d6XTknBWmy9vwFNgyRWzwVpNTEUsRbjlKahKekSKh2TM5i/de3AaNXY6x7d8c7GBQXspXj+uIE6dhzDxki902FjM/WtTU1hTtn+KMw5ttxWj4SJbanp6jaGURaHvDafpxlOa5bImJp2ZjKHre6YKa7jw3H4UYgVUjN4ozsFcJuZCrRu4EISnNLQlMuEL7+7yVNd5Kj8bYgeUkXlq3rXSQr0liebkvNAScVIrqV+rYx0hRlTm/ZCFh7gRxgvdzcIjdZOPtcW6NkD1Il4oeCIVeLDsFtt+fqngFKM+UN7JvStPelKazCz0JCkTfp4tUdxbOso9Lja09RiRilWS2whUkx5RUz2w//wRDXyt/hIdnd4qYw6UlVcc4IdfalS1zHJWsevRKboWaYxF75GaDvtJUwuWa0olOM2N0KHrqooCEktCxTbP1+sdlc04sx+NVUlOYO+9pRIFJ8/6AXS7r85Aj51CQsz4KNeIAz3rM2FcaWbfa3liZVg8Ljsojmi0uzH7Wt8RMra7zfHHkTvb3CDrRtStIk+jFF76LqTuh0CuK9mRnSjJ/Qk+hvnDwNhQqF9+sz8v5ezyM1lawPK4yAI4KcPD0gOIvshJp0bhasaF/W86sIVEd1NvJ3UAhR7FbzaI0odsCUgdIA5rtGrDVnjojGUMkQy7VZQanzePQE/R2rhWkaIPNEZOoysSEO389pK7miez408of+fOdHPLtPd2fb/BeHydeX0+eL9O//6rydyi2Wmc="
}
    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:
    • 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.

    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
    JSON