Web Pay-In (Hosted Payment Page)¶

Initiates a deposit using the Hosted Payment Page (HPP). The gateway creates a payment session and returns a URL where the end user completes the payment in their browser. This flow is ideal when you want to offload the payment UI to PayAlo.

Endpoint¶

POST /gateway/mmo/v2/web/payin/{method}

Parameter	Location	Type	Required	Description
`method`	Path	string	Yes	Payment method key configured for your brand (e.g., `card-eu`, `mpesa-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., `"EUR"`)
`payer`	Msisdn Party	End user initiating the payment
`payer.id`	string	Your identifier for the end user (max 255 chars)
`payer.msisdn`	string	Phone number in international format (3-20 chars)
`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)

Optional Fields¶

Field	Type	Description
`payer.firstName`	string	End user's first name (max 255 chars)
`payer.lastName`	string	End user's last name (max 255 chars)
`payer.email`	string	End user's email address (max 320 chars)
`successRedirectUrl`	string	URL to redirect the end user after successful payment (max 2048 chars)
`errorRedirectUrl`	string	URL to redirect the end user after failed payment (max 2048 chars)
`reconciliationReference`	string	Your reconciliation identifier (max 255 chars). Defaults to `merchantReference` if omitted.
`labels`	object	Key-value metadata (max 10 entries). See Labels.

Example Request¶

POST /gateway/mmo/v2/web/payin/card-eu HTTP/1.1
Host: api.payalo.com
X-Api-Key: <your-api-key>
Content-Type: application/json

{
  "amount": {
    "value": 25.00,
    "currency": "EUR"
  },
  "payer": {
    "id": "user-42",
    "msisdn": "+491234567890",
    "firstName": "Max",
    "lastName": "Mustermann",
    "email": "[email protected]"
  },
  "country": "DE",
  "resultUrl": "https://merchant.example.com/webhooks/payalo",
  "merchantReference": "web-dep-20240601-001",
  "successRedirectUrl": "https://merchant.example.com/payment/success",
  "errorRedirectUrl": "https://merchant.example.com/payment/error",
  "reconciliationReference": "INV-2024-003"
}

Response¶

Success — `200 OK`¶

Returns the Web Pay-In response, which extends the Initiate Payment response with HPP-specific fields.

Field	Type	Description
`status`	string	Always `"pending"`
`gatewayReference`	string	Unique transaction ID (ULID format)
`merchantReference`	string	Echo of your request
`reconciliationReference`	string	Your reconciliation reference, or `merchantReference` if not provided
`createdAt`	string	ISO 8601 timestamp
`pageUrl`	string	URL of the Hosted Payment Page. Redirect the end user to this URL.
`pageOpenMode`	string	How to open the payment page. Currently always `"redirect"`.

Example Success Response¶

{
  "status": "pending",
  "gatewayReference": "b2p01j3ghjkmn0000000000000000c3d4",
  "merchantReference": "web-dep-20240601-001",
  "reconciliationReference": "INV-2024-003",
  "createdAt": "2024-06-01T13:15:00+00:00",
  "pageUrl": "https://hpp.payalo.com/pay/session-xyz789",
  "pageOpenMode": "redirect"
}

Important: Redirect the end user's browser to pageUrl immediately. HPP sessions have a limited lifetime and will expire if not used promptly.

Error Responses¶

HTTP Status	`errorCode`	Specific code in `type` URL	Scenario
`400`	`validation_failed`	`validation_failed`	A required field is missing or invalid.
`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": "Currency is not supported.",
  "errorCode": "validation_failed"
}

Redirect Flow¶

After receiving a successful response:

Redirect the end user's browser to the pageUrl.
The end user completes the payment on the Hosted Payment Page.
On completion, the end user is redirected to:
successRedirectUrl if the payment succeeds (if provided)
errorRedirectUrl if the payment fails (if provided)
Regardless of redirect, the gateway sends a callback to your resultUrl with the final transaction status.

sequenceDiagram
    participant U as End User (Browser)
    participant M as Your Server
    participant G as PayAlo Gateway
    participant H as Hosted Payment Page

    U->>M: Initiate checkout
    M->>G: POST /web/payin/{method}
    G-->>M: 200 { gatewayReference, pageUrl }
    M-->>U: 302 Redirect to pageUrl
    U->>H: GET pageUrl (browser opens HPP)
    Note over U,H: User enters payment details and confirms

    alt Payment succeeded
        H-->>U: 302 Redirect to successRedirectUrl
    else Payment failed or cancelled
        H-->>U: 302 Redirect to errorRedirectUrl
    end

    U->>M: Lands on success/error page (UX only)

    Note over G: Some time later (async)
    G->>M: POST resultUrl<br/>(authoritative status)
    M-->>G: 2xx (body informational only)

Note: The redirect URLs are for user experience only. Always rely on the callback to your resultUrl for authoritative transaction status — do not use the redirect as confirmation of payment. The end user can close the browser before the redirect happens, or land on the success page even though the underlying payment ultimately 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.