Huch API Documentation

Appearance

Integration FAQ ​

This page consolidates common integration questions for Open Banking Payin (deposits) and Payouts (withdrawals).

1) Can I initiate test deposit and withdrawal? ​

Payin (Sandbox) ​

You can initiate test deposits using the sandbox.

Test bank

  • Country: Germany
  • Bank: Deutsche Postbank Sandbox
  • IBAN: DE17215730140403340300

PSU IDs (for status simulation)

  • 6154033403 → PROCESSING
  • 6154033411 → FAILED

Simulate PAID status (Dashboard) ​

To simulate a PAID status:

  1. Create a new payment
  2. Do not select a bank
  3. Mark the transaction as PAID in the dashboard

Payout (Sandbox) ​

You can test payouts in sandbox:

  • We credit your sandbox balance
  • You can initiate a payout to a sandbox bank

2) How can I receive callbacks (webhook) notifications? ​

Payin (Open Banking) ​

You must subscribe to webhook notifications. You will receive:

  • Final statuses
  • PROCESSING status (for payin)

Docs:

  • /open-banking/notification/subscription-to-webhook-events

Note: Payin and Payout webhook payloads/structures are different.

Payout (Withdrawals) ​

For payouts, the webhook URL is provided per request (not via subscription):

  • Add webhook_url in each payout initiation request

Docs:

  • /payouts/payout-initiation

webhook_url requirements:

  • Publicly accessible HTTPS endpoint
  • Accepts POST requests
  • Accepts JSON payloads
  • Responds quickly with 200 OK

3) Do webhook callbacks have signatures? ​

Yes. Webhook signature verification is supported (HMAC-SHA256).
Use signature verification to ensure:

  • Requests originate from HUCH
  • Payload is not tampered with

(Internal reference: signature page in Confluence.)

4) Do you support IP whitelisting? ​

Yes. Please share your live IP addresses so we can whitelist them.

Also whitelist HUCH production IPs:

  • Payin: 52.47.150.158
  • Withdrawal: 51.44.195.207

5) Can you implement request signature verification (HMAC-SHA256)? ​

Yes. (See the signature documentation referenced in the internal Confluence page.)

6) Payin: What customer details are required? ​

Required

  • A real customer_email

Recommended

  • Other customer details (useful in case of disputes)

7) Payouts: What customer details are required? ​

All required customer details are important and must be provided.

8) Payouts: customer_bic and sort_code ​

  • customer_bic is required
  • sort_code is mandatory for the UK (GBP)

9) Do you have a list of sort codes for the UK? ​

No. We don’t provide a sort code list.

10) Do we have REJECTED status for payin? ​

“Rejected” is not a standalone payment state to rely on as a separate flow.

Possible failed payment statuses include:

  • FAILED
  • AUTH_FAILED
  • EXECUTE_FAILED
  • REJECTED
  • CANCELLED

A transaction can move from PROCESSING to a failed status later.

11) Where do we read the transaction status? ​

Use payment_status.

Do not use status (deprecated).

12) Which final status should we trust? ​

PROCESSING ​

Customer’s bank is processing the transaction (not complete). Some banks don’t send final statuses; in that case, check settlement on your bank account.

Customer’s bank confirmed the transfer was initiated.

  • SEPA Instant → usually immediate
  • SEPA Normal → may settle later

Rarely, banks can block transfers for AML reasons — you may still want to confirm settlement before delivering a product/service.

This is the best status to confirm funds landed on the merchant bank account. It is sent when we receive a confirmation from the merchant bank.

FORCE_PAID (Fast Approval) ​

Fast Approval can be enabled on merchant request to avoid long PROCESSING delays.

How it works:

  1. When a bank indicates the transaction is technically accepted, we send FORCE_PAID
  2. Merchant may treat it as completed and credit the customer immediately

Risk: the bank may still reject later (rare) → merchant bears the financial risk.

This is commonly used to reduce delays in markets where banks are slower to confirm (e.g., NL).

Fast Approval can be enabled/disabled per country and per bank.

13) What does the Hosted Payment Page (HPP) URL look like? ​

The url returned in the payment creation response is the Hosted Payment Page (HPP) you redirect the customer to.

EnvironmentHosted Payment Page (HPP)
Sandboxhttps://sandbox.huch.tech/pay/{payment_id}
Productionhttps://pay.huchpay.com/pay/{payment_id}

Always redirect using the url value from the API response rather than building the URL yourself.

14) What is bank_ref? ​

bank_ref is the bank reference used for reconciliation (e.g., with Gurupay). It helps:

  • reconcile transactions with the bank
  • provide accurate PAID_RECEIVED
  • support merchant reconciliation processes

15) Can we use both deposit and withdrawal for AT? ​

Yes, both are supported.

16) Are Hosted Checkout (deposit) and Request Payout (withdrawal) bank transfer methods? ​

Yes, both are bank transfer methods.

Common naming used by partners:

  • Deposit: Bank transfer deposit (or Instant bank transfer)
  • Withdrawal: Bank transfer withdrawal (or SEPA withdrawal)

17) Supported processing currencies ​

Deposits (C2B) ​

The currency must match the supported C2B currency:

  • EUR → EUR
  • NOK → NOK
  • SEK → SEK
  • DKK → DKK
  • GBP → GBP
  • PLN → PLN

Withdrawals ​

Supported currencies:

  • EUR
  • GBP EOF