Charge Trusted Card

Initiate a payment using a verified trusted card. Returns a URL for the hosted checkout and a transaction ID.

This flow behaves like a Payments API checkout request and reuses the same response_url redirect pattern. See Hosted Checkout Flows.

Endpoint

POST /trusted-cards/{uuid}/charge

Access	Requirement
Authenticated	Yes
Required Scope	`wapi-trusted-cards-charge-request`, or `wapi-trusted-cards-all`
Rate Limit	15 requests per minute

Request

Headers

Header	Value
`Accept`	`application/json`
`Authorization`	`Bearer <access_token>`
`X-WAPI-Key`	`wapi_live_<kid>_<secret>` or `wapi_test_<kid>_<secret>`

Send exactly one of Authorization or X-WAPI-Key.

Path Parameters

Parameter	Type	Required	Description
`uuid`	string	Yes	The UUID of the verified trusted card

Body (form-data)

Parameter	Type	Required	Description
`account_number`	string	Conditional	Authorized MMA account number used to resolve the charging context
`total`	string	Yes	Payment amount (e.g., `"155.00"`)
`currency`	string	Yes	Currency code (e.g., `"USD"`)
`fee_structure`	string	Yes	Fee arrangement: `"customer_pay"`, `"merchant_absorb"`, or `"split"`
`order_id`	string	Yes	Your unique order/reference ID
`origin`	string	Yes	Identifier for the source of the charge
`environment`	string	No	`"sandbox"` or `"live"`. If provided, must match the trusted card's environment. Overridden by the card's stored environment.
`country_code`	string	No	Two-letter country code. If provided, must match the platform's country code. Overridden by platform configuration.
`response_url`	string	Yes	URL for the payment result callback
`data`	string	No	Optional JSON string (max 8192 characters) merged into the downstream Payments API `data` payload

Notes:

uuid must be a valid UUID.
account_number must be a numeric string when provided.
account_number is required when the authenticated caller belongs to an MMA and needs to identify the authorized MMA account for the charge.
The endpoint validates account_number for authorization, then forwards the payment request using the authenticated user's own account number and the trusted card's stored environment.
If environment is provided, it must be "sandbox" or "live" and must match an environment where the trusted card has been used. The value is overridden by the card's stored environment.
If country_code is provided, it must match the platform's country code. The value is overridden by platform configuration.
If data is provided, it must be valid JSON and must not exceed 8192 characters.
For sandbox card numbers used when creating and verifying a trusted card for charge testing, see Testing → Trusted Card Sandbox Cards.

Responses

200 OK

{
  "message": "OK",
  "url": "https://ttsb.wipayfinancial.com/checkout/payment?_data=...",
  "transaction_id": "SB-47-1-oId_123-20241028001909"
}

Field	Type	Description
`url`	string	Checkout URL for payment processing
`transaction_id`	string	Unique transaction identifier for tracking

The redirect to response_url reuses the Payments API Transaction Response model.

400 Bad Request

Missing UUID

{
  "message": "The uuid is not a valid UUID (version 4)."
}

Invalid authorized account

{
  "message": "The selected account number is invalid."
}

Invalid country code

{
  "message": "The selected country code is invalid."
}

Invalid environment for this trusted card

{
  "message": "Invalid environment for your verified Trusted Card."
}

401 Unauthorized

{
  "message": "Unauthorized"
}

403 Forbidden

Unauthorized MMA context

{
  "message": "The provided account number must be authorized before proceeding."
}

Trusted card must be verified

{
  "message": "Please verify your Trusted Card before proceeding."
}

Invalid scopes

{
  "message": "Invalid scope(s) provided."
}

Example

curl -X POST "https://ttsb.wipayfinancial.com/wapi/trusted-cards/213e4777-2179-4fbd-9540-84e8ed83187a/charge" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -F "total=155.00" \
  -F "currency=USD" \
  -F "fee_structure=customer_pay" \
  -F "order_id=oId_123" \
  -F "origin=example-origin" \
  -F "environment=sandbox" \
  -F "country_code=TT" \
  -F "response_url=https://example.com/callback"

On this page