Skip to main content
POST
Set Up Payment Link Wallet
Create this resource once per account and currency before creating payment links. It is separate from deposit wallets and has no deposit address. One payment link wallet supports all of its available_networks; the selected network and deposit address belong to each payment request. Requires payins:write, an active account, approved payment-link onboarding, and an available network for the currency.

Request

currency is required and accepts USDT or USDC. Do not pass network or a provider wallet ID.

Response

Successful calls always return HTTP 201, including when this account already has a payment link wallet for the currency. Repeat calls return the same ID and current stored status. An Idempotency-Key is not required: the account and currency identify the resource, including for concurrent calls.
available_networks reflects enabled networks with configured treasury routing and can change. Use a network from the latest response.

Integration sequence

  1. Subscribe to payment_link_wallet.updated before setup.
  2. Call this endpoint and store the returned plw_ ID. If the response is already ready, continue immediately; 201 alone does not mean ready.
  3. Wait for the payment_link_wallet.updated webhook or use Get Payment Link Wallet. Handle duplicate webhooks using the event ID and check data.status.
  4. Create a payment link using this account and currency. Repeat step 4 for subsequent links.
Hop sends payment_link_wallet.updated when the wallet becomes ready or failed. Use GET if that notification is delayed or missed. If the setup response is lost or a provider error occurs, repeat POST with the same account and currency. It returns the existing resource, and retries provisioning if the first attempt did not reach the provider. If the status stays pending after a successful retry, wait for the readiness webhook or poll GET. Accounts with earlier payment links must also perform setup once. Hop adopts an existing matching provider wallet where one exists, keeping the same settlement destination.