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",
"DateCreated": "2020-12-02T00:00:00",
"DateFailed": null,
"DateClears": "2020-12-03T00:00:00",
"DateSettled": "2020-12-03T08:34:33.013",
"DateUpdated": "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"},
"Uri": ".../v3/payments/PID123"
}
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",
"DateCreated": "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:
|
| 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",
"DateCreated": "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",
"DateCreated": "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."
]
}
Comments
0 comments
Please sign in to leave a comment.