Bitpay

Accept cryptocurrency payments through Bitpay.

Bitpay provides a cryptocurrency checkout route with automatic capture. Payment webhooks can move an invoice through processing, success, or failure outcomes. Review the refund caveat below before enabling this connector.

Status and capabilities

Integration status: sandbox

Category: alternative payment method

Webhook flows: payments

Payment method	Type	Mandates	Refunds	Capture methods	Countries	Currencies
crypto	Crypto	not supported	supported	automatic	30	8

The feature matrix declares refunds, but the refund execute request returns NotImplemented. Do not rely on refunds until the declaration gap is resolved.

Authentication

Supply API Key, the label shown in the Hyperswitch control center. Bitpay carries it as a token value rather than an authorization header: the authorize request serializes it into the request body as token, and payment sync appends it to the URL as ?token=.... The build_headers() override sends only the content type and X-Accept-Version: 2.0.0, and never calls get_auth_header(), so no Authorization header is sent. See the body field in BitpayPaymentsRequest and the sync URL in get_url(). BitpayAuthType::try_from() maps the dashboard field.

Because the key travels in a query string on sync, it can reach proxy and server logs that would not record a header. Treat it as you would any other secret in a URL.

Before you start

1. Sign in to the Hyperswitch control center.

2. Enter API Key during connector activation.

3. Leave Source verification key blank. Bitpay uses the default no-op verification algorithm, so a value here adds no signature verification. See the webhook warning below before you rely on callbacks at all.

To connect Bitpay to your Hyperswitch account, follow Activate a connector on Hyperswitch, then return here for Bitpay-specific behavior.

Webhooks

Bitpay callbacks are not authenticated. Do not treat one as proof of payment. The connector verifies no signature: the default get_webhook_source_verification_algorithm() selects NoAlgorithm, whose verify_signature() always returns true, so every callback that reaches the endpoint is accepted. Anyone who can reach it can post invoice_confirmed or invoice_completed and drive a payment to succeeded.

Confirm with payment sync before you release goods or mark an order paid, and treat the callback only as a signal to go and check.

The events below are what the connector does with a callback once it accepts it.

The connector handles 8 event wire values.

Wire value	Effect
invoice_paidInFull	Payment is processing
invoice_confirmed	Payment succeeds
invoice_completed	Payment succeeds
invoice_expired	No payment update is applied
invoice_failedToConfirm	No payment update is applied
invoice_declined	Payment fails
invoice_refundComplete	No payment update is applied
invoice_manuallyNotified	No payment update is applied

Any other event value uses the unknown fallback and applies no payment update. The 8 wire values and fallback come from WebhookEventType; their effects come from get_webhook_event_type().

Source reference

Authentication and webhook behavior on this page follows Bitpay connector source and Bitpay transformers.