Getting Started

Welcome to the Huch API documentation. This guide will help you get started with using our RESTful API to integrate Huch's powerful features into your applications.

Prerequisites

Before you begin, make sure you have:

1. API credentials (client ID and client secret)
2. A solid understanding of RESTful APIs and HTTP methods
3. If you don't have API credentials yet, contact us to get started
4. Having a valid merchant ID

Testing the API

1. Firstly, authenticate yourself to get the access token.
   • Click on the "Authentication" button above in navbar.
   • Fill in the client ID and client secret and the merchant ID.
   • Click on the "Authenticate".
   • An access token will be saved in your browser's local storage.
   • Now the access token will be used for all the endpoints in the documentation automatically.
2. Then you can start testing the endpoints.
   • You can find the documentation for each endpoint in the sidebar.
   • Each endpoint has a "Try Out" button to test the endpoint with your own data.
   • You can also use copy the pre-made code snippets such as cURL, PHP, JavaScript, etc. to test the endpoint.

REST API endpoints

Sandbox environment

For testing purposes, you can use the sandbox environment endpoint:

 https://api-gateway-sandbox.huch.tech

Live environment

When you're ready to go live, use the following endpoint:

https://api-gateway.huchpay.com

Note

On Sandbox Payments will be marked as completed manually for testing purposes. This allows you to simulate successful transactions without actual fund transfers.

Hosted Payment Page (HPP)

The payment creation response returns a url — this is the Hosted Payment Page (HPP), where the customer chooses their bank and confirms the payment. Redirect the customer to that url.

Environment	Hosted Payment Page (HPP)
Sandbox	https://sandbox.huch.tech/pay/{payment_id}
Live	https://pay.huchpay.com/pay/{payment_id}

Always redirect using the url returned by the API rather than assembling the URL yourself.

Tools & references

Resource	Where
Postman collection (Sandbox)	Run in Postman
OpenAPI specification	openapi.json in the documentation repository
Errors, X-Request-ID and retry rules	Errors & Error Codes
Payment status meanings & when to fulfil	Get payment details
Webhook signature & replay protection	Webhook Security
Sandbox test credentials & test banks	Test Data (Sandbox)
Common integration questions	Integrations FAQ

Important Disclaimer

We **strongly recommend** opening the payment URL in a new external page (Hosted Payment Page - HPP). This approach provides better security, reliability and user experience. The HPP is fully responsive.

Reasons to Avoid iFrame Integration:

• Potential functional limitations
• Issues with language switching
• Problems with pop-ups
• Difficulties with redirection to banking applications

For optimal user experience and compatibility, Always prefer using an external page (HPP) over iFrame integration.