Create Trusted Card

Start the trusted card creation process. This returns a URL to a secure hosted page where the user enters their card details.

This flow uses the same hosted checkout and response_url redirect model as the Payments API, with trusted-card-specific response semantics. See Hosted Checkout Flows.

This feature is available to verified WiPay accounts and is not limited to BUSINESS accounts. Availability still depends on the endpoint's verification, environment, and trusted-card eligibility rules.

Endpoint

POST /trusted-cards

Access	Requirement
Authenticated	Yes
Required Scope	`wapi-trusted-cards-create`, 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.

Body (form-data)

Parameter	Type	Required	Description
`environment`	string	Yes	`"sandbox"` or `"live"`
`response_url`	string	Yes	URL to redirect the user after card entry

Notes:

response_url must be a valid URL up to 255 characters.
Trusted Card creation uses a USD hosted enrollment request and merchant-absorb fee handling for the verification flow.
For sandbox card numbers used on the hosted card-entry page, see Testing → Trusted Card Sandbox Cards.

Responses

200 OK

{
  "message": "OK",
  "url": "https://ttsb.wipayfinancial.com/checkout/payment?_data=...",
  "transaction_id": "SB-12-30105-qc6TE4CBFk-20241107020132"
}

Field	Type	Description
`url`	string	Redirect URL for the hosted card entry page
`transaction_id`	string	Transaction ID for this card creation request

On a successful redirect, WiPay appends a uuid for the trusted card to your response_url. In live environments, the micro-charge total is intentionally omitted from the response parameters; in sandbox it is included to aid testing.

400 Bad Request

{
  "message": "The selected environment is invalid."
}

401 Unauthorized

{
  "message": "Unauthorized"
}

403 Forbidden

Card already exists

{
  "message": "This user already has a trusted card."
}

Trusted card creation is not allowed

{
  "message": "..."
}

Invalid scopes

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

Example

curl -X POST https://ttsb.wipayfinancial.com/wapi/trusted-cards \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -F "environment=sandbox" \
  -F "response_url=https://example.com/callback"

On this page