Plugin API Reference

Medpaid Plugin API

All public endpoints for integrating HSA/FSA payments into your storefront. Endpoints are 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.

POST/plugin/clients/checkout-champ/configure-platformConfigure Platform (Checkout Champ)

Set connection settings for a Checkout Champ 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 CC store domain.

CartCallbackUri string nullable URL Medpaid calls after cart processing.

OrderConfirmationRedirectUri string nullable Redirect URL after order confirmation.

PluginApiUri string nullable Your plugin API endpoint URI.

PluginKey string nullable Plugin authentication key.

Response 200 OK

(boolean) boolean true if configuration saved.

POST/plugin/clients/checkout-champ/check-platformCheck Platform (Checkout Champ)

Verify all Checkout Champ platform settings are in place.

Request Body application/json

ExternalKey string Your merchant external key.

OnboardingKey string Your merchant onboarding key.

Response 200 OK

IsOk boolean true when configuration is complete.

HasStoreDomain boolean

HasPluginKey boolean

HasCartCallbackUri boolean

HasOrderConfirmationRedirectUri boolean

HasPluginApiUri boolean

Config object Current configuration values.

Errors string[] Validation errors if IsOk is false.

POST/plugin/clients/woocommerce/configure-platformConfigure Platform (WooCommerce)

Set connection settings for a WooCommerce integration. This is called automatically by the Medpaid WordPress plugin.

Request Body application/json

ExternalKey string Your merchant external key.

OnboardingKey string Your merchant onboarding key.

Website string WooCommerce store URL.

CartCallbackUri string URL Medpaid calls after cart processing.

OrderConfirmationRedirectUri string Redirect after order confirmation.

PluginApiUri string Your plugin API endpoint URI.

PluginKey string Plugin authentication key.

Response 200 OK

(boolean) boolean true if configuration saved.

POST/plugin/clients/woocommerce/check-platformCheck Platform (WooCommerce)

Verify all WooCommerce platform settings are in place.

Request Body application/json

ExternalKey string Your merchant external key.

OnboardingKey string Your merchant onboarding key.

Response 200 OK

IsOk boolean true when configuration is complete.

HasWebsite boolean

HasPluginKey boolean

HasCartCallbackUri boolean

HasOrderConfirmationRedirectUri boolean

HasPluginApiUri boolean

Config object Current configuration values.

Errors string[] Validation errors if IsOk is false.

GET/plugin/clients/woocommerce/get-clientGet Client (WooCommerce)

Retrieve merchant details for a WooCommerce integration.

Parameters

NameInTypeRequiredDescription

OnboardingKeyquerystringYes

ExternalKeyquerystringYes

Response 200 OK

Id string (guid)

Name string

ContactName string

ContactEmail string

ContactPhone string

Address string

IsActive boolean

GET/plugin/clients/woocommerce/get-client-statusGet Client Status (WooCommerce)

Check if a WooCommerce merchant account is active.

Parameters

NameInTypeRequiredDescription

OnboardingKeyquerystringYes

ExternalKeyquerystringYes

Response 200 OK

IsActive boolean

POST/plugin/clients/shopify/configure-platformConfigure Platform (Shopify)

Set connection settings for a Shopify integration.

Request Body application/json

Xa string Shopify app installation token.

ExternalKey string

AppName string nullable

StoreDomain string nullable

CartCallbackUri string nullable

OfflineAdminToken string nullable

OfflineStorefrontToken string nullable

Response 200 OK

(boolean) boolean

POST/plugin/clients/shopify/check-platformCheck Platform (Shopify)

Verify all Shopify platform settings are in place.

Request Body application/json

Xa string Shopify app installation token.

ExternalKey string

OnboardingKey string

Response 200 OK

IsOk boolean

HasDomain boolean

HasValidToken boolean

HasScopes boolean

Errors string[]

Cart

Push cart data from your storefront to Medpaid and retrieve cart status. The push endpoint initiates the HSA/FSA checkout or reimbursement flow and returns a CartReference used for tracking.

POST/plugin/cart/pushPush Cart

Submit a cart for generic plugin integrations. Returns a CartReference 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 Platform identifier.

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

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.

PaymentSuccessRedirect string nullable

PaymentFailureRedirect string nullable

Response 200 OK

Ref string Unique cart reference to track the Medpaid session.

POST/plugin/cart/checkout-champ/pushPush Cart (Checkout Champ)

Submit a cart from Checkout Champ. Use Action: "checkout" for in-checkout HSA/FSA payment or Action: "reimburse" for the Medpaid Reimburse post-purchase flow.

Request Body application/json

Action string "checkout" or "reimburse".

Source string Use "checkout-champ".

PlatformId string Your CC platform ID.

OnboardingKey string

ExternalKey string

OrderData object

OrderId string nullable

OrderDate string nullable

CustomerId string nullable

Email string nullable

Phone string nullable

CurrencyCode string

BillingAddress object nullable

ShippingAddress object nullable

LineItems object[]

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

OrderKey string nullable CC order key.

PaymentSuccessRedirect string nullable

PaymentFailureRedirect string nullable

IsSubscription boolean

Response 200 OK

CartReference string Unique reference for this cart. Redirect the customer to portal.medpaid.com/checkout/{CartReference}.

GET/plugin/cart/checkout-champ/get/{CartReference}Get Cart (Checkout Champ)

Retrieve the current status of a Checkout Champ cart by its reference.

Parameters

NameInTypeRequiredDescription

CartReferencepathstringYesThe CartReference returned from a push.

OnboardingKeyquerystringYes

ExternalKeyquerystringYes

Response 200 OK

CartReference string

Status string Current cart status (e.g. Pending, Completed, Failed).

Total decimal

Currency string

PaymentProcessor string nullable

ProcessorTransactionId string nullable

PaymentToken string nullable

Refunds object[]

Id string (guid)

RefundAmount decimal

RefundType string nullable

RefundQueueStatus string

RefundedAt date-time nullable

CreatedAt date-time nullable

UpdatedAt date-time nullable

CompletedAt date-time nullable

POST/plugin/cart/shopify/pushPush Cart (Shopify)

Submit a Shopify cart to Medpaid. Returns a CartReference for the initiated flow.

Request Body application/json

Action string

Source string Use "shopify".

OnboardingKey string

ExternalKey string

OrderData object Shopify order data matching the push cart schema.

Ref string nullable

PaymentSuccessRedirect string nullable

PaymentFailureRedirect string nullable

Response 200 OK

CartReference string

POST/plugin/cart/woocommerce/pushPush Cart (WooCommerce)

Submit a WooCommerce cart to Medpaid. Called automatically by the WordPress plugin when a customer selects Medpaid at checkout.

Request Body application/json

Action string

Source string Use "woocommerce".

OnboardingKey string

ExternalKey string

OrderData object WooCommerce order data matching the push cart schema.

Ref string nullable

PaymentSuccessRedirect string nullable

PaymentFailureRedirect string nullable

Response 200 OK

CartReference string

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

IsHsaApproved boolean

IsPublished boolean

RequiresLmn boolean

GET/plugin/products/checkout-champ/get-productsGet Products (Checkout Champ)

Retrieve products for a Checkout Champ integration.

Parameters

NameInTypeRequiredDescription

OnboardingKeyquerystringYes

ExternalKeyquerystringYes

Response 200 OK

(array) object[] Array of product objects with eligibility data.

GET/plugin/products/woocommerce/get-productsGet Products (WooCommerce)

Retrieve products for a WooCommerce integration.

Parameters

NameInTypeRequiredDescription

OnboardingKeyquerystringYes

ExternalKeyquerystringYes

Response 200 OK

(array) object[] Array of product objects with eligibility data.

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

OnboardingKey string

ExternalKey string

Products object[]

ExternalId string Your product ID.

Title string

Description string nullable

Vendor string nullable

ProductUrl string nullable

ImageUrl string nullable

Barcode string nullable

Response 200 OK

Imported integer Number of products imported.

Skipped integer Number of products skipped (already exist).

POST/plugin/onboarding/checkout-champ/import-productsImport Products (Checkout Champ)

Bulk import products from Checkout Champ into Medpaid.

Request Body application/json

OnboardingKey string

ExternalKey string

Products object[] Array of CC product objects with ExternalId, Title, Description, Vendor, URLs, and Barcode.

Response 200 OK

Imported integer

Skipped integer

POST/plugin/onboarding/shopify/import-productsImport Products (Shopify)

Bulk import products from Shopify into Medpaid.

Request Body application/json

OnboardingKey string

ExternalKey string

Products object[] Array of Shopify product objects.

Response 200 OK

Imported integer

Skipped integer

POST/plugin/onboarding/shopify/update-productsUpdate Products (Shopify)

Update existing products in Medpaid from Shopify when catalog details change.

Request Body application/json

OnboardingKey string

ExternalKey string

Products object[] Array of updated Shopify product objects.

Response 200 OK

Updated integer

POST/plugin/onboarding/woocommerce/import-productsImport Products (WooCommerce)

Bulk import WooCommerce products into Medpaid. Called automatically by the WordPress plugin.

Request Body application/json

OnboardingKey string

ExternalKey string

Products object[] Array of WooCommerce product objects.

Response 200 OK

Imported integer

Skipped integer

Orders

Manage recurring orders and retrieve order status. Recurring endpoints are Checkout Champ-specific; order status retrieval is available for WooCommerce.

POST/plugin/orders/checkout-champ/recurringCreate Recurring Order (Checkout Champ)

Register a new recurring/subscription order in Medpaid for a Checkout Champ customer.

Request Body application/json

OnboardingKey string

ExternalKey string

OrderId string CC order ID.

CustomerId string

ProductId string

SubscriptionId string

Amount decimal

CurrencyCode string

Email string

Response 200 OK

RecurringOrderId string (guid)

Status string

POST/plugin/orders/checkout-champ/recurring/cancelCancel Recurring Order (Checkout Champ)

Cancel an active recurring/subscription order in Medpaid.

Request Body application/json

OnboardingKey string

ExternalKey string

SubscriptionId string The CC subscription ID to cancel.

Response 200 OK

Cancelled boolean

GET/plugin/orders/woocommerce/get-orderGet Order (WooCommerce)

Retrieve the status of a WooCommerce order in Medpaid.

Parameters

NameInTypeRequiredDescription

OnboardingKeyquerystringYes

ExternalKeyquerystringYes

OrderIdquerystringYesWooCommerce order ID.

Response 200 OK

OrderId string

Status string

TransactionId string nullable

Amount decimal

ProcessedAt 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/checkout-champ/pushPush Refund (Checkout Champ)

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

Request Body application/json

OnboardingKey string

ExternalKey string

CartReference string nullable The CartReference from the original push.

ProcessorTransactionId string nullable Payment processor transaction ID.

RefundAmount decimal Amount to refund.

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

RefundType string Refund type identifier.

IdempotencyKey string nullable Unique key to prevent duplicate refunds on retry.

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/checkout-champ/get/{RefundId}Get Refund (Checkout Champ)

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

Parameters

NameInTypeRequiredDescription

RefundIdpathstring (guid)Yes

OnboardingKeyquerystringYes

ExternalKeyquerystringYes

Response 200 OK

Id string (guid)

RefundAmount decimal

RefundType string nullable

RefundQueueStatus string

RefundedAt date-time nullable

GET/plugin/refunds/checkout-champ/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)

RefundAmount decimal

RefundType string nullable

RefundQueueStatus string

RefundedAt date-time nullable

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.