Payment Methods

This documentation page provides a comprehensive guide on managing payment methods on the CarePortals Patient API. You will learn how to use it to retrieve, add, and remove payment information, ensuring a seamless and secure transaction experience.

Careportals is available to integrate with Stripe and NMI payment processors.

Pre-requisites

Before you begin, you need to configure a payment processor for your organization. See the pages below to learn how to set up your payment processor on CarePortals:

Stripe Setup

NMI Setup

📘
While the setup for Stripe and NMI is different, the API requests to manage payment methods are the same for both.

Managing Payment Methods

The CarePortals Patient API provides the following endpoints to manage a patient's payment methods:

Retrieve Existing Payment Methods
Add a New Payment Method
Remove a Payment Method

Retrieve Existing Payment Methods

To check if a patient already has saved payment methods, such as before starting a checkout process, you can retrieve a list of them by calling the Retrieve Patient Payment Methods endpoint with a GET request. The following headers are required:

Authorization (<your_token>): This header must contain the JSON Web Token (JWT) for the authenticated patient.
Accept: This header specifies the desired content type of the response.
Origin: This header indicates the origin of the request.

curl 'https://patient-api.portals.care/users/payment-methods' \
  -H 'Authorization: Bearer <your_token>' \
  -H 'Accept: application/json, text/plain, * \
  -H 'Origin: https://demo.portals.care'

[
  {
    "id": "pm_1Rz78FKeCoUxIkZxXhFa0HlF",
    "object": "payment_method",
    "allow_redisplay": "unspecified",
    "billing_details": {
      "address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "123 Main Street",
        "line2": "Apt 4B",
        "postal_code": "94105",
        "state": "CA"
      },
      "email": "[email protected]",
      "name": "Jane Doe",
      "phone": "+14155552671",
      "tax_id": null
    },
    "card": {
      "brand": "visa",
      "checks": {
        "address_line1_check": "pass",
        "address_postal_code_check": "pass",
        "cvc_check": "pass"
      },
      "country": "US",
      "display_brand": "visa",
      "exp_month": "4",
      "exp_year": "2029",
      "fingerprint": "wkxxH2W0e4S1mvIM",
      "funding": "credit",
      "generated_from": null,
      "last4": "4242",
      "networks": {
        "available": [
          "visa"
        ],
        "preferred": null
      },
      "regulated_status": "unregulated",
      "three_d_secure_usage": {
        "supported": true
      },
      "wallet": null
    },
    "created": 1755915879,
    "customer": "cus_Rwr5mZerq1Q2VL",
    "livemode": false,
    "metadata": {},
    "radar_options": {},
    "type": "card",
    "last4": "4242",
    "exp": "4/2029"
  }
]

Upon a successful request, the API will return an array of the patient's saved payment method objects.

📘
If no payment methods are found, the API will return an empty array ([]).

Add a New Payment Method

To add a new payment method for a patient, you will call the Add Patient Payment Method endpoint with a POST request. This is useful during a checkout flow when a patient does not have a saved payment method or when they are updating their payment information in their profile.

For the body, the required parameter is the paymentMethodId.

📘
paymentMethodId
The paymentMethodId is a token that must be generated on your front-end by the payment processor's library (e.g., Stripe.js).

For Stripe: This value is the PaymentMethod ID (e.g., pm_123abc...).

For NMI: This value is the Payment Token.

Please consult the official Stripe or NMI developer documentation for token creation.

curl -X POST 'https://patient-api.portals.care/v2/users/payment-methods' \
--header 'Authorization: Bearer <YOUR_JWT>' \
--header 'Content-Type: application/json' \
--data '
{
  "paymentMethodId": "pi_1Rz78FKeCoUxIkZxXhFa0HlF"
}'

{
  "last4": "0101",
  "type": "card",
  "exp": "9/2028"
}

A successful response will return a payment method object containing the last4 digits, type, and expiration date (exp) of the newly added card.

Remove a Payment Method

To remove a patient's expired or invalid payment method, call the Remove Payment Method endpoint with a DELETE request. The specific ID of the payment method you wish to delete must be included as a path parameter in the URL.

curl -X DELETE 'https://patient-api.portals.care/v2/users/payment-methods/pi_1Rz78FKeCoUxIkZxXhFa0HlF' \
--header 'Authorization: Bearer <YOUR_JWT>'

{
  "success": true
}

A successful response indicates that the payment method was deleted and will return a JSON object with a boolean success field set to true.