Skip to main content
To return funds to your shopper, refund the payment. You can refund either the full captured amount or a part of the captured amount. You can also perform multiple partial refunds, as long as their sum doesn’t exceed the captured amount. Some payment methods do not support partial refunds. To learn if a payment method supports partial refunds, refer to the payment method page such as cards, iDEAL, or Klarna.
You can only refund a payment after it has already been captured.

​
Refund a payment

In order to refund a payment, you will need the transaction id from the transaction you want to refund. You can retrieve this identifier in several ways:
  • In a server-to-server integration, the transactionId field is returned at the root of the create payment response.
  • For a Checkout integration, query the order by its orderId. The associated transactions are listed under the Transactions node, which includes the transactionId field.
  • If you have notifications configured, Paybyrd sends a notification for each processed payment. Every notification includes the transactionId for that event.
  • You can also find the transactionId in the Paybyrd dashboard for every transaction in the Transacion Detail view.

​
API Call

You can find below an example of how to refund a transaction and the generated response: 
curl --request POST \
 --url https://gateway.paybyrd.com/api/v2/refund/4faa13cd-f6ff-414e-b5bd-b61d1e72e418 \
 --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --header 'x-api-key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B' \
 --data '{"amount":"10.00"}'

{
 "sourceTransaction": {
   "refundedAmount": "10.00",
   "remainingAmount": "0.00",
   "transactionId": "4faa13cd-f6ff-414e-b5bd-b61d1e72e418",
   "amount": "10.00"
 },
 "code": "BYRD200",
 "description": "Operation successfully completed",
 "transactionId": "c16ce479-319d-4e7b-a966-7735c34b2cc5",
 "amount": "10.00"
}

​
Handling rejections

Refunds can be declined, and you must handle these cases in your integration. When a refund cannot be processed, Paybyrd responds with code BYRD205. For example: 
curl --request POST \
 --url https://gateway.paybyrd.com/api/v2/refund/4faa13cd-f6ff-414e-b5bd-b61d1e72e418 \
 --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --header 'x-api-key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B' \
 --data '{"amount":"5.00"}'

{
 "sourceTransaction": {
   "refundedAmount": "0.00",
   "remainingAmount": "5.00",
   "transactionId": "4faa13cd-f6ff-414e-b5bd-b61d1e72e418",
   "amount": "5.00"
 },
 "code": "BYRD205",
 "description": "Operation rejected",
 "transactionId": "c16ce479-319d-4e7b-a966-7735c34b2cc5",
 "amount": "5.00"
}
When you receive BYRD205, the refund was declined by the bank. Declines can be temporary, so you can retry the request later. For more information about a declined refund, contact support.

​
Handling errors

When the Paybyrd API encounters an error, you receive this response structure:
Payment already refunded
{
	"isError": true,
	"code": "BYRD230",
	"description": "The refund amount exceeds the remaining balance of the original payment"
}
Generic error
{
	"isError": true,
	"code": "BYRD999",
	"description": "Operation failed. This code is related to unhandled errors."
}
You can find the full list of response codes and their descriptions in the Response code reference.