Payment Request
Send a payment request to WiPay's Hosted Payment Page
WiPay merchant account number. Use 1234567890 for sandbox testing.
ISO 3166-1 alpha-2 country code (uppercase). Supported: BB, GD, GY, JM, TT.
^[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. Uses the WiPay checkout page. The legacy value credit_card is deprecated and should not be used for new integrations.
"credit_card_co"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 <= 50JSON string of custom data to pass through to the response.
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 <= 10Billing country code. ISO 3166-1 alpha-2.
^[A-Z]{2}$Customer phone number in E.164 format (e.g. +18687778899).
^\+[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"
}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. Do not treat that response as payment confirmation. Wait for the final redirect to your
response_urland verify the result server-side. - Hosted checkout transactions can remain pending briefly while WiPay completes gateway processing, timeout handling, or recovery. See Hosted Checkout Flows for the transaction lifecycle.