AinePay
EN中文
Webhooks

Test Notify URL

When setting or updating the merchant notify URL in the AinePay merchant dashboard, AinePay tests the merchant's system through this endpoint, so the merchant's system must respond to it.

Endpoint

  • Method: GET
  • Path: {notifyUrl}/ainepay/notify
  • Authentication: Requires the AinePay merchant dashboard
  • Content-Type: application/x-www-form-urlencoded

Parameters submitted in the dashboard

parametertypedescriptionrequiredexample
urlstringThe URL for receiving callbacks, length 10~2048. Must comply with the URL requirements below.yeshttps://merchant.example.com
codestringThe merchant's 6-digit two-factor (2FA/TOTP) code. Two-factor authentication must be enabled and verified to set or update the notify URL.yes123456

URL Validation

  1. Strip any trailing / from the submitted URL.
  2. Append the fixed webhook path /ainepay/notify.
  3. Send a GET request with the x-callback-token header (redirects are not followed).
  4. The merchant's system must return a successful HTTP status (2xx).
  5. The merchant's system must echo the same x-callback-token value in the response header.
  6. If validation passes, the URL is saved as the merchant's notify URL.

URL Requirements

  • The URL must be an absolute URL.
  • The scheme must be http or https.
  • The URL cannot contain a fragment.
  • In production, the URL must use https and effective port 443.
  • In production, the URL cannot contain user info and cannot use an IP literal as the host.
  • In production, the host must resolve to public addresses (no private, loopback, or link-local addresses).

Expected Test Request

GET /ainepay/notify HTTP/1.1
Host: merchant.example.com
User-Agent: CallbackVerifier/1.0
x-callback-token: K8sJ2mQ4nR7vT0xY3bC6dF9gH1jL5pZw

Common Errors

  • PARAMETER_ERROR if the submitted URL is missing, malformed, or violates URL validation rules.
  • TOTP_NOT_ENABLED if the merchant has not enabled two-factor authentication; TOTP_CODE_INVALID if the code is wrong or already used.
  • CALL_BACK_URL_INVALID if the verification request cannot reach your endpoint, gets a non-2xx response, or does not receive the same x-callback-token back.