​

Payments Overview

​

Core Concepts

​

Collections (Incoming Payments)

1. A checkout session is created with a unique URL
2. Customer is redirected to Fyatu’s checkout page
3. Customer logs in and authorizes the payment
4. Funds are transferred from customer to your business wallet
5. You receive a webhook notification

Customer → Checkout Page → Authorization → Your Business Wallet

​

Payouts (Outgoing Payments)

1. Verify the recipient’s account
2. Create the payout with amount and recipient
3. Funds are instantly transferred
4. Recipient receives notification

Your Business Wallet → Fyatu Account → Recipient

​

Refunds

• Choose between FULL or PARTIAL refund mode at refund time
• Each collection can only be refunded once - choose wisely
• Processing fees are non-refundable
• Maximum refundable amount = Net amount (original - fee)
• Debited from your business wallet
• Use a predefined reason code (see GET /refunds/reasons)

​

Payment Flow

​

Collection Flow

​

Payout Flow

​

Fees

​

Collection Fees

​

Payout Fees

​

Refund Fees

• No additional fee for refunds
• Original collection fee is not refundable
• Maximum refund = Net amount (original - fee)

​

Statuses

​

Collection Statuses

​

Payout Statuses

​

Refund Statuses

​

Webhooks

​

Collection Webhook Payload

{
  "event": "collection.completed",
  "data": {
    "collectionId": "SCI679A1B2C3D4E5",
    "reference": "A2B4C6D8E0F2",
    "orderId": "INV-001",
    "amount": 25.00,
    "fee": 0.75,
    "netAmount": 24.25,
    "currency": "USD",
    "status": "COMPLETED",
    "payer": {
      "name": "John Doe",
      "email": "[email protected]"
    },
    "completedAt": "2026-01-08T11:35:00+00:00"
  },
  "timestamp": "2026-01-08T11:35:01+00:00"
}

​

Webhook Security

1. Checking the source IP
2. Validating the signature (if implemented)
3. Verifying the payment via API before fulfilling orders

​

Best Practices

​

For Collections

1. Use Order IDs: Link collections to your order system
2. Set Webhook URL: Receive real-time notifications
3. Verify via API: Always confirm payment server-side
4. Handle Expiry: Sessions expire after 60 minutes
5. Prevent Duplicates: Use unique order IDs

​

For Payouts

1. Verify First: Always verify recipient before paying
2. Use References: Track payouts with unique references
3. Check Balance: Ensure sufficient wallet balance
4. Monitor Limits: Track daily/monthly limits
5. Store IDs: Keep payout IDs for support

​

For Refunds

1. One Refund Only: Each collection can only be refunded once - choose FULL or PARTIAL wisely
2. Use Reason Codes: Always include a predefined refund reason code
3. Wallet Balance: Ensure balance covers refund amount
4. Track Refunds: Monitor refund rates for fraud detection
5. Communicate: Notify customers about refund status

​

Integration Checklist

​

Error Handling

​

Common Errors

​

Retry Logic

async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status >= 500 && i < maxRetries - 1) {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}

​

Related Endpoints

​

Collections

• POST /collections - Create checkout session
• GET /collections/{id} - Get collection details
• GET /collections - List collections

​

Refunds

• POST /collections/{id}/refund - Create refund
• GET /refunds - List refunds
• GET /refunds/reasons - Get available refund reason codes

​

Payouts

• GET /accounts/{clientId} - Verify recipient
• POST /payouts - Create payout
• GET /payouts/{id} - Get payout details
• GET /payouts - List payouts