Developer Guide

EMandate

BillAgain's eMandate iFrame method allows you to embed an eMandate into your forms and pages so that signees does not need to leave your page to sign an eMandate

URL

POST https://api.billagain.com/v1/emandate

INPUT PARAMETERS (29 Fields)

Parameter Format Description
Name req Alpha Name of signee
Lastname req Alpha Last Name of signee
Company Alpha Name of company, only displayed if isCompanySignee is true
TradingAs Alpha Trading As name of company, only displayed if isCompanySignee is true
Tel Numeric Signee's contact number
Email Alpha Signee's email address
Address1 Alpha Numeric Signee's address line 1
Address2 Alpha Numeric Signee's address line 2
City Alpha Signee's city
State Alpha Signee's Province/State
CountryISOCode Alpha Signee's country three letter ISO code
PostalCode Alpha Signee's postal code
bank_Name req Alpha Bank name
bank_BranchCode req Alpha Branch code
bank_AccHolder req Alpha Account holder
bank_AccNumber req Numeric Account number
bank_AccountType req Alpha Numeric Account type
debit_ActionDay req Numeric Debit order action date
debit_StartDate req Date Debit order start date
debit_EndDate Date Debit order end date
debit_Frequency req Numeric How often the debit order must go off, e.g. Monthly, Daily, Yearly, Weekly etc.
debit_Escalation Numeric Any debit order escalations
debit_Amt req Numeric Debit order amount
debit_MaxAmt Numeric Unique reference to contract
debit_NameOnStmt req Alpha Abbreviated signee name contained on bank statement
debit_ContractRef req Alpha Numeric Unique reference to contract
debit_VariableAmts Numeric Any debit order variable amounts
isCustomerEditable Boolean Specify if customer will be allowed to change basic information on eMandate
isCompanySignee Boolean Specify if customer is signing on behalf of a compnay

OUTPUT PARAMETERS (1 Field)

Parameter Format Description
Token Alpha Numeric Once you have set up your eMandate you will be given a token, this will be used as a unique identifier that should be passed when adding a payment method, the token is valid for 24 hours if unsigned.

STEPS

Follow the following steps:

  1. Add the following HTML to your page <script src="https://api.billagain.com/widget/emandate/iFrame/script"></script> <div id="billagain_emandate_embedded"> </div>
  2. Post the input parameters (Name, Lastname, Bank Details, etc) to https://api.billagain.com/v1/emandate to receive a token

  3. Call the following javascript code to initialize the iFrame 
    
billagain.init({
   containerID: "billagain_emandate_embedded",
   token: {token},//replace with token from step 2
   onComplete: function () {
     //Add Code here
     //Specify what must happen if the eMandate was signed succesfully
   },
   onError: function () {
     //Add Code here
     //Specify what must happen if the eMandate signiture failed 
   }
});
    Replace {token} with the token that comes back from step 2

The following needs to be passed in the init function

  • containerID - previously created div id
  • token - token that you received from eMandate setup function
  • onComplete - specify javascript function that needs to be fired once eMandate process has been completed
  • onError - specify javascript function that needs to be fired id a error occurs on eMandate process
Select the button below for a demonstration on the eMandate function:
Demo

EXAMPLES

JSON Input

{
  "Address1": "9 Bandit Road",
  "Address2": "Summers",
  "bank_AccHolder": "Jona",
  "bank_AccNumber": "654-4587-214",
  "bank_AccountType": "Savings",
  "bank_BranchCode": "654123654",
  "debit_ActionDay": "1",
  "PostalCode": "654123",
  "Name": "Jona",
  "LastName": "Hall",
  "Company": "Jonas Inc",
  "TradingAs": "Jonas",
  "Tel": "1234567894",
  "debit_Amt": "650.00",
  "debit_ContractRef": "jhall0001",
  "Email": "asdasd@asdad.com",
  "State": "Eastern Cape",
  "bank_Name": "ABB Bank",
  "City": "Port Jones",
  "CountryISOCode": "ZAR",
  "debit_EndDate": "",
  "debit_Escalation": "",
  "debit_Frequency": "",
  "debit_MaxAmt": "",
  "debit_NameOnStmt": "",
  "debit_StartDate": "12 Apr 2017",
  "debit_VariableAmts": "Please note that the amounts can vary depending on what the customer agreed on."
}

JSON Output

HTTP CODE: 204 No Content

Should you wish to, you may redirect your Clients to Bill Again’s eMandate sign up page rather than embedding the process within your own system. To do so, please use the URL presented below:

URL

POST https://api.billagain.com/widget/emandate

INPUT PARAMETERS (29 Fields)

Parameter Format Description
Name req Alpha Name of signee
Lastname req Alpha Last Name of signee
Company Alpha Name of company, only displayed if isCompanySignee is true
TradingAs Alpha Trading As name of company, only displayed if isCompanySignee is true
Tel Numeric Signee's contact number
Email Alpha Signee's email address
Address1 Alpha Numeric Signee's address line 1
Address2 Alpha Numeric Signee's address line 2
City Alpha Signee's city
State Alpha Signee's Province/State
CountryISOCode Alpha Signee's country three letter ISO code
PostalCode Alpha Signee's postal code
bank_Name req Alpha Bank name
bank_BranchCode req Alpha Branch code
bank_AccHolder req Alpha Account holder
bank_AccNumber req Numeric Account number
bank_AccountType req Alpha Numeric Account type
debit_ActionDay req Numeric Debit order action date
debit_StartDate req Date Debit order start date
debit_EndDate Date Debit order end date
debit_Frequency req Numeric How often the debit order must go off, e.g. Monthly, Daily, Yearly, Weekly etc.
debit_Escalation Numeric Any debit order escalations
debit_Amt req Numeric Debit order amount
debit_MaxAmt Numeric Unique reference to contract
debit_NameOnStmt req Alpha Abbreviated signee name contained on bank statement
debit_ContractRef req Alpha Numeric Unique reference to contract
debit_VariableAmts Numeric Any debit order variable amounts
isCustomerEditable Boolean Specify if customer will be allowed to change basic information on eMandate
isCompanySignee Boolean Specify if customer is signing on behalf of a compnay

OUTPUT PARAMETERS (1 Field)

Parameter Format Description
Token Alpha Numeric Once you have set up your eMandate you will be given a token, this will be used as a unique identifier in the future.

STEPS

Follow the following steps:

Post to the above API to receive your token
Once you have received your token redirect to the following address http://api.billagain.com/widget/emandate?token={Token}&returnURL={returnURL}

Replacing the { } as follows

  • {Token} - with the token you have receved after setup of eMandate
  • {returnURL} - the url you would like BillAgain to redirect to after eMandate process is completed eg. http://www.yourwebsite.com

EXAMPLES

JSON Input

{
  "Address1": "9 Bandit Road",
  "Address2": "Summers",
  "bank_AccHolder": "Jona",
  "bank_AccNumber": "654-4587-214",
  "bank_AccountType": "Savings",
  "bank_BranchCode": "654123654",
  "debit_ActionDay": "1",
  "PostalCode": "654123",
  "Name": "Jona",
  "LastName": "Hall",
  "Company": "Jonas Inc",
  "TradingAs": "Jonas",
  "Tel": "1234567894",
  "debit_Amt": "650.00",
  "debit_ContractRef": "jhall0001",
  "Email": "asdasd@asdad.com",
  "State": "Eastern Cape",
  "bank_Name": "ABB Bank",
  "City": "Port Jones",
  "CountryISOCode": "ZAR",
  "debit_EndDate": "",
  "debit_Escalation": "",
  "debit_Frequency": "",
  "debit_MaxAmt": "",
  "debit_NameOnStmt": "",
  "debit_StartDate": "12 Apr 2017",
  "debit_VariableAmts": "Please note that the amounts can vary depending on what the customer agreed on."
}

JSON Output

HTTP CODE: 204 No Content

Retrieve data linked to a specific eMandate

URL

Get https://api.billagain.com/v1/emandate

URL PARAMETERS (1 Field)

Parameter Format Description
Token req Alpha Numeric eMandate token

OUTPUT PARAMETERS (36 Fields)

Parameter Format Description
customerPaymentMethodID Alpha Current Linked Customer Payment Method identifier
Token Alpha Current eMandate Token, used for signing and downloading of eMandate
Name Alpha Name of signee
Lastname Alpha Last Name of signee
Company Alpha Name of company, only displayed if isCompanySignee is true
TradingAs Alpha Trading As name of company, only displayed if isCompanySignee is true
Tel Numeric Signee's contact number
Email Alpha Signee's email address
Address1 Alpha Numeric Signee's address line 1
Address2 Alpha Numeric Signee's address line 2
City Alpha Signee's city
State Alpha Signee's Province/State
PostalCode Alpha Signee's postal code
CountryISOCode Alpha Signee's country three letter ISO code
bank_DebitMethod Alpha Current eMandate debit type
bank_Name Alpha Bank name
bank_BranchCode Alpha Branch code
bank_AccHolder Alpha Account holder
bank_AccNumber Numeric Account number
bank_AccountType Alpha Numeric Account type
debit_Frequency Numeric How often the debit order must go off, e.g. Monthly, Daily, Yearly, Weekly etc.
debit_NameOnStmt Alpha Abbreviated signee name contained on bank statement
debit_ContractRef Alpha Numeric Unique reference to contract
debit_StartDate Date Debit order start date
debit_ActionDay Numeric Debit order action date
debit_EndDate Date Debit order end date
debit_Amt Numeric Debit order amount
debit_MaxAmt Numeric Unique reference to contract
debit_Escalation Numeric Any debit order escalations
debit_VariableAmts Numeric Any debit order variable amounts
DateCreated Date eMandate creation date
DateSigned Date eMandate signiture date
BeneficiaryName Alpha Numeric Beneficiary Name
BeneficiaryContactNumber Alpha Numeric Beneficiary Contact Number
BeneficiaryWebPage Alpha Numeric Beneficiary Web Page
BeneficiaryEmail Alpha Numeric Beneficiary Email

EXAMPLES

JSON Output

HTTP CODE: 200 OK
{
  "customerPaymentMethodID": null,
  "Token": "99ebee8f-eec8-4f49-9525-fe728e69c2fe",
  "Name": "N",
  "LastName": "LN",
  "Tel": "123",
  "Email": "reier360@gmail.com",
  "Address1": "9 Bandit Road",
  "Address2": "1",
  "City": "123",
  "State": "State",
  "PostalCode": "123",
  "CountryISOCode": "ZAR",
  "bank_DebitMethod": "debit_order",
  "bank_Name": "123",
  "bank_BranchCode": "654123654",
  "bank_AccHolder": "1",
  "bank_AccNumber": "1",
  "bank_AccountType": "Savings",
  "debit_Frequency": "",
  "debit_NameOnStmt": "",
  "debit_ContractRef": "123",
  "debit_StartDate": "2017-04-12T00:00:00",
  "debit_ActionDay": 1,
  "debit_EndDate": null,
  "debit_Amt": 123,
  "debit_MaxAmt": null,
  "debit_Escalation": "",
  "debit_VariableAmts": "",
  "DateCreated": "2016-04-26T15:39:29.7019974+02:00",
  "DateSigned": null,
  "BeneficiaryName": "Test Company ",
  "BeneficiaryContactNumber": "04133265651",
  "BeneficiaryWebPage": "www.thecodegroup.co.za",
  "BeneficiaryEmail": "tester@thecodegroup.co.za"
}

Download PDF version of current eMandate

URL

https://api.billagain.com/widget/emandate/download

URL PARAMETERS (1 Field)

Parameter Format Description
token req Numeric Unique eMandate token