jlengrand/adyen-openapi
1
0
Fork 0
mirror of https://github.com/gcatanese/adyen-openapi.git synced 2026-03-10 15:47:40 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
adyen-openapi/json/BalancePlatformTransactionNotification-v4.json
Adyen Automation 61333c82f2 spec release
2025-05-02 09:37:49 +02:00

664 lines
30 KiB
JSON
Raw Permalink Blame History

{
"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"
}
}
}
}
}
Reference in New Issue View Git Blame Copy Permalink