Articles in this section

Customers & BPAY Reference

  • Updated

Our Customer API lets you create, update, manage your customers. You can retrieve individual customers as well as a list of all your customers.

Endpoints

GET     '/customers'
 GET     '/customers/{code}'
 POST    '/customers'
 PUT     '/customers/{code}'
Group 1 (2).png

This documentation is deprecated

Please refer to the updated documentation https://docs.payadvantage.com.au/reference/customers_get 

Returns a customer record using the Code attribute as an identifier.

Example Request

curl -L -X GET 'https://api.payadvantage.com.au/v3/customers/{code}' \
 -H 'Authorization: Bearer {access_token}' \

Example Responses

STATUS 200 // Successful
    
{
	"Code": "ABCDEF",
	"ExternalID": "ABC001",
	"IsConsumer": true,
	"DateJoined": "2013-09-13T14:10:31.247",
	"Name": "Some Person",
	"FirstName": "Some",
	"LastName": "Person",
	"CustomRef": "ACC52632",
	"Email": "someperson@email.com",
	"BillerCode": null,
	"BPAYRef": null,
	"DateUpdated": "2013-09-13T14:10:31.247",
	"DateCreated": "2013-09-13T14:10:31.247",
	"CreatedBy": {
		"FirstName": "Your",
		"LastName": "User",
		"UserName": "youruser@email.com"
	},
	"IsActive": true
}

STATUS 4## // Error
    
{
	"errorCode": "error_code",
	"messages": [
		"Error message."
	]
}

Query Parameters

Parameter used in the GET function URL.

code string min = 6, max = 6
Unique internal identifier assigned to the customer by Pay Advantage. This cannot be changed. Returns a single customer record.
Group 1 (2).png

This documentation is deprecated

Please refer to the updated documentation https://docs.payadvantage.com.au/reference/customers_search 

Returns a list of customers sorted by name (ascending by default). The list is paged and will always return the first page of records.

Example Request

curl -L -X GET 'https://api.payadvantage.com.au/v3/customers' \
 -H 'Authorization: Bearer {access_token}' \

Example Responses

STATUS 200 // Successful
    
{
	"Records": [
		{
			"Code": "ABCDEF",
			"ExternalID": "ABC001",
			"IsConsumer": true,
			"DateJoined": "2013-09-13T14:10:31.247",
			"Name": "Some Person",
			"FirstName": "Some",
			"LastName": "Person",
			"CustomRef": "ACC52632",
			"Email": "someperson@email.com",
			"BillerCode": null,
			"BPAYRef": null,
			"DateUpdated": "2013-09-13T14:10:31.247",
			"DateCreated": "2013-09-13T14:10:31.247",
			"CreatedBy": {
				"FirstName": "Your",
				"LastName": "User",
				"UserName": "youruser@email.com"
			},
			"IsActive": true
		},
		{
			...
		}
	],
  "Meta":
		{
			"page": 1,
			"recs_per_page": 15,
			"total_recs": 75
		}
}

Query Parameters

Parameters used in the request URL to return filtered or sorted data in the response body. These parameters follow the same rules as any standard HTML query string parameter. The first parameter is separated by ‘?’ and subsequent parameters are separated by ‘&’.

page integer
The page number you want to view using the zero-based index i.e. page=0 will return page 1 of customers. If the page index is greater than the last page, you will be returned an empty page. Negative indexes will return an error.
per_page integer min = 0, max = 1000
Number of records to view per page. By default the value is 100. Values greater than the max value, or negative values will return an error.
sort string array
Lets you sort customer records by a defined set of fields. You can sort by one field e.g. sort={field1} or by many e.g. sort={field1},{field2}

A minus symbol (-) in front of the field indicates the descending order for that field only e.g. sort={field1},-{field2} will sort field1 by ascending but field2 by descending.
Valid Field Strings:
  • datecreated
  • dateupdated
  • name
  • firstname
  • lastname
  • customer
  • dob
code string min = 6, max = 6
Unique internal identifier assigned to the customer by Pay Advantage. This cannot be changed. Returns a single customer record.
externalid string min = 2, max = 12
Optional identifier from an external system that can be recorded as an attribute against this customer. Returns any customer with this id.
datecreated date string
Returns customer records based on date and time customer was created. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datecreated={ddMMyyyy}
datecreatedto date string
Returns customers who were created before or on the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datecreatedto={ddMMyyyy}
datecreatedfrom date string
Returns customers who were created after or on the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datecreatedfrom={ddMMyyyy}
dateupdated date string allows null
Returns customers who were updated on the specified date. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared. Using null as a value will return all customers who have never been updated e.g. dateupdated={ddMMyyyy}
dateupdatedto date string allows null
Returns customers who were updated before or on the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. dateupdatedto={ddMMyyyy}
dateupdatedfrom date string allows null
Returns customers who were updated after or on the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. dateupdated={ddMMyyyy}
name string min = 2, max = 200
Returns customers based on their name. If the customer is not a business, this field will return the firstname and lastname of a customer e.g. name={string}
firstname string min = 1, max = 50
Returns based on first name of a customer, or the first name of a businesses primary contact e.g. firstname={string}
lastname string min = 1, max = 50
Returns based on last name of a customer, or the last name of a businesses primary contact e.g. lastname={string}
customref string min = 2, max = 20
Returns based on a custom reference number against a customer e.g.customref={string}
email string min = 2, max = 200
Returns based on customers primary email address. This address is used for sending payment receipts, alerts, and is required for a customer to authorise a direct debit e.g. email={string}
isconsumer boolean
Returns list based on type i.e. consumers or businesses. True indicates that this customer is a person. False indicates this customer is a business e.g. isconsumer=false returns businesses only.
dob date string
Returns based on date of birth queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. dob={ddMMyyyy}
isactive boolean
Indicates wether the customer is active or not. A customer must have no active direct debits, or pending payment requests to be set to inactive. Returns a list of active or inactive customers e.g. isactive=true will return only active customers.
Group 1 (2).png

This documentation is deprecated

Please refer to the updated documentation https://docs.payadvantage.com.au/reference/customers_post 

Creates a new customer using any attributes sent in request body.

Two customer types can be created - A Consumer or a  Business.

To setup a direct debit or use features such as payment requests with this customer, you need to include a mobile number and email address. We recommend you create new customers with the following attributes to ensure that you can get the most use out of Pay Advantage.

Required Fields to Create a Customer

// We recommend you use these fields when creating a new customer

{
	"IsConsumer": true,
	"Email": "bob@email.com.au",
	"FirstName": "Bob",
	"MobileNumber": {
		"CountryISO": "AU",
		"Number": "0700000000"
	}
}

Example Request

curl -L -X POST 'https://api.payadvantage.com.au/v3/customers' \
 -H 'Authorization: Bearer {access_token}' \
 -H 'Content-Type: application/json' \
 -d '{
       "IsConsumer": true,
       "Email": "bob@email.com.au",
       "FirstName": "Bob",
       "LastName": "Smith",
       "MobileNumber": {
         "CountryISO": "AU",
         "Number": "0700000000"
       }
     }'

Example Responses

STATUS 201 // Successful
    
{
	"Code": "ABCDEF",
	"ExternalID": "ABC001",
	"IsConsumer": true,
	"DateJoined": "2020-09-13T14:10:31.247",
	"Name": "Bob Smith",
	"FirstName": "Bob",
	"LastName": "Smith",
	"Email": "bob@email.com.au",
	"BillerCode": null,
	"BPAYRef": null,
	"DateUpdated": "null",
	"DateCreated": "2013-09-13T14:10:31.247",
	"CreatedBy": {
		"FirstName": "Your",
		"LastName": "User",
		"UserName": "youruser@email.com"
	},
	"IsActive": true
}
STATUS 4## // Error
    
{
	"errorCode": "error_code",
	"messages": [
		"Error message."
	]
}

Request Parameters

ExternalID string min = 1, max = 50
Identifier from an external system that can be apended to this customer.
IsConsumer boolean Required
Flag that indicates customer type. True is a "Consumer" and false is a "Business".
Name string min = 1, max = 80
This attribute is used to store a business name against a customer. If the customer type is a "Consumer" do not use this attribute.
FirstName string min = 1, max = 80Required
The first name of a customer, or the first name of a businesses primary contact. When the customer type is "Consumer" this field is required.
LastName string min = 1, max = 80
The last name of a customer, or the last name of a businesses primary contact. Generally it is a good idea to include this field.
CustomRef string min = 1, max = 20
Stores a custom reference number against a customer.
Email string min = 1, max = 200Required
The customers primary email address. This address is used for sending payment receipts, alerts, and is required for a customer to authorise a direct debit.
SendDirectDebitErrorEmails boolean
Controls wether customer will be automatically sent emails on Direct Debit payment failures. If true emails will be automatically sent, if false no email will be sent. This is set to whatever default you have configured in your Pay Advantage portal's customer settings.
SendPaymentReceiptEmails boolean
Controls wether customer will be automatically sent email receipts for payments. If true emails will be automatically sent, if false no email will be sent. This is set to whatever default you have configured in your Pay Advantage portal's customer settings.
BpayDetailsEmail string array
Controls wether a customer will be sent an email with their BPAY details when it is generated by our system. Allowed options are "default", "force_do_not_send", "force_send".
DOB date string
This is an optional attribute that can be appended to a customer to record their date of birth. Enter your date string in this format "YYYY-MM-DD".
MobileNumber Dictionary Required
Customers mobile phone number. Uses these child parameters;
CountryISO string array Required
The ISO code corresponding to the mobiles country e.g. Australia is "AU". Full list of Country ISO and codes can be found here.
Number string max = 20Required
If the number is entered as a full number, i.e. "+6140000000", the CountryISO will be ignored.
HomePhoneNumber Dictionary
Customers home phone number. Uses these child parameters;
CountryISO string array
The ISO code corresponding to the mobiles country e.g. Australia is "AU". Full list of Country ISO and codes can be found here.
Number string max = 20
If the number is entered as a full number, i.e. "+6170000000", the CountryISO will be ignored.
PhoneNumber Dictionary
Customers primary contact number. Can be either a home, or mobile number. Uses these child parameters;
CountryISO string array
The ISO code corresponding to the mobiles country e.g. Australia is "AU". Full list of Country ISO and codes can be found here.
Number string max = 20
If the number is entered as a full number, i.e. "+6170000000", the CountryISO will be ignored.
Street1 string min = 1, max = 255
Address line 1. Street, PO Box, Company name e.g. "1 Smith St"
Street2 string min = 1, max = 255
Address line 2. Apartment or unit number, suite, building number.
Suburb string min = 1, max = 100
Suburb, City, District, Town, or Village name.
State string min = 1, max = 50
State, Country, Province, or region name.
Postcode string min = 1, max = 10
Post code or ZIP code.
CountryISO3316 string array
The ISO code corresponding the country the address is located in e.g. Australia is "AU".
Full list of country ISO and related codes can be found here.
Group 1 (2).png

This documentation is deprecated

Please refer to the updated documentation https://docs.payadvantage.com.au/reference/customers_put 

Updates the specified customer by setting the values of any parameters passed in the request body. For example, if you pass the Email parameter, the customers email will be updated to the new string.

If a parameter is not included in the request body, it will not be updated. This request accepts mostly the same parameters as the customer creation call with a few exceptions. The parameters used to update phone numbers are different from those used when creating a customer.

Update Customers Email Address

curl -L -X PUT 'https://api.payadvantage.com.au/v3/customers/{code}' \
 -H 'Authorization: Bearer {access_token}' \
 -H 'Content-Type: application/json' \
 -d '{
       "Email": "bob.smith@email.com"
     }'

A full list of parameters that can be passed are included after the example request and responses. Using this endpoint you can also change a customers type between business and consumer, or set them to inactive if they have no pending payments or active direct debits in Pay Advantage.

Example Request

curl -L -X PUT 'https://api.payadvantage.com.au/v3/customers/{code}' \
 -H 'Authorization: Bearer {access_token}' \
 -H 'Content-Type: application/json' \
 -d '{
       "Email": "bob.smith@email.com.au",
       "Mobile": "0400000000",
       "MobileCountryID": 1
     }'

Example Responses

STATUS 200 // Successful
    
{
	"Code": "ABCDEF",
	"DateUpdated": "2020-12-31T14:28:11:123"
}
STATUS 4## // Error
    
{
	"errorCode": "error_code",
	"messages": [
		"Error message."
	]
}

Request Parameters

ExternalID string min = 1, max = 50
Identifier from an external system that can be appended to this customer.
IsConsumer boolean
Flag that indicates customer type. True is a "Consumer" and false is a "Business". Changing this will update the customer type. If you change a customer to a business you must also update the parameter Name to be a business name.
Name string min = 1, max = 80
This attribute is used to store a business name against a customer. If the customer type is a "Consumer" do not use this attribute.
FirstName string min = 1, max = 80
The first name of a customer, or the first name of a businesses primary contact.
LastName string min = 1, max = 80
The last name of a customer, or the last name of a businesses primary contact.
CustomRef string min = 1, max = 20
Stores a custom reference number against a customer.
Email string min = 1, max = 200
The customers primary email address. This address is used for sending payment receipts, alerts, and is required for a customer to authorise a direct debit.
SendDirectDebitErrorEmails boolean
Controls wether customer will be automatically sent emails on Direct Debit payment failures. If true emails will be automatically sent, if false no email will be sent. This is set to whatever default you have configured in your Pay Advantage portal's customer settings.
SendPaymentReceiptEmails boolean
Controls wether customer will be automatically sent email receipts for payments. If true emails will be automatically sent, if false no email will be sent. This is set to whatever default you have configured in your Pay Advantage portal's customer settings.
DOB date string
This is an optional attribute that can be appended to a customer to record their date of birth. Enter your date string in this format "YYYY-MM-DD".
Phone string max = 10
Customers primary phone number. This string doesn't accept special characters such as "+" and should be a local number instead i.e. don't pass "+61400000000" instead use "0400000000"
PhoneCountryID integer
The Country ID of a customers primary phone. The full list of Country ID's can be found here.
HomePhone string max = 10
Customers home phone number. This string doesn't accept special characters such as "+" and should be a local number instead i.e. don't pass "+61700000000" instead use "0700000000"
HomePhoneCountryID integer
The Country ID of a customers home phone. The full list of Country ID's can be found here.
Mobile string max = 10
Customers mobile phone number. This string doesn't accept special characters such as "+" and should be a local number instead i.e. don't pass "+61400000000" instead use "0400000000"
MobileCountryID integer
The Country ID of a customers mobile phone. The full list of Country ID's can be found here.
Street1 string max = 255
Address line 1. Street, PO Box, Company name e.g. "1 Smith St"
Street2 string min = 1, max = 255
Address line 2. Apartment or unit number, suite, building number.
Suburb string min = 1, max = 100
Suburb, City, District, Town, or Village name.
State string min = 1, max = 50
State, Country, Province, or region name.
Postcode string min = 1, max = 10
Post code or ZIP code.
CountryISO3316 string array
The ISO code corresponding the country the address is located in e.g. Australia is "AU". Full list of country ISO and related codes can be found here.
isactive boolean
Indicates wether the customer is active or not. A customer must have no active direct debits, or pending payment requests to be set to inactive.
Group 1 (2).png

This documentation is deprecated

Please refer to the updated documentation https://docs.payadvantage.com.au/reference/customers_createbpayref 

By default your customers do not generate their own BPAY reference on creation. There are three methods to create or update customers to have a BPAY reference.

POST   '.../customers?with=bpayref'
 PUT   '/customers/{code}?with=bpayref'
 POST  '/customers/{code}/createbpayref'

Generate a BPAY Reference when Creating Customer

To generate a BPAY reference for your customer on creation you will need to add ?with=bpayref to the end of the url your are posting to.

This method functions the same as the create customer method, and will need appropriate request body parameters to return a successful response.

Example Request 

curl -L -X POST 'https://api.payadvantage.com.au/v3/customers?withbpayref' \
 -H 'Authorization: Bearer {access_token}' \
 -H 'Content-Type: application/json' \
 -d '{
       "IsConsumer": true,
       "Email": "bob@email.com.au",
       "FirstName": "Bob",
       "LastName": "Smith",
       "MobileNumber": {
         "CountryISO": "AU",
         "Number": "0700000000"
       }
     }'

Example Responses

STATUS 201 // Successful
    
{
	"Code": "ABCDEF",
	"ExternalID": "ABC001",
	"IsConsumer": true,
	"DateJoined": "2020-09-13T14:10:31.247",
	"Name": "Bob Smith",
	"FirstName": "Bob",
	"LastName": "Smith",
	"Email": "bob@email.com.au",
	"BillerCode": "1234",
	"BPAYRef": "123412341234",
	"DateUpdated": "null",
	"DateCreated": "2013-09-13T14:10:31.247",
	"CreatedBy": {
		"FirstName": "Your",
		"LastName": "User",
		"UserName": "youruser@email.com"
	},
	"IsActive": true
}
STATUS 4## // Error
    
{
	"errorCode": "error_code",
	"messages": [ 
		"Error message."
	]
}

Generate a BPAY Reference when Updating Customer

To generate a BPAY reference for an existing customer you will need to add ?with=bpayref to the end of the url your are posting to.

This method functions the same as the update customer method, and will need appropriate request body parameters to return a successful response.

Example Request 

curl -L -X PUT 'https://api.payadvantage.com.au/v3/customers/{code}?withbpayref' \
 -H 'Authorization: Bearer {access_token}' \
 -H 'Content-Type: application/json' \
 -d '{
       "Email": "bob@email.com.au",
       "MobileNumber": "0400000000",
       "MobileCountryID": 1
     }'

Example Responses

STATUS 200 // Successful
    
{
	"Code": "ABCDEF",
	"DateUpdated": "2020-12-31T14:28:11:123"
}
STATUS 4## // Error
    
{
	"errorCode": "error_code",
	"messages": [
		"Error message."
	]
}

Generate a BPAY Reference for Exisiting Customer

To generate a BPAY reference for an exisiting customer, there is a unique endpoint that can be called after referencing the customer you want to update with their Code.

This method is unique and doesn't require any body content to be sent with the request.

Example Request 

curl -L -X POST 'https://api.payadvantage.com.au/v3/customers/{code}/createbpayref' \
 -H 'Authorization: Bearer {access_token}' \

Example Responses

STATUS 200 // Successful
    
{
	"Code": "ABCDEF",
	"DateUpdated": "2020-12-31T14:28:11:123",
}
STATUS 4## // Error
    
{
	"errorCode": "error_code",
	"messages": [ 
		"Error message."
	]
}

Use the update customer endpoint and method to turn customers inactive.

Pass the boolean parameter IsActive as false to set a customer as inactive. For a customer to be set to inactive they must have no active direct debits or pending payments. If you wish to turn this customer on again later, set them active by changing this parameter to true.

Set Customer to Inactive

curl -L -X PUT 'https://api.payadvantage.com.au/v3/customers/{code}' \
 -H 'Authorization: Bearer {access_token}' \
 -H 'Content-Type: application/json' \
 -d '{
       "IsActive": false
     }'

Example Responses

STATUS 200 // Successful
    
{
	"Code": "ABCDEF",
	"DateUpdated": "2020-12-31T14:28:11:123"
}
STATUS 4## // Error
    
{
	"errorCode": "error_code",
	"messages": [
		"Error message."
	]
}

Related articles

Comments

0 comments

Article is closed for comments.