HUCH

Supports in this guide: Payments

Provider website: huch.tech

What you need to do for start processing transactions (brief summary)

1. Choose account type
2. Get your credentials (from HUCH)
3. Connect in Dashboard
4. Send an API request

Choose account type

HUCH can be connected in different ways (depending on your needs):

• If you do payments -> choose Provider account

If you're not sure which one to use, confirm with your Corefy account manager.

Prerequisites: get from HUCH

Get the following values for your HUCH project/account:

• Client ID -> Corefy field client_id -> example: 9b1f6c2e-4d7a-4e1b-8c3f-2a5d7e9f1b34 -> where to find: HUCH backoffice / issued by HUCH manager. Used to obtain the API access token and to verify HUCH callback signatures.
• Client Secret -> Corefy field client_secret -> example: cs_7f3a9c21b8e44d0a -> where to find: HUCH backoffice / issued by HUCH manager. Used together with the Client ID to obtain the API access token.
• Merchant ID -> Corefy field merchant_id -> example: 4f8a2c1e-9b3d-4e7a-8c5f-1d2e3a4b5c6d -> where to find: HUCH backoffice / issued by HUCH manager. Identifies your HUCH merchant account.
• API URL (optional) -> Corefy field api_url -> overrides the default HUCH API host -> leave empty unless your account manager tells you otherwise.

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "8e3dbbb0-17af-4c9a-bedb-93bdac6900a2",
      "service": "openbanking_eur_hpp",
      "currency": "EUR",
      "amount": 100,
      "customer": {
        "reference_id": "cus_123",
        "email": "johnsmith@gmail.com"
      }
    }
  }
}

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "6795502c-e27d-4d07-85e0-93245aab9a3f",
      "service": "openbanking_eur_hpp",
      "currency": "EUR",
      "amount": 100,
      "description": "Order 12345",
      "customer": {
        "reference_id": "cus_123",
        "email": "johnsmith@gmail.com",
        "name": "John Smith",
        "phone": "+34612345678",
        "address": {
          "country": "ES",
          "city": "Madrid",
          "street": "Calle Mayor 1",
          "post_code": "28013"
        }
      }
    }
  }
}

Additional info

1. Callbacks are set up automatically. Corefy sends its callback URL to HUCH with every payment, so there is nothing to configure in the HUCH Merchant Dashboard. Callback signatures are verified with your Client ID, and Corefy also checks the payment status with HUCH on its own.

2. Bank-specific services. With a bank-specific service, HUCH shows the customer a short confirmation page with the chosen bank and then redirects them to that bank. With openbanking_eur_hpp, the customer picks the bank on the HUCH payment page.

3. Pending payments. A payment stays pending while the bank is still processing it (HUCH status PROCESSING). If the bank never sends a final status, the payment stays pending - contact HUCH support to resolve it.

FAQ / Troubleshooting

• Invalid credentials / auth error -> verify Client ID and Client Secret for the chosen environment (sandbox credentials require Test mode enabled)
• INVALID_DETAILS / "Customer email is required" -> send customer.email in the request or set the customer_email constant for the route
• INVALID_DETAILS / "[email]: This value is not a valid email address." -> customer.email in the request has an invalid format; it is checked even when the customer_email constant is set
• Currency or service is not supported -> HUCH processes EUR only; confirm the services enabled for your account with your Corefy account manager
• Not sure which account type to use? -> ask your Corefy account manager