PayWithMyBank (Trustly) transactions API

openapi: 3.1.0
info:
  title: accountData transactions API
  version: 1.0.0
servers:
- url: https://sandbox.trustly.one/api/v1
  description: Sandbox
tags:
- name: transactions
paths:
  /transactions/{transactionId}/cancel:
    post:
      operationId: post-transactions-cancel
      summary: Cancel transaction
      description: 'Cancels an existing transaction that has not yet been processed. A cancellation should be issued as soon as you know the transaction will not be completed.


        A Deferred or Instant payment transaction can only be canceled before the payment processing cut-off time. If the Cancel request returns an error, a Refund call should be executed instead.


        Additionally, this endpoint can be used to cancel a Bank Authorization when a user revokes access to their bank from your application. If the bank authorization transaction is voided, further `/capture` or `/deposit` requests using the canceled transaction will not be permitted. Any outstanding transactions with a `pending` status related to the bank authorization will remain unchanged and must be canceled individually if necessary.'
      tags:
      - transactions
      parameters:
      - name: transactionId
        in: path
        description: Authorization Transaction ID retrieved from a Trustly Deferred or Recurring transaction.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: ''
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantReference:
                  type: string
                  description: A specific merchant reference for this cancellation. For example, this could be a merchant order number or the same merchant reference value used in the original establish call.
                message:
                  type: string
                  description: An optional message describing the reason for the cancellation. (maximum of 40 characters)
                reason:
                  type: number
                  format: double
                  description: 'A specific reason code for this cancellation. '
                signature:
                  type: string
                  description: 'A specific signature for this cancellation. '
  /transactions/{transactionId}/capture:
    post:
      operationId: post-transactions-transactionId-capture
      summary: Capture transaction
      description: "Capture collects money amounts (minimum of 0.99) from a customer bank account of a previously authorized transaction.\n\nThis operation creates a new transaction called a Capture transaction. It is linked to the payment you are partially or fully capturing.\n\nYou can issue multiple capture requests against a single Authorization. However, the sum of these captures must be less than or equal to what is allowed by the authorized payment.\n\nEnsure you also implement an Event Notification Handler to get transaction status updates. Although the splitToken field is optional at the API level, if you are using 'guaranteed' payments, omitting this field will result in a Fail event. When providing a splitToken, be sure the string is URL encoded.\n\n> **Note for Money Transfer** \n> If your application is configured for \"Money Transfer\" many properties in the `beneficiary` and `beneficiaryAccount` objects will be required. \n> See [Send money](/integrate/send-money) for more details."
      tags:
      - transactions
      parameters:
      - name: transactionId
        in: path
        description: Authorization Transaction ID retrieved from a Trustly Deferred or Recurring transaction, or Preauthorization Transaction ID retrieved from a Trustly Preauthorize API.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: ''
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantReference:
                  type: string
                  description: A specific merchant reference for this capture such as an order number. If your account is configured for idempotency, this value must be unique to prevent duplicate transactions.
                amount:
                  type: string
                  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)
                splitToken:
                  type: string
                  description: Encrypted token received from the Authorize event. Note, token may include url escape characters which must be encoded or the request will result in an error.
                beneficiaryAccount.iban:
                  type: string
                  description: International Bank Account Number (IBAN)
                beneficiaryAccount.accountNumber:
                  type: string
                  description: Account Number
                beneficiaryAccount.paymentProvider.name:
                  type: string
                  description: Name of financial institution. 35 characters maximum.
                beneficiaryAccount.paymentProvider.swift:
                  type: string
                  description: International SWIFT code of the payment provider
                beneficiaryAccount.paymentProvider.routingNumber:
                  type: string
                  description: Routing Number (9 digits)"
                beneficiaryAccount.paymentProvider.country:
                  type: string
                  description: 2-letter ISO country code of the beneficiary financial institution
                beneficiary.name:
                  type: string
                  description: Customer full legal name
                beneficiary.email:
                  type: string
                  description: Customer email address
                beneficiary.dateOfBirth:
                  type: string
                  description: Customer date of birth
                beneficiary.taxId:
                  type: string
                  description: Customer tax ID (e.g. SSN [US], SIN [CA])
                beneficiary.address.address1:
                  type: string
                  description: Street address of the beneficiary financial institution
                beneficiary.address.address2:
                  type: string
                  description: Street address line 2 of the beneficiary financial institution (if applicable)
                beneficiary.address.city:
                  type: string
                  description: City or Locality of the beneficiary financial institution
                beneficiary.address.state:
                  type: string
                  description: State or Province of the beneficiary financial institution
                beneficiary.address.zip:
                  type: string
                  description: ZIP or postal code of the beneficiary financial institution
                beneficiary.address.country:
                  type: string
                  description: 2 character ISO Country code of the beneficiary financial institution
                metadata.remittance.withdrawalMethod:
                  $ref: '#/components/schemas/TransactionsTransactionIdCapturePostRequestBodyContentApplicationXWwwFormUrlencodedSchemaMetadataRemittanceWithdrawalMethod'
                  description: The method by which the recipient will receive the funds.
                interactionId:
                  type: string
                  description: Optional interaction ID parameter for Preauthorization and Capture APIs, inclusion of which signifies consumer interaction tied to data obtained from getTrustlyInteraction function. If not specified, Trustly assumes the consumer is present in session. Set to "consumerNotPresent" to signify that the transaction is merchant-initiated and the consumer is not present.
              required:
              - merchantReference
              - amount
              - splitToken
  /transactions/{transactionId}/deposit:
    post:
      operationId: post-transactions-deposit
      summary: Deposit transaction
      description: 'Deposit sends money amounts (minimum of 0.99) to a customer bank account of a previously authorized Disbursement or Deferred transaction.


        This operation creates a new transaction called a Deposit transaction. It is linked to the disbursement payment.


        You can create multiple Deposit transactions against a single Disbursement or Deferred Authorization so long as the amount doesn''t exceed the total of the Authorization.


        Ensure you also implement an Event Notification Handler to get transaction status updates.'
      tags:
      - transactions
      parameters:
      - name: transactionId
        in: path
        description: Authorization Transaction ID retrieved from a Trustly Deferred or Disbursement Authorization.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: ''
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantReference:
                  type: string
                  description: A specific merchant reference for this deposit. For example, this could be a merchant order number or the same merchant reference value used in the original establish call.
                amount:
                  type: number
                  format: double
                  description: The amount to be sent. (maximum of 10 characters with support for 2 decimal places)
                instantPayoutRequest:
                  type: boolean
                  description: Whether instant payout for the deposit will be attempted.
                externalTier:
                  type: string
                  description: The merchant's tier associated with the customer (e.g. vip).
              required:
              - merchantReference
  /establish:
    post:
      operationId: post-establish
      summary: Establish a new transaction for authorization
      description: "This endpoint creates a new unauthorized transaction and returns a URL to be provided for a user to authorize the transaction. After the user has authorized the transaction with a bank, the transaction can be used with other Trustly APIs to retrieve account data or process payments.\n\nFor more details and descriptions of the fields supported by this endpoint see [Establish Data object](doc:features/establish-data-object).\n\n> **Note for Money Transfer** \n> If your application is configured for \"Money Transfer\" many properties in the `customer`, `beneficiary` and `beneficiaryAccount` objects will be required. \n> See [Send money](/integrate/send-money) for more details."
      tags:
      - transactions
      parameters:
      - name: createTransaction
        in: query
        description: If true, Trustly will return a transactionId that can be used with other API's. Either createTransaction or notify is required.
        required: false
        schema:
          type: boolean
      - name: notify
        in: query
        description: If true, Trustly will notify the User via SMS or Email with a URL that can be used to complete the transaction. Either createTransaction or notify is required.
        required: false
        schema:
          type: boolean
      - name: channel
        in: query
        description: 'Comma separated list of notification channels. Currently only sms and email are supported. Example: sms,email will send a notification via SMS and email to the User. Required if notify is true.'
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: ''
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EstablishData'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantId:
                  type: string
                  description: Your Trustly-provided Merchant ID.
                accessId:
                  type: string
                  description: Your Trustly-provided client application access ID.
                amount:
                  type: string
                  description: The amount of the transaction. This represents the maximum amount of the transactions that can be processed with the Authorization. If the amount is 0.00, there will be no upper bound on the transaction. (10 characters with support for 2 decimal places)
                currency:
                  $ref: '#/components/schemas/EstablishPostRequestBodyContentApplicationJsonSchemaCurrency'
                  description: 3-letter ISO Currency Code.
                description:
                  type: string
                  description: A summary description of the order. Do not pass Consumer PII (name, email address, etc) in this field.
                returnUrl:
                  type: string
                  description: The URL where the user should be redirected to when the user successfully authorizes the transaction (must be a valid URL or function).
                cancelUrl:
                  type: string
                  description: The URL where the user should be redirected to if the user exits or the transaction is canceled (must be a valid URL or function).
                notificationUrl:
                  type: string
                  description: Notification URL to use for notifications associated with this transaction. This overrides the notification URL configured by Trustly during onboarding.
                paymentType:
                  $ref: '#/components/schemas/EstablishPostRequestBodyContentApplicationJsonSchemaPaymentType'
                  description: "Specifies the type of transaction to create. Possible values are Instant, Deferred, Disbursement, Recurring, Verification, and Retrieval. Default is Retrieval.\n\n **Note:** If your application is configured for \"Money Transfer\" and utilizes the \"Instant\" `paymentType` several properties under `customer`, `beneficiary` and `beneficiaryAccount` will be required. \n> See [Send money](/integrate/send-money) for more details."
                requestSignature:
                  type: string
                  description: Request Signature used to secure the request.
                displayAmount:
                  type: number
                  format: double
                  description: Optionally displays the provided transaction amount to the user throughout the Lightbox experience.
                merchantReference:
                  type: string
                  description: A unique identifier that you create to represent the Transaction in the Trustly system.
                customer:
                  $ref: '#/components/schemas/Customer'
                account:
                  $ref: '#/components/schemas/EstablishPostRequestBodyContentApplicationJsonSchemaAccount'
                  description: Account information. Required if paymentType is Verification and a transactionId is not included.
                beneficiary:
                  $ref: '#/components/schemas/EstablishPostRequestBodyContentApplicationJsonSchemaBeneficiary'
                beneficiaryAccount:
                  $ref: '#/components/schemas/EstablishPostRequestBodyContentApplicationJsonSchemaBeneficiaryAccount'
                  description: 'Financial institution account associated with the ultimate beneficiary of a transaction. Required when using `paymentType: Instant` for [Money Transfer](/integrate/send-money)'
                kycType:
                  type: string
                  description: Specifies the KYC (Know Your Customer) type. This field is optional and can only be used by merchants configured for [Trustly ID](/integrate/retrieve-data/trustly-id).
                metadata:
                  $ref: '#/components/schemas/EstablishPostRequestBodyContentApplicationJsonSchemaMetadata'
                  description: Provide additional use case-specific properties in this object.
              required:
              - merchantId
              - accessId
              - currency
              - returnUrl
              - cancelUrl
              - requestSignature
              - merchantReference
  /transactions:
    get:
      operationId: list-transactions
      summary: Get transactions
      description: Returns a list of transactions. It can be paged and filtered by appending arguments to the query string of the request.
      tags:
      - transactions
      parameters:
      - name: transactionType
        in: query
        description: Returns transactions of this Transaction Type. It is possible to filter by multiple values by repeating this argument.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: transactionStatus
        in: query
        description: Returns transactions that currently have this Transaction Status. It is possible to filter by multiple values by repeating this argument.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: originalTransactionId
        in: query
        description: Returns transactions that belongs to this original transaction identifier.
        required: false
        schema:
          type: string
      - name: payment.paymentId
        in: query
        description: Returns transactions of the payment specified by this payment ID.
        required: false
        schema:
          type: string
      - name: payment.paymentType
        in: query
        description: Returns transactions of the 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: payment.merchantReference
        in: query
        description: Returns transactions of the payments associated with this merchant reference.
        required: false
        schema:
          type: string
      - name: payment.verification.status
        in: query
        description: Returns transactions of the payments at this payment Verification Status.
        required: false
        schema:
          type: number
          format: double
      - name: paymentProviderTransaction.ppTrxStatusCode
        in: query
        description: Returns transactions of the payment specified by this payment provider status code.
        required: false
        schema:
          type: string
      - name: orderBy
        in: query
        description: Returns transactions by this order field
        required: false
        schema:
          type: string
      - name: sortOrder
        in: query
        description: Returns transactions by this sort order
        required: false
        schema:
          type: string
      - name: startIndex
        in: query
        description: Returns transactions from that offset
        required: false
        schema:
          type: string
      - name: count
        in: query
        description: Returns the maximum number of transactions specified by this field
        required: false
        schema:
          type: string
      - name: amount.min
        in: query
        description: Returns transactions for that minimum amount.
        required: false
        schema:
          type: string
      - name: amount.max
        in: query
        description: Returns transactions for that maximum amount.
        required: false
        schema:
          type: string
      - name: paid.min
        in: query
        description: Returns transactions for that minimum paid.
        required: false
        schema:
          type: string
      - name: paid.max
        in: query
        description: Returns transactions for that maximum paid.
        required: false
        schema:
          type: string
      - name: refunded.min
        in: query
        description: Returns transactions with this minimum refund amount.
        required: false
        schema:
          type: string
      - name: refunded.max
        in: query
        description: Returns transactions with this maximum refund amount.
        required: false
        schema:
          type: string
      - name: createdAt.start
        in: query
        description: Returns transactions after this creation date
        required: false
        schema:
          type: string
      - name: createdAt.end
        in: query
        description: Returns transactions before this creation date
        required: false
        schema:
          type: string
      - name: updatedAt.start
        in: query
        description: Returns transactions after this update date
        required: false
        schema:
          type: string
      - name: updatedAt.end
        in: query
        description: Returns transactions before this update date
        required: false
        schema:
          type: string
      - name: processedAt.start
        in: query
        description: Returns transactions after this processing date
        required: false
        schema:
          type: string
      - name: processedAt.end
        in: query
        description: Returns transactions before this processing date
        required: false
        schema:
          type: string
      - name: completedAt.start
        in: query
        description: Returns transactions after this completion date
        required: false
        schema:
          type: string
      - name: completedAt.end
        in: query
        description: Returns transactions before this completion date
        required: false
        schema:
          type: string
      - name: paymentProviderTransaction.paymentProviderTransactionId
        in: query
        description: Returns transactions of the payment specified by this payment provider id.
        required: false
        schema:
          type: string
      - name: payment.description
        in: query
        description: Returns transactions with this payment description
        required: false
        schema:
          type: string
      - name: payment.fingerprint
        in: query
        description: Returns transactions with this payment fingerprint
        required: false
        schema:
          type: string
      - name: payment.merchant.merchantId
        in: query
        description: Returns transactions of the payment specified by this merchant identification.
        required: false
        schema:
          type: string
      - name: payment.paymentProvider.paymentProviderId
        in: query
        description: Returns transactions by this payment provider identification.
        required: false
        schema:
          type: string
      - name: payment.authorization.status
        in: query
        description: Returns transactions of the payments at this payment Authorization Status.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: payment.fiAccount.providerId
        in: query
        description: Returns transactions of the payment specified by this payment provider identification.
        required: false
        schema:
          type: string
      - name: payment.fiAccount.accountNumber
        in: query
        description: Returns transactions of the payment specified by account number.
        required: false
        schema:
          type: string
      - name: payment.fiAccount.routingNumber
        in: query
        description: Returns transactions of the payment specified by routing number.
        required: false
        schema:
          type: string
      - name: payment.fiAccount.verified
        in: query
        description: Returns transactions of the payment if account is verified.
        required: false
        schema:
          type: boolean
      - name: ipAddr
        in: query
        description: Returns transactions with this IP address
        required: false
        schema:
          type: string
      - name: routingNumber
        in: query
        description: Returns transactions with this routing number
        required: false
        schema:
          type: string
      - name: accountNumber
        in: query
        description: Returns transactions with this account number
        required: false
        schema:
          type: string
      - name: customerName
        in: query
        description: Returns transactions with this customer name
        required: false
        schema:
          type: string
      - name: payment.customer.name
        in: query
        description: Returns transactions of the payment specified by customer name.
        required: false
        schema:
          type: string
      - name: payment.customer.externalId
        in: query
        description: Returns transactions of the payment specified by customer external identification.
        required: false
        schema:
          type: string
      - name: ignoreUserPortalTransactions
        in: query
        description: Returns transactions bypassing the portal user.
        required: false
        schema:
          type: boolean
      - name: payment.paymentProvider.framework
        in: query
        description: Returns transactions of the payment provider specified by framework.
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: ''
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transactions_list-transactions_Response_200'
  /transactions/{transactionId}/capture/preAuth:
    post:
      operationId: post-transactions-transactionId-capture-preauth
      summary: Preauthorize transaction
      description: The Preauthorize API allows the merchant to pre-authorize one or more captures up to the total pre-authorized amount on a pre-authorized period interval in hours. Captures after the pre-authorized period interval are treated as normal Captures (will need to pass the full balance and risk analysis to be guaranteed).
      tags:
      - transactions
      parameters:
      - name: transactionId
        in: path
        description: Authorization Transaction ID retrieved from a Trustly Deferred or Recurring transaction.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: ''
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantReference:
                  type: string
                  description: A specific merchant reference for this preauthorization. For example, this could be a merchant order number or the same merchant reference value used in the original establish call.
                period:
                  type: integer
                  default: 0
                  description: Number of hours the preauthorization will be valid for.
                amount:
                  type: string
                  description: The amount to be authorized. (maximum of 10 characters with support for 2 decimal places). Required if the bank authorization was created with an amount of 0.00. If not specified, then the full amount of the bank authorization will be used.
                splitToken:
                  type: string
                  description: Token received on the Authorize event.
                externalTier:
                  type: string
                  description: The merchant's tier associated with the customer (e.g. vip).
                metadata.remittance.withdrawalMethod:
                  $ref: '#/components/schemas/TransactionsTransactionIdCapturePreAuthPostRequestBodyContentApplicationXWwwFormUrlencodedSchemaMetadataRemittanceWithdrawalMethod'
                  description: The method by which the recipient will receive the funds.
                interactionId:
                  type: string
                  description: Optional interaction ID parameter for Preauthorization and Capture APIs, inclusion of which signifies consumer interaction tied to data obtained from getTrustlyInteraction function. If not specified, Trustly assumes the consumer is present in session. Set to "consumerNotPresent" to signify that the transaction is merchant-initiated and the consumer is not present.
              required:
              - merchantReference
              - period
              - amount
  /transactions/{transactionId}/reclaim:
    post:
      operationId: post-transactions-transactionId-reclaim
      summary: Reclaim transaction
      description: 'Reclaims a previously completed Deposit transaction (minimum of 0.99). You can optionally reclaim partially. You can do so as many times as you wish until the entire deposited amount has been reclaimed.


        A Deposit transaction can only be reclaimed after the transaction has been processed and completed.


        Ensure you also implement an [event notification](/integrate/core-concepts/webhooks-and-events) handler to get transaction status updates.'
      tags:
      - transactions
      parameters:
      - name: transactionId
        in: path
        description: Deposit Transaction ID retrieved from a Trustly Deposit transaction.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: ''
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantReference:
                  type: string
                  description: A specific merchant reference for this reclaim. For example, this could be a merchant order number or the same merchant reference value used in the original establish call.
                amount:
                  type: string
                  description: The amount to be reclaimed which can be less or equal than the current balance of the deposit transaction being reclaimed. If the value is omitted the remaining balance is reclaimed. (maximum of 10 characters with support for 2 decimal places)
              required:
              - amount
  /transactions/{transactionId}/refresh:
    post:
      operationId: post-transactions-refresh
      summary: Refresh a transaction
      description: Refresh allows for data associated with a transaction to be updated to the most recent available.
      tags:
      - transactions
      parameters:
      - name: transactionId
        in: path
        description: Authorization Tr

# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paywithmybank/refs/heads/main/openapi/paywithmybank-transactions-api-openapi.yml