Trustly North America API

openapi: 3.1.0
info:
  title: Trustly North America API
  version: 1.0.0
  description: Trustly Pay by Bank REST API for the United States and Canada (Trustly Inc., formerly PayWithMyBank). Establish
    and authorize bank transactions, capture and deposit funds, send payouts, refund and cancel, tokenize and verify bank
    accounts, retrieve account data and Trustly ID identity details, manage customers and disputes, and receive event notifications
    (webhooks). Sandbox and production share one contract; only the host differs.
  contact:
    name: Trustly North America developer experience
    url: https://amer.developers.trustly.com/help
    email: amer.developer.experience@trustly.com
  termsOfService: https://www.trustly.com/about-us/terms-and-conditions
  x-api-evangelist-provenance:
    source: https://amer.developers.trustly.com/openapi.json
    fetched: '2026-09-18'
    note: Verbatim provider spec from the Fern-hosted docs (also linked from /.well-known/api-catalog as /openapi/api.yaml).
      info.title/description/contact/termsOfService added by API Evangelist from the provider docs; paths, schemas and webhooks
      untouched. Production server added from the Environment URLs table at https://amer.developers.trustly.com/integrate/api-fundamentals/testing.
paths:
  /transactions/{transactionId}/accountSummary:
    get:
      operationId: accountData_get-transaction-account-summary
      summary: Get account activity summary
      description: 'Returns summarized and aggregated information about an account such as deposits, withdrawals and balances
        for various time periods.


        **Warning**<br />Please wait to receive the [DataReady](/api-reference/api/event-notifications/data-ready) event before
        calling this endpoint. Requests to this endpoint made prior to receiving the DataReady event can result in partial
        data being returned.'
      tags:
      - accountData
      parameters:
      - name: transactionId
        in: path
        description: Transaction ID retrieved from a Trustly Authorization transaction.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account_Data_get-transaction-account-summary_Response_200'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-transaction-account-summaryRequestBadRequestError'
      security:
      - HTTPBasic: []
  /transactions/{transactionId}/payment/paymentProvider/account/balance:
    get:
      operationId: accountData_get-transactions-account-balance
      summary: Get account balance
      description: 'Retrieves the details of an Account that was authorized for a Transaction. You need only supply the unique
        transactionId that was returned as part of a bank authorization.


        This is a restricted API and must be approved for usage by the Trustly Compliance team.


        **Note**<br />This endpoint retrieves data for the account selected during the Lightbox flow, which is already available
        once authorization completes. Waiting for the [DataReady](/api-reference/api/event-notifications/data-ready) event
        is not required to call this endpoint — DataReady signals completion of data retrieval for non-selected accounts and
        full account activity, not the selected account''s balance.


        **Note for International Financial Institutions**<br />In some geographies the `Account` object in the response for
        this API may contain additional properties. For example, the `taxId` returned for accounts from Brazilian institutions.'
      tags:
      - accountData
      parameters:
      - name: transactionId
        in: path
        description: Transaction ID retrieved from a Trustly Authorization transaction.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account_Data_get-transactions-account-balance_Response_200'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-transactions-account-balanceRequestBadRequestError'
      security:
      - HTTPBasic: []
  /transactions/{transactionId}/payment/paymentProvider/user:
    get:
      operationId: accountData_get-user
      summary: Get account users
      description: 'This endpoint retrieves users'' information from an Authorized Bank transaction.


        **Warning**<br />Please wait to receive the [DataReady](/api-reference/api/event-notifications/data-ready) event before
        calling this endpoint. Requests to this endpoint made prior to receiving the DataReady event can result in partial
        data being returned.'
      tags:
      - accountData
      parameters:
      - name: transactionId
        in: path
        description: Transaction ID retrieved from a Trustly Authorization transaction.
        required: true
        schema:
          type: string
      - name: expand
        in: query
        description: A field in the API response to be expanded in order for more details to be provided (e.g. customer.segmentedName).
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/TransactionsTransactionIdPaymentPaymentProviderUserGetParametersExpandSchemaItems'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FIUser'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-userRequestBadRequestError'
      security:
      - HTTPBasic: []
  /transactions/{transactionId}/payment/paymentProvider/accounts:
    get:
      operationId: accountData_list-selected-accounts
      summary: List all accounts
      description: 'Returns a list of all user-selected accounts associated with a given authorization transaction.


        **Warning**<br />Please wait to receive the [DataReady](/api-reference/api/event-notifications/data-ready) event before
        calling this endpoint. Requests to this endpoint made prior to receiving the DataReady event can result in partial
        data being returned.'
      tags:
      - accountData
      parameters:
      - name: transactionId
        in: path
        description: Transaction ID retrieved from a Trustly Authorization transaction.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account_Data_list-selected-accounts_Response_200'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List-selected-accountsRequestBadRequestError'
      security:
      - HTTPBasic: []
  /feedback:
    post:
      operationId: accounts_post-account-feedback
      summary: Post account feedback
      description: "Utilize this endpoint to record feedback regarding the result of an ACH payment using the account information\
        \ verified by Trustly during a Verification Transaction. This feedback data helps optimize account verification scores\
        \ over time. It is **required** when using Trustly Connect. \n\n> **Note for Trustly Pay** \n> For apps using Trustly\
        \ Pay, feedback should be provided on individual transactions rather than on the account. See [`/transactions/{id}/feedback`](ref:post-transaction-feedback)\
        \ for transaction-specific feedback details."
      tags:
      - accounts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Accounts_post-account-feedback_Response_200'
        '400':
          description: Invalid parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseException'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseException'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantId:
                  type: number
                  format: double
                  description: A unique Trustly merchant identifier.
                account:
                  $ref: '#/components/schemas/FeedbackPostRequestBodyContentApplicationJsonSchemaAccount'
                  description: The token is required only when account number and routing number are not sent and vice-versa.
                feedback:
                  $ref: '#/components/schemas/Feedback'
              required:
              - merchantId
              - account
              - feedback
      security:
      - HTTPBasic: []
  /accounts/tokenize:
    post:
      operationId: accounts_post-accounts-tokenize?-verifyAccount
      summary: Tokenize an account
      description: Convert legacy ACH ABA routing and account numbers or an International Bank Account Number (IBAN) into
        a verified token to meet NACHA requirements.
      tags:
      - accounts
      parameters:
      - name: verifyAccount
        in: query
        description: If true, Trustly will verify the provided account data. Default value is false.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Accounts_post-accounts-tokenize_-verifyAccount_Response_200'
        '400':
          description: One of the request parameters is invalid (sending an invalid amount format string for example).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post-accounts-tokenize_-verifyAccountRequestBadRequestError'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantId:
                  type: string
                  minLength: 1
                account:
                  $ref: '#/components/schemas/AccountsTokenizePostRequestBodyContentApplicationJsonSchemaAccount'
              required:
              - merchantId
              - account
      security:
      - HTTPBasic: []
  /accounts/verify:
    post:
      operationId: accounts_get-accounts-verify
      summary: Verify an account
      description: Allows for verification of most global accounts by passing in an account object containing either bank
        routing and account numbers or an IBAN.
      tags:
      - accounts
      parameters:
      - name: expand
        in: query
        description: A field in the API response to be expanded in order for more details to be provided (e.g. account.paymentProvider).
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialInstitutionAccount'
        '400':
          description: One of the request parameters is invalid (sending an invalid amount format string for example).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-accounts-verifyRequestBadRequestError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantId:
                  type: number
                  format: double
                  description: A unique Trustly merchant identifier.
                account:
                  $ref: '#/components/schemas/AccountsVerifyPostRequestBodyContentApplicationJsonSchemaAccount'
              required:
              - merchantId
              - account
      security:
      - HTTPBasic: []
  /countries:
    get:
      operationId: countries_get-countries
      summary: List countries
      description: Returns a list of all available products by country.
      tags:
      - countries
      parameters:
      - name: country
        in: query
        description: 2-character ISO code of the country for the bank account that was selected. Currently only the US, CA,
          UK, DE, and AU are supported.
        required: false
        schema:
          $ref: '#/components/schemas/CountriesGetParametersCountry'
      - name: paymentType
        in: query
        description: Returns the countries that support this Payment Type.
        required: false
        schema:
          type: string
      - name: paymentProvider.subType
        in: query
        description: Returns the countries that support this Payment Provider SubType
        required: false
        schema:
          type: string
      - name: enabled
        in: query
        description: If true, returns all countries that are currently supported. Default value is true.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Countries_get-countries_Response_200'
        '400':
          description: One of the request parameters is invalid (sending an invalid amount format string for example).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-countriesRequestBadRequestError'
      security:
      - HTTPBasic: []
  /customers:
    post:
      operationId: customers_post-customers
      summary: Create or Update a Customer
      description: 'Creates a new customer record in the merchant account. In cases when the customer was not created at the
        time an Authorization was established, use this endpoint to register customer details, such as name, email, and optional
        metadata, to support your integration.


        If an existing `customerId` or `externalId` is provided, the specified customer will be updated with any new or updated
        properties. To remove properties of an existing customer, set the property to `null`. Before using this endpoint,
        it may be helpful to call [Get Customer by ID](ref:get-customers-customerid) to obtain the relevant customer object.'
      tags:
      - customers
      parameters:
      - name: externalId
        in: query
        description: The externalId that was passed when the Customer record was created.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customers_post-customers_Response_200'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Customer'
      security:
      - HTTPBasic: []
    get:
      operationId: customers_get-customers
      summary: Get Customers
      description: "Retrieves a list of customers associated with the merchant account. Use this endpoint to view customer\
        \ details relevant to your integration. \n\n Results can be filtered by either the `externalId` or `customerId` properties\
        \ in order to retrieve the details of a single customer using the unique `externalId` that was provided during customer\
        \ creation. Other filtering and paging capabilities are not supported at this time."
      tags:
      - customers
      parameters:
      - name: externalId
        in: query
        description: The externalId that was passed when the Customer record was created.
        required: false
        schema:
          type: string
      - name: customerId
        in: query
        description: The identifier of the Customer to be retrieved.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customers_get-customers_Response_200'
      security:
      - HTTPBasic: []
  /customers/{customerId}:
    get:
      operationId: customers_get-customers-customerId
      summary: Get Customer by ID
      description: Retrieves the details of a Customer using the unique `customerId` that was returned upon customer creation.
      tags:
      - customers
      parameters:
      - name: customerId
        in: path
        description: The identifier of the Customer to be retrieved.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customers_get-customers-customerId_Response_200'
      security:
      - HTTPBasic: []
    post:
      operationId: customers_post-customers-customerId
      summary: Update Customer by ID
      description: Updates the specified Customer by setting the values of the parameters on the customer object passed. Before
        calling this endpoint, it may be beneficial to call [Get Customer by ID](/api-reference/api/customers/get-customers-customer-id)
        to obtain a Customer Object. Change the desired fields in the Customer object and then modify the object before calling
        the update endpoint with the modified object.
      tags:
      - customers
      parameters:
      - name: customerId
        in: path
        description: The identifier of the Customer to be retrieved.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customers_post-customers-customerId_Response_200'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Customer'
      security:
      - HTTPBasic: []
  /collections/recovery/dispute:
    post:
      operationId: disputeManagement_post-dispute-recovery
      summary: Post a dispute
      description: This endpoint allows you to recover a retail dispute. The response includes key transaction information,
        such as the transaction status, as well as amounts, and account details for payment or authorization transactions.
      tags:
      - disputeManagement
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '400':
          description: Invalid parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseException'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                transactionId:
                  type: string
                  description: Transaction ID retrieved from a Trustly Dispute Webhook.
                amount:
                  type: string
                  maxLength: 10
                  description: The amount to be captured. If the value is omitted, the maximum allowed amount is captured.
                    (maximum of 10 characters with support for 2 decimal places).
              required:
              - transactionId
              - amount
      security:
      - HTTPBasic: []
  /transactions/{transactionId}/user:
    get:
      operationId: identity_get-trustly-id-user-data
      summary: Get user
      description: Retrieve the User object associated with the Trustly ID authorization transaction.
      tags:
      - identity
      parameters:
      - name: transactionId
        in: path
        description: Transaction ID retrieved from a Trustly Authorization transaction.
        required: true
        schema:
          type: string
      - name: expand
        in: query
        description: "A field in the API response to be expanded in order for more details to be provided.\nSupported values:\n\
          \ * `segmentedName`: returns a segmented version of the name field returned in the response."
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/TransactionsTransactionIdUserGetParametersExpandSchemaItems'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-trustly-id-user-dataRequestBadRequestError'
      security:
      - HTTPBasic: []
  /transactions/{transactionId}/user/detail:
    get:
      operationId: identity_get-trustly-id-user-details
      summary: Get user verification details
      description: "Retrieve the verification results and details of a Trustly ID-enabled authorization transaction. The details\
        \ returned by this endpoint are segmented into two lists: verifications and attributes. \n\nThe verification objects\
        \ contain the `name` and `result` of the verification as well as reason codes and reason descriptions corresponding\
        \ to the results. If a verification includes a sanction screening and a match was returned, the results of the screening\
        \ will also be included. If no `screeningResults` property is returned in the verification object, no match was returned.\n\
        >**Note:** Verifications are configured per application, check with your Trustly services team member for definitions\
        \ of your configured verifications.\n\nThe attribute objects contain metadata which describe how the property was\
        \ verified and a list of `verification` objects which apply to the attribute."
      tags:
      - identity
      parameters:
      - name: transactionId
        in: path
        description: Transaction ID retrieved from a Trustly Authorization transaction.
        required: true
        schema:
          type: string
      - name: expand
        in: query
        description: "A field in the API response to be expanded in order for more details to be provided.\nSupported values:\n\
          \ * `verification`: returns human-readable reason rules and descriptions."
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/TransactionsTransactionIdUserDetailGetParametersExpandSchemaItems'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserVerificationDetail'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-trustly-id-user-detailsRequestBadRequestError'
      security:
      - HTTPBasic: []
  /transactions/{transactionId}/feedback:
    post:
      operationId: identity_post-transaction-feedback
      summary: Update user status
      description: "This endpoint updates the status of a user by posting feedback data to Trustly for an authorized Identity\
        \ transaction. This communicates to Trustly that the user associated with the transaction has been successfully registered\
        \ in the merchant system, or that the user record has been voided and therefore will not be eligible for future payment\
        \ transactions. \n\nTo confirm a user was registered, set properties `status` to `4`, `subStatus` to `559` and `description`\
        \ to `Registered`. To void a user who did not complete registration after completing the Trustly ID flow, set `status`\
        \ to `13`, `subStatus` to `558` and `description` to `Known bad user`. \n\nfor more information about Trustly ID,\
        \ see [Verify identity with Trustly ID](/integrate/retrieve-data/trustly-id)."
      tags:
      - identity
      parameters:
      - name: transactionId
        in: path
        description: Transaction ID retrieved from a Trustly Authorization transaction.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          description: Access not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post-transaction-feedbackRequestUnauthorizedError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: integer
                  default: 4
                subStatus:
                  type: integer
                  default: 559
                description:
                  type: string
                  default: Registered
      security:
      - HTTPBasic: []
  /customers/lookup:
    get:
      operationId: networkCheckApi_get-customer-lookup
      summary: Look up whether a user is known to Trustly
      description: 'Checks whether a user has previously used Trustly, based on one or more provided identifiers (email or
        phone).


        Merchants can use this endpoint without having to launch Trustly widget/lightbox. One such use case could be to use
        this endpoint early in the payment funnel — before the user reaches the payment selection screen — to determine whether
        to surface Trustly as the top payment option. A `true` response indicates the user is already familiar with Pay by
        Bank and is more likely to complete a Trustly-powered transaction.


        **How it works:** The lookup queries Trustly''s user database across all stored identifiers. If any provided identifier
        matches a known Trustly user, `isInTrustlyNetwork` is returned as `true`.


        **Authentication:** Requests must be authenticated with HTTP Basic Auth using your `accessId` as the username and
        `accessKey` as the password.'
      tags:
      - networkCheckApi
      parameters:
      - name: email
        in: query
        description: User's email address.
        required: true
        schema:
          type: string
          format: email
      - name: phone
        in: query
        description: User's phone number in ITU E.164 format.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Lookup result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerLookupResponse'
        '400':
          description: Bad Request — missing mandatory fields or invalid email
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerLookupResponse'
        '401':
          description: Access not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-customer-lookupRequestUnauthorizedError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                description: Any type
      security:
      - HTTPBasic: []
  /paymentProviders:
    get:
      operationId: paymentProviders_get-paymentProviders
      summary: List payment providers
      description: Returns a list of payment providers, filtered by country. It can be paged and filtered by appending arguments
        to the query string of the request.
      tags:
      - paymentProviders
      parameters:
      - name: countries
        in: query
        description: 2 character ISO Country code. There can be multiple instances of this query parameter to represent a
          list of countries.
        required: false
        schema:
          type: string
      - name: paymentType
        in: query
        description: Filters out payment providers not enabled for the specified payment type. Possible values are Instant,
          Deferred, Disbursement, Recurring, Verification, and Retrieval.
        required: false
        schema:
          type: string
      - name: startIndex
        in: query
        description: Returns payment providers from that offset.
        required: false
        schema:
          type: string
      - name: count
        in: query
        description: Returns the maximum number of payment providers specified by this field.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment_Providers_get-paymentProviders_Response_200'
      security:
      - HTTPBasic: []
  /payments:
    get:
      operationId: payments_list-payments
      summary: List payments
      description: Returns a list of transactions. It can be paged and filtered by appending arguments to the query string
        of the request.
      tags:
      - payments
      parameters:
      - name: paymentType
        in: query
        description: Returns payments of this Payment Type. It is possible to filter by multiple values by repeating this
          argument.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: merchantReference
        in: query
        description: Returns transactions of the payments associated with this merchant reference.
        required: false
        schema:
          type: string
      - name: authorization.status
        in: query
        description: Returns transactions of the payments at this payment Authorization Status.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: verification.status
        in: query
        description: Returns transactions of the payments at this payment Verification Status.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: paymentId
        in: query
        description: Returns payments of this identification.
        required: false
        schema:
          type: string
      - name: merchant.merchantId
        in: query
        description: Returns payments by this merchant identification.
        required: false
        schema:
          type: string
      - name: description
        in: query
        description: Returns payments by description.
        required: false
        schema:
          type: string
      - name: paymentProvider.paymentProviderId
        in: query
        description: Returns payments by this payment provider identification.
        required: false
        schema:
          type: string
      - name: customer.customerId
        in: query
        description: Returns payments by this customer identification.
        required: false
        schema:
          type: string
      - name: fingerprint
        in: query
        description: Returns payments by this fingerprint.
        required: false
        schema:
          type: string
      - name: createdAt.start
        in: query
        description: Returns payments after this creation date
        required: false
       

# --- truncated at 32 KB (199 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/trustly/refs/heads/main/openapi/trustly-north-america-openapi.yml