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",
	"ExternalReference": "Your reference ID",
	"BPAYReference": "123456789",
	"SettlementCode": "AABB12"
}

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",
			"ExternalReference": "Your reference ID",
			"BPAYReference": "123456789",
			"SettlementCode": "AABB12"
		},
		{
			...
		}
	]
	"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.
externalreference string max = 50
The Reference applied to a related debit instruction.
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",
			"ExternalReference": null,
			"BPAYReference": null,
			"SettlementCode": null
		},
		{
			...
		}
	]
	"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",
			"ExternalReference": "Your reference ID",
			"BPAYReference": "123456789",
			"SettlementCode": "AABB12"
		},
		{
			...
		}
	]
	"Meta": {
		"page": 0,
		"recs_per_page": 100,
		"total_recs": 287
	}
}

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

Refunds

Our Refunds API handles the creation, cancellation, and monitoring of refunds for payments. When you create a refund in Pay Advantage you append a payment as a reference, but the refund is treated as it's own unique payment. As with payments, a refund is never effectively successful, it just hasn’t failed. There is even the potential for a refund to be sent back at a later date.

If a refund’s status is set to Failed you can identify the date and reason by interrogating the attempts then looking at the record marked as IsCurrent. If a refund is re-attempted then a new attempt record will be created and the status will change to Pending, even if only for a very short while.

Attempts indicate the refund is going back to the original account used with the payment being refunded. This is identified by the IsOriginatingAccount field. Refunds that have been forced from chargebacks by external agencies can be detected using the IsMerchantInitiated field being set as false. Please note that you cannot modify these refunds. It is possible to refund to an alternative bank account, but only via the Pay Advantage web-application.

Endpoints

GET     '/refunds/{code}'
 GET     '/refunds'
 POST    '/refunds'
 PUT     '/refunds/{code}?cancel=true'

Returns a single refund record using the Code value of a refund as an identifier. This lets you view the current status of a refund, a history of attempts, any reason for failure, amount, reference to the payment this refund is associated, wether the refund was initiated by you.

Example Request

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

Example Responses

STATUS 200 // Successful
    
{
	"Code": "AAA000",
	"DateCreated": "2020-12-02T11:50:43.235",
	"DateUpdated": "2020-12-04T13:51:42.14",
	"Amount": 49.12,
	"ExternalReference": "Your reference ID",
	"Status": "processing",
	"Payment": {
		"Code": "AAA111"
	},
  "IsMerchantInitiated": true,
  "Attempts": [
		{
			"IsCurrent": true,
      "IsOriginatingAccount": true,
      "DateCreated": "2020-12-04T11:50:43.235",
      "DateFailed": null,
      "FailReason": null
		},
    {
			"IsCurrent": false,
      "IsOriginatingAccount": true,
      "DateCreated": "2020-12-02T11:50:43.235",
      "DateFailed": null,
      "FailReason": null
		}
	]
}

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

Returns a list of refund records arranged by date created (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/refunds' \
 -H 'Authorization: Bearer {access_token}'

Example Responses

STATUS 200 // Successful
    
{
	"Records": [
		{
			"Code": "AAA000",
			"DateCreated": "2020-12-02T11:50:43.235",
			"DateUpdated": "2020-12-04T13:51:42.14",
			"Amount": 49.12,
			"ExternalReference": "Your reference ID",
			"Status": "processing",
			"Payment": {
				"Code": "AAA111"
			},
			"IsMerchantInitiated": true,
			"Attempts": [
				{
					"IsCurrent": true,
					"IsOriginatingAccount": true,
					"DateCreated": "2020-12-04T11:50:43.235",
					"DateFailed": null,
					"FailReason": null
				},
				{
					"IsCurrent": false,
					"IsOriginatingAccount": true,
					"DateCreated": "2020-12-02T11:50:43.235",
					"DateFailed": null,
					"FailReason": null
				}
			]
		},
		{
			...
		}
	]
	"Meta": {
		"page": 0,
		"recs_per_page": 100,
		"total_recs": 594
	}
}

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

Query Parameters

page integer
The page number you want to view using the zero-based index i.e. page=0 will return page 1 of refund 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.
datecreated date string
Returns refund 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 refund 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 refund 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}
dateupdated date string
Returns refund records based on the last date and time a refund 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 refund 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 refund 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 refund amount as a currency amount in AUD e.g. 15.50
amountto number
Returns refund 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 refund 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
externlid boolean
Identifier from an external system that can be appended to a refund.
status string array
payment_clearing string If the payment fails it won't be cleared, then the refund is not necessary. So the refund waits for the payment to clear before being sent. chargeback_clearing string If the refunded payment has been settled to your account, then a chargeback initiated by the customers bank retrieves this payment from the Merchant (you). The refund to the Customer will not continue until the chargeback clears. It is worth checking with your customer and potentially cancelling the refund if a customer has initiated a chargeback. pending string The refund is ready to be attempted, but has not yet been processed. processing string The refund has been accepted by the payment gateway and is processing. processed string The refund has been accepted by the payment gateway and has been processed. failed string The refund failed to process. cancelled string The refund was cancelled either intentionally by your account or the because the original payment failed clearing and the refund was not necessary. undetermined string A gateway issue has occurred and the refund's status is not yet known. Do not take any further action on this refund until this issue is resolved. If the issue remains unresolved for an extended period of time contact support and our technical team will look into it.
payment dictionary
code string Unique identifier assigned to the payment that this refund is associated with. Use this to filter list by any refunds related to a specific payment e.g. payment.code=aaa111

Create a refund payment and queue it up to be processed. When you create a refund in Pay Advantage you append a payment as a reference, but the refund is treated as it's own unique payment.

This request must include the relevant payments Code and a Reason for refund. The full amount including any fees will be refunded. Eventually partial refunds will allow for different amounts.

Like payments, refunds can sometimes take some time to process, this is dependant on payment type and bank processing times. As with payments, a refund is never effectively successful, it just hasn’t failed. There is even the potential for a refund to be sent back at a later date.

Example Request

curl -L -X POST 'https://api.payadvantage.com.au/v3/refunds' \
 -H 'Authorization: Bearer {access_token}' \
 -H 'Content-Type: application/json' \
 -d '{
       "Reason": "Product Return",
       "Payment": {
         "Code": "AAA111"
       },
       "ExternalID": "Your Reference ID"
     }'

Example Responses

STATUS 200 // Successful
    
{
	"Code": "AAA000",
	"DateCreated": "2020-12-02T11:50:43.235",
	"DateUpdated": "2020-12-04T13:51:42.14",
	"Amount": 49.12,
	"ExternalReference": "Your reference ID",
	"Status": "processing",
	"Payment": {
		"Code": "AAA111"
	},
  "IsMerchantInitiated": true,
  "Attempts": [
		{
			"IsCurrent": true,
      "IsOriginatingAccount": true,
      "DateCreated": "2020-12-04T11:50:43.235",
      "DateFailed": null,
      "FailReason": null
		}
	]
}

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

Request Parameters

Reason string Required
Use this string attribute to publish a reference reason for the refund. This is to help you identify what was refunded, why etc.
Payment dictionary Required
Code string Required Unique internal identifier appended to the payment you want to create a refund for.
ExternalID string
Identifier from an external system that can be appended to a refund.

Will cancel a refund if it has not yet been processed. Uses the refunds Code attribute as an identifier. Not all refunds are able to be cancelled. For example, once a refund has been processed it can not be cancelled. To cancel a refund you must provide a cancel reason in the request body. A successful response will return an empty body.

Example Request

curl -L -X PUT 'https://api.payadvantage.com.au/v3/refunds/{code}?cancel=true' \
 -H 'Authorization: Bearer {access_token}' \
 -H 'Content-Type: application/json' \
 -d '{
       "Reason": "Reason for cancelling"
     }'

Example Responses

STATUS 204 // Successful
    
{
	
}

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

Articles in this section

Payments & Refunds

Payments

Refunds

Comments

Articles in this section

Payments

Refunds

Related articles