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
source	string	Max length 50	Indicates the X-source header value received in API request
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
agent	Agent		Agent Description

Customer Structure

Field	Type	Valid values	Description
enterpriseIdentifier	string	Max length	Enterprise Identifier
hsid	uuid	valid uuid4	Healthsafe Identifier
metadata	Object		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

PaymentMethodDetails - CardCategories

For refunds initiated on payments made using manufacturer cards and unlinked refunds made using manufacturer card, the paymentMethodDetails object will include a cardCategories array with additional information:

Field	Type	Description
cardCategories	Array	Array of card category objects for manufacturer cards
└─ type	string	Type of card (e.g., "MANUFACTURER_CARD")
└─ medications	Array	List of medications associated with the card; may be empty array
└─ label	string	Name of medication (e.g., "Acetaminophen")
└─ value	string	Medication dosage information (e.g., "125mg")

The cardCategories object will be included in the following scenarios:

• For manufacturer cards with associated medications: The medications array will contain medication objects with label and value
• For manufacturer cards without medications: The medications array will be empty

Agent Structure

Field	Type	Valid values	Description
firstName	string	Max length 50	First name of Agent
lastName	string	Max length 50	Last name of Agent
userId	string	Max length 50	MSId of Agent
isAccessVerified	boolean	true/false	Is access verified by merchant

Sample Event

Events will be sent in JSON format.

{
    "name": "REFUND_SUCCESS | REFUND_FAILED  | REFUND_PENDING",
    "source": "vendor-portal",
    "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": {  
            "enterpriseIdentifier": "enterprise id",
            "hsid": "62b737bf-ca25-4319-b2b7-05d0fd684654",
            "metadata": {
                "patientId": "rx-patient-id"
            }
            "firstName": "John",  
            "lastName": "Doe",
            "dateOfBirth": "2000-09-21", 
            "email": "test@mail.com",  
            "ssnLastFour": "6785",         
            "phoneNumber": {  
                "number": "9876543210",  
                "countryCode": "91"  
            }
            "zip5": null     
        },
        "paymentMethod": {
            "card": {
                "last4": "4444",
                "status": "ACTIVE",
                "zipCode": "94043",
                "cardBrand": "MASTERCARD",
                "expiryYear": 2026,
                "nameOnCard": "Card Holder Name",
                "expiryMonth": 12,
                "manufacturerCard": true
            },
            "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": true,
                "cardCategories": [
                    {
                        "type": "MANUFACTURER_CARD",
                        "medications": [
                            {
                                "label": "Acetaminophen",
                                "value": "125mg"
                            }
                        ]
                    }
                ]
            }
        },
        "agent": {
            "firstName": "string",
            "lastName": "string",
            "isAccessVerified": true,
            "userId": "string"
        },
        "merchantTransactionId": "b6d52a1f-b4e7-4de7-85de-9bd5032d7643"
    },
    "error": {
        "code": "VENDOR_ERROR",
        "message": "Cannot issue refund on expired or cancelled card",
        "declineCode": "generic_decline",
        "errorDetails": null
    }
}