Payment Request

Request Body

account_numberinteger

WiPay merchant account number. Use 1234567890 for sandbox testing.

country_codestring

ISO 3166-1 alpha-2 country code (uppercase). Supported: BB, GD, GY, JM, TT.

Match^[A-Z]{2}$

currencystring

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.

Match^[A-Z]{3}$

environmentstring

Transaction environment. Valid values can be fetched using the Supported Environments helper endpoint; the usable values are the items in the returned JSON array.

Value in"live" | "sandbox"

fee_structurestring

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.

Value in"customer_pay" | "merchant_absorb" | "split"

methodstring

Payment method. Uses the WiPay checkout page. The legacy value credit_card is deprecated and should not be used for new integrations.

Value in"credit_card_co"

order_idstring

Your unique order identifier. Alphanumeric, hyphens, and underscores. Must not begin or end with - or _. Recommended max length: 16.

Match^(?![_-])[a-zA-Z0-9_-]+(?<![_-])$

originstring

Your application identifier.

Match^(?![_-])[a-zA-Z0-9_-]+(?<![_-])$

Length1 <= length <= 32

response_urlstring

URL that receives the transaction response redirect.

Formaturi

Length1 <= length <= 255

totalnumber

Transaction amount (2 decimal places). Must be within the min/max limits for the selected currency.

emailstring

Customer email address. Must differ from the merchant's registered email.

Formatemail

Lengthlength <= 50

data?string

Optional integrator-supplied pass-through string echoed in the transaction response and webhook payloads. JSON is recommended for structured values but not required.

Lengthlength <= 4096

version?string

Your application version. Semantic Versioning recommended (e.g. 1.0.0).

Lengthlength <= 16

fname?string

Customer first name.

Lengthlength <= 30

lname?string

Customer last name. Requires fname.

Lengthlength <= 30

name?string

Customer full name (alternative to fname+lname). Auto-split on last space.

Lengthlength <= 60

addr1?string

Billing address line 1.

Lengthlength <= 50

addr2?string

Billing address line 2. Requires addr1.

Lengthlength <= 50

city?string

Billing city.

Lengthlength <= 30

state?string

Billing 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.

Lengthlength <= 30

zipcode?string

Billing postal/zip code.

Lengthlength <= 10

country?string

Billing country code. ISO 3166-1 alpha-2.

Match^[A-Z]{2}$

phone?string

Customer phone number in E.164 format (e.g. +18687778899).

Match^\+[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"
  }'

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_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 and assigned a transaction-attempt reference. Do not treat that response as payment confirmation. Wait for the redirect to your response_url and 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 event for later lifecycle changes.
Use data for 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.

Payment Request

Request Body

Response Body

200

400

401

Notes