Payments: Refund

Modified on Fri, 29 Mar 2024 at 09:56 PM

Refunding a Payment

This API is used to refund a sale transaction after a sale has been completed.

You will need your MerchantID {mid} and PaymentKey {x-acme-payment-key} to run refunds, if you do not have these, please contact your ACME account manager.

This API utilizes previously generated tokens, leveraging ACME’s Token API and the Charge Object

POST v1/payment/{mid}/refund

Request Parameters

The merchant id that the authorization

Request Body

Include a RefundRequest object as the body of the request.

Sample Request

POST https://sandX-api.acmepayments.net/v1/payment/12345/refund

Sample Request Body

{
  "saleId" : "sale_72a57412-04bf-4803-9667-369cd414a07f",
  "charge": {
    "amount" : 1.00
  }
}

Response

Returns an RefundResponse object.

Sample Response Body

Successful Refund Transaction

{
    "saleId": "sale_72a57412-04bf-4803-9667-369cd414a07f",
    "refundId": "refund_f9ff5560-f770-422e-bea1-58ba44cd74c2",
    "charge":
    {
        "amount": "1.00"
    },
    "card":
    {
        "lastFour": "3333",
        "expirationDate":
        {
            "month": "12",
            "year": "2026"
        },
        "brand": "Visa"
    },
    "amount":
    {
        "totalAmount": "1.00",
        "netAmount": "0.86",
        "fee":
        {
            "totalFee": "0.14",
            "fixedFee": "0.06",
            "percentageFee": "0.08",
            "percentageRate": "2.90"
        }
    }
}

Failed Refund Transaction

Failed responses will vary depending on which trusted party is issuing a failure. In some cases, ACME may or may not pass back the code depending on the type of failure encountered. We will make best efforts to send back issuing bank or processor errors.

{
    "message": "Refund amount must be positive",
    "errorCode": 10026,
    "type": "NEGATIVE_REFUND_AMOUNT",
    "requestId": "6e360f6a-5d31-11ec-9ceb-064a412857e4"
}

RefundRequest Object

Name	Type	Description	Required
saleId	string	The Sale Id that you are refunding	Required
charge	Charge Object ›	The charge object for the refund. The amount being refunded on the order is required. It cannot be more than is remaining on the order or token if one is provided	Required

RefundResponse Object

Name	Type	Description
refundId	string	The id of the refund
saleId	string	The Sale Id that you are refunding
charge	Charge Object ›	The charge object associated with the refund. The amount refunded will match the input amount as we will error if there is insufficient funds on the order to be refunded to this token otherwise.
card	Card Object ›	The details of the credit card
Fee	Fee Object	Fee object containing the details of the fees

Fee Object

Name	Type	Description
totalFee	string	The total amount of the fee
fixedFee	string	The amount of the fee that was due to a fixed rate
percentageFee	string	The amount of the fee that was due to a percent rate
percentageRate	string	The percentage that was used to calculate the fee
optional fee	string	An optional fee that might be applied at time of transaction creation.