{ "openapi" : "3.1.0", "info" : { "version" : "4", "x-publicVersion" : true, "title" : "Transaction webhooks", "description" : "After a transfer is booked in a balance account, Adyen sends webhooks with information about the transaction.\n\nYou can use the data from these webhooks to, for example:\n- Update balances in your dashboards.\n- Keep track of incoming and outgoing funds.", "termsOfService" : "https://www.adyen.com/legal/terms-and-conditions", "contact" : { "name" : "Adyen Developer Experience team", "url" : "https://github.com/Adyen/adyen-openapi" } }, "tags" : [ { "name" : "General" } ], "webhooks" : { "balancePlatform.transaction.created" : { "post" : { "tags" : [ "General" ], "summary" : "Transaction created", "description" : "After a transfer is booked in a balance account, Adyen sends this webhook with information about the transaction.\n\n", "x-addedInVersion" : "1", "operationId" : "post-balancePlatform.transaction.created", "x-sortIndex" : 0, "x-methodName" : "transactionCreated", "security" : [ { "BasicAuth" : [ ] } ], "requestBody" : { "content" : { "application/json" : { "examples" : { "01.balancePlatform-transaction-created-payout-ti" : { "$ref" : "#/components/examples/post-balancePlatform.transaction.created-01.balancePlatform-transaction-created-payout-ti" }, "02.balancePlatform-transaction-created-internal-incoming" : { "$ref" : "#/components/examples/post-balancePlatform.transaction.created-02.balancePlatform-transaction-created-internal-incoming" }, "03.balancePlatform-transaction-created-outgoing-business-account" : { "$ref" : "#/components/examples/post-balancePlatform.transaction.created-03.balancePlatform-transaction-created-outgoing-business-account" } }, "schema" : { "$ref" : "#/components/schemas/TransactionNotificationRequestV4" } } } }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BalancePlatformNotificationResponse" } } }, "description" : "OK - the request has succeeded." } } } } }, "components" : { "schemas" : { "Amount" : { "additionalProperties" : false, "properties" : { "currency" : { "description" : "The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes#currency-codes).", "maxLength" : 3, "minLength" : 3, "type" : "string" }, "value" : { "description" : "The amount of the transaction, in [minor units](https://docs.adyen.com/development-resources/currency-codes#minor-units).", "format" : "int64", "type" : "integer" } }, "required" : [ "value", "currency" ], "type" : "object" }, "BalancePlatformNotificationResponse" : { "additionalProperties" : false, "properties" : { "notificationResponse" : { "description" : "Respond with any **2xx** HTTP status code to [accept the webhook](https://docs.adyen.com/development-resources/webhooks#accept-notifications).", "type" : "string" } }, "type" : "object" }, "BankCategoryData" : { "additionalProperties" : false, "properties" : { "priority" : { "x-addedInVersion" : "4", "description" : "The priority for the bank transfer. This sets the speed at which the transfer is sent and the fees that you have to pay. Required for transfers with `category` **bank**.\n\nPossible values:\n\n* **regular**: for normal, low-value transactions.\n\n* **fast**: a faster way to transfer funds, but the fees are higher. Recommended for high-priority, low-value transactions.\n\n* **wire**: the fastest way to transfer funds, but this has the highest fees. Recommended for high-priority, high-value transactions.\n\n* **instant**: for instant funds transfers in [SEPA countries](https://www.ecb.europa.eu/paym/integration/retail/sepa/html/index.en.html).\n\n* **crossBorder**: for high-value transfers to a recipient in a different country.\n\n* **internal**: for transfers to an Adyen-issued business bank account (by bank account number/IBAN).", "enum" : [ "crossBorder", "fast", "instant", "internal", "regular", "wire" ], "type" : "string" }, "type" : { "default" : "bank", "description" : "**bank**", "enum" : [ "bank" ], "type" : "string" } }, "type" : "object" }, "InternalCategoryData" : { "additionalProperties" : false, "properties" : { "modificationMerchantReference" : { "x-addedInVersion" : "4", "description" : "The capture's merchant reference included in the transfer.", "type" : "string" }, "modificationPspReference" : { "x-addedInVersion" : "4", "description" : "The capture reference included in the transfer.", "type" : "string" }, "type" : { "default" : "internal", "description" : "**internal**", "enum" : [ "internal" ], "type" : "string" } }, "type" : "object" }, "IssuedCard" : { "additionalProperties" : false, "properties" : { "authorisationType" : { "x-addedInVersion" : "4", "description" : "The authorisation type. For example, **defaultAuthorisation**, **preAuthorisation**, **finalAuthorisation**", "type" : "string" }, "panEntryMode" : { "x-addedInVersion" : "4", "description" : "Indicates the method used for entering the PAN to initiate a transaction.\n\nPossible values: **manual**, **chip**, **magstripe**, **contactless**, **cof**, **ecommerce**, **token**.", "enum" : [ "chip", "cof", "contactless", "ecommerce", "magstripe", "manual", "token" ], "type" : "string" }, "processingType" : { "x-addedInVersion" : "4", "description" : "Contains information about how the payment was processed. For example, **ecommerce** for online or **pos** for in-person payments.", "enum" : [ "atmWithdraw", "balanceInquiry", "ecommerce", "moto", "pos", "purchaseWithCashback", "recurring", "token" ], "type" : "string" }, "relayedAuthorisationData" : { "x-addedInVersion" : "4", "description" : "If you are using relayed authorisation, this object contains information from the relayed authorisation response from your server.", "$ref" : "#/components/schemas/RelayedAuthorisationData" }, "schemeTraceId" : { "x-addedInVersion" : "4", "description" : "The identifier of the original payment. This ID is provided by the scheme and can be alphanumeric or numeric, depending on the scheme. The `schemeTraceID` should refer to an original `schemeUniqueTransactionID` provided in an earlier payment (not necessarily processed by Adyen). A `schemeTraceId` is typically available for authorization adjustments or recurring payments.", "type" : "string" }, "schemeUniqueTransactionId" : { "x-addedInVersion" : "4", "description" : "The unique identifier created by the scheme. This ID can be alphanumeric or numeric depending on the scheme.", "type" : "string" }, "type" : { "default" : "issuedCard", "description" : "**issuedCard**", "enum" : [ "issuedCard" ], "type" : "string" }, "validationFacts" : { "x-addedInVersion" : "4", "description" : "The evaluation of the validation facts. See [validation checks](https://docs.adyen.com/issuing/validation-checks) for more information.", "items" : { "$ref" : "#/components/schemas/TransferNotificationValidationFact" }, "type" : "array" } }, "type" : "object" }, "PaymentInstrument" : { "additionalProperties" : false, "properties" : { "description" : { "description" : "The description of the resource.", "type" : "string" }, "id" : { "description" : "The unique identifier of the resource.", "type" : "string" }, "reference" : { "description" : "The reference for the resource.", "type" : "string" }, "tokenType" : { "x-addedInVersion" : "3", "description" : "The type of wallet that the network token is associated with.", "type" : "string" } }, "type" : "object" }, "PlatformPayment" : { "additionalProperties" : false, "properties" : { "modificationMerchantReference" : { "x-addedInVersion" : "4", "description" : "The capture's merchant reference included in the transfer.", "type" : "string" }, "modificationPspReference" : { "x-addedInVersion" : "4", "description" : "The capture reference included in the transfer.", "type" : "string" }, "paymentMerchantReference" : { "x-addedInVersion" : "4", "description" : "The payment's merchant reference included in the transfer.", "type" : "string" }, "platformPaymentType" : { "x-addedInVersion" : "4", "description" : "Specifies the nature of the transfer. This parameter helps categorize transfers so you can reconcile transactions at a later time, using the Balance Platform Accounting Report for [marketplaces](https://docs.adyen.com/marketplaces/reports-and-fees/balance-platform-accounting-report/) or [platforms](https://docs.adyen.com/platforms/reports-and-fees/balance-platform-accounting-report/).\n\nPossible values:\n\n* **AcquiringFees**: for the acquiring fee incurred on a transaction.\n\n* **AdyenCommission**: for the transaction fee due to Adyen under [blended rates](https://www.adyen.com/knowledge-hub/guides/payments-training-guide/get-the-best-from-your-card-processing).\n\n* **AdyenFees**: for all the transaction fees due to Adyen. This is the sum of Adyen's commission and Adyen's markup.\n\n* **AdyenMarkup**: for the transaction fee due to Adyen under [Interchange++ pricing](https://www.adyen.com/pricing).\n\n* **BalanceAccount**: or the sale amount of a transaction.\n\n* **Commission**: for your platform's commission on a transaction.\n\n* **DCCPlatformCommission**: for the DCC Commission for the platform on a transaction.\n\n* **Interchange**: for the interchange fee (fee paid to the issuer) incurred on a transaction.\n\n* **PaymentFee**: for all of the transaction fees.\n\n* **Remainder**: for the left over amount after currency conversion.\n\n* **SchemeFee**: for the scheme fee incurred on a transaction. This is the sum of the interchange fees and the acquiring fees.\n\n* **Surcharge**: for the surcharge paid by the customer on a transaction.\n\n* **Tip**: for the tip paid by the customer.\n\n* **TopUp**: for an incoming transfer to top up your user's balance account.\n\n* **VAT**: for the Value Added Tax.", "enum" : [ "AcquiringFees", "AdyenCommission", "AdyenFees", "AdyenMarkup", "BalanceAccount", "ChargebackRemainder", "Commission", "DCCPlatformCommission", "Default", "Interchange", "PaymentFee", "Remainder", "SchemeFee", "Surcharge", "Tip", "TopUp", "VAT" ], "type" : "string" }, "pspPaymentReference" : { "x-addedInVersion" : "4", "description" : "The payment reference included in the transfer.", "type" : "string" }, "type" : { "default" : "platformPayment", "description" : "**platformPayment**", "enum" : [ "platformPayment" ], "type" : "string" } }, "type" : "object" }, "RelayedAuthorisationData" : { "additionalProperties" : false, "properties" : { "metadata" : { "x-addedInVersion" : "3", "additionalProperties" : { "type" : "string" }, "description" : "Contains key-value pairs of your references and descriptions, for example, `customId`:`your-own-custom-field-12345`.", "type" : "object" }, "reference" : { "x-addedInVersion" : "3", "description" : "Your reference for the relayed authorisation data.", "type" : "string" } }, "type" : "object" }, "Resource" : { "additionalProperties" : false, "properties" : { "balancePlatform" : { "description" : "The unique identifier of the balance platform.", "type" : "string" }, "creationDate" : { "description" : "The date and time when the event was triggered, in ISO 8601 extended format. For example, **2020-12-18T10:15:30+01:00**.", "format" : "date-time", "type" : "string" }, "id" : { "description" : "The ID of the resource.", "type" : "string" } }, "type" : "object" }, "ResourceReference" : { "additionalProperties" : false, "properties" : { "description" : { "description" : "The description of the resource.", "type" : "string" }, "id" : { "description" : "The unique identifier of the resource.", "type" : "string" }, "reference" : { "description" : "The reference for the resource.", "type" : "string" } }, "type" : "object" }, "Transaction" : { "additionalProperties" : false, "properties" : { "accountHolder" : { "x-addedInVersion" : "4", "description" : "Contains information about the account holder associated with the `balanceAccount`.", "$ref" : "#/components/schemas/ResourceReference" }, "amount" : { "x-addedInVersion" : "1", "description" : "Contains information about the amount of the transaction.", "$ref" : "#/components/schemas/Amount" }, "balanceAccount" : { "x-addedInVersion" : "4", "description" : "Contains information about the balance account involved in the transaction.", "$ref" : "#/components/schemas/ResourceReference" }, "balancePlatform" : { "x-addedInVersion" : "1", "description" : "The unique identifier of the balance platform.", "type" : "string" }, "bookingDate" : { "x-addedInVersion" : "1", "description" : "The date the transaction was booked into the balance account.", "format" : "date-time", "type" : "string" }, "creationDate" : { "description" : "The date and time when the event was triggered, in ISO 8601 extended format. For example, **2020-12-18T10:15:30+01:00**.", "format" : "date-time", "type" : "string" }, "description" : { "x-addedInVersion" : "1", "description" : "The `description` from the `/transfers` request.", "type" : "string" }, "id" : { "x-addedInVersion" : "1", "description" : "The unique identifier of the transaction.", "type" : "string" }, "paymentInstrument" : { "x-addedInVersion" : "4", "description" : "Contains information about the payment instrument that was used for the transaction.", "$ref" : "#/components/schemas/PaymentInstrument" }, "referenceForBeneficiary" : { "x-addedInVersion" : "1", "description" : "The reference sent to or received from the counterparty.\n\n* For outgoing funds, this is the [`referenceForBeneficiary`](https://docs.adyen.com/api-explorer/#/transfers/latest/post/transfers__resParam_referenceForBeneficiary) from the [`/transfers`](https://docs.adyen.com/api-explorer/#/transfers/latest/post/transfers__reqParam_referenceForBeneficiary) request.\n\n * For incoming funds, this is the reference from the sender.", "type" : "string" }, "status" : { "x-addedInVersion" : "1", "description" : "The status of the transaction.\n\n Possible values:\n\n* **pending**: The transaction is still pending.\n\n* **booked**: The transaction has been booked to the balance account.\n\n", "enum" : [ "booked", "pending" ], "type" : "string" }, "transfer" : { "x-addedInVersion" : "4", "description" : "Contains information about the transfer related to the transaction.", "$ref" : "#/components/schemas/TransferView" }, "valueDate" : { "x-addedInVersion" : "1", "description" : "The date the transfer amount becomes available in the balance account.", "format" : "date-time", "type" : "string" } }, "required" : [ "id", "accountHolder", "balanceAccount", "amount", "status", "bookingDate", "valueDate", "balancePlatform" ], "type" : "object" }, "TransactionNotificationRequestV4" : { "additionalProperties" : false, "properties" : { "data" : { "description" : "Contains details about the event.", "$ref" : "#/components/schemas/Transaction" }, "environment" : { "description" : "The environment from which the webhook originated.\n\nPossible values: **test**, **live**.", "type" : "string" }, "timestamp" : { "description" : "When the event was queued.", "format" : "date-time", "type" : "string" }, "type" : { "description" : "Type of the webhook.", "enum" : [ "balancePlatform.transaction.created" ], "type" : "string" } }, "required" : [ "environment", "data" ], "type" : "object" }, "TransferNotificationValidationFact" : { "additionalProperties" : false, "properties" : { "result" : { "description" : "The evaluation result of the validation fact.", "type" : "string" }, "type" : { "description" : "The type of the validation fact.", "type" : "string" } }, "type" : "object" }, "TransferView" : { "additionalProperties" : false, "properties" : { "categoryData" : { "x-addedInVersion" : "4", "description" : "The relevant data according to the transfer category.", "oneOf" : [ { "$ref" : "#/components/schemas/BankCategoryData" }, { "$ref" : "#/components/schemas/InternalCategoryData" }, { "$ref" : "#/components/schemas/IssuedCard" }, { "$ref" : "#/components/schemas/PlatformPayment" } ] }, "id" : { "description" : "The ID of the resource.", "type" : "string" }, "reference" : { "x-addedInVersion" : "4", "description" : "The [`reference`](https://docs.adyen.com/api-explorer/#/transfers/latest/post/transfers__reqParam_reference) from the `/transfers` request. If you haven't provided any, Adyen generates a unique reference.", "type" : "string" } }, "required" : [ "reference" ], "type" : "object" } }, "securitySchemes" : { "BasicAuth" : { "scheme" : "basic", "type" : "http" } }, "examples" : { "post-balancePlatform.transaction.created-01.balancePlatform-transaction-created-payout-ti" : { "summary" : "Transaction related to a payout", "description" : "Example webhook for a transaction related to a payout to a transfer instrument", "value" : { "data" : { "id" : "EVJN00000000000000000000000003EUR", "amount" : { "value" : -10000, "currency" : "EUR" }, "status" : "booked", "transfer" : { "categoryData" : { "priority" : "regular", "type" : "bank" }, "id" : "3JNC3O5ZVFLLGV4B", "reference" : " Your internal reference for the transfer" }, "valueDate" : "2023-08-11T16:19:35+02:00", "bookingDate" : "2023-08-11T16:31:02+02:00", "creationDate" : "2023-08-11T16:19:35+02:00", "description" : "Your description of the transfer", "referenceForBeneficiary" : "Your reference sent to the beneficiary of the transfer", "accountHolder" : { "id" : "AH00000000000000000000001", "reference" : "Your reference for the account holder", "description" : "Your description of the account holder" }, "balanceAccount" : { "id" : "BA00000000000000000000001", "description" : "Your description of the balance account from where the amount is debited." }, "balancePlatform" : "YOUR_BALANCE_PLATFORM" }, "environment" : "test", "timestamp" : "2023-08-11T16:16:35+02:00", "type" : "balancePlatform.transaction.created" } }, "post-balancePlatform.transaction.created-02.balancePlatform-transaction-created-internal-incoming" : { "summary" : "Transaction related to an incoming internal transfer", "description" : "Example webhook for a transaction related to an incoming internal transfer", "value" : { "data" : { "id" : "EVJN00000000000000000000000003EUR", "amount" : { "value" : 10000, "currency" : "EUR" }, "status" : "booked", "transfer" : { "categoryData" : { "type" : "internal" }, "id" : "48TYZO5ZVURJ2FCW", "reference" : " Your internal reference for the transfer" }, "valueDate" : "2023-08-11T16:19:35+02:00", "bookingDate" : "2023-08-11T16:31:02+02:00", "creationDate" : "2023-08-11T16:19:35+02:00", "description" : "The sender's of the transfer", "referenceForBeneficiary" : "The sender's reference sent to the beneficiary of the transfer", "accountHolder" : { "id" : "AH00000000000000000000001", "reference" : "Your reference for the account holder", "description" : "Your description of the account holder" }, "balanceAccount" : { "id" : "BA00000000000000000000001", "description" : "Your description of the balance account from where the amount is debited." }, "balancePlatform" : "YOUR_BALANCE_PLATFORM" }, "environment" : "test", "timestamp" : "2023-08-11T16:16:35+02:00", "type" : "balancePlatform.transaction.created" } }, "post-balancePlatform.transaction.created-03.balancePlatform-transaction-created-outgoing-business-account" : { "summary" : "Transaction related to an outgoing bank transfer", "description" : "Example webhook for a transaction related to an outgoing bank transfer", "value" : { "data" : { "id" : "EVJN00000000000000000000000003EUR", "amount" : { "value" : -10000, "currency" : "EUR" }, "status" : "booked", "transfer" : { "categoryData" : { "priority" : "regular", "type" : "bank" }, "id" : "3JNC3O5ZVFLLGV4B", "reference" : " Your internal reference for the transfer" }, "valueDate" : "2023-08-11T16:19:35+02:00", "bookingDate" : "2023-08-11T16:31:02+02:00", "creationDate" : "2023-08-11T16:19:35+02:00", "description" : "Your description of the transfer", "referenceForBeneficiary" : "Your reference sent to the beneficiary of the transfer", "accountHolder" : { "id" : "AH00000000000000000000001", "reference" : "Your reference for the account holder", "description" : "Your description of the account holder" }, "balanceAccount" : { "id" : "BA00000000000000000000001", "description" : "Your description of the balance account from where the amount is debited." }, "paymentInstrument" : { "id" : "PI00000000000000000000001", "description" : "Your description of the payment instrument" }, "balancePlatform" : "YOUR_BALANCE_PLATFORM" }, "environment" : "test", "timestamp" : "2023-08-11T16:16:35+02:00", "type" : "balancePlatform.transaction.created" } } } } }