Troubleshooting
Introduction
Troubleshooting helps partners identify and resolve common issues during the integration and testing process. This section provides possible causes, recommended solutions, and checking steps for all YUKK integration services, helping partners resolve issues before contacting the support team.
Troubleshooting Table
Integration & Functionality Testing for QRIS SNAP & Virtual Account (H2H)
This section lists the most common errors that may occur during the integration and testing process, along with their typical causes and recommended resolutions. By following this guide, partners can quickly identify and resolve issues without needing to escalate unnecessarily.
| Error | Cause | Resolution |
|---|---|---|
| 401xx01 Invalid Token (B2B Access Token) | - Token has expired. - Incorrect signature generation. - Mismatch between X-Timestamp in request and payload signature. | - Generate token using valid Client IDand Client Secret. - Re-check signature creation process and input values. - Ensure timestamp matches in both request and signature (ISO8601, UTC). - Request a new token if expired. |
| 403 / 404 CloudFront Error | - Partner’s IP address not whitelisted. - Invalid or incorrect endpoint URL. - Request payload format not valid. | - Confirm partner IP is registered and whitelisted by YUKK (submit request via latest SOP). - Verify endpoint URL against official documentation. - Ensure request payload follows proper JSON structure and format. |
| 401xx00 Invalid Signature | - Wrong hashing algorithm used. - Incorrect concatenation of payload components. - Using the wrong clientSecret during HMAC generation. | - Verify use of the correct algorithm (HMAC-SHA512). - Ensure payload is built according to the signature formula. - Confirm the correct clientSecret is used. |
| 401 Unauthorized Access | - Missing or invalid Authorization header. - Expired access token. - Token not properly attached to the request. | - Ensure Authorization header is included with Bearer {token} format.- Generate and attach a valid access token. - Retry with refreshed credentials. |
| 400 Bad Request | - Request payload has invalid fields. - Required parameters missing. - JSON formatting error. | - Double-check request body against API specs. - Ensure all mandatory fields are provided. - Validate JSON structure and formatting. |
| Timeout / Connection Error | - Network latency or unstable internet connection. - API endpoint not reachable. - Partner system not handling requests asynchronously. | - Check server/network connectivity. - Verify endpoint is correct and accessible. - Implement retry logic with exponential backoff. |
| Duplicate Transaction | - Same request ID reused. - Partner did not generate unique identifiers per request. - Retry sent without updating parameters. | - Ensure every request uses a unique transaction/request ID. - Apply proper idempotency handling. - Avoid resubmitting the same payload. |
Integration & Functionality Testing for Wallet & Payment SNAP
| Error | Cause | Resolution |
|---|---|---|
| 401xx00 Invalid Signature | - Wrong hashing algorithm used for the specific API type. - JSON body URLs or string parameters containing escaped backslashes. - Missing Base64 encoding on the final HMAC-SHA512 hash output for Symmetric Signature. - Using an incorrect or mismatched clientSecret during HMAC generation. - Mismatch between the timestamp inside stringToSign and the X-TIMESTAMP request header. | - Verify the correct algorithm is used based on the API type: Asymmetric (SHA256withRSA): Used for B2B Access Token generation. Symmetric (HMAC-SHA512): Used for API Services requests. - Ensure signature generation uses a minified body without escaped slashes (unescaped_slashes) so all forward slashes remain clean (e.g., "url":"[https://domain.com](https://domain.com)...") before calculating bodyHash. - Encode the final HMAC-SHA512 signature result to Base64 before inserting it into the X-SIGNATURE HTTP header (Formula: Base64(HMAC_SHA512(clientSecret, stringToSign))). - Confirm that the clientSecret matches the registered credentials in the respective environment (Sandbox/Production). - Ensure the timestamp inside stringToSign strictly matches the X-TIMESTAMP header value. |
| 4007302 Invalid Mandatory Field (additionalInfo) | - Request body for B2B Access Token is missing the required additionalInfo object or the scope field inside it. - Sending only grantType: client_credentials without defining the target scope. | - Include the additionalInfo object containing the appropriate scope inside the JSON request body. |
| 4017400 Unauthorized (authCode used.) | - Submitting an authCode to the B2B2C API (/access-token/b2b2c) that has already been consumed or invalidated by a previous request. - The authCode is strictly one-time use only. | - Re-trigger OAuth Flow: Execute a fresh Get OAuth URL (Account Binding) request to obtain a brand-new authCode. - Immediate Re-submit: Send the B2B2C request using the newly generated authCode. |
Recommended Checking Steps
When an issue occurs, partners are advised to check the request and response details carefully before escalating the issue and for Virtual Account H2H integration, partners should review the full request and response flow.
QRIS SNAP
Before escalating an issue to the support team, verify the following:
- Confirm that all required request headers (such as Authorization, X-TIMESTAMP, and X-SIGNATURE) are included and correctly generated.
- Validate that the request payload follows the API specification and contains all required fields.
- Ensure the transaction ID is unique and has not been used previously.
- Verify that your callback URL is active, reachable, and correctly configured.
- Review the response code and response message returned by the API.
- If applicable, verify the latest transaction status using the Status Inquiry API.
- Save the complete request, response, and timestamp to assist with further investigation.
Virtual Account (H2H)
Before escalating an issue to the support team, verify the following:
- Ensure you are using the correct Base URL for the selected environment (Staging or Production).
- Verify that your API credentials are valid and match the selected environment.
- Confirm that all required request headers (such as Authorization, X-TIMESTAMP, and X-SIGNATURE) are included and correctly generated.
- Validate that the request payload follows the API specification and contains all required fields.
- Verify that the Virtual Account number is valid, unique (if applicable), and has not expired.
- Confirm that the payment amount and customer information are correct.
- Verify that your callback URL is active, reachable, and correctly configured to receive payment notifications.
- Review the response code and response message returned by the API.
- If applicable, verify the latest transaction status using the Virtual Account Inquiry API.
- Save the complete request, response, and timestamp to assist with further investigation.
note
General Troubleshooting Notes
Please always make sure that the endpoint, credentials, and environment are aligned. Staging and production have different base URLs, credentials, and product configurations. Using the wrong combination may cause failed requests, invalid authentication, or transaction data not found.
For payment-related issues, avoid creating repeated transactions before checking the latest status. Partners should use the inquiry or status-check API first to confirm the transaction result.