Common Issues

Buyer is not recognized

Verify buyer profile activation, protocol, and buyer identifier mapping. Confirm credentials match the incoming request format.

Signature validation fails

Check strict signature setting, shared secret value, and request canonicalization on the caller side.

Request blocked by security checks

Validate source IP against allowlist and confirm hook/return URL policy constraints for the current environment.

Transfer returns replay or conflict

Review idempotency key usage. Reuse only for true retries of the same payload; generate a new key for new business requests.

Cart API returns context errors

Check token availability and context lifecycle state (active vs expired). Ensure the correct token is propagated in each call.

Mapping output is incomplete

Review mapping profile assignment on buyer, required mapping rules, and transformer/value-map configuration.

Support cannot isolate issue quickly

Use trace correlation id and export JSON trace details for deterministic reproduction with the integration partner.

Need structured error definitions

Use the Error Catalog for category-by-category resolution steps.