{ "openapi" : "3.1.0", "info" : { "title" : "Open Banking API", "description" : "The Open Banking API provides secure endpoints to share financial data and services with third parties. This API offers quick and reliable user verification.\n\nWith these endpoints, you can:\n\n- **Create a list of available account verification routes**: Create a list of Account Information Service Providers (AISPs) for third-party individual account verification. Successful connections generate a unique code used for requesting bank reports and verifying identity.\n- **Verify bank account ownership**: Get the account verification report using the unique code from a successful open banking connection. This report provides identity verification and bank account details.\n## Authentication\nEach request made to the Open Banking API must be signed with an API key. Generate an API key in your Customer Area.\n\nTo connect to the API, add an X-API-Keyheader with the API key as the value, for example:\n\n ```\ncurl\n-H \"Content-Type: application/json\" \n-H \"X-API-Key: YOUR_API_KEY\" \n...\n```\n\n## Roles and permissions\nTo use the Open Banking API, your API credential must have the following roles:\n- **Role for OpenBanking account verification use case: EXTERNAL**\n\nReach out to your Adyen contact to set up these roles.\n", "termsOfService" : "https://www.adyen.com/legal/terms-and-conditions", "contact" : { "name" : "Adyen Developer Experience team", "url" : "https://github.com/Adyen/adyen-openapi" }, "version" : "1" }, "servers" : [ { "url" : "https://obgateway-test.adyen.com/obgateway/v1", "description" : "Test Environment" }, { "url" : "https://obgateway-live.adyen.com/obgateway/v1", "description" : "Live Environment" } ], "tags" : [ { "name" : "Account Verification", "x-groupIndex" : 1 } ], "paths" : { "/accountVerification/reports/{code}" : { "get" : { "tags" : [ "Account Verification" ], "summary" : "Get account verification report", "description" : "Get the account verification report using a unique code from a successful open banking connection. This report provides identity verification and bank account details.", "operationId" : "get-accountVerification-reports-code", "parameters" : [ { "name" : "code", "in" : "path", "description" : "The unique code you receive after a successful open banking flow that is included as a query parameter in the `redirectUrl` callback.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "minLength" : 1 } } ], "responses" : { "200" : { "description" : "OK - The request has succeeded.", "headers" : { "X-State" : { "style" : "simple", "explode" : false, "schema" : { "description" : "The state provided in the routes generation request.", "example" : "123A-456B-789C-10D" } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AccountVerificationReportResponse" }, "examples" : { "Account verification report (ACH)" : { "summary" : "Account verification report for an ACH account", "description" : "Provides a detailed report of verified ACH account.", "value" : { "id" : "nJwJE68h6vlSEnk", "country" : "US", "accounts" : [ { "accountId" : "XvNzLGMpl3fBevllWEwks3jvBvPy88sbkypkP", "accountType" : "CURRENT", "accountName" : "Plaid Gold Standard 0% Interest Checking", "accountNumber" : "1111222233330000", "currency" : "USD", "identifiers" : { "ach" : { "accountNumber" : "1111222233330000", "routingNumber" : "011401533" } }, "parties" : [ { "identity" : { "fullLegalName" : "Jane Doe", "name" : "Jane Doe" }, "role" : "HOLDER" } ], "bankName" : "Wells Fargo" }, { "accountId" : "XvNzLGMpl3fBevllWEwks3jvBvPy88sbkypkP", "accountType" : "CURRENT", "accountName" : "Plaid Gold Standard 0% Interest Checking", "accountNumber" : "3333222211110000", "currency" : "USD", "identifiers" : { "ach" : { "accountNumber" : "3333222211110000", "routingNumber" : "033587521" } }, "parties" : [ { "identity" : { "fullLegalName" : "Jane Doe", "name" : "Jane Doe" }, "role" : "HOLDER" } ], "bankName" : "Bank of America" } ] } }, "Account verification report (BSB)" : { "summary" : "Account verification report for a BSB account", "description" : "Provides a detailed report of verified BSB account.", "value" : { "id" : "lkumovjdFQFy6JhbSaWTa8sCH79fzJJnFMKpkSST09ism2lCMlsnSEsrjx6XNr4u_kxhSg==", "country" : "AU", "accounts" : [ { "accountId" : "lkumovjdFQFy6JhbSaWTa8sCH79fzJJnFMKpkSST09ism2lCMlsnSEsrjx6XNr4u_kxhSg==", "accountType" : "UNKNOWN", "accountName" : "Savings Account", "accountNumber" : "37458052", "currency" : "AUD", "identifiers" : { "bsb" : { "accountNumber" : "37458052", "bsbCode" : "413574" } }, "parties" : [ { "identity" : { "fullLegalName" : "Peter Sherman", "name" : "Peter" }, "role" : "HOLDER" } ], "bankName" : "Banking Sandbox Data Holder" } ] } }, "Account verification report (EFT)" : { "summary" : "Account verification report for an EFT account", "description" : "Provides a detailed report of verified EFT account.", "value" : { "id" : "69ee9452ef824fe092f1417f37535755", "country" : "CA", "accounts" : [ { "accountId" : "th7681t6j876930300478t246534j8fi", "accountType" : "CURRENT", "accountName" : "Checking Account 1", "accountNumber" : "111122220000", "currency" : "CAD", "identifiers" : { "eft" : { "accountNumber" : "111122220000", "branch" : "01533", "institution" : "114" } }, "parties" : [ { "identity" : { "fullLegalName" : "Jessie Dean", "name" : "Jessie Dean" }, "role" : "HOLDER" } ], "bankName" : "Plaid Demo Bank" } ] } }, "Account verification report (IBAN)" : { "summary" : "Account verification report for an IBAN account", "description" : "Provides a detailed report of verified IBAN account.", "value" : { "id" : "69ee9452ef824fe092f1417f37535755", "country" : "ES", "accounts" : [ { "accountId" : "ed5080e4f485430290475d246534c8fd", "accountType" : "CURRENT", "accountName" : "Checking Account 1", "accountNumber" : "ES1376230223254275408743", "currency" : "EUR", "identifiers" : { "iban" : { "iban" : "ES1376230223254275408743", "bban" : "76230223254275408743", "bic" : "BIC001" } }, "parties" : [ { "identity" : { "fullLegalName" : "Alberta Bobbeth Charleson", "name" : "Alberta Bobbeth Charleson" }, "role" : "HOLDER" } ], "bankName" : "Tink Demo Bank" } ] } } } } } }, "400" : { "description" : "Bad Request - The request is malformed or is not in the expected format.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } }, "401" : { "description" : "Unauthorized - The API credential used in the request is invalid or does not have the right permissions.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } }, "404" : { "description" : "Not Found - The entity was not found.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } }, "422" : { "description" : "Unprocessable Entity - A request validation error.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } }, "429" : { "description" : "Too Many Requests - Request rate limit exceeded.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } }, "500" : { "description" : "Internal Service Error - An unrecoverable error occurred while trying to perform the request.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } } }, "x-methodName" : "getAccountVerificationReport", "x-sortIndex" : 2 } }, "/accountVerification/routes" : { "post" : { "tags" : [ "Account Verification" ], "summary" : "Create routes for account verification", "description" : "Create a list of routes for verifying bank accounts of third-party individuals. Successful connections generate a unique code used for requesting bank reports and verifying identity.", "operationId" : "post-accountVerification-routes", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AccountVerificationRoutesRequest" }, "examples" : { "Account verification routes request" : { "summary" : "List AISP Routes for account verification", "description" : "Specifies the country, locale, state, and redirect URL to initiate the account verification process and receive available bank routes.", "value" : { "country" : "NL", "locale" : "en-US", "state" : "11a1e60a-18b0-4dda-9258-e0ae29e1e2a3", "redirectUrl" : "https://merchanturl.example.org/redirect/url" } } } } }, "required" : true }, "responses" : { "200" : { "description" : "OK - The request has succeeded.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AccountVerificationRoutesResponse" }, "examples" : { "Account verification routes response" : { "summary" : "Response detailing available bank routes for account verification", "description" : "Returns a list of bank providers available for account verification in the specified country, along with their respective redirection URLs to initiate the authentication flow.", "value" : { "routes" : [ { "provider" : { "name" : "Tink", "logoURL" : "https://obgateway.adyen.com/obgateway/static/provider/images/tink-logo.svg" }, "link" : "https://obgateway.adyen.com/obgateway/provider/outgoing/tink/redirect/13ec4802-c987-4f8c-8909-9a75ff567256" } ] } } } } } }, "400" : { "description" : "Bad Request - The request is malformed or is not in the expected format.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } }, "401" : { "description" : "Unauthorized - The API credential used in the request is invalid or does not have the right permissions.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } }, "422" : { "description" : "Unprocessable Entity - A request validation error.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } }, "429" : { "description" : "Too Many Requests - Request rate limit exceeded.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } }, "500" : { "description" : "Internal Service Error - An unrecoverable error occurred while trying to perform the request.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } } }, "x-methodName" : "createAccountVerificationRoutes", "x-sortIndex" : 1 } } }, "components" : { "schemas" : { "ACHAccountIdentifier" : { "type" : "object", "properties" : { "accountLastDigits" : { "type" : "string", "description" : "The last digits of the account number. If the accountNumber is tokenized, this field contains the last digits of the non-tokenized account number. This helps users verify the account without seeing the full number." }, "accountNumber" : { "type" : "string", "description" : "The account number of the bank account." }, "isTokenized" : { "type" : "boolean", "description" : "Indicates whether the account number is tokenized. A tokenized account number is a unique ID generated by a bank to protect the user's actual account number." }, "routingNumber" : { "type" : "string", "description" : "The [routing number](https://en.wikipedia.org/wiki/ABA_routing_transit_number), without separators or whitespace." } }, "required" : [ "accountNumber", "routingNumber" ] }, "AccountIdentifiers" : { "type" : "object", "properties" : { "ach" : { "$ref" : "#/components/schemas/ACHAccountIdentifier", "description" : "Identifiers relevant for Automated Clearing House (ACH) payments, primarily used in the United States." }, "bacs" : { "$ref" : "#/components/schemas/BACSAccountIdentifier", "description" : "Identifiers relevant for Bankers' Automated Clearing Services (BACS) payments, primarily used in the United Kingdom." }, "bsb" : { "$ref" : "#/components/schemas/BSBAccountIdentifier", "description" : "Identifiers relevant for Australian banking, specifically for BSB (Bank-State-Branch) numbers." }, "eft" : { "$ref" : "#/components/schemas/EFTAccountIdentifier", "description" : "Identifiers relevant for Electronic Funds Transfer (EFT) payments, commonly used in Canada." }, "iban" : { "$ref" : "#/components/schemas/IBANAccountIdentifier", "description" : "The international bank account number as defined in the ISO-13616 standard." }, "rix" : { "$ref" : "#/components/schemas/RIXAccountIdentifier", "description" : "Identifiers relevant for the Rix (Russian Interbank eXchange) system, used for interbank payments within Russia." } } }, "AccountParty" : { "type" : "object", "properties" : { "identity" : { "$ref" : "#/components/schemas/Identity", "description" : "Contains the identity details of the party." }, "role" : { "$ref" : "#/components/schemas/PartyRole", "description" : "Specifies a role or capacity of the party in relation to the bank account." } }, "required" : [ "identity", "role" ] }, "AccountType" : { "type" : "string", "enum" : [ "CURRENT", "SAVINGS", "BUSINESS", "CREDIT_CARD", "LOAN", "UNKNOWN" ] }, "AccountVerificationCountry" : { "type" : "string", "enum" : [ "SE", "FI", "NO", "DK", "NL", "IT", "DE", "AT", "ES", "PT", "FR", "GB", "BE", "LV", "LT", "PL", "EE", "IE", "US", "CA", "AU" ] }, "AccountVerificationReportResponse" : { "type" : "object", "properties" : { "accounts" : { "type" : "array", "description" : "A list of bank accounts with their respective information.", "items" : { "$ref" : "#/components/schemas/VerifiedAccount" } }, "country" : { "$ref" : "#/components/schemas/AccountVerificationCountry", "description" : "The location where the third-party individual's bank account is registered." }, "id" : { "type" : "string", "description" : "The unique identifier for the specific report." } }, "required" : [ "accounts", "country", "id" ] }, "AccountVerificationRoutesRequest" : { "type" : "object", "properties" : { "country" : { "$ref" : "#/components/schemas/AccountVerificationCountry", "description" : "The location where the third-party individual's bank account is registered. Adyen uses this information to determine an available open banking provider, and to configure the open banking flow for that respective location." }, "locale" : { "type" : "string", "description" : "The language to use in the open banking flow UI, specified by a combination of a two-letter [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) language code and an [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.\n\nThis information is used to configure the open banking flow with the same language for a consistent user experience.\n\nDefault value: **en-US**" }, "redirectUrl" : { "type" : "string", "format" : "url", "description" : "The URL where Adyen redirects the third-party individual after they complete the open banking flow." }, "state" : { "type" : "string", "description" : "A value that helps you identify the request in callback handling. You can generate this value on a per-session basis to protect the callback against Cross-Site Request Forgery (CSRF) attacks. This value must be composed of characters that can be successfully URL-encoded." } }, "required" : [ "country", "redirectUrl" ] }, "AccountVerificationRoutesResponse" : { "type" : "object", "properties" : { "routes" : { "type" : "array", "description" : "This array lists available open banking redirection links, each with its associated provider metadata.", "items" : { "$ref" : "#/components/schemas/Route" } } }, "required" : [ "routes" ] }, "BACSAccountIdentifier" : { "type" : "object", "properties" : { "accountNumber" : { "type" : "string", "description" : "The account number of the bank account." }, "sortCode" : { "type" : "string", "description" : "A number that identifies the specific bank and branch where a UK bank account is held." } }, "required" : [ "accountNumber", "sortCode" ] }, "BSBAccountIdentifier" : { "type" : "object", "properties" : { "accountNumber" : { "type" : "string", "description" : "The account number of the bank account." }, "bsbCode" : { "type" : "string", "description" : "The BSB (Bank-State-Branch) code." } }, "required" : [ "accountNumber", "bsbCode" ] }, "DefaultErrorResponseEntity" : { "type" : "object", "description" : "Standardized error response following RFC-7807 format", "externalDocs" : { "url" : "https://www.rfc-editor.org/rfc/rfc7807" }, "properties" : { "detail" : { "type" : "string", "description" : "A human-readable explanation specific to this occurrence of the problem." }, "errorCode" : { "type" : "string", "description" : "Unique business error code." }, "instance" : { "type" : "string", "description" : "A URI that identifies the specific occurrence of the problem if applicable." }, "invalidFields" : { "type" : "array", "description" : "Array of fields with validation errors when applicable.", "items" : { "$ref" : "#/components/schemas/InvalidField" } }, "requestId" : { "type" : "string", "description" : "The unique reference for the request." }, "status" : { "type" : "integer", "format" : "int32", "description" : "The HTTP status code." }, "title" : { "type" : "string", "description" : "A short, human-readable summary of the problem type." }, "type" : { "type" : "string", "description" : "A URI that identifies the validation error type. It points to human-readable documentation for the problem type." } } }, "EFTAccountIdentifier" : { "type" : "object", "properties" : { "accountNumber" : { "type" : "string", "description" : "The account number of the bank account." }, "branch" : { "type" : "string", "description" : "Identifies the specific branch where the account is held within the Canadian banking system." }, "institution" : { "type" : "string", "description" : "The financial institution that identifies the bank in Canada." } }, "required" : [ "accountNumber", "branch", "institution" ] }, "IBANAccountIdentifier" : { "type" : "object", "properties" : { "bban" : { "type" : "string", "description" : "The Basic Bank Account Number (BBAN) component of the IBAN." }, "bic" : { "type" : "string", "description" : "BIC of a bank account." }, "iban" : { "type" : "string", "description" : "The international bank account number as defined in the [ISO-13616](https://www.iso.org/standard/81090.html) standard. This is the national identifier for the bank account, following the country-specific format, and is part of the full IBAN." } }, "required" : [ "bban", "bic", "iban" ] }, "Identity" : { "type" : "object", "properties" : { "fullLegalName" : { "type" : "string", "description" : "The complete legal name of the individual or entity." }, "name" : { "type" : "string", "description" : "A commonly used or human-readable name for the individual or entity." } }, "required" : [ "fullLegalName", "name" ] }, "InvalidField" : { "type" : "object", "properties" : { "message" : { "type" : "string", "description" : "Description of the validation error." }, "name" : { "type" : "string", "description" : "The field that has an invalid value." }, "value" : { "type" : "string", "description" : "The invalid value." } }, "required" : [ "message", "name", "value" ] }, "PartyRole" : { "type" : "string", "enum" : [ "HOLDER", "AUTHORIZED_USER", "OTHER", "UNKNOWN" ] }, "Provider" : { "type" : "object", "properties" : { "logoURL" : { "type" : "string", "description" : "The URL of the organization's or brand's logo. This URL typically points to an image file (e.g., .png, .jpg, .svg) that can be displayed to visually represent the entity.", "minLength" : 1 }, "name" : { "type" : "string", "description" : "The official or commonly used name of the organization, brand, or entity.", "minLength" : 1 } }, "required" : [ "logoURL", "name" ] }, "RIXAccountIdentifier" : { "type" : "object", "properties" : { "accountNumber" : { "type" : "string", "description" : "The account number of the bank account." }, "clearingNumber" : { "type" : "string", "description" : "The 4- to 5-digit clearing number, without separators or whitespace." } }, "required" : [ "accountNumber", "clearingNumber" ] }, "Route" : { "type" : "object", "properties" : { "link" : { "type" : "string", "description" : "The redirection link. You can use this link to redirect the user to the open banking flow when the user selects it.", "minLength" : 1 }, "provider" : { "$ref" : "#/components/schemas/Provider", "description" : "Metadata about the selected provider, including the name and company logo. You can use this information to inform the user about the provider they will be redirected to when they select the link." } }, "required" : [ "link", "provider" ] }, "VerifiedAccount" : { "type" : "object", "properties" : { "accountId" : { "type" : "string", "description" : "The unique identifier for the bank account." }, "accountName" : { "type" : "string", "description" : "The name of the bank account. This name is assigned by the banking institution, and it describes the type of bank account." }, "accountNumber" : { "type" : "string", "description" : "The account number of the bank account." }, "accountType" : { "$ref" : "#/components/schemas/AccountType", "description" : "The type of the bank account. Possible values are **CURRENT**, **SAVINGS**, **BUSINESS**, **CREDIT_CARD**, **LOAN**, **UNKNOWN**." }, "bankName" : { "type" : "string", "description" : "The name of the banking institution where the bank account is held." }, "currency" : { "type" : "string", "description" : "The currency of the funds in the bank account." }, "identifiers" : { "$ref" : "#/components/schemas/AccountIdentifiers", "description" : "Contains various codes and details used to uniquely identify the bank account across different regions." }, "parties" : { "type" : "array", "description" : "Contains details of all parties associated with the report.", "items" : { "$ref" : "#/components/schemas/AccountParty" } } }, "required" : [ "accountId", "accountName", "accountNumber", "accountType", "currency", "identifiers", "parties" ] } }, "securitySchemes" : { "ApiKeyAuth" : { "type" : "apiKey", "name" : "X-API-Key", "in" : "header" }, "BasicAuth" : { "type" : "http", "scheme" : "basic" } } }, "jsonSchemaDialect" : "https://spec.openapis.org/oas/3.1/dialect/base" }