Payment Attempts

Payment attempts provide a unified way to start and track how a payment is executed, whether by Open Banking bank redirect or card processing.

New to Trustist payment models? Start with Payments Overview.

Key idea: Create the payment first, then create one or more attempts against that payment. Each attempt can return a requiredAction for your frontend to execute.

Why Attempts Exist

  • A payment stores commercial context (amount, reference, return URL, customer context).
  • An attempt stores execution context (bank/card details, current status, action required).
  • You can retry safely by creating a new attempt instead of mutating payment state manually.
  • The same API model is used for both bank and card flows.

Flow Overview

  1. Create payment via POST /v1/payments.
  2. (Bank flow) fetch available banks via GET /v1/banks?countryCode=GB&paymentRails=FASTER_PAYMENTS.
  3. Create attempt via POST /v1/payments/{paymentId}/attempts.
  4. If response contains requiredAction.url, redirect the payer there.
  5. (Card only, if required) finalize with POST /v1/payments/{paymentId}/attempts/{attemptId}/finalize.
  6. Confirm final state using payment webhooks and/or GET /v1/payments/{paymentId}.

Attempt Rules

  • Exactly one of bank or card must be provided.
  • bank.bankId is mandatory for bank attempts.
  • browserData is mandatory for card attempts.
  • Bank attempts require payment returnUrl to be present on the payment.
  • Use idempotencyKey to deduplicate client retries. On key clash, the existing attempt is returned.

Bank Attempt Example

POST /v1/payments/{paymentId}/attempts
{
  "idempotencyKey": "bank-2026-02-12-001",
  "bank": {
    "bankId": "Q2r6W9h8TtK1mX4pJ0yZcA"
  }
}
{
  "id": "enc_attempt_id",
  "status": "STARTED",
  "requiredAction": {
    "type": "bank_redirect",
    "url": "https://...token-auth-url..."
  }
}

For bank attempts, requiredAction.url is the URL to send the payer to immediately.

Card Attempt Example

Compliance note: card attempts involve handling cardholder data in merchant systems. This is likely to place the merchant in PCI DSS scope. 
POST /v1/payments/{paymentId}/attempts
{
  "idempotencyKey": "card-2026-02-12-001",
  "card": {
    "number": "4242424242424242",
    "expiryMonth": "12",
    "expiryYear": "2030",
    "cvc": "123"
  },
  "billingAddress": {
    "firstName": "Jane",
    "lastName": "Doe",
    "lineOne": "10 Example Street",
    "city": "London",
    "postalCode": "SW1A 1AA",
    "country": "GB"
  },
  "browserData": {
    "browserJavaEnabled": false,
    "browserJavascriptEnabled": true,
    "browserLanguage": "en-GB",
    "browserColorDepth": 24,
    "browserScreenHeight": 1080,
    "browserScreenWidth": 1920,
    "browserTZ": "0",
    "browserUserAgent": "Mozilla/5.0",
    "browserAcceptHeader": "text/html,application/json"
  }
}

Finalize Card Attempt

POST /v1/payments/{paymentId}/attempts/{attemptId}/finalize

Finalize is for card attempts only. Bank attempts do not require finalize.

Completion and Webhooks

  • Use payment webhooks for authoritative completion events.
  • Use GET /v1/payments/{paymentId} if you need pull-based confirmation.
  • Treat redirects as UX signals, not final settlement confirmation.

Related Guides