---
title: "Establish a new transaction for authorization"
method: POST
path: "/establish"
tags: ["transactions"]
---

# Establish a new transaction for authorization

`POST /establish`

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.

For more details and descriptions of the fields supported by this endpoint see [Establish Data object](doc:features/establish-data-object).

> **Note for Money Transfer** 
> If your application is configured for "Money Transfer" many properties in the `customer`, `beneficiary` and `beneficiaryAccount` objects will be required. 
> See [Send money](/integrate/send-money) for more details.

## Query parameters

- `createTransaction` boolean
- `notify` boolean
- `channel` string

## Headers

- `Authorization` string, required

## Request body

- object
  - `merchantId` string, required — Your Trustly-provided Merchant ID.
  - `accessId` string, required — Your Trustly-provided client application access ID.
  - `amount` string — 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` 'USD' | 'CAD', required — 3-letter ISO Currency Code.
  - `description` string — A summary description of the order. Do not pass Consumer PII (name, email address, etc) in this field.
  - `returnUrl` string, required — The URL where the user should be redirected to when the user successfully authorizes the transaction (must be a valid URL or function).
  - `cancelUrl` string, required — 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` string — Notification URL to use for notifications associated with this transaction. This overrides the notification URL configured by Trustly during onboarding.
  - `paymentType` 'Retrieval' | 'Deferred' | 'Disbursement' | 'Instant' | 'Recurring' | 'Verification' — Specifies the type of transaction to create. Possible values are Instant, Deferred, Disbursement, Recurring, Verification, and Retrieval. Default is Retrieval. **Note:** If your application is configured for "Money Transfer" and utilizes the "Instant" `paymentType` several properties under `customer`, `beneficiary` and `beneficiaryAccount` will be required. > See [Send money](/integrate/send-money) for more details.
  - `requestSignature` string, required — Request Signature used to secure the request.
  - `displayAmount` string — Optionally displays the provided transaction amount to the user throughout the Lightbox experience. **Note:** This value must be sent as a JSON string (for example, `"10.50"`), not as a numeric value.
  - `merchantReference` string, required — A unique identifier that you create to represent the Transaction in the Trustly system.
  - `customer` Customer — The Trustly customer object, containing identification details and contact information.
    - `name` string, required — Full name of the Customer
    - `taxId` string — Customer tax ID (e.g. SSN [US], SIN [CA]). *May be required depending on industry and location.*
    - `address` Address, required — Valid mailing or billing address associated with the customer
      - `address1` string — Address line 1 (e.g., street or PO Box)
      - `address2` string — Address line 2 (e.g., apartment, suite or unit number)
      - `city` string — City, district, town or village
      - `state` string — State, province or region code
      - `zip` string — ZIP or Postal Code
      - `country` string, required — 2 character [ISO Country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
    - `phone` string, required — Customer phone number.
    - `email` string, required — Customer email address.
    - `dateOfBirth` string — Customer date of birth.
    - `createdAt` integer — The record created date and time as a UNIX timestamp.
    - `updatedAt` integer — The record created date and time as a UNIX timestamp.
    - `customerId` string — A unique Trustly customer identifier.
    - `externalId` string — A unique merchant customer identifier.
    - `merchantId` string — A unique Trustly merchant identifier.
    - `enrollDate` integer — Date of the user's first transaction in your system, regardless of payment method used as a UNIX timestamp.
    - `vip` string — Range that determines how low-risk the customer represents to the merchant
    - `currency` string — Customer currency.
    - `balance` string — Customer account balance (not associated with a financial institution account).
    - `organizationNumber` string — Organization number for business accounts
    - `externalTier` string — It should describe the customer''s rank to the merchant (e.g. Gold, Diamond, 4 stars, etc.)
    - `personId` string — Unique customer identity throughout different banks.
    - `customData` CustomerCustomData — Object for sending merchant-specific custom data.
    - `driverLicense` DriverLicense
      - `number` string, required — Driver License number.
      - `state` string, required — 2 character ISO State code.
    - `nationalId` string — Customer National ID
  - `account` EstablishPostRequestBodyContentApplicationJsonSchemaAccount — Account information. Required if paymentType is Verification and a transactionId is not included.
    - `routingNumber` string — Bank Routing Number
    - `accountNumber` string — Bank Account Number
    - `type` string — Financial Institution Account Type
  - `beneficiary` EstablishPostRequestBodyContentApplicationJsonSchemaBeneficiary — The ultimate beneficiary of this payment. Required when using `paymentType: Instant` for [Money Transfer](/integrate/send-money)
    - `name` string — Full name of the Customer
    - `taxId` string — Customer tax ID (e.g. SSN [US], SIN [CA]). *May be required depending on industry and location.*
    - `address` Address — Valid mailing or billing address associated with the customer
      - `address1` string — Address line 1 (e.g., street or PO Box)
      - `address2` string — Address line 2 (e.g., apartment, suite or unit number)
      - `city` string — City, district, town or village
      - `state` string — State, province or region code
      - `zip` string — ZIP or Postal Code
      - `country` string, required — 2 character [ISO Country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
    - `phone` string — Customer phone number.
    - `email` string — Customer email address.
    - `dateOfBirth` string — Customer date of birth.
    - `createdAt` integer — The record created date and time as a UNIX timestamp.
    - `updatedAt` integer — The record created date and time as a UNIX timestamp.
  - `beneficiaryAccount` EstablishPostRequestBodyContentApplicationJsonSchemaBeneficiaryAccount — Financial institution account associated with the ultimate beneficiary of a transaction. Required when using `paymentType: Instant` for [Money Transfer](/integrate/send-money)
    - `accountNumber` number, double
    - `iban` string — International Bank Account Number (IBAN)
    - `paymentProvider` PaymentProvider — Details of the Financial institution
      - `paymentProviderId` string — A unique identifier for the Payment Provider.
      - `type` number, double
      - `name` string, required — Name of the payment provider
      - `instantPayoutAvailable` boolean — Whether payment provider supports instant payout.
      - `subType` '1000' | '2000' | '2001' — Financial Institution Account Type: * `1000`: Online Banking * `2000`: Manual Entry * `2001`: Manual Entry with Challenge Deposit
      - `swift` string
      - `address` Address — Valid mailing or billing address associated with the customer
        - `address1` string — Address line 1 (e.g., street or PO Box)
        - `address2` string — Address line 2 (e.g., apartment, suite or unit number)
        - `city` string — City, district, town or village
        - `state` string — State, province or region code
        - `zip` string — ZIP or Postal Code
        - `country` string, required — 2 character [ISO Country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
      - `country` 'US' | 'CA' | 'UK' | 'DE' | 'AU' — 2-letter ISO country code of the financial institution
      - `instantPayment` boolean
  - `kycType` string — 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` EstablishPostRequestBodyContentApplicationJsonSchemaMetadata — Provide additional use case-specific properties in this object.
    - `lang` string — Display language for text in the Trustly UI using the [ISO 639 Language Code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) format (e.g. `de_DE` or `fr_CA`). Defaults to `en_US` if not provided.
    - `finishButtonLabelType` 'pay' | 'deposit' | 'withdraw' — Modify the final button label of the Trustly UI. The default label is "Continue", by passing a supported alternative in this property the button label can be changed to "Pay Now", "Deposit" or "Withdraw".
    - `integrationContext` 'InAppBrowser' | 'InAppBrowserNotify' | 'ExternalBrowser' — Configuration required for mobile app compatibility with OAuth bank login flows. More details can be found in the [OAuth and Mobile apps guide](doc:oauth-guide).
    - `urlScheme` string — The deep link url associated with your mobile application. When users are directed to an external bank login or bank application on success or failure they will be redirected to this url. More details can be found in the [OAuth and Mobile apps guide](doc:oauth-guide).
    - `clc` EstablishPostRequestBodyContentApplicationJsonSchemaMetadataClc — Properties relating to Trustly In-Person configuration. Required for Trustly In-Person apps.
      - `propertyId` number, double — ID number for property or location
      - `machineId` number, double — ID number specific to an associated Electronic Wagering System
      - `qrTimestamp` string, date-time — Timestamp of QR code generation
      - `playerNumber` number, double — Player tracking number

## Response `200`

OK

- EstablishData — `establishData` is required to establish a new user authorization or to launch the Trustly UI for any other reason
  - `merchantId` string — Your Merchant ID.
  - `paymentType` number, double — The Payment Type of the transaction to create. Currently only Disbursement, Deferred, and Instant are supported.
  - `returnUrl` string — Return URL to use when the transaction is completed.
  - `cancelUrl` string — Cancel URL to use if the user cancels the transaction.
  - `notificationUrl` string — Notification URL to use for notifications associated with this transaction. This overrides the notification URL configured at the merchant level.
  - `data` string
  - `accessId` string — Your client application access id. It will be provided to you.
  - `requestSignature` string — Request Signature that can be validated to verify the response authenticity.
  - `transactionId` string — Transaction ID retrieved from Trustly.
  - `merchantReference` string — An external reference from the merchant. Ex: Order identifier from merchant e-commerce application.
  - `description` string — Merchant order description
  - `currency` 'USD' — 3-letter ISO Currency Code. Currently only USD is supported.
  - `kycType` 'OnlineBanking' — Specifies the KYC (Know Your Customer) type as number. The possible value is 1 (OnlineBanking). This field is optional and can only be used by merchants configured for [Trustly ID](/integrate/retrieve-data/trustly-id).
  - `amount` string — 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)
  - `verification` Verification
    - `status` '1' | '2' | '3' | '4' — Verification Status: * `1`: Automatic - Payment verification followed Trustly internal rules. * `2`: ToVerify - Payment transaction is held (status = OnHold) for further investigation and approval by the merchant. * `3`: Verified - Payment was verified and approved by the merchant or Trustly (see Verification Mode). * `4`: Refused - Payment was denied by the merchant or Trustly after verification.
    - `mode` '1' | '2' | '3' | '4' — Verification Mode: * `1`: VerifiedByMerchant * `2`: ApprovedByMerchant * `3`: VerifiedByTrustly * `4`: AmountAuthorizedByMerchant
    - `verifyCustomer` boolean — If true, the Customer information (name and zip code) was verified against information provided by the User's bank.
  - `customer` Customer — The Trustly customer object, containing identification details and contact information.
    - `name` string, required — Full name of the Customer
    - `taxId` string — Customer tax ID (e.g. SSN [US], SIN [CA]). *May be required depending on industry and location.*
    - `address` Address, required — Valid mailing or billing address associated with the customer
      - `address1` string — Address line 1 (e.g., street or PO Box)
      - `address2` string — Address line 2 (e.g., apartment, suite or unit number)
      - `city` string — City, district, town or village
      - `state` string — State, province or region code
      - `zip` string — ZIP or Postal Code
      - `country` string, required — 2 character [ISO Country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
    - `phone` string, required — Customer phone number.
    - `email` string, required — Customer email address.
    - `dateOfBirth` string — Customer date of birth.
    - `createdAt` integer — The record created date and time as a UNIX timestamp.
    - `updatedAt` integer — The record created date and time as a UNIX timestamp.
    - `customerId` string — A unique Trustly customer identifier.
    - `externalId` string — A unique merchant customer identifier.
    - `merchantId` string — A unique Trustly merchant identifier.
    - `enrollDate` integer — Date of the user's first transaction in your system, regardless of payment method used as a UNIX timestamp.
    - `vip` string — Range that determines how low-risk the customer represents to the merchant
    - `currency` string — Customer currency.
    - `balance` string — Customer account balance (not associated with a financial institution account).
    - `organizationNumber` string — Organization number for business accounts
    - `externalTier` string — It should describe the customer''s rank to the merchant (e.g. Gold, Diamond, 4 stars, etc.)
    - `personId` string — Unique customer identity throughout different banks.
    - `customData` CustomerCustomData — Object for sending merchant-specific custom data.
    - `driverLicense` DriverLicense
      - `number` string, required — Driver License number.
      - `state` string, required — 2 character ISO State code.
    - `nationalId` string — Customer National ID
  - `account` Account
    - `providerId` string — Payment provider ID.
    - `paymentProvider` PaymentProvider — Details of the Financial institution
      - `paymentProviderId` string — A unique identifier for the Payment Provider.
      - `type` number, double
      - `name` string, required — Name of the payment provider
      - `instantPayoutAvailable` boolean — Whether payment provider supports instant payout.
      - `subType` '1000' | '2000' | '2001' — Financial Institution Account Type: * `1000`: Online Banking * `2000`: Manual Entry * `2001`: Manual Entry with Challenge Deposit
      - `swift` string
      - `address` Address — Valid mailing or billing address associated with the customer
        - `address1` string — Address line 1 (e.g., street or PO Box)
        - `address2` string — Address line 2 (e.g., apartment, suite or unit number)
        - `city` string — City, district, town or village
        - `state` string — State, province or region code
        - `zip` string — ZIP or Postal Code
        - `country` string, required — 2 character [ISO Country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
      - `country` 'US' | 'CA' | 'UK' | 'DE' | 'AU' — 2-letter ISO country code of the financial institution
      - `instantPayment` boolean
    - `country` 'US' | 'CA' | 'UK' | 'DE' | 'AU' — 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.
    - `name` string — A description to identify a specific account (e.g. Test checking account)
    - `type` number, double — See Financial Institution Account Type Values.
    - `profile` number, double — See Financial Institution Account Profile Values
    - `accountNumber` string — Bank Account Number or VAN if `virtualAccountRoutingPair` is equal to `true`.
    - `iban` string — IBAN (International Bank Account Number) is an internationally agreed system of identifying bank accounts across national borders
    - `verified` boolean — Indicates if the account is verified or not.
    - `verification` FinancialInstitutionAccountVerification
      - `verified` boolean, required — true if the account is verified; false otherwise.
      - `type` '1' | '2' | '3', required — Verification Type: * `1`: Manual - The account was verified with manual account verification. For example, Manual Electronic Check and Micro Challenge Deposit. * `2`: Online Banking verification - The Account was verified using the Trustly Online Banking application. * `3`: Database verification - The Account was verified using the Trustly database or a Third-Party Service.
      - `hasEnoughFunds` boolean, required — If true, there is enough balance in account.
      - `verificationDate` integer, required — The date and time the verification was completed as a UNIX timestamp.
      - `score` '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' — Verification Score: * `0`: Invalid input. The account or routing number are invalid. (Verified Mapping = false) * `1`: There is a strong indication that the account is invalid. (Verified Mapping = false) * `2`: There are active non-bankable returns on this account that are less than 3 years old. (Verified Mapping = false) * `3`: There are administrative returns on this account. (Verified Mapping = false) * `4`: The format appears to be suspicious. (Verified Mapping = false) * `5`: There is no data on this account or format. (Verified Mapping = false) * `6`: We have not seen this account, but the format appears to be valid. (Verified Mapping = true) * `7`: We have seen this account but have not received a final disposition on the transaction. (Verified Mapping = true) * `8`: We have seen this account, but not in the last 6 months, and have seen no returns associated with the account. (Verified Mapping = true) * `9`: We have seen this account in the last 6 months and have seen no returns associated with the account. (Verified Mapping = true) * `10`: This account has been directly validated with/by the financial institution or 3rd party. We have the highest confidence that this account is valid. (Verified Mapping = true)
      - `thirdPartyScore` '0' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | '999' — Verification Third-Party Score: * `0`: Failed RT validation. (Verified Mapping = 0) * `100`: The supplier has a strong indication that this account is invalid. (Verified Mapping = 1) * `200`: The supplier has active non-bankable debt(s) on this account that are less than 3 years old. (Verified Mapping = 2) * `300`: The supplier has administrative returns on this account. (Verified Mapping = 3) * `400`: The supplier does not have Neg data on this account, but the format appears to be suspicious. (Verified Mapping = 4) * `500`: The supplier does not have data on this account or format. (Verified Mapping = 5) * `600`: The supplier has not seen this account, but the format appears valid. (Verified Mapping = 6) * `700`: The supplier has seen this account, but did not receive a final disposition on the transaction. (Verified Mapping = 7) * `800`: The supplier has seen this account, but not in the last 6 months. (Verified Mapping = 8) * `900`: The supplier has seen this account in the last 6 months. (Verified Mapping = 9) * `999`: The supplier has the highest confidence that this account is valid. (Verified Mapping = 10)
      - `numberOfTries` number, double — Number of tries allowed.
      - `numberOfAttemptsLeft` number, double — Number of remaining attempts.
    - `source` number, double
    - `routingNumber` string — Bank Routing Number
    - `token` string — The Account Token
    - `accountNumberLastFour` string — The last 4 digits of the real account number.
    - `virtualAccountRoutingPair` boolean — Indicates if account is using virtual/tokenized account and routing numbers (VANs/TANs) or not.
  - `metadata` Attribute
    - `name` string
    - `value` string
  - `trustlyABRequest` TrustlyABRequest
    - `successURL` string
    - `failURL` string
    - `uRLTarget` string
    - `callbackURL` string
    - `notificationURL` string
  - `url` string, required

---

[API](https://skmtc.dev/trustly/apis/api.md) · [All operations](https://skmtc.dev/trustly/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/trustly/api/revisions/2dad675032f1/schema)