Inward remittance notifications

Send an encrypted notification with recipient, amount and currency. Accepted notifications enter in_transit; acceptance is not proof of funds received.

https://api-integration-gateway-my-7c92.hipayx.com/v1/inward-remittance-notifications

Authentication and encryption in four steps

1. Obtain your Client ID, API Token and independent AES key privately. Real credentials never appear in public documentation.
2. Build the JSON payload described below and encrypt using AES-256-GCM. Generate a fresh random 12-byte nonce for every encryption.
3. POST nonce and ciphertext over HTTPS, with your Token and Client ID in the headers.
4. The server authenticates the Token, decrypts with the shared secret, validates fields and stores the notification idempotently. The shared key is confidential, not public.

Authorization: Bearer YOUR_API_TOKEN
X-Client-Id: YOUR_CLIENT_ID
Content-Type: application/json

{"nonce":"BASE64_NONCE","ciphertext":"BASE64_CIPHERTEXT_AND_TAG"}

The key contains 32 random bytes, exchanged using padded standard Base64. The nonce is 12 random bytes. ciphertext is encrypted bytes followed by the 16-byte GCM tag, then standard Base64 encoded. Never reuse a nonce under the same key. Do not use the Token as the encryption key or substitute a short numeric password.

Additional authenticated data (AAD) is the following UTF-8 string, ending with your assigned Client ID. The example handles it automatically:

hipayx-v1|POST|/v1/inward-remittance-notifications|YOUR_CLIENT_ID

Only the encrypted JSON envelope is accepted, not plaintext business fields. The old JWE/public-private-key protocol is retired.

Business fields inside the ciphertext

All fields must be present; extra fields are rejected. Remarks may be an empty string.

Batch and independent order references

EXAMPLE COMPANY → EXAMPL + 260917 + 001
EXAMPL260917001

Use the first six Latin letters of the recipient account NAME, ignoring spaces/punctuation and uppercasing; not the account number. Append YYMMDD and a sender-coordinated sequence from 001 to 999. Do not wrap after 999 for the same date/prefix. Agree the business timezone and handling of names shorter than six Latin letters during onboarding.

Batch numbers are grouping metadata. Deduplication uses Client ID + notification_id. Identical business content returns the original receipt; changed content under the same ID is rejected. Preserve batch and order IDs on retries, refresh timestamp if necessary, and generate a new nonce when re-encrypting.

Responses and retries

{
  "receipt_id": "receiver-generated-uuid",
  "notification_id": "your-order-reference",
  "status": "in_transit",
  "duplicate": false,
  "received_at": 1789600000
}

On failure, use exponential backoff with jitter starting at two seconds, capped at one minute. Investigate persistent failures; do not retry indefinitely.

Credited-status webhook

Accepted notifications become in_transit. Only our trusted internal confirmation may transition to credited and enqueue a webhook; senders cannot declare credit using the intake endpoint.

Callback configuration

Provide your HTTPS callback URL privately, configured per Client ID, not per notification. Public port 443 only; redirects/private targets prohibited. Verified public IPs are pinned and must be reviewed when changed.

{
  "event_id": "stable-event-uuid",
  "event_type": "remittance.credited",
  "client_id": "YOUR_CLIENT_ID",
  "notification_id": "your-order-reference",
  "batch_id": "EXAMPL260917001",
  "receipt_id": "original-receipt-uuid",
  "status": "credited",
  "credited_at": 1789600000,
  "confirmation_reference": "ledger-reference"
}

X-HIPAYX-Event-Id: stable-event-uuid
X-HIPAYX-Timestamp: current-unix-seconds
X-HIPAYX-Signature: v1=HEX_HMAC_SHA256

HMAC-SHA256(webhook_secret, timestamp + "." + raw_body)

Callbacks send signed JSON over HTTPS without recipient account details. The webhook signing secret is separate from Token and AES key. Verify the exact raw body in constant time, reject timestamps outside five minutes, and deduplicate by event_id. Return 2xx only after durable recording.

Non-2xx/network failures retry up to 12 attempts, starting at 30 seconds with exponential backoff capped at one hour. Event ID/body stay fixed, signature timestamp refreshes. Exhausted events remain for review; missing callback configuration leaves them pending.

Example and operational scope

Download Python example

pip install cryptography httpx

HIPAYX_CLIENT_ID
HIPAYX_API_KEY
HIPAYX_ENCRYPTION_KEY
HIPAYX_API_URL

python client_example.py

Provide credentials via secure environment variables or a secret manager. HIPAYX_ENCRYPTION_KEY is the privately supplied Base64 key. The example uses dummy data and does not move funds. Never put credentials in browser code, public repositories or URLs.

The Malaysia gateway currently receives and stores ciphertext; Hong Kong forwarding is not yet connected. Real partner callback configuration and acceptance testing remain required. This service does not verify bank receipt or alter balances.

support@hipayx.com