Troubleshooting

This page is the canonical place for diagnosing facilitator integration issues.

Common Categories

Setup issue

Typical signs:

• wrong facilitator URL
• mismatched payTo address
• incorrect network or asset assumptions
• malformed payment requirements

What to do:

1. verify the public base URL
2. compare your requirements against the live /supported surface
3. re-check your network and asset assumptions

Bad transaction

Typical signs:

• malformed instructions
• invalid account references
• payload shape does not match the required payment path

What to do:

1. inspect the generated payment transaction carefully
2. simplify the transaction to the smallest valid payment path
3. use POST /verify before attempting settlement

Network slow or expired payment

Typical signs:

• blockhash or timeout-related failure
• payment expired during retry

What to do:

1. retry the flow
2. make sure your client does not wait too long between quote and retry
3. separate transient network conditions from real integration bugs

Connection issue

Typical signs:

• temporary inability to reach the facilitator or upstream services

What to do:

1. retry
2. confirm the public endpoint is healthy
3. distinguish upstream or network instability from deterministic merchant bugs

Policy rejection

Typical signs:

• policy:* error codes
• payload rejected despite being signed

What to do:

1. read the error code closely
2. compare your transaction shape to sponsor policy expectations
3. simplify the payment transaction

Debugging Sequence

When something fails, use this order:

1. confirm the target network is supported
2. inspect GET /supported
3. validate the payload with POST /verify
4. inspect the returned error code
5. retry settlement only after the validation path is clean