Refunds

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'

This documentation is deprecated

Please refer to the updated documentation https://docs.payadvantage.com.au/reference/refunds_post-1

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.

This documentation is deprecated

Please refer to the updated documentation https://docs.payadvantage.com.au/reference/refunds_get-1

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." 
	]
}

This documentation is deprecated

Please refer to the updated documentation https://docs.payadvantage.com.au/reference/refunds_search-1

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

This documentation is deprecated

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

Comments

Articles in this section

Related articles