Developer Guide

Payments

Initiates API payment processing request

URL

POST https://api.billagain.com/v1/secure/initiate

INPUT PARAMETERS (16 Fields)

Parameter Format Description
customerID req Numeric Unique customer identifier
Mode req Alpha The processing mode, (Options: redirect)
Method req Alpha The processing method, (Options: credit_card, bank_account, hpp)
isPayment req Boolean An indicator to indicate that the transaction is a payment transaction
StorageMode req Alpha Storage Modes:
  • cc - The credit card information will be stored
  • cc_token - The credit card information will be stored and a token will be stored for gateway processing (this is the most flexible option)
  • token - A token will be stored for gateway processing, the credit card information will not be stored
  • no_cc - Credit card information will not be stored, use this if only bank account processing allowed
paymentMethod_retainOnSuccess req Boolean An indicator to indicate that the payment method must be kept after successful processing, has to be true if using existing payment method, paymentMethod_isPrimary is true or paymentMethod_isEnrol is true
paymentMethod_isPrimary req Boolean An indicator to indicate that the payment method must be set as primary payment method, can only be true if paymentMethod_retainOnSuccess is true
paymentMethod_isEnrol req Boolean An indicator to indicate that the payment method must be enrolled either via ThreeD Secure for credit cards or eMandate signing for bank accounts, can only be true if paymentMethod_retainOnSuccess is true
subscriptionID Numeric Unique subscription identifier, only applicable for bank account if eMandate needs to be signed as well, used to populate eMandate details
gatewayID Numeric Unique gateway identifier, only applicable if payment needs to be made or if credit card needs to be tokenised and/or enrolled
paymentMethodID Numeric Unique payment method identifier, if passed through the corresponding payment method will be used to perform transaction, only applicable for enrollment or payments, if passed through paymentMethod_retainOnSuccess must be true
CurrencyCode req Alpha 3 letter currency code, eg. ZAR, USD
Amount Numeric Monetary value of transaction if payment transaction, has to be equal to zero if isPayment is false
Description Alpha Numeric Description of goods
RedirectUrl URL The page to redirect customer to after processing has completed
NotifyUrl URL The notification web service where the ultimate result will be sent to

OUTPUT PARAMETERS (3 Fields)

Parameter Format Description
isSuccess Boolean Unique payment identifier
ErrorMessage Alpha Numeric Description of any error that has occurred, will only be returned if applicable
RedirectUrl Alpha Numeric URL to redirect customer to, will only be returned if applicable

STEPS

Follow the following steps:

  1. Post input params to API endpoint to get output params

  2. Redirect to RedirectUrl that has been passed back in output params, not the one that has been passed in in input params

  3. Customer will then be redirected to us to perform transaction

  4. After transaction is completed the customer will be redirected back to the RedirectUrl specified in the input params, outcome and transaction identifier will be passed back in query string when redirecting, this will allow you to use the transactionID to get the transaction in order to verify completion or outcome, please check the Get Transaction method in this section

  5. The NotifyUrl passed in input params will be notified of completion or outcome, verification should be done using Get Transaction method to combat against false or outdated information

EXAMPLES

JSON Input

{
            "customerID":200,
            "Mode":"redirect",
            "Method":"credit_card",
            "isPayment":false,
            "StorageMode":"cc_token",
            "gatewayID":99,
            
            "paymentMethod_isEnrol":true,
            "paymentMethod_retainOnSuccess":true,
            "CurrencyCode":"ZAR",
            "Amount":0,
            "Description":"Payment",
            "RedirectUrl":"https://customerarea.mysite.com",
            "NotifyUrl":"https://notificationservice.mysite.com"
}

JSON Output

HTTP CODE: 201 Created
{
  "isSuccess": true,
  "RedirectUrl": "https://notify.billagain.com/secure/process/5/200/qQPHbizijkuMvTigLR"
}

Gets transaction for verification

URL

GET https://api.billagain.com/v1/secure/transactions/{transactionID}

URL PARAMETERS (1 Field)

Parameter Format Description
transactionID req Alpha Numeric Unique transaction identifier, that was given back in URL or notification

OUTPUT PARAMETERS (29 Fields)

Parameter Format Description
transactionID Alpha Numeric Unique transaction identifier
customerID Numeric Unique customer identifier
Token Alpha Numeric Unique transaction token
Mode Alpha The processing mode, (Options: redirect)
Method Alpha The processing method, (Options: credit_card, bank_account, hpp)
isPayment Boolean An indicator to indicate that the transaction is a payment transaction
StorageMode Alpha Method of storing credit card data, (Options: cc, cc_token, no_cc, token), not relevant for bank accounts but should be passsed through anyway
paymentMethod_retainOnSuccess Boolean An indicator to indicate that the payment method must be kept after successful processing, has to be true if using existing payment method, paymentMethod_isPrimary is true or paymentMethod_isEnrol is true
paymentMethod_isPrimary Boolean An indicator to indicate that the payment method must be set as primary payment method, can only be true if paymentMethod_retainOnSuccess is true
paymentMethod_isEnrol Boolean An indicator to indicate that the payment method must be enrolled either via ThreeD Secure for credit cards or eMandate signing for bank accounts, can only be true if paymentMethod_retainOnSuccess is true
subscriptionID Numeric Unique subscription identifier, only applicable for bank account if eMandate needs to be signed as well, used to populate eMandate details
gatewayID Numeric Unique gateway identifier, only applicable if payment needs to be made or if credit card needs to be tokenised and/or enrolled
paymentMethodID Numeric Unique payment method identifier, if passed through the corresponding payment method will be used to perform transaction, only applicable for enrollment or payments, if passed through paymentMethod_retainOnSuccess must be true
paymentID Numeric The unique identifier for BillAgain payment that was created
CurrencyCode Alpha 3 letter currency code, eg. ZAR, USD
Amount Numeric Monetary value of transaction if payment transaction, has to be equal to zero if isPayment is false
Description Alpha Numeric Description of goods
isCancelled Boolean An indicator to indicate that the transaction has been cancelled by customer
isSubmitted Boolean An indicator to indicate that the transaction has been submitted for processing
isComplete Boolean An indicator to indicate that the transaction has completed
threwError Boolean An indicator to indicate that the transaction was subject to an error and has not been successfully processed
Description Alpha Numeric Text result
RedirectUrl URL The page to redirect customer to after processing has completed
NotifyUrl URL The notification web service where the ultimate result will be sent to
notify_Date Datetime Date notification was sent
notify_NumTries Number Number of times notification was attempted
notify_LastTryDate Datetime The date the last notification was sent
notify_FailedMessage Alpha Numeric The reason why notification was not delivered successfully
DateCreated Datetime The date the transaction was initiated