Aggregated Payment (Merchant Collection by Card Number)

This transaction type enables a payment service Aggregator to accept customer payments on behalf of an integrated Merchant. Funds are debited from the Payer and distributed between the Merchant (net of the Aggregator fee) and the Aggregator (fee portion) automatically.

Business Flow

1. Merchant signs an agreement / onboards with the Aggregator.
2. Aggregator instructs the Merchant to create (or provide) a wallet in the heth.me system and sends back the wallet_id.
3. Using its own API key, the Aggregator creates a payment transaction specifying the Merchant wallet details in money_storage_merchant and the Payer card details in money_storage.
4. Upon successful processing, the balances of the Payer, Merchant, and Aggregator are updated in a single step.
5. The transaction status can be polled using the standard transaction retrieval method (authorized with the same API key).

Example Request

curl --location --request POST 'https://app.heth.me/api/v1/transactions' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: 165f15d4-0143-4d6a-a387-e3c44aaef7f6' \
  --data '{
    "params": {
      "amount": 10000000000000000,
      "currency": "USDT",
      "env": "prod",
      "type": "payment",
      "route": "hot_hot_ETH",
      "money_storage_merchant": {
        "wallet_id": "002305DDA4FED2BABA57C1C70CC8E575D5D8A7AD",
        "network": "ETH",
        "type": "p2p_proxy",
        "currency": "USDT"
      },
      "money_storage": {
        "network": "ETH",
        "type": "bank_card",
        "currency": "USDT",
        "cardnumber": "9981040364688168",
        "cvv": "128",
        "exp_month": "08",
        "exp_year": "2026",
        "cardholder": "John Doe"
      },
      "description": "Payment",
      "txid": "hot_hot_ETH"
    }
  }'

Field Reference

Field	Description	Type	Example
amount	Transaction amount (minor units)	Number	10000000000000000000
currency	Transaction currency (default USDT)	String	USDT
env	Execution environment (default prod)	String	prod
type	Transaction type (payment)	String	payment
route	Processing route (must match configured mapping)	String	hot_hot_ETH
money_storage_merchant	Merchant (payee) wallet descriptor	Object
> wallet_id	Merchant wallet identifier	String	002305DDA4FED2BABA57C1C70CC8E575D5D8A7AD
> network	Blockchain network (TRX or ETH)	String	ETH
> type	Wallet interaction type (e.g. p2p_proxy)	String	p2p_proxy
> currency	Merchant settlement currency (default USDT)	String	USDT
money_storage	Payer funding instrument descriptor	Object
> network	Blockchain network (TRX or ETH)	String	ETH
> type	Instrument type (bank_card)	String	bank_card
> currency	Payer currency (default USDT)	String	USDT
> cardnumber	Virtual card number	String	9981040364688168
> cvv	Virtual card CVV	String	128
> exp_month	Card expiry month	String	08
> exp_year	Card expiry year	String	2026
> cardholder	Cardholder name	String	John Doe
description	Human-readable description	String	Payment
txid	Client-side transaction identifier	String	hot_hot_ETH

Notes

• The Aggregator fee logic is applied automatically based on the API key configuration.
• Ensure route matches an enabled processing route for the provided API key.
• Use idempotent txid values to avoid accidental duplicate submissions.
• Retrieve transaction status via the standard GET transaction endpoint (polling until a terminal state is reached).