@t-0/provider-starter-ts 1.1.13 → 1.1.15

package/README.md

@@ -15,19 +15,25 @@ The CLI will prompt for a project name, then create a ready-to-run project with
 ```
 your-project-name/
 ├── src/
-│   ├── index.ts              # Entry point
-│   ├── service.ts            # Provider service implementation
-│   ├── publish_quotes.ts     # Quote publishing logic
-│   ├── get_quote.ts          # Quote retrieval logic
-│   ├── submit_payment.ts     # Payment submission logic
-│   └── lib.ts                # Utility functions
-├── Dockerfile                # Docker configuration
-├── .env                      # Environment variables (with generated keys)
-├── .env.example              # Example environment file
-├── .eslintrc.json            # ESLint configuration
-├── .gitignore                # Git ignore rules
-├── package.json              # Project dependencies
-└── tsconfig.json             # TypeScript configuration
+│   ├── index.ts                                  # Entry point
+│   ├── service.ts                                # Phase 2: ProviderService handlers
+│   ├── payment_intent_pay_in_service.ts          # Phase 3A: PayInProviderService handler
+│   ├── payment_intent_beneficiary_service.ts     # Phase 3B: BeneficiaryService handler
+│   ├── publish_quotes.ts                         # Phase 1: payout quote publishing
+│   ├── get_quote.ts                              # Phase 1: quote retrieval
+│   ├── publish_payment_intent_quotes.ts          # Phase 3A: pay-in quote publishing
+│   ├── get_payment_intent_quote.ts               # Phase 3B: indicative quote retrieval
+│   ├── create_payment_intent.ts                  # Phase 3B: create a payment intent
+│   ├── confirm_funds_received.ts                 # Phase 3A: confirm funds received
+│   ├── submit_payment.ts                         # Phase 2: payment submission
+│   └── lib.ts                                    # Utility functions
+├── Dockerfile                                    # Docker configuration
+├── .env                                          # Environment variables (with generated keys)
+├── .env.example                                  # Example environment file
+├── .eslintrc.json                                # ESLint configuration
+├── .gitignore                                    # Git ignore rules
+├── package.json                                  # Project dependencies
+└── tsconfig.json                                 # TypeScript configuration
 ```
 
 ## Key Files to Modify
@@ -64,6 +70,26 @@ your-project-name/
 4. Test payment submission by uncommenting the `submitPayment` call in `src/index.ts`.
 5. Coordinate with the T-0 team to test end-to-end payment flows.
 
+### Phase 3: Payment Intent Flow
+
+The payment intent flow is independent of Phase 2. It is an asynchronous pay-in flow where an end-user pays a pay-in provider in fiat (bank transfer, mobile money, etc.) and a beneficiary provider receives settlement on the crypto side. Quotes are indicative until funds are received, settlement happens periodically, and a confirmation code links the end-user's payment back to a specific payment intent.
+
+Implement **one** of the two sub-phases below depending on your role. If you participate on both sides, implement both.
+
+**Phase 3A -- Pay-In Provider role** (skip if you're a beneficiary):
+
+1. **Step 3A.1** Replace the sample pay-in quote publishing in `src/publish_payment_intent_quotes.ts` with your own.
+2. **Step 3A.2** Implement `getPaymentDetails` in `src/payment_intent_pay_in_service.ts` -- return bank account / mobile money details plus a payment reference the end-user will include in their transfer.
+3. **Step 3A.3** When you detect the end-user's fiat payment, call `confirmFundsReceived` (see `src/confirm_funds_received.ts`).
+
+**Phase 3B -- Beneficiary Provider role** (skip if you're pay-in):
+
+1. **Step 3B.1** Verify indicative quotes are returned (`src/get_payment_intent_quote.ts`).
+2. **Step 3B.2** Create payment intents for your end-users via `createPaymentIntent` (see `src/create_payment_intent.ts`).
+3. **Step 3B.3** Implement `paymentIntentUpdate` in `src/payment_intent_beneficiary_service.ts` to receive notifications when funds are received.
+
+If you only play one role, delete the files for the other role and remove the corresponding `r.service(...)` registration in `src/index.ts`.
+
 ## Available Commands
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t-0/provider-starter-ts",
-  "version": "1.1.13",
+  "version": "1.1.15",
   "description": "CLI tool to scaffold a Node.js t-0 Network integration service",
   "main": "dist/create.js",
   "bin": {

package/template/package.json

@@ -12,7 +12,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@t-0/provider-sdk": "^1.1.13",
+    "@t-0/provider-sdk": "^1.1.15",
     "dotenv": "^16.3.1",
     "tiny-invariant": "^1.3.3"
   },

package/template/src/confirm_funds_received.ts

@@ -0,0 +1,31 @@
+import {type Client, PaymentIntentNetwork, PaymentMethodType} from "@t-0/provider-sdk";
+
+export default async function confirmFundsReceived(
+    paymentIntentClient: Client<typeof PaymentIntentNetwork.PaymentIntentService>,
+    paymentIntentId: bigint,
+    confirmationCode: string,
+    transactionReference: string,
+) {
+  // Pay-In Provider role — Step 3A.3.
+  // Call this after you have matched an incoming fiat payment to a payment intent
+  // (using the payment reference you returned from getPaymentDetails). Settlement
+  // with the beneficiary provider will proceed once this confirmation is accepted.
+  const response = await paymentIntentClient.confirmFundsReceived({
+    paymentIntentId,
+    confirmationCode,
+    paymentMethod: PaymentMethodType.SEPA,
+    transactionReference,
+    // optional: if your provider has multiple legal entities, set originatorProviderLegalEntityId
+  })
+
+  switch (response.Result.case) {
+    case 'accept':
+      console.log(`Funds accepted for payment intent ${paymentIntentId}`)
+      break;
+    case 'reject':
+      console.log(`Funds rejected for payment intent ${paymentIntentId}: ${response.Result.value.reason}`)
+      break;
+    default:
+      console.error("unexpected result type")
+  }
+}

package/template/src/create_payment_intent.ts

@@ -0,0 +1,37 @@
+import {type Client, PaymentIntentNetwork} from "@t-0/provider-sdk";
+import {toProtoDecimal} from "./lib";
+import {randomUUID} from "node:crypto";
+
+export default async function createPaymentIntent(
+    paymentIntentClient: Client<typeof PaymentIntentNetwork.PaymentIntentService>,
+) {
+  // Beneficiary Provider role — Step 3B.2.
+  // Store the returned paymentIntentId to correlate with the PaymentIntentUpdate
+  // notification you'll receive on your BeneficiaryService handler once the end-user
+  // completes the pay-in.
+  const response = await paymentIntentClient.createPaymentIntent({
+    externalReference: randomUUID(), // idempotency key — reuse to retry without duplicating the intent
+    currency: 'EUR',
+    amount: toProtoDecimal(500, 0), // end-user pays 500 EUR
+    travelRuleData: {
+      // TODO: populate real IVMS101 beneficiary information for your end-user.
+      beneficiary: [{}],
+    },
+  })
+
+  switch (response.Result.case) {
+    case 'success':
+      console.log(
+          `Created payment intent id=${response.Result.value.paymentIntentId}`,
+          `with ${response.Result.value.payInDetails.length} pay-in option(s)`,
+      )
+      // TODO: persist (paymentIntentId, externalReference) and present the
+      // payInDetails options to your end-user.
+      break;
+    case 'failure':
+      console.log(`Failed to create payment intent: ${response.Result.value.reason}`)
+      break;
+    default:
+      console.error("unexpected result type")
+  }
+}

package/template/src/get_payment_intent_quote.ts

@@ -0,0 +1,28 @@
+import {type Client, PaymentIntentNetwork} from "@t-0/provider-sdk";
+import {toProtoDecimal} from "./lib";
+
+export default async function getPaymentIntentQuote(
+    paymentIntentClient: Client<typeof PaymentIntentNetwork.PaymentIntentService>,
+) {
+  // Beneficiary Provider role — Step 3B.1.
+  // Use this to check available rates before creating a payment intent. The actual
+  // settlement rate is determined when the pay-in provider confirms funds received.
+  const response = await paymentIntentClient.getQuote({
+    currency: "EUR",
+    amount: toProtoDecimal(500, 0), // end-user pays 500 EUR
+  })
+
+  switch (response.Result.case) {
+    case 'success':
+      console.log(
+          `Got ${response.Result.value.bestQuotes.length} best pay-in quotes`,
+          `and ${response.Result.value.allQuotes.length} total quotes`,
+      )
+      break;
+    case 'quoteNotFound':
+      console.log("No pay-in quotes available for this currency/amount")
+      break;
+    default:
+      console.error("unexpected result type")
+  }
+}

package/template/src/index.ts

@@ -4,6 +4,9 @@ import {
   createService,
   NetworkService,
   nodeAdapter,
+  PaymentIntentBeneficiary,
+  PaymentIntentNetwork,
+  PaymentIntentPayInProvider,
   ProviderService,
   signatureValidation,
 } from "@t-0/provider-sdk";
@@ -14,6 +17,12 @@ import CreateProviderService from "./service";
 import getQuote from "./get_quote";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import submitPayment from "./submit_payment";
+import CreatePayInProviderService from "./payment_intent_pay_in_service";
+import CreateBeneficiaryService from "./payment_intent_beneficiary_service";
+import publishPaymentIntentQuotes from "./publish_payment_intent_quotes";
+import getPaymentIntentQuote from "./get_payment_intent_quote";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import createPaymentIntent from "./create_payment_intent";
 
 dotenv.config();
 
@@ -32,14 +41,22 @@ async function main() {
   console.log(`📡 Port: ${port}`);
   console.log(`🔑 Network Public Key: ${networkPublicKeyHex}`);
   const networkClient = createClient(privateKeyHex!, endpoint, NetworkService);
+  const paymentIntentClient = createClient(privateKeyHex!, endpoint, PaymentIntentNetwork.PaymentIntentService);
 
   await publishQuotes(networkClient, quotePublishingInterval)
 
+  // Phase 3A — Pay-In Provider role. Comment out if you are only a beneficiary.
+  await publishPaymentIntentQuotes(paymentIntentClient, quotePublishingInterval)
+
   const server = http.createServer(
     signatureValidation(
       nodeAdapter(
         createService(networkPublicKeyHex!, (r) => {
           r.service(ProviderService, CreateProviderService(networkClient));
+          // Phase 3A — Pay-In Provider role. Remove if you are only a beneficiary.
+          r.service(PaymentIntentPayInProvider.PayInProviderService, CreatePayInProviderService(paymentIntentClient));
+          // Phase 3B — Beneficiary Provider role. Remove if you are only a pay-in provider.
+          r.service(PaymentIntentBeneficiary.BeneficiaryService, CreateBeneficiaryService());
         })))
   ).listen(port);
   console.log("✅ Service ready and is listening at", server.address());
@@ -59,10 +76,21 @@ async function main() {
   // await submitPayment(networkClient)
 
   // TODO: Step 2.5 ask t-0 team to submit a payment which would trigger your payOut endpoint
+
+  // ──────────────────────────────────────────────────────────────
+  // Payment Intent Flow — Phase 3
+  //
+  // Implement the role that applies to you. See the README for details.
+  // ──────────────────────────────────────────────────────────────
+
+  // Phase 3B — Beneficiary Provider role. Comment out if you are only a pay-in provider.
+  // TODO: Step 3B.1 check that indicative quotes are returned
+  await getPaymentIntentQuote(paymentIntentClient)
+  // TODO: Step 3B.2 create a payment intent for a real end-user when they want to pay
+  // await createPaymentIntent(paymentIntentClient)
 }
 
 main().catch((error) => {
   console.error('❌ Error starting service:', error);
   process.exit(1);
 });
-

package/template/src/payment_intent_beneficiary_service.ts

@@ -0,0 +1,38 @@
+import {
+    HandlerContext,
+    PaymentIntentBeneficiary,
+} from "@t-0/provider-sdk";
+
+/*
+  Payment Intent Flow — Beneficiary Provider role.
+
+  Implement this service if you are a beneficiary provider (you receive settlement for the crypto side).
+  Please refer to docs and proto definition comments to understand the full flow.
+ */
+const CreateBeneficiaryService = () => {
+    return {
+        // TODO: Step 3B.3 Implement how you handle notifications about your payment intents.
+        //
+        // The network calls this endpoint when the status of one of your payment intents
+        // changes (e.g. funds received from the end-user). Correlate req.paymentIntentId
+        // with the id you stored after calling createPaymentIntent and update your
+        // internal state accordingly.
+        async paymentIntentUpdate(req: PaymentIntentBeneficiary.PaymentIntentUpdateRequest, _: HandlerContext) {
+            switch (req.update.case) {
+                case 'fundsReceived':
+                    console.log(
+                        `Payment intent ${req.paymentIntentId}: funds received,`,
+                        `settlementAmount=${JSON.stringify(req.update.value.settlementAmount)},`,
+                        `paymentMethod=${req.update.value.paymentMethod},`,
+                        `transactionReference=${req.update.value.transactionReference}`,
+                    )
+                    break;
+                default:
+                    console.log(`Payment intent ${req.paymentIntentId}: unknown update variant`)
+            }
+            return {} as PaymentIntentBeneficiary.PaymentIntentUpdateResponse
+        },
+    }
+};
+
+export default CreateBeneficiaryService;

package/template/src/payment_intent_pay_in_service.ts

@@ -0,0 +1,39 @@
+import {
+    type Client,
+    HandlerContext,
+    PaymentIntentNetwork,
+    PaymentIntentPayInProvider,
+} from "@t-0/provider-sdk";
+
+/*
+  Payment Intent Flow — Pay-In Provider role.
+
+  Implement this service if you are a pay-in provider (you receive fiat from end-users).
+  Please refer to docs and proto definition comments to understand the full flow.
+ */
+const CreatePayInProviderService = (paymentIntentClient: Client<typeof PaymentIntentNetwork.PaymentIntentService>) => {
+    return {
+        // TODO: Step 3A.2 Implement how you return payment details for the end-user.
+        //
+        // The network calls this endpoint during CreatePaymentIntent processing. Return
+        // payment details (bank account, mobile money number, etc.) for each requested
+        // paymentMethod, including a unique payment reference that will let you match
+        // the incoming fiat payment back to this payment intent.
+        //
+        // Store (paymentIntentId, confirmationCode) so you can validate it later in
+        // confirmFundsReceived.
+        async getPaymentDetails(req: PaymentIntentPayInProvider.GetPaymentDetailsRequest, _: HandlerContext) {
+            console.log(`Received GetPaymentDetails for payment intent ${req.paymentIntentId}, methods: ${req.paymentMethods.join(',')}`)
+            return {
+                result: {
+                    case: 'details',
+                    value: {
+                        paymentDetails: [], // TODO: populate one PaymentDetails per requested paymentMethod
+                    },
+                },
+            } as unknown as PaymentIntentPayInProvider.GetPaymentDetailsResponse
+        },
+    }
+};
+
+export default CreatePayInProviderService;

package/template/src/publish_payment_intent_quotes.ts

@@ -0,0 +1,39 @@
+import {type Client, PaymentIntentNetwork, PaymentMethodType} from "@t-0/provider-sdk";
+import {toProtoDecimal} from "./lib";
+import {randomUUID} from "node:crypto";
+import {timestampFromDate} from "@bufbuild/protobuf/wkt";
+
+export default async function publishPaymentIntentQuotes(
+    paymentIntentClient: Client<typeof PaymentIntentNetwork.PaymentIntentService>,
+    quotePublishingInterval: number,
+): Promise<void> {
+  // TODO: Step 3A.1 replace this with fetching pay-in quotes from your systems and publishing them into t-0 Network.
+  // We recommend publishing at least once per 5 seconds, but not more than once per second.
+  const tick = async () => {
+    try {
+      // NOTE: Every updateQuote request discards all previous payment intent quotes
+      // that were published before. Combine multiple quotes into a single request.
+      await paymentIntentClient.updateQuote({
+        paymentIntentQuotes: [{
+          currency: 'EUR',
+          paymentMethod: PaymentMethodType.SEPA,
+          expiration: timestampFromDate(new Date(Date.now() + 30 * 1000)), // 30 seconds from now
+          timestamp: timestampFromDate(new Date()),
+          bands: [{
+            clientQuoteId: randomUUID(),
+            maxAmount: toProtoDecimal(1000, 0), // max 1000 USD for this band
+            // rate is always USD/XXX, so for EUR quote should be USD/EUR
+            rate: toProtoDecimal(92, -2), // rate 0.92
+          }],
+        }],
+      })
+    } catch (error) {
+      console.error(error);
+      return
+    }
+    console.log("payment intent quote published")
+  }
+
+  await tick()
+  setInterval(tick, quotePublishingInterval);
+}

package/template/src/service.ts

@@ -69,7 +69,7 @@ const CreateProviderService = (networkClient: Client<typeof NetworkService>) =>
             return {} as AppendLedgerEntriesResponse
         },
 
-        async approvePaymentQuote(req: ApprovePaymentQuoteRequest, _: HandlerContext) {
+        async approvePaymentQuotes(req: ApprovePaymentQuoteRequest, _: HandlerContext) {
             // TODO: when the payment goes through the Manual AML Check on the pay-out provider side, the provider submitted the payment will have a last look to approve final quote
             // The request includes payOutFix — the fixed charge in USD for this payout.
             // Consider it alongside payOutRate and payOutAmount when deciding to accept.