This page documents the exact request/response schema and behaviors for the server‑to‑server card payments endpoint, matching the current implementation.
Endpoint #
– Method: POST
– Path: `/v1/payments/server-to-server`
– Auth: HMAC (see Authentication docs)
– Content-Type: `application/json`
Request Body #
Top‑level fields your backend sends to the TrustistEcommerce API.
Required
– `amount` (number): Payment amount in GBP (e.g., 99.99)
– `reference` (string): Your unique order/transaction reference
– `cardDetails` (object): See CardDetails
– `browserData` (object): See BrowserData
Optional
– `description` (string): Payment description
– `customerDetails` (string): Customer information for your records
– `payerEmail` (string): Customer email used for receipts/status
– `billingAddress` (object): See BillingAddress
– `workflow` (object): Optional flags (e.g., `mode: “RemoteOnly”`, `suppressMerchantEmails`, `suppressPayerEmails`)
– `partnerId` (string): Optional partner identifier
– `partnerReference` (string): Optional partner reference string
– `customerId` (string): Optional existing customer identifier (must belong to the authenticated merchant)
CardDetails #
– `number` (string, required): Card number (13–19 digits, no spaces)
– `expiryMonth` (string, required): Month in `MM` format (e.g., “12”)
– `expiryYear` (string, required): Year in `YYYY` format (e.g., “2026”)
– `cvc` (string, required): Security code (3–4 digits)
BillingAddress (optional) #
– `firstName` (string)
– `lastName` (string)
– `lineOne` (string)
– `lineTwo` (string)
– `city` (string)
– `country` (string, ISO 2 e.g., “GB”)
– `postalCode` (string)
– `region` (string)
BrowserData (required) #
Matches `ProcessServerToServerBrowserData`.
– `browserJavaEnabled` (boolean)
– `browserJavascriptEnabled` (boolean)
– `browserLanguage` (string)
– `browserColorDepth` (number)
– `browserScreenHeight` (number)
– `browserScreenWidth` (number)
– `browserTZ` (string) – time zone; collect client value, server may normalise
– `browserUserAgent` (string)
– `browserAcceptHeader` (string)
– `browserIP` (string) – your server should set the true client IP if available
– `browserJavaEnabledString` (string: “true”|”false”)
– `challengeWindowSize` (string) – e.g., “FULLSCREEN”, “500×600”
– `deviceChannel` (string) – “Browser” or “Application”
Responses #
The API returns one of the following JSON objects with HTTP 200 on success.
Frictionless (no bank authentication required) #
{
"id": "<payment-id>",
"status": "COMPLETE",
"requiredAction": null
}Bank authentication required (hosted page) #
{
"id": "<payment-id>",
"status": "PENDING_ACTION",
"requiredAction": {
"type": "redirect",
"url": "https://.../challenge?paymentId=<payment-id>"
}
}Notes
– `requiredAction.type` is normalised to `”redirect”`.
– `requiredAction.url` is a Trustist‑hosted authentication page. Open it in an iframe, lightbox, or full redirect.
– After completion, the payment is finalised server‑side and your frontend receives a completion postMessage from the hosted page.
Errors (validation/business rules) #
HTTP 400 with body:
{ "error": "<message>" }Common messages include:
– “Invalid card number length or format”
– “Card expiry date is in the past”
– “American Express cards are not accepted by this merchant”
Other error codes (e.g., 401/403/500) follow standard semantics and include a string message body.
Behavioural Notes #
– Frictionless approvals are finalised before the response – expect `status: “COMPLETE”` immediately.
– When `requiredAction` is returned, the hosted page completes the bank challenge and then finalises the payment automatically.
– Webhooks provide the authoritative status for fulfilment.
Idempotency & Reliability #
– The processing pipeline is idempotent; retries will not double‑charge.
– Use your `reference` to correlate orders.
– Rely on webhooks for fulfilment updates (see Merchant Webhooks).
Example Request #
{
"amount": 10.00,
"reference": "ORDER-12345",
"payerEmail": "customer@example.com",
"cardDetails": {
"number": "4444333322221111",
"expiryMonth": "12",
"expiryYear": "2026",
"cvc": "123"
},
"billingAddress": {
"firstName": "John",
"lastName": "Smith",
"lineOne": "123 High Street",
"city": "London",
"country": "GB",
"postalCode": "SW1A 1AA"
},
"browserData": {
"browserJavaEnabled": false,
"browserJavascriptEnabled": true,
"browserLanguage": "en-GB",
"browserColorDepth": 24,
"browserScreenHeight": 1080,
"browserScreenWidth": 1920,
"browserTZ": "Europe/London",
"browserUserAgent": "Mozilla/5.0...",
"browserAcceptHeader": "*/*",
"browserIP": "203.0.113.42",
"browserJavaEnabledString": "false",
"challengeWindowSize": "FULLSCREEN",
"deviceChannel": "Browser"
}
}Example Success Responses #
Frictionless
{ "id": "3PAY...", "status": "COMPLETE", "requiredAction": null }Challenge
{ "id": "3PAY...", "status": "PENDING_ACTION", "requiredAction": { "type": "redirect", "url": "https://.../challenge?paymentId=3PAY..." } }Example Error #
{ "error": "Invalid card number length or format" }