{"id":31589365,"url":"https://github.com/atsb/ap2-payment-processor","last_synced_at":"2025-10-06T02:52:18.052Z","repository":{"id":318221862,"uuid":"1070408252","full_name":"atsb/AP2-Payment-Processor","owner":"atsb","description":"This is the first AP2 (Agent Payments Protocol) Simulated Message Processing System that is able to process and settle AP2 payments","archived":false,"fork":false,"pushed_at":"2025-10-05T21:31:18.000Z","size":17,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-05T22:32:58.581Z","etag":null,"topics":["agent-payments-protocol","ap2","message-processing","payment-processing","payments","protocol"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/atsb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-05T21:24:09.000Z","updated_at":"2025-10-05T21:44:02.000Z","dependencies_parsed_at":"2025-10-05T22:33:03.981Z","dependency_job_id":null,"html_url":"https://github.com/atsb/AP2-Payment-Processor","commit_stats":null,"previous_names":["atsb/ap2-payment-processor"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/atsb/AP2-Payment-Processor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atsb%2FAP2-Payment-Processor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atsb%2FAP2-Payment-Processor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atsb%2FAP2-Payment-Processor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atsb%2FAP2-Payment-Processor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atsb","download_url":"https://codeload.github.com/atsb/AP2-Payment-Processor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atsb%2FAP2-Payment-Processor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278551493,"owners_count":26005388,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-payments-protocol","ap2","message-processing","payment-processing","payments","protocol"],"created_at":"2025-10-06T02:52:12.953Z","updated_at":"2025-10-06T02:52:18.036Z","avatar_url":"https://github.com/atsb.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# AP2 Payment Processor\n\nThis repository implements the first working reference **AP2 Payment Processor**.  \nIt demonstrates how to construct, validate, and persist **AP2 Mandates** as Verifiable Credentials (VCs), following the [AP2 0.1-alpha specification](https://ap2-protocol.org/).\n\n---\n\n## 📖 What is AP2?\n\n**AP2 (Agent Protocol 2)** is an experimental open protocol for **auditable, intent-driven payments**.  \nIt defines a set of **Mandates** (VC types) that capture the lifecycle of a payment:\n\n- **IntentMandate** – a user's raw intent to pay\n- **CartMandate** – merchant checkout confirmation\n- **PaymentMandate** – finalized payment details\n- **RefundMandate** – refund of a prior payment\n- **FraudFlag** – fraud evidence attached to a prior mandate\n\n## Custom Mandate\n- **NettingMandate** – settlement netting between counterparties (traditional banking sector) for EOD batch processing\n\nEach mandate is a **W3C Verifiable Credential**, signed by the appropriate actor (user wallet, merchant, processor).  \nThe chain of mandates forms a **transparent, append-only audit trail**. This does NOT apply to the NettingMandate, which is a custom Mandate not known by W3C.\n\n---\n\n## ⚙️ What this Processor Does\n\nThis implementation provides:\n\n- A **MandateFactory** that builds spec-compliant VCs for each mandate type.\n- A **PaymentProcessor** that orchestrates flows:\n  - Payment (Intent → Cart → Payment)\n  - Refunds (linked to a prior PaymentMandate)\n  - Fraud flags (linked to any prior mandate)\n  - Netting obligations\n- A **Ledger** that persists transactions and enforces invariants.\n- An **AgentPrompt** loop that parses natural language commands into structured flows.\n\nThe design emphasizes:\n- **Spec compliance** (contexts, schemas, RevocationList2020)\n- **Auditability** (every mandate has a UUID, linkage to prior mandates, and explicit notes)\n- **Extensibility** (easy to add new mandate types)\n\n---\n\n## 🚀 Usage\n\n### 1. Start the Agent\n\n1. Double click the .exe file and you will be greeted by a 'AP2\u003e' prompt.\n\n### Example Prompts\n\n#### Basic Payment Flow\n\n```\nSend 5 GBP to Starbucks for Batch Brew\n```\nor\n```\nPay 5 GBP to Starbucks for Batch Brew\n```\n\n**Produces:** IntentMandate → CartMandate → PaymentMandate\n\n---\n\n#### Intent-Only\n\n```\nIntent for 5 GBP to RunFree for Red Shoes in Size 44\n```\n\n**Produces:** IntentMandate\n\n---\n\n#### Using Raw Intent JSON\n\n```\nuse ../intent_mandate_0_1.json\n```\n\nWill produce the following questions:\n\n```\nAmount for this intent: 500\nCurrency (default EUR): GBP\nReceiver (merchant id): Footlocker\n```\n\nAfter this, the raw intent will be fed into the payment processor and a VC IntentMandate will be created and the full happy path will continue. The raw intent is taken directly from the AP2 Protocol website, proving spec-compliance message processing.\n\n**Output:**\n\n```\nTXN txn-cf061aeb-01ba-4ceb-8943-66d36e74a28c | issuer:user-wallet -\u003e Footlocker 500.0 GBP\nvc_id of this PaymentMandate is: vc_id=urn:uuid:71badfed-69f9-4de4-a6aa-7dfde3865178\n```\n\n---\n\n#### Refund Flow\n\n```\nrefund urn:uuid:71badfed-69f9-4de4-a6aa-7dfde3865178 for 500 GBP\n```\n\n**Produces:**\n\n```\n[Agent] Please provide a reason for this refund: Accidental Transaction\n```\n\nThe `urn:uuid:71badfed-69f9-4de4-a6aa-7dfde3865178` is the `vc_id` of the PaymentMandate, which is per-spec.\n\n**Output:**\n\n```\nTXN refund-5ed1b74b-1d15-4476-8a4f-c55e1fddef8e | issuer:processor -\u003e Footlocker -500.0 GBP\n```\n\n---\n\n#### Netting Flow (Corporate Banking)\n\n```\nSend 500000 KRW from SHN to CNY settlement run DTP2 for Shares\n```\n\n**Produces:**\n\n```\n[Agent] Netting Finished.\n```\n\nThis prompt triggers the new Netting path for investment banks, commercial banking and corporate banking environments. The 'PaymentMandate' will only be sent 'after' Netting has finished (EOD Batch processing simulation).\n\nThis allows AP2 to be used within the traditional confines of the corporate banking structure.\n\n##### Example NettingMandate:\n\n```json\n{\n  \"@context\": [\n    \"https://www.w3.org/2018/credentials/v1\",\n    \"https://ap2-protocol.org/contexts/mandates/v1\",\n    \"https://w3id.org/security/v2\"\n  ],\n  \"id\": \"urn:uuid:a3f79c45-9176-4427-9ade-cba800312b58\",\n  \"type\": [\n    \"VerifiableCredential\",\n    \"NettingMandate\"\n  ],\n  \"issuer\": \"issuer:netting\",\n  \"issuanceDate\": \"2025-10-05T20:57:43Z\",\n  \"expirationDate\": \"2025-10-05T21:57:43Z\",\n  \"credentialSchema\": {\n    \"id\": \"https://ap2-protocol.org/schemas/mandate-schema.json\",\n    \"type\": \"JsonSchemaValidator2018\"\n  },\n  \"credentialStatus\": {\n    \"id\": \"https://ap2-protocol.org/status/registry#revocation-list-1\",\n    \"type\": \"RevocationList2020Status\"\n  },\n  \"credentialSubject\": {\n    \"label\": \"Netting obligation for settlement run DTP2\",\n    \"note\": \"Netting 500000.0\",\n    \"mandate_id\": \"c5c9fc56-0546-4e89-8b04-a0e600474908\",\n    \"prev_mandate_id\": \"urn:uuid:2c467e21-9688-4dea-a862-408709763ccd\",\n    \"prev_mandate_ids\": [\n      \"urn:uuid:2c467e21-9688-4dea-a862-408709763ccd\"\n    ],\n    \"timestamp\": \"2025-10-05T20:57:43Z\",\n    \"merchant_id\": \"CNY\",\n    \"payment_details\": {\n      \"amount\": 500000.0,\n      \"currency\": \"KRW\",\n      \"counterparty\": \"CNY\",\n      \"settlement_run\": \"DTP2\"\n    }\n  },\n  \"proof\": {\n    \"type\": \"Ed25519Signature2020\",\n    \"created\": \"2025-10-05T20:57:43Z\",\n    \"verificationMethod\": \"issuer:netting#keys-1\",\n    \"proofPurpose\": \"assertionMethod\",\n    \"proofValue\": \"1VtvDTkTvckVFFJ5btRz56isSKDku1FNwgbWamr2wnDJwosaprrYni6ALiTimkVpXoMdB6CF8VtviDgjuY3Fy2z\"\n  }\n}\n```\n\n##### Complete Mandate Chain Output:\n\n```\nTXN txn-f6443613-0ba8-4c31-9438-3195500d0f53 | SHN -\u003e CNY 500000.0 KRW\nMandate Chain:\n ├─ IntentMandate (mandate_id=c1b03b47-e649-4b3e-88a9-f2a45a5b16cf, vc_id=urn:uuid:78c12433-5204-4204-87c7-1919b131f170)\n    merchant=CNY issuer=issuer:user-wallet exp=2025-10-05T21:57:43Z\n ├─ CartMandate (mandate_id=e716c58e-1dc1-4c34-b648-cb884315aff3, vc_id=urn:uuid:2c467e21-9688-4dea-a862-408709763ccd)\n    merchant=CNY issuer=issuer:merchant exp=2025-10-05T21:57:43Z\n ├─ NettingMandate (mandate_id=c5c9fc56-0546-4e89-8b04-a0e600474908, vc_id=urn:uuid:a3f79c45-9176-4427-9ade-cba800312b58)\n    merchant=CNY issuer=issuer:netting exp=2025-10-05T21:57:43Z\n └─ PaymentMandate (mandate_id=89f7f94d-a74f-407c-a6f9-4b93928a059c, vc_id=urn:uuid:9c0636ff-4f12-4f99-83f8-23b390c0bd1c)\n    merchant=CNY issuer=issuer:processor exp=2025-10-05T21:57:43Z\n```\n\n---\n\n#### Fraud Flag\n\n```\nflag urn:uuid:9c0636ff-4f12-4f99-83f8-23b390c0bd1c\n```\n\n**Produces:**\n\n```\n[Agent] Please provide a reason for this fraud initiation: Unauthorized\n```\n\nThis flags a PaymentMandate as a fraudulent transaction and sends this to the processor to nullify it (0.0 amounts) which then directs it to the merchant / counterparty.\n\n**Output:**\n\n```\nTXN fraud-8ccdcb36-b19e-4cf2-856a-87d9d40a5529 | issuer:processor -\u003e CNY 0.0 KRW\nMandate Chain:\n └─ FraudFlag (mandate_id=9643a3aa-573e-4450-b325-9875c057e996, vc_id=urn:uuid:06bc8ed0-ef18-4274-8da3-e99cbc8d0c1c)\n    merchant=n/a issuer=issuer:processor exp=2025-10-05T22:02:17Z\n```\n\n---\n\n## 🔗 Mandate Chain\n\nEvery transaction creates an auditable chain of linked mandates:\n\n1. **IntentMandate** - User initiates payment intent\n2. **CartMandate** - Merchant confirms cart details\n3. **NettingMandate** (optional) - Settlement netting for corporate banking\n4. **PaymentMandate** - Processor finalizes payment\n5. **RefundMandate** / **FraudFlag** (optional) - Post-payment actions\n\nEach mandate references the previous mandate via `prev_mandate_id`, creating a complete audit trail.\n\n---\n\n## 📋 Mandate Types\n\n| Mandate Type | Issuer | Purpose |\n|-------------|--------|---------|\n| **IntentMandate** | User Wallet | Express payment intent |\n| **CartMandate** | Merchant | Confirm checkout details |\n| **NettingMandate** | Netting Service | EOD batch settlement |\n| **PaymentMandate** | Processor | Finalize payment |\n| **RefundMandate** | Processor | Issue refund |\n| **FraudFlag** | Processor | Flag fraudulent activity |\n\n---\n\n## 🏦 Corporate Banking Integration\n\nThe **NettingMandate** enables AP2 to integrate with traditional banking workflows:\n\n- Supports end-of-day (EOD) batch processing\n- Settlement run identification (e.g., DTP2)\n- Counterparty netting for investment and commercial banking\n- Payment execution only after netting completion\n\nThis bridges the gap between the AP2 payment protocol and traditional corporate banking infrastructure.\n\n---\n\n## 🔐 Security \u0026 Compliance\n\n- All mandates are **W3C Verifiable Credentials** (except NettingMandate)\n- Signed with **Ed25519Signature2020**\n- Support for **RevocationList2020Status**\n- Complete audit trail with timestamp and issuer verification\n- Immutable mandate chain with cryptographic linkage\n\n---\n\n## 📝 License\n\nThis is a reference implementation for the AP2 protocol. See [ap2-protocol.org](https://ap2-protocol.org/) for specification details.  Source code will be released soon under a business friendly licence.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatsb%2Fap2-payment-processor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatsb%2Fap2-payment-processor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatsb%2Fap2-payment-processor/lists"}