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.
• Linked refunds are supported for both CARD and ACH payment methods, whereas unlinked refunds are supported only for the CARD payment method.

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	PENDING, COMPLETED, 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

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

Paymentmethod Structure

Field	Type	Valid values	Description
id	uuid	valid uuid4	Payment method Id
card	Card		Card Description when payment Method is of type CARD. Deprecated in favour of paymentMethodDetails
nickname	string	Max length 50	Payment method nickname
default	boolean	true/false	determines if the payment method is default for the customer
paymentMethodType	string	Max length 50	Payment method type can be CARD or BANK_ACCOUNT
paymentMethodDetails	Card or ACH		One of Card or ACH
sourceProvider	SourceProvider		To identify the source of the Payment method

Source Provider Structure

Field	Type	Valid values	Description
name	Enum	CCG, GOOGLE_PAY, APPLE_PAY	Name of the source provider

Card Structure

Field	Type	Valid values	Description
nameOnCard	string	Max length 50	Name of the customer
cardBrand	string	VISA, AMEX, DINERS, DISCOVER, JCB, MASTERCARD, UNIONPAY, UNKNOWN	Card brand
expiryMonth	long	01-12	Month of expiration
expiryYear	long	Max length 4	Year of expiration
last4	string	Max length 4	Last four digits of the card
zipCode	string	Max length 5	5 digit zipcode
status	string	ACTIVE/EXPIRED	Status of the card
manufacturerCard	boolean	true/false	Determines if the card is manufacturer card or not. Only Agents can flag certain cards as manufacturer cards. Cards flagged as manufacturer cards cannot be default card.
cardCategories	CardCategories		Card categories that define different types of payment cards and their associated medication information

ACH Structure

Field	Type	Valid values	Description
type	string	BANK_ACCOUNT	Type of the PaymentMethod
accountHolderType	string	individual or company	Account holder type
accountType	string	checking or savings	Account Type
bankName	string		Bank Name
last4	string		Last 4 digits of bank account number
routingNumber	string		Routing number of bank
nameOnAccount	string		Name on Account
status	enum	ACTIVE and INVALIDATED	Bank Account Status

CardCategories Structure

CardCategories is an array of card category objects that define different types of payment cards and their associated medication information.

Field	Type	Valid values	Description
type	string	MANUFACTURER_CARD	The type of card category
medications	array[object]	Array of Objects	List of medication objects that are eligible for payment using this card

Example CardCategories Structure

"cardCategories": [
    {
        "type": "MANUFACTURER_CARD",
        "medications": []
    }
]

Note:

• The medications array can be empty [] if no specific medications are associated with the card category.
• cardCategories array can be empty for normal or regular card.

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": {  
             "name": null,  
             "firstName": "John",  
             "lastName": "Doe",  
             "email": "test@mail.com",  
             "ssnLastFour": "6785",  
             "dateOfBirth": "2000-09-21",  
             "hsid": "62b737bf-ca25-4319-b2b7-05d0fd684654",  
             "enterpriseIdentifier": null,  
             "zip5": null,  
             "phoneNumber": {  
                "number": "9876543210",  
                "countryCode": "91"  
             },  
             "metadata": {
                "patientId": "rx-patient-id"
            }  
        },
        "paymentMethod": {
            "card": {
                "last4": "4444",
                "status": "ACTIVE",
                "zipCode": "94043",
                "cardBrand": "MASTERCARD",
                "expiryYear": 2026,
                "nameOnCard": "Card Holder Name",
                "expiryMonth": 12,
                "manufacturerCard": true,
                "cardCategories": [
                    {
                        "type": "MANUFACTURER_CARD",
                        "medications": []
                    }
                ]
            },
            "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": []
                    }
                ]
            }
        },
        "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
    }
}

More Info on REFUND_FAILED Webhook

The REFUND_FAILED webhook is triggered when a refund attempt for a payment cannot be successfully processed at Stripe or CCG processor.

This event is critical because it ensures that merchants are informed about refund failures so they can promptly address the situation, maintain customer trust, and avoid operational bottlenecks.

Refer to the table below to understand the various failure scenarios at the CCG processor

Unlinked Refund Failure Scenarios

Error Scenario	REFUND_FAILED Webhook Triggered	PaymentMethodDetails Included
Credit to Invalid Payment Method ID	Yes	No
Credit Exceeds Allowed Refund Limit	Yes	Yes
Credit to Bank Account	Yes	No

Linked Refund Failure Scenarios

Error Scenario	REFUND_FAILED Webhook Triggered	PaymentMethodDetails Included
Refund on Invalid Payment ID	Yes	No
Refund on Uncaptured Payment	Yes	Yes
Refund on Closed ACH Account	Yes	Yes
Refund for Disputed Payments	Yes	Yes
Refund on Payment Already Refunded	Yes	Yes
Refund Greater than Original Amount	Yes	Yes