{"templateId":"markdown","sharedDataIds":{},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"API principles","description":"Worldpay for Developers - docs, code examples, resources and tools. Everything you need to build your omnichannel payment solution.","siteUrl":"https://docs.worldpay-bsh.securedataplatform.co.uk","image":"/access/assets/worldpay-logo-light.21b7daf79984773a9fcd7d4fbcb07ae5289dfffd6023c4c3dca720c7058e53dc.33f780a6.svg","keywords":"documentation, api, openapi, sdks, developer, payments, json, payouts, 3ds","jsonLd":{"@context":"https://schema.org","@type":"Organization","url":"https://docs.worldpay-bsh.securedataplatform.co.uk/access","name":"Worldpay"},"meta":[{"name":"google-site-verification","content":"zjziIKaP3ImsqsfhYnEBnq1R85UabiSwl7HTXuwtZuo"},{"name":"doc_product","content":"Access"},{"name":"doc_category","content":"Documentation"}],"llmstxt":{"hide":false,"sections":[{"title":"Payments API","description":"Payment orchestration API combining fraud assessment, 3ds authentication, SCA exemptions, Worldpay Token creation and a card or wallet based payment.","includeFiles":["products/payments/@20240601/**/*"]},{"title":"Payment Queries API","description":"Querying your payments data, based on a variety of parameters.","includeFiles":["products/payment-queries/@v1/**/*"]},{"title":"Card BIN Data API","description":"Provides detailed information about a card.","includeFiles":["products/card-bin/@v1/**/*"]},{"title":"3DS Authentication API","description":"Request 3DS authentication to protect against fraud, be SCA compliant and to shift liability using this standalone API.","includeFiles":["products/3ds/@v3/**/*"]},{"title":"FraudSight API","description":"Request a risk assessment and receive a response with an outcome (e.g. lowRisk) using this standalone API.","includeFiles":["products/fraudsight/@v1/**/*"]},{"title":"Checkout SDK","description":"Integrate using our clientside SDKs for both web and native devices. Benefit from SAQ-A/PCI-SSF compliance.","includeFiles":["products/checkout/web/@v2/**/*","products/checkout/ios/@v4/**/*","products/checkout/android/@v4/**/*","products/checkout/react-native/@v3/**/*","products/checkout/flutter/@v1/**/*"]},{"title":"Tokens API","description":"Minimizes the exposure of sensitive card details and increases the security of your customer's card details.","includeFiles":["products/tokens/@v3/**/*"]},{"title":"Card Payments API","description":"Request a card payment using this standalone API, requires separate requests for 3DS, Fraud assessment etc.","includeFiles":["products/card-payments/@v7/**/*"]},{"title":"Card Verifications API","description":"Verify your customer's card to maximize your authentication rates.","includeFiles":["products/card-verifications/@v6/**/*"]},{"title":"Account Payouts API","description":"Send funds to your customer's bank accounts and search for payouts using parameters.","includeFiles":["products/account-payouts/@20250101/**/*"]},{"title":"APMs","description":"Pay using eWallets, bank transfers, direct debits, local card schemes, Postpay and eInvoice/ Buy Now Pay Later.","includeFiles":["products/apms/@20240701/**/*"]},{"title":"Balance API","description":"Request your account details for a single account or all accounts under an entity.","includeFiles":["products/balance/@20250101/**/*"]},{"title":"Card Payouts API","description":"Send funds to your customer's cards.","includeFiles":["products/card-payouts/@v4/**/*"]},{"title":"Events (Webhooks)","description":"Receive status updates from Access Worldpay by setting up a webhook.","includeFiles":["products/events/@v1/**/*"]},{"title":"FX API","description":"Manage Foreign Exchange (FX) on your payments.","includeFiles":["products/fx/@v1/**/*"]},{"title":"Hosted Payment Pages (HPP) API","description":"Our low-code option to take payments securely at the lowest PCI compliance level - SAQ A.","includeFiles":["products/hosted-payment-pages/@v1/**/*"]},{"title":"Money Transfers API","description":"Money Transfer OCTs (Original Credit Transaction) allow funds to be pushed to an eligible card in 30 minutes or less.","includeFiles":["products/money-transfers/@v1/**/*"]},{"title":"Parties API","description":"Create parties, manage your payout instruments and beneficial owners and carry out identity verification checks.","includeFiles":["products/parties/@20250101/**/*"]},{"title":"SCA Exemptions API","description":"Maximize a frictionless checkout experience by using issuer data insights to apply exemptions.","includeFiles":["products/sca-exemptions/@v1/**/*"]},{"title":"Split Payments API","description":"Divide funds from a single payment amongst yourself and your parties/sellers.","includeFiles":["products/split-payments/@20250625/**/*"]},{"title":"Statements API","description":"Retrieve your account statement and see individual entries for all credits and debits.","includeFiles":["products/statements/@20250101/**/*"]},{"title":"Transfers API","description":"Transfer funds from source account to target account.","includeFiles":["products/transfers/@20250101/**/*"]},{"title":"Verified Tokens API","description":"Verified Tokens ensures that your customer's payment details are valid and CIT compliant when creating a token.","includeFiles":["products/verified-tokens/@v3/**/*"]}]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"api-principles","__idx":0},"children":["API principles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section gives you an overview of the standards we follow to create market-leading APIs."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"api-overview","__idx":1},"children":["API overview"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Hypertext Application Language (HAL) for learnability"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["HAL defines the format of the APIs resources and links. It makes hyperlinking between API resources consistent and easy. It allows you to interlink our different APIs for a more consumable and explorable experience."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["HAL is both machine and human readable; an advantage that means you can get context from API Reference."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We follow this convention to structure our resource and action links so you can use them with standard libraries."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Media types to control API version usage"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The media type specifies the nature and format of the JSON file. It defines how the file should be processed. The formatting of your request must meet the standard or the request is not accepted."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Our media type is defined in our ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type"]}," header, it defines the API version and is standardized across our APIs."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Content-Type: application/vnd.worldpay.verifiedpayments-v1.hal+json\n"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"best-practice","__idx":2},"children":["Best practice"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Access Worldpay returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WP-CorrelationId"]}," in the headers of service responses. We ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["highly recommend"]}," you log this. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WP-CorrelationId"]}," is used by us to examine individual service requests."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"why-do-you-release-new-api-versions","__idx":3},"children":["Why do you release new API versions?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To introduce new features in our APIs, which may introduce a breaking change."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"does-a-new-api-version-always-introduce-a-breaking-change","__idx":4},"children":["Does a new API version always introduce a breaking change?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Generally yes, we may introduce a new parameter in a request that is not recognized in the previous version of the API."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"are-the-versions-backward-compatible","__idx":5},"children":["Are the versions backward compatible?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No, each version may accept a different schema."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"non-breaking-change-definition","__idx":6},"children":["Non-breaking change definition"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To ensure resilience when integrating into any of our Access APIs, you must consider that Worldpay might make the following changes without moving to another version:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"in-responses","__idx":7},"children":["In responses:"]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["Reordering elements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Elements within the response body can be sent in any order."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"apple\": \"gala\",\n    \"pear\": \"conference\"\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["or"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"pear\": \"conference\",\n    \"apple\": \"gala\"\n}\n"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["New elements"]},"\nA new element is now included in your response.\n",{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"apple\": \"gala\",\n    \"pear\": \"conference\"\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"apple\": \"gala\",\n    \"pear\": \"conference\",\n    \"melon\": \"honeydew\"\n}\n"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["New links and relationship types"]},"\nAdditional action links and URI resources are now returned within your response.\n",{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"_links\": {\n        \"service:action1\": {\n            \"href\": \"https://access.worldpay-bsh.securedataplatform.co.uk/service/action1\"\n        },\n        \"service:action2\": {\n            \"href\": \"https://access.worldpay-bsh.securedataplatform.co.uk/service/action2\"\n        }\n    }\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"_links\": {\n        \"service:action1\": {\n            \"href\": \"https://access.worldpay-bsh.securedataplatform.co.uk/service/action1\"\n        },\n        \"service:action2\": {\n            \"href\": \"https://access.worldpay-bsh.securedataplatform.co.uk/service/action2\"\n        },\n        \"service:action3\": {\n            \"href\": \"https://access.worldpay-bsh.securedataplatform.co.uk/service/action3\"\n        }\n    }\n}\n"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["New enumerate errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Additional ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/reference/worldpay-error-responses"},"children":["errors"]}," may be added when ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["new features"]}," warrant a new error condition. Additional ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/reference/worldpay-error-responses#field-validation-errors"},"children":["validation errors"]}," may be added if new optional elements are added to the request."]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["New HTTP error codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Additional ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/reference/worldpay-error-responses#top-level-errors"},"children":["HTTP error codes"]}," may be added when ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["new features"]}," warrant a new error condition."]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["New headers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A new HTTP header is now added to our response."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"in-requests","__idx":8},"children":["In requests"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sending any elements not recorded in our documentation will return an error."]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["Reordering elements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Elements within the request body can be sent in any order."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"apple\": \"gala\",\n    \"pear\": \"conference\"\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["or"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"pear\": \"conference\",\n    \"apple\": \"gala\"\n}\n"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["New optional elements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["New elements that are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not mandatory"]}," can now be sent. For example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchant.mcc"]}," in our Payments API or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," in our Tokens API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"apple\": \"gala\",\n    \"pear\": \"conference\"\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"apple\": \"gala\",\n    \"pear\": \"conference\",\n    \"melon\": \"honeydew\"\n}\n"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["Increase in element value size"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The value of an element now allows for an increased number of characters."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"phrase\": \"the quick brown fox\"\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"phrase\": \"the quick brown fox jumps over the lazy dog\"\n}\n"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["Increase in format/scope of an element value"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Changes in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/reference/formatting"},"children":["validation rules"]}," mean that requests which previously resulted in an error may now not."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A \"time\" value which previously allowed only hours and minutes, now also optionally allows seconds."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"time\": \"11:50\"\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"time\": \"11:50:59\"\n}\n"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["Increase in range values"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We may expand the range of values we accept. This means requests that previously resulted in a validation error may now succeed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, previously allowed range value was 10-50. New range is 10-100."]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["New enumerate values"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Element value options have now increased."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Previously allowed value options are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apple"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pear"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["melon"]},". You could now also submit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mango"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"fruit\": \"apple\"\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"fruit\": \"mango\"\n}\n"},"children":[]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For any changes that fall outside the above definition, Worldpay creates a new version. Go to our ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/reference/formatting"},"children":["formatting page"]}," for current standards."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You should now familiarize yourself with our ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/reference/security"},"children":["security best practices"]},"."]}]},"headings":[{"value":"API principles","id":"api-principles","depth":1},{"value":"API overview","id":"api-overview","depth":3},{"value":"Best practice","id":"best-practice","depth":3},{"value":"Why do you release new API versions?","id":"why-do-you-release-new-api-versions","depth":4},{"value":"Does a new API version always introduce a breaking change?","id":"does-a-new-api-version-always-introduce-a-breaking-change","depth":4},{"value":"Are the versions backward compatible?","id":"are-the-versions-backward-compatible","depth":4},{"value":"Non-breaking change definition","id":"non-breaking-change-definition","depth":2},{"value":"In responses:","id":"in-responses","depth":3},{"value":"In requests","id":"in-requests","depth":3}],"frontmatter":{"seo":{"title":"API principles"}},"lastModified":"2025-09-22T09:15:26.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/reference/api-principles/non-breaking-definition","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}