{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Access API Principles | Worldpay Developer","description":"Worldpay for Developers - docs, code examples, resources and tools. Everything you need to build your omnichannel payment solution.","siteUrl":"https://docs.worldpay.com/access","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.com/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/**/*"],"excludeFiles":[]},{"title":"Payment Queries API","description":"Querying your payments data, based on a variety of parameters.","includeFiles":["products/payment-queries/@v1/**/*"],"excludeFiles":[]},{"title":"Card BIN Data API","description":"Provides detailed information about a card.","includeFiles":["products/card-bin/@v1/**/*"],"excludeFiles":[]},{"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/**/*"],"excludeFiles":[]},{"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/**/*"],"excludeFiles":[]},{"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/**/*"],"excludeFiles":[]},{"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/**/*"],"excludeFiles":[]},{"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/**/*"],"excludeFiles":[]},{"title":"Card Verifications API","description":"Verify your customer's card to maximize your authentication rates.","includeFiles":["products/card-verifications/@v6/**/*"],"excludeFiles":[]},{"title":"Account Payouts API","description":"Send funds to your customer's bank accounts and search for payouts using parameters.","includeFiles":["products/account-payouts/@20250101/**/*"],"excludeFiles":[]},{"title":"APMs","description":"Pay using eWallets, bank transfers, direct debits, local card schemes, Postpay and eInvoice/ Buy Now Pay Later.","includeFiles":["products/apms/@20240701/**/*"],"excludeFiles":[]},{"title":"Balance API","description":"Request your account details for a single account or all accounts under an entity.","includeFiles":["products/balance/@20250101/**/*"],"excludeFiles":[]},{"title":"Card Payouts API","description":"Send funds to your customer's cards.","includeFiles":["products/card-payouts/@v4/**/*"],"excludeFiles":[]},{"title":"Events (Webhooks)","description":"Receive status updates from Access Worldpay by setting up a webhook.","includeFiles":["products/events/@v1/**/*"],"excludeFiles":[]},{"title":"FX API","description":"Manage Foreign Exchange (FX) on your payments.","includeFiles":["products/fx/@v1/**/*"],"excludeFiles":[]},{"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/**/*"],"excludeFiles":[]},{"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/**/*"],"excludeFiles":[]},{"title":"Parties API","description":"Create parties, manage your payout instruments and beneficial owners and carry out identity verification checks.","includeFiles":["products/parties/@20250101/**/*"],"excludeFiles":[]},{"title":"SCA Exemptions API","description":"Maximize a frictionless checkout experience by using issuer data insights to apply exemptions.","includeFiles":["products/sca-exemptions/@v1/**/*"],"excludeFiles":[]},{"title":"Split Payments API","description":"Divide funds from a single payment amongst yourself and your parties/sellers.","includeFiles":["products/split-payments/@20250625/**/*"],"excludeFiles":[]},{"title":"Statements API","description":"Retrieve your account statement and see individual entries for all credits and debits.","includeFiles":["products/statements/@20250101/**/*"],"excludeFiles":[]},{"title":"Transfers API","description":"Transfer funds from source account to target account.","includeFiles":["products/transfers/@20250101/**/*"],"excludeFiles":[]},{"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/**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"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 are following to create a market-leading API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication-and-identity","__idx":1},"children":["Authentication and identity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We use a single set of basic auth credentials for all our Access APIs. However, we use a different set between the Try (test) and Live environment."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For clientside SDKs, we create a public ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkout Id"]}," that is mapped to your accounts API credentials. With this, we initialize the SDK."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"openapi-schema--discovery","__idx":2},"children":["OpenAPI schema / Discovery"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every API has a schema available in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.openapis.org/"},"children":["OpenAPI"]}," format using version 3.0.1+, this is linted (checked) for syntax accuracy automatically. If you spot any inaccuracies, you can flag it, using the page comment tool (thumbs up/down) that is on every page."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Discovery for older services was originally handled by first querying the root resource. This is no longer necessary and we are slowly phasing it out as new breaking API versions are introduced. Our service URIs are stable and unlikely to change. A direct call simplifies the integration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"versioning","__idx":3},"children":["Versioning"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We're migrating APIs to a new way of setting the version. Therefore you will see a different approach depending on the APIs you're using."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"latest-standard","__idx":4},"children":["Latest standard"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["New or updated APIs such as ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/payments/"},"children":["Payments"]}," or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/apms/"},"children":["APMs"]}," use:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["version header ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WP-Api-Version"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a date e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2024-06-01"]}," indicating the initial release or latest ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#breaking--non-breaking-changes"},"children":["breaking version"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The Content-Type for these APIs is also simply ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"previous-standard","__idx":5},"children":["Previous standard"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For APIs that have yet to be updated to the newer standards (e.g. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/card-payments/"},"children":["Card Payments"]}," / ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/3ds/"},"children":["3DS"]},") the Media Type is used to specify the version e.g.:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type: application/vnd.worldpay.fraudsight-v1.hal+json"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"breaking-and-non-breaking-changes","__idx":6},"children":["Breaking and non-breaking changes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For changes that alter the existing behavior, resource names, objects or key:values, a new API version is required, these are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["breaking changes"]},". This could be a new feature that, with the existing API design, is not possible or a new API standard that needs adopting across APIs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are various cases where an API will change but it is considered ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["non-breaking"]},". For example, introducing new key:values is not considered breaking as your application code should only be checking for the values it was originally integrated against. Your integration must be resilient enough to handle these being introduced."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"more-examples-of-non-breaking-changes","__idx":7},"children":["More examples of non-breaking changes:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"in-responses","__idx":8},"children":["In responses:"]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["Changing URIs/URIS and their FQDNs/paths"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The structure and length of a URI/ URI including the Fully Qualified Domain Name (FQDN) and their path might change."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"_links\": {\n        \"service:action\": {\n            \"href\": \"https://access.worldpay.com/service/action\"\n        },\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["or"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"_links\": {\n        \"service:action\": {\n            \"href\": \"https://api.access.worldpay.com/api/process\"\n        },\n"},"children":[]}]},{"$$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"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A new object or new attributes within an object are now included in your response."]},{"$$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"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Additional action links and URI resources are now returned within your response."]},{"$$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.com/service/action1\"\n        },\n        \"service:action2\": {\n            \"href\": \"https://access.worldpay.com/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.com/service/action1\"\n        },\n        \"service:action2\": {\n            \"href\": \"https://access.worldpay.com/service/action2\"\n        },\n        \"service:action3\": {\n            \"href\": \"https://access.worldpay.com/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":"b","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":"b","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":4,"id":"in-requests","__idx":9},"children":["In requests"]},{"$$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":"b","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":"Heading","attributes":{"level":2,"id":"type-of-integration","__idx":10},"children":["Type of integration"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Modular"]}," - APIs with a single distinct purpose. For example, 3DS authentication, create and manage tokens. You could use these:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["to create custom/complex payments flow - e.g. 3DS authentication with a long gap before the payment"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["as a gateway agnostic fraud assessment or 3DS authentication for use with multiple 3rd party payment gateways"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Orchestrated"]}," - To simplify the integration we wrap various modular APIs to form common journeys. Our ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/payments/"},"children":["Payments API"]}," is the main example of this, allowing risk assessment, 3DS authentication, token creation and the card payment itself to be conducted in a single API."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"consistent-language","__idx":11},"children":["Consistent language"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Focusing on making our APIs as easy to integrate and use, the language across different services is aiming to be the same. This ensures learnability, usability and quick integration."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["billingAddress"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}," key:value on one API should be the same as another when used in the same context. Where it's not currently, these will be updated in a future new API version."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-action-links","__idx":12},"children":["Next action links"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Whilst not strictly supporting HAL (Hypertext Application Language) we take some of the elements of it to make the actions you could perform next clear."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As with versioning you will see a different approach depending on the APIs you're using."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"latest-standard-1","__idx":13},"children":["Latest standard"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Uses a combination of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_link"]}," mostly for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["self"]}," querying"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_actions"]}," for the next possible steps you could take (e.g. cancel a payment)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n\"_links\": {\n    \"self\": {\n        \"href\": \"https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D\"\n    }\n},\n\"_actions\": {\n    \"cancelPayment\": {\n        \"href\": \"https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D/cancellations\",\n        \"method\": \"POST\"\n    }\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"previous-standard-1","__idx":14},"children":["Previous standard"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Contains only the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_links"]}," object"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Also contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_curies"]}," for accessing the schema of a given resource. Phased out in favour of OpenAPI schema."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"_links\": {\n        \"cardPayments:cancel\": {\n            \"href\": \"https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiI=\"\n        },\n        \"cardPayments:settle\": {\n            \"href\": \"https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiI=\"\n        },\n        \"cardPayments:partialSettle\": {\n            \"href\": \"https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazNhYjYzMiI=\"\n        },\n        \"cardPayments:events\": {\n            \"href\": \"https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiI=\"\n        },\n        \"curies\": [\n            {\n                \"name\": \"cardPayments\",\n                \"href\": \"https://try.access.worldpay.com/rels/cardPayments/{rel}\",\n                \"templated\": true\n    }\n  }\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The links themselves can be either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["static"]}," to simply inform you of the next possible action or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dynamic"]}," so as to embed/contain details to be used in the next action and are therefore unique to an individual transaction."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The maximum length of the encrypted action link data, excluding the base URL, will be up to 1024 characters."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"logging-for-support-purposes","__idx":15},"children":["Logging for support purposes"]},{"$$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":"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":"Authentication and identity","id":"authentication-and-identity","depth":2},{"value":"OpenAPI schema / Discovery","id":"openapi-schema--discovery","depth":2},{"value":"Versioning","id":"versioning","depth":2},{"value":"Latest standard","id":"latest-standard","depth":3},{"value":"Previous standard","id":"previous-standard","depth":3},{"value":"Breaking and non-breaking changes","id":"breaking-and-non-breaking-changes","depth":2},{"value":"More examples of non-breaking changes:","id":"more-examples-of-non-breaking-changes","depth":3},{"value":"In responses:","id":"in-responses","depth":4},{"value":"In requests","id":"in-requests","depth":4},{"value":"Type of integration","id":"type-of-integration","depth":2},{"value":"Consistent language","id":"consistent-language","depth":2},{"value":"Next action links","id":"next-action-links","depth":2},{"value":"Latest standard","id":"latest-standard-1","depth":4},{"value":"Previous standard","id":"previous-standard-1","depth":4},{"value":"Logging for support purposes","id":"logging-for-support-purposes","depth":2}],"frontmatter":{"seo":{"title":"Access API Principles | Worldpay Developer"},"sidebar":{"path":"../../../sidebars.yaml"}},"lastModified":"2026-02-13T11:40:37.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/reference/api-principles","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}