Huch API Documentation

Appearance

Get Started ​

For more information about our API endpoints and authentication, please refer to our Authentication / REST API Endpoints Guide.

Endpoint POST ​

http
/api/payout/create

Headers ​

http
'Content-Type: application/json'
'Authorization: Bearer {access-token}'

Payout Initiation ​

This endpoint is used for initiating payouts. It accepts a payload with various parameters for payout configuration.

Request Parameters ​

ParameterTypeRequiredDescription
currencyStringYesISO 4217 currency code. only (EUR, GBP) are supported
amountIntegerYesAmount in cents (e.g., 1000 for 10 EUR).
Min: 10000 | Max: 1000000
merchant_transaction_idStringYesUnique transaction ID for merchant tracking.
Max 150 chars
customer_emailStringYesCustomer's email. Used for identification and notifications
payout_infoObjectYesObject containing bank account details for the payout. See Payout Info Object below
customer_phone_numberStringNoOptional customer phone number
customer_billing_infoObjectYesObject containing customer's billing details like name, address, etc. See Customer Billing Info Object below
labelStringYesDescription of the transaction. Max 25 chars
webhook_urlStringYesURL endpoint that receives payout notifications via POST requests with JSON payloads. Must be a publicly accessible HTTPS URL that can accept webhook POST requests

Payout Info Object ​

FieldTypeRequired depending on currencyDescription
bank_nameStringYesName of customer's bank
customer_ibanStringYes (EUR)IBAN of customer's bank account
customer_bicStringYes (EUR)BIC of customer's bank
account_numberStringYes (GBP)Account number of customer's bank
sort_codeStringYes (GBP)Sort code of customer's bank

Customer Billing Info Object ​

FieldTypeRequiredDescription
customer_first_nameStringYesCustomer's first name
customer_last_nameStringYesCustomer's last name
customer_country_alpha_2StringYesISO 2-letter country code (e.g., FR)
customer_cityStringYesCustomer's city
customer_street_addressStringYesCustomer's street address
customer_postcodeStringYesCustomer's postal code

Example Request (SEPA) ​

json
{
  "merchant_id": "999d2142-629c-4f32-b7ec-7ec5e7ee5f2f",
  "merchant_transaction_id": "your-payment-id-4546-456",
  "amount": 14800,
  "currency": "EUR",
  "customer_email": "email123@test.com",
  "customer_ip": "192.168.1.1",
  "customer_phone_number": "+1 647-244-2736",
  "payout_info": {
    "customer_iban": "FR5010096000405167372929B42",
    "customer_bic": "AIBKIE2D",
    "bank_name": "CIH",
    "bank_country": "FR"
  },
  "customer_billing_info": {
    "customer_first_name": "John",
    "customer_last_name": "Doe",
    "customer_country_alpha_2": "FR",
    "customer_city": "Paris",
    "customer_street_address": "24 rue de la paix",
    "customer_postcode": "75000"
  },
  "label": "Withdrawal of Win 0001",
  "webhook_url": "https://your-website.com/webhook"
}

Successful Response (200 OK) ​

json
{
  "status": 1,
  "message": "success",
  "data": {
    "payout_id": "9dbefc91-b6ab-4610-a676-f7b469f9b638",
    "payment_flow": "payout",
    "amount": 14800,
    "currency": "EUR",
    "label": "Withdrawal of Win 0001",
    "status_description": "Transaction under processing",
    "status": "PENDING",
    "merchant_id": "999d2142-629c-4f32-b7ec-7ec5e7ee5f2f",
    "merchant_transaction_id": "your-payment-id-4546-456",
    "environment": "SANDBOX"
  }
}

Example Request (FPS) ​

json
{ 
  "merchant_id": "999d2142-629c-4f32-b7ec-7ec5e7ee5f2f",
  "merchant_transaction_id": "your-payment-id-4546-456",
  "amount": 14800,
  "currency": "GBP",
  "customer_email": "email11@test.com",
  "customer_ip": "192.168.1.1",
  "customer_phone_number": "+1 647-244-2736",
  "payout_info": {
    "account_number": "31926819",
    "sort_code": "040026",
    "bank_name": "Revolut"
  },
  "customer_billing_info": {
    "customer_first_name": "John",
    "customer_last_name": "Doe",
    "customer_country_alpha_2": "FR",
    "customer_city": "Paris",
    "customer_street_address": "24 rue de la paix",
    "customer_postcode": "75000"
  },
  "label": "Withdrawal of Win 0001",
  "webhook_url": "https://your-website.com/webhook"
}

Successful Response (200 OK) ​

json
{
  "status": 1,
  "message": "success",
  "data": {
    "payout_id": "9dbefc91-b6ab-4610-a676-f7b469f9b638",
    "payment_flow": "payout",
    "amount": 14800,
    "currency": "GBP",
    "label": "Withdrawal of Win 0001",
    "status_description": "Transaction under processing",
    "status": "PENDING",
    "merchant_id": "999d2142-629c-4f32-b7ec-7ec5e7ee5f2f",
    "merchant_transaction_id": "your-payment-id-4546-456",
    "environment": "SANDBOX"
  }
}

HTTP Code sample for SEPA ​

1curl --location --request POST 'https://api-gateway-sandbox.huch.tech/api/payout/create' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer ' \
4--data-raw '{
5  "merchant_id": "999d2142-629c-4f32-b7ec-7ec5e7ee5f2f",
6  "merchant_transaction_id": "dfdb941c-7235-4f32-866a-265fb429e6e1",
7  "amount": 14800,
8  "currency": "EUR",
9  "customer_email": "email123@test.com",
10  "customer_ip": "192.168.1.1",
11  "customer_phone_number": "+1 647-244-2736",
12  "payout_info": {
13    "customer_iban": "FR5010096000405167372929B42",
14    "customer_bic": "AIBKIE2D",
15    "bank_name": "CIH",
16    "bank_country": "FR"
17  },
18  "customer_billing_info": {
19    "customer_first_name": "John",
20    "customer_last_name": "Doe",
21    "customer_country_alpha_2": "FR",
22    "customer_city": "Paris",
23    "customer_street_address": "24 rue de la paix",
24    "customer_postcode": "75000"
25  },
26  "label": "Withdrawal of Win 0001",
27  "webhook_url": "https://your-website.com/webhook"
28}'

HTTP Code sample for FPS ​

1curl --location --request POST 'https://api-gateway-sandbox.huch.tech/api/payout/create' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer ' \
4--data-raw '{
5  "merchant_id": "999d2142-629c-4f32-b7ec-7ec5e7ee5f2f",
6  "merchant_transaction_id": "dfdb941c-7235-4f32-866a-265fb429e6e1",
7  "amount": 10000,
8  "currency": "GBP",
9  "customer_email": "email321@test.com",
10  "customer_ip": "192.168.1.1",
11  "customer_phone_number": "+1 647-244-2736",
12  "payout_info": {
13    "account_number": "00057085",
14    "sort_code" : "041356",
15    "bank_name": "Revolut"
16  },
17   "customer_billing_info": {
18    "customer_first_name": "John",
19    "customer_last_name": "Doe",
20    "customer_country_alpha_2": "FR",
21    "customer_city": "Paris",
22    "customer_street_address": "24 rue de la paix",
23    "customer_postcode": "75000"
24  },
25  "label": "Withdrawal of Win 0001",
26  "webhook_url": "https://your-website.com/webhook"
27}'

Important Notes ​

  1. All amounts must be provided in cents (e.g., 14800 = 148.00 EUR)
  2. The webhook URL must be publicly accessible and able to receive POST requests
  3. For SEPA payments, both IBAN and BIC are required
  4. For FPS payments (GBP), account number and sort code are required
  5. The label field is limited to 25 characters
  6. The merchant_transaction_id must be unique for each transaction

Errors ​

Error codeMeaning
400Invalid or missing information
403Action not allowed

See the Errors & Error Codes page for the shared error format, the X-Request-ID correlation header, and retry guidance.