Bill Again - Recurring Billing System

Getting Started

API (v1)

Client Libraries

.Net

Batches

Get a list of batches account related

URL

GET https://api.billagain.com/v1/batches

URL PARAMETERS

None - optional paging values can be passed through

OUTPUT PARAMETERS (11 Fields)

Parameter	Format	Description
BatchToken	GUID	Unique batch identifier
CurrencyCode	Alpha	3 letter currency code, eg. ZAR, USD
GatewayToken	GUID	Unique gateway identifier
CreatedDate	Date	Date batch was created
SubmitDate	Date	Date batch was submitted if submitted
ActionDate	Date	Date batch should go off
BuildError	Alpha Numeric	Build error if batch not successful
State	Alpha Numeric	Current batch state
NumberOfPayments	Alpha Numeric	Number of lines in batch
PaymentsTotal	Alpha Numeric	Total amount paid
Notes	Alpha Numeric	Any additional notes

EXAMPLES

JSON Output

HTTP CODE: 200 OK
[
  {
    "BatchToken": "b7243c6b-4ff9-4bf2-9e91-e2970329ed1d",
    "CurrencyCode": "ZAR",
    "GatewayToken": "d9308a66-66be-4b2a-87d6-fc0cbd2fde13",
    "CreatedDate": "2016-04-03T17:25:46.2089071+02:00",
    "SubmitDate": null,
    "ActionDate": "2016-04-03T00:00:00+02:00",
    "State": "open",
    "BuildError": null,
    "NumberOfPayments": 1,
    "PaymentsTotal": "200.00",
    "Notes": "My Notes"
  },
  {
    "BatchToken": "d075aec2-5b36-47d3-843d-1792401f3356",
    "CurrencyCode": "ZAR",
    "GatewayToken": "d9308a66-66be-4b2a-87d6-fc0cbd2fde13",
    "CreatedDate": "2016-04-03T17:01:24.2101247+02:00",
    "SubmitDate": "2016-04-03T17:01:36.027985+02:00",
    "ActionDate": "2016-04-11T00:00:00+02:00",
    "State": "build",
    "BuildError": null,
    "NumberOfPayments": 1,
    "PaymentsTotal": "100.00",
    "Notes": "My Notes"
  }
]

Returns a specific batch

URL

GET https://api.billagain.com/v1/batches/{BatchToken}

URL PARAMETERS (1 Field)

Parameter	Format	Description
BatchToken req	Numeric	Unique batch identifier

OUTPUT PARAMETERS (11 Fields)

Parameter

Format

Description

BatchToken

GUID

Unique batch identifier

CurrencyCode

Alpha

3 letter currency code, eg. ZAR, USD

GatewayToken

GUID

Unique gateway identifier

CreatedDate

Date

Date batch was created

SubmitDate

Date

Date batch was submitted if submitted

ActionDate

Date

Date batch should go off

State

Alpha Numeric

Current batch state

BuildError

Alpha Numeric

Build error if batch not successful

NumberOfPayments

Alpha Numeric

Number of lines in batch

Notes

Alpha Numeric

Any additional notes

Payments

Object List

paymentID	Numeric	Unique payment identifier
Amount	Numeric	Payment Amount

EXAMPLES

JSON Output

HTTP CODE: 200 OK
{
  "BatchToken": "b7243c6b-4ff9-4bf2-9e91-e2970329ed1d",
  "CurrencyCode": "ZAR",
  "GatewayToken": "d9308a66-66be-4b2a-87d6-fc0cbd2fde13",
  "CreatedDate": "2016-04-03T17:25:46.2089071+02:00",
  "SubmitDate": null,
  "ActionDate": "2016-04-03T00:00:00+02:00",
  "State": "open",
  "BuildError": null,
  "NumberOfPayments": 1,
  "PaymentsTotal": "200.00",
  "Notes": "My Notes"
}

Creates a batch

URL

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

INPUT PARAMETERS (4 Fields)

Parameter	Format	Description
CurrencyCode req	Alpha	3 letter currency code, eg. ZAR, USD
GatewayToken req	Alpha	Unique gateway identifier
ActionDate req	date	Date batch should go off
Notes	Alpha Numeric	Any additional notes

OUTPUT PARAMETERS (10 Fields)

Parameter	Format	Description
BatchToken	GUID	Unique batch identifier
CurrencyCode	Alpha	3 letter currency code, eg. ZAR, USD
GatewayToken	GUID	Unique gateway identifier
CreatedDate	Date	Date batch was created
SubmitDate	Date	Date batch was submitted if submitted
ActionDate	Date	Date batch should go off
State	Alpha Numeric	Current batch state
BuildError	Alpha Numeric	Build error if batch not successful
NumberOfPayments	Alpha Numeric	Number of lines in batch
Notes	Alpha Numeric	Any additional notes

EXAMPLES

JSON Input

  {
    "CurrencyCode": "ZAR",
    "GatewayToken": "d9308a66-66be-4b2a-87d6-fc0cbd2fde13",
    "ActionDate": "23 April 2016",
    "Notes": "My notes"
  }

JSON Output

HTTP CODE: 201 Created
{
  "BatchToken": "fecbd21e-2967-4128-8d8c-171c43faa35c",
  "CurrencyCode": "ZAR",
  "GatewayToken": "d9308a66-66be-4b2a-87d6-fc0cbd2fde13",
  "CreatedDate": "2016-04-08T11:37:01.4113161+02:00",
  "SubmitDate": null,
  "ActionDate": "2016-04-23T00:00:00+02:00",
  "State": "open",
  "BuildError": null,
  "NumberOfPayments": 0,
  "Notes": "My notes"
}

Edit a specific batch

URL

PUT https://api.billagain.com/v1/batches

INPUT PARAMETERS (5 Fields)

Parameter	Format	Description
BatchToken req	GUID	Unique batch identifier
CurrencyCode req	Alpha	3 letter currency code, eg. ZAR, USD
GatewayToken req	Alpha	Unique gateway identifier
ActionDate req	date	Date batch should go off
Notes	Alpha Numeric	Any additional notes

EXAMPLES

JSON Input

 {
  "BatchToken" : "fecbd21e-2967-4128-8d8c-171c43faa35c",   
  "CurrencyCode": "ZAR",
  "GatewayToken": "d9308a66-66be-4b2a-87d6-fc0cbd2fde13",
  "CreatedDate": "2016-04-08T11:37:01.4113161+02:00",
  "ActionDate": "2016-04-23T00:00:00+02:00",
  "Notes": "My Notes Edited"
 }

JSON Output

HTTP CODE: 204 No Content

Submits a specific batch

URL

PUT https://api.billagain.com/v1/batches/submit

INPUT PARAMETERS (3 Fields)

Parameter	Format	Description
BatchToken req	GUID	Unique batch identifier
ActionDate req	date	Date batch should go off
Notes	Alpha Numeric	Any additional notes

EXAMPLES

JSON Input

 {
  "BatchToken" : "283533e9-df13-4590-88bf-c98a60dfc008",
  "ActionDate": "2017-04-23T00:00:00+02:00",
  "Notes": "My Notes Edited"
 }

JSON Output

HTTP CODE: 204 No Content

Cancels a batch

URL

PUT https://api.billagain.com/v1/batches/cancel

INPUT PARAMETERS (1 Field)

Parameter	Format	Description
BatchToken req	GUID	Unique batch identifier

EXAMPLES

JSON Output

HTTP CODE: 204 No Content

Adds a payment line to batch

URL

POST https://api.billagain.com/v1/batches/payments

INPUT PARAMETERS (8 Fields)

Parameter

Format

Description

BatchToken req

GUID

Unique batch identifier

customerID req

Numeric

Unique customer identifier

Amount req

Numeric

Payment amount

Ref

Alpha Numeric

Reference of payment

Memo

Alpha Numeric

Payment Memo

paymentMethodID req

Numeric

Billagain payment method identifier

isAutoApply

Boolean

AutoApply conditions:

True - the payment will be made to the earliest invoice and {PaymentApplied} is not required and will not be used
False - (false by default) then {PaymentApplied} is required

PaymentApplied req

Object List

Alternative field options:

invoiceID - is required if {invoiceNumber} is empty, note invoiceID will always take first priority
invoiceNumber - is required if {invoiceID} is empty

amount req	Numeric	Portion of the Payment used to pay invoice
invoiceID req	Numeric	Unique Invoice identifier
invoiceNumber	Numeric	Unique Invoice identifier

OUTPUT PARAMETERS (10 Fields)

Parameter

Format

Description

paymentID

Numeric

Unique payment identifier

customerID

Numeric

Unique customer identifier

Amount

Numeric

The Amount paid by customer

CurrencyCode

Alpha

3 letter currency code, eg. ZAR, USD

Date

The date of payment

Memo

Alpha Numeric

Payment Memo

Method

Alpha

Customers payment method (Options: cash, cheque, credit_card, bank_account, eft)

Ref

Alpha Numeric

Reference of payment

Status

Alpha

The payment status (Options : Pending, Allocated, Partial, Unallocated, Failed )

PaymentApplied req

Object List

Alternative field options:

invoiceID - is required if {invoiceNumber} is empty, note invoiceID will always take first priority
invoiceNumber - is required if {invoiceID} is empty

allocationID	Numeric	Unique Allocation identifier
amount	Numeric	Portion of the Payment used to pay invoice
invoiceID	Numeric	Unique Invoice identifier

EXAMPLES

JSON Input

{
  "BatchToken" : "fecbd21e-2967-4128-8d8c-171c43faa35c",
  "customerID": 269,
  "Amount": 200,
  "Ref": "My invoice payments 11351, 11352",
  "isAutoApply" : false,
  "Memo": "My Memo",
  "paymentMethodID": 10106,
  "PaymentApplied": [
    {
      "invoiceID": 11351,
      "amount": 100
    },
    {
      "invoiceID": 11352,
      "amount": 100
    }
  ]
}

JSON Output

HTTP CODE: 201 Created
{
  "paymentID": 10806,
  "customerID": 269,
  "Status": "Allocated",
  "Date": "2016-04-08T10:18:30.483551Z",
  "CurrencyCode": "ZAR",
  "Amount": 200,
  "Method": "debit_order",
  "Ref": "My invoice payments 11351, 11352",
  "Memo": "My Memo",
  "PaymentApplied": [
    {
      "allocationID": 10385,
      "invoiceID": 11351,
      "paymentID": 10817,
      "amount": 100
    },
    {
      "allocationID": 10386,
      "invoiceID": 11352,
      "paymentID": 10817,
      "amount": 100
    }
  ]
}

Edits a payment line

URL

PUT https://api.billagain.com/v1/batches/payments

INPUT PARAMETERS (10 Fields)

Parameter

Format

Description

paymentID req

Numeric

Unique payment identifier

BatchToken req

GUID

Unique batch identifier

customerID req

Numeric

Unique customer identifier

Amount req

Numeric

The Amount paid by customer

CurrencyCode req

Alpha

3 letter currency code, eg. ZAR, USD

Date req

Date

The date of payment

Memo

Alpha Numeric

Payment Memo

Method req

Alpha

Customers payment method (Options: cash, cheque, credit_card, bank_account, eft)

Ref

Alpha Numeric

Reference of payment

PaymentApplied req

Object List

List of payment allocations - options:

Add - by posting a nested Payment Allocations object and excluding the {allocationID}
Edit - by posting a nested Payment Allocations object and including existing {allocationID} connected to the this {paymentID}
Delete - by not including the existing Payment Allocations object from the payment list

amount req	Numeric	Portion of the Payment used to pay invoice
invoiceID req	Numeric	Unique Invoice identifier
invoiceNumber	Numeric	Unique Invoice identifier

EXAMPLES

JSON Input

{
  "paymentID": 10814,
  "BatchToken": "fecbd21e-2967-4128-8d8c-171c43faa35c",
  "customerID": 269,
  "Amount": 500,
  "Ref": "My invoice payments",
  "Memo": "My Memo 2",
  "paymentMethodID": 10106,
  "PaymentApplied": [
    {
      "invoiceID": 11351,
      "amount": 200
    },
    {
      "invoiceID": 11352,
      "amount": 200
    },
    {
      "invoiceNumber": 957,
      "amount": 100
    }
  ]
}

JSON Output

HTTP CODE: 204 No Content

Deletes a payment line

URL

DELETE https://api.billagain.com/v1/batches/payments/{paymentid}

URL PARAMETERS (1 Field)

Parameter	Format	Description
paymentID req	Numeric	Unique payment identifier

EXAMPLES

JSON Output

HTTP CODE: 204 No Content

Developer Guide

Batches

URL

URL PARAMETERS

OUTPUT PARAMETERS (11 Fields)

EXAMPLES

JSON Output

URL

URL PARAMETERS (1 Field)

OUTPUT PARAMETERS (11 Fields)

EXAMPLES

JSON Output

URL

INPUT PARAMETERS (4 Fields)

OUTPUT PARAMETERS (10 Fields)

EXAMPLES

JSON Input

JSON Output

URL

INPUT PARAMETERS (5 Fields)

EXAMPLES

JSON Input

JSON Output

URL

INPUT PARAMETERS (3 Fields)

EXAMPLES

JSON Input

JSON Output

URL

INPUT PARAMETERS (1 Field)

EXAMPLES

JSON Output

URL

INPUT PARAMETERS (8 Fields)

OUTPUT PARAMETERS (10 Fields)

EXAMPLES

JSON Input

JSON Output

URL

INPUT PARAMETERS (10 Fields)

EXAMPLES

JSON Input

JSON Output

URL

URL PARAMETERS (1 Field)

EXAMPLES

JSON Output