MakeRefund API

Cancel payment and return funds to customer

Overview

The "MakeRefund" endpoint is a POST request. It is used to cancel the payment and return the funds to the customer. Detailed functionality of how to use this endpoint is explained in the Refund section.

The endpoint on Swagger is: Refund_MakeRefund.

Now, we are going to declare the endpoint and its models along with each accepted parameter and possible value.

📘 Request Header: Add "Authorization": "Bearer {Token}" to request header. Token of demo configuration can be found in your portal account settings.
❗ Refund Request Responsibility: Please make sure to send one refund request each time, to avoid duplicate partial refund requests (You need to handle this from your system front-end side). Also, make sure your system prevents duplicate refund submissions for the same payment.

Request Model

The request is a POST request with the following parameters:

Input Parameter Type Description
KeyType string State either it's "InvoiceId" or "PaymentId"
Key string Value of the key type mentioned
ServiceChargeOnCustomer boolean Determine whether the customer will be charged for the service fees or not. Service fees (for Royat Pay).
Amount decimal The amount to be refunded
Comment string Extra comments for your reference

Response Model

After viewing the Response Model that you will get as a result of your request, here, you will find full details about the Data Model of this API endpoint. Let's check it and its contents.

Response Field Type Description
Key string The key value you have passed for the Request Transaction
RefundId number The unique refund ID
RefundReference string The refund reference generated by Royat Pay for following up with the finance team
RefundInvoiceId string The InvoiceId of the refunded amount
Amount number The amount to be refunded
Comment string The comments that you have passed in the request

Sample Messages

MakeRefund Request

{
  "Key": "3445302",
  "KeyType": "invoiceid",
  "ServiceChargeOnCustomer": false,
  "Amount": 1,
  "Comment": "partial refund to the customer"
}

MakeRefund Response

{
  "IsSuccess": true,
  "Message": "Refund Created Successfully!",
  "ValidationErrors": null,
  "Data": {
    "Key": "3445302",
    "RefundId": 86815,
    "RefundReference": "2024000022",
    "RefundInvoiceId": 3449413,
    "Amount": 1,
    "Comment": "partial refund to the customer"
  }
}

Important Notes

KeyType Values

  • "InvoiceId" - Use when you have the Invoice ID
  • "PaymentId" - Use when you have the Payment ID

Partial Refunds

You can process partial refunds by specifying an Amount less than the original payment amount. Make sure to handle duplicate refund requests on your front-end to avoid processing the same refund multiple times.

Service Charge

The ServiceChargeOnCustomer parameter determines whether the customer will be charged for the service fees. Set to false if you want to absorb the service charge, or true if the customer should pay it.

API Endpoint

Endpoint Method Description
/api/payment/refund POST Create a refund for a payment transaction

Support

For more information and support, please contact the Royat Pay team.