> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rc.cleverhub.co/llms.txt
> Use this file to discover all available pages before exploring further.
# List PayIns
> This API allows you to fetch a payment links list of customer linked to your app-id. This API is paginated. The default is 20 transactions per page.
## OpenAPI
````yaml /api/openapi/v3-reference.yaml get /v3/payin_links
openapi: 3.0.2
info:
title: Multi-currency Gateway
description: "\n---\n\n## Introduction\n\nThe Multi-currency Gateway APIs have been designed to simplify how merchants manage payments across different currencies and methods. All transactions are processed directly through our gateway, ensuring a seamless experience while minimising the effort required for integration.\n\n👉 **Demo:** [View Demo Website](https://minimoo.cleverpay.store/)\n\n### Key Features\n\n- **Unified API Schema**: Handle multiple currencies through a single, consistent schema.\n- **Multi-Currency Support**: Accept and process payments in multiple currencies seamlessly.\n- **Currency-Aware Payment Methods**: Automatically present the supported payment options based on the transaction currency.\n- **Fast Onboarding**: Minimal setup effort with standardised API requests and responses.\n\n---\n\n## Integrate Multi-currency Gateway APIs into your website\n\n### 1. Payment Method\n\nUse this API to integrate and display all payment methods directly on your website. It’s the fastest option, as you won’t need to build or manage the payment method UI yourself.\n\n\n\n- **Step 1**\_Call the Get PayIn Methods API\_to retrieve the list of available methods. (You may display this list directly in your UI.)\n- **Step 2**\_Call the\_Create PayIn API\_with the selected\_`payin_method_code`\_from Step 1.\n- **Step 3**\_The customer completes checkout\_on the Hello Clever hosted checkout page.\n- **Step 4** Wait for the webhook notification from Hello Clever and update the transaction status in your system accordingly.\n\n---\n\n### 2. Payment Link (Hello Clever brand)\n\nUse this API to integrate and run your own payment gateway. Use our Payment Link API (Hello Clever branded) to start collecting payments in no time, we’ll handle the rest of the checkout experience for you.\n\n\n\n- **Step 1** Call the Create PayIn API without the `payin_method_code` field.\n- **Step 2**\_Redirect the customer to the generated\_`payment_url`.\n- **Step 3**\_The customer completes checkout by selecting from\_**all available payment methods**\_on the Hello Clever hosted checkout page.\n- **Step 4** Wait for the webhook notification from Hello Clever and update the transaction status in your system accordingly.\n\n---\n\n### 3. Payment Link (Your brand)\n\nPlease get in touch with [support@helloclever.co](mailto:support@helloclever.co) to customise your brand\n\n\n\n---\n\n## Integrate Multi-currency Gateway APIs with UX Control\n\n### 1. Redirect UX\n\nAfter receiving the `payment_url` from the Create PayIn API, redirect the user to that URL to complete the payment.\n\n**NOTE**: Some browsers (such as Safari, Chrome, etc.) block redirect functionality, preventing automatic redirection to the Payment Link. You need to allow pop-ups in your browser settings [here](#troubleshooting).\n\n**Example**:\n\n\n\n---\n\n### 2. Popup UX\n\nAfter receiving the `payment_url` from the Create PayIn API, render it inside a pop-up window so the user can complete the payment without leaving your site.\n\n**Example**:\n\n\n\nIn the Popup option, you can control for handling of payment success or failure events for closing the pop-up accordingly. This guide shows you how.\n\n---\n\n### Handle Payment Events in Popup UX\n\n_Listen to payment success or failure events to trigger your logic and close the pop-up when the transaction is completed._\n\n```jsx\nwindow.addEventListener(\"message\", function (event) {\n if (\n !event.data?.hc_payment_event ||\n typeof event.data?.hc_payment_event !== \"object\"\n )\n return;\n\n // Check the event type\n if (event.data.hc_payment_event.event_type === \"onChange\") {\n if (event.data.hc_payment_event.page_state === \"success\") {\n // Handle your logic here\n // E.g: If you want to redirect the main page to the success URL\n // window.location.href = event.data.hc_payment_event.redirect_url.success;\n }\n\n if (event.data.hc_payment_event.page_state === \"failed\") {\n // Handle your logic here\n // E.g: If you want to redirect the main page to the failure URL\n // window.location.href = event.data.hc_payment_event.redirect_url.failure;\n }\n }\n});\n```\n\n**Event data object**\n\n- `event_type`: The type of event triggered by the payment link\n - `onChange`: Triggered when the payment link state changes. This occurs when the `page_state` is success or failed page, or when the countdown reaches 0.\n - `onDone` : Triggered when the **Done** button is clicked on the success page; or when the countdown counts to 0.\n \n- `page_state`: The current state of the payment link\n - `success`: when the payment link is on the success page\n - `failed`: when the payment link is on the failed page\n\n```jsx\n// Data format\nhc_payment_event {\n event_type: string, // \"onChange\" || \"onDone\"\n page_state: \"success\" | \"failed\"\n}\n```\n\n**Example:** If you want to control when the pop-up closes on successful or failed transactions.\n\n\n\n**Best Practices**\n - Treat **webhooks** as the source of truth for payment status. \n - Use **event listener** only to improve UX (instant feedback, UI updates).\n\n---\n\n## Troubleshooting\n\n- Some browsers (such as Safari, Chrome, etc.) block redirect functionality, preventing automatic redirection to the Payment Link. You need to allow pop-ups in your browser settings.\n\n \n\n \n\n 1. Click Tab icon\n 2. Open “Settings for [DOMAIN]”\n\n \n\n 3. Allow “Pop-up Window Blocked”\n\n \n"
version: 3.0.0
termsOfService: https://helloclever.co/terms
contact:
email: support@helloclever.co
servers:
- url: https://api.cleverhub.co/api
description: Sandbox Environment
- url: https://api-merchant.helloclever.co/api
description: Production Environment
security:
- app-id: []
secret-key: []
paths:
/v3/payin_links:
get:
tags:
- PayIn
summary: List PayIns
description: >-
This API allows you to fetch a payment links list of customer linked to
your app-id. This API is paginated. The default is 20 transactions per
page.
parameters:
- name: page
in: query
schema:
type: string
description: Page number to query. Currently we support 20 records per page
- name: per_page
in: query
schema:
type: string
description: Default 20 records per page
- name: external_id
in: query
required: false
schema:
type: string
description: |
Filter payment links by a custom external_id.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
records:
type: array
items:
type: object
required:
- uuid
- expires_at
- payment_url
- amount
- description
properties:
uuid:
type: string
description: Unique identifier for the payment transaction.
expires_at:
type: string
format: date-time
description: Expiration time (ISO 8601 UTC) of the payment link.
payment_url:
type: string
format: uri
description: URL of the payment.
payin_method_code:
type: string
description: Code of the selected payment method.
amount:
type: number
description: Transaction amount.
description:
type: string
description: Description of the payment transaction.
external_id:
type: string
description: Custom ID.
transaction_info:
type: object
description: Information about the transaction.
properties:
uuid:
type: string
description: Transaction UUID
currency:
type: string
description: Currency code for the transaction.
amount:
type: number
description: Original payment amount.
paid_amount:
type: number
description: Amount that has been paid.
refund_amount:
type: number
description: Amount that has been refunded.
status:
type: string
description: The current status of the payment request.
status_text:
type: string
description: Detailed explanation of the current status
pagination:
type: object
description: Pagination of payment links list.
properties:
page:
type: integer
description: Page number.
next_page:
type: integer
description: Next page number.
size:
type: integer
description: Size of page.
total_pages:
type: integer
description: Total page number.
total_count:
type: integer
description: Size of payment links list.
example:
records:
- uuid: HZYN6JUN
expires_at: '2025-09-11T00:36:40.181Z'
payment_url: https://paylink.cleverhub.co/SFpZTjZKVU4
payin_method_code: null,
amount: 10000.0,
description: Test payin
external_id: '123456'
transaction_info: null
- uuid: 8SXGTYA1
expires_at: '2025-08-25T09:12:41.056Z'
payment_url: https://paylink.cleverhub.co/OFNYR1RZQTE
payin_method_code: vn_vietqr_vnd
amount: 12000.0,
description: Test payin
external_id: '123456'
transaction_info:
uuid: O5T7MS67
currency: VND
amount: 12000
paid_amount: 0
refund_amount: 0
status: pending
status_text: >-
Customer started a new payment but hasn't proceeded
yet.
pagination:
page: 1
next_page: null
size: 20
total_pages: 1
total_count: 16
'400':
description: Bad Request
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
code:
type: string
message:
type: string
example:
errors:
code: REQUIRE_LOGIN
message: Not Authorised
components:
securitySchemes:
app-id:
type: apiKey
in: header
name: app-id
description: |
A unique identifier assigned to each application.
secret-key:
type: apiKey
in: header
name: secret-key
description: |
A secure token associated with the `app-id`.
````
## Related topics
- [Accept Instant Payments with AUD PayID](/developer-reference/api-use-cases/accept-instant-payments-with-aud-payid.md)
- [Clever AI Actionable Insights](/clever-ai/actionable-insights.md)
- [Handle Multi-Currency Payins and Payouts](/developer-reference/api-use-cases/handle-multi-currency-payins-and-payouts.md)