Payment Request

Submit a payment request to WiPay to initiate a credit/debit card transaction through the Hosted Payment Page.

Base URL

Payments API uses the shared country-based live and sandbox host pattern documented in Platforms and Environments.

Append /plugins/payments/request to the selected base URL.
Use the WiPay platform where the merchant account exists.
Use the sandbox or live host that matches the target environment.

Endpoint

POST https://{country_code}.wipayfinancial.com/plugins/payments/request

Authentication: None — requests are identified by account_number (a verified WiPay BUSINESS Account number)

Use the selected base URL, then append /plugins/payments/request.

Request

Headers

Header	Value	Required
`Accept`	`application/json`	Only for JSON response mode
`Accept`	`/` or omitted	For browser redirect mode
`Content-Type`	`application/x-www-form-urlencoded`	For API calls

Body Parameters

Required Parameters

Parameter	Type	Description
`account_number`	integer	Your WiPay account number. Use `1234567890` for sandbox testing.
`country_code`	string	Two-letter WiPay platform code, such as `BB`, `GD`, `GY`, `JM`, or `TT`.
`currency`	string	Three-letter transaction currency code for the selected platform.
`environment`	string	`live` or `sandbox`.
`fee_structure`	string	Fee arrangement: `customer_pay`, `merchant_absorb`, or `split`.
`method`	string	Payment method for the request. Standard hosted card integrations use `credit_card`.
`order_id`	string	Your unique order/reference ID.
`origin`	string	Identifier for your application, for example `MyApp-v1.0`.
`response_url`	string	URL that will receive the transaction response as a query-string redirect.
`total`	number	Payment amount.

Optional Parameters

Parameter	Type	Description
`avs`	boolean	Enable Address Verification System. `1` = enabled, `0` = disabled. Default: `0`.
`data`	string	Optional JSON string to pass through to the response.
`email`	string	Customer email address. Returned as `customer_email` in the response. Also pre-fills the AVS form email field when `avs=1`.
`version`	string	Your application's version number. Semantic Versioning recommended.

Notes:

account_number is validated as an integer merchant identifier and must belong to an account that can process the requested total, currency, and environment.
country_code must be uppercase, must refer to a supported active WiPay platform, and can trigger platform redirection if the request reaches the wrong country host.
currency must be uppercase, ISO 4217 compliant, and supported on the selected platform.
email must be a valid email address up to 50 characters.
order_id and origin may contain letters, numbers, dashes, and underscores, but must not begin or end with a dash or underscore.
origin is limited to 32 characters.
response_url must be a valid URL up to 255 characters.
total must be normalized to 2 decimal places. The backend also enforces gateway and origin-specific minimum and maximum transaction limits and rejects values above 99999999.99.
data must be valid JSON and can be up to 40960 characters. WiPay security logic may still alter or omit the returned value.
version can be up to 16 characters.

order_id length depends on the hosted checkout configuration behind the transaction.

To maximize compatibility across configurations, keep order_id at 16 characters or fewer.
Some configurations accept up to 48 characters.

AVS Parameters (Optional)

These parameters pre-fill the Address Verification form on the Hosted Payment Page. They are only relevant when avs=1.

Parameter	Type	Description
`addr1`	string	Street address of the cardholder
`addr2`	string	Apartment, suite, floor, or similar secondary address line
`city`	string	City of residence
`country`	string	Country of residence
`fname`	string	Cardholder first name. Concatenated with `lname` as `customer_name` in the response.
`lname`	string	Cardholder last name. Must be used together with `fname`.
`name`	string	Full name alternative to `fname` and `lname`.
`phone`	string	Cardholder phone number. Returned as `customer_phone` for non-AVS flows.
`state`	string	State or subdivision value used for AVS checks
`zipcode`	string	Zip or postal code

AVS notes:

addr1 can be up to 50 characters.
addr2 can be up to 50 characters and requires addr1.
city can be up to 30 characters.
country must be an uppercase ISO 3166-1 alpha-2 code.
fname and lname can be up to 30 characters each, and lname requires fname.
name can be up to 60 characters.
phone accepts common phone-number characters and is normalized toward E.164 when AVS validation is active.
state is primarily relevant for US-based AVS checks.
zipcode can be up to 10 characters.

If you send name without fname and lname in an AVS flow, WiPay attempts to split the last word into lname and the preceding words into fname.

Responses

200 OK (JSON mode)

{
  "url": "https://tt.wipayfinancial.com/checkout/...",
  "message": "OK",
  "transaction_id": "SB-12-1-oid_123-aBc-20210616024001"
}

Field	Type	Description
`url`	string	URL to redirect the customer to the Hosted Payment Page
`message`	string	Status message
`transaction_id`	string	WiPay's unique identifier for this transaction. The API attempts to return it whenever possible, but clients should not treat it as guaranteed on every error path.

400 Bad Request

{
  "url": "https://example.com/response?status=error&reasonDescription=The%20country%20code%20field%20is%20required.",
  "message": "The country code field is required."
}

Web Redirect Mode

When using an HTML form submission, or omitting Accept: application/json, the customer is automatically redirected to the Hosted Payment Page. No JSON response is returned.

Notes

The total must be correct to 2 decimal places (e.g., 10.00).
Based on the configured fee_structure, the final amount charged to the customer may differ from the total. See Fee Rates for details.
The minimum transaction amount is $1.00 USD or the currency-value equivalent.
The response_url will receive transaction results as a query string. See Transaction Response for all response parameters.
The transaction_id is 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 request account_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_url and 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.

Example

curl -X POST https://ttsb.wipayfinancial.com/plugins/payments/request \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "account_number=1234567890" \
  -d "avs=0" \
  -d "country_code=TT" \
  -d "currency=USD" \
  -d "environment=sandbox" \
  -d "fee_structure=customer_pay" \
  -d "method=credit_card" \
  -d "order_id=oid_123-aBc" \
  -d "origin=WiPay-example_app" \
  -d "response_url=https://example.com/response" \
  -d "total=10.00"

On this page