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

632 lines
23 KiB
YAML
Raw 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.
You can use the data from these webhooks to, for example:
- Update balances in your dashboards.
- 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.
'
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**.
Possible values:
* **regular**: for normal, low-value transactions.
* **fast**: a faster way to transfer funds, but the fees are higher. Recommended
for high-priority, low-value transactions.
* **wire**: the fastest way to transfer funds, but this has the highest
fees. Recommended for high-priority, high-value transactions.
* **instant**: for instant funds transfers in [SEPA countries](https://www.ecb.europa.eu/paym/integration/retail/sepa/html/index.en.html).
* **crossBorder**: for high-value transfers to a recipient in a different
country.
* **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.
Possible 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/).
Possible values:
* **AcquiringFees**: for the acquiring fee incurred on a transaction.
* **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).
* **AdyenFees**: for all the transaction fees due to Adyen. This is the
sum of Adyen''s commission and Adyen''s markup.
* **AdyenMarkup**: for the transaction fee due to Adyen under [Interchange++
pricing](https://www.adyen.com/pricing).
* **BalanceAccount**: or the sale amount of a transaction.
* **Commission**: for your platform''s commission on a transaction.
* **DCCPlatformCommission**: for the DCC Commission for the platform on
a transaction.
* **Interchange**: for the interchange fee (fee paid to the issuer) incurred
on a transaction.
* **PaymentFee**: for all of the transaction fees.
* **Remainder**: for the left over amount after currency conversion.
* **SchemeFee**: for the scheme fee incurred on a transaction. This is
the sum of the interchange fees and the acquiring fees.
* **Surcharge**: for the surcharge paid by the customer on a transaction.
* **Tip**: for the tip paid by the customer.
* **TopUp**: for an incoming transfer to top up your user''s balance account.
* **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.
Possible 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