DOCSEARCHbyAlgolia
Submit Docs

Home Credit Partner API

website·Indexed 30 days ago

https://main.hc-docs.pages.dev/

Technical specifications and implementation guides for the Home Credit Partner API (version 3.4.0). Documentation covers REST API endpoints for financing applications, installment program calculations, precheck scorings, and calculator software installation for partner e-shops.

Tokens
42.9K
Snippets
165
Records
284
Agent score
74%

What's inside Home Credit

  1. Overview of the Home Credit integration process

    Integrating Home Credit involves a four-step workflow with flexible implementation options ranging from full API control to minimal integration via widgets or web clients:

    1. Calculator: Display installment options on the product page using an API, Widget, or direct link.
    2. Create Application: Initiate the application process via API and redirect the customer to complete the submission.
    3. Notifications: Receive status updates through a configured endpoint, API polling, or the web client.
    4. Fulfillment: Confirm the shipment or delivery of the order via API or the web client.

  2. Overview of the Home Credit integration process

    The Home Credit integration consists of four primary steps, offering flexibility from full API implementation to minimal integration:

    1. Calculator (Kalkulačka): Display installment options on the product page via API, widget, or a direct link.
    2. Application Creation (Vytvoření žádosti): Create a loan application via API or redirect the customer to complete it.
    3. Notifications (Notifikace): Track application status via a webhook endpoint, API, or web client.
    4. Warehousing and Delivery (Vyskladnění a doručení): Confirm shipment or delivery via API or web client.

  3. Overview of Home Credit One-Click API for Installments

    The Home Credit (HC) One-Click API allows partner e-shops to integrate Home Credit payment methods, enabling customers to complete online purchases via installment plans. The API is divided into several functional groups: Security, Application resources (lifecycle management), Installments calculator resources, Merchantsite resources (for asynchronous notifications), and Health checks.

  4. Check API and back-end service availability

    To monitor the operational status of the system, use the following resources:

    • Use the API state check resource to determine the current state of the API.
    • Use the health check resource to verify the availability of back-end services.

  5. Calculate installment program details via API

    Use the POST /financing/v3/installmentPrograms endpoint to retrieve detailed information about an installment program. The API returns the installment program that most closely matches the provided input criteria. The endpoint can return a 200 OK response upon success or a 422 Unprocessable Entity response if the input is invalid.
    POST /financing/v3/installmentPrograms

  6. Track application origin and workflow in v3

    Version v3 introduces new structures for process tracking:

    • workflowSteps[]: Found in the response, providing structured information about the next steps in the process.
    • Origin tracking: Use precheckIds for pre-check references, sourceId for campaign identifiers, and extendedData for UTM parameters and tracking information.

  7. Retrieve order details using /financing/v1/orders

    Use the GET /financing/v1/orders endpoint to retrieve current information about a specific order, primarily its status and detailed order data. To target a specific application, use the path /financing/v1/orders{?applicationId}, where {applicationId} is the ID received from the /financing/v1/applications response after creation.

    Requirements:

    • Authentication: Required
    • Permission: applications.overview

    Supported Financing Types:

    • INSTALLMENT: Supported

    Supported Request Statuses:

    • PROCESSING, ODMÍTNUTO (Rejected), ZRUŠENO (Cancelled), PŘIPRAVENO (Ready)

    Successful Response (200 OK): Returns an object containing:

    • Order number
    • Total order price (including VAT)
    • Order items (list containing item name, total price for all units including VAT, and item status)
    • Order status
    • Basic application info (ID, application status, and application sub-status)
    GET /financing/v1/orders?applicationId={applicationId}

  8. Check API and Backend Service Health

    To monitor the availability and operational status of the API and its underlying backend services, use the following dedicated health check endpoints:

    • Use the API Status Check resource to determine the current overall status of the API.
    • Use the API Health Check resource to verify the availability of specific backend services.

  9. HC On-line payment integration overview

    The HC On-line payment method is integrated via a REST API using JSON for all requests and responses. The integration process follows four primary steps: 1. Calculator (showing installment options), 2. Create application (initiating the financing request), 3. Notifications (tracking application status), and 4. Fulfillment (confirming shipping and delivery).

  10. Handle Home Credit return URL parameters

    When Home Credit redirects a customer back to the e-shop (via approvedRedirectUrl or rejectedRedirectUrl), the following parameters are appended to the URL to provide context about the transaction outcome:

    • orderNumber (string): The e-shop's internal order number provided during application creation.
    • applicationId (string): The HCO application identifier.
    • withdrawal (boolean): true if financed from an existing revolving loan; false if a new contract is created.
    • downPayment (number): The value of the down payment (typically 0).
    • stateReason (enum): The application substate.
    • checkSum (string): A hashed message for verification.
    http://youreshop.cz?orderNumber=0606104036&stateReason=PROCESSING_SIGNED&downPayment=100000&checkSum=443E150D3406F6A8DC62C1DB224AFDD84FA9907071BB1AD9B2C7701031793662191501B26AADF3A31361341EA176C80B23D8A9A5E5B5219538289945FE0C20A7&applicationId=01-11b00a1ef1&withdrawal=false

  11. Notify partners about application changes via API

    Use the /partner/notification/endpoint with a POST request to inform a partner that changes have been made to an application. The endpoint returns a 204 (No Content) status code upon success or a 400 (Bad Request) status code if the request is invalid.
    POST /partner/notification/endpoint

  12. Retrieve order details using /financing/v1/orders

    Use the GET /financing/v1/orders{?applicationId} endpoint to retrieve current information about a specific order, including its state and associated application details. This endpoint requires the authenticated user to have the applications.overview authority.

    Supported Financing Types:

    • INSTALLMENT

    Supported Application States:

    • PROCESSING
    • REJECTED
    • CANCELED
    • READY

    Successful Response (200 OK): Returns an object containing:

    • Order number
    • Order total price (including VAT)
    • Order items array (containing item name, total price including VAT, and item state)
    • Order state
    • Application basic information (ID, state, and substate)
    GET /financing/v1/orders?applicationId={applicationId}