diff --git a/submissions/payout-mercyoyelude2/images/authorize.png b/submissions/payout-mercyoyelude2/images/authorize.png new file mode 100644 index 0000000..696ad83 Binary files /dev/null and b/submissions/payout-mercyoyelude2/images/authorize.png differ diff --git a/submissions/payout-mercyoyelude2/images/flow-diagram.png b/submissions/payout-mercyoyelude2/images/flow-diagram.png new file mode 100644 index 0000000..43d4e75 Binary files /dev/null and b/submissions/payout-mercyoyelude2/images/flow-diagram.png differ diff --git a/submissions/payout-mercyoyelude2/images/ilp-browser.png b/submissions/payout-mercyoyelude2/images/ilp-browser.png new file mode 100644 index 0000000..358f58e Binary files /dev/null and b/submissions/payout-mercyoyelude2/images/ilp-browser.png differ diff --git a/submissions/payout-mercyoyelude2/images/server-dropdown-sandbox.png b/submissions/payout-mercyoyelude2/images/server-dropdown-sandbox.png new file mode 100644 index 0000000..068440c Binary files /dev/null and b/submissions/payout-mercyoyelude2/images/server-dropdown-sandbox.png differ diff --git a/submissions/payout-mercyoyelude2/setup.md b/submissions/payout-mercyoyelude2/setup.md new file mode 100644 index 0000000..3003415 --- /dev/null +++ b/submissions/payout-mercyoyelude2/setup.md @@ -0,0 +1,171 @@ +# How to Use Chimoneyโ€™s Interledger Wallet Address Payout Endpoint +> Endpoint: `/payouts/interledger-wallet-address` + +In this tutorial, weโ€™ll walk through how to integrate Chimoney's API to send payouts to an Interledger Wallet Address. This will allow you to make cross-border payments using a digital wallet. By the end, you'll know how to test the endpoint, troubleshoot common errors, and integrate it into your app. + +--- + +## ๐Ÿงฐ 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) + + Your sandbox account comes preloaded with $1000 (10,000 Chimoney) for testing purposes. + +- ๐Ÿ”‘ **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)** + You can use the following tools to test the API: + - **Postman:** Import the collection [here]([link-to-collection](https://documenter.getpostman.com/view/26097715/2sA3kXCzD2#c311f506-2938-440b-abe9-dc232530a84f)) + - **cURL:** Example command: + ```bash + curl -X POST https://api.chimoney.io/v0.2.4/payouts/interledger-wallet-address -H "Authorization: Bearer " -d '{"amount": "100", "currency": "USD", ...}' + ``` + - 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 +This step authenticates your requests, letting the API know that you have permission to interact with the endpoint. + +5. [Click here](https://api.chimoney.io/v0.2.4/api-docs/#/Payouts/post_v0_2_4_payouts_interledger_wallet_address) to go directly to the `POST /payouts/interledger-wallet-address` section in the API Explorer. +6. Replace the `interledgerWalletAddress` field with your own ILP address +7. Hit **Execute**! + +Now, your first test payout should go through if everything 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: +Some wallets are configured to only support certain currencies. For instance, if your ILP wallet is set up for USD, it wonโ€™t process requests in CAD due to system limitations or regulatory reasons. + +### โœ… 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. + +In addition to successful payouts, you may encounter a variety of other responses from the API. Below are some examples and how to troubleshoot them. +### โš ๏ธ 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!** ๐Ÿ™Œ diff --git a/submissions/payout-mercyoyelude2/tutorial.md b/submissions/payout-mercyoyelude2/tutorial.md new file mode 100644 index 0000000..7d9fd9d --- /dev/null +++ b/submissions/payout-mercyoyelude2/tutorial.md @@ -0,0 +1,217 @@ +# 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 of 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 is 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 +Now that your configuration is set up, it is time to write the code that will send a payout to an Interledger wallet using Chimoneyโ€™s API. Let us start by creating a reusable service class. + +### 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`) +In this step, you will see how to **bring everything together**. +We will import the Chimoney service, provide an Interledger wallet address, set an amount and narration, then trigger a payout. This example also shows how to capture success responses and gracefully handle errors. + +```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" + } +})(); +``` +--- + +## 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` + +--- + +## Handling Errors & Troubleshooting +Chimoneyโ€™s API may return various errors depending on your inputs or environment. Below are common issues and how to resolve them: + +| **Code** | **Description** | **Example Message** | **How to Fix** | +|----------|-------------------|--------------------------------------------------------------------|--------------------------------------------------------------------------------| +| **200** | Success | `"Payout to Chimoney wallets completed successfully."` | No action needed. | +| **400** | Validation error | `"The request parameters are invalid."` | Double-check request body (wallet address format, required fields, etc.). | +| **401** | Unauthorized | `"API key is not defined. Generate a new one from the developer portal."` | Ensure your API key is set in `.env` and passed in headers. | +| **403** | Forbidden | `"API Access not enabled for account Test. Email support@chimoney.io"` | Contact Chimoney support to enable API access for your account. | +| **500** | Server error | `"An internal server error occurred."` | Retry after a short delay. If persistent, reach out to Chimoney support. | + +--- + +## You Did It + +You just: +- Set up your environment +- Made a successful payout to an Interledger wallet +- Learned how to handle and debug errors + + +Thatโ€™s it for the setup! + +_Next up: Extend this into a backend job or admin panel!_ + diff --git a/submissions/payout-mercyoyelude2/use-case.md b/submissions/payout-mercyoyelude2/use-case.md new file mode 100644 index 0000000..6f4d555 --- /dev/null +++ b/submissions/payout-mercyoyelude2/use-case.md @@ -0,0 +1,132 @@ +# Global Payment via Chimoneyโ€™s Interledger Wallet Address +--- + +## ๐Ÿ“˜ Scenario + +You are running a global hackathon, write-a-thon that will be rewarding participants across borders. Rather than managing complex banking setups for each country, you want to send fast, secure payments directly to Interledger-enabled wallets using Chimoney. + +--- + +## ๐Ÿš€ Why This Use Case? + +- ๐ŸŒŽ Pay participants across borders without worrying about banking differences +- โšก Instant value transfer via Interledger Protocol (ILP) +- ๐Ÿ’ต Support multiple currencies like USD +- ๐Ÿ“ฑ Easy integration into your existing backend or platform + +--- + +## ๐Ÿ”„ Flow Overview + +### ๐Ÿชœ Flow - Step-by-Step + +1. โœ… **Winners Announced:** Hackathon winners are announced. +2. ๐Ÿงฎ **Payout Calculated:** Your backend calculates how much to send. +3. ๐Ÿ›ฐ **API Call Sent:** Your app sends a `POST` request to the `/payouts/interledger-wallet-address` endpoint with: + - Their ILP address + - Amount in USD + - Narration +4. ๐Ÿ’ธ **Chimoney Handles Transfer:** Chimoney routes and completes the payout to the ILP wallet. +5. ๐Ÿ“ฌ **Notification (Optional):** You can trigger an email or in-app notification to the freelancer. + +### ๐Ÿ“Š Flow Diagram + +![ILP Payout Flow](./images//flow-diagram.png) +--- + +## ๐Ÿงฐ Prerequisites + +- โœ… Chimoney Developer Account ([Create one](https://sandbox.chimoney.io/)) +- ๐Ÿ”‘ API Key (Grab from dashboard) +- ๐ŸŒ Valid Interledger Wallet Address (`https://ilp-sandbox.chimoney.com/`) +- ๐Ÿ›  Postman, Curl, or your preferred HTTP client + +--- + +## ๐Ÿ“ค Sending the Payout + +Hereโ€™s a real request example using the `/payouts/interledger-wallet-address` endpoint: + +```json +POST /v0.2.4/payouts/interledger-wallet-address +Host: api-v2-sandbox.chimoney.io + +Headers: + X-API-KEY: Bearer YOUR_API_KEY + +Body: +{ + "turnOffNotification": false, + "debitCurrency": "USD", + "interledgerWallets": [ + { + "interledgerWalletAddress": "https://ilp-sandbox.chimoney.com/your-id", + "currency": "USD", + "amountToDeliver": 10, + "narration": "Congratulations on emerging hackathon winner!", + "collectionPaymentIssueID": "hackathon-001" + } + ] +} +``` + +โœ… Success Response + +```json +{ + "status": "success", + "message": "Chimoney payout to Interledger wallet completed successfully", + "data": { + "paymentLink": "https://sandbox.chimoney.io/pay/?issueID=...", + ... + } +} +``` + +--- + +## โ— Common Errors + +### ๐Ÿ›‘ CAD is not enabled + +```json +{ + "status": "error", + "message": "CAD is not enabled for the interledger Wallet Address..." +} +``` + +**Fix:** Use "USD" for both currency and debitCurrency + +### ๐Ÿ›‘ Invalid Chimoney User ID +```json +{ + "error": "sender must be a valid Chimoney user ID" +} +``` +**Fix:** Remove or correct the subAccount field. + +--- + +## ๐Ÿ’ก Wrap-up +Not limited to one-time payments, with just a few lines of code, you can automate freelancer/employees payouts globally. Chimoney + Interledger makes cross-border payments smooth, developer-friendly, and scalable. + +### โœจ Real-World Extensions +Here are more ways to apply this payout flow: + +- #### Open-source contributor rewards +Automate thank-you payouts for contributors using their ILP wallet address (e.g. via GitHub Actions or Discord bots). + +- #### Content creation platforms +Pay writers, creators, or community moderators directly based on engagement or content milestones. + +- #### Job boards or marketplaces +Trigger seamless payouts to service providers upon completion of gigs or tasks. + +- #### Hackathons and community events +Send rewards at scale without dealing with traditional banking headaches. + +--- + +## Next Step: +๐ŸŽฏ Integrate this API flow into your backend and trigger payouts with this [tutorial](./tutorial.md)! \ No newline at end of file