SmartGen Mastercard MPQR Troubleshooting and Support Runbook

Use the links below to move between the SmartGen Mastercard documentation chapters and the live Sandbox Lab. The Lab is for simulated technical testing only; it does not authorize real-money use or live merchant fulfillment.

SmartGen Mastercard MPQR Troubleshooting and Support Runbook

First diagnostic rule

Separate the problem into four layers:

Layer	Question
Browser	Did the page send the request and receive CORS headers?
SmartGen Worker	Did the Worker validate and sign the request?
Mastercard API	Did Mastercard accept, decline, or reject the request?
Partner/settlement	Is the merchant, QR, account, or settlement relationship approved?

A direct curl request can work while a browser request fails because of CORS. A signed Sandbox request can work while Production fails because the Production partner, key, merchant, or program approval is missing.

Common symptoms

Symptom	Likely cause	Safe action
Browser says Worker unavailable	Missing/incorrect CORS origin, stale page, Worker unreachable	Test `OPTIONS`, reload page, check Worker health
HTTP 503 from Worker	Required secret/configuration missing	Check names and environment; never print values
Mastercard authentication error	Wrong Consumer Key/key pair, expired key, bad body hash, wrong signature URL	Verify project, key, exact body, method, URL, timestamp; rotate if exposed
HTTP 400 invalid input	Missing field, unsupported value, bad account/QR format	Compare against current Mastercard field specification
HTTP 402 decline	Sandbox/provider decline scenario	Record reason; do not fulfill; do not retry blindly
HTTP 500/system error	Provider simulation or transient error	Retrieve by reference before retrying
HTTP 404 retrieval	Unknown Transfer ID/reference or wrong environment	Confirm ID, reference, and endpoint environment
Payment approved but no QR image	Direct transfer test or missing approved QR payload	Obtain QR capability from Receiving Institution/partner
Sandbox works, MTF fails	MTF not configured, wrong Partner Reference ID, missing approval	Ask Mastercard/sponsor to confirm MTF setup
MTF works, Production fails	Production key not activated, wrong endpoint/partner/merchant	Verify Production onboarding and cutover checklist

CORS test

curl -i -X OPTIONS \
  "https://YOUR_WORKER.workers.dev/api/mastercard/mpqr/payment" \
  -H "Origin: https://smartgentools.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: content-type"

The response should contain the exact allowed origin and the allowed methods. Do not solve a production CORS issue by opening the Worker to every origin.

OAuth diagnosis

Check these items without printing credentials:

The Consumer Key belongs to the same Mastercard project as the public key corresponding to the private signing key.
The private key is a valid PKCS#8 PEM value and has not been truncated.
The request uses OAuth 1.0a with RSA-SHA256.
oauth_body_hash is the Base64 SHA-256 hash of the exact bytes sent as the request body.
The signature base URL has the correct scheme, host, and path and excludes the query string.
Query and OAuth parameters are encoded and sorted correctly.
The timestamp is current and the nonce is unique.
The Authorization header values are percent-encoded correctly.
The environment, Consumer Key, Partner ID, and endpoint all belong together.

Do not troubleshoot by switching to OAuth 2.0 unless Mastercard confirms that the current MPQR project and endpoint support it.

Status uncertainty

If the request times out after submission, do not automatically create another transfer. Keep the internal order in unknown, retrieve by Transfer ID if it was returned, otherwise retrieve by Transfer Reference, and escalate after the defined retry window.

Support evidence

When opening a Mastercard or partner support case, provide:

environment
API family and operation
UTC timestamp
HTTP status
provider status/reason code
Transfer Reference
Transfer ID if returned
correlation-id
sanitized request summary
sanitized response summary

Never attach private keys, keystore passwords, OAuth headers, full PANs, CVVs, PINs, OTPs, or unmasked customer data.

Credential exposure response

If a Consumer Key, private key, keystore password, or OAuth header is exposed:

Revoke or rotate the affected Sandbox/MTF/Production key in Mastercard Developers.
Create a replacement key pair as instructed by Mastercard.
Update only the appropriate Worker secret.
Deploy to a non-production environment.
Run the signer and API smoke tests.
Remove exposed material from local files, downloads, shell history, CI logs, screenshots, and messages.
Record the incident and affected environment.

SmartGen Mastercard MPQR Troubleshooting and Support Runbook

SmartGen Mastercard navigation