Payments

Supported Events

Event Type	Description	Applicable payment method types
PAYMENT_SUCCEEDED	Emitted when payment is captured and is successful.	CARD, BANK_ACCOUNT
PAYMENT_SUCCEDED	Emitted when payment is captured and is successful. **Will be deprecated**	CARD, BANK_ACCOUNT
PAYMENT_FAILED	Emitted when a payment fails.	CARD, BANK_ACCOUNT
PAYMENT_ACCEPTED	Emitted when a payment is submitted successfully and is being processed.	CARD, BANK_ACCOUNT
PAYMENT_AUTHORIZED	Emitted when a payment is AUTHORIZED. Authorized payment should be captured later using capture endpoint to complete the payment.	CARD
PAYMENT_CANCELED	Emitted when a payment is canceled.	CARD, BANK_ACCOUNT

Event Structure

Field	Type	Valid values	Description
name	Enum	PAYMENT_SUCCEEDED, PAYMENT_FAILED, PAYMENT_ACCEPTED, PAYMENT_AUTHORIZED, PAYMENT_CANCELED	Event name
payload	Payload		Event Payload

Payload Structure

Field	Type	Valid values	Description
amount	long	50 - 99999999	Amount (in cents) requested for payment
authorizedAmount	long	50 - 99999999	(PRE_AUTH) Maximum amount approved for capture (in cents); Starting R27, pre-authorization and partial-authorization, should infer this field to consider authorized amount; Prior to R27, infer amount field;
capturedAmount	long	50 - 99999999	(SALE) Amount(in cents) immediately settled. (PRE_AUTH) Amount(in cents) successfully captured.
partialAuthorization	boolean	true/false	(PRE_AUTH) Indicates whether a partial authorization was requested.
description	string	Max length 50	Payment Description
id	uuid	valid uuid4	Payment Identifier
merchantId	uuid	valid uuid4	Merchant Identifier
merchantTransactionId	string	Max length 50	MerchantTransactionId sent by the merchant with original payment request
paymentDateUtc	date	Date in ISO string format	Payment completed datetime
paymentMethod	PaymentMethod		Paymentmethod Description
customer	Customer		Customer Description
error	Error		Error Information
consent	Consent		Consent required for bank account payments

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
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

Consent Structure

Field	Type	Valid values	Description
merchantConsentId	string	Valid UUID	Consent Id
merchantConsentText	string		Consent text
collectionTimestamp	string		Timestamp of when the consent was collected
collectionDetails	ConsentCollectionDetails		Details about how consent was collected

Consent Collection Details Structure

Field	Type	Valid values	Description
type	enum	WEB, TEL, PPD	Consent type
web	ConsentCollectionWeb		Details of consent collected through the website
tel	ConsentCollectionTel		Details of consent collected through the telephone

Consent Collection Web Structure

Field	Type	Valid values	Description
ipAddress	string	Valid IP address	IP address from which the consent is collected
userAgent	string		Agent involved in the consent collection

Consent Collection Tel Structure

Field	Type	Valid values	Description
phoneNumber	PhoneNumber	Valid country code and phone number	Phone number from which the consent is collected

Phone Number Structure

Field	Type	Valid values	Description
countryCode	string	Valid country code	Country code
number	string	Valid phone number	Phone number

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.

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

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

Important Note

In the event that payment is captured and succeeded, we will be publishing two events: PAYMENT_SUCCEDED and PAYMENT_SUCCEEDED.

PAYMENT_SUCCEDED will be deprecated by 06/15/2024 and only PAYMENT_SUCCEEDED will be published going forward.

Payment with CARD

Events will be sent in JSON format.

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

{
      "name": "PAYMENT_SUCCEEDED"
      "payload": {
        "amount": 1500,
        "description": "Payment Description",
        "id": "6ab9bf74-03e0-4f47-bd70-bf57b103a5fd",
        "merchantId": "44387763-4eeb-4592-a564-b10aadee95be",
        "merchantTransactionId": "e31de58d-cb20-40ff-ad58-b99d500z0001",
        "paymentDateUtc": "2011-10-05T14:48:00.000Z",
        "paymentMethod": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "sourceProvider":{
                "name": "CCG"
            },
            "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": {
            "enterpriseId": "enterprise id",
            "hsid": "hsid",
            "firstName": "first name",
            "lastName": "last name",
            "email": "email",
            "ssnLastFour": "1234",
            "phoneNumber": {
                "number": "1234567890",
                "countryCode": "1"
            },
            "dateOfBirth": "dob",
            "zip5": "23124"
            "metadata": {
                "patientId": "rx-patient-id"
            }
        },
        "error": {
            "code": "card_declined",
            "message": "Your card has insufficient funds.",
            "declineCode": "generic_decline",
            "errorDetails": {
                "code": "no_account",
                "message": "The customer's bank account could not be located.",
                "declineCode": "generic_decline",
                "networkDeclineCode": "51",
                "networkAdviceCode":"02"
              }
          }
      }
}

Payment with BANK ACCOUNT

{
    "name": "PAYMENT_SUCCEDED",
    "payload": {
        "amount": 5000,
        "capturedAmount": 5000,
        "partialAuthorization": false,
        "description": "Test Payment from Postman_003",
        "id": "27f986f9-8440-4d30-8816-b3faf82dfd2e",
        "merchantId": "44387763-4eeb-4592-a564-b10aadee95be",
        "merchantTransactionId": "a812eb9d-9726-4764-b30a-06c234a75fa1",
        "paymentDateUtc": "2024-05-06T12:26:27.192037",
        "consent": {
            "merchantConsentText": "some text",
            "collectionTimestamp": "1054684654",
            "collectionDetails": {
                "type": "TEL",
                "tel": {
                    "inboundPhoneNumber": {
                        "countryCode": "1",
                        "number": "1234567890"
                    }
                }
            }
        },
        "paymentMethod": {
            "paymentMethodType": "BANK_ACCOUNT",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "sourceProvider":{
                "name": "CCG"
            },
            "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": {
            "enterpriseId": "enterprise id",
            "hsid": "hsid",
            "firstName": "first name",
            "lastName": "last name",
            "email": "email",
            "ssnLastFour": "1234",
            "phoneNumber": {
                "number": "1234567890",
                "countryCode": "1"
            },
            "dateOfBirth": "dob",
            "zip5": "23124"
            "metadata": {
                "patientId": "rx-patient-id"
            }
        }
    }
}