Using Refunds
The secure refund APIs allow you to refund a settled payment transaction. Funds are refunded to the credit/debit card or ACH account, which was used in the payment transaction.
The secure refund API allows you to refund a settled payment transaction. Funds are refunded to the credit/debit card or ACH account which was used in the payment transaction.
Note: The refund API currently supports refunds of the total payment transaction amount only. Partial amount refunds are not supported.
The refund process comprises two steps:
- The merchant calls the POST Retrieve Refund Eligibility method to determine if the payment transaction is currently eligible to be refunded.
- If the POST Retrieve Refund Eligibility response indicates that the transaction is eligible for refund, the merchant calls the POST Secure Refund Payment method to process the refund.
Prerequisites
To process refunds, the merchant must have the Refund Collection feature enabled. Contact your AndDone administrator if Refund Collection is not enabled.
Checking Refund Eligibility
Before submitting a refund payment request, the merchant must verify that the payment transaction is eligible for refund. To be eligible for refund, a transaction meet the following criteria:
- The transaction must be successfully processed and settled at least two days prior to the refund request.
- The transaction must be of type SALE.
- The transaction status must not be Authorized, Chargeback, Declined or Failed.
- The transaction must not be part of a batch that is yet to be processed.
- The transaction must not be in the MPIPD/MPIPI payment category.
- The transaction must not be processed with Commerce Bank.
- The transaction is not eligible if the transaction status is refunded and the total refund amount is equal to the Total capture amount of the transaction.
- The transaction is not eligible if the transaction status is refunded and there is a refund event on the transaction in the previous 24 hours.
To check the eligibility of the payment transaction for refund, call the POST Retrieve Refund Eligibility method. This method requires the unique transaction identifier (TransactionId) for the payment transaction to be refunded.
Example: POST Retrieve Refund Eligibility request body
{
"TransactionId": "8241f0b3-9976-42d8-9e03-b640292f6549"
}The POST Retrieve Refund Eligibility method returns the eligibility status of the specified payment transaction.
Examples: POST Retrieve Refund Eligibility response
If the transaction is eligible for refund, a refundEligible value of true is returned.
{"refundEligible":true,"message":null}If the transaction is not eligible for for refund, a message is returned stating the reason for ineligibility.
{
"message": "Key_InProgressTransactionCanNotBeRefunded"
"description": "",
"errors": []
}Requesting a Refund Payment
If the payment transaction is eligible for a refund, you can submit a refund payment request by calling the POST Secure Refund Payment method. This method requires the unique transaction identifier (TransactionId) for the payment transaction to be refunded and the amount of the payment. Note that the amount to be refunded must equal the total dollar amount of the payment. Partial refunds are not currently supported.
{
"RefundAmount": 128.00,
"TransactionId": "8241f0b3-9976-42d8-9e03-b640292f6549",
"RefundDetail": "Refund down payment amount.",
"RefundReason": "Incorrect amount charged."
}If successful, the POST Secure Refund Payment method returns:
- The
transactionID,traceNumberandrefundReferenceassociated with the refund payment. - The details of the original payment transaction, including payment method, billing contact, amount and the original payment transaction ID
referenceTransactionID.
Example: POST Secure Refund Payment response
{
"transactionId": "940636ae-d74e-4b9a-b7bc-35c560720be5",
"traceNumber": "JSTFJRRD43LWFL65",
"transactionCode": "WEB",
"transactionOrigin": "WebForm",
"refundOrigin": "API",
"billingContact": {
"name": {
"title": null,
"firstName": "Joe",
"middleName": null,
"lastName": "Jackson"
},
"companyName": null,
"department": null,
"fax": null,
"phone": "8003213388",
"alternatePhone": null,
"mobile": null,
"email": null,
"url": null,
"address": {
"addressLine1": "30",
"addressLine2": "Memorial Drive",
"city": "Avon ",
"state": "NY",
"country": 1,
"postalCode": "12701",
"timeZone": null
}
},
"shippingContact": null,
"referenceTransactionId": "8241f0b3-9976-42d8-9e03-b640292f6549",
"transactionDate": "01-11-2024 10:36:37",
"merchantId": "4bvl9KxM",
"ipAddress": "162.158.175.22",
"operationType": "Refund",
"channelType": "CreditCard",
"processMethod": "CardNotPresent",
"processorName": "Adyen",
"isDebit": false,
"tenderInfo": {
"bankName": null,
"routingNumber": null,
"rawMICRLine": null,
"accountType": null,
"checkType": null,
"checkNumber": null,
"nameOnCheck": null,
"accountHolderName": null,
"accountCategory": null,
"cardHolderName": "Joe Jackson",
"cardType": "VISA",
"maskCardNumber": "****0008",
"binNumber": null,
"cardExpiry": "0330",
"cvData": null,
"cvDataStatus": "NS",
"trackData": null,
"healthCareAccountType": null,
"rxAmount": 0.0,
"visionAmount": null,
"dentalAmount": null,
"clinicAmount": null,
"isCheckCard": false,
"captureAmount": 128.0,
"amount": 128.0,
"tipAmount": 0.0,
"convenienceAmount": 0.0,
"taxAmount": 0.0,
"taxAfterDiscount": false,
"taxPercent": 0.0,
"adjustmentPercentValue": null,
"adjustmentFixedValue": null,
"adjustmentAmount": null,
"adjustmentDisplayName": null,
"adjustmentDescriptorMessage": null,
"paymentAdjustmentType": "None",
"preAuthCode": null,
"maskAccount": null,
"epb": null,
"ksn": null,
"cashBackAmount": 0.0,
"accountToken": null,
"accountTokenMessage": null,
"createAccountToken": false,
"discountType": "Fixed",
"discountPercent": 0.0,
"discountAmount": 0.0,
"commissionType": 0,
"commissionValue": null
},
"referenceCustomerId": null,
"customerAccountId": null,
"invoiceNo": null,
"poNo": null,
"referenceNo": "Reference_1032",
"remarks": null,
"recurringType": "Installment",
"recurringId": null,
"installmentNumber": null,
"installmentCount": null,
"allowDuplicates": false,
"verificationEnabled": false,
"sentSuccessNotification": false,
"sentFailedNotification": false,
"trainingMode": false,
"terminalId": "VT000085",
"isOffline": false,
"transactionStatus": "PendingForAuthorized",
"previousTransactionStatus": "Created",
"transactionResult": null,
"level": 0,
"partnerId": null,
"orderId": null,
"invoiceId": null,
"paymentLinkId": null,
"additionalFields": null,
"settlementDate": null,
"issuer": "FIRST PEOPLES COMMUNITY F.C.U.",
"paymentReference": "Reference_1032",
"refundReference": "940636ae-d74e-4b9a-b7bc-35c560720be5"If the refund request is unsuccessful, the POST Secure Refund Payment returns a message indicating the reason that the refund request was not completed.
{
"message": "Key_AlreadyRefundedTransaction",
"description": "",
"errors": []
}Refund Eligibility and Payment Request Messages
The following table describes the messages returned by the POST Retrieve Refund Eligibility and POST Secure Refund Payment Request methods.
| Message | Description |
|---|---|
| Key_BatchedTransactionCanNotBeRefund | The payment transaction is part of a batch and cannot be refunded. |
| Key_IPFSTransactionCanNotBeRefund | This is a merchant payment transaction made on behalf of IPFS and cannot be refunded using this API. |
| Key_CommerceBankTransactionCanNotBeRefund | Transactions processed by Commerce Bank cannot be refunded using this API. |
| Key_InProgressTransactionCanNotBeRefunded | The payment transaction is currently in progress and cannot be refunded. |
| Key_RejectedTransactionCanNotBeRefunded | The payment transaction was rejected and cannot be refunded. |
| Key_ChargebackTransactionCanNotBeRefund | The payment transactions is in a chargeback status and cannot be refunded. |
| Key_SetteledTransactionCanNotBeLessThanTwoBussinessDay | The payment transaction was settled within the last two business days and cannot be refunded. Payment transactions must be settled at least two days prior to the refund payment request. |
| Key_RefundAmountCanNotBeGreaterThanCapturedAmount | The specified refund amount is greater than the captured amount for the payment transaction. The reqeusted refund amount must be equal to the amount of the payment transaction. |
| Key_RefundAmountIsNotValid | The selected refund amount is invalid and cannot be processed. |
| Key_TransactionIdCannotBeEmptyOrNULL | An invalid transaction has been selected for refund; the transaction ID cannot be empty or null. |
| Key_RefundAmountAndCaptureAmountShouldBeEqual | Partial refunds are not permitted. The refund amount must be equal to the payment transaction amount. |
| Key_PlatFormAccountTransactionCanNotBeRefunded | Platform account transactions cannot be refunded. |