The 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
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 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."
]
}
Comments
0 comments
Please sign in to leave a comment.