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

    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 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
    subscription Subscription (optional) The subscription object
    affiliateMerchantId integer (optional) The affiliated merchant id that this payment should be done for (Retrieved from Get Affilicate Merchants)

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

    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

    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,
        "message": "Approved",
        "originalErrorCode": "fin000",
        "code":1
    }
    

    Error Response

    {
        "success": false,
        "message": "Insufficient funds",
        "originalErrorCode": "fin051",
        "code":-1
    }
    
    Property Type Description
    success boolean true on success

    Execute Payment

    Partial Payment Request

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

    Reversal Request. (Amount = 0)

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

    Response

    {
        "success": true
    }
    

    Error Response

    {
        "success": false,
        "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

    Refund Payment

    Partial Refund Request

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

    Response

    {
        "success": true
    }
    

    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

    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 transfered 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 direclty 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.

    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"
          }
       },
       "reference":"MERCHANTREFERENCE01",
       "threeDSecure":true,
       "authorize":true,
       "allowMultiCurrencyPurchase":false,
       "transactionDate": "2021-09-20",
       "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"
          }
       },
       "reference":"MERCHANTREFERENCE01",
       "threeDSecure":true,
       "allowMultiCurrencyPurchase":false,
       "transactionDate": "2021-09-20",
       "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"
       },
       "reference":"MERCHANTREFERENCE01",
       "threeDSecure":false
    }
    
    Property Type Description
    transaction Transaction The transaction object
    threeDSecure boolean Forces 3D Secure to always be requested on the payment page
    reference string The merchant reference
    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)
    transactionDate string (optional) The travel/booking date or the date that the goods is purchased (format - 'yyyy-MM-dd') (default today)
    pax string (optional) The number of people travelling (if travel booking) or the number of items / packages (default 1)

    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
    }
    

    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

    Refund Payment - Other

    Partial Refund Request.

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

    Response

    {
        "success": true
    }
    

    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

    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"
    }
    
    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": 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"
    }
    
    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"
    }
    
    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 Affilicate 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 funds between affilicated merchant. Affiliated merchants are set up by a PayGenius system administrator on request.

    Create Transfer

    POST /pg/api/v2/transfer/create

    summary

    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 Affilicate 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 one",
          "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.

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

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

    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 Affilicate 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

    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