Skip to main content
↳ Organization KYC gates everything. Until Hop approves it, every endpoint returns 403 KYC_NOT_APPROVED with details.kyc_status. Sandbox and production have separate keys and separate webhook endpoints.
Youthe API callerHopautomaticHop teampeople, outside the API
  1. 1You
    Sign the agreement and submit organization KYCoffline
  2. 2Hop team
    Approves KYC; issues your ids, a sandbox key and secret, and the key’s scopescus_ · acct_ · ak_
  3. 3You
    Verify your signing function against the two test vectorsHMAC-SHA256
  4. 4You
    Read balances to confirm key, clock, IP allowlist and scopes in one callGET/customers/{cid}/accounts/{aid}/balances
  5. 5Hop
    Returns 200, or 401 / 403 with the cause in error.message401 · 403
  6. 6You
    Register a webhook endpoint for payin and payout eventsPOST/customers/{cid}/webhook-endpointswh_
  7. 7Hop
    Returns the signing secret once; store it before discarding the responsesecret shown once
  8. 8Hop team
    Issues production key and secret after sandbox sign-offseparate keys
  9. 9You
    Platform customers: create one account per end customer, then take it live with Flow 2POST/customers/{cid}/accountsacct_
Known gaps: your cus_ and acct_ ids come from Hop out of band; there is no endpoint to read them. There is no ping endpoint for webhooks; in sandbox, Simulate Payin raises a real signed payin.received delivery to test the handler.
Notes: The Platform’s owncus_ and acct_ ids are generated by Hop out of band and provided at onboarding completion; there is no endpoint to read them. There is no ping endpoint for webhooks; in sandbox, Simulate Payin raises a real signed payin.received delivery to test the handler.

​
Troubleshooting