Payment Request
Send a payment request to WiPay's Hosted Payment Page
WiPay merchant account number. Use 1234567890 for sandbox testing.
WiPay processing platform as an uppercase ISO 3166-1 alpha-2 country code. Supported: BB, GD, GY, JM, TT. This does not prefill the customer's billing-country or phone controls.
^[A-Z]{2}$ISO 4217 currency code (uppercase). Valid values can be fetched using the Supported Currencies helper endpoint; the usable values are the items in the returned JSON array.
^[A-Z]{3}$Transaction environment. Valid values can be fetched using the Supported Environments helper endpoint; the usable values are the items in the returned JSON array.
"live" | "sandbox"Determines who pays the processing fee. Valid values can be fetched using the Supported Fee Structures helper endpoint; the usable values are the keys of the returned JSON object.
"customer_pay" | "merchant_absorb" | "split"Payment method. credit_card_co uses the full WiPay checkout page. 3co_simple uses a simplified WiPay checkout page designed for iframe or redirect flows. The legacy value credit_card is deprecated and should not be used for new integrations.
"credit_card_co" | "3co_simple"Your unique order identifier. Alphanumeric, hyphens, and underscores. Must not begin or end with - or _. Recommended max length: 16.
^(?![_-])[a-zA-Z0-9_-]+(?<![_-])$Your application identifier.
^(?![_-])[a-zA-Z0-9_-]+(?<![_-])$1 <= length <= 32URL that receives the transaction response redirect.
uri1 <= length <= 255Transaction amount (2 decimal places). Must be within the min/max limits for the selected currency.
Customer email address. Must differ from the merchant's registered email.
emaillength <= 50Optional integrator-supplied pass-through string echoed in the transaction response and webhook payloads. JSON is recommended for structured values but not required.
length <= 4096Your application version. Semantic Versioning recommended (e.g. 1.0.0).
length <= 16Customer first name.
length <= 30Customer last name. Requires fname.
length <= 30Customer full name (alternative to fname+lname). Auto-split on last space.
length <= 60Billing address line 1.
length <= 50Billing address line 2. Requires addr1.
length <= 50Billing city.
length <= 30Billing state/province ISO 3166-2 code. Valid values can be fetched using the Get States/Subdivisions helper endpoint; the usable values are the keys of the returned JSON object.
length <= 30Billing postal/zip code.
length <= 10Optional customer billing country as an uppercase ISO 3166-1 alpha-2 code. For credit_card_co and 3co_simple, prefills both the Billing Country and phone dialing-country selectors; for the United States, use US. A complete valid E.164 phone value overrides this value only for the phone selector.
^[A-Z]{2}$Optional customer phone number in E.164 format. A complete valid E.164 number prefills the phone field and selects its matching dialing country, overriding country only for the phone selector.
^\+[1-9]\d{1,14}$Response Body
curl -X POST "https://tt.wipayfinancial.com/plugins/payments/request" \ -H "Content-Type: application/json" \ -d '{ "account_number": 1234567890, "country_code": "TT", "currency": "TTD", "environment": "sandbox", "fee_structure": "customer_pay", "method": "credit_card_co", "order_id": "order123", "origin": "MyApp", "response_url": "https://example.com/payment/callback", "total": 25, "email": "user@example.com" }'{
"url": "https://tt.wipayfinancial.com/checkout/payment?...",
"message": "OK",
"transaction_id": "SB-12-1-order123-20260310120000"
}{
"url": "https://example.com/payment/callback?status=error&reasonDescription=...",
"message": "The country code field is required.",
"transaction_id": ""
}{
"message": "string",
"url": "http://example.com",
"transaction_id": "string"
}Checkout Prefill
The country-related request fields have separate purposes:
country_codeselects the WiPay processing platform. Use the platform associated with the merchant account, such asJM; do not change it to represent the customer's billing country.countryoptionally prefills the customer's Billing Country selector and the phone dialing-country selector. Use an uppercase ISO 3166-1 alpha-2 code such asUS.phoneoptionally prefills the phone field. A complete valid E.164 number selects its matching dialing country instead of thecountryvalue for the phone selector.
For example, a payment processed on the Jamaica platform for a customer with a United States billing address and phone number can include:
{
"country_code": "JM",
"country": "US",
"phone": "+12025550123"
}For both credit_card_co and 3co_simple, country sets both selectors when phone is omitted or is not a complete valid E.164 number. A complete valid E.164 phone value overrides country only for the phone selector; country continues to set the Billing Country selector. For AVS requests, provide a valid state when the selected billing country has subdivisions; use Get States/Subdivisions to retrieve accepted values.
Notes
- The
transaction_idis assigned at the time of the request, before the customer completes checkout. - The sandbox API Key is
123, but it is used only for server-side hash verification, not as the requestaccount_number. - A successful request response only means WiPay created the hosted checkout session and assigned a transaction-attempt reference. Do not treat that response as payment confirmation. Wait for the redirect to your
response_urland verify the result server-side. - A transaction attempt can remain pending briefly while WiPay waits for the gateway's final result. See Hosted Checkout Flows for the hosted-checkout lifecycle.
- If you also consume Payments API webhooks, use the browser redirect for the immediate checkout result and the webhook
eventfor later lifecycle changes. - Use
datafor integration-specific context you want echoed back after checkout, such as a cart ID or invoice ID. JSON is recommended for structured values but not required. See Pass-Through Data.