Articles in this section

Payments

  • Updated

Payments

Our Payments API holds real-time records of any attempted payment in the Pay Advantage system. It is used for monitoring and tracking payments so that they can be managed appropriately by your own system. The Payments API does not deal with re-attempting failed payments.

All payments are associated with either a Customer, or a Debit Instruction. When a payment is attempted we allow a small window for any failures to be reported (typically 2-3 business days). This is due to some banks and credit card facilities being slow to respond to payments. If no failure has been reported within this window then it is considered "cleared" and will then be settled to your account. BPAY payments are the only exception as they clear/settle immediately.

All payment types can fail (for a number of reasons) in which case the “DateFailed” and “FailCode” fields will be populated. Be aware that a payment can fail after the money has been settled to your account. This could occur many days, months, even years after settlement. Because of this nature of payments, It is more correct to consider a payment as "not failed" rather than succeeded; however for most scenarios you can consider a settled payment as a "success". Charge-backs and late dishonours are very rare for most businesses.

Endpoints

GET     '/payments/{code}'
 GET     '/payments'
 GET     '/payments_failed/{ddMMyyyy}'
 GET     '/payments_settled/{ddMMyyyy}'

Returns a single payment record using the Code value of a payment as an identifier. This lets you view the current status of a payment, a history of the payments progression through different states (paid, failed, cleared, settled, etc.), any reason for failure, amount, payment type, any other relevant references.

Example Request

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

Example Responses

STATUS 200 // Successful
    
{
	"Code": "PID123",
	"DatePaid": "2020-12-02T00:00:00",
	"DateFailed": null,
	"DateClears": "2020-12-03T00:00:00",
	"DateSettled": "2020-12-03T08:34:33.013",
	"FailCode": null,
	"FailReason": null,
	"Amount": 300,
	"AmountIncFees": 300,
	"ReadyToSettle": true,
	"PaymentType": "bpay_bank_Account",
	"ExternalID": "Your reference ID",
	"BPAYReference": "123456789",
	"SettlementCode": "AABB12",
	"Customer":{"Code": "HJH123", "Name":"John Smith"}
}

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

Returns a list of payment records arranged by date paid (most recent first by default). The list is paged and will always return the first page of records. If there are no records that match your search you will be returned an empty list.

Example Request

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

Example Responses

STATUS 200 // Successful
    
{
	"Records": [
		{
			"Code": "PID123",
			"DatePaid": "2020-12-02T00:00:00",
			"DateFailed": null,
			"DateClears": "2020-12-03T00:00:00",
			"DateSettled": "2020-12-03T08:34:33.013",
			"FailCode": null,
			"FailReason": null,
			"Amount": 300,
			"AmountIncFees": 300,
			"ReadyToSettle": true,
			"PaymentType": "bpay_bank_Account",
			"ExternalID": "Your reference ID",
			"BPAYReference": "123456789",
			"SettlementCode": "AABB12",
	                "Customer":{"Code": "HJH123", "Name":"John Smith"}
		},
		{
			...
		}
	]
	"Meta": {
		"page": 0,
		"recs_per_page": 100,
		"total_recs": 594
	}
}
STATUS 4## // Error
    
{
	"errorCode": "error_code",
	"messages": [
		"Error message."
	]
}

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 payment records. 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 payment 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
  • datepaid
  • datefailed
  • datesettled
  • dateupdated
  • amount
  • amountincfees
  • customername
code string min = 6, max = 6
Unique internal identifier specific to a single payment.
datecreated date string
Returns payment records based on date and time they were 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 payment records that 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 payment records that 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}
datepaid date string
Returns payment records based on date and time a payment was attempted. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datepaid={ddMMyyyy}
datepaidto date string
Returns payment records that were attempted 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. datepaidto={ddMMyyyy}
datepaidfrom date string
Returns payment records that were attempted 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. datepaidfrom={ddMMyyyy}
datefailed date string
Returns payment records based on date and time a payment was failed. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datefailed={ddMMyyyy}
datefailedto date string
Returns payment records that failed 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. datefailedto={ddMMyyyy}
datefailedfrom date string
Returns payment records that failed 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. datefailedfrom={ddMMyyyy}
dateclears date string
Returns payment records based on date and time a payment will be cleared. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. dateclears={ddMMyyyy}
dateclearsto date string
Returns payment records that will clear 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. dateclearsto={ddMMyyyy}
dateclearsfrom date string
Returns payment records that will clear 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. dateclearsfrom={ddMMyyyy}
datesettled date string
Returns payment records based on date and time a payment settled to your bank account. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datesettled={ddMMyyyy}
datesettledto date string
Returns payment records that settled 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. datesettledto={ddMMyyyy}
datesettledfrom date string
Returns payment records that settled 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. datesettledfrom={ddMMyyyy}
dateupdated date string
Returns payment records based on the last date and time a payment was updated. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. dateupdated={ddMMyyyy}
dateupdatedto date string
Returns payment records that were updated/changed 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
Returns payment records that were updated/changed 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. dateupdatedfrom={ddMMyyyy}
amount number
The payment amount value as a currency amount in AUD e.g. 15.50
amountto number
Returns payment records where the amount is less than or equal to the amount queried. Enter amount value as a currency amount in AUD e.g. 15.50
amountfrom number
Returns payment records where the amount is more than or equal to the amount queried. Enter amount value as a currency amount in AUD e.g. 15.50
readytosettle boolean
Indicates wether the payment has been cleared and is ready to settle to your bank account. This will remain true after a payment has settled.
amountincfees number
Total amount that was charged for the payment (inclusive of fees). Amount needs to be entered in AUD e.g. $100 would be amountincfees=100.00
amountincfeesto number
Returns an array of records where the total payment amount (inclusive of fees) is equal to or less than the value queried. Amount needs to be entered in AUD e.g. $100 would be amountincfeesto=100.00
amountincfeesfrom number
Returns an array of records where the total payment amount (inclusive of fees) is equal to or more than the value queried. Amount needs to be entered in AUD e.g. $100 would be amountincfeesfrom=100.00
bpayreference string min = 10, max = 10
Will return a payment record associated with this BPAY Customer Reference Number.
externalID string max = 50
The Reference applied to a related debit instruction.
customer.code string min = 6, max = 6
The identifier of the customer that this payment was for. Note debit instructions will return null.
settlementcode string min = 6, max = 6
The identifier of the settlement that this payment was included in.
failcode string array
View a list of fail codes in our Enum Values & Fail Codes section. Use the name as the query value.
paymenttype string array
View a list of payment types in our Enum Values & Fail Codes section. Use the name as the query value.

Returns a list of failed payments for a specified date. Avoid using today's date as payments can fail at any time during the day. For direct debit bank payments, it is best to query failed payments at least one day since the payment was attempted. You can view a list of fail codes in our Enums & Fail Codes documentation to better understand reason for failure returned on these payment records and manage appropriately.

Example Request

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

If required you create more complex filters using the previous end point and parameters for returning a list of payment records. For example, returning a list of failed payments for a week.

GET 'https://api.payadvantage.com.au/v3/payments?datefailedfrom=10122020&datefailedto=17122020'

Example Responses

STATUS 200 // Successful
    
{
	"Records": [
		{
			"Code": "PID123",
			"DatePaid": "2020-12-02T00:00:00",
			"DateFailed": "2020-12-03T00:00:00",
			"DateClears": "2020-12-03T00:00:00",
			"DateSettled": null,
			"FailCode": "insufficient_funds",
			"FailReason": "Try another card or try again later.",
			"Amount": 300,
			"AmountIncFees": 300,
			"ReadyToSettle": false,
			"PaymentType": "direct_debit_credit_card",
			"ExternalID": null,
			"BPAYReference": null,
			"SettlementCode": null,
	                "Customer":{"Code": "HJH123", "Name":"John Smith"}
		},
		{
			...
		}
	]
	"Meta": {
		"page": 0,
		"recs_per_page": 100,
		"total_recs": 15
	}
}
STATUS 4## // Error
    
{
	"errorCode": "error_code",
	"messages": [
		"Error message." 
	]
}

Returns a list of settled payments for a specified date. If using today as the date, it is recommended to run this as late in the day as possible (6pm - Midnight) so that any settlements that occurred during the day are captured.

Example Request

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

Example Responses

STATUS 200 // Successful
    
{
	"Records": [
		{
			"Code": "PID123",
			"DatePaid": "2020-12-02T00:00:00",
			"DateFailed": null,
			"DateClears": "2020-12-03T00:00:00",
			"DateSettled": "2020-12-03T08:34:33.013",
			"FailCode": null,
			"FailReason": null,
			"Amount": 300,
			"AmountIncFees": 300,
			"ReadyToSettle": true,
			"PaymentType": "bpay_bank_Account",
			"ExternalID": "Your reference ID",
			"BPAYReference": "123456789",
			"SettlementCode": "AABB12",
	                "Customer":{"Code": "HJH123", "Name":"John Smith"}
		},
		{
			...
		}
	]
	"Meta": {
		"page": 0,
		"recs_per_page": 100,
		"total_recs": 287
	}
}
STATUS 4## // Error
    
{
	"errorCode": "error_code",
	"messages": [
		"Error message." 
	]
}

Related articles

Comments

0 comments

Please sign in to leave a comment.