Refunds

Refund events are sent when a refund is processed. Refunds can be processed for both CARD and BANK_ACCOUNT payment methods. There are two types of refunds that can be processed i.e., linked and unlinked refunds.

• Linked refunds are processed against a payment and unlinked refunds are processed without a payment.
• In case of unlinked refunds i.e., credit / cashback, payment method id is needed to process the refund.

Supported Events

Event Type	Description	Applicable payment method types
REFUND_SUCCESS	Emitted when refund is successful.	CARD, BANK_ACCOUNT
REFUND_FAILED	Emitted when a refund fails.	CARD, BANK_ACCOUNT
REFUND_PENDING	Emitted when a refund status is pending.	CARD, BANK_ACCOUNT

Event Structure

Field	Type	Valid values	Description
name	Enum	REFUND_SUCCESS, REFUND_FAILED, REFUND_PENDING	Event name
payload	Payload		Event Payload

Payload Structure

Field	Type	Valid values	Description
amount	long	50 - 99999999	Refund amount in United States Cents
reason	String	Max length 50	Refund reason
refundId	uuid	valid uuid4	Refund Identifier
Payment	Payment		Payment Details
merchantTransactionId	String	Max length 50	MerchantTransactionId sent by the merchant with original refund request
merchantId	uuid	valid uuid4	Merchant Identifier
metadata	String	Max length 50	Client provided additional metadate
paymentMethod	PaymentMethod		Paymentmethod Description
customer	Customer		Customer Description
error	Error		Error Information
status	String	COMPLETED and FAILED	Refund Status

Customer Structure

Field	Type	Valid values	Description
enterpriseId	string	Max length	Payment method Id
hsid	uuid	valid uuid4	Healthsafe Identifier
metadata	string	Max length 50	Client provided additional metadata
firstName	String		first name
lastName	String		last name
email	String		email address
ssnLastFour	Digits (4)		SSN last four digits, e.g 1234
phoneNumber	Object		Contains both the phone number and the country code
└─ number	Digits (10-20)		Phone number, e.g. 9876543210
└─ countryCode	Digits (1-3)		Country code, e.g. 91
dateOfBirth	Date (YYYY-MM-DD)		Date of Birth, e.g. 1975-11-14
zip5	Digits (5)		ZIP Code, e.g. 10001

Error Structure

Field	Type	Valid values	Description
code	string	Max length 50	Short code for error
description	string	Max length 255	Error description
errorDetails	ErrorDetails		Error details

Error Details Structure

Field	Type	Valid values	Description
code	string	Max length 100	code for error
message	string	Max length 255	Error description
declineCode	string	Max length 100	Decline Code
networkAdviceCode	string	Max length 100	Network Advice Code
networkDeclineCode	string	Max length 100	Network Decline Code

Sample Event

Events will be sent in JSON format.

{
    "name": "REFUND_SUCCESS | REFUND_FAILED  | REFUND_PENDING",
      "payload": {
        "amount": 100,
        "reason": "DUPLICATE",
        "status": "COMPLETED",
        "payment": {
            "id": "d3398a06-e038-4aaa-9a6f-08e6884b6aa9",
            "amount": 900000,
            "merchantId": "b955db5e-aef2-47de-bbb9-c80b9cc16e8f",
            "description": "UI widget payment",
            "capturedAmount": 900000,
            "partialAuthorization": false,
            "merchantTransactionId": "68da00a3-d96c-4731-ad9c-f7b4f005b04c"
        },
        "refundId": "242ecd9b-333a-4537-ba95-bea1de6ce973",
        "merchantId": "b955db5e-aef2-47de-bbb9-c80b9cc16e8f",
        "customer": {  
                "name": null,  
                "firstName": "John",  
                "lastName": "Doe",  
                "email": "test@mail.com",  
                "ssnLastFour": "6785",  
                "dateOfBirth": "2000-09-21",  
                "hsid": "62b737bf-ca25-4319-b2b7-05d0fd684654",  
                "enterpriseId": null,  
                "zip5": null,  
                "phoneNumber": {  
                "number": "9876543210",  
                "countryCode": "91"  
                },  
                patientId": "rx-patient-id"  
        },
        "paymentMethod": {
            "card": {
                "last4": "4444",
                "status": "ACTIVE",
                "zipCode": "94043",
                "cardBrand": "MASTERCARD",
                "expiryYear": 2026,
                "nameOnCard": "Card Holder Name",
                "expiryMonth": 12,
                "manufacturerCard": false
            },
            "default": false,
            "nickname": "",
            "paymentMethodType": "CARD",
            "paymentMethodDetails": {
                "type": "CARD",
                "last4": "4444",
                "status": "ACTIVE",
                "zipCode": "94043",
                "cardBrand": "MASTERCARD",
                "expiryYear": 2026,
                "nameOnCard": "Card Holder Name",
                "expiryMonth": 12,
                "manufacturerCard": false
            }
        },
        "merchantTransactionId": "b6d52a1f-b4e7-4de7-85de-9bd5032d7643"
    },
    "error": {
        "code": "VENDOR_ERROR",
        "message": "Cannot issue refund on expired or cancelled card",
        "declineCode": "generic_decline",
        "errorDetails": null
    }
}