payee_credential: No valid payee credential

A payee route (GET /payee/v1/destinations, POST /payee/v1/destinations, GET /payee/v1/vouchers, GET /payee/v1/receive, and the payee terms, task, recourse and off-ramp routes) needs to know which payee is calling, and the request did not prove it. The Authorization header carried neither of:

When a Dynamo-Payee header was sent but refused, reason names the check instead of payee_credential:

reasonWhat was wrong
payee_proof_v1an address-and-time (v1) proof; refused at every version: sign a v2 proof
payee_proof_malformedthe header is not v2;payee=…;aud=…;ts=…;nonce=…;body=…;sig=…
payee_proof_staleissued more than 300 seconds from the deployment's clock
payee_proof_audiencemade for another deployment or tenant
payee_proof_bodythe body hash does not match the body received
payee_proof_replayedthe nonce was already used
payee_signaturenot signed by the payee's key for this method, path and body

Nothing was read or changed. A scoped credential of another kind answers 403 credential_scope instead.

On the hosted tier, Authorization carries the tenant's API key (Bearer …) and the payee proof goes in a separate Dynamo-Payee header; the front door forwards it to the payee route. A proof sent in Authorization alone answers 401 unauthorized at the front door. A scoped payee credential may be sent as Bearer … in Authorization on its own.

What to do

On the wire

HTTP 401.

{
  "error": "unauthorized",
  "reason": "payee_credential",
  "detail": "a fresh Dynamo-Payee signature by the serviceNode key is required (fail closed)"
}

The detail wording differs slightly between routes; the reason is the same.

See getting paid as a payee and all error codes.