payout-mercyoyelude2 submission

submissions/payout-mercyoyelude2/setup.md

@@ -0,0 +1,166 @@
+# How to Use Chimoney’s Interledger Wallet Address Payout Endpoint
+> Endpoint: `/payouts/interledger-wallet-address`
+
+Before you jump into integrating Chimoneys payout API, here is a quick walkthrough to get everything set up and ready to roll.
+
+---
+
+## 🧰 Prerequisites
+
+Before diving in, make sure you have the following:
+
+- 🔐 **Chimoney Developer Account**  
+  Create one here: [chimoney.io/developers-api](https://chimoney.io/developers-api)
+
+  Account is funded with $1000(10000 Chimoney) of test amount.
+
+- 🔑 **API Key**  
+  Grab it from your dashboard. Need help? [Watch this video](https://www.loom.com/share/436303eb69c44f0d9757ea0c655bed89?sid=b6a0f661-721c-4731-9873-ae6f2d25780)
+
+- 💳 **Interledger Wallet Address**  
+  Found on your dashboard after login. It will look something like:  
+  `https://ilp-sandbox.chimoney.com/your-unique-id`
+
+- 🧪 **API Testing Tools (Optional)**  
+  Use any of the following:
+  - Postman
+  - Curl
+  - Your favorite HTTP client (e.g. Axios, Fetch)
+
+- 🧠 **Basic Knowledge of REST APIs**  
+  You will be working with `POST` requests and JSON payloads.
+
+---
+
+## 🚀 Test the Endpoint in the API Explorer
+
+Let us make a test call using Chimoney’s Swagger (API explorer):
+
+1. Go to [Chimoney’s API Explorer](https://api.chimoney.io/v0.2.4/api-docs/#/Payouts/post_v0_2_4_payouts_interledger_wallet_address)
+2. Switch to `sandbox mode` (top-left dropdown)
+
+![Sandbox dropdown](./images/server-dropdown-sandbox.png)
+
+3. Click **Authorize** and paste your API key
+4. [Jump](https://api.chimoney.io/v0.2.4/api-docs/#/Payouts/post_v0_2_4_payouts_interledger_wallet_address) to `POST /payouts/interledger-wallet-address`
+5. Replace the `interledgerWalletAddress` field with your own ILP address
+6. Hit **Execute**!
+
+Boom — your first test payout should go through if all is set up correctly ✅
+
+---
+
+## 🛠 Common Errors and How to Fix Them
+
+### ❌ Error: `CAD is not enabled for the interledger Wallet Address`
+
+```json
+{
+  "status": "error",
+  "message": "CAD is not enabled for the interledger Wallet Address (Payment Pointer), https://ilp-sandbox.chimoney.com/********"
+}
+```
+
+### 💡 Why it happens:
+Your ILP wallet only supports USD (not CAD).
+
+### ✅ Fix: Change both currency fields to USD:
+```json
+"currency": "USD",
+"debitCurrency": "USD"
+```
+
+**🕵️‍♀️ Pro tip:** Open your ILP wallet address in a browser to confirm supported assets.
+
+
+![ILP assets](./images/ilp-browser.png)
+
+### ❌ Error: `sender must be a valid Chimoney user ID`
+
+### 💡 Why it happens:
+You have either included an invalid subAccount or do not need one.
+
+### ✅ Fix:
+
+- Don’t have a subAccount? Just remove the field.
+
+- Or go to your dashboard → Transactions tab → copy your user ID.
+
+---
+
+## Other API Responses
+If everything checks out, you should see a success response like this:
+
+### ✅ 200 OK – Success
+```json
+{
+  "status": "success",
+  "message": "Chimoney payout to Interledger wallet completed successfully",
+  "data": {
+    "paymentLink": "https://sandbox.chimoney.io/pay/?issueID=...",
+    "chimoneys": [
+      {
+        "interledgerWalletAddress": "https://ilp-sandbox.chimoney.com/your-id",
+        "amount": 200,
+        "currency": "USD",
+        "chiRef": "some-unique-id"
+      }
+    ],
+    "redeemLink": "https://sandbox.chimoney.io/redeem/?chi=..."
+  }
+}
+```
+Use the `paymentLink` or `redeemLink` to simulate or test payouts end-to-end.
+
+
+### ⚠️ 400 / 401 / 403 – Invalid or Unauthorized Request
+
+```json
+{
+  "status": "error",
+  "error": "sender must be a valid Chimoney user ID"
+}
+```
+
+Or:
+
+```json
+{
+  "status": "error",
+  "message": "Unauthorized – API key missing or invalid"
+}
+```
+
+Refer to the **Common Errors** section above to resolve these.
+
+### 💥 500 – Internal Server Error
+```json
+{
+  "status": "error",
+  "type": "InternalError",
+  "code": "SERVER_ERROR",
+  "message": "Something went wrong"
+}
+```
+If this happens, double-check your payload format or retry later.
+
+---
+
+## Wrapping Up
+That is it! At this point, you should be able to:
+
+- Create a Chimoney developer account and generate an API key
+
+- Authenticate using your API key
+
+- Locate and use your ILP wallet address
+
+- Make a test payout request via the API Explorer
+
+- Troubleshoot common errors like currency mismatch or sender ID issues
+
+### 🎯 Next Step: Integrate the API in your project
+
+Now that you are all set up, let us write some code and make payouts from your app using this [tutorial guide](./tutorial.md).
+
+**Happy building!** 🙌

submissions/payout-mercyoyelude2/tutorial.md

@@ -0,0 +1,218 @@
+# How to Make Payouts to Interledger Wallets Using Chimoney’s API
+
+In this tutorial, you will learn how to integrate Chimoney’s `/payouts/interledger-wallet-address` endpoint into your existing project and send live payouts using your wallet-enabled Chimoney account.
+
+---
+
+## 🔧 What You’ll Build
+
+- Configure your environment
+- Build a payout service with Chimoney’s API
+- Handle real-world errors (like currency mismatches)
+- Test your first ILP payout
+
+---
+
+## 🧰 Prerequisites
+
+Before you start, make sure you have completed the [Setup Guide](./setup.md). You should already have:
+- A Chimoney developer account
+- Your API key
+- Your ILP wallet address
+- Tested the `payouts to interledger wallet address` endpoint
+
+Additionally;
+- Basic knowledge on RESTful APIs
+- Node.js and npm/yarn installed
+- Axios for HTTP requests
+
+With that out of the way, let us dive in.
+
+---
+
+## 🗂 Project Structure
+
+Here’s what your folder might look like:
+
+```bash
+chimoney-payouts/
+├── .env
+├── src/
+│   ├── config.js
+│   ├── services/
+│   │   └── chimoneyService.js
+│   └── index.js
+├── package.json
+└── README.md
+```
+
+## 🗂 Step 1: 🔧 Configuration & Setup
+
+### Install Dependencies
+
+```bash
+mkdir chimoney-payouts && cd chimoney-payouts
+npm init -y
+npm install axios dotenv
+```
+
+### Environment Variables
+
+Create `.env`:
+
+```js
+CHIMONEY_API_KEY=your_api_key_here
+CHIMONEY_ENV=sandbox # or "production"
+
+ILP_WALLET_ADDRESS=https://ilp-sandbox.chimoney.com/your-id
+```
+
+---
+
+### Configuration Module (`config.js`)
+
+```js
+import dotenv from "dotenv";
+dotenv.config();
+
+export const config = {
+  apiKey: process.env.CHIMONEY_API_KEY,
+  baseUrl:
+    process.env.CHIMONEY_ENV === "production"
+      ? "https://api-v2.chimoney.io/v0.2.4"
+      : "https://api-v2-sandbox.chimoney.io/v0.2.4",
+  headers: {
+    Accept: "application/json",
+    "Content-Type": "application/json",
+    "X-API-KEY": process.env.CHIMONEY_API_KEY,
+  },
+};
+```
+
+---
+
+## 🧾 Step 2: Build the Chimoney Interledger Service
+### Create `chimoneyService.js`:
+
+```js
+import axios from "axios";
+import { config } from "./config.js";
+
+class ChimoneyService {
+  constructor() {
+    this.client = axios.create({
+      baseURL: config.baseUrl,
+      headers: config.headers,
+    });
+  }
+
+  async sendInterledgerPayout({ walletAddress, amount, narration, collectionPaymentIssueID = "" }) {
+    try {
+      const payload = {
+        turnOffNotification: false,
+        debitCurrency: "USD",
+        interledgerWallets: [
+          {
+            interledgerWalletAddress: walletAddress,
+            currency: "USD",
+            amountToDeliver: amount,
+            narration,
+            collectionPaymentIssueID, // optional but great for tracking payouts
+          },
+        ],
+      };
+
+      const res = await this.client.post("/payouts/interledger-wallet-address", payload);
+      return res.data;
+    } catch (err) {
+      if (err.response) {
+        console.error("Chimoney API error:", err.response.data);
+        throw err.response.data;
+      }
+      throw err;
+    }
+  }
+}
+
+export default ChimoneyService;
+```
+
+---
+
+## ⚙️ Step 3: Usage Example (`index.js`)
+
+```js
+import ChimoneyService from "./chimoneyService.js";
+import dotenv from "dotenv";
+dotenv.config();
+
+(async () => {
+  const service = new ChimoneyService();
+
+  const walletAddress = process.env.ILP_WALLET_ADDRESS; // e.g., https://ilp-sandbox.chimoney.com/your-id
+  const amount = 10; // USD
+  const narration = "Freelance payout for job #123";
+  const collectionPaymentIssueID = "job-123-issue";
+
+  try {
+    const result = await service.sendInterledgerPayout({
+      walletAddress,
+      amount,
+      narration,
+      collectionPaymentIssueID,
+    });
+    console.log("✅ Payout Success:", result);
+  } catch (error) {
+    const res = error.response;
+    console.error("❌ Payout Failed:", {
+        status: res?.status,
+        message: res?.data?.message || res?.data?.error || error.message
+    });
+    // handle error messages, e.g.:
+    // if errorData.message includes "CAD is not enabled"
+    // if errorData.error includes "valid Chimoney user ID"
+  }
+})();
+```
+
+### 🧪 Notes & Error Handling
+#### Response Object Includes:
+- status, message
+- data.paymentLink / data.redeemLink
+- data.chimoneys or data.payouts with chiRef, issueID, etc.
+
+
+### ⚠️ Common Errors
+Here are a couple of issues you might hit (and how to fix them):
+
+#### 1. ❌ "CAD is not enabled"
+**Fix:** Change **currency** to "USD"
+
+#### 2. ❌ "sender must be a valid Chimoney user ID"
+**Fix:** Invalid **subAccount**, (remove the field if unused, or request for one through support).
+
+
+**Wrap error handler to inspect `errorData.message` or `.error` and act accordingly.**
+
+---
+
+## 🔄 How It Works (Behind the Scenes)
+
+1. 🧾 You make a `POST` request to the `/payouts/interledger-wallet-address` endpoint
+2. 🔐 Chimoney authenticates your API key
+3. 💳 Chimoney deducts the amount from your wallet
+4. 🌐 The ILP wallet address receives the payout (in supported currency)
+5. 📦 A response is returned with `chiRef`, status, and optionally a `paymentLink`
+
+---
+
+## 🎉 You Did It
+You just:
+
+- Set up your environment
+- Made a successful payout to an Interledger wallet
+- Learned how to handle and debug errors
+
+
+_🔗 Next up: Extend this into a backend job or admin panel!_
+