Skip to main content

Save cards and charge saved cards for payments on account

Summary​

Partners can save a patient's card from every card payment endpoint, list the patient's saved cards, and charge a saved card to create a payment on account.

Saving a card​

Pass storeCardDetails: true to save the card used for the payment:

  • createPaymentIntentForPaymentOnAccount
  • createPaymentIntentForBooking
  • startTerminalPaymentOnAccount
  • startTerminalPaymentForBooking

When storeCardDetails is false or omitted, the card is not saved. The implementor is responsible for ensuring the cardholder has given explicit consent for card details to be stored and used for future payments.

The card is saved after the payment succeeds. Saving never blocks or fails the payment itself. If the patient already has the same card saved, the existing card is kept and no duplicate is added.

For the two Terminal operations, the practice must be able to save cards from a terminal; otherwise the request returns the error Saving cards from a terminal is not available for this practice. PaymentOnAccountTerminalPayload and BookingTerminalPaymentPayload include a new cardSaved field:

  • null when saving was not requested or the payment has not succeeded yet.
  • true when the card was saved.
  • false when the payment succeeded but Stripe did not produce a card that can be saved.

Listing saved cards​

patientSavedCards(patientId) returns the patient's saved cards. Each SavedPaymentCard has an id and the same PaymentCardDetails shown on payments (brand, last four digits and expiry). A patient without saved cards returns an empty list. It requires the seePatients and createPayment rights.

Charging a saved card​

payOnAccountWithSavedCard charges one of the patient's saved cards and records the payment on account in the same request. It takes the patientId, a savedCardId from patientSavedCards, the amount, a required chargeType, and the optional date, comment and metadata used by other payments on account. It returns the created PaymentOnAccount and the Stripe paymentChargeId. It requires the createPayment right.

chargeType states how the patient authorises the charge:

  • MAIL_OR_TELEPHONE_ORDER – the patient authorises this charge by phone, email or post.
  • MERCHANT_INITIATED – the practice charges the card under an agreement the patient made earlier, without the patient taking part.

When the charge fails, no payment on account is created and the payload returns an error. A card that does not belong to the patient returns Saved card not found for patient.

If the card issuer requires authentication (3D Secure), the charge fails with Card requires authentication; use createPaymentIntentForPaymentOnAccount with the patient present. In that case, take the payment with createPaymentIntentForPaymentOnAccount while the patient is present to complete authentication.

Migration​

All changes are additive. Existing requests behave as before.