Skip to content

PayAlo Documentation

Direct Tax Payout

Direct Tax Payout¶

Initiates a payout to a tax authority. Unlike other endpoints, this does not require a payer or payee object — the recipient is implicitly the tax authority associated with the payment method and country.

Endpoint¶

POST /gateway/mmo/v2/direct/taxpayout/{method}

Parameter	Location	Type	Required	Description
`method`	Path	string	Yes	Payment method key configured for your brand (e.g., `tax-ke`). Max 100 characters.

Request Body¶

Required Fields¶

Field	Type	Description
`amount`	Money	Payment amount and currency
`amount.value`	decimal	Amount value. Must be greater than 0.
`amount.currency`	string	ISO 4217 currency code (e.g., `"KES"`)
`country`	string	ISO 3166-1 alpha-2 country code (max 10 chars)
`resultUrl`	string	HTTPS URL to receive the async result callback (max 2048 chars)
`merchantReference`	string	Unique idempotency key for this transaction (max 255 chars)
`reconciliationReference`	string	Your reconciliation identifier (max 255 chars)

Note: Unlike other endpoints, reconciliationReference is required for tax payouts.

Optional Fields¶

Field	Type	Description
`labels`	object	Key-value metadata (max 10 entries). See Labels.

Example Request¶

POST /gateway/mmo/v2/direct/taxpayout/tax-ke HTTP/1.1
Host: api.payalo.com
X-Api-Key: <your-api-key>
Content-Type: application/json

{
  "amount": {
    "value": 15000.00,
    "currency": "KES"
  },
  "country": "KE",
  "resultUrl": "https://merchant.example.com/webhooks/payalo",
  "merchantReference": "tax-20240601-001",
  "reconciliationReference": "TAX-Q2-2024-001",
  "labels": {
    "taxPeriod": "Q2-2024",
    "taxType": "VAT"
  }
}

Response¶

Success — `200 OK`¶

Returns the Initiate Payment response.

Field	Type	Description
`status`	string	Always `"pending"`
`gatewayReference`	string	Unique transaction ID (ULID format)
`merchantReference`	string	Echo of your request
`reconciliationReference`	string	Echo of your `reconciliationReference`
`createdAt`	string	ISO 8601 timestamp

Example Success Response¶

{
  "status": "pending",
  "gatewayReference": "b2p01j3efghjk0000000000000000a7b8",
  "merchantReference": "tax-20240601-001",
  "reconciliationReference": "TAX-Q2-2024-001",
  "createdAt": "2024-06-01T14:00:00+00:00"
}

Error Responses¶

HTTP Status	`errorCode`	Specific code in `type` URL	Scenario
`400`	`validation_failed`	`validation_failed`	A required field is missing or invalid (including `reconciliationReference`).
`400`	`validation_failed`	`config_unsupported_country` / `config_unsupported_currency` / `config_unsupported_payment_method` / `config_method_transaction_min_limit` / `config_method_transaction_max_limit`	Country, currency, payment method, or amount is not allowed by your brand configuration.
`400`	`validation_failed`	`merchant_disabled`	Your brand has been disabled.
`400`	`bad_request`	`bad_request`	Request body is malformed or unreadable.
`401`	`unauthorized`	`unauthorized`	API key is missing or invalid.
`404`	`not_found`	`not_found`	Resource not found.
`422`	`merchant_transactionid_duplicate`	`merchant_transactionid_duplicate`	Duplicate `merchantReference`.
`500`	`internal_server_error`	`internal_server_error`	Unexpected server error.

See Error Handling for the full error response structure and error code reference.

Example Error Response — `400 Bad Request`¶

{
  "type": "https://docs.payalo.com/errors/validation_failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "ReconciliationReference is required.",
  "errorCode": "validation_failed"
}

Callback¶

When the transaction reaches a terminal state (success or failed), the gateway sends a webhook to your resultUrl. See Callback Documentation for payload format, signature verification, and retry policy.

Status Flow¶

graph LR
    pending --> success
    pending --> failed

The transaction enters pending on creation. After asynchronous processing it moves to either success or failed. See Transaction Lifecycle for full details.