Installation
Integration
Option 1 — CDN (HTML)
Include the Payaza bundle script and callPayazaCheckout.setup() when the customer initiates checkout.
Option 2 — npm / yarn (JavaScript)
Option 3 — npm / yarn (TypeScript)
If
setup conflicts with a function name in your codebase, import it under an alias: import { setup as PayazaSetup } from "payaza-web-sdk";Phone number format
Thephone_number field must be in international format — country code followed by the subscriber number, with no spaces, dashes, or + prefix.
Callback response
Thecallback function fires when the payment flow completes. It receives a single response object:
Errors
Ensure all required parameters are present and correctly formatted before callingshowPopup().
Invalid merchant key
Validation error
Environment mismatch
Parameters
Required
Your public API key from the Payaza dashboard. Do not Base64-encode this —
pass the raw key directly.
Environment for the transaction. Accepts
"Live" or "Test". Must match the
environment of your merchant_key.The customer’s phone number in international format — country code
followed by the number, no spaces or dashes. Example:
"+2347012345678" for
Nigeria. See the phone number format table above.A unique identifier you generate for each transaction. Must be unique per
payment attempt — reusing a reference will cause an error.
Optional
Required only for CIV and BEN collections. Pass the ISO country code —
e.g.
"CIV" or "BEN". Not needed for NGN, GHS, or other standard
currencies.Overrides the business name shown on the checkout page. Defaults to your
registered Payaza business name if omitted.
Controls the bank transfer option in the checkout modal. Set
expires_in_minutes to define how long the virtual account stays active. Min: 15, max: 480. Defaults to 30 if omitted.Set
plan_id to the planCode value that was created using the Create Plan API or from your Payaza Dashboard which acts as a unique identifier for your subscription plan.An array containing the split account values and corresponding ratios.
Field Parameters
code(string): Set this to the unique split account identifier value that was generated using the Create Split Account API.ratio(integer): Defines the relative weighted portion used to calculate how the transaction remainder is divided between the split accounts.
Ratio Rules
The calculation matches integers directly to decimal percentage scales where1 represents 10%, 2 represents 20%, 3 represents 30%, and 4 represents 40% allocations.
Critical Rule: When assigning multiple split account elements inside this configuration array, the cumulative sum of all ratio values must equal exactly 10 in total (representing 100%).
Example Payload
Custom metadata attached to the transaction — e.g. order ID, user ID, ticket reference. Returned in the callback response. Must be a valid JSON object.
Called when the payment flow completes (success or failure). Receives the
transaction outcome object. See Callback response above.