KYAPay Profile

2.1.1. Buy-Side Roles

Buyer Agent:

An Agent performing tasks on behalf of a Buyer Principal, that has its own Agent Identity.¶

Buyer Agent Platform:

The Agent Platform hosting the Buyer Agent. Some use cases require the Platform to have its own verified identity assertions, grouped into the apd claim.¶

Buyer Identity:

The aggregate verified identity assertions of the buy-side entities, typically encompassing the Buyer Principal, the Buyer Agent Platform, and the Buyer Agent itself. This composite identity is conveyed via the KYA token, allowing the seller to verify the entire chain of responsibility behind a request. Grouped into the bid claim.¶

Buyer Principal:

A legal entity (human or organization) behind the purchase / consumption of a product or service. The Principal typically interacts with the seller via a Buyer Agent. Many sellers are required to be able to determine the Buyer Identity in order to comply with KYC/AML regulations, accounting standards, and to maintain a direct customer relationships.¶

2.1.2. Sell-Side Roles

Seller Agent:

An Agent performing tasks on behalf of a Seller Principal, directly interacting with Buyer Agents to facilitate discovery and purchase. Typically runs on Internet-connected infrastructure, and discoverable via service directories.¶

Seller Agent Platform:

The Agent Platform that hosts Seller Agents.¶

Seller Identity:

The aggregate verified identity assertions of the sell-side entities, typically encompassing the Seller Principal, the Seller Agent Platform, as well as the Seller Agent Identity. These various aspects of Seller Identity allow Buyers and Buyer Agents to perform reputation-based logic, to verify that they are interacting with the authorized (and expected) counter-party, and to fulfill KYC/AML regulation requirements.¶

Seller Principal:

A legal entity (human or organization) that owns the product, service, or content being sold, and serves as the ultimate beneficiary of a business transaction.¶

2.1.3. Ecosystem Infrastructure Roles

Identity Token Issuer:

A trusted neutral entity that conducts Know Your Customer (KYC) and Know Your Business (KYB) verifications. It is responsible for issuing cryptographically signed kya tokens that attest to the identity of the Principal, Agent, and Agent Platform, for both Buyers and Sellers.¶

Payment Token Issuer:

A trusted entity responsible for facilitating the exchange of payments and credentials between the Buyer and Seller. It issues signed pay tokens that enable settlement via various schemes (Cards, Banks, Cryptocurrency), without exposing raw credentials or secrets.¶

3.2.1. bid - Buyer Identity Sub-claims

The Buyer Identity (bid) claim contains sub-claims useful for buyer use cases, as follows.¶

email:

REQUIRED - Buyer email.¶

3.2.2. Agent Platform Identity apd Sub-claims

The apd claim is optional. If present, it contains the following sub-claims.¶

id:

REQUIRED - Agent Platform identifier.¶

name:

REQUIRED - Agent Platform name.¶

email:

OPTIONAL - Email associated with agent platform.¶

phone_number:

OPTIONAL - Phone number associated with agent platform.¶

organization_name:

OPTIONAL - Legal name associated with agent platform.¶

verifier:

OPTIONAL - URL of the Identity Verifier¶

verification_status:

OPTIONAL - Verification status. One of "VERIFIED", "UNVERIFIED".¶

verification_id:

OPTIONAL - Verification identifier. Identifier for the verification performed, such as a GUID.¶

3.2.3. Agent Identity aid Sub-claims

The aid claim is optional. If present, it contains the following sub-claims.¶

name:

REQUIRED - Agent name. The name should reflect the business purpose of the agent.¶

creation_ip:

OPTIONAL - The public IP address of the system / agent that requested the token. Its value is a string containing the public IPv4 or IPv6 address from where the token request originated. It MUST be captured directly from the token request.¶

source_ips:

OPTIONAL - Valid public IP address, or range of public IP addresses, from where the system / agent's requests to merchants / services will originate. Array of comma-separated IPv4 addresses or ranges, IPv6 addresses or ranges, or domain names resolvable to an IP address via DNS. IPv4 and IPv6 addresses can be a single IPv4 or IPv6 address or a range of IPv4 or IPv6 addresses in CIDR notation or start-and-end IP pairs.¶

3.3.1. Agent Identity sti Sub-claims

The sti claim is optional. If present, it MAY contain the following sub-claims, all of which are OPTIONAL.¶

type:

REQUIRED - "type" is dependant on the "stp" value; for "COIN" - "USDC" or "x402"; for "CARD" - "VISA_VIC"¶

paymentToken:

OPTIONAL - String containing Virtual Payment Card Number in ISO/IEC 7812 format. 12-19 characters.¶

tokenExpirationMonth:

OPTIONAL - String containing two-digit Expiration Month Number.¶

tokenExpirationYear:

OPTIONAL - String containing four-digit Expiration Year.¶

tokenSecurityCode:

OPTIONAL - String containing 3 or 4 digit CVV code.¶

3.3.2. PAY Token Example

The following informative example displays a decoded PAY type token.¶

{
  "kid": "FgT4q8c5IqbBCCjcho5JdeGQvuK1keMDFc9IwCm8J7Y", // JWK Key ID
  "alg": "ES256",
  "typ": "pay+jwt"
}.{
  "iss": "https://example.net/pay_token_issuer", // Issuer URL
  "iat": 1742245254,
  "exp": 1773867654,
  "jti": "b9821893-7699-4d24-af06-803a6a16476b",
  "sub": "8b810549-7443-494f-b4ad-5bc65871e32b", // Buyer Agent Account ID
  "aud": "37888095-2721-48d9-a2df-bfe4075f223a", // Seller Agent Account ID

  "env": "sandbox",
  "ver": "1",
  "ssi": "274efc47-024e-466f-b278-152d2ee73955", // Seller Service ID
  "btg": "16c135ce-a99a-453d-a7b5-4958fd91de5f", // Buyer Tag (Internal Reference ID)

  "spr": "0.01",
  "sps": "PAY_PER_USE",
  "amount": "15",
  "cur": "USD",
  "value": "15000000",
  "mnr": 1500,
  "stp": "CARD",
  "sti": {
    "type": "VISA_VIC",
    "paymentToken": "1234567890123456",
    "tokenExpirationMonth": "03",
    "tokenExpirationYear": "2030",
    "tokenSecurityCode": "123",
    "verifier": "https://verifier.example.info", // URL of payment method verifier
    "verification_status": "VERIFIED", // Outcome of the verifier's payment method verification - one of "VERIFIED", "UNVERIFIED" (OPTIONAL)
    "verification_id": "3a6e1b76-8f78-4c24-b1bd-dc78a8cc3711" // Identifier for the verification performed, such as a GUID.
  }
}

4.1.1. JWT Header Validation

1. alg - JWTs MUST be signed using allowed JWA algorithms (currently, ES256).¶

2. kid - The kid claim MUST be present, and set to a valid key id discoverable via the issuer's (payload iss claim) JWK Set.¶

3. typ - The typ claim MUST be one of: kya+jwt, pay+jwt, or kya-pay+jwt.¶

4.1.2. JWT Payload Validation

1. Verify JWT Signature - Valid JWTs MUST be signed with a valid key belonging To the token's issuer (iss claim)¶

2. Validate iss Claim - Ensure that the token is signed by the expected valid issuer.¶

3. Validate the exp Claim - The verifier MUST validate that the token has not expired, within the verifier's clock drift tolerance.¶

4. Validate the iat Claim - The verifier MUST validate that the token was issued in the past, within the verifier's clock drift tolerance.¶

5. Validate the jti Claim - Ensure that the jti claim is present, and is a UUID.¶

6. Validate the aud Claim - ...¶

7. Validate the env Claim - Ensure that the Environment claim is set to an expected and usecase-appropriate value (such as production, sandbox, etc.)¶