feat(connector): [facilitapay] fix refunds, add webhook and void support

[pixincreate]

Type of Change

• Bugfix
• New feature
• Enhancement
• Refactoring
• Dependency updates
• Documentation
• CI/CD

Description

This Facilitapay PR introudces 2 new features and a bug fix which is described below:

• Add support for webhooks
  • Source verification supported
  • Payments
  • Refunds (It is only supported for pix payment when a third party makes a transaction instead of the actual user). The payload for both payments and refunds is exactly the same with 0 difference. It is kind of use less to have webhook for support for Refunds
• Add support for voiding payments
  • At Facilita, refund means voiding a payment
  • This is a GET call with no request body
• Fix a bug in Refunds (It was not testable until now)
  • At Facilita, refund_received_transaction means refunding a payment
  • This is a GET call with no request body
  • Does not support partial refunds

Additional Changes

• This PR modifies the API contract
• This PR modifies the database schema
• This PR modifies application configuration/environment variables

Motivation and Context

closes #8777

How did you test it?

Partial refunds

curl --location 'http://localhost:8080/refunds' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: dev_FwRHVH9xL5cvYOsONW8YzIphnGhIibnEy9tCWuNCpDLwSnzR4Ilogl6sia26pcND' \
--data '{
    "payment_id": "pay_le5uOFoizxZPXFHPQuK1",
    "amount": 1000,
    "reason": "Customer returned product",
    "refund_type": "instant",
    "metadata": {
        "udf1": "value1",
        "new_customer": "true",
        "login_date": "2019-09-10T10:11:12Z"
    }
}'

{
    "error": {
        "type": "invalid_request",
        "message": "Payment method type not supported",
        "code": "IR_19",
        "reason": "Partial refund not supported by Facilitapay is not supported by Facilitapay"
    }
}

Refunds

curl --location 'http://localhost:8080/refunds' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: dev_FwRHVH9xL5cvYOsONW8YzIphnGhIibnEy9tCWuNCpDLwSnzR4Ilogl6sia26pcND' \
--data '{
    "payment_id": "pay_le5uOFoizxZPXFHPQuK1",
    "amount": 10400,
    "reason": "Customer returned product",
    "refund_type": "instant",
    "metadata": {
        "udf1": "value1",
        "new_customer": "true",
        "login_date": "2019-09-10T10:11:12Z"
    }
}'

{
    "refund_id": "ref_bEMav88LA7llD0KS6Twk",
    "payment_id": "pay_le5uOFoizxZPXFHPQuK1",
    "amount": 10400,
    "currency": "BRL",
    "status": "succeeded",
    "reason": "Customer returned product",
    "metadata": {
        "udf1": "value1",
        "new_customer": "true",
        "login_date": "2019-09-10T10:11:12Z"
    },
    "error_message": null,
    "error_code": null,
    "unified_code": null,
    "unified_message": null,
    "created_at": "2025-07-28T18:43:11.748Z",
    "updated_at": "2025-07-28T18:43:12.819Z",
    "connector": "facilitapay",
    "profile_id": "pro_ODZKRkH2uJIfAPClUy8B",
    "merchant_connector_id": "mca_A4Kpc6NUvBsN8RGvvJsm",
    "split_refunds": null,
    "issuer_error_code": null,
    "issuer_error_message": null
}

will introduce cypress in a separate pr

Void

curl --location 'https://pix-mbp.orthrus-monster.ts.net/payments/pay_XIq2h8snAnSp425StpHM/cancel' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: dev_FwRHVH9xL5cvYOsONW8YzIphnGhIibnEy9tCWuNCpDLwSnzR4Ilogl6sia26pcND' \
--data '{"cancellation_reason":"requested_by_customer"}'

{
    "payment_id": "pay_XIq2h8snAnSp425StpHM",
    "merchant_id": "postman_merchant_GHAction_1753728068",
    "status": "cancelled",
    "amount": 10400,
    "net_amount": 10400,
    "shipping_cost": null,
    "amount_capturable": 0,
    "amount_received": null,
    "connector": null,
    "client_secret": "pay_XIq2h8snAnSp425StpHM_secret_Za7LqUCCvag8LBMCyYBp",
    "created": "2025-07-28T18:44:39.081Z",
    "currency": "BRL",
    "customer_id": null,
    "customer": {
        "id": null,
        "name": null,
        "email": "[email protected]",
        "phone": "999999999",
        "phone_country_code": "+1"
    },
    "description": "Its my first payment request",
    "refunds": null,
    "disputes": null,
    "mandate_id": null,
    "mandate_data": null,
    "setup_future_usage": null,
    "off_session": null,
    "capture_on": null,
    "capture_method": "automatic",
    "payment_method": null,
    "payment_method_data": null,
    "payment_token": null,
    "shipping": {
        "address": {
            "city": "San Fransico",
            "country": "BR",
            "line1": "1467",
            "line2": "Harrison Street",
            "line3": "Harrison Street",
            "zip": "94122",
            "state": "California",
            "first_name": "PiX",
            "last_name": null
        },
        "phone": null,
        "email": null
    },
    "billing": {
        "address": {
            "city": "San Fransico",
            "country": "BR",
            "line1": "1467",
            "line2": "Harrison Street",
            "line3": "Harrison Street",
            "zip": "94122",
            "state": "California",
            "first_name": "PiX",
            "last_name": "THE"
        },
        "phone": null,
        "email": null
    },
    "order_details": null,
    "email": null,
    "name": null,
    "phone": null,
    "return_url": "https://duck.com/",
    "authentication_type": "three_ds",
    "statement_descriptor_name": "joseph",
    "statement_descriptor_suffix": "JS",
    "next_action": null,
    "cancellation_reason": "requested_by_customer",
    "error_code": null,
    "error_message": null,
    "unified_code": null,
    "unified_message": null,
    "payment_experience": null,
    "payment_method_type": null,
    "connector_label": null,
    "business_country": null,
    "business_label": "default",
    "business_sub_label": null,
    "allowed_payment_method_types": null,
    "ephemeral_key": null,
    "manual_retry_allowed": false,
    "connector_transaction_id": null,
    "frm_message": null,
    "metadata": {
        "udf1": "value1",
        "login_date": "2019-09-10T10:11:12Z",
        "new_customer": "true"
    },
    "connector_metadata": null,
    "feature_metadata": null,
    "reference_id": null,
    "payment_link": null,
    "profile_id": "pro_ODZKRkH2uJIfAPClUy8B",
    "surcharge_details": null,
    "attempt_count": 1,
    "merchant_decision": null,
    "merchant_connector_id": null,
    "incremental_authorization_allowed": null,
    "authorization_count": null,
    "incremental_authorizations": null,
    "external_authentication_details": null,
    "external_3ds_authentication_attempted": false,
    "expires_on": "2025-07-28T18:59:39.081Z",
    "fingerprint": null,
    "browser_info": {
        "language": "en-GB",
        "time_zone": -330,
        "ip_address": "208.127.127.193",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36 Edg/126.0.0.0",
        "color_depth": 24,
        "java_enabled": true,
        "screen_width": 1280,
        "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
        "screen_height": 720,
        "java_script_enabled": true
    },
    "payment_method_id": null,
    "payment_method_status": null,
    "updated": "2025-07-28T18:44:43.912Z",
    "split_payments": null,
    "frm_metadata": null,
    "extended_authorization_applied": null,
    "capture_before": null,
    "merchant_order_reference_id": null,
    "order_tax_amount": null,
    "connector_mandate_id": null,
    "card_discovery": null,
    "force_3ds_challenge": false,
    "force_3ds_challenge_trigger": false,
    "issuer_error_code": null,
    "issuer_error_message": null,
    "is_iframe_redirection_enabled": null,
    "whole_connector_response": null
}

Webhook Setup

curl --location 'https://sandbox-api.facilitapay.com/api/v1/enable_webhooks' \
--header 'Authorization: Bearer <jwt_token>' \
--header 'Content-Type: application/json' \
--data '{
    "url": "https://baseUrl/webhooks/:merchant_id/facilitapay"
    
}'

{
    "data": {
        "secret": "1111"
    }
}

Payment Webhook

Source verification:

Incoming Webhook Logs:

Outgoing Webhook:

Refund Webhook

The payment_refunded webhook is only sent for a very specific use case - when a pix payment is automatically refunded because it was paid from a third-party account. for regular api-initiated refunds, facilitapay sends the same identified and wire_created webhooks as for payments, making it impossible to distinguish between payment and refund webhooks.

Checklist

• I formatted the code cargo +nightly fmt --all
• I addressed lints thrown by just clippy && just clippy_v2
• I reviewed the submitted code
• I added unit tests for my changes where possible

[semanticdiff-com]

Review changes with  

Changed Files

File	Status
crates/hyperswitch_connectors/src/connectors/facilitapay/transformers.rs	8% smaller
crates/hyperswitch_connectors/src/connectors/facilitapay/responses.rs	3% smaller
crates/hyperswitch_connectors/src/connectors/facilitapay.rs	3% smaller
crates/connector_configs/toml/development.toml	Unsupported file format
crates/connector_configs/toml/production.toml	Unsupported file format
crates/connector_configs/toml/sandbox.toml	Unsupported file format
crates/hyperswitch_connectors/src/connectors/facilitapay/requests.rs	0% smaller