Version: v1

Payment Methods

This document describes the webhook events related to payment methods and their structures.

Quick Reference

Supported Events - List of all payment method webhook events
Event Structure - Core structure of webhook event payloads
Payload Structure - Details of the payload object
Data Structures - Reference for all data structures
Sample Events - Example JSON payloads for different payment method events

Supported Events

Supported Events

Event Type	Description
PAYMENT_METHOD_CREATED	Emitted when a payment method is created.
PAYMENT_METHOD_UPDATED	Emitted when a payment method is updated.
PAYMENT_METHOD_DELETED	Emitted when a payment method is deleted.
PAYMENT_METHOD_REPLACED	Emitted when a payment method is replaced. More details

Event Structure

Event Structure

Field	Type	Valid values	Description
name	Enum	PAYMENT_METHOD_CREATED, PAYMENT_METHOD_UPDATED, PAYMENT_METHOD_DELETED, PAYMENT_METHOD_REPLACED	Event name
source	string	Max length 50	Indicates the X-source header value received in API request
payload	Payload		Event Payload

Payload Structure

Payload Structure

Field	Type	Valid values	Description
paymentMethod	PaymentMethod		Payment method Description
customer	Customer		Customer Description
agent	Agent		Agent Description
deletedPaymentMethodId	UUID	Valid UUID	Deleted PaymentMethod Id, in PAYMENT_METHOD_REPLACED event

Data Structures

Customer Structure

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
dateOfBirth	Date (YYYY-MM-DD)		Date of Birth, e.g. 1975-11-14
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
zip5	Digits (5)		ZIP Code, e.g. 10001

Agent Structure

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

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

Card Structure

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.

ACH Structure

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

Sample Events

note

card object under paymentMethod is deprecated in favor of paymentMethodDetails. Please refer PaymentMethod for more details.

PAYMENT_METHOD_* with Card

{
    "name": "PAYMENT_METHOD_CREATED | PAYMENT_METHOD_UPDATED | PAYMENT_METHOD_DELETED | PAYMENT_METHOD_REPLACED",
    "source": "vendor-portal",
    "payload": {
        "paymentMethod": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "card": {
                "last4": "string",
                "type" : "CARD",
                "status": "ACTIVE",
                "cardBrand": "VISA",
                "expiryYear": 0,
                "nameOnCard": "string",
                "expiryMonth": 0,
                "zipCode": "string",
                "manufacturerCard": false
            },
            "paymentMethodDetails": {
                "last4": "string",
                "type" : "CARD",
                "status": "ACTIVE",
                "cardBrand": "VISA",
                "expiryYear": 0,
                "nameOnCard": "string",
                "expiryMonth": 0,
                "zipCode": "string",
                "manufacturerCard": false
            },
            "default": true,
            "paymentMethodType": "CARD",
            "nickname": "string"
        },
        "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     
        },
        "agent": {
            "firstName": "First Name",
            "lastName": "Last Name",
            "userId": "msId",
            "isAccessVerified": true
        },
        "deletedPaymentMethodId": "597f6eca-6276-4993-bfeb-53cbbbba6f12"
    }
}

PAYMENT_METHOD_* with Bank Account

{
    "name": "PAYMENT_METHOD_CREATED | PAYMENT_METHOD_UPDATED | PAYMENT_METHOD_DELETED | PAYMENT_METHOD_REPLACED",
    "source": "vendor-portal",
    "payload": {
        "paymentMethod": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "paymentMethodType": "BANK_ACCOUNT",
            "paymentMethodDetails": {
                "type": "BANK_ACCOUNT",
                "accountHolderType": "individual",
                "accountType": "checking",
                "bankName": "STRIPE TEST BANK",
                "last4": "6789",
                "routingNumber": "110000000",
                "nameOnAccount": "Name on account test",
                "status": "ACTIVE"
            },
            "nickname": "Nickname test",
            "default": true
        },
       "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     
        },
        "agent": {
            "firstName": "First Name",
            "lastName": "Last Name",
            "userId": "msId",
            "isAccessVerified": true
        },
        "deletedPaymentMethodId": "597f6eca-6276-4993-bfeb-53cbbbba6f12"
    }
}

Supported Events​

Event Structure​

Payload Structure​

Data Structures​

Customer Structure​

Agent Structure​

PaymentMethod Structure​

Card Structure​

ACH Structure​

Sample Events​