developer documentation

Troubleshooting

This section provides solutions to standard integration issues and helpful debugging tips.

HMAC Authentication Failures

  • Ensure your API key and secret are correct
  • Verify that you’re using the exact request body for HMAC calculation
  • Check that your HMAC header format is correct: hmac {api_key}:{hmac_signature}

💡 Tip

If you’re having trouble with HMAC authentication, try using our SDK which handles HMAC calculation for you.

Redirect URL Unauthorized

  • Make sure the redirect_url is registered in your allowed redirect URLs
  • Check for exact matching including protocol (http/https) and trailing slashes

⚠️ Common mistake

https://example.com/callback and
https://example.com/callback/ are considered different URLs.

Register both if needed.

Verification Flow Interruptions

  • Verify that your server can make outbound HTTPS requests
  • Check that your server’s IP is not blocked by any firewall

💡 Testing tip

Use our Postman collection to verify each step of the flow independently.

CPF background check not approving

  • Make sure the request uses country:br and the CPF is sent inside user_info.cpf.
  • Send the CPF as 11 digits without punctuation; invalid check digits fail the check silently.
  • Encrypt cpf, name, and dob with the API secret of the same environment (sandbox or production).
  • Confirm with your onboarding manager that the CPF method is enabled in the business settings you are sending, and which match mode applies. In “CPF + date of birth” mode, a date of birth that differs from the registered one fails the check even for an adult.
  • Background checks never return a failure reason. When raising a support case, quote the verification_id.
    The CPF, name and date of birth you sent are never stored, so we cannot retrieve them afterwards.

💡 Testing tip

Use our Postman collection to verify each step of the flow independently.

API Error Codes

Common error status codes and their resolutions:

Status Error Resolution

400

Bad Request

Check that your request format and parameters are correct

401

Unauthorized

Verify API credentials and HMAC signature

403

Forbidden

Your credentials are valid but you lack permission for this action

429

Too Many Requests

Implement rate limiting in your application

500

Server Error

Contact support with your request details and timestamp

Additional Resources

  • Status Page – Check API availability and incidents
  • Try using our SDK which handles the bulk of the work for you.
  • Still having trouble? Contact your onboarding manager for support.

This documentation is maintained by the Verifymy’s team. For the latest updates and version history, visit our documentation repository.

on this page