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.

Prerequisites

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:

📘

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

• Organization ID (<ORG_ID>): If you are using a custom domain, you must send the Organization ID (<ORG_ID>) in the request header. For requests made from a CarePortals subdomain, this header is not required, as the ID is retrieved from the domain itself.

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.