Skip to main content
Create and manage payouts programmatically.

​
Endpoints

MethodEndpointDescription
GET/payoutsList payouts
GET/payouts/:idGet payout
POST/payoutsCreate payout

​
List Payouts

GET /mfi/payouts

​
Query Parameters

ParameterTypeDescription
pagenumberPage number (default: 1)
limitnumberItems per page (default: 20, max: 100)
statusstringFilter: pending_approval, approved, rejected, executing, completed, failed
typestringFilter: direct, disbursement
searchstringSearch by client name or wallet address

​
Response

{
  "data": [
    {
      "id": "pyt_xxxxxxxx",
      "type": "direct",
      "clientId": "cli_xxxxxxxx",
      "client": {
        "id": "cli_xxxxxxxx",
        "firstName": "Jean",
        "lastName": "Pierre",
        "walletAccountId": "GABC...XYZ"
      },
      "walletAccountId": "GABC...XYZ",
      "assetAmount": "1000.00",
      "assetCode": "HTG",
      "memo": "Refund for order #123",
      "approvalStatus": "approved",
      "execStatus": "sent",
      "createdAt": "2026-01-25T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 25,
    "page": 1,
    "limit": 20,
    "totalPages": 2
  },
  "counts": {
    "all": 25,
    "pending_approval": 2,
    "approved": 3,
    "rejected": 1,
    "executing": 0,
    "completed": 18,
    "failed": 1
  }
}

​
Get Payout

GET /mfi/payouts/:id

​
Response

{
  "id": "pyt_xxxxxxxx",
  "type": "direct",
  "clientId": "cli_xxxxxxxx",
  "client": {
    "id": "cli_xxxxxxxx",
    "firstName": "Jean",
    "lastName": "Pierre",
    "phoneNumber": "+50912345678",
    "email": "[email protected]",
    "walletAccountId": "GABC...XYZ"
  },
  "walletAccountId": "GABC...XYZ",
  "assetAmount": "1000.00",
  "assetCode": "HTG",
  "assetIssuer": "GHTG...ISSUER",
  "memo": "Refund for order #123",
  "approvalStatus": "approved",
  "execStatus": "sent",
  "createdAt": "2026-01-25T10:00:00Z",
  "updatedAt": "2026-01-25T10:05:00Z",
  "attempts": [
    {
      "id": "att_xxxxxxxx",
      "attemptNumber": 1,
      "txHash": "abc123def456...",
      "ledgerSeq": 12345678,
      "errorCode": null,
      "errorMessage": null,
      "createdAt": "2026-01-25T10:05:00Z"
    }
  ]
}

​
Create Payout

POST /mfi/payouts

​
Request Body

{
  "clientId": "cli_xxxxxxxx",
  "assetAmount": 1000.00,
  "assetCode": "HTG",
  "memo": "Refund for order #123"
}
Or with direct wallet address: 
{
  "walletAccountId": "GABC...XYZ",
  "assetAmount": 1000.00,
  "assetCode": "HTG",
  "memo": "Payment to vendor"
}

​
Fields

FieldTypeRequiredDescription
clientIdstringNo*Client ID (uses client’s wallet address)
walletAccountIdstringNo*Direct Stellar wallet address
assetAmountnumberYesAmount to send
assetCodestringYesCurrency code (HTG, USD)
assetIssuerstringNoAsset issuer (null for native XLM)
memostringNoTransaction memo (max 28 characters)
*Either clientId or walletAccountId must be provided.

​
Validation

  • walletAccountId must be a valid Stellar address (56 characters, starts with G)
  • assetAmount must be positive
  • assetCode max 12 characters
  • memo max 28 characters (Stellar memo limit)

​
Response

Returns the created payout (same format as Get Payout).

​
Payout Status

​
Approval Status

StatusDescription
pendingAwaiting approval
approvedApproved, ready for execution
rejectedApproval denied

​
Execution Status

StatusDescription
pendingNot yet executed
ready_to_sendQueued for execution
sentSuccessfully completed
failedExecution failed

​
Errors

StatusCodeDescription
400invalid_clientClient not found
400no_walletClient has no wallet address
400invalid_walletInvalid Stellar address format
400invalid_amountAmount must be positive
400missing_recipientEither clientId or walletAccountId required
404not_foundPayout not found

​
Webhooks

Subscribe to payout events:
  • payout.created
  • payout.approved
  • payout.rejected
  • payout.completed
  • payout.failed
See Webhooks for setup instructions.