Here is a comprehensive "First Aid" troubleshooting script designed for our merchants. This guide is intended to reduce back and forth between our team and yours. It includes basic checks, specific error categories, and exactly what to prepare if you need to escalate to our team.

Before reaching out to our Technical Support team, please run through this quick diagnostic checklist. In most cases, transaction or API issues can be resolved using the steps below.

Phase 1: The "Sanity Check" (Start Here)

Before diving into code, please verify the following:

• Environment Check: Are you making requests to the Live environment using Test keys (or vice versa)? Or making use of sk_live keys where pk_live keys have been specified in our API docs? 

• Service Status: Check our Status Page to ensure there are no ongoing system-wide downtimes or partner outages (e.g., NIBSS downtime, etc).

• API Key validation: Have your API keys been recently regenerated or expired? If you have multiple accounts with us, could you please confirm that you’re using the API keys associated with the account where the payment method is enabled? 

• Welcome to Kora: Please check the endpoint called, to confirm it is the correct/complete endpoint as shown in our docs. 

Phase 2: Specific Issue Categories

Scenario A: Kora dashboard Issues

The login page won't load, or the user is getting blocked.

• The user is getting blocked: If you are getting an error message (Sorry, you have been blocked. You are unable to access korapay.com) while trying to access our dashboard https://merchant.korapay.com/auth/login,  please reach out to support@korapay.com with the email address of the user experiencing this issue as well as the IP address of the user.

• The user is unable to submit the KYC request/Submit button not enabled: Please make sure all required fields on the form are filled out and that every dropdown option has been selected. If you have already done this and the issue still persists, please record a short screen recording showing the problem. Include the email address of the user experiencing the issue and send both to support@korapay.com. 

• “Internal server error” when downloading transaction reports: The selected date range is too large. Please choose a smaller range and try again. 

• Login failure due to incorrect Username/password: Please check your login details, and try again. 

• “Incorrect OTP code” error message: Please refresh the page and retry the login process to receive a new OTP. Ensure you use it before it expires. 

Scenario B: API Errors (400s and 500s)

If your API requests are failing, look at the HTTP Status Code in your response.

Scenario C: Checkout Issues

The payment modal won't load, or the customer is getting stuck on your page.

• Timer less than 1 hour for bank transfer method: Please confirm that the payer did not first generate a virtual bank account number, switch payment methods, and then attempt to return to bank transfer. Please note that the virtual account number is generated during the initial attempt, and the countdown begins immediately from that time.

• Redirection failing: If you are using a hosted checkout page, ensure you have provided a valid redirect_url in your initial payload.

Scenario D: Transaction Failures (Customer attempted to pay, but it failed)

Please review the Errors section of our API documentation for more details. 

Scenario D: Webhook/Notification Issues

The transaction was successful, but your system didn't update the status of the transaction.

1. Check your Webhook URL: Is the webhook URL correct? 

   • For payouts: please login to your Kora dashboard, and confirm that the correct URL has been set as explained here. 

   • For pay-ins: please examine your request payload, and confirm that the correct webhook URL is being sent in your notification_url parameter. 

2. Check your Server Logs: Are you receiving our POST request?

   • If Yes, but your system isn't updating: Your server is likely throwing an error internally. Please check your logs.

   • If No: Your firewall is likely blocking our IP address. Please reach out to the team, so we can provide our IP address for you to whitelist. 

3. Did you return a 200 OK? Your server must acknowledge our webhook with a 200 OK status. If you do not respond after multiple retries, our system assumes it failed and may stop retrying. 

4. 408 HTTP error: This is a client timeout error. It means that there is a long running process on your webhook notification implementation. You should strongly consider making the webhook operation asynchronous. 

Phase 3: How to Escalate to Technical Support

If you have run through the steps above and the issue persists, please reach out to our support team at support@korapay.com. 

To help us resolve your issue swiftly, please include the following in your first message:

1. The Exact Endpoint: (e.g., https://api.korapay.com/merchant/api/v1/charges/mobile-money)

2. Transaction Reference / ID: Provide the specific transaction reference. If you are sharing a screenshot of transaction references, please also copy and paste the full references into your escalation. This ensures we capture the details accurately and prevents any errors that can occur when retyping information from an image.

3. The Raw Request Payload: The JSON you sent to us (please mask sensitive data like your secret keys, full card numbers or CVVs).

4. The Raw Response Payload: The exact error JSON as well as the Status Code you received from us.

5. Time and Date: When did this happen? (Please specify your Timezone).