1. Pilot Profile

1.1 Purpose

The subsections in this document are normative for the push-payment pilot under YONA Ruleset 1.0.

This pilot focuses on:

• yona.authorization_request in push-payment form
• yona.authorization_response terminal outcomes
• DID discovery, JOSE validation, request/response binding, and deterministic endpoint behavior

1.2 Scope boundary

The pilot includes push-payment authorization behavior only.

The pilot excludes:

• YonaPaymentIntentService
• yona.retrieve_intent
• yona.payment_intent
• pull-payment retrieval path
• pull-specific embedded_payment_intent handling
• pull-specific binding cases
• a full YONA conformance claim

A participant that completes this pilot has validated the push-payment authorization interface only.

In this pilot, the beneficiary reference is beneficiary_handle.

beneficiary_handle identifies the beneficiary context within the beneficiary VASP.

Originator VASPs MUST treat beneficiary_handle as opaque and MUST NOT infer settlement instructions from it.

1.3 Outside YONA scope

A non-normative description of out-of-YONA activities (for example, existing Travel Rule, custody, and settlement providers) is in Pilot Overview ( What stays unchanged). This pilot does not change YONA's scope boundaries.

YONA does not define:

• Travel Rule payloads
• settlement instructions
• settlement execution
• custody
• local compliance policy
• post-ACCEPT message transport

Those activities remain outside YONA and occur only after a valid ACCEPT, if the participating VASPs choose to proceed.

Pilot completion and a valid ACCEPT do not establish counterparty approval, regulatory eligibility, Travel Rule readiness, or settlement approval outside the tested YONA authorization interface.

1.4 Required pilot capabilities

To claim pilot support accurately, an implementation MUST cover the following technical baseline as applicable to the role or roles it implements.

1.4.1 Discovery

An implementation MUST support did:web resolution for YONA interactions.

For this pilot, the beneficiary-side authorization endpoint is identified through a DID document service entry.

A beneficiary-side pilot implementation MUST publish a DID document service entry whose type value is YonaAuthorizationService.

That type value identifies the service entry as the beneficiary-side YONA authorization endpoint for interoperability under this pilot.

The corresponding serviceEndpoint value in that service entry is the HTTPS endpoint to which the originator sends the push-payment yona.authorization_request.

An originator-side pilot implementation MUST resolve the beneficiary DID document, locate the service entry whose type is YonaAuthorizationService, and use that entry's serviceEndpoint as the authorization endpoint.

If the required DID document cannot be resolved, or if the required YonaAuthorizationService service entry is missing, invalid, or unusable, the initiating implementation MUST NOT send the YONA request and MUST NOT proceed as if ACCEPT occurred.

1.4.2 Transport

Pilot requests and responses MUST use HTTPS POST and JWS Compact Serialization.

The request Content-Type MUST be application/jose.

Pilot clients MUST send Accept: application/jose.

1.4.3 Push-payment authorization messages

The pilot request message is yona.authorization_request in push-payment form.

The pilot response message is terminal yona.authorization_response.

All YONA signed messages in this pilot include the common required claims:

• iss
• aud
• iat
• exp
• jti
• message_type
• ruleset_id

For authorization messages in this pilot, intent_id is also required.

The push form of yona.authorization_request uses:

• beneficiary_handle
• payment_terms
• intended_asset_type

The terminal yona.authorization_response uses:

• intent_id
• decision
• request_jws_sha256

A valid pilot response is a valid, verified terminal response bound to the exact request bytes through request_jws_sha256.

1.4.4 Binding

Implementations MUST preserve the exact request bytes used for hashing and comparison.

request_jws_sha256 MUST be computed over the exact JWS Compact Serialization of the request, not over decoded JSON, reconstructed JOSE objects, normalized strings, trimmed strings, or reserialized content.

1.4.5 Terminal outcomes

The only terminal authorization outcomes are ACCEPT and REJECT.

If the originator VASP does not receive a valid terminal yona.authorization_response within 60 seconds, the result is NO_RESPONSE.

NO_RESPONSE MUST be treated as REJECT.

No implementation may proceed to post-ACCEPT steps without a valid, verified terminal ACCEPT.

1.5 Role, flow, and endpoint mapping

Role under test:

• originator client
• beneficiary server
• or both, as implemented

Interaction scope:

• push only

Flow exercised:

• push-payment authorization

Endpoint exercised:

• the beneficiary-side serviceEndpoint published in the DID document service entry whose type is YonaAuthorizationService

Service publication on the beneficiary side:

• a DID document service entry with type: "YonaAuthorizationService" MUST be published
• YonaPaymentIntentService is not required for pilot-only claims

1.6 Pilot claim language

Pilot claims MUST be explicit and non-ambiguous.

A successful participant MAY state:

"Completed the YONA push-payment pilot under yona:ruleset:v1.0; not a full YONA conformance claim."

A pilot claim MUST NOT be presented as full YONA conformance, certification, registry approval, or endorsement.

1.7 Transition to full BIP

This pilot is the lower-lift path for early interface validation.

A participant that later expands to full BIP MUST add the retrieval, pull-payment, and other newly applicable full-BIP material.

A participant that already passed this pilot for the same implementation version and material configuration SHOULD carry those passed push-applicable results forward rather than repeating them.

2. Pilot Test Suite

2.1 Purpose

This section defines the pilot verification basis.

It identifies the push-payment authorization subset of the YONA Conformance Test Suite that applies to this pilot. It does not replace that companion document, and pilot participants MUST use the referenced cases, fixtures, expected outcomes, pass criteria, and supporting details when testing pilot support.

Pilot participants MAY test locally against fixtures, expected outcomes, and their own test harnesses, or bilaterally against another implementation. A live interVASP counterparty is allowed, but not required for pilot support.

In this section, references to the authorization endpoint mean the beneficiary-side serviceEndpoint published in the DID document service entry whose type is YonaAuthorizationService.

It does not define a different verification model.

2.2 Core valid-path cases

See YONA Conformance Test Suite Section 5.2 for more details.

Execute the following required valid-path cases:

• BIP-VAL-004
• BIP-VAL-005
• BIP-VAL-006
• BIP-VAL-007

These cases cover:

• valid push-payment yona.authorization_request
• valid terminal yona.authorization_response
• repeated materially equivalent requests
• repeated materially changed requests

2.3 Required Invalid-Field Cases

2.3.1 yona.authorization_request (beneficiary server receives)

2.3.1.1 Common fields for both request forms

Apply MISSING, WRONG_TYPE, and BAD_VALUE to:

• iss
• aud
• iat
• exp
• jti
• message_type
• ruleset_id
• intent_id

Minimum BAD_VALUE examples (non-exhaustive) that MUST be covered:

• message_type != yona.authorization_request
• ruleset_id != yona:ruleset:v1.0
• invalid intent_id
• non-integer iat or exp
• expired exp

2.3.1.2 Push-payment form

Apply MISSING, WRONG_TYPE, and BAD_VALUE to:

• beneficiary_handle
• payment_terms
• payment_terms.amount
• payment_terms.amount_units
• payment_terms.currency
• intended_asset_type

Minimum BAD_VALUE examples (non-exhaustive) that MUST be covered:

• invalid beneficiary_handle
• aud mismatch with the DID encoded in beneficiary_handle
• non-canonical amount
• amount_units != minor
• non-canonical currency
• invalid CAIP-19 intended_asset_type

2.3.1.3 Request-form classification and mixed-field cases

Reject:

• push fields plus embedded_payment_intent
• invalid hybrid request forms
• push form missing intended_asset_type

2.3.2 yona.authorization_response (originator client receives)

Apply MISSING, WRONG_TYPE, and BAD_VALUE to:

• iss
• aud
• iat
• exp
• jti
• message_type
• ruleset_id
• intent_id
• decision
• request_jws_sha256

Minimum BAD_VALUE examples (non-exhaustive) that MUST be covered:

• message_type != yona.authorization_response
• ruleset_id != yona:ruleset:v1.0
• decision not equal to ACCEPT or REJECT
• iss != authorization_request.aud
• aud != authorization_request.iss
• intent_id != authorization_request.intent_id
• request_jws_sha256 mismatch
• expired exp
• replayed jti

2.4 Duplicate JSON Member Tests

See YONA Conformance Test Suite Section 7 for more details.

Execute cases covering:

• BIP-DUP-003
• BIP-DUP-004

Expected result:

• message is invalid
• receiver MUST reject
• for authorization, the receiver MUST return terminal REJECT if bindable; otherwise it MUST NOT return a YONA response message

In this section, bindable means the beneficiary server can preserve the exact request bytes, extract iss, aud, and intent_id as strings from the payload bytes, and sign a response.

2.5 DID / JOSE / Signature Profile Matrix

See YONA Conformance Test Suite Section 8 for more details.

Execute:

• BIP-SIG-001 through BIP-SIG-012

These cases cover:

• malformed compact JWS
• invalid or missing JOSE protected-header values
• DID resolution failures
• key lookup failures
• unauthorized or unusable keys
• signature verification failures
• issuer/key mismatches
• missing or unusable required service entries

For this pilot, the required service entry is the DID document service entry whose type is YonaAuthorizationService, and the endpoint selected from that entry is its serviceEndpoint.

If the DID resolves but the required YonaAuthorizationService service entry is missing, invalid, or unusable, the client MUST NOT send the request and MUST NOT proceed as if ACCEPT occurred.

2.6 request_jws_sha256 Tests

See YONA Conformance Test Suite Section 9 for more details.

Execute:

• BIP-HASH-001 through BIP-HASH-005

Expected result:

• exact-byte binding passes
• non-exact-byte binding fails

These cases verify that request_jws_sha256 is computed from the exact request bytes, not from decoded or reserialized content.

2.7 Malformed JOSE Body Tests

See YONA Conformance Test Suite Section 10 for more details.

Execute:

• BIP-JOSE-001 through BIP-JOSE-009

These cases cover:

• malformed request bodies
• invalid base64url segments
• invalid UTF-8 JSON payloads
• non-JSON payloads
• malformed authorization responses
• non-200 response handling
• wrong content type
• terminal responses that arrive too late

Expected result:

• unbindable request bodies MUST NOT produce a YONA response message
• malformed or unusable authorization responses count as no valid terminal response obtained
• if no valid terminal response is obtained by the cutoff, the result is NO_RESPONSE
• NO_RESPONSE MUST be treated as REJECT

2.8 Wrong-Binding Cases

See YONA Conformance Test Suite Section 11 for more details.

Execute:

• BIP-BIND-007
• BIP-BIND-008
• BIP-BIND-009
• BIP-BIND-010
• BIP-BIND-011

These cases cover:

• aud mismatch with the DID encoded in beneficiary_handle
• response iss mismatch
• response aud mismatch
• response intent_id mismatch
• request_jws_sha256 mismatch

Expected result:

• the beneficiary rejects wrong-bound push requests
• the originator rejects wrong-bound authorization responses

The originator MUST NOT act on decision unless signature verification, iss, aud, intent_id, and request_jws_sha256 validation all succeed.

2.9 Replay and Freshness Tests

2.9.1 Signed-message replay tests

Replay exact valid yona.authorization_response under local replay policy.

A replayed response MUST NOT be treated as a new valid message.

2.9.2 Repeated yona.authorization_request tests

Apply repeated-request tests to yona.authorization_request within the same (iss, intent_id) scope.

The repeated-request tests MUST cover:

• a materially equivalent repeat with only non-material differences such as jti, iat, exp, kid, or signature bytes
• a materially changed repeat with one or more material authorization inputs changed
• a repeated request that receives a newly generated response bound to the repeated request bytes

Expected result:

• a materially equivalent repeat MUST NOT be treated as a replay solely because it is newly signed
• a materially equivalent repeat MUST receive the same terminal decision, newly bound to the repeated request bytes
• a materially changed repeat MUST be handled according to the repeated-request outcome rules

2.9.3 Freshness tests

Apply freshness tests to authorization messages:

• valid exp
• expired exp
• boundary exp

The expected boundary-case outcome MUST be documented and applied consistently.

2.10 Prohibited Content Tests

Inject prohibited content into defined fields of:

• push-form yona.authorization_request
• yona.authorization_response

These tests MUST cover prohibited content such as Travel Rule payload data, destination addresses, settlement instructions, or other prohibited content where the ruleset requires rejection.

These tests MUST NOT assume a global detector for unknown fields.

2.11 Byte-Exact Hashing Fixtures for request_jws_sha256

For hashing and comparison, implementations MUST use the exact JWS Compact Serialization of the published raw artifact. Reserialized JSON, reconstructed JOSE objects, normalized strings, trimmed strings, or reformatted document renderings are not equivalent.

2.11.1 Fixture publication rule

For this pilot, the following raw artifacts are published as companion fixtures:

• fixture-a-push-authorization-request.jws
• fixture-c-authorization-response.jws
• expected.json

expected.json records the expected SHA-256 digests (hex and base64url) and request-binding values for these fixtures, plus fixture metadata. If a rendered HTML or PDF representation wraps lines or otherwise alters presentation, the raw artifact bytes remain authoritative.

2.11.2 Fixture A — Push-payment authorization request

Raw artifact: fixture-a-push-authorization-request.jws

Exact JWS Compact Serialization:

eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDp3ZWI6b3JpZ2luYXRvci5leGFtcGxlI2sxIn0.eyJpc3MiOiJkaWQ6d2ViOm9yaWdpbmF0b3IuZXhhbXBsZSIsImF1ZCI6ImRpZDp3ZWI6YmVuZWZpY2lhcnkuZXhhbXBsZSIsImlhdCI6MTc2MDAwMjAwMCwiZXhwIjoxNzYwMDAyMDYwLCJqdGkiOiJqdGlfcHVzaF9hdXRob3JpemF0aW9uX3JlcXVlc3RfMDAwMSIsIm1lc3NhZ2VfdHlwZSI6InlvbmEuYXV0aG9yaXphdGlvbl9yZXF1ZXN0IiwicnVsZXNldF9pZCI6InlvbmE6cnVsZXNldDp2MS4wIiwiaW50ZW50X2lkIjoib3JpZ2luYXRvcl9wdXNoX2ludGVudF8wMDAxIiwiYmVuZWZpY2lhcnlfaGFuZGxlIjoiZGlkPWRpZDp3ZWI6YmVuZWZpY2lhcnkuZXhhbXBsZTthbGlhcz1hbGlhc18wMDAxIiwicGF5bWVudF90ZXJtcyI6eyJhbW91bnQiOiIxMjUwIiwiYW1vdW50X3VuaXRzIjoibWlub3IiLCJjdXJyZW5jeSI6IlVTRCJ9LCJpbnRlbmRlZF9hc3NldF90eXBlIjoiZWlwMTU1OjEvZXJjMjA6MHhBMGI4Njk5MWM2MjE4YjM2YzFkMTlENGEyZTlFYjBjRTM2MDZlQjQ4In0.AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0-Pw

Decoded header (non-normative, reference only):

{
  "alg": "EdDSA",
  "typ": "JWT",
  "kid": "did:web:originator.example#k1"
}

Decoded payload (non-normative, reference only):

{
  "iss": "did:web:originator.example",
  "aud": "did:web:beneficiary.example",
  "iat": 1760002000,
  "exp": 1760002060,
  "jti": "jti_push_authorization_request_0001",
  "message_type": "yona.authorization_request",
  "ruleset_id": "yona:ruleset:v1.0",
  "intent_id": "originator_push_intent_0001",
  "beneficiary_handle": "did=did:web:beneficiary.example;alias=alias_0001",
  "payment_terms": {
    "amount": "1250",
    "amount_units": "minor",
    "currency": "USD"
  },
  "intended_asset_type": "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}

Expected output

2.11.3 Fixture C — Authorization response referencing Fixture A

Fixture C is a terminal yona.authorization_response paired with Fixture A. The request_jws_sha256 claim in this response is the base64url(SHA-256(exact Fixture A compact JWS bytes)) (the same value as the “expected request_jws_sha256” row in Section 2.11.2).

Raw artifact: fixture-c-authorization-response.jws

Exact response JWS Compact Serialization

eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDp3ZWI6YmVuZWZpY2lhcnkuZXhhbXBsZSNrMSJ9.eyJpc3MiOiJkaWQ6d2ViOmJlbmVmaWNpYXJ5LmV4YW1wbGUiLCJhdWQiOiJkaWQ6d2ViOm9yaWdpbmF0b3IuZXhhbXBsZSIsImlhdCI6MTc2MDAwMjAwMSwiZXhwIjoxNzYwMDAyMDYxLCJqdGkiOiJqdGlfcHVzaF9hdXRob3JpemF0aW9uX3Jlc3BvbnNlXzAwMDEiLCJtZXNzYWdlX3R5cGUiOiJ5b25hLmF1dGhvcml6YXRpb25fcmVzcG9uc2UiLCJydWxlc2V0X2lkIjoieW9uYTpydWxlc2V0OnYxLjAiLCJpbnRlbnRfaWQiOiJvcmlnaW5hdG9yX3B1c2hfaW50ZW50XzAwMDEiLCJkZWNpc2lvbiI6IkFDQ0VQVCIsInJlcXVlc3RfandzX3NoYTI1NiI6Ik9QR3BUd3o1Z3lFckZ6aXNvdVVPcTU0Yk95QjZuejNDb2hpWG1HLVBzQTQifQ.CQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQ

Decoded header (non-normative, reference only):

{
  "alg": "EdDSA",
  "typ": "JWT",
  "kid": "did:web:beneficiary.example#k1"
}

Decoded payload (non-normative, reference only):

{
  "iss": "did:web:beneficiary.example",
  "aud": "did:web:originator.example",
  "iat": 1760002001,
  "exp": 1760002061,
  "jti": "jti_push_authorization_response_0001",
  "message_type": "yona.authorization_response",
  "ruleset_id": "yona:ruleset:v1.0",
  "intent_id": "originator_push_intent_0001",
  "decision": "ACCEPT",
  "request_jws_sha256": "OPGpTwz5gyErFzisouUOq54bOyB6nz3CohiXmG-PsA4"
}

2.12 Deterministic REJECT vs NO_RESPONSE Decision Table

Use the following decision logic for a beneficiary server receiving yona.authorization_request:

Client interpretation:

• if no valid, verified terminal response is obtained within 60 seconds, the outcome is NO_RESPONSE
• NO_RESPONSE MUST be treated as REJECT

2.13 Pilot pass criteria

A pilot support claim is supportable only when:

1. all applicable pilot-required cases are executed;
2. all applicable pilot-required cases pass with deterministic outcomes; and
3. the report clearly identifies what was in scope and what was intentionally excluded.

Passing this pilot does not establish full YONA conformance.

3. Pilot Report Format

3.1 Purpose

This section defines the minimum report content for a pilot-support statement.

It provides a compact report format for documenting pilot execution, scope, case results, and supporting evidence.

It is aligned to the style of the YONA Conformance Report Template, but scoped specifically to the YONA push-payment pilot. It does not define a different verification model.

3.2 Required report fields

A pilot report MUST record:

• report metadata, including:
  • report title or identifier
  • report date
  • report type (self-asserted, internal, bilateral, or third-party)
  • assessor identity, including organization and responsible person or team
  • organization whose implementation was evaluated
• implementation under test, including:
  • implementation name
  • implementation version
  • source revision, build identifier, or equivalent artifact identifier
  • test environment identifier or description
• governing artifacts, including:
  • the pilot document identifier or version used for the evaluation
  • tested ruleset_id
  • the YONA Conformance Test Suite identifier or version used
  • any companion fixture set or raw-artifact identifier used during testing
• tested role or roles:
  • originator
  • beneficiary
  • or both, as implemented
• interaction scope:
  • push-payment authorization only
• flow coverage:
  • push-payment authorization only
• endpoint coverage:
  • the beneficiary-side serviceEndpoint published in the DID document service entry whose type is YonaAuthorizationService
• material configuration inputs that can affect deterministic outcomes, including as applicable:
  • DID resolution setup
  • JOSE and protected-header validation behavior
  • key-selection and verification behavior
  • freshness handling
  • replay handling
  • repeated-request handling
  • timeout and NO_RESPONSE handling
  • any local policy choices that materially affect pilot-required outcomes
• case-by-case execution results for all applicable pilot-required cases, including for each executed case:
  • exact case identifier
  • short case description or case group
  • observed result
  • pass or fail result
  • evidence pointer or evidence identifier
• case-level treatment of anything not executed as a passing case, including:
  • not applicable, with reason
  • excluded, with reason
  • failed, with reason
• evidence inventory sufficient to support the reported result, including as applicable:
  • JWS samples or fixture references
  • DID documents or DID resolution records
  • endpoint request and response traces
  • signature-verification evidence
  • exact-byte hashing evidence for request_jws_sha256
  • binding recomputation evidence
  • replay and freshness traces
  • timeout or NO_RESPONSE timing evidence
• explicit declaration that retrieval and pull-only sections were out of scope for this pilot report
• explicit statement that the report is a pilot-support statement only and not a full YONA conformance claim

A pilot report MUST make clear which applicable pilot-required cases were executed and passed.

A pilot report MUST NOT imply full YONA conformance from pilot-only results.

3.3 Suggested pilot claim statement

"[Organization / implementation] completed the YONA push-payment pilot for the scope documented in this report under yona:ruleset:v1.0. This report records the roles tested, applicable pilot-required cases executed, observed results, and supporting evidence. This is a pilot-support statement only and not a full YONA conformance claim."

3.4 Pilot report checklist

• ☐ Report metadata recorded
• ☐ Tested YONA documents and versions identified
• ☐ Pilot scope recorded
• ☐ Material configuration inputs recorded
• ☐ Applicable cases, results, and evidence recorded
• ☐ Any exclusions or failures explained
• ☐ Pull-only content marked out of scope
• ☐ Full YONA conformance not claimed