The Refunds API handles the creation, cancellation, and monitoring of refunds for payments. As with payments, a refund is never effectively successful, it just hasn’t failed. If a refund attempt does ever fail, you should cancel the refund or re-attempt the refund to an alternate account (via the Web Portal only).
Refunds that have been forced by chargebacks from external agencies can be detected using the IsMerchantInitiated field being set as false. Please note that you cannot modify these refunds.
Endpoints
GET '/refunds/{code}'
GET '/refunds'
POST '/refunds'
PUT '/refunds/{code}?cancel=true'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.
To refund an amount in full including all on-charged fees you should omit or set the the amount field to Null. To partially refund specify a value in the amount field. When partially refunding only that amount will be refunded.
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",
"ExternalID": "Your reference ID",
"IsMerchantInitiated": true,
"Amount": 49.12,
"Reason": "Product Return",
"Account": "012-345, XXX123",
"DateCreated": "2021-04-02T11:50:43.235",
"DateUpdated": "2021-04-04T13:51:42.14",
"DateCancelled": null,
"CancelledReason": null,
"DateFailed": null,
"FailReason": null,
"Payment": {
"Code": "AAA111"
},
"Customer": {
"Code": "ABC123",
"Name": "Some Customer"
},
"CreatedBy": {
"FirstName": "John",
"LastName": "User",
"UserName": "john.u@yourdomain.com"
}
}STATUS 4## // Error
{
"errorCode": "error_code",
"messages": [
"Error message."
]
}
Request Parameters
| Reason string Required |
|---|
| Small description why the refund was issued. |
| Payment dictionary Required |
|
Code string Required
Unique identifier of the payment you want to create a refund for.
|
| ExternalID string |
| Identifier from an external system that can be appended to a refund. |
| Amount decimal |
| The amount to refund. Will refund the remaining payment amount if omitted. To refund in full including on-charged fees value should be Null or field omitted. |
Returns a single refund record using the Code of a refund as an identifier.
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",
"ExternalID": "Your Reference ID",
"IsMerchantInitiated": true,
"Amount": 49.12,
"Reason": "Product Return",
"Account": "012-345, XXX123",
"DateCreated": "2021-04-02T11:50:43.235",
"DateUpdated": "2021-04-04T13:51:42.14",
"DateCancelled": null,
"CancelledReason": null,
"DateFailed": null,
"FailReason": null,
"Payment": {
"Code": "AAA111"
},
"Customer": {
"Code": "ABC123",
"Name": "Some Customer"
},
"CreatedBy": {
"FirstName": "John",
"LastName": "User",
"UserName": "john.u@yourdomain.com"
}
}
STATUS 4## // Error
{
"errorCode": "error_code",
"messages": [
"Error message."
]
}
Returns a list of refund records. 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",
"ExternalID": "Your reference ID",
"IsMerchantInitiated": true,
"Amount": 49.12,
"Reason": "Refund Reason",
"Account": "012-345, XXX123",
"DateCreated": "2020-12-02T11:50:43.235",
"DateUpdated": "2020-12-04T13:51:42.14",
"DateCancelled": null,
"CancelledReason": null,
"DateFailed": null,
"FailReason": null,
"Payment": {
"Code": "AAA111"
},
"Customer": {
"Code": "ABC123",
"Name": "Some Customer"
},
"CreatedBy": {
"FirstName": "John",
"LastName": "User",
"UserName": "john.u@yourdomain.com"
}
},
{ ... }
]
"Meta": {
"page": 0,
"recs_per_page": 100,
"total_recs": 1
}
}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 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 string |
| Identifier from an external system that can be appended to a refund. |
| payment.code string |
| Unique identifier assigned to the payment that this refund is for. Use this to find any refunds related to a specific payment e.g. payment.code=aaa111 |
| customer.code string |
| Unique identifier assigned to the customer that this refund is associated with. Use this to find any refunds related to a specific customer e.g. customer.code=ABC123 |
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."
]
}
Comments
0 comments
Please sign in to leave a comment.