Payouts API

The Payouts API handles the core transfer flow: creating single payouts, checking their status, listing history, and submitting bulk batches. Every payout requires a valid (unexpired) quote.

POST/v1/payoutsCreate a payout

GET/v1/payouts/:idGet payout status

GET/v1/payoutsList payouts

POST/v1/payouts/bulkCreate a bulk batch

GET/v1/payouts/bulk/:batch_idGet batch status

Create a payout

POST/v1/payouts

Creates a payout and returns a USDC deposit address. In production, send the exact USDC amount to this address to trigger the transfer. In sandbox, the deposit is simulated automatically.

Request body

Field	Type	Required	Description
`quote_id`	`string`	Yes	ID of an `ACTIVE` quote.
`recipient_phone`	`string`	Yes	Recipient mobile number in E.164 format (e.g. `+256700123456`).
`recipient_name`	`string`	No	Recipient's full name. Used for provider validation where required.
`network`	`string`	Yes	Mobile money network. Must match the quote's target currency. See Supported Networks.
`idempotency_key`	`string`	Yes	Unique key for deduplication. Max 128 chars.

Response

Field	Type	Description
`payout_id`	`string`	Unique payout identifier.
`status`	`string`	Initial status: `AWAITING_FUNDS`.
`deposit_address`	`string`	USDC Ethereum address to send funds to.
`source_amount_usdc`	`number`	Exact USDC amount to send.
`target_amount_fiat`	`number`	Local currency amount recipient receives.
`target_currency`	`string`	Recipient's currency.
`exchange_rate`	`number`	Locked rate from the quote.
`recipient_phone`	`string`	Destination phone.
`network`	`string`	Mobile money network.
`message`	`string`	Human-readable instruction.
`created_at`	`string`	ISO 8601 timestamp.

bash

"color:#ff7b72">curl "color:#79c0ff">-X POST https://api-sandbox.settlra.com/v1/payouts \
  "color:#79c0ff">-H "Authorization: Bearer sk_sandbox_your_key" \
  "color:#79c0ff">-H "Content-Type: application/json" \
  "color:#79c0ff">-d '{
    "quote_id": "q_01j3ab4cd5ef6gh7ij8kl9mn0p",
    "recipient_phone": "+256700123456",
    "recipient_name": "Jane Nakato",
    "network": "MTN_UG",
    "idempotency_key": "payout-abc123"
  }'

json

{
  "payout_id": "pyt_01j3pq8rs9tu0vw1xy2za3bc4d",
  "status": "AWAITING_FUNDS",
  "deposit_address": "0xA1B2C3D4E5F60718293A4B5C6D7E8F90A1B2C3D4",
  "source_amount_usdc": 500,
  "target_amount_fiat": 1871250,
  "target_currency": "UGX",
  "exchange_rate": 3742.5,
  "recipient_phone": "+256700123456",
  "network": "MTN_UG",
  "created_at": "2024-07-01T12:00:30.000Z",
  "message": "Send exactly 500.000000 USDC to 0xA1B2C3... to initiate this payout."
}

Payout status values

Status	Description
`CREATED`	Payout record created, awaiting on-chain USDC deposit.
`AWAITING_FUNDS`	Deposit address issued. Monitoring blockchain for incoming USDC.
`STABLECOIN_RECEIVED`	USDC confirmed on-chain. Compliance screening in progress.
`COMPLIANCE_HOLD`	AML or sanctions flag raised. Manual review required.
`PAYOUT_INITIATED`	Mobile money transfer sent to provider.
`PAYOUT_CONFIRMED`	Provider accepted the transfer.
`SETTLED`	Mobile money delivered to recipient. Final state.
`FAILED`	Unrecoverable failure after retries. Final state.
`REVERSED`	Funds returned to sender (e.g. compliance rejection). Final state.
`MANUAL_REVIEW`	Operations team intervention required.

Get payout status

GET/v1/payouts/:id

bash

"color:#ff7b72">curl https://api-sandbox.settlra.com/v1/payouts/pyt_01j3pq8rs9tu0vw1xy2za3bc4d \
  "color:#79c0ff">-H "Authorization: Bearer sk_sandbox_your_key"

List payouts

GET/v1/payouts

Query parameters

Parameter	Type	Default	Description
`status`	`string`	—	Filter by payout status.
`limit`	`number`	20	Number of results (1–100).
`offset`	`number`	0	Pagination offset.

bash

"color:#ff7b72">curl "https://api-sandbox.settlra.com/v1/payouts?status=SETTLED&limit=10" \
  "color:#79c0ff">-H "Authorization: Bearer sk_sandbox_your_key"

Create a bulk payout batch

POST/v1/payouts/bulk

Submit up to 100 payouts in a single batch. Each item in the array must have a pre-created quote. Returns a batch_id to track progress.

Request body

json

{
  "payouts": [
    {
      "quote_id": "q_01j3ab4cd5ef6gh7ij8kl9mn0p",
      "recipient_phone": "+256700123456",
      "recipient_name": "Jane Nakato",
      "network": "MTN_UG",
      "idempotency_key": "bulk-batch-001-item-001"
    },
    {
      "quote_id": "q_02j4bc5de6fg7hi8jk9lm0no1p",
      "recipient_phone": "+256752987654",
      "recipient_name": "Joseph Ochieng",
      "network": "AIRTEL_UG",
      "idempotency_key": "bulk-batch-001-item-002"
    }
  ]
}

Response

json

{
  "batch_id": "batch_01j3rs4tu5vw6xy7za8bc9de0f",
  "total_count": 2,
  "status": "PROCESSING",
  "created_at": "2024-07-01T12:00:00.000Z"
}

Get batch status

GET/v1/payouts/bulk/:batch_id

bash

"color:#ff7b72">curl https://api-sandbox.settlra.com/v1/payouts/bulk/batch_01j3rs4tu5vw6xy7za8bc9de0f \
  "color:#79c0ff">-H "Authorization: Bearer sk_sandbox_your_key"

json

{
  "batch_id": "batch_01j3rs4tu5vw6xy7za8bc9de0f",
  "status": "PROCESSING",
  "total": 2,
  "completed": 1,
  "failed": 0,
  "pending": 1,
  "total_amount_usdc": 1000,
  "payouts": [
    {
      "payout_id": "pyt_01j3pq8rs9tu0vw1xy2za3bc4d",
      "idempotency_key": "bulk-batch-001-item-001",
      "status": "SETTLED",
      "recipient_phone": "+256700123456"
    },
    {
      "payout_id": "pyt_02j4rs9tu0vw1xy2za3bc4de5f",
      "idempotency_key": "bulk-batch-001-item-002",
      "status": "PAYOUT_INITIATED",
      "recipient_phone": "+256752987654"
    }
  ],
  "created_at": "2024-07-01T12:00:00.000Z",
  "updated_at": "2024-07-01T12:04:12.000Z"
}