Trustly Group · Schema
EstablishData
`establishData` is required to establish a new user authorization or to launch the Trustly UI for any other reason
CompanyPaymentsPay by BankOpen BankingAccount-to-AccountPayoutsDirect DebitBank Account VerificationIdentity VerificationFintechWebhookMCP
Properties
| Name | Type | Description |
|---|---|---|
| merchantId | string | Your Merchant ID. |
| paymentType | number | 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 | object | 3-letter ISO Currency Code. Currently only USD is supported. |
| kycType | object | 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 |
| 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 transacti |
| verification | object | |
| customer | object | |
| account | object | |
| metadata | object | |
| trustlyABRequest | object | |
| url | string |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/api-evangelist/trustly/main/json-schema/trustly-establish-data-schema.json",
"title": "EstablishData",
"description": "`establishData` is required to establish a new user authorization or to launch the Trustly UI for any other reason",
"x-generated": "2026-10-12",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/trustly-transactions-api-openapi.yml#/components/schemas/EstablishData",
"type": "object",
"properties": {
"merchantId": {
"type": "string",
"description": "Your Merchant ID."
},
"paymentType": {
"type": "number",
"format": "double",
"description": "The Payment Type of the transaction to create. Currently only Disbursement, Deferred, and Instant are supported."
},
"returnUrl": {
"type": "string",
"description": "Return URL to use when the transaction is completed."
},
"cancelUrl": {
"type": "string",
"description": "Cancel URL to use if the user cancels the transaction."
},
"notificationUrl": {
"type": "string",
"description": "Notification URL to use for notifications associated with this transaction. This overrides the notification URL configured at the merchant level."
},
"data": {
"type": "string"
},
"accessId": {
"type": "string",
"description": "Your client application access id. It will be provided to you."
},
"requestSignature": {
"type": "string",
"description": "Request Signature that can be validated to verify the response authenticity."
},
"transactionId": {
"type": "string",
"description": "Transaction ID retrieved from Trustly."
},
"merchantReference": {
"type": "string",
"description": "An external reference from the merchant. Ex: Order identifier from merchant e-commerce application."
},
"description": {
"type": "string",
"description": "Merchant order description"
},
"currency": {
"$ref": "#/$defs/EstablishDataCurrency",
"description": "3-letter ISO Currency Code. Currently only USD is supported."
},
"kycType": {
"$ref": "#/$defs/EstablishDataKycType",
"description": "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": {
"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)"
},
"verification": {
"$ref": "#/$defs/Verification"
},
"customer": {
"$ref": "#/$defs/Customer"
},
"account": {
"$ref": "#/$defs/Account"
},
"metadata": {
"$ref": "#/$defs/Attribute"
},
"trustlyABRequest": {
"$ref": "#/$defs/TrustlyABRequest"
},
"url": {
"type": "string",
"minLength": 1
}
},
"required": [
"url"
],
"$defs": {
"Account": {
"type": "object",
"properties": {
"providerId": {
"type": "string",
"description": "Payment provider ID."
},
"paymentProvider": {
"$ref": "#/$defs/PaymentProvider"
},
"country": {
"$ref": "#/$defs/AccountCountry",
"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."
},
"name": {
"type": "string",
"description": "A description to identify a specific account (e.g. Test checking account)"
},
"type": {
"type": "number",
"format": "double",
"description": "See Financial Institution Account Type Values."
},
"profile": {
"type": "number",
"format": "double",
"description": "See Financial Institution Account Profile Values"
},
"accountNumber": {
"type": "string",
"minLength": 1,
"description": "Bank Account Number or VAN if `virtualAccountRoutingPair` is equal to `true`."
},
"iban": {
"type": "string",
"description": "IBAN (International Bank Account Number) is an internationally agreed system of identifying bank accounts across national borders"
},
"verified": {
"type": "boolean",
"description": "Indicates if the account is verified or not."
},
"verification": {
"$ref": "#/$defs/FinancialInstitutionAccountVerification"
},
"source": {
"type": "number",
"format": "double"
},
"routingNumber": {
"type": "string",
"minLength": 1,
"description": "Bank Routing Number"
},
"token": {
"type": "string",
"minLength": 1,
"description": "The Account Token"
},
"accountNumberLastFour": {
"type": "string",
"description": "The last 4 digits of the real account number."
},
"virtualAccountRoutingPair": {
"type": "boolean",
"description": "Indicates if account is using virtual/tokenized account and routing numbers (VANs/TANs) or not."
}
},
"title": "Account"
},
"AccountCountry": {
"type": "string",
"enum": [
"US",
"CA",
"UK",
"DE",
"AU"
],
"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.",
"title": "AccountCountry"
},
"Address": {
"type": "object",
"properties": {
"address1": {
"type": "string",
"minLength": 1,
"description": "Address line 1 (e.g., street or PO Box)"
},
"address2": {
"type": "string",
"description": "Address line 2 (e.g., apartment, suite or unit number)"
},
"city": {
"type": "string",
"minLength": 1,
"description": "City, district, town or village"
},
"state": {
"type": "string",
"minLength": 2,
"description": "State, province or region code"
},
"zip": {
"type": "string",
"minLength": 5,
"description": "ZIP or Postal Code"
},
"country": {
"type": "string",
"minLength": 2,
"description": "2 character [ISO Country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)"
}
},
"required": [
"country"
],
"description": "Valid mailing or billing address associated with the customer",
"title": "Address"
},
"Attribute": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
},
"title": "Attribute"
},
"Customer": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Full name of the Customer"
},
"taxId": {
"type": "string",
"description": "Customer tax ID (e.g. SSN [US], SIN [CA]). *May be required depending on industry and location.*"
},
"address": {
"$ref": "#/$defs/Address"
},
"phone": {
"type": "string",
"description": "Customer phone number."
},
"email": {
"type": "string",
"minLength": 1,
"description": "Customer email address."
},
"dateOfBirth": {
"type": "string",
"description": "Customer date of birth."
},
"createdAt": {
"type": "integer",
"description": "The record created date and time as a UNIX timestamp."
},
"updatedAt": {
"type": "integer",
"description": "The record created date and time as a UNIX timestamp."
},
"customerId": {
"type": "string",
"description": "A unique Trustly customer identifier."
},
"externalId": {
"type": "string",
"minLength": 1,
"description": "A unique merchant customer identifier."
},
"merchantId": {
"type": "string",
"minLength": 1,
"description": "A unique Trustly merchant identifier."
},
"enrollDate": {
"type": "integer",
"description": "Date of the user's first transaction in your system, regardless of payment method used as a UNIX timestamp."
},
"vip": {
"type": "string",
"description": "Range that determines how low-risk the customer represents to the merchant"
},
"currency": {
"type": "string",
"description": "Customer currency."
},
"balance": {
"type": "string",
"description": "Customer account balance (not associated with a financial institution account)."
},
"organizationNumber": {
"type": "string",
"description": "Organization number for business accounts"
},
"externalTier": {
"type": "string",
"description": "It should describe the customer''s rank to the merchant (e.g. Gold, Diamond, 4 stars, etc.)"
},
"personId": {
"type": "string",
"description": "Unique customer identity throughout different banks."
},
"customData": {
"$ref": "#/$defs/CustomerCustomData",
"description": "Object for sending merchant-specific custom data."
},
"driverLicense": {
"$ref": "#/$defs/DriverLicense"
},
"nationalId": {
"type": "string",
"description": "Customer National ID"
}
},
"required": [
"name",
"address",
"phone",
"email"
],
"description": "The Trustly customer object, containing identification details and contact information.",
"title": "Customer"
},
"CustomerCustomData": {
"type": "object",
"properties": {},
"description": "Object for sending merchant-specific custom data.",
"title": "CustomerCustomData"
},
"DriverLicense": {
"type": "object",
"properties": {
"number": {
"type": "string",
"description": "Driver License number."
},
"state": {
"type": "string",
"description": "2 character ISO State code."
}
},
"required": [
"number",
"state"
],
"title": "DriverLicense"
},
"EstablishDataCurrency": {
"type": "string",
"enum": [
"USD"
],
"description": "3-letter ISO Currency Code. Currently only USD is supported.",
"title": "EstablishDataCurrency"
},
"EstablishDataKycType": {
"type": "string",
"enum": [
"OnlineBanking"
],
"description": "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).",
"title": "EstablishDataKycType"
},
"FinancialInstitutionAccountVerification": {
"type": "object",
"properties": {
"verified": {
"type": "boolean",
"description": "true if the account is verified; false otherwise."
},
"type": {
"$ref": "#/$defs/FinancialInstitutionAccountVerificationType",
"description": "Verification Type:\n * `1`: Manual - The account was verified with manual account verification. For example, Manual Electronic Check and Micro Challenge Deposit.\n * `2`: Online Banking verification\t- The Account was verified using the Trustly Online Banking application.\n * `3`: Database verification\t- The Account was verified using the Trustly database or a Third-Party Service. \n"
},
"hasEnoughFunds": {
"type": "boolean",
"description": "If true, there is enough balance in account."
},
"verificationDate": {
"type": "integer",
"description": "The date and time the verification was completed \n as a UNIX timestamp."
},
"score": {
"$ref": "#/$defs/FinancialInstitutionAccountVerificationScore",
"description": "Verification Score:\n * `0`: Invalid input. The account or routing number are invalid. (Verified Mapping = false)\n * `1`: There is a strong indication that the account is invalid. (Verified Mapping = false)\n * `2`: There are active non-bankable returns on this account that are less than 3 years old. (Verified Mapping = false)\n * `3`: There are administrative returns on this account. (Verified Mapping = false)\n * `4`: The format appears to be suspicious. (Verified Mapping = false)\n * `5`: There is no data on this account or format. (Verified Mapping = false)\n * `6`: We have not seen this account, but the format appears to be valid. (Verified Mapping = true)\n * `7`: We have seen this account but have not received a final disposition on the transaction. (Verified Mapping = true)\n * `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)\n * `9`: We have seen this account in the last 6 months and have seen no returns associated with the account. (Verified Mapping = true)\n * `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)\n"
},
"thirdPartyScore": {
"$ref": "#/$defs/FinancialInstitutionAccountVerificationThirdPartyScore",
"description": "Verification Third-Party Score:\n * `0`: Failed RT validation. (Verified Mapping = 0)\n * `100`: The supplier has a strong indication that this account is invalid. (Verified Mapping = 1)\n * `200`: The supplier has active non-bankable debt(s) on this account that are less than 3 years old. (Verified Mapping = 2)\n * `300`: The supplier has administrative returns on this account. (Verified Mapping = 3)\n * `400`: The supplier does not have Neg data on this account, but the format appears to be suspicious. (Verified Mapping = 4)\n * `500`: The supplier does not have data on this account or format. (Verified Mapping = 5)\n * `600`: The supplier has not seen this account, but the format appears valid. (Verified Mapping = 6)\n * `700`: The supplier has seen this account, but did not receive a final disposition on the transaction. (Verified Mapping = 7)\n * `800`: The supplier has seen this account, but not in the last 6 months. (Verified Mapping = 8)\n * `900`: The supplier has seen this account in the last 6 months. (Verified Mapping = 9)\n * `999`: The supplier has the highest confidence that this account is valid. (Verified Mapping = 10)\n"
},
"numberOfTries": {
"type": "number",
"format": "double",
"description": "Number of tries allowed."
},
"numberOfAttemptsLeft": {
"type": "number",
"format": "double",
"description": "Number of remaining attempts."
}
},
"required": [
"verified",
"type",
"hasEnoughFunds",
"verificationDate"
],
"title": "FinancialInstitutionAccountVerification"
},
"FinancialInstitutionAccountVerificationScore": {
"type": "string",
"enum": [
"0",
"1",
"2",
"3",
"4",
"5",
"6",
"7",
"8",
"9",
"10"
],
"description": "Verification Score:\n * `0`: Invalid input. The account or routing number are invalid. (Verified Mapping = false)\n * `1`: There is a strong indication that the account is invalid. (Verified Mapping = false)\n * `2`: There are active non-bankable returns on this account that are less than 3 years old. (Verified Mapping = false)\n * `3`: There are administrative returns on this account. (Verified Mapping = false)\n * `4`: The format appears to be suspicious. (Verified Mapping = false)\n * `5`: There is no data on this account or format. (Verified Mapping = false)\n * `6`: We have not seen this account, but the format appears to be valid. (Verified Mapping = true)\n * `7`: We have seen this account but have not received a final disposition on the transaction. (Verified Mapping = true)\n * `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)\n * `9`: We have seen this account in the last 6 months and have seen no returns associated with the account. (Verified Mapping = true)\n * `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)\n",
"title": "FinancialInstitutionAccountVerificationScore"
},
"FinancialInstitutionAccountVerificationThirdPartyScore": {
"type": "string",
"enum": [
"0",
"100",
"200",
"300",
"400",
"500",
"600",
"700",
"800",
"900",
"999"
],
"description": "Verification Third-Party Score:\n * `0`: Failed RT validation. (Verified Mapping = 0)\n * `100`: The supplier has a strong indication that this account is invalid. (Verified Mapping = 1)\n * `200`: The supplier has active non-bankable debt(s) on this account that are less than 3 years old. (Verified Mapping = 2)\n * `300`: The supplier has administrative returns on this account. (Verified Mapping = 3)\n * `400`: The supplier does not have Neg data on this account, but the format appears to be suspicious. (Verified Mapping = 4)\n * `500`: The supplier does not have data on this account or format. (Verified Mapping = 5)\n * `600`: The supplier has not seen this account, but the format appears valid. (Verified Mapping = 6)\n * `700`: The supplier has seen this account, but did not receive a final disposition on the transaction. (Verified Mapping = 7)\n * `800`: The supplier has seen this account, but not in the last 6 months. (Verified Mapping = 8)\n * `900`: The supplier has seen this account in the last 6 months. (Verified Mapping = 9)\n * `999`: The supplier has the highest confidence that this account is valid. (Verified Mapping = 10)\n",
"title": "FinancialInstitutionAccountVerificationThirdPartyScore"
},
"FinancialInstitutionAccountVerificationType": {
"type": "string",
"enum": [
"1",
"2",
"3"
],
"description": "Verification Type:\n * `1`: Manual - The account was verified with manual account verification. For example, Manual Electronic Check and Micro Challenge Deposit.\n * `2`: Online Banking verification\t- The Account was verified using the Trustly Online Banking application.\n * `3`: Database verification\t- The Account was verified using the Trustly database or a Third-Party Service. \n",
"title": "FinancialInstitutionAccountVerificationType"
},
"PaymentProvider": {
"type": "object",
"properties": {
"paymentProviderId": {
"type": "string",
"minLength": 1,
"description": "A unique identifier for the Payment Provider."
},
"type": {
"type": "number",
"format": "double"
},
"name": {
"type": "string",
"minLength": 1,
"description": "Name of the payment provider"
},
"instantPayoutAvailable": {
"type": "boolean",
"description": "Whether payment provider supports instant payout."
},
"subType": {
"$ref": "#/$defs/PaymentProviderSubType",
"description": "Financial Institution Account Type:\n * `1000`: Online Banking\n * `2000`: Manual Entry\n * `2001`: Manual Entry with Challenge Deposit\n"
},
"swift": {
"type": "string"
},
"address": {
"$ref": "#/$defs/Address"
},
"country": {
"$ref": "#/$defs/PaymentProviderCountry",
"description": "2-letter ISO country code of the financial institution"
},
"instantPayment": {
"type": "boolean"
}
},
"required": [
"name"
],
"description": "Details of the Financial institution",
"title": "PaymentProvider"
},
"PaymentProviderCountry": {
"type": "string",
"enum": [
"US",
"CA",
"UK",
"DE",
"AU"
],
"description": "2-letter ISO country code of the financial institution",
"title": "PaymentProviderCountry"
},
"PaymentProviderSubType": {
"type": "string",
"enum": [
"1000",
"2000",
"2001"
],
"description": "Financial Institution Account Type:\n * `1000`: Online Banking\n * `2000`: Manual Entry\n * `2001`: Manual Entry with Challenge Deposit\n",
"title": "PaymentProviderSubType"
},
"TrustlyABRequest": {
"type": "object",
"properties": {
"successURL": {
"type": "string"
},
"failURL": {
"type": "string"
},
"uRLTarget": {
"type": "string"
},
"callbackURL": {
"type": "string"
},
"notificationURL": {
"type": "string"
}
},
"title": "TrustlyABRequest"
},
"Verification": {
"type": "object",
"properties": {
"status": {
"$ref": "#/$defs/VerificationStatus",
"description": "Verification Status:\n * `1`: Automatic - Payment verification followed Trustly internal rules.\n * `2`: ToVerify\t- Payment transaction is held (status = OnHold) for further investigation and approval by the merchant.\n * `3`: Verified - Payment was verified and approved by the merchant or Trustly (see Verification Mode).\n * `4`: Refused - Payment was denied by the merchant or Trustly after verification.\n"
},
"mode": {
"$ref": "#/$defs/VerificationMode",
"description": "Verification Mode:\n * `1`: VerifiedByMerchant\n * `2`: ApprovedByMerchant\n * `3`: VerifiedByTrustly\n * `4`: AmountAuthorizedByMerchant\n"
},
"verifyCustomer": {
"type": "boolean",
"description": "If true, the Customer information (name and zip code) was verified against information provided by the User's bank."
}
},
"title": "Verification"
},
"VerificationMode": {
"type": "string",
"enum": [
"1",
"2",
"3",
"4"
],
"description": "Verification Mode:\n * `1`: VerifiedByMerchant\n * `2`: ApprovedByMerchant\n * `3`: VerifiedByTrustly\n * `4`: AmountAuthorizedByMerchant\n",
"title": "VerificationMode"
},
"VerificationStatus": {
"type": "string",
"enum": [
"1",
"2",
"3",
"4"
],
"description": "Verification Status:\n * `1`: Automatic - Payment verification followed Trustly internal rules.\n * `2`: ToVerify\t- Payment transaction is held (status = OnHold) for further investigation and approval by the merchant.\n * `3`: Verified - Payment was verified and approved by the merchant or Trustly (see Verification Mode).\n * `4`: Refused - Payment was denied by the merchant or Trustly after verification.\n",
"title": "VerificationStatus"
}
}
}Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/trustly-establish-data"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.