NAV Navbar
JSON
  • Obtaining Your Access Details
  • Making Requests
  • Card Payments Methods
  • Card Vault Methods
  • Instant EFT Methods
  • Transaction Methods
  • Payment Page Methods
  • Object 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 Methods

    The card payment methods provide a facility to perform credit card transactions on a user's card.

    Create Payment

    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":2018,
          "expiryMonth":10,
          "type": "visa",
          "cvv":"698"
       },
       "transaction":{  
          "reference":"Invoice #1871",
          "currency":"ZAR",
          "amount":100
       },
       "threeDSecure":false
    }
    

    Request using a card token

    {  
       "creditCard":{  
        "token": "8a86c511-14e2-4981-b13a-041d53ff4f62"
       },
       "transaction":{  
          "reference":"Invoice #1871",
          "currency":"ZAR",
          "amount":100
       },
       "threeDSecure":false
    }
    

    Request using a transaction reference

    {
       "creditCard":{  
        "transactionReference": "8a86c511-14e2-4981-b13a-041d53ff4f62"
       },
       "transaction":{  
          "reference":"Invoice #1871",
          "currency":"ZAR",
          "amount":100
       },
       "threeDSecure":false
    }
    

    Request using a payment reference

    {
       "creditCard":{  
        "paymentReference": "8a86c511-14e2-4981-b13a-041d53ff4f62"
       },
       "transaction":{  
          "reference":"Invoice #1871",
          "currency":"ZAR",
          "amount":100
       },
       "threeDSecure":false
    }
    
    Property Type Description
    creditCard Credit Card The card object
    transaction Transaction The transaction object
    threeDSecure boolean Forces 3D Secure to always be enabled

    Response Data

    Non-3DS Response

    {
        "success": true,
        "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=="
        },
        "reference": "38424fc9-d7de-4215-9e9d-93e40bd94160",
        "code": 2,
        "message": "3D Secure authentication required"
    }
    
    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

    Confirm 3D Secure 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
    }
    
    Property Type Description
    success boolean true on success

    Execute Payment

    Partial Payment Request

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

    Response

    {
        "success": true
    }
    

    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.

    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.

    Request Data

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

    Response Data

    Property Type Description
    success boolean true on success

    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": 2018,
            "expiryMonth": 10,
            "cvv": 503,
            "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"
    }
    
    Property Type Description
    cardNumber string The user's card number
    token string The stored card's token

    Response Data

    Response

    {
        "success": true,
        "card": {
            "number": "455027XXXXXX3018",
            "cardHolder": "TT",
            "expiryYear": 2018,
            "expiryMonth": 10,
            "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/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"
    }
    
    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

    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 Payment

    POST /pg/api/v2/redirect/create

    summary

    Request Data

    Request

    {  
      "transaction":{
        "reference":"Invoice #1871",
        "currency":"ZAR",
        "amount":100
      },
      "consumer": {
        "name": "Bilbo",
        "surname": "Baggins",
        "email": "bilbo@shire.com",
        "address": {
           "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"
      },
      "auth": false,
      "pageUrlKey": "demo_page"
    }
    
    Property Type Description
    transaction Transaction The transaction details
    consumer Consumer The consumer details
    consumer.address 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. Contact accounts@paygenius.co.za to get your page url key or access it from the backend.

    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"
    }
    
    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":2018,
      "expiryMonth":10,
      "type": "visa",
      "cvv":"503"
    }
    

    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 Two digit number representing the card’s expiration month
    expiryMonth integer Four digit number representing the card’s expiration year
    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 The credit card number
    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

    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"
    }
    
    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

    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
    surname string City
    postCode string Postal Code
    country string Consumer's country of resindence

    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