Plugin API Reference

Medpaid Plugin API

The general endpoints for integrating HSA/FSA payments into your storefront, grouped by resource. Only /plugin/ endpoints are listed here — internal and admin endpoints are not included.

Base URLhttps://api.medpaid.com

Authentication?OnboardingKey=…&ExternalKey=…

Content-Typeapplication/json

ProtocolHTTPS only

Authentication — Include OnboardingKey and ExternalKey as query parameters on every request. These credentials are issued when your merchant account is set up. Contact support@medpaid.com to retrieve or rotate your keys. Keep keys server-side — do not expose them in client-side code.

Clients

Configure platform connection, verify setup, and retrieve merchant account details. Most integrations call configure-platform once during setup, then check-platform to confirm all fields are correct before going live.

POST/plugin/clients/configure-platformConfigure Platform

Set connection settings for a generic plugin integration. Provide your store domain, callback URLs, and plugin key.

Request Body application/json

ExternalKey string Your merchant external key.

OnboardingKey string Your merchant onboarding key.

StoreDomain string nullable Your store domain (e.g. yourstore.com).

CartCallbackUri string nullable URL Medpaid calls after cart is processed.

OrderConfirmationRedirectUri string nullable URL to redirect shoppers after order confirmation.

PluginApiUri string nullable Your plugin API endpoint URI.

PluginKey string nullable Plugin-specific authentication key.

Response 200 OK

(boolean) boolean true if configuration was saved successfully.

POST/plugin/clients/check-platformCheck Platform

Verify that all required platform settings are in place. Use this after configure-platform to confirm you are ready to accept carts.

Request Body application/json

ExternalKey string Your merchant external key.

OnboardingKey string Your merchant onboarding key.

Response 200 OK

IsOk boolean true when all required fields are present and valid.

HasStoreDomain boolean Whether store domain is configured.

HasPluginKey boolean Whether plugin key is set.

HasCartCallbackUri boolean Whether cart callback URL is set.

HasOrderConfirmationRedirectUri boolean Whether order confirmation redirect is set.

HasPluginApiUri boolean Whether plugin API URI is set.

Config object Current platform config values.

Errors string[] List of validation errors if IsOk is false.

GET/plugin/clients/get-clientGet Client

Retrieve authenticated merchant account details.

Parameters

NameInTypeRequiredDescription

OnboardingKeyquerystringYes

ExternalKeyquerystringYes

Response 200 OK

Id string (guid) Medpaid merchant ID.

Name string Merchant business name.

ContactName string Primary contact name.

ContactEmail string Primary contact email.

ContactPhone string Primary contact phone.

Address string Merchant address.

IsActive boolean Whether the merchant account is active.

GET/plugin/clients/get-client-statusGet Client Status

Lightweight check to confirm the merchant account is active. Useful for health checks in your integration.

Parameters

NameInTypeRequiredDescription

OnboardingKeyquerystringYes

ExternalKeyquerystringYes

Response 200 OK

IsActive boolean true when the merchant account is enabled.

POST/plugin/clients/log-intakeLog Intake

Submit a new merchant intake form. Used during onboarding to register a merchant before credentials are issued.

Request Body application/json

PublicKey string Public onboarding key provided by Medpaid.

Name string Business name.

Address string Business address.

Website string Store website URL.

ContactFirstName string Contact first name.

ContactLastName string Contact last name.

ContactEmail string Contact email address.

ContactPhone string Contact phone number.

Response 200 OK

(boolean) boolean true if intake was recorded successfully.

Cart

Push an order's cart from your storefront to Medpaid to start the HSA/FSA checkout or reimbursement flow. Each push returns a Ref, the cart reference that identifies the cart from then on.

POST/plugin/cart/pushPush Cart

Submit a cart for generic plugin integrations. Returns a Ref to identify this cart through the Medpaid flow.

Request Body application/json

Action string Flow type: "checkout" for direct HSA/FSA payment, "reimburse" for post-purchase reimbursement.

Source string Integration source identifier (e.g. "plugin").

PlatformId string nullable Your platform's identifier for this order.

OnboardingKey string

ExternalKey string

OrderData object Order details.

OrderId string nullable

OrderDate string nullable

CustomerId string nullable

Email string nullable

Phone string nullable

CurrencyCode string

BillingAddress object nullable

FirstName string nullable

LastName string nullable

Phone string nullable

Company string nullable

Address1 string nullable

Address2 string nullable

City string nullable

ProvinceCode string nullable

CountryCode string nullable

Zip string nullable

ShippingAddress object nullable

FirstName string nullable

LastName string nullable

Phone string nullable

Company string nullable

Address1 string nullable

Address2 string nullable

City string nullable

ProvinceCode string nullable

CountryCode string nullable

Zip string nullable

LineItems object[] Array of line items.

Name string nullable

LineId string nullable

ProductId string

VariantId string nullable

Quantity integer

Subtotal decimal

Total decimal

LineItemsTotal decimal nullable

DiscountTotal decimal nullable

ShippingTotal decimal nullable

TaxesTotal decimal nullable

Total decimal nullable

Ref string nullable Optional idempotency reference.

OrderKey string nullable

PaymentSuccessRedirect string nullable

PaymentFailureRedirect string nullable

Response 200 OK

Ref string Unique cart reference to track the Medpaid session.

POST/plugin/cart/push/browserPush Cart (Browser)

Push a reimbursement cart from browser JavaScript. It authenticates with a browser cart push key instead of OnboardingKey and ExternalKey, and validates the request Origin. It creates a cart for a finalized, pending-payment order, or returns the existing Ref if a cart was already pushed for the same PlatformId. It does not accept a Ref and never updates an existing cart. Action ("reimburse") and Source are set by Medpaid.

Request Body application/json

BrowserKey string Your browser cart push key.

PlatformId string nullable Your platform's identifier for this order.

OrderData object Order details.

OrderId string nullable

OrderDate string nullable

CustomerId string nullable

Email string nullable

Phone string nullable

CurrencyCode string

BillingAddress object nullable

FirstName string nullable

LastName string nullable

Phone string nullable

Company string nullable

Address1 string nullable

Address2 string nullable

City string nullable

ProvinceCode string nullable

CountryCode string nullable

Zip string nullable

ShippingAddress object nullable

FirstName string nullable

LastName string nullable

Phone string nullable

Company string nullable

Address1 string nullable

Address2 string nullable

City string nullable

ProvinceCode string nullable

CountryCode string nullable

Zip string nullable

LineItems object[] Array of line items.

Name string nullable

LineId string nullable

ProductId string

VariantId string nullable

Quantity integer

Subtotal decimal

Total decimal

LineItemsTotal decimal nullable

DiscountTotal decimal nullable

ShippingTotal decimal nullable

TaxesTotal decimal nullable

Total decimal nullable

OrderKey string nullable

PaymentSuccessRedirect string nullable

PaymentFailureRedirect string nullable

Response 200 OK

Ref string Cart reference: new, or the existing one for this PlatformId.

Products

Retrieve the list of products in your Medpaid catalog along with their HSA/FSA eligibility status and LMN requirements.

GET/plugin/products/get-productsGet Products

Retrieve all products configured for your merchant account with their eligibility and approval status.

Parameters

NameInTypeRequiredDescription

OnboardingKeyquerystringYes

ExternalKeyquerystringYes

Response 200 OK

(array) object[] Array of product objects.

Id string (guid) Medpaid product ID.

Name string

VendorName string nullable

ClientName string

ExternalKey string

IsHsaApproved boolean

IsPublished boolean

RequiresLmn boolean

Type integer Product type: 0 Pending, 1 Supplements, 2 Equipment, 3 Proteins, 4 Gym Membership.

IsMedpaidIneligible boolean

Onboarding

Bulk-import products from your platform into Medpaid for eligibility review. Call import-products during initial setup and when your catalog changes.

POST/plugin/onboarding/import-productsImport Products

Bulk import products for a generic integration. Products are queued for eligibility review.

Request Body application/json

ExternalKey string

OnboardingKey string

Products object[]

Id string Your product ID.

Title string

Description string

Status string

Vendor string nullable

FeaturedMedia object nullable Product image.

Preview object nullable

Image object nullable

Url string nullable

AltText string nullable

OnlineStoreUrl string Product page URL.

Barcode string nullable

Response 200 OK

Ids string (guid)[] Medpaid product IDs for the imported products.

Orders

Retrieve the Medpaid status of an order you have pushed.

GET/plugin/orders/get-orderGet Order

Retrieve the status of an order in Medpaid, including its cart reference and payment transactions.

Parameters

NameInTypeRequiredDescription

PlatformIdquerystringYesThe PlatformId the order was pushed with.

ExternalKeyquerystringYes

OnboardingKeyquerystringYes

Response 200 OK

Ref string Cart reference for the order.

PlatformId string

OrderKey string nullable

Status string

Amount decimal

CurrencyCode string

ProcessorTransactionId string nullable Payment processor transaction ID.

PaidAt date-time nullable

Transactions object[]

Id string (guid)

TransactionId string

Amount decimal

Status string

Type string

CreatedAt date-time nullable

UpdatedAt date-time nullable

Refunds

Push refund requests and check refund status. Use the idempotency key to safely retry refund requests without duplication.

POST/plugin/refunds/pushPush Refund

Submit a refund request for a cart. Returns a refund ID and initial queue status.

Request Body application/json

OnboardingKey string

ExternalKey string

CartReference string The Ref returned when the cart was pushed.

ProcessorTransactionId string nullable Payment processor transaction ID.

RefundAmount decimal Amount to refund.

RefundCurrency string nullable Currency code (e.g. USD).

RefundType string Refund type: "Refund" or "PartialRefund".

IdempotencyKey string Unique key to prevent duplicate refunds on retry.

RefundCreatedAt date-time nullable When the refund was created on your platform.

Response 200 OK

Id string (guid) Medpaid refund ID.

RefundQueueStatus string Current status of the refund in the processing queue.

CreatedAt date-time

GET/plugin/refunds/get/{RefundId}Get Refund

Retrieve the status of a specific refund by its Medpaid ID.

Parameters

NameInTypeRequiredDescription

RefundIdpathstring (guid)Yes

OnboardingKeyquerystringYes

ExternalKeyquerystringYes

Response 200 OK

Id string (guid) Medpaid refund ID.

RefundQueueStatus string Current status of the refund in the processing queue.

RefundAmount decimal

RefundCurrency string

RefundType string nullable

DenialReason string nullable Why the refund was denied, if it was.

RefundedAt date-time nullable

CreatedAt date-time

UpdatedAt date-time

GET/plugin/refunds/get-by-idempotencyGet Refund by Idempotency Key

Look up a refund using the idempotency key you provided when pushing the refund. Useful for reconciliation after retries.

Parameters

NameInTypeRequiredDescription

OnboardingKeyquerystringYes

ExternalKeyquerystringYes

IdempotencyKeyquerystringYes

Response 200 OK

Id string (guid) Medpaid refund ID.

RefundQueueStatus string Current status of the refund in the processing queue.

RefundAmount decimal

RefundCurrency string

RefundType string nullable

DenialReason string nullable Why the refund was denied, if it was.

RefundedAt date-time nullable

CreatedAt date-time

UpdatedAt date-time

End Users

Query shopper-level data such as active LMN status. Use has-valid-lmn before showing an HSA/FSA CTA to customers who may already be qualified.

POST/plugin/endusers/has-valid-lmnHas Valid LMN

Check whether a specific shopper already has an active Letter of Medical Necessity. If HasValidLmn is true, the shopper can proceed directly to payment without a new assessment.

Request Body application/json

Xa string Your API authentication token.

Email string Shopper email address to look up.

ExternalKey string nullable

Id string (guid) nullable Medpaid user ID (alternative to email lookup).

Response 200 OK

HasValidLmn boolean true if the shopper has an active, non-expired LMN.

ExpiresOn date nullable LMN expiration date.

GrantedOn date nullable Date the LMN was issued.

PrimeProductName string nullable Name of the primary product the LMN was issued for.