Refund status updates

Understand the different ways to get the status of a refund

The time it takes a bank to process a refund can vary and may not be instant. Because of this, Vyne provides updates when a refund status changes.

There are different methods to obtain the status of the refund.

Entity

Method

Description

Use case

Using the refund

Webhook notifications

Webhook notification of a status change on the refund.

Be notified as soon as the refund status changes.

Using the refund

Get refunds

Get the status of the refund manually.

If a manual update is required on demand, merchants can get the status of the refund at any time.

Using webhook notifications

When the status of a refund or payment is updated, Vyne will send a digitally signed POST request to the specified callback URL. Make sure you have set up a callback URL.

You will receive two webhook notifications:

  1. A notification of refund status change.
  2. A notification of payment status change (to REFUNDED or PART_REFUNDED).

Find out more about refund statuses here.

Webhook

--header 'x-signature=h4DnIgww/Qw0NhMFlzgQuLKpvhVgJGm5ZSImO7wh7MewUX3AJYa06fwh9naN1Zp7h9OopRbVR3oY8L0PzDmirXyX1QM3eRZIkSjAZs+S9vx7D2ETH0WGk3ByJ28i3j6Q3Be3G5PEx91llVgTsOyYTdKVykzh/b8azI+5fr45PMe6mOKVjb8hoBsMJP9n+jQWQ8NnkR9h4iCxxqULFsY+oXu08dFFMPfnyc2Lp7rA66kLZVU7w4XS3rrNxoWV65Z75lvB8wAefWkR9KdFE8kWdZpAqdG+nC78EEZOo3fMoW+RuNKP57rw0yjC0Xmh8fActzTVyKcBlhum+/fTBc8rCbeoFKoHBiXQ+mcTKTdTveVEe2P95jtet6C2AMI0grRo7N45kMPT2IhyFxe4WUtafkpkJhTCu65QliGlQwKnebCQYB4uQUmvTQ8vli8FKjomeGis4KYOkQMA1YAatVF00IThbVVKO3QafVGUfn3Sue6EdNPT8UW8DiQ2UPsAYCI8N+M0YyebQZ48NqAv6Rp0Kz/srxiJc7YiWhLIgmoFe5Kfz+HWrIIZknH66HRhK3AFYocSliWtOH9p6YwaDNZ/M7giW7zjNpjWyRq7uoPLFD9OYZgaC+4vIreL3KTx/eCVHx0yqNajVSYAuMExwrPxoctklGAjuWHEFIRtm6wXqE0='
--header 'x-signature-keyId=718c7272-4e33-466b-8ad8-28fa2c95193f'
{
  "type": "REFUND_STATUS_CHANGE",
  "refundId": "1715e35b3894ba09",
  "status": "COMPLETED",
  "paymentId": "f4fce78db4020045",
  "timestamp": 1632739322180,
  "amount": 5.00,
  "currency": "GBP",
  "merchantReference": "ABC",
  "customerReference": "123"
}

Parameter

Description

type

A constant type for the refund status notification.

refundId

16 digit long, alphanumeric unique identifier.

status

The new status of the refund. For all possible statuses see here.

paymentId

16 digit long, alphanumeric unique identifier of the payment to which the refund belongs.

timestamp

Exact date when the webhook notification was sent represented by a UNIX epoch time in milliseconds.

amount

The amount of the refund.

currency

The three-character refund currency using ISO 4217.

merchantReference (if provided)

The merchant reference of the related payment, optionally provided by merchant upon making PIRPIR - Payment Initiation Request.

customerReference (if provided)

The customer reference of the related payment, optionally provided by merchant upon making PIRPIR - Payment Initiation Request.

📘

Helpful to know

Although webhook notifications will always be sent when the status of a refund is updated, notifications are only sent for a payment when there is a status change:

  • If the payment already has a status of PART_REFUNDED, and the subsequent refund amount doesn't result in a full refund, a webhook notification will not be sent.
  • If the payment already has a status of PART_REFUNDED, and the subsequent refund amount does result in a full refund, a webhook notification will be sent as the status changes from PART_REFUNDED to REFUNDED.

Verifying integrity

Every webhook notification sent by Vyne is digitally signed using public key cryptography, also known as asymmetric cryptography, and will allow the merchant verify the origin and the integrity of the message. Learn how to verify the integrity of the webhook notification here.

Using refund status call

Request

You can request the status of on any refund at any time by sending an HTTP GET request to the relevant base URL + /api/v1/refunds/ including the headers Authorization: Bearer <payment_token>. Generate a fresh payment token for the <payment_token>.

curl --location --request GET 'https://uat.app.payvyne.com/api/v1/refunds/REFUND-1bd7805da16df89e' \
--header 'Authorization: Bearer <payment_token>' \
--header 'Content-Type: application/json'

Parameter

Description

refundId

16 digit alphanumeric unique refund identifier.

Response

A successful request returns a 200 response code and an object with details of the refund.

If something unexpected happened during the request, the API returns an error response with the appropriate HTTP status code and a JSON response that contains detailed information about the problem.

{
  "refundId": "1715e35b3894ba09",
  "status": "COMPLETED",
  "paymentId": "f4fce78db4020045",
  "amount": 5.00,
  "currency": "GBP",
  "merchantReference": "ABC",
  "customerReference": "123"
}

Parameter

Description

refundId

16 digit alphanumeric unique refund identifier.

status

The current status of the refund. For all possible statuses see here.

paymentId

16 digit alphanumeric unique payment identifier (corresponding to the original payment).

amount

The amount to be refunded.

currency

The three-character refund currency using ISO 4217.

merchantReference (if provided)

Reference field for order ID - can be up to 256 characters and alphanumeric.

customerReference (if provided)

Reference field for customer ID - can be up to 128 characters alphanumeric.


Did this page help you?