PayWithMyBank (Trustly) identity API
The identity API from PayWithMyBank (Trustly) — 3 operation(s) for identity.
The identity API from PayWithMyBank (Trustly) — 3 operation(s) for identity.
openapi: 3.1.0
info:
title: accountData identity API
version: 1.0.0
servers:
- url: https://sandbox.trustly.one/api/v1
description: Sandbox
tags:
- name: identity
paths:
/transactions/{transactionId}/user:
get:
operationId: 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'
- name: Authorization
in: header
description: ''
required: true
schema:
type: string
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'
/transactions/{transactionId}/user/detail:
get:
operationId: 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'
- name: Authorization
in: header
description: ''
required: true
schema:
type: string
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'
/transactions/{transactionId}/feedback:
post:
operationId: 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
- name: Authorization
in: header
description: ''
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
components:
schemas:
Verification:
type: object
properties:
status:
$ref: '#/components/schemas/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: '#/components/schemas/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
ScreeningResult:
type: array
items:
$ref: '#/components/schemas/ScreeningResultItems'
title: ScreeningResult
CustomerCustomData:
type: object
properties: {}
description: Object for sending merchant-specific custom data.
title: CustomerCustomData
PaymentSystem:
type: string
enum:
- '-1'
- '1'
- '2'
description: "Financial Institution Account Type:\n * `-1`: None\n * `1`: PayWithMyBank\n * `2`: TrustlyAB"
title: PaymentSystem
TransactionsTransactionIdUserDetailGetParametersExpandSchemaItems:
type: string
enum:
- verification
title: TransactionsTransactionIdUserDetailGetParametersExpandSchemaItems
AdversityMediaScreeningResult:
type: object
properties:
screeningType:
$ref: '#/components/schemas/ScreeningResultScreeningType'
score:
type: number
format: double
description: Match score indicating the strength of a match.
name:
type: string
description: Name of the user.
text:
type: string
description: Text description.
url:
type: string
description: Source's URL.
title:
type: string
description: The adverse media title.
date:
type: string
format: date
description: The adverse media date.
trustedEntity:
type: string
description: The name of the entity that provided the adverse media match.
description: Screening information for Adversity Media Screening.
title: AdversityMediaScreeningResult
AttributeVerificationDetailName:
type: string
enum:
- taxId
- name
- address
- phone
- dateOfBirth
- email
- driverLicense
- deceased
description: Which attribute does this entry refer to.
title: AttributeVerificationDetailName
PaymentMerchant:
type: object
properties:
merchantId:
type: string
description: Unique Trustly Merchant ID.
name:
type: string
description: Merchants name.
title: PaymentMerchant
TransactionTransactionType:
type: string
enum:
- '0'
- '1'
- '2'
- '3'
- '4'
- '5'
- '6'
- '7'
- '8'
- '10'
description: Type of transaction record. See [Transaction Types](/integrate/api-fundamentals/status-codes-and-type-definitions#transaction-types)
title: TransactionTransactionType
Address:
type: object
properties:
address1:
type: string
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
description: City, district, town or village
state:
type: string
description: State, province or region code
zip:
type: string
description: ZIP or Postal Code
country:
type: string
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
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
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
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
TransactionsTransactionIdUserGetParametersExpandSchemaItems:
type: string
enum:
- segmentedName
title: TransactionsTransactionIdUserGetParametersExpandSchemaItems
Get-trustly-id-user-detailsRequestBadRequestError:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/TransactionsTransactionIdUserDetailGetResponsesContentApplicationJsonSchemaErrorsItems'
required:
- errors
title: Get-trustly-id-user-detailsRequestBadRequestError
TransactionStatus:
type: string
enum:
- '0'
- '1'
- '2'
- '3'
- '4'
- '5'
- '6'
- '7'
- '8'
- '10'
- '11'
- '12'
- '13'
- '14'
description: Status code of the Payment Provider Transaction record. See [Transaction Types](/integrate/api-fundamentals/status-codes-and-type-definitions#transaction-types)
title: TransactionStatus
AttributeVerificationMethod:
type: integer
description: 'Indicates which type of verification was performed. It can be:
* `1` means electronic identity verification.
* `2` meaning it is manual document verification.
* `3` meaning it is OCR verification.
* `4` meaning it is Trusted Entity.'
title: AttributeVerificationMethod
TransactionsTransactionIdUserDetailGetResponsesContentApplicationJsonSchemaErrorsItems:
type: object
properties:
domain:
type: string
code:
type: number
format: double
location:
type: string
message:
type: string
occurredAt:
type: number
format: double
required:
- domain
- code
- location
- message
- occurredAt
title: TransactionsTransactionIdUserDetailGetResponsesContentApplicationJsonSchemaErrorsItems
schemas-Address:
type: object
properties:
address1:
type: string
description: Address Line 1.
address2:
type: string
description: Address Line 2.
city:
type: string
description: Address City.
state:
$ref: '#/components/schemas/StateCode'
zip:
type: string
description: 5 character US Zip Code.
country:
$ref: '#/components/schemas/SchemasAddressCountry'
description: 2 character ISO Country code. Currently only the US is supported.
required:
- country
title: schemas-Address
Customer:
type: object
properties:
name:
type: string
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: '#/components/schemas/Address'
phone:
type: string
description: Customer phone number.
email:
type: string
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
description: A unique merchant customer identifier.
merchantId:
type: string
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: '#/components/schemas/CustomerCustomData'
description: Object for sending merchant-specific custom data.
driverLicense:
$ref: '#/components/schemas/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
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
UserVerificationDetailDetail:
type: object
properties:
verification:
type: array
items:
$ref: '#/components/schemas/UserVerificationResult'
attribute:
type: array
items:
$ref: '#/components/schemas/AttributeVerificationDetail'
title: UserVerificationDetailDetail
WatchlistScreeningResult:
type: object
properties:
screeningType:
$ref: '#/components/schemas/ScreeningResultScreeningType'
score:
type: number
format: double
description: Match score indicating the strength of a match.
name:
type: string
description: Name of the user.
aliases:
type: array
items:
type: string
description: List of known aliases.
dateOfBirth:
type: string
format: date
description: Date of birth.
nationality:
type: string
description: Nationality.
source:
type: string
description: Source of the information.
sourceRegion:
type: string
description: Region of the source.
remarks:
type: string
description: Additional remarks.
caution:
type: string
description: Caution notes.
url:
type: string
format: uri
description: Source's URL.
address:
type: string
description: Full street address of the user with city and country.
gender:
$ref: '#/components/schemas/WatchlistScreeningResultGender'
description: Gender of the user.
designationDate:
type: string
format: date
description: Designation date.
trustedEntity:
type: string
description: The name of the entity that provided the watchlist match.
description: Screening information for Watchlist Screening.
title: WatchlistScreeningResult
PaymentCurrency:
type: string
enum:
- USD
description: 3-letter ISO Currency Code. Currently only USD is supported.
title: PaymentCurrency
ScreeningResultItems:
oneOf:
- $ref: '#/components/schemas/WatchlistScreeningResult'
- $ref: '#/components/schemas/AdversityMediaScreeningResult'
- $ref: '#/components/schemas/PEPScreeningResult'
title: ScreeningResultItems
ScreeningResultScreeningType:
type: string
enum:
- '1'
- '2'
- '3'
description: 'Type of screening being performed. May be:
* `1`: Watchlist Screening.
* `2`: Adverse Media Screening.
* `3`: PEP Screening.'
title: ScreeningResultScreeningType
schemas-DriverLicense:
type: object
properties:
number:
type: string
description: The driver's license number. Even though this field is called 'number', it may contain non-numeric characters if the country allows that.
state:
$ref: '#/components/schemas/StateCode'
description: A driver's license.
title: schemas-DriverLicense
SchemasAddressCountry:
type: string
enum:
- US
description: 2 character ISO Country code. Currently only the US is supported.
title: SchemasAddressCountry
Transaction:
type: object
properties:
transactionId:
type: string
description: A unique transaction identifier generated by Trustly (15 character max).
transactionType:
$ref: '#/components/schemas/TransactionTransactionType'
description: Type of transaction record. See [Transaction Types](/integrate/api-fundamentals/status-codes-and-type-definitions#transaction-types)
payment:
$ref: '#/components/schemas/Payment'
currency:
$ref: '#/components/schemas/TransactionCurrency'
description: 3-letter ISO Currency Code. Currently only USD is supported.
amount:
type: string
description: The amount of the transaction. (10 characters with support for 2 decimal places)
pending:
type: string
description: The total amount that is still pending completion. (10 characters with support for 2 decimal places)
paid:
type: string
description: The total amount that was already paid. (10 characters with support for 2 decimal places)
refunded:
type: string
description: The total amount that was refunded. (10 characters with support for 2 decimal places)
reversed:
type: string
description: The total amount that was reversed. (10 characters with support for 2 decimal places)
balance:
type: string
description: The balance of the amount paid, minus the amount reversed and/or refunded. (10 characters with support for 2 decimal places)
paymentProviderTransaction:
$ref: '#/components/schemas/PaymentProviderTransaction'
status:
$ref: '#/components/schemas/TransactionStatus'
description: Status code of the Payment Provider Transaction record. See [Transaction Types](/integrate/api-fundamentals/status-codes-and-type-definitions#transaction-types)
statusMessage:
type: string
description: A descriptive status message. (120 characters)
ip:
type: string
description: The client IP address in IPv4 or IPv6 format.
createdAt:
type: integer
description: The date and time the transaction was created as a UNIX timestamp.
processedAt:
type: integer
description: The date and time the transaction was processed as a UNIX timestamp.
completedAt:
type: integer
description: The date and time the transaction was completed as a UNIX timestamp.
updatedAt:
type: integer
description: The date and time the transaction was last updated as a UNIX timestamp.
ppTrxId:
type: string
description: internal use only
merchantReference:
type: string
description: Merchants internal reference id for the transaction.
expiredAt:
type: integer
description: The date and time the preauthorization will expire as a UNIX timestamp.
recordVersion:
type: number
format: double
description: The current record version.
originalTransactionId:
type: string
fee:
type: string
timeZone:
type: string
representmentScheduledAt:
type: number
format: double
paymentProcessorType:
type: string
statusCode:
type: string
preAuthorized:
type: boolean
required:
- transactionId
- transactionType
- payment
- currency
- amount
- pending
- paid
- refunded
- reversed
- balance
- paymentProviderTransaction
- status
- statusMessage
- ip
- createdAt
- processedAt
- completedAt
- updatedAt
- merchantReference
- recordVersion
description: A Trustly transaction object
title: Transaction
UserVerificationResult:
type: object
properties:
result:
$ref: '#/components/schemas/UserVerificationResultCode'
reasons:
type: array
items:
$ref: '#/components/schemas/UserVerificationReason'
screeningResult:
type: array
items:
$ref: '#/components/schemas/ScreeningResult'
description: Details on the user verification.
title: UserVerificationResult
PEPScreeningResult:
type: object
properties:
screeningType:
$ref: '#/components/schemas/ScreeningResultScreeningType'
score:
type: number
format: double
description: Match score indicating the strength of a match.
name:
type: string
description: Name of the user.
dateOfBirth:
type: string
format: date
description: Date of birth.
contry:
type: string
description: Country.
professionalHistory:
type: array
items:
type: string
trustedEntity:
type: string
description: The name of the entity that provided the PEP match.
description: Screening information for PEP Screening.
title: PEPScreeningResult
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
AttributeVerification:
type: object
properties:
trustedEntity:
type: string
description: The name of the entity that verified the attribute.
verificationType:
type: integer
description: 'Indicates the type of the entity that verified this piece of data. It can be:
* `1` verified by a financial institution.
* `2` verified by user input.
* `3` verified by the Trustly internal database.
* `4` verified by an external provider.'
verificationMethod:
$ref: '#/components/schemas/AttributeVerificationMethod'
result:
$ref: '#/components/schemas/AttributeVerificationResult'
verifiedAt:
type: integer
format: int64
description: Unix Timestamp in milliseconds (since the epoch) when the verification took place.
title: AttributeVerification
AttributeVerificationDetail:
type: object
properties:
name:
$ref: '#/components/schemas/AttributeVerificationDetailName'
description: Which attribute does this entry refer to.
source:
$ref: '#/components/schemas/AttributeVerificationDetailSource'
createdAt:
type: integer
format: int64
description: Unix Timestamp in milliseconds (since the epoch) when the attribute was fetched from an external source and associated with the user.
link:
type: string
description: Link to user attribute using JSON pointer syntax.
verification:
type: array
items:
$ref: '#/components/schemas/AttributeVerification'
description: Attribute details as part of a Trustly ID user verification details
title: AttributeVerificationDetail
UserVerificationErrorCode:
type: string
enum:
- '-1'
- '1'
- '2'
- '3'
- '4'
- '5'
- '6'
description: 'An error code indicating why the user verification has failed. May be:
* `-1`: no error. the verification was successful.
* `1`: there was an internal, unspecified error (should not happen).
* `2`: the user is below the minimum age.
* `3`: some of the attributes did not meet the minimum verification criteria.
* `4`: some mandatory attributes are not available.
* `5`: the user was identified as a person who is deceased.
* `6`: entries were matched during the screening process'
title: UserVerificationErrorCode
PaymentProviderSubtype:
type: string
enum:
- '1000'
- '2000'
- '2001'
description: "Payment Provider Subtype:\n * `1000`: EasyOnline\n * `2000`: MEC\n * `2001`: MCD"
title: PaymentProviderSubtype
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
PaymentProvider:
type: object
properties:
paymentProviderId:
type: string
description: A unique identifier for the Payment Provider.
type:
type: number
format: double
name:
type: string
description: Name of the payment provider
instantPayoutAvailable:
type: boolean
description: Whether payment provider supports instant payout.
subType:
$ref: '#/components/schemas/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: '#/components/schemas/Address'
country:
$ref: '#/components/schemas/PaymentProviderCountry'
description: 2-letter ISO country code of the financial institution
instantPayment:
type: boolean
required:
- name
description: Details of the Financial institution
title: PaymentProvider
SegmentedName:
type: object
properties:
title:
type: string
description: The title of a given full name.
firstName:
type: string
description: The first name of a given full name.
middleName:
type: array
items:
type: string
description: The list of middle names of a given full name.
lastName:
type: string
description: The last name of a given full name.
suffix:
type: string
description: The suffix of a given full name.
description: The segmented version of a given name.
title: SegmentedName
PaymentProviderTransactionPaymentProcessor:
type: object
properties:
paymentProcessorId:
type: string
type:
type: integer
name:
type: string
shortName:
type: string
url:
type: string
active:
type: string
titl
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paywithmybank/refs/heads/main/openapi/paywithmybank-identity-api-openapi.yml