@cashfreepayments/agent-skills 0.0.1

package/dist/templates/crossBorder.md

@@ -0,0 +1,264 @@
+---
+name: Cashfree Cross Border
+description: Use this to see Cross Border documentation and API references
+---
+
+# Cashfree Cross Border - Collect from India Integration
+
+## Overview
+This integration enables foreign merchants (based outside India) to collect payments from Indian customers using Indian payment methods (UPI, Cards, Net Banking, etc.). Funds are settled to the merchant's overseas bank account.
+
+## API Base URLs
+- **Sandbox**: `https://sandbox.cashfree.com/`
+- **Production**: `https://api.cashfree.com/`
+
+## Authentication Headers
+```
+x-client-id: <your_client_id>
+x-client-secret: <your_client_secret>
+x-api-version: 2025-01-01
+```
+
+## Backend Integration
+
+### 1. Create Order
+**Endpoint**: `POST /pg/orders`
+
+```javascript
+// Node.js example
+const createOrder = async (orderData) => {
+  const response = await fetch('https://sandbox.cashfree.com/pg/orders', {
+    method: 'POST',
+    headers: {
+      'x-client-id': process.env.CASHFREE_CLIENT_ID,
+      'x-client-secret': process.env.CASHFREE_CLIENT_SECRET,
+      'x-api-version': '2025-01-01',
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      order_id: orderData.orderId,
+      order_amount: orderData.amount,
+      order_currency: 'INR',
+      customer_details: {
+        customer_id: orderData.customerId,
+        customer_email: orderData.email,
+        customer_phone: orderData.phone
+      },
+      order_meta: {
+        return_url: orderData.returnUrl,
+        notify_url: orderData.webhookUrl
+      }
+    })
+  });
+  return response.json();
+};
+```
+
+### 2. Upload Payment Verification Details
+**Endpoint**: `POST /import/transactions/{cf_payment_id}/details`
+
+Required for regulatory compliance. Upload documents after successful payment.
+
+```javascript
+const uploadVerificationDetails = async (cfPaymentId, details) => {
+  const response = await fetch(
+    `https://api.cashfree.com/import/transactions/${cfPaymentId}/details`,
+    {
+      method: 'POST',
+      headers: {
+        'x-client-id': process.env.CASHFREE_CLIENT_ID,
+        'x-client-secret': process.env.CASHFREE_CLIENT_SECRET,
+        'x-api-version': '2025-01-01',
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        goods_description: details.goodsDescription,
+        invoice_number: details.invoiceNumber,
+        importer_name: details.importerName,
+        importer_address: details.importerAddress,
+        country_of_origin: details.countryOfOrigin,
+        // For Physical Goods:
+        shipment_date: details.shipmentDate,
+        port_of_loading: details.portOfLoading,
+        awb_number: details.awbNumber,
+        hs_code: details.hsCode
+      })
+    }
+  );
+  return response.json();
+};
+```
+
+### 3. Get Payment Verification Status
+**Endpoint**: `GET /import/transactions/{cf_payment_id}`
+
+```javascript
+const getVerificationStatus = async (cfPaymentId) => {
+  const response = await fetch(
+    `https://api.cashfree.com/import/transactions/${cfPaymentId}`,
+    {
+      headers: {
+        'x-client-id': process.env.CASHFREE_CLIENT_ID,
+        'x-client-secret': process.env.CASHFREE_CLIENT_SECRET,
+        'x-api-version': '2025-01-01'
+      }
+    }
+  );
+  return response.json();
+};
+```
+
+### 4. Get Settlement Details
+**Endpoint**: `GET /import/settlements`
+
+## Frontend Integration
+
+### Cashfree JS SDK Checkout
+```html
+<script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>
+
+<script>
+const cashfree = Cashfree({ mode: "sandbox" }); // or "production"
+
+function initiatePayment(paymentSessionId) {
+  cashfree.checkout({
+    paymentSessionId: paymentSessionId,
+    redirectTarget: "_modal" // or "_self" for redirect
+  }).then((result) => {
+    if (result.error) {
+      console.error("Payment error:", result.error.message);
+    }
+    if (result.paymentDetails) {
+      console.log("Payment completed:", result.paymentDetails);
+    }
+  });
+}
+</script>
+```
+
+## Webhook Integration
+
+### Configure Webhook Endpoint
+Register your webhook URL in the Cashfree Dashboard under Developers > Webhooks.
+
+### Webhook Events for Cross Border
+1. **PAYMENT_VERIFICATION_UPDATE** - Payment verification status changes
+2. **ICA_SETTLEMENT_UPDATE** - Settlement status updates
+
+### Webhook Handler with Signature Verification
+
+```javascript
+// Node.js/Express webhook handler
+const crypto = require('crypto');
+
+app.post('/webhook/cashfree', express.raw({ type: 'application/json' }), (req, res) => {
+  const signature = req.headers['x-webhook-signature'];
+  const timestamp = req.headers['x-webhook-timestamp'];
+  const rawBody = req.body.toString();
+  
+  // Verify signature
+  const signedPayload = timestamp + rawBody;
+  const expectedSignature = crypto
+    .createHmac('sha256', process.env.CASHFREE_CLIENT_SECRET)
+    .update(signedPayload)
+    .digest('base64');
+  
+  if (signature !== expectedSignature) {
+    return res.status(401).send('Invalid signature');
+  }
+  
+  const payload = JSON.parse(rawBody);
+  
+  // Handle different webhook types
+  switch (payload.type) {
+    case 'PAYMENT_VERIFICATION_UPDATE':
+      handleVerificationUpdate(payload.data);
+      break;
+    case 'ICA_SETTLEMENT_UPDATE':
+      handleSettlementUpdate(payload.data);
+      break;
+    case 'PAYMENT_SUCCESS_WEBHOOK':
+      handlePaymentSuccess(payload.data);
+      break;
+  }
+  
+  res.status(200).send('OK');
+});
+
+function handleVerificationUpdate(data) {
+  // data contains: cf_payment_id, payment_status, payment_verification_status,
+  // payment_verification_expiry, required_details[]
+  console.log('Verification status:', data.payment_verification_status);
+  // ACTION_REQUIRED, IN_REVIEW, VERIFIED, REJECTED
+}
+
+function handleSettlementUpdate(data) {
+  // data contains: cf_ica_settlement_id, settlement_amount_inr,
+  // settlement_foreign_currency_details, status, settlement_utr
+  console.log('Settlement status:', data.status);
+}
+```
+
+### Payment Verification Webhook Payload
+```json
+{
+  "data": {
+    "order_id": "order_123",
+    "cf_payment_id": 5114910634577,
+    "payment_status": "SUCCESS",
+    "payment_verification_status": "ACTION_REQUIRED",
+    "payment_verification_expiry": "2024-07-12T15:19:42+05:30",
+    "required_details": [
+      { "doc_name": "goods_description", "doc_type": "VALUE", "doc_status": "ACTION_REQUIRED" },
+      { "doc_name": "invoice_file", "doc_type": "DOCUMENT", "doc_status": "IN_REVIEW" }
+    ]
+  },
+  "event_time": "2024-07-12T13:39:42+05:30",
+  "type": "PAYMENT_VERIFICATION_UPDATE"
+}
+```
+
+### ICA Settlement Webhook Payload
+```json
+{
+  "data": {
+    "cf_ica_settlement_id": 12,
+    "collection_amount_inr": 604854.0,
+    "settlement_amount_inr": 243651.95,
+    "settlement_foreign_currency_details": {
+      "settlement_amount_fcy": null,
+      "settlement_currency": "USD",
+      "settlement_forex_rate": null
+    },
+    "status": "NOT_INITIATED"
+  },
+  "event_time": "2024-10-03T13:27:36+05:30",
+  "type": "ICA_SETTLEMENT_UPDATE"
+}
+```
+
+## Key APIs Summary
+| API | Endpoint | Purpose |
+|-----|----------|---------|
+| Create Order | `POST /pg/orders` | Create payment order |
+| Order Pay | `POST /pg/orders/{order_id}/pay` | Process payment |
+| Get Payment | `GET /pg/orders/{order_id}/payments/{cf_payment_id}` | Verify payment status |
+| Upload Verification | `POST /import/transactions/{cf_payment_id}/details` | Upload compliance docs |
+| Get Verification | `GET /import/transactions/{cf_payment_id}` | Check verification status |
+| Get Settlement | `GET /import/settlements` | Get settlement details |
+
+## Important Notes
+- Always verify webhook signatures before processing
+- Upload verification documents promptly after successful payments
+- Settlement happens in foreign currency to overseas bank account
+- Settlements can be as fast as T+2 days
+
+---
+
+This skills file covers the Cross Border - Collect from India integration based on the [Overview](/payments/international-payments/collect-from-india/overview) and [Webhooks](/api-reference/payments/latest/international-payments/collect-from-india/import-webhooks) documentation.
+
+```suggestions
+(Collect from India Overview)[/payments/international-payments/collect-from-india/overview]
+(Import Webhooks)[/api-reference/payments/latest/international-payments/collect-from-india/import-webhooks]
+(API Overview)[/api-reference/payments/latest/international-payments/collect-from-india/overview]
+```

package/dist/templates/payouts.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Payouts skill template
+ */
+export declare function getPayoutsSkillTemplate(): string;
+//# sourceMappingURL=payouts.d.ts.map

package/dist/templates/payouts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payouts.d.ts","sourceRoot":"","sources":["../../src/templates/payouts.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAGhD"}

package/dist/templates/payouts.js

@@ -0,0 +1,10 @@
+import * as fs from "fs";
+import * as path from "path";
+/**
+ * Payouts skill template
+ */
+export function getPayoutsSkillTemplate() {
+    const templatePath = path.join(__dirname, "payouts.md");
+    return fs.readFileSync(templatePath, "utf8");
+}
+//# sourceMappingURL=payouts.js.map

package/dist/templates/payouts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payouts.js","sourceRoot":"","sources":["../../src/templates/payouts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAI7B;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACnC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IACxD,OAAO,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;AACjD,CAAC"}

package/dist/templates/payouts.md

@@ -0,0 +1,332 @@
+---
+name: Cashfree Payouts
+description: Use this to see Payouts documentation and API references
+---
+
+# Cashfree Payouts Integration
+
+## Overview
+Cashfree Payouts enables instant fund transfers to bank accounts, UPI IDs, cards, and wallets. This is a **backend-only integration** - no frontend SDK is required.
+
+---
+
+## Environment Configuration
+
+```
+# Environment URLs
+PRODUCTION_URL_V2=https://api.cashfree.com/payout
+SANDBOX_URL_V2=https://sandbox.cashfree.com/payout
+PRODUCTION_URL_V1=https://payout-api.cashfree.com
+SANDBOX_URL_V1=https://payout-gamma.cashfree.com
+
+# Required Headers
+x-client-id: <YOUR_CLIENT_ID>
+x-client-secret: <YOUR_CLIENT_SECRET>
+x-api-version: 2024-01-01
+```
+
+---
+
+## Authentication
+
+### V1 API (Bearer Token)
+Call `/payout/v1/authorize` to get a Bearer token (valid for 6 minutes):
+
+```bash
+curl -X POST 'https://payout-api.cashfree.com/payout/v1/authorize' \
+  -H 'X-Client-Id: <CLIENT_ID>' \
+  -H 'X-Client-Secret: <CLIENT_SECRET>'
+```
+
+**Response:**
+```json
+{
+  "status": "SUCCESS",
+  "message": "Token generated",
+  "subCode": "200",
+  "data": { "token": "eyJ0eXA...fWStg", "expiry": 1564130052 }
+}
+```
+
+### V2 API (Direct Authentication)
+Use `x-client-id` and `x-client-secret` headers directly - no token needed.
+
+### 2FA Requirements
+- **IP Whitelisting**: Whitelist up to 25 IPv4 addresses in Dashboard > Developers > Two-Factor Authentication
+- **Public Key Signature**: If no static IP, generate signature using RSA encryption with `X-Cf-Signature` header
+
+---
+
+## Backend API Integration
+
+### 1. Create Beneficiary (V2)
+
+```bash
+curl -X POST 'https://sandbox.cashfree.com/payout/beneficiary' \
+  -H 'x-client-id: <CLIENT_ID>' \
+  -H 'x-client-secret: <CLIENT_SECRET>' \
+  -H 'x-api-version: 2024-01-01' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "beneficiary_id": "JOHN18011343",
+    "beneficiary_name": "John Doe",
+    "beneficiary_instrument_details": {
+      "bank_account_number": "00111122233",
+      "bank_ifsc": "HDFC0000001",
+      "vpa": "test@upi"
+    },
+    "beneficiary_contact_details": {
+      "beneficiary_email": "johndoe@cashfree.com",
+      "beneficiary_phone": "9876543210",
+      "beneficiary_address": "177A Bleecker Street",
+      "beneficiary_city": "Bangalore",
+      "beneficiary_state": "Karnataka",
+      "beneficiary_postal_code": "560001"
+    }
+  }'
+```
+
+### 2. Standard Transfer (V2)
+
+```bash
+curl -X POST 'https://sandbox.cashfree.com/payout/transfers' \
+  -H 'x-client-id: <CLIENT_ID>' \
+  -H 'x-client-secret: <CLIENT_SECRET>' \
+  -H 'x-api-version: 2024-01-01' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "beneficiary_id": "JOHN18011343",
+    "amount": 100.00,
+    "transfer_id": "TRANSFER_001",
+    "transfer_mode": "banktransfer",
+    "remarks": "Payout for order"
+  }'
+```
+
+**Transfer Modes:** `banktransfer`, `upi`, `imps`, `neft`, `rtgs`, `paytm`, `amazonpay`
+
+### 3. Direct Transfer (Without Pre-added Beneficiary)
+
+```bash
+curl -X POST 'https://payout-api.cashfree.com/payout/v1/directTransfer' \
+  -H 'Authorization: Bearer <TOKEN>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "amount": 100,
+    "transferId": "DIRECT_001",
+    "transferMode": "banktransfer",
+    "beneDetails": {
+      "bankAccount": "00111122233",
+      "ifsc": "HDFC0000001",
+      "name": "John Doe",
+      "phone": "9876543210",
+      "email": "johndoe@cashfree.com",
+      "address1": "Bangalore"
+    }
+  }'
+```
+
+### 4. Batch Transfer (V2)
+
+```bash
+curl -X POST 'https://sandbox.cashfree.com/payout/transfers/batch' \
+  -H 'x-client-id: <CLIENT_ID>' \
+  -H 'x-client-secret: <CLIENT_SECRET>' \
+  -H 'x-api-version: 2024-01-01' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "batch_transfer_id": "BATCH_001",
+    "batch_format": "BANK_ACCOUNT",
+    "delete_bene": 1,
+    "batch": [
+      {
+        "transfer_id": "TXN_001",
+        "amount": 100,
+        "phone": "9876543210",
+        "bank_account": "00111122233",
+        "ifsc": "HDFC0000001",
+        "email": "user1@email.com",
+        "name": "User One"
+      }
+    ]
+  }'
+```
+
+### 5. Get Transfer Status (V2)
+
+```bash
+curl -X GET 'https://sandbox.cashfree.com/payout/transfers/<transfer_id>' \
+  -H 'x-client-id: <CLIENT_ID>' \
+  -H 'x-client-secret: <CLIENT_SECRET>' \
+  -H 'x-api-version: 2024-01-01'
+```
+
+### 6. Get Balance
+
+```bash
+curl -X GET 'https://payout-api.cashfree.com/payout/v1/getBalance' \
+  -H 'Authorization: Bearer <TOKEN>'
+```
+
+---
+
+## Webhook Integration
+
+### Configure Webhooks
+Dashboard > Payouts > Developers > Webhooks
+
+### Webhook Events
+
+| Event | Description |
+|-------|-------------|
+| `TRANSFER_SUCCESS` | Transfer completed, account debited |
+| `TRANSFER_FAILED` | Transfer attempt failed |
+| `TRANSFER_REVERSED` | Bank reversed the transfer |
+| `TRANSFER_ACKNOWLEDGED` | Bank confirmed credit to beneficiary |
+| `TRANSFER_REJECTED` | Cashfree rejected the transfer |
+| `LOW_BALANCE_ALERT` | Account balance below threshold |
+| `CREDIT_CONFIRMATION` | Balance credited to account |
+| `BENEFICIARY_INCIDENT` | Service disruption for beneficiary bank |
+
+### Sample Webhook Payload
+
+```json
+{
+  "event": "TRANSFER_SUCCESS",
+  "transferId": "TRANSFER_001",
+  "referenceId": "123456",
+  "utr": "P16111765023806",
+  "acknowledged": 1,
+  "eventTime": "2024-01-15T10:30:00Z",
+  "signature": "base64_encoded_signature"
+}
+```
+
+### Webhook Signature Verification
+
+Verify using HMAC-SHA256 with your client secret:
+
+```javascript
+// Node.js
+const crypto = require("crypto");
+
+function verifyWebhook(req) {
+  const timestamp = req.headers["x-webhook-timestamp"];
+  const rawBody = req.rawBody; // Must use raw body, not parsed JSON
+  const secretKey = "<client-secret>";
+  
+  const signStr = timestamp + rawBody;
+  const computedSignature = crypto
+    .createHmac("sha256", secretKey)
+    .update(signStr)
+    .digest("base64");
+  
+  return computedSignature === req.headers["x-webhook-signature"];
+}
+```
+
+```python
+# Python
+import base64
+import hashlib
+import hmac
+
+def verify_webhook(request):
+    raw_body = request.data.decode('utf-8')
+    timestamp = request.headers['x-webhook-timestamp']
+    signature = request.headers['x-webhook-signature']
+    
+    sign_data = timestamp + raw_body
+    message = bytes(sign_data, 'utf-8')
+    secret = bytes("<client-secret>", 'utf-8')
+    
+    computed = base64.b64encode(
+        hmac.new(secret, message, digestmod=hashlib.sha256).digest()
+    ).decode("utf-8")
+    
+    return computed == signature
+```
+
+```java
+// Java
+import javax.crypto.Mac;
+import javax.crypto.spec.SecretKeySpec;
+import java.util.Base64;
+
+public String verifySignature(HttpServletRequest request) throws Exception {
+    String payload = request.getReader().lines().collect(Collectors.joining());
+    String timestamp = request.getHeader("x-webhook-timestamp");
+    String data = timestamp + payload;
+    
+    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
+    SecretKeySpec secretKey = new SecretKeySpec(
+        "<client-secret>".getBytes(), "HmacSHA256"
+    );
+    sha256_HMAC.init(secretKey);
+    
+    return Base64.getEncoder().encodeToString(
+        sha256_HMAC.doFinal(data.getBytes())
+    );
+}
+```
+
+### IPs to Whitelist (for receiving webhooks)
+
+**Sandbox:** `52.66.25.127`, `15.206.45.168`  
+**Production:** `52.66.101.190`, `3.109.102.144`, `18.60.134.245`, `18.60.183.142`  
+**Port:** `443` (HTTPS)
+
+---
+
+## Transfer Status Codes
+
+| Status | Description |
+|--------|-------------|
+| `SUCCESS` | Transfer completed |
+| `PENDING` | Awaiting bank confirmation |
+| `FAILED` | Transfer failed |
+| `REVERSED` | Bank reversed the transfer |
+| `REJECTED` | Rejected by Cashfree |
+
+---
+
+## Error Handling
+
+| Code | Message | Action |
+|------|---------|--------|
+| 403 | IP not whitelisted | Whitelist IP in dashboard |
+| 403 | Token is not valid | Regenerate auth token |
+| 404 | Beneficiary does not exist | Add beneficiary first |
+| 409 | Transfer Id already exists | Use unique transfer ID |
+| 412 | Not enough available balance | Add funds to account |
+| 422 | Invalid IFSC code | Verify bank details |
+
+---
+
+## Sample Integration Kits
+
+- **Node.js**: https://github.com/cashfree/cashfree-payout-node
+- **Python**: https://github.com/cashfree/cashfree-payout-python
+- **Java**: https://github.com/cashfree/cashfree-payout-java
+- **PHP**: https://github.com/cashfree/cashfree-payout-php
+
+---
+
+## Best Practices
+
+1. Always verify webhook signatures before processing
+2. Implement idempotency - webhooks may be delivered multiple times
+3. Use unique `transfer_id` for each transaction
+4. Store `reference_id` and `utr` for reconciliation
+5. Handle `PENDING` status with polling or webhooks
+6. Keep API credentials secure - never expose in frontend code
+
+---
+
+This skills file was created based on the Cashfree Payouts documentation. For more details, see:
+
+```suggestions
+(Payouts API Overview)[/api-reference/payouts/overview]
+(Webhooks V2)[/api-reference/payouts/v2/webhooks/webhooks-v2]
+(Standard Transfer Integration)[/payouts/payouts/integrations/standard-transfer]
+```

package/dist/templates/pg.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Payment Gateway skill template
+ */
+export declare function getPGSkillTemplate(): string;
+//# sourceMappingURL=pg.d.ts.map

package/dist/templates/pg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg.d.ts","sourceRoot":"","sources":["../../src/templates/pg.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAG3C"}

package/dist/templates/pg.js

@@ -0,0 +1,10 @@
+import * as fs from "fs";
+import * as path from "path";
+/**
+ * Payment Gateway skill template
+ */
+export function getPGSkillTemplate() {
+    const templatePath = path.join(__dirname, "pg.md");
+    return fs.readFileSync(templatePath, "utf8");
+}
+//# sourceMappingURL=pg.js.map

package/dist/templates/pg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg.js","sourceRoot":"","sources":["../../src/templates/pg.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAI7B;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAC9B,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACnD,OAAO,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;AACjD,CAAC"}