Developer Guide

Payments

Get a list of payments customer related

URL

GET https://api.billagain.com/v1/customers/{customerID}/payments

URL PARAMETERS (3 Fields)

Parameter Format Description
customerID req Numeric Unique customer identifier
page Numeric Current page number
page_size Numeric Amount of items on requested page

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 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 )
allocations Object List
allocationID Numeric Unique Allocation identifier
amountApplied Numeric Portion of the Payment used to pay invoice
invoiceID Numeric Unique Invoice identifier
positiveAdjustmentID Numeric Unique positive adjustment identifier

EXAMPLES

JSON Output

HTTP CODE: 200 OK
[
  {
    "paymentID": 10774,
    "customerID": 269,
    "Status": "Pending",
    "Date": "2016-04-03T15:26:05.7987439Z",
    "CurrencyCode": "ZAR",
    "Amount": 1000,
    "Method": "debit_order",
    "Ref": "Invoices 702, Opening Balance 703",
    "Memo": "",
    "Allocations": [
      {
        "allocationID": 10303,
        "invoiceID": 702,
        "positiveAdjustmentID": 0,
        "amountApplied": 500
      },
      {
        "allocationID": 10304,
        "invoiceID": 0,
        "positiveAdjustmentID": 703,
        "amountApplied": 500
      }
    ]
  },
  {
    "paymentID": 10773,
    "customerID": 269,
    "Status": "Allocated",
    "Date": "2016-04-03T15:01:24.4844861Z",
    "CurrencyCode": "ZAR",
    "Amount": 200,
    "Method": "debit_order",
    "Ref": "Invoices 704",
    "Memo": "Advanced payment of R200",
    "Allocations": [
      {
        "allocationID": 10302,
        "invoiceID": 704,
        "positiveAdjustmentID": 0,
        "amountApplied": 200
      }
    ]
  }
]

Get a list of payments account related

URL

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

INPUT PARAMETERS (2 Fields)

Parameter Format Description
page Numeric Current page number
page_size Numeric Amount of items on requested page

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 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 )
allocations Object List
allocationID Numeric Unique Allocation identifier
amountApplied Numeric Portion of the Payment used to pay invoice
invoiceID Numeric Unique Invoice identifier
positiveAdjustmentID Numeric Unique positive adjustment identifier

EXAMPLES

JSON Output

HTTP CODE: 200 OK
[
  {
    "paymentID": 10720,
    "customerID": 226,
    "Status": "Pending",
    "Date": "2016-01-15T12:38:15.9648657Z",
    "CurrencyCode": "ZAR",
    "Amount": 2000,
    "Method": "debit_order",
    "Ref": "Invoices 11343",
    "Memo": "",
    "Allocations": [
      {
        "allocationID": 10260,
        "invoiceID": 11343,
        "positiveAdjustmentID": 0,
        "amountApplied": 1000
      }
    ]
  },
  {
    "paymentID": 10735,
    "customerID": 231,
    "Status": "Allocated",
    "Date": "2016-02-26T07:18:10.2376481Z",
    "CurrencyCode": "ZAR",
    "Amount": 4000,
    "Method": "credit_card",
    "Ref": "Invoices 11348, Opening Balance 11349",
    "Memo": "",
    "Allocations": [
      {
        "allocationID": 10263,
        "invoiceID": 11348,
        "positiveAdjustmentID": 0,
        "amountApplied": 3000
      },
      {
        "allocationID": 10264,
        "invoiceID": 0,
        "positiveAdjustmentID": 11349,
        "amountApplied": 1000
      }
    ]
  }
]

Get specific payment

URL

GET https://api.billagain.com/v1/payments/{paymentID}

URL PARAMETERS (1 Field)

Parameter Format Description
paymentID req Numeric Unique payment 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 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 )
allocations Object List
allocationID Numeric Unique Allocation identifier
amountApplied Numeric Portion of the Payment used to pay invoice
invoiceID Numeric Unique Invoice identifier
positiveAdjustmentID Numeric Unique positive adjustment identifier

EXAMPLES

JSON Output

HTTP CODE: 200 OK
{
  "paymentID": 10735,
  "customerID": 231,
  "Status": "Allocated",
  "Date": "2016-02-26T07:18:10.2376481Z",
  "CurrencyCode": "ZAR",
  "Amount": 4000,
  "Method": "credit_card",
  "Ref": "Invoices 11348, Opening Balance 11349",
  "Memo": "",
  "Allocations": [
    {
      "allocationID": 10263,
      "invoiceID": 11348,
      "positiveAdjustmentID": 0,
      "amountApplied": 3000
    },
    {
      "allocationID": 10264,
      "invoiceID": 0,
      "positiveAdjustmentID": 11352,
      "amountApplied": 1000
    }
  ]
}

Add specific payment

URL

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

INPUT PARAMETERS (9 Fields)

Parameter Format Description
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
AutoApply Boolean AutoApply conditions:
  • True - the payment will be made to the earliest invoice and payment allocations is not required and will not be used
  • False - (false by default) then payment allocations is required
allocations Object List List of payment allocations - options:
  • Add - by posting a nested Payment Allocations object and excluding the {allocationID}
Alternative field options:
  • invoiceID - is required if {invoiceNumber} or {positiveAdjustmentID} is empty, note {invoiceID} will always take first priority
  • invoiceNumber - is required if {invoiceID} or {positiveAdjustmentID} is empty
  • positiveAdjustmentID - is required if both {invoiceNumber} and {invoiceID} are empty. May only apply payment to an invoice or positive adjustment, not both.
allocationID Numeric Unique Allocation identifier
amountApplied Numeric Portion of the Payment used to pay invoice
invoiceID Numeric Unique Invoice identifier
positiveAdjustmentID Numeric Unique positive adjustment 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 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 )
allocations Object List
allocationID Numeric Unique Allocation identifier
amountApplied Numeric Portion of the Payment used to pay invoice
invoiceID Numeric Unique Invoice identifier
positiveAdjustmentID Numeric Unique positive adjustment identifier

EXAMPLES

JSON Input

{
  "customerID": 269,
  "Date": "05 Apr 2016",
  "CurrencyCode": "ZAR",
  "Amount": 200,
  "Method": "credit_card",
  "Ref": "My invoice payments 11351, 11352",
  "Memo": "",
  "Allocations": [
    {
      "invoiceID": 11351,    
      "amountApplied": 100
    },
    {
      "positiveAdjustmentID": 11352,
      "amountApplied": 100
    }
  ]
}

JSON Output

HTTP CODE: 201 Created
{
  "paymentID": 10800,
  "customerID": 269,
  "Status": "Allocated",
  "Date": "2016-04-04T22:00:00Z",
  "CurrencyCode": "ZAR",
  "Amount": 200,
  "Method": "credit_card",
  "Ref": "My invoice payments 11351, Opening Balance 11352",
  "Memo": "",
  "Allocations": [
    {
      "allocationID": 10321,
      "invoiceID": 11351,
      "positiveAdjustmentID": 0,
      "paymentID": 10800,
      "amountApplied": 100
    },
    {
      "allocationID": 10322,
      "invoiceID": 0,
      "positiveAdjustmentID": 11352,
      "paymentID": 10800,
      "amountApplied": 100
    }
  ]
}

Edit specific payment

URL

PUT https://api.billagain.com/v1/payments/{paymentID}

URL PARAMETERS (1 Field)

Parameter Format Description
paymentID req Numeric Unique payment identifier

INPUT PARAMETERS (8 Fields)

Parameter Format Description
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
Allocations 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
Alternative field options:
  • invoiceID - is required if {invoiceNumber} is empty, note {invoiceID} will always take first priority
  • invoiceNumber - is required if {invoiceID} is empty
  • positiveAdjustmentID - is required if both {invoiceNumber} and {invoiceID} are empty. May only apply payment to an invoice or positive adjustment, not both.
allocationID Numeric Unique Allocation identifier
amountApplied Numeric Portion of the Payment used to pay invoice
invoiceID Numeric Unique Invoice identifier
positiveAdjustmentID Numeric Unique positive adjustment identifier
invoiceNumber Numeric Unique Invoice identifier

EXAMPLES

JSON Input

{
  "customerID": 269,
  "Date": "06 Apr 2016",
  "CurrencyCode": "ZAR",
  "Amount": 750.00,
  "Method": "debit_order",
  "Ref": "Invoices and Opening Balance payments",
  "Memo": "",
  "Allocations": [
    {
      "allocationID": 10323,
      "invoiceID": 11351,
      "amountApplied": 250
    },
    {
      "allocationID": 10325,
      "positiveAdjustmentID": 11352,
      "amountApplied": 350
    },
    {
      "invoiceID": 11358,
      "amountApplied": 100
    }
  ]
}

JSON Output

HTTP CODE: 204 No Content

Delete specific payment

URL

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

INPUT PARAMETERS (1 Field)

Parameter Format Description
paymentID req Numeric Unique payment identifier

EXAMPLES

JSON Output

HTTP CODE: 204 No Content