Facilitapay

Connect Facilitapay through Hyperswitch.

Facilitapay supports Pix bank transfers in the sandbox, with refunds and automatic capture. Payment webhook processing is declared.

To connect Facilitapay to your Hyperswitch account, follow Activate a connector on Hyperswitch, then return here for what Facilitapay supports.

Status and capabilities

Integration status: sandbox

Category: payment gateway

Webhook flows: payments

Payment method	Type	Mandates	Refunds	Capture methods	Countries	Currencies
bank transfer	Pix	not supported	supported	automatic, sequential automatic	BRA	BRL

The table says refunds are supported, which is true only for the full amount. A refund whose amount differs from the payment amount is rejected before any request is sent, with "Partial refund not supported by Facilitapay". See build_request(). Refund the whole payment or not at all.

Authentication

Activation needs three values. [facilitapay.connector_auth.BodyKey] supplies the first two labels, and the connector metadata supplies the third:

Field	Required
Username	yes
Password	yes
Merchant Account Number	yes, from facilitapay.metadata.destination_account_number

All three are required, so activation will not complete with the username alone.

Before you start

1. Obtain your Username, Password and Merchant Account Number from Facilitapay.

2. Sign in to the Hyperswitch control center and open Facilitapay, which is offered in the connector list.

3. Enter all three during connector activation.

4. Read the webhook warning below before you rely on callbacks.

Webhooks

Facilitapay callbacks are weakly authenticated. Do not treat one as proof of payment.

Verification compares a secret carried in the callback body against your configured value as plain text, at verify_webhook_source(). Nothing is computed over the payload, so the check says only that the sender knew the secret, and the source comment describes it as "a simple 4-digit secret".

Two things make that weaker still. When no webhook secret is configured the comparison falls back to the literal string default_secret (facilitapay.rs:836), rather than failing closed, so a connector with no secret set accepts any callback carrying that value.

And the default path leaves it unset. No connector_webhook_details block exists for Facilitapay in any connector configuration, so the control center offers no field for it. The value can still be set through the connector-account API, as merchant_secret in connector_webhook_details, but a connector configured through the dashboard alone will not have one.

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

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

Wire value	Effect
exchange_created	Payment is processing
identified	Payment succeeds
payment_approved	Payment succeeds
wire_created	Payment succeeds
payment_expired	Payment fails
payment_failed	Payment fails
payment_refunded	Refund succeeds
wire_waiting_correction	Payment needs action

The eight wire values come from FacilitapayWebhookEventType; their effects come from get_webhook_event_type(). The match is exhaustive, so every declared value maps to an outcome and there is no unknown fallback.

Source reference

Authentication and webhook behavior on this page is tied to Hyperswitch 502bfe8ddbe6a9a9619dc4e0b88900a780c2aac5. See Facilitapay connector source and Facilitapay transformers.