{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/product/issue-cards/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","img","example-box","fields","field"]},"type":"markdown"},"seo":{"title":"Relayed Authorisation: Approve or decline card transactions in real time","siteUrl":"https://docs.wise.com","projectTitle":"Wise Platform","description":"Wise Platform offer domestic and cross-border payments tools for technology platforms, banks and financial institutions.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"relayed-authorisation","__idx":0},"children":["Relayed authorisation"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Please contact your Wise sales team to use this feature"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Relayed authorisation allows partners to approve or decline card transactions in real time. By forwarding authorisation requests directly to the partner, Wise enables partners to decide instantly using their own internal fraud engines or spend controls."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This feature is optional. By default, Wise manages authorisations based on your pre-configured ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/spend-controls"},"children":["spend controls"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/spend-limits"},"children":["limits"]},". Once enabled, Wise forwards authorisation requests directly to you for real-time decisioning. To configure and activate this service, please reach out to our implementation team."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authorisation requests for the following transaction types are not relayed to partners:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["REFUND"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["ACCOUNT_CREDIT"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["CREDIT_TRANSACTION"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":1},"children":["How it works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An example of this flow is shown in the diagram below:"]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/relay-auth-seq.180b55be3de9a2abb0a2d52a52e6347d01cd6ef9cae5a3f0bb2d1133bf128b91.28b10c14.png","alt":"relayed authorisation flow","framed":false,"withLightbox":false},"children":[]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a cardholder makes a payment, the scheme initiates an authorisation request and sends it to Wise."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Wise runs authorisation rules, internal fraud checks, and any spend controls or spend limits set by you (the partner) or end customer. If any check fails, Wise declines the transaction and does not forward the authorisation request to the partner."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If Wise checks pass, the request is forwarded to you, unless the transaction type is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCOUNT_CREDIT"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDIT_TRANSACTION"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You decide to approve or decline the authorisation synchronously and respond within 2s. If no response is received, Wise approves the transaction by default. The transaction data and webhook events include additional data about your decision and whether Wise made the default decision."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If approved, Wise reserves the funds for the transaction and forwards the authorisation response to the scheme. The request can still be declined if funds are insufficient at the balance reservation."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["While card schemes such as Visa and Mastercard allow 5 to 7 seconds for authorization requests, these should be processed as rapidly as possible to ensure an optimal user experience."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Additionally, the card scheme mandates that transaction acceptance rates remain above a specific threshold. Unexplained declines cause significant customer confusion, we require partners to decline transactions only when there is a specific, valid reason."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"required-configurations","__idx":2},"children":["Required configurations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before enabling relayed authorisation, you must provide our implementation team with an endpoint to accept relay authorisation requests. This endpoint must have an open TCP port for HTTPs traffic on port 443."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"ip-whitelisting","__idx":3},"children":["IP whitelisting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the partner needs to whitelist our IP addresses, please reach out to our implementation team."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"interfaces","__idx":4},"children":["Interfaces"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authorisation-request","__idx":5},"children":["Authorisation request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The request is signed and packaged in accordance with the JOSE specification, with the ES256 algorithm. Upon receiving the encoded request, you must use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/jose#get-wise-jwt-public-key"},"children":["Wise public key"]}," (with parameters set as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["algorithm=ES256"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version=1"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope=PAYLOAD_SIGNING"]},") to decode and verify the request. You do not need to sign the response."]},{"$$mdtype":"Tag","name":"ExampleBox","attributes":{"title":"Example Request","type":"code"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"eyJ2ZXJzaW9uIjoxLCJhbGciOiJFUzI1NiJ9.eyJjYXJkVG9rZW4iOiI2MWY1YTgzNS00OTEyLTQ5MzMtNzdjMS1kYzcyZmRmMzVmOWYiLCJ0cmFuc2FjdGlvblR5cGUiOiJQT1NfUFVSQ0hBU0UiLCJpZGVtcG90ZW5jeUlkIjoiNmY5NDQ1NzQtOWZjMC00ZjYxLWRkOTktMmVjNzBmNDhkNWU3Iiwic2NoZW1lUmVmZXJlbmNlSWQiOiI0NTkxODA3ODY3MzE5NDAiLCJ0cmFuc2FjdGlvbkFtb3VudFdpdGhGZWVzIjp7ImFtb3VudCI6MTAsImN1cnJlbmN5IjoiS1JXIn0sImJpbGxpbmdBbW91bnRXaXRoRmVlcyI6eyJhbW91bnQiOjEwLCJjdXJyZW5jeSI6IktSVyJ9LCJmZWVzIjpbXSwibWVyY2hhbnQiOnsibmFtZSI6IkFDUVVJUkVSIE5BTUUiLCJjYXRlZ29yeSI6eyJjb2RlIjoiNTQ5OSJ9LCJsb2NhdGlvbiI6eyJjb3VudHJ5IjoiZ2JyIiwiY2l0eSI6IkNJVFkgTkFNRSIsInppcENvZGUiOiIiLCJzdGF0ZSI6IiJ9fSwiY3JlYXRpb25UaW1lIjoiMjAyNi0wMS0yMlQwOTozNzo1OVoiLCJiYWxhbmNlQmVmb3JlIjp7ImFtb3VudCI6ODg1ODQ2OCwiY3VycmVuY3kiOiJLUlcifSwib3JpZ2luYWxBdXRoRGF0YSI6eyJzY2hlbWVSZWZlcmVuY2VJZCI6IjQ1OTE4MDc4NjczMTk0MCJ9LCJwcm9wZXJ0aWVzIjp7ImlzSW5jcmVtZW50YWxSZXF1ZXN0IjpmYWxzZX19.brhggeprEzT0wnq8j3Ed4qVAoM7uILudVE68WEGK0Tlhz3A1g0B_VBWro9LGyjH8ckyiiR5G8su2wh-2smYGrA\n","lang":"shell"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After receiving and verifying the signature, you can decode the payload into its standard JSON format."]},{"$$mdtype":"Tag","name":"ExampleBox","attributes":{"title":"Example Request","type":"code"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"Header:\n{ \n  \"version\": 1,\n  \"alg\": \"ES256\"\n}\n\nBody:\n{\n  \"cardToken\": \"61f5a835-4912-4933-77c1-dc72fdf35f9f\",\n  \"transactionType\": \"POS_PURCHASE\",\n  \"idempotencyId\": \"6f944574-9fc0-4f61-dd99-2ec70f48d5e7\",\n  \"schemeReferenceId\": \"459180786731940\",\n  \"transactionAmountWithFees\": {\n    \"amount\": 10,\n    \"currency\": \"KRW\"\n  },\n  \"billingAmountWithFees\": {\n    \"amount\": 10,\n    \"currency\": \"KRW\"\n  },\n  \"fees\": [],\n  \"merchant\": {\n    \"name\": \"ACQUIRER NAME\",\n    \"category\": {\n      \"code\": \"5499\"\n    },\n    \"location\": {\n      \"country\": \"gbr\",\n      \"city\": \"CITY NAME\",\n      \"zipCode\": \"\",\n      \"state\": \"\"\n    }\n  },\n  \"creationTime\": \"2026-01-22T09:37:59Z\",\n  \"balanceBefore\": {\n    \"amount\": 8858468,\n    \"currency\": \"KRW\"\n  },\n  \"originalAuthData\": {\n    \"schemeReferenceId\": \"459180786731940\"\n  },\n  \"properties\": {\n    \"isIncrementalRequest\": false\n  }\n}\n","lang":"shell"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The header simply identifies the algorithm and key version used for signing. The request body contains the following fields:"]},{"$$mdtype":"Tag","name":"Fields","attributes":{"title":"Authorisation Request"},"children":[{"$$mdtype":"Tag","name":"Field","attributes":{"name":"cardToken","format":"text"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Card token"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"transactionType","format":"text"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/card-transaction#type"},"children":["Type"]}," of the transaction"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"idempotencyId","format":"text"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Unique ID of authorisation request. Use this field to detect duplicate requests should they occur"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"schemeReferenceId","format":"text"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A unique identifier used to track a transaction within a specific payment network, or \"scheme,\" like Visa or Mastercard"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"transactionAmountWithFees","format":"money"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Transaction amount + Wise ATM or account funding fees"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"billingAmountWithFees","format":"money"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Billing amount + Wise ATM or account funding fees"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"fees[n].amount","format":"decimal"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fee amount"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"fees[n].currency","format":"string"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Currency code"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"fees[n].feeType","format":"string"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fee type"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"merchant.name","format":"text"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Merchant name"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"merchant.category.code","format":"text"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Merchant category code"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"merchant.location.country","format":"text"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Merchant country"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"merchant.location.city","format":"text"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Merchant city"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"merchant.location.zipCode","format":"text"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Merchant ZIP code"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"merchant.location.state","format":"text"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Merchant state"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"creationTime","format":"date-time"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authorisation request time (ISO 8601 format)"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"balanceBefore","format":"money"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Available balance converted to billing currency, excluding any conversion fees"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"originalAuthData.schemeReferenceId","format":"text"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Linked original transaction data for handling incremental authorisation"]}]},{"$$mdtype":"Tag","name":"Field","attributes":{"name":"properties.isIncrementalRequest","format":"boolean"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Whether it is an incremental authorisation request (updating amount of an existing transaction)"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authorisation-response","__idx":6},"children":["Authorisation response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You should respond with a 200 status code for both approved and declined transactions. The response should not be signed. A responseCode must be included in the response body, using one of the following codes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APPROVED"]},": approves the transaction. All other codes decline the transaction."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PROCESSING_ERROR"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NON_SUPPORTED_CURRENCY"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NON_SUPPORTED_MCC_FOR_COUNTRY"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BLOCKED_COUNTRY"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSACTION_TYPE_NOT_SUPPORTED"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SUSPECTED_FRAUD"]}]}]},{"$$mdtype":"Tag","name":"ExampleBox","attributes":{"title":"Example Response","type":"code"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n  \"responseCode\": \"APPROVED\"\n}\n"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"transaction-webhook-and-object","__idx":7},"children":["Transaction webhook and object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can retrieve the result of your authorisation decision in the returned ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/card-transaction"},"children":["Transaction object"]}," in API and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/webhook-event/eventcardstransactionstatechange"},"children":["card transaction webhook"]},". These will both include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["relayAuthorisationData"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["relay_authorisation_data"]}," for webhook) block that includes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["responseCode"]},"  if provided"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fallback"]}," indicating whether there was a fallback applied by Wise"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If authorisation relay is not enabled in your integration, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["relayAuthorisationData"]}," will always be null and can be ignored."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you (the partner) approved the transaction but it was ultimately declined by insufficient funds, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["relayAuthorisationData.responseCode"]}," would be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APPROVED"]},", though the transaction is declined with declineReason as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INSUFFICIENT_FUNDS"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In rare cases of internal system issues in Wise, it is possible that you (the partner) responded but Wise still applied a fallback. In this case, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["relayAuthorisationData.responseCode"]}," would be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["relayAuthorisationData.fallback"]}," would be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},"."]}]},"headings":[{"value":"Relayed authorisation","id":"relayed-authorisation","depth":1},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Required configurations","id":"required-configurations","depth":2},{"value":"IP whitelisting","id":"ip-whitelisting","depth":3},{"value":"Interfaces","id":"interfaces","depth":2},{"value":"Authorisation request","id":"authorisation-request","depth":3},{"value":"Authorisation response","id":"authorisation-response","depth":3},{"value":"Transaction webhook and object","id":"transaction-webhook-and-object","depth":3}],"frontmatter":{"seo":{"title":"Relayed Authorisation: Approve or decline card transactions in real time"}},"lastModified":"2026-06-11T16:49:59.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/product/issue-cards/relayed-authorisation","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}