diff --git a/json/BalancePlatformTransferNotification-v3.json b/json/BalancePlatformTransferNotification-v3.json index 535d54f..c505d0e 100644 --- a/json/BalancePlatformTransferNotification-v3.json +++ b/json/BalancePlatformTransferNotification-v3.json @@ -607,6 +607,30 @@ ], "type" : "object" }, + "DirectDebitInformation" : { + "additionalProperties" : false, + "properties" : { + "dateOfSignature" : { + "description" : "The date when the direct debit mandate was accepted by your user, in [ISO-8601](https://www.w3.org/TR/NOTE-datetime) format.", + "format" : "date-time", + "type" : "string" + }, + "dueDate" : { + "description" : "The date when the funds are deducted from your user's balance account.", + "format" : "date-time", + "type" : "string" + }, + "mandateId" : { + "description" : "Your unique identifier for the direct debit mandate.", + "type" : "string" + }, + "sequenceType" : { + "description" : "Identifies the direct debit transfer's type.\nPossible values: **OneOff**, **First**, **Recurring**, **Final**.", + "type" : "string" + } + }, + "type" : "object" + }, "EstimationTrackingData" : { "additionalProperties" : false, "properties" : { @@ -858,6 +882,7 @@ "paymentCost", "paymentCostPending", "pendingApproval", + "pendingExecution", "received", "refundPending", "refundReversalPending", @@ -1343,6 +1368,11 @@ "description" : "Your description for the transfer. It is used by most banks as the transfer description. We recommend sending a maximum of 140 characters, otherwise the description may be truncated.\n\nSupported characters: **[a-z] [A-Z] [0-9] / - ?** **: ( ) . , ' + Space**\n\nSupported characters for **regular** and **fast** transfers to a US counterparty: **[a-z] [A-Z] [0-9] & $ % # @** **~ = + - _ ' \" ! ?**", "type" : "string" }, + "directDebitInformation" : { + "x-addedInVersion" : "3", + "description" : "The details of the direct debit.", + "$ref" : "#/components/schemas/DirectDebitInformation" + }, "direction" : { "x-addedInVersion" : "2", "description" : "The direction of the transfer.\n\nPossible values: **incoming**, **outgoing**.", @@ -1486,6 +1516,7 @@ "x-addedInVersion" : "2", "description" : "Additional information about the status of the transfer.", "enum" : [ + "accountHierarchyNotActive", "amountLimitExceeded", "approved", "balanceAccountTemporarilyBlockedByTransactionRule", @@ -1497,12 +1528,15 @@ "counterpartyBankUnavailable", "declined", "declinedByTransactionRule", + "directDebitNotSupported", "error", "notEnoughBalance", "pendingApproval", + "pendingExecution", "refusedByCounterpartyBank", "routeNotFound", "scaFailed", + "transferInstrumentDoesNotExist", "unknown" ], "type" : "string" @@ -1526,6 +1560,11 @@ "description" : "If you are using relayed authorisation, this object contains information from the relayed authorisation response from your server.", "$ref" : "#/components/schemas/RelayedAuthorisationData" }, + "review" : { + "x-addedInVersion" : "3", + "description" : "Contains status updates related to additional reviews.", + "$ref" : "#/components/schemas/TransferReview" + }, "sequenceNumber" : { "x-addedInVersion" : "3", "description" : "The sequence number of the transfer webhook. The numbers start from 1 and increase with each new webhook for a specific transfer.\n\nThe sequence number can help you restore the correct sequence of events even if they arrive out of order.", @@ -1588,6 +1627,7 @@ "paymentCost", "paymentCostPending", "pendingApproval", + "pendingExecution", "received", "refundPending", "refundReversalPending", @@ -1757,6 +1797,7 @@ "x-addedInVersion" : "3", "description" : "The reason for the transfer status.", "enum" : [ + "accountHierarchyNotActive", "amountLimitExceeded", "approved", "balanceAccountTemporarilyBlockedByTransactionRule", @@ -1768,12 +1809,15 @@ "counterpartyBankUnavailable", "declined", "declinedByTransactionRule", + "directDebitNotSupported", "error", "notEnoughBalance", "pendingApproval", + "pendingExecution", "refusedByCounterpartyBank", "routeNotFound", "scaFailed", + "transferInstrumentDoesNotExist", "unknown" ], "type" : "string" @@ -1844,6 +1888,7 @@ "paymentCost", "paymentCostPending", "pendingApproval", + "pendingExecution", "received", "refundPending", "refundReversalPending", @@ -2005,6 +2050,31 @@ }, "type" : "object" }, + "TransferReview" : { + "additionalProperties" : false, + "properties" : { + "numberOfApprovalsCompleted" : { + "description" : "Shows the number of approvals completed for the transfer.", + "format" : "int32", + "type" : "integer" + }, + "numberOfApprovalsRequired" : { + "description" : "Shows the number of [approvals](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) required to process the transfer.", + "format" : "int32", + "type" : "integer" + }, + "scaOnApproval" : { + "description" : "Shows the status of the Strong Customer Authentication (SCA) process.\n\nPossible values: **required**, **completed**, **notApplicable**.", + "enum" : [ + "completed", + "notApplicable", + "required" + ], + "type" : "string" + } + }, + "type" : "object" + }, "UKLocalAccountIdentification" : { "additionalProperties" : false, "properties" : { diff --git a/json/BalancePlatformTransferNotification-v4.json b/json/BalancePlatformTransferNotification-v4.json index a5fec31..56947d8 100644 --- a/json/BalancePlatformTransferNotification-v4.json +++ b/json/BalancePlatformTransferNotification-v4.json @@ -86,17 +86,32 @@ "content" : { "application/json" : { "examples" : { - "balancePlatform-transfer-updated-authorised-incoming-internal" : { - "$ref" : "#/components/examples/post-balancePlatform.transfer.updated-balancePlatform-transfer-updated-authorised-incoming-internal" + "01.payout-authorized" : { + "$ref" : "#/components/examples/post-balancePlatform.transfer.updated-01.payout-authorized" }, - "balancePlatform-transfer-updated-authorised-outgoing-external" : { - "$ref" : "#/components/examples/post-balancePlatform.transfer.updated-balancePlatform-transfer-updated-authorised-outgoing-external" + "02.payout-booked" : { + "$ref" : "#/components/examples/post-balancePlatform.transfer.updated-02.payout-booked" }, - "balancePlatform-transfer-updated-booked-incoming-internal" : { - "$ref" : "#/components/examples/post-balancePlatform.transfer.updated-balancePlatform-transfer-updated-booked-incoming-internal" + "03.internal-authorised" : { + "$ref" : "#/components/examples/post-balancePlatform.transfer.updated-03.internal-authorised" }, - "balancePlatform-transfer-updated-booked-outgoing-external" : { - "$ref" : "#/components/examples/post-balancePlatform.transfer.updated-balancePlatform-transfer-updated-booked-outgoing-external" + "04.internal-booked" : { + "$ref" : "#/components/examples/post-balancePlatform.transfer.updated-04.internal-booked" + }, + "05.directDebit-booked" : { + "$ref" : "#/components/examples/post-balancePlatform.transfer.updated-05.directDebit-booked" + }, + "06.directDebit-cancelled" : { + "$ref" : "#/components/examples/post-balancePlatform.transfer.updated-06.directDebit-cancelled" + }, + "07.directDebit-failed" : { + "$ref" : "#/components/examples/post-balancePlatform.transfer.updated-07.directDebit-failed" + }, + "08.internalDirectDebit-incoming-booked" : { + "$ref" : "#/components/examples/post-balancePlatform.transfer.updated-08.internalDirectDebit-incoming-booked" + }, + "09.internalDirectDebit-outgoing-booked" : { + "$ref" : "#/components/examples/post-balancePlatform.transfer.updated-09.internalDirectDebit-outgoing-booked" } }, "schema" : { @@ -656,6 +671,30 @@ ], "type" : "object" }, + "DirectDebitInformation" : { + "additionalProperties" : false, + "properties" : { + "dateOfSignature" : { + "description" : "The date when the direct debit mandate was accepted by your user, in [ISO-8601](https://www.w3.org/TR/NOTE-datetime) format.", + "format" : "date-time", + "type" : "string" + }, + "dueDate" : { + "description" : "The date when the funds are deducted from your user's balance account.", + "format" : "date-time", + "type" : "string" + }, + "mandateId" : { + "description" : "Your unique identifier for the direct debit mandate.", + "type" : "string" + }, + "sequenceType" : { + "description" : "Identifies the direct debit transfer's type.\nPossible values: **OneOff**, **First**, **Recurring**, **Final**.", + "type" : "string" + } + }, + "type" : "object" + }, "EstimationTrackingData" : { "additionalProperties" : false, "properties" : { @@ -1002,6 +1041,7 @@ "paymentCost", "paymentCostPending", "pendingApproval", + "pendingExecution", "received", "refundPending", "refundReversalPending", @@ -1566,6 +1606,11 @@ "description" : "Your description for the transfer. It is used by most banks as the transfer description. We recommend sending a maximum of 140 characters, otherwise the description may be truncated.\n\nSupported characters: **[a-z] [A-Z] [0-9] / - ?** **: ( ) . , ' + Space**\n\nSupported characters for **regular** and **fast** transfers to a US counterparty: **[a-z] [A-Z] [0-9] & $ % # @** **~ = + - _ ' \" ! ?**", "type" : "string" }, + "directDebitInformation" : { + "x-addedInVersion" : "3", + "description" : "The details of the direct debit.", + "$ref" : "#/components/schemas/DirectDebitInformation" + }, "direction" : { "x-addedInVersion" : "2", "description" : "The direction of the transfer.\n\nPossible values: **incoming**, **outgoing**.", @@ -1596,6 +1641,7 @@ "x-addedInVersion" : "2", "description" : "Additional information about the status of the transfer.", "enum" : [ + "accountHierarchyNotActive", "amountLimitExceeded", "approved", "balanceAccountTemporarilyBlockedByTransactionRule", @@ -1607,12 +1653,15 @@ "counterpartyBankUnavailable", "declined", "declinedByTransactionRule", + "directDebitNotSupported", "error", "notEnoughBalance", "pendingApproval", + "pendingExecution", "refusedByCounterpartyBank", "routeNotFound", "scaFailed", + "transferInstrumentDoesNotExist", "unknown" ], "type" : "string" @@ -1628,6 +1677,11 @@ "description" : " A reference that is sent to the recipient. This reference is also sent in all webhooks related to the transfer, so you can use it to track statuses for both the source and recipient of funds.\n\n Supported characters: **a-z**, **A-Z**, **0-9**.The maximum length depends on the `category`.\n\n - **internal**: 80 characters\n\n- **bank**: 35 characters when transferring to an IBAN, 15 characters for others.", "type" : "string" }, + "review" : { + "x-addedInVersion" : "3", + "description" : "Contains status updates related to additional reviews.", + "$ref" : "#/components/schemas/TransferReview" + }, "sequenceNumber" : { "x-addedInVersion" : "3", "description" : "The sequence number of the transfer webhook. The numbers start from 1 and increase with each new webhook for a specific transfer.\n\nThe sequence number can help you restore the correct sequence of events even if they arrive out of order.", @@ -1690,6 +1744,7 @@ "paymentCost", "paymentCostPending", "pendingApproval", + "pendingExecution", "received", "refundPending", "refundReversalPending", @@ -1845,6 +1900,7 @@ "x-addedInVersion" : "3", "description" : "The reason for the transfer status.", "enum" : [ + "accountHierarchyNotActive", "amountLimitExceeded", "approved", "balanceAccountTemporarilyBlockedByTransactionRule", @@ -1856,12 +1912,15 @@ "counterpartyBankUnavailable", "declined", "declinedByTransactionRule", + "directDebitNotSupported", "error", "notEnoughBalance", "pendingApproval", + "pendingExecution", "refusedByCounterpartyBank", "routeNotFound", "scaFailed", + "transferInstrumentDoesNotExist", "unknown" ], "type" : "string" @@ -1922,6 +1981,7 @@ "paymentCost", "paymentCostPending", "pendingApproval", + "pendingExecution", "received", "refundPending", "refundReversalPending", @@ -2083,6 +2143,31 @@ }, "type" : "object" }, + "TransferReview" : { + "additionalProperties" : false, + "properties" : { + "numberOfApprovalsCompleted" : { + "description" : "Shows the number of approvals completed for the transfer.", + "format" : "int32", + "type" : "integer" + }, + "numberOfApprovalsRequired" : { + "description" : "Shows the number of [approvals](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) required to process the transfer.", + "format" : "int32", + "type" : "integer" + }, + "scaOnApproval" : { + "description" : "Shows the status of the Strong Customer Authentication (SCA) process.\n\nPossible values: **required**, **completed**, **notApplicable**.", + "enum" : [ + "completed", + "notApplicable", + "required" + ], + "type" : "string" + } + }, + "type" : "object" + }, "UKLocalAccountIdentification" : { "additionalProperties" : false, "properties" : { @@ -2280,46 +2365,49 @@ "type" : "balancePlatform.transfer.created" } }, - "post-balancePlatform.transfer.updated-balancePlatform-transfer-updated-authorised-incoming-internal" : { - "summary" : "Authorized incoming internal transfer", - "description" : "Example webhook of an authorised incoming transfer", + "post-balancePlatform.transfer.updated-01.payout-authorized" : { + "summary" : "Authorized payout to a transfer instrument", + "description" : "Example webhook of an authorised outgoing bank transfer", "value" : { "data" : { - "id" : "2WT1N05XXY7P9XH9", - "type" : "internalTransfer", "accountHolder" : { - "description" : "Your description of the account holder of the target balance account", - "id" : "AH00000000000000000000002", + "description" : "Your description of the account holder", + "id" : "AH00000000000000000000001", "reference" : "Your reference for the account holder" }, "amount" : { "currency" : "EUR", - "value" : 1000 + "value" : 10000 }, "balanceAccount" : { - "description" : "Your description of the target balance account", - "id" : "BA00000000000000000000002" + "description" : "Your description of the balance account from where the amount is debited", + "id" : "BA00000000000000000000001", + "reference" : "Your reference for the balance account" }, "balancePlatform" : "YOUR_BALANCE_PLATFORM", "balances" : [ { "currency" : "EUR", "received" : 0, - "reserved" : 1000 + "reserved" : -10000 } ], - "category" : "internal", + "category" : "bank", + "categoryData" : { + "priority" : "regular", + "type" : "bank" + }, "creationDate" : "2023-02-28T13:30:05+02:00", - "description" : "Your description of the transfer", - "direction" : "incoming", + "description" : "Your user description of the transfer", + "direction" : "outgoing", "events" : [ { "bookingDate" : "2023-02-28T13:30:18+02:00", - "id" : "JDRF00000000000000000000000001", + "id" : "EVJN00000000000000000000000001", "mutations" : [ { "currency" : "EUR", - "received" : 1000 + "received" : -10000 } ], "status" : "received", @@ -2327,31 +2415,36 @@ }, { "bookingDate" : "2023-02-28T13:30:18+02:00", - "id" : "JDRF00000000000000000000000002", + "id" : "EVJN00000000000000000000000002", "mutations" : [ { "currency" : "EUR", - "received" : -1000, - "reserved" : 1000 + "received" : 10000, + "reserved" : -10000 } ], "status" : "authorised", "type" : "accounting" } ], + "id" : "6JKRLZ8LOT47J7RY", "reason" : "approved", - "reference" : "Your reference for the transfer", - "referenceForBeneficiary" : "Your-reference-for-the-recipient-of-the-transfer-request", + "reference" : "Your user reference for the transfer", + "referenceForBeneficiary" : "Your user reference for the beneficiary", "sequenceNumber" : 2, - "status" : "authorised" + "transactionRulesResult" : { + "allHardBlockRulesPassed" : true + }, + "status" : "authorised", + "type" : "bankTransfer" }, "environment" : "test", "type" : "balancePlatform.transfer.updated" } }, - "post-balancePlatform.transfer.updated-balancePlatform-transfer-updated-authorised-outgoing-external" : { - "summary" : "Authorized payout to a transfer instrument", - "description" : "Example webhook of an authorised outgoing bank transfer", + "post-balancePlatform.transfer.updated-02.payout-booked" : { + "summary" : "Booked payout to a transfer instrument", + "description" : "Example webhook of a booked outgoing bank transfer", "value" : { "data" : { "accountHolder" : { @@ -2371,9 +2464,10 @@ "balancePlatform" : "YOUR_BALANCE_PLATFORM", "balances" : [ { + "balance" : -10000, "currency" : "EUR", "received" : 0, - "reserved" : -10000 + "reserved" : 0 } ], "category" : "bank", @@ -2381,6 +2475,9 @@ "priority" : "regular", "type" : "bank" }, + "counterparty" : { + "transferInstrumentId" : "SE00000000000000000000001" + }, "creationDate" : "2023-02-28T13:30:05+02:00", "description" : "Your user description of the transfer", "direction" : "outgoing", @@ -2409,24 +2506,109 @@ ], "status" : "authorised", "type" : "accounting" + }, + { + "bookingDate" : "2023-02-28T13:30:18+02:00", + "id" : "EVJN00000000000000000000000003", + "mutations" : [ + { + "balance" : -10000, + "currency" : "EUR", + "received" : 0, + "reserved" : 10000 + } + ], + "status" : "booked", + "transactionId" : "EVJN00000000000000000000000003EUR", + "type" : "accounting", + "valueDate" : "2023-03-01T12:58:25+01:00" } ], "id" : "6JKRLZ8LOT47J7RY", "reason" : "approved", "reference" : "Your user reference for the transfer", "referenceForBeneficiary" : "Your user reference for the beneficiary", - "sequenceNumber" : 2, + "sequenceNumber" : 3, "transactionRulesResult" : { "allHardBlockRulesPassed" : true }, - "status" : "authorised", + "status" : "booked", "type" : "bankTransfer" }, "environment" : "test", "type" : "balancePlatform.transfer.updated" } }, - "post-balancePlatform.transfer.updated-balancePlatform-transfer-updated-booked-incoming-internal" : { + "post-balancePlatform.transfer.updated-03.internal-authorised" : { + "summary" : "Authorized incoming internal transfer", + "description" : "Example webhook of an authorised incoming transfer", + "value" : { + "data" : { + "id" : "2WT1N05XXY7P9XH9", + "type" : "internalTransfer", + "accountHolder" : { + "description" : "Your description of the account holder of the target balance account", + "id" : "AH00000000000000000000002", + "reference" : "Your reference for the account holder" + }, + "amount" : { + "currency" : "EUR", + "value" : 1000 + }, + "balanceAccount" : { + "description" : "Your description of the target balance account", + "id" : "BA00000000000000000000002" + }, + "balancePlatform" : "YOUR_BALANCE_PLATFORM", + "balances" : [ + { + "currency" : "EUR", + "received" : 0, + "reserved" : 1000 + } + ], + "category" : "internal", + "creationDate" : "2023-02-28T13:30:05+02:00", + "description" : "Your description of the transfer", + "direction" : "incoming", + "events" : [ + { + "bookingDate" : "2023-02-28T13:30:18+02:00", + "id" : "JDRF00000000000000000000000001", + "mutations" : [ + { + "currency" : "EUR", + "received" : 1000 + } + ], + "status" : "received", + "type" : "accounting" + }, + { + "bookingDate" : "2023-02-28T13:30:18+02:00", + "id" : "JDRF00000000000000000000000002", + "mutations" : [ + { + "currency" : "EUR", + "received" : -1000, + "reserved" : 1000 + } + ], + "status" : "authorised", + "type" : "accounting" + } + ], + "reason" : "approved", + "reference" : "Your reference for the transfer", + "referenceForBeneficiary" : "Your-reference-for-the-recipient-of-the-transfer-request", + "sequenceNumber" : 2, + "status" : "authorised" + }, + "environment" : "test", + "type" : "balancePlatform.transfer.updated" + } + }, + "post-balancePlatform.transfer.updated-04.internal-booked" : { "summary" : "Booked incoming internal transfer", "description" : "Example webhook of a booked incoming transfer", "value" : { @@ -2515,29 +2697,28 @@ "type" : "balancePlatform.transfer.updated" } }, - "post-balancePlatform.transfer.updated-balancePlatform-transfer-updated-booked-outgoing-external" : { - "summary" : "Booked payout to a transfer instrument", - "description" : "Example webhook of a booked outgoing bank transfer", + "post-balancePlatform.transfer.updated-05.directDebit-booked" : { + "summary" : "Business accounts - Successful external direct debit", + "description" : "Example webhook of a booked external direct debit transfer", "value" : { "data" : { "accountHolder" : { "description" : "Your description of the account holder", - "id" : "AH00000000000000000000001", + "id" : "AH00000000000000000000002", "reference" : "Your reference for the account holder" }, "amount" : { "currency" : "EUR", - "value" : 10000 + "value" : 1000 }, "balanceAccount" : { - "description" : "Your description of the balance account from where the amount is debited", - "id" : "BA00000000000000000000001", - "reference" : "Your reference for the balance account" + "description" : "Your description of the target balance account", + "id" : "BA00000000000000000000002" }, "balancePlatform" : "YOUR_BALANCE_PLATFORM", "balances" : [ { - "balance" : -10000, + "balance" : -1000, "currency" : "EUR", "received" : 0, "reserved" : 0 @@ -2545,68 +2726,452 @@ ], "category" : "bank", "categoryData" : { - "priority" : "regular", "type" : "bank" }, "counterparty" : { - "transferInstrumentId" : "SE00000000000000000000001" + "bankAccount" : { + "accountHolder" : { + "fullName" : "John Smith", + "type" : "unknown" + }, + "accountIdentification" : { + "iban" : "FR0000000000000000000000117", + "type" : "iban" + } + } }, - "creationDate" : "2023-02-28T13:30:05+02:00", - "description" : "Your user description of the transfer", - "direction" : "outgoing", + "creationDate" : "2024-08-28T13:30:05+02:00", + "directDebitInformation" : { + "dateOfSignature" : "2023-01-01T01:00:00+01:00", + "dueDate" : "2024-08-23T02:00:00+02:00", + "mandateId" : "EBAClearing-MANDAT001", + "sequenceType" : "FRST" + }, + "direction" : "incoming", "events" : [ { - "bookingDate" : "2023-02-28T13:30:18+02:00", - "id" : "EVJN00000000000000000000000001", + "bookingDate" : "2024-08-28T13:30:18+02:00", + "id" : "JDRF00000000000000000000000001", "mutations" : [ { "currency" : "EUR", - "received" : -10000 + "received" : -1000 } ], "status" : "received", "type" : "accounting" }, { - "bookingDate" : "2023-02-28T13:30:18+02:00", - "id" : "EVJN00000000000000000000000002", + "bookingDate" : "2024-08-28T13:30:18+02:00", + "id" : "JDRF00000000000000000000000002", "mutations" : [ { "currency" : "EUR", - "received" : 10000, - "reserved" : -10000 + "received" : 1000, + "reserved" : -1000 } ], "status" : "authorised", "type" : "accounting" }, { - "bookingDate" : "2023-02-28T13:30:18+02:00", - "id" : "EVJN00000000000000000000000003", + "bookingDate" : "2024-08-28T13:30:18+02:00", + "id" : "JDRF00000000000000000000000003", "mutations" : [ { - "balance" : -10000, + "balance" : -1000, "currency" : "EUR", "received" : 0, - "reserved" : 10000 + "reserved" : 1000 } ], "status" : "booked", - "transactionId" : "EVJN00000000000000000000000003EUR", + "transactionId" : "JDRF00000000000000000000000MEUR", "type" : "accounting", - "valueDate" : "2023-03-01T12:58:25+01:00" + "valueDate" : "2024-08-28T14:00:00+02:00" } ], - "id" : "6JKRLZ8LOT47J7RY", + "id" : "2WT1N05XXY7P9XH9", + "paymentInstrument" : { + "description" : "Your reference for the payment instrument", + "id" : "PI00000000000000000000001" + }, "reason" : "approved", - "reference" : "Your user reference for the transfer", - "referenceForBeneficiary" : "Your user reference for the beneficiary", + "reference" : "Your reference for the transfer", + "referenceForBeneficiary" : "The sender's reference for the beneficiary", "sequenceNumber" : 3, + "status" : "booked", "transactionRulesResult" : { "allHardBlockRulesPassed" : true }, - "status" : "booked", - "type" : "bankTransfer" + "type" : "bankDirectDebit" + }, + "environment" : "test", + "type" : "balancePlatform.transfer.updated" + } + }, + "post-balancePlatform.transfer.updated-06.directDebit-cancelled" : { + "summary" : "Business accounts - Cancelled external direct debit", + "description" : "Example webhook of a cancelled external direct debit transfer", + "value" : { + "data" : { + "accountHolder" : { + "description" : "Your description of the account holder", + "id" : "AH00000000000000000000002", + "reference" : "Your reference for the account holder" + }, + "amount" : { + "currency" : "EUR", + "value" : 1000 + }, + "balanceAccount" : { + "description" : "Your description of the target balance account", + "id" : "BA00000000000000000000002" + }, + "balancePlatform" : "YOUR_BALANCE_PLATFORM", + "balances" : [ + { + "currency" : "EUR", + "received" : -1000 + } + ], + "category" : "bank", + "categoryData" : { + "type" : "bank" + }, + "counterparty" : { + "bankAccount" : { + "accountHolder" : { + "fullName" : "John Smith", + "type" : "unknown" + }, + "accountIdentification" : { + "iban" : "FR0000000000000000000000117", + "type" : "iban" + } + } + }, + "creationDate" : "2024-08-28T13:30:05+02:00", + "directDebitInformation" : { + "dateOfSignature" : "2023-01-01T01:00:00+01:00", + "dueDate" : "2024-08-23T02:00:00+02:00", + "mandateId" : "EBAClearing-MANDAT001", + "sequenceType" : "FRST" + }, + "direction" : "incoming", + "events" : [ + { + "bookingDate" : "2024-08-28T13:30:18+02:00", + "id" : "JDRF00000000000000000000000001", + "mutations" : [ + { + "currency" : "EUR", + "received" : -1000 + } + ], + "status" : "received", + "type" : "accounting" + }, + { + "bookingDate" : "2024-08-28T13:30:18+02:00", + "id" : "JDRF00000000000000000000000002", + "mutations" : [ + { + "currency" : "EUR", + "received" : 1000 + } + ], + "reason" : "unknown", + "status" : "cancelled", + "type" : "accounting" + } + ], + "id" : "2WT1N05XXY7P9XH9", + "paymentInstrument" : { + "description" : "Your reference for the payment instrument", + "id" : "PI00000000000000000000001" + }, + "reason" : "approved", + "reference" : "Your reference for the transfer", + "referenceForBeneficiary" : "The sender's reference for the beneficiary", + "sequenceNumber" : 2, + "status" : "refused", + "transactionRulesResult" : { + "allHardBlockRulesPassed" : true + }, + "type" : "bankDirectDebit" + }, + "environment" : "test", + "type" : "balancePlatform.transfer.updated" + } + }, + "post-balancePlatform.transfer.updated-07.directDebit-failed" : { + "summary" : "Business accounts - Failed external direct debit", + "description" : "Example webhook of a failed external direct debit transfer", + "value" : { + "data" : { + "accountHolder" : { + "description" : "Your description of the account holder", + "id" : "AH00000000000000000000002", + "reference" : "Your reference for the account holder" + }, + "amount" : { + "currency" : "EUR", + "value" : 1000 + }, + "balanceAccount" : { + "description" : "Your description of the target balance account", + "id" : "BA00000000000000000000002" + }, + "balancePlatform" : "YOUR_BALANCE_PLATFORM", + "balances" : [ + { + "currency" : "EUR", + "received" : -1000 + } + ], + "category" : "bank", + "categoryData" : { + "type" : "bank" + }, + "counterparty" : { + "bankAccount" : { + "accountHolder" : { + "fullName" : "John Smith", + "type" : "unknown" + }, + "accountIdentification" : { + "iban" : "FR0000000000000000000000117", + "type" : "iban" + } + } + }, + "creationDate" : "2024-08-28T13:30:05+02:00", + "directDebitInformation" : { + "dateOfSignature" : "2023-01-01T01:00:00+01:00", + "dueDate" : "2024-08-23T02:00:00+02:00", + "mandateId" : "EBAClearing-MANDAT001", + "sequenceType" : "FRST" + }, + "direction" : "incoming", + "events" : [ + { + "bookingDate" : "2024-08-28T13:30:18+02:00", + "id" : "JDRF00000000000000000000000001", + "mutations" : [ + { + "currency" : "EUR", + "received" : -1000 + } + ], + "status" : "received", + "type" : "accounting" + }, + { + "bookingDate" : "2024-08-28T13:30:18+02:00", + "id" : "JDRF00000000000000000000000002", + "mutations" : [ + { + "currency" : "EUR", + "received" : 1000 + } + ], + "status" : "refused", + "type" : "accounting" + } + ], + "id" : "2WT1N05XXY7P9XH9", + "paymentInstrument" : { + "description" : "Your reference for the payment instrument", + "id" : "PI00000000000000000000001" + }, + "reason" : "unknown", + "reference" : "Your reference for the transfer", + "referenceForBeneficiary" : "The sender's reference for the beneficiary", + "sequenceNumber" : 2, + "status" : "cancelled", + "transactionRulesResult" : { + "allHardBlockRulesPassed" : true + }, + "type" : "bankDirectDebit" + }, + "environment" : "test", + "type" : "balancePlatform.transfer.updated" + } + }, + "post-balancePlatform.transfer.updated-08.internalDirectDebit-incoming-booked" : { + "summary" : "Business accounts - Successful internal direct debit (incoming)", + "description" : "Example webhook of a booked incoming internal direct debit transfer", + "value" : { + "data" : { + "accountHolder" : { + "id" : "AH00000000000000000000002", + "reference" : "Your reference for the account holder" + }, + "amount" : { + "currency" : "EUR", + "value" : 1000 + }, + "balanceAccount" : { + "description" : "Your description for the balance account", + "id" : "BA00000000000000000000002" + }, + "balancePlatform" : "YOUR_BALANCE_PLATFORM", + "balances" : [ + { + "balance" : -1000, + "currency" : "EUR", + "received" : 0, + "reserved" : 0 + } + ], + "category" : "internal", + "categoryData" : { + "type" : "internal" + }, + "counterparty" : { + "balanceAccountId" : "BA00000000000000000LIABLE" + }, + "creationDate" : "2024-08-28T13:30:05+02:00", + "direction" : "incoming", + "events" : [ + { + "bookingDate" : "2024-08-28T13:30:18+02:00", + "id" : "JDRF00000000000000000000000001", + "mutations" : [ + { + "currency" : "EUR", + "received" : -1000 + } + ], + "status" : "received", + "type" : "accounting" + }, + { + "bookingDate" : "2024-08-28T13:30:18+02:00", + "id" : "JDRF00000000000000000000000002", + "mutations" : [ + { + "currency" : "EUR", + "received" : 1000, + "reserved" : -1000 + } + ], + "status" : "authorised", + "type" : "accounting" + }, + { + "bookingDate" : "2024-08-28T13:30:18+02:00", + "id" : "JDRF00000000000000000000000003", + "mutations" : [ + { + "balance" : -1000, + "currency" : "EUR", + "received" : 0, + "reserved" : 1000 + } + ], + "status" : "booked", + "transactionId" : "JDRF00000000000000000000000MEUR", + "type" : "accounting", + "valueDate" : "2024-08-28T14:00:00+02:00" + } + ], + "id" : "2WT1N05XXY7P9XH9", + "reason" : "approved", + "reference" : "Your reference for the transfer", + "sequenceNumber" : 3, + "status" : "booked", + "type" : "internalDirectDebit" + }, + "environment" : "test", + "type" : "balancePlatform.transfer.updated" + } + }, + "post-balancePlatform.transfer.updated-09.internalDirectDebit-outgoing-booked" : { + "summary" : "Business accounts - Successful internal direct debit (outgoing)", + "description" : "Example webhook of a booked outgoing internal direct debit transfer", + "value" : { + "data" : { + "accountHolder" : { + "id" : "AH000000000000000000LIABLE", + "reference" : "Your reference for the account holder" + }, + "amount" : { + "currency" : "EUR", + "value" : 1000 + }, + "balanceAccount" : { + "description" : "Your description for the balance account", + "id" : "BA000000000000000000LIABLE" + }, + "balancePlatform" : "YOUR_BALANCE_PLATFORM", + "balances" : [ + { + "balance" : 1000, + "currency" : "EUR", + "received" : 0, + "reserved" : 0 + } + ], + "category" : "internal", + "categoryData" : { + "type" : "internal" + }, + "counterparty" : { + "balanceAccountId" : "BA00000000000000000000002" + }, + "creationDate" : "2024-08-28T13:30:05+02:00", + "direction" : "outgoing", + "events" : [ + { + "bookingDate" : "2024-08-28T13:30:18+02:00", + "id" : "JDRF00000000000000000000000001", + "mutations" : [ + { + "currency" : "EUR", + "received" : 1000 + } + ], + "status" : "received", + "type" : "accounting" + }, + { + "bookingDate" : "2024-08-28T13:30:18+02:00", + "id" : "JDRF00000000000000000000000002", + "mutations" : [ + { + "currency" : "EUR", + "received" : -1000, + "reserved" : 1000 + } + ], + "status" : "authorised", + "type" : "accounting" + }, + { + "bookingDate" : "2024-08-28T13:30:18+02:00", + "id" : "JDRF00000000000000000000000003", + "mutations" : [ + { + "balance" : 1000, + "currency" : "EUR", + "received" : 0, + "reserved" : -1000 + } + ], + "status" : "booked", + "transactionId" : "JDRF00000000000000000000000MEUR", + "type" : "accounting", + "valueDate" : "2024-08-28T14:00:00+02:00" + } + ], + "id" : "2WT1N05XXY7P9XH9", + "reason" : "approved", + "reference" : "Your reference for the transfer", + "sequenceNumber" : 3, + "status" : "booked", + "type" : "internalDirectDebit" }, "environment" : "test", "type" : "balancePlatform.transfer.updated" diff --git a/json/TransferService-v2.json b/json/TransferService-v2.json index c1ea164..ba792ad 100644 --- a/json/TransferService-v2.json +++ b/json/TransferService-v2.json @@ -290,7 +290,7 @@ "Transfers" ], "summary" : "Transfer funds", - "description" : ">Versions 1 and 2 of the Transfers API are deprecated. If you are just starting your implementation, use the latest version.\n\nStarts a request to transfer funds to [balance accounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts), [transfer instruments](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments), or third-party bank accounts. Adyen sends the outcome of the transfer request through webhooks.\n\nTo use this endpoint, you need an additional role for your API credential and transfers must be enabled for the source balance account. Your Adyen contact will set these up for you.", + "description" : ">Versions 1 and 2 of the Transfers API are deprecated. If you are just starting your implementation, use the latest version.\n\nStarts a request to transfer funds to:\n- [Balance accounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts)\n- [Transfer instruments](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments)\n- [Third-party bank accounts](https://docs.adyen.com/payouts/payout-service/pay-out-to-bank-accounts)\n- [Third-party cards](https://docs.adyen.com/payouts/payout-service/pay-out-to-cards)\n\nAdyen sends the outcome of the transfer request through webhooks.\n\nTo use this endpoint:\n- Your API credential must have the **TransferService Webservice Initiate** [role](https://docs.adyen.com/platforms/manage-access/webservice-roles/?tab=transfers_3).\n- The account holder must have the required [capabilities](https://docs.adyen.com/platforms/verification-overview/capabilities).\n\nReach out to your Adyen contact to set up these permissions.", "x-addedInVersion" : "2", "operationId" : "post-transfers", "x-sortIndex" : 1, @@ -1029,6 +1029,7 @@ "x-addedInVersion" : "2", "description" : "Additional information about the status of the transfer.", "enum" : [ + "accountHierarchyNotActive", "amountLimitExceeded", "approved", "balanceAccountTemporarilyBlockedByTransactionRule", @@ -1040,12 +1041,15 @@ "counterpartyBankUnavailable", "declined", "declinedByTransactionRule", + "directDebitNotSupported", "error", "notEnoughBalance", "pendingApproval", + "pendingExecution", "refusedByCounterpartyBank", "routeNotFound", "scaFailed", + "transferInstrumentDoesNotExist", "unknown" ], "type" : "string" @@ -1118,6 +1122,7 @@ "paymentCost", "paymentCostPending", "pendingApproval", + "pendingExecution", "received", "refundPending", "refundReversalPending", diff --git a/json/TransferService-v3.json b/json/TransferService-v3.json index ae2278f..58edfd8 100644 --- a/json/TransferService-v3.json +++ b/json/TransferService-v3.json @@ -626,7 +626,7 @@ "Transfers" ], "summary" : "Transfer funds", - "description" : ">Versions 1 and 2 of the Transfers API are deprecated. If you are just starting your implementation, use the latest version.\n\nStarts a request to transfer funds to [balance accounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts), [transfer instruments](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments), or third-party bank accounts. Adyen sends the outcome of the transfer request through webhooks.\n\nTo use this endpoint, you need an additional role for your API credential and transfers must be enabled for the source balance account. Your Adyen contact will set these up for you.", + "description" : ">Versions 1 and 2 of the Transfers API are deprecated. If you are just starting your implementation, use the latest version.\n\nStarts a request to transfer funds to:\n- [Balance accounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts)\n- [Transfer instruments](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments)\n- [Third-party bank accounts](https://docs.adyen.com/payouts/payout-service/pay-out-to-bank-accounts)\n- [Third-party cards](https://docs.adyen.com/payouts/payout-service/pay-out-to-cards)\n\nAdyen sends the outcome of the transfer request through webhooks.\n\nTo use this endpoint:\n- Your API credential must have the **TransferService Webservice Initiate** [role](https://docs.adyen.com/platforms/manage-access/webservice-roles/?tab=transfers_3).\n- The account holder must have the required [capabilities](https://docs.adyen.com/platforms/verification-overview/capabilities).\n\nReach out to your Adyen contact to set up these permissions.", "x-addedInVersion" : "2", "operationId" : "post-transfers", "x-sortIndex" : 1, @@ -758,6 +758,184 @@ } } }, + "/transfers/approve" : { + "post" : { + "tags" : [ + "Transfers" + ], + "summary" : "Approve initiated transfers", + "description" : "Initiates the approval of a list of transfers that triggered an additional [review](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-review). Adyen sends the outcome of the approval request through webhooks.\n\nTo use this endpoint:\n- Your API credential must have the **TransferService Approve** [role](https://docs.adyen.com/platforms/manage-access/webservice-roles/?tab=transfers_3).\n- The account holder must have the required [capabilities](https://docs.adyen.com/platforms/verification-overview/capabilities).\n\nReach out to your Adyen contact to set up these permissions.", + "x-addedInVersion" : "3", + "operationId" : "post-transfers-approve", + "x-sortIndex" : 2, + "x-methodName" : "approveInitiatedTransfers", + "security" : [ + { + "clientKey" : [ + ] + }, + { + "BasicAuth" : [ + ] + }, + { + "ApiKeyAuth" : [ + ] + } + ], + "requestBody" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ApproveTransfersRequest" + } + } + } + }, + "parameters" : [ + { + "description" : "Header for authenticating through SCA", + "example" : "SCA realm=\"ApproveTransfers\" auth-param1=\"eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl...\"", + "name" : "WWW-Authenticate", + "in" : "header", + "schema" : { + "type" : "string" + } + } + ], + "responses" : { + "200" : { + "description" : "No Content - look at the actual response code for the status of the request. " + }, + "401" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ServiceError" + } + } + }, + "description" : "Unauthorized - authentication required.", + "headers" : { + "auth-param1" : { + "$ref" : "#/components/headers/auth-param1" + } + } + }, + "403" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransferServiceRestServiceError" + } + } + }, + "description" : "Forbidden - insufficient permissions to process the request." + }, + "422" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransferServiceRestServiceError" + } + } + }, + "description" : "Unprocessable Entity - a request validation error." + }, + "500" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransferServiceRestServiceError" + } + } + }, + "description" : "Internal Server Error - the server could not process the request." + } + } + } + }, + "/transfers/cancel" : { + "post" : { + "tags" : [ + "Transfers" + ], + "summary" : "Cancel initiated transfers", + "description" : "Initiates the cancellation of a list of transfers that triggered an additional [review](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-review). Adyen sends the outcome of the cancel request through webhooks.\n\nTo use this endpoint:\n- Your API credential must have the **TransferService Approve** [role](https://docs.adyen.com/platforms/manage-access/webservice-roles/?tab=transfers_3).\n- The account holder must have the required [capabilities](https://docs.adyen.com/platforms/verification-overview/capabilities).\n\nReach out to your Adyen contact to set up these permissions.", + "x-addedInVersion" : "3", + "operationId" : "post-transfers-cancel", + "x-sortIndex" : 3, + "x-methodName" : "cancelInitiatedTransfers", + "security" : [ + { + "clientKey" : [ + ] + }, + { + "BasicAuth" : [ + ] + }, + { + "ApiKeyAuth" : [ + ] + } + ], + "requestBody" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/CancelTransfersRequest" + } + } + } + }, + "responses" : { + "200" : { + "description" : "No Content - look at the actual response code for the status of the request. " + }, + "401" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransferServiceRestServiceError" + } + } + }, + "description" : "Unauthorized - authentication required." + }, + "403" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransferServiceRestServiceError" + } + } + }, + "description" : "Forbidden - insufficient permissions to process the request." + }, + "422" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransferServiceRestServiceError" + } + } + }, + "description" : "Unprocessable Entity - a request validation error." + }, + "500" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransferServiceRestServiceError" + } + } + }, + "description" : "Internal Server Error - the server could not process the request." + } + } + } + }, "/transfers/{transferId}/returns" : { "post" : { "tags" : [ @@ -767,7 +945,7 @@ "description" : "Initiates the return of previously transferred funds without creating a new `transferId`.", "x-addedInVersion" : "3", "operationId" : "post-transfers-transferId-returns", - "x-sortIndex" : 2, + "x-sortIndex" : 4, "x-methodName" : "returnTransfer", "security" : [ { @@ -965,6 +1143,19 @@ ], "type" : "object" }, + "ApproveTransfersRequest" : { + "additionalProperties" : false, + "properties" : { + "transferIds" : { + "description" : "Contains the unique identifiers of the transfers that you want to approve.", + "items" : { + "type" : "string" + }, + "type" : "array" + } + }, + "type" : "object" + }, "BRLocalAccountIdentification" : { "additionalProperties" : false, "properties" : { @@ -1154,6 +1345,19 @@ ], "type" : "object" }, + "CancelTransfersRequest" : { + "additionalProperties" : false, + "properties" : { + "transferIds" : { + "description" : "Contains the unique identifiers of the transfers that you want to cancel.", + "items" : { + "type" : "string" + }, + "type" : "array" + } + }, + "type" : "object" + }, "CapitalBalance" : { "additionalProperties" : false, "properties" : { @@ -1438,6 +1642,30 @@ ], "type" : "object" }, + "DirectDebitInformation" : { + "additionalProperties" : false, + "properties" : { + "dateOfSignature" : { + "description" : "The date when the direct debit mandate was accepted by your user, in [ISO-8601](https://www.w3.org/TR/NOTE-datetime) format.", + "format" : "date-time", + "type" : "string" + }, + "dueDate" : { + "description" : "The date when the funds are deducted from your user's balance account.", + "format" : "date-time", + "type" : "string" + }, + "mandateId" : { + "description" : "Your unique identifier for the direct debit mandate.", + "type" : "string" + }, + "sequenceType" : { + "description" : "Identifies the direct debit transfer's type.\nPossible values: **OneOff**, **First**, **Recurring**, **Final**.", + "type" : "string" + } + }, + "type" : "object" + }, "Fee" : { "additionalProperties" : false, "properties" : { @@ -2345,6 +2573,11 @@ "description" : "Your description for the transfer. It is used by most banks as the transfer description. We recommend sending a maximum of 140 characters, otherwise the description may be truncated.\n\nSupported characters: **[a-z] [A-Z] [0-9] / - ?** **: ( ) . , ' + Space**\n\nSupported characters for **regular** and **fast** transfers to a US counterparty: **[a-z] [A-Z] [0-9] & $ % # @** **~ = + - _ ' \" ! ?**", "type" : "string" }, + "directDebitInformation" : { + "x-addedInVersion" : "3", + "description" : "The details of the direct debit.", + "$ref" : "#/components/schemas/DirectDebitInformation" + }, "direction" : { "x-addedInVersion" : "2", "description" : "The direction of the transfer.\n\nPossible values: **incoming**, **outgoing**.", @@ -2388,6 +2621,7 @@ "x-addedInVersion" : "2", "description" : "Additional information about the status of the transfer.", "enum" : [ + "accountHierarchyNotActive", "amountLimitExceeded", "approved", "balanceAccountTemporarilyBlockedByTransactionRule", @@ -2399,12 +2633,15 @@ "counterpartyBankUnavailable", "declined", "declinedByTransactionRule", + "directDebitNotSupported", "error", "notEnoughBalance", "pendingApproval", + "pendingExecution", "refusedByCounterpartyBank", "routeNotFound", "scaFailed", + "transferInstrumentDoesNotExist", "unknown" ], "type" : "string" @@ -2420,6 +2657,11 @@ "description" : " A reference that is sent to the recipient. This reference is also sent in all webhooks related to the transfer, so you can use it to track statuses for both the source and recipient of funds.\n\n Supported characters: **a-z**, **A-Z**, **0-9**.The maximum length depends on the `category`.\n\n - **internal**: 80 characters\n\n- **bank**: 35 characters when transferring to an IBAN, 15 characters for others.", "type" : "string" }, + "review" : { + "x-addedInVersion" : "3", + "description" : "Contains status updates related to additional reviews.", + "$ref" : "#/components/schemas/TransferReview" + }, "status" : { "x-addedInVersion" : "2", "description" : "The result of the transfer.\n\n For example, **authorised**, **refused**, or **error**.", @@ -2476,6 +2718,7 @@ "paymentCost", "paymentCostPending", "pendingApproval", + "pendingExecution", "received", "refundPending", "refundReversalPending", @@ -2610,6 +2853,11 @@ "description" : " A reference that is sent to the recipient. This reference is also sent in all webhooks related to the transfer, so you can use it to track statuses for both parties involved in the funds movement.\n\n Supported characters: **a-z**, **A-Z**, **0-9**. The maximum length depends on the `category`.\n\n- **internal**: 80 characters\n\n- **bank**: 35 characters when transferring to an IBAN, 15 characters for others.", "type" : "string" }, + "review" : { + "x-addedInVersion" : "3", + "description" : "Contains information required for triggering transfer reviews. ", + "$ref" : "#/components/schemas/TransferRequestReview" + }, "type" : { "x-addedInVersion" : "3", "description" : "The type of transfer.\n\nPossible values:\n\n - **bankTransfer**: for push transfers to a transfer instrument or a bank account. The `category` must be **bank**.\n- **internalTransfer**: for push transfers between balance accounts. The `category` must be **internal**.\n- **internalDirectDebit**: for pull transfers (direct debits) between balance accounts. The `category` must be **internal**. \n\n", @@ -2633,6 +2881,46 @@ ], "type" : "object" }, + "TransferRequestReview" : { + "additionalProperties" : false, + "properties" : { + "numberOfApprovalsRequired" : { + "description" : "Specifies the number of [approvals](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) required to process the transfer.", + "format" : "int32", + "type" : "integer" + }, + "scaOnApproval" : { + "description" : "Specifies whether you will initiate Strong Customer Authentication (SCA) in thePOST [/transfers/approve](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) request.\n\nOnly applies to transfers made with an Adyen [business account](https://docs.adyen.com/platforms/business-accounts).", + "type" : "boolean" + } + }, + "type" : "object" + }, + "TransferReview" : { + "additionalProperties" : false, + "properties" : { + "numberOfApprovalsCompleted" : { + "description" : "Shows the number of approvals completed for the transfer.", + "format" : "int32", + "type" : "integer" + }, + "numberOfApprovalsRequired" : { + "description" : "Shows the number of [approvals](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) required to process the transfer.", + "format" : "int32", + "type" : "integer" + }, + "scaOnApproval" : { + "description" : "Shows the status of the Strong Customer Authentication (SCA) process.\n\nPossible values: **required**, **completed**, **notApplicable**.", + "enum" : [ + "completed", + "notApplicable", + "required" + ], + "type" : "string" + } + }, + "type" : "object" + }, "TransferServiceRestServiceError" : { "additionalProperties" : false, "properties" : { diff --git a/json/TransferService-v4.json b/json/TransferService-v4.json index 5ef29c3..6429cc7 100644 --- a/json/TransferService-v4.json +++ b/json/TransferService-v4.json @@ -629,7 +629,7 @@ "description" : "Returns all the transfers related to a balance account, account holder, or balance platform.\n\nWhen making this request, you must include at least one of the following:\n- `balanceAccountId`\n- `accountHolderId`\n- `balancePlatform`.\n\nThis endpoint supports cursor-based pagination. The response returns the first page of results, and returns links to the next and previous pages when applicable. You can use the links to page through the results.\n\n", "x-addedInVersion" : "4", "operationId" : "get-transfers", - "x-sortIndex" : 3, + "x-sortIndex" : 5, "x-methodName" : "getAllTransfers", "security" : [ { @@ -843,7 +843,7 @@ "Transfers" ], "summary" : "Transfer funds", - "description" : ">Versions 1 and 2 of the Transfers API are deprecated. If you are just starting your implementation, use the latest version.\n\nStarts a request to transfer funds to [balance accounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts), [transfer instruments](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments), or third-party bank accounts. Adyen sends the outcome of the transfer request through webhooks.\n\nTo use this endpoint, you need an additional role for your API credential and transfers must be enabled for the source balance account. Your Adyen contact will set these up for you.", + "description" : ">Versions 1 and 2 of the Transfers API are deprecated. If you are just starting your implementation, use the latest version.\n\nStarts a request to transfer funds to:\n- [Balance accounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts)\n- [Transfer instruments](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments)\n- [Third-party bank accounts](https://docs.adyen.com/payouts/payout-service/pay-out-to-bank-accounts)\n- [Third-party cards](https://docs.adyen.com/payouts/payout-service/pay-out-to-cards)\n\nAdyen sends the outcome of the transfer request through webhooks.\n\nTo use this endpoint:\n- Your API credential must have the **TransferService Webservice Initiate** [role](https://docs.adyen.com/platforms/manage-access/webservice-roles/?tab=transfers_3).\n- The account holder must have the required [capabilities](https://docs.adyen.com/platforms/verification-overview/capabilities).\n\nReach out to your Adyen contact to set up these permissions.", "x-addedInVersion" : "2", "operationId" : "post-transfers", "x-sortIndex" : 1, @@ -975,16 +975,194 @@ } } }, + "/transfers/approve" : { + "post" : { + "tags" : [ + "Transfers" + ], + "summary" : "Approve initiated transfers", + "description" : "Initiates the approval of a list of transfers that triggered an additional [review](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-review). Adyen sends the outcome of the approval request through webhooks.\n\nTo use this endpoint:\n- Your API credential must have the **TransferService Approve** [role](https://docs.adyen.com/platforms/manage-access/webservice-roles/?tab=transfers_3).\n- The account holder must have the required [capabilities](https://docs.adyen.com/platforms/verification-overview/capabilities).\n\nReach out to your Adyen contact to set up these permissions.", + "x-addedInVersion" : "3", + "operationId" : "post-transfers-approve", + "x-sortIndex" : 2, + "x-methodName" : "approveInitiatedTransfers", + "security" : [ + { + "clientKey" : [ + ] + }, + { + "BasicAuth" : [ + ] + }, + { + "ApiKeyAuth" : [ + ] + } + ], + "requestBody" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ApproveTransfersRequest" + } + } + } + }, + "parameters" : [ + { + "description" : "Header for authenticating through SCA", + "example" : "SCA realm=\"ApproveTransfers\" auth-param1=\"eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl...\"", + "name" : "WWW-Authenticate", + "in" : "header", + "schema" : { + "type" : "string" + } + } + ], + "responses" : { + "200" : { + "description" : "No Content - look at the actual response code for the status of the request. " + }, + "401" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ServiceError" + } + } + }, + "description" : "Unauthorized - authentication required.", + "headers" : { + "auth-param1" : { + "$ref" : "#/components/headers/auth-param1" + } + } + }, + "403" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransferServiceRestServiceError" + } + } + }, + "description" : "Forbidden - insufficient permissions to process the request." + }, + "422" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransferServiceRestServiceError" + } + } + }, + "description" : "Unprocessable Entity - a request validation error." + }, + "500" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransferServiceRestServiceError" + } + } + }, + "description" : "Internal Server Error - the server could not process the request." + } + } + } + }, + "/transfers/cancel" : { + "post" : { + "tags" : [ + "Transfers" + ], + "summary" : "Cancel initiated transfers", + "description" : "Initiates the cancellation of a list of transfers that triggered an additional [review](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-review). Adyen sends the outcome of the cancel request through webhooks.\n\nTo use this endpoint:\n- Your API credential must have the **TransferService Approve** [role](https://docs.adyen.com/platforms/manage-access/webservice-roles/?tab=transfers_3).\n- The account holder must have the required [capabilities](https://docs.adyen.com/platforms/verification-overview/capabilities).\n\nReach out to your Adyen contact to set up these permissions.", + "x-addedInVersion" : "3", + "operationId" : "post-transfers-cancel", + "x-sortIndex" : 3, + "x-methodName" : "cancelInitiatedTransfers", + "security" : [ + { + "clientKey" : [ + ] + }, + { + "BasicAuth" : [ + ] + }, + { + "ApiKeyAuth" : [ + ] + } + ], + "requestBody" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/CancelTransfersRequest" + } + } + } + }, + "responses" : { + "200" : { + "description" : "No Content - look at the actual response code for the status of the request. " + }, + "401" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransferServiceRestServiceError" + } + } + }, + "description" : "Unauthorized - authentication required." + }, + "403" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransferServiceRestServiceError" + } + } + }, + "description" : "Forbidden - insufficient permissions to process the request." + }, + "422" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransferServiceRestServiceError" + } + } + }, + "description" : "Unprocessable Entity - a request validation error." + }, + "500" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransferServiceRestServiceError" + } + } + }, + "description" : "Internal Server Error - the server could not process the request." + } + } + } + }, "/transfers/{id}" : { "get" : { "tags" : [ "Transfers" ], "summary" : "Get a transfer", - "description" : "Returns a transfer.", + "description" : "Returns the details of a specified transfer.", "x-addedInVersion" : "4", "operationId" : "get-transfers-id", - "x-sortIndex" : 4, + "x-sortIndex" : 6, "x-methodName" : "getTransfer", "security" : [ { @@ -1079,7 +1257,7 @@ "description" : "Initiates the return of previously transferred funds without creating a new `transferId`.", "x-addedInVersion" : "3", "operationId" : "post-transfers-transferId-returns", - "x-sortIndex" : 2, + "x-sortIndex" : 4, "x-methodName" : "returnTransfer", "security" : [ { @@ -1315,6 +1493,19 @@ }, "type" : "object" }, + "ApproveTransfersRequest" : { + "additionalProperties" : false, + "properties" : { + "transferIds" : { + "description" : "Contains the unique identifiers of the transfers that you want to approve.", + "items" : { + "type" : "string" + }, + "type" : "array" + } + }, + "type" : "object" + }, "BRLocalAccountIdentification" : { "additionalProperties" : false, "properties" : { @@ -1560,6 +1751,19 @@ ], "type" : "object" }, + "CancelTransfersRequest" : { + "additionalProperties" : false, + "properties" : { + "transferIds" : { + "description" : "Contains the unique identifiers of the transfers that you want to cancel.", + "items" : { + "type" : "string" + }, + "type" : "array" + } + }, + "type" : "object" + }, "CapitalBalance" : { "additionalProperties" : false, "properties" : { @@ -1869,6 +2073,30 @@ ], "type" : "object" }, + "DirectDebitInformation" : { + "additionalProperties" : false, + "properties" : { + "dateOfSignature" : { + "description" : "The date when the direct debit mandate was accepted by your user, in [ISO-8601](https://www.w3.org/TR/NOTE-datetime) format.", + "format" : "date-time", + "type" : "string" + }, + "dueDate" : { + "description" : "The date when the funds are deducted from your user's balance account.", + "format" : "date-time", + "type" : "string" + }, + "mandateId" : { + "description" : "Your unique identifier for the direct debit mandate.", + "type" : "string" + }, + "sequenceType" : { + "description" : "Identifies the direct debit transfer's type.\nPossible values: **OneOff**, **First**, **Recurring**, **Final**.", + "type" : "string" + } + }, + "type" : "object" + }, "EstimationTrackingData" : { "additionalProperties" : false, "properties" : { @@ -2295,6 +2523,7 @@ "paymentCost", "paymentCostPending", "pendingApproval", + "pendingExecution", "received", "refundPending", "refundReversalPending", @@ -3140,6 +3369,11 @@ "description" : "Your description for the transfer. It is used by most banks as the transfer description. We recommend sending a maximum of 140 characters, otherwise the description may be truncated.\n\nSupported characters: **[a-z] [A-Z] [0-9] / - ?** **: ( ) . , ' + Space**\n\nSupported characters for **regular** and **fast** transfers to a US counterparty: **[a-z] [A-Z] [0-9] & $ % # @** **~ = + - _ ' \" ! ?**", "type" : "string" }, + "directDebitInformation" : { + "x-addedInVersion" : "3", + "description" : "The details of the direct debit.", + "$ref" : "#/components/schemas/DirectDebitInformation" + }, "direction" : { "x-addedInVersion" : "2", "description" : "The direction of the transfer.\n\nPossible values: **incoming**, **outgoing**.", @@ -3162,6 +3396,7 @@ "x-addedInVersion" : "2", "description" : "Additional information about the status of the transfer.", "enum" : [ + "accountHierarchyNotActive", "amountLimitExceeded", "approved", "balanceAccountTemporarilyBlockedByTransactionRule", @@ -3173,12 +3408,15 @@ "counterpartyBankUnavailable", "declined", "declinedByTransactionRule", + "directDebitNotSupported", "error", "notEnoughBalance", "pendingApproval", + "pendingExecution", "refusedByCounterpartyBank", "routeNotFound", "scaFailed", + "transferInstrumentDoesNotExist", "unknown" ], "type" : "string" @@ -3194,6 +3432,11 @@ "description" : " A reference that is sent to the recipient. This reference is also sent in all webhooks related to the transfer, so you can use it to track statuses for both the source and recipient of funds.\n\n Supported characters: **a-z**, **A-Z**, **0-9**.The maximum length depends on the `category`.\n\n - **internal**: 80 characters\n\n- **bank**: 35 characters when transferring to an IBAN, 15 characters for others.", "type" : "string" }, + "review" : { + "x-addedInVersion" : "3", + "description" : "Contains status updates related to additional reviews.", + "$ref" : "#/components/schemas/TransferReview" + }, "status" : { "x-addedInVersion" : "2", "description" : "The result of the transfer.\n\n For example, **authorised**, **refused**, or **error**.", @@ -3250,6 +3493,7 @@ "paymentCost", "paymentCostPending", "pendingApproval", + "pendingExecution", "received", "refundPending", "refundReversalPending", @@ -3397,6 +3641,11 @@ "description" : "Your description for the transfer. It is used by most banks as the transfer description. We recommend sending a maximum of 140 characters, otherwise the description may be truncated.\n\nSupported characters: **[a-z] [A-Z] [0-9] / - ?** **: ( ) . , ' + Space**\n\nSupported characters for **regular** and **fast** transfers to a US counterparty: **[a-z] [A-Z] [0-9] & $ % # @** **~ = + - _ ' \" ! ?**", "type" : "string" }, + "directDebitInformation" : { + "x-addedInVersion" : "3", + "description" : "The details of the direct debit.", + "$ref" : "#/components/schemas/DirectDebitInformation" + }, "direction" : { "x-addedInVersion" : "2", "description" : "The direction of the transfer.\n\nPossible values: **incoming**, **outgoing**.", @@ -3427,6 +3676,7 @@ "x-addedInVersion" : "2", "description" : "Additional information about the status of the transfer.", "enum" : [ + "accountHierarchyNotActive", "amountLimitExceeded", "approved", "balanceAccountTemporarilyBlockedByTransactionRule", @@ -3438,12 +3688,15 @@ "counterpartyBankUnavailable", "declined", "declinedByTransactionRule", + "directDebitNotSupported", "error", "notEnoughBalance", "pendingApproval", + "pendingExecution", "refusedByCounterpartyBank", "routeNotFound", "scaFailed", + "transferInstrumentDoesNotExist", "unknown" ], "type" : "string" @@ -3459,6 +3712,11 @@ "description" : " A reference that is sent to the recipient. This reference is also sent in all webhooks related to the transfer, so you can use it to track statuses for both the source and recipient of funds.\n\n Supported characters: **a-z**, **A-Z**, **0-9**.The maximum length depends on the `category`.\n\n - **internal**: 80 characters\n\n- **bank**: 35 characters when transferring to an IBAN, 15 characters for others.", "type" : "string" }, + "review" : { + "x-addedInVersion" : "3", + "description" : "Contains status updates related to additional reviews.", + "$ref" : "#/components/schemas/TransferReview" + }, "sequenceNumber" : { "x-addedInVersion" : "3", "description" : "The sequence number of the transfer webhook. The numbers start from 1 and increase with each new webhook for a specific transfer.\n\nThe sequence number can help you restore the correct sequence of events even if they arrive out of order.", @@ -3521,6 +3779,7 @@ "paymentCost", "paymentCostPending", "pendingApproval", + "pendingExecution", "received", "refundPending", "refundReversalPending", @@ -3676,6 +3935,7 @@ "x-addedInVersion" : "3", "description" : "The reason for the transfer status.", "enum" : [ + "accountHierarchyNotActive", "amountLimitExceeded", "approved", "balanceAccountTemporarilyBlockedByTransactionRule", @@ -3687,12 +3947,15 @@ "counterpartyBankUnavailable", "declined", "declinedByTransactionRule", + "directDebitNotSupported", "error", "notEnoughBalance", "pendingApproval", + "pendingExecution", "refusedByCounterpartyBank", "routeNotFound", "scaFailed", + "transferInstrumentDoesNotExist", "unknown" ], "type" : "string" @@ -3753,6 +4016,7 @@ "paymentCost", "paymentCostPending", "pendingApproval", + "pendingExecution", "received", "refundPending", "refundReversalPending", @@ -3893,6 +4157,11 @@ "description" : " A reference that is sent to the recipient. This reference is also sent in all webhooks related to the transfer, so you can use it to track statuses for both parties involved in the funds movement.\n\n Supported characters: **a-z**, **A-Z**, **0-9**. The maximum length depends on the `category`.\n\n- **internal**: 80 characters\n\n- **bank**: 35 characters when transferring to an IBAN, 15 characters for others.", "type" : "string" }, + "review" : { + "x-addedInVersion" : "3", + "description" : "Contains information required for triggering transfer reviews. ", + "$ref" : "#/components/schemas/TransferRequestReview" + }, "type" : { "x-addedInVersion" : "3", "description" : "The type of transfer.\n\nPossible values:\n\n - **bankTransfer**: for push transfers to a transfer instrument or a bank account. The `category` must be **bank**.\n- **internalTransfer**: for push transfers between balance accounts. The `category` must be **internal**.\n- **internalDirectDebit**: for pull transfers (direct debits) between balance accounts. The `category` must be **internal**. \n\n", @@ -3990,6 +4259,46 @@ }, "type" : "object" }, + "TransferRequestReview" : { + "additionalProperties" : false, + "properties" : { + "numberOfApprovalsRequired" : { + "description" : "Specifies the number of [approvals](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) required to process the transfer.", + "format" : "int32", + "type" : "integer" + }, + "scaOnApproval" : { + "description" : "Specifies whether you will initiate Strong Customer Authentication (SCA) in thePOST [/transfers/approve](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) request.\n\nOnly applies to transfers made with an Adyen [business account](https://docs.adyen.com/platforms/business-accounts).", + "type" : "boolean" + } + }, + "type" : "object" + }, + "TransferReview" : { + "additionalProperties" : false, + "properties" : { + "numberOfApprovalsCompleted" : { + "description" : "Shows the number of approvals completed for the transfer.", + "format" : "int32", + "type" : "integer" + }, + "numberOfApprovalsRequired" : { + "description" : "Shows the number of [approvals](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) required to process the transfer.", + "format" : "int32", + "type" : "integer" + }, + "scaOnApproval" : { + "description" : "Shows the status of the Strong Customer Authentication (SCA) process.\n\nPossible values: **required**, **completed**, **notApplicable**.", + "enum" : [ + "completed", + "notApplicable", + "required" + ], + "type" : "string" + } + }, + "type" : "object" + }, "TransferServiceRestServiceError" : { "additionalProperties" : false, "properties" : { diff --git a/yaml/BalancePlatformTransferNotification-v3.yaml b/yaml/BalancePlatformTransferNotification-v3.yaml index a4f9ad4..1453424 100644 --- a/yaml/BalancePlatformTransferNotification-v3.yaml +++ b/yaml/BalancePlatformTransferNotification-v3.yaml @@ -516,6 +516,28 @@ components: - accountNumber - bankCode type: object + DirectDebitInformation: + additionalProperties: false + properties: + dateOfSignature: + description: The date when the direct debit mandate was accepted by your + user, in [ISO-8601](https://www.w3.org/TR/NOTE-datetime) format. + format: date-time + type: string + dueDate: + description: The date when the funds are deducted from your user's balance + account. + format: date-time + type: string + mandateId: + description: Your unique identifier for the direct debit mandate. + type: string + sequenceType: + description: 'Identifies the direct debit transfer''s type. + + Possible values: **OneOff**, **First**, **Recurring**, **Final**.' + type: string + type: object EstimationTrackingData: additionalProperties: false properties: @@ -731,6 +753,7 @@ components: - paymentCost - paymentCostPending - pendingApproval + - pendingExecution - received - refundPending - refundReversalPending @@ -1158,6 +1181,10 @@ components: Supported characters for **regular** and **fast** transfers to a US counterparty: **[a-z] [A-Z] [0-9] & $ % # @** **~ = + - _ '' " ! ?**' type: string + directDebitInformation: + x-addedInVersion: '3' + description: The details of the direct debit. + $ref: '#/components/schemas/DirectDebitInformation' direction: x-addedInVersion: '2' description: 'The direction of the transfer. @@ -1347,6 +1374,7 @@ components: x-addedInVersion: '2' description: Additional information about the status of the transfer. enum: + - accountHierarchyNotActive - amountLimitExceeded - approved - balanceAccountTemporarilyBlockedByTransactionRule @@ -1358,12 +1386,15 @@ components: - counterpartyBankUnavailable - declined - declinedByTransactionRule + - directDebitNotSupported - error - notEnoughBalance - pendingApproval + - pendingExecution - refusedByCounterpartyBank - routeNotFound - scaFailed + - transferInstrumentDoesNotExist - unknown type: string reference: @@ -1391,6 +1422,10 @@ components: description: If you are using relayed authorisation, this object contains information from the relayed authorisation response from your server. $ref: '#/components/schemas/RelayedAuthorisationData' + review: + x-addedInVersion: '3' + description: Contains status updates related to additional reviews. + $ref: '#/components/schemas/TransferReview' sequenceNumber: x-addedInVersion: '3' description: 'The sequence number of the transfer webhook. The numbers start @@ -1458,6 +1493,7 @@ components: - paymentCost - paymentCostPending - pendingApproval + - pendingExecution - received - refundPending - refundReversalPending @@ -1602,6 +1638,7 @@ components: x-addedInVersion: '3' description: The reason for the transfer status. enum: + - accountHierarchyNotActive - amountLimitExceeded - approved - balanceAccountTemporarilyBlockedByTransactionRule @@ -1613,12 +1650,15 @@ components: - counterpartyBankUnavailable - declined - declinedByTransactionRule + - directDebitNotSupported - error - notEnoughBalance - pendingApproval + - pendingExecution - refusedByCounterpartyBank - routeNotFound - scaFailed + - transferInstrumentDoesNotExist - unknown type: string schemeTraceID: @@ -1685,6 +1725,7 @@ components: - paymentCost - paymentCostPending - pendingApproval + - pendingExecution - received - refundPending - refundReversalPending @@ -1808,6 +1849,30 @@ components: description: The type of the validation fact. type: string type: object + TransferReview: + additionalProperties: false + properties: + numberOfApprovalsCompleted: + description: Shows the number of approvals completed for the transfer. + format: int32 + type: integer + numberOfApprovalsRequired: + description: Shows the number of [approvals](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) + required to process the transfer. + format: int32 + type: integer + scaOnApproval: + description: 'Shows the status of the Strong Customer Authentication (SCA) + process. + + + Possible values: **required**, **completed**, **notApplicable**.' + enum: + - completed + - notApplicable + - required + type: string + type: object UKLocalAccountIdentification: additionalProperties: false properties: diff --git a/yaml/BalancePlatformTransferNotification-v4.yaml b/yaml/BalancePlatformTransferNotification-v4.yaml index 307afe1..03ed1c2 100644 --- a/yaml/BalancePlatformTransferNotification-v4.yaml +++ b/yaml/BalancePlatformTransferNotification-v4.yaml @@ -66,14 +66,24 @@ webhooks: content: application/json: examples: - balancePlatform-transfer-updated-authorised-incoming-internal: - $ref: '#/components/examples/post-balancePlatform.transfer.updated-balancePlatform-transfer-updated-authorised-incoming-internal' - balancePlatform-transfer-updated-authorised-outgoing-external: - $ref: '#/components/examples/post-balancePlatform.transfer.updated-balancePlatform-transfer-updated-authorised-outgoing-external' - balancePlatform-transfer-updated-booked-incoming-internal: - $ref: '#/components/examples/post-balancePlatform.transfer.updated-balancePlatform-transfer-updated-booked-incoming-internal' - balancePlatform-transfer-updated-booked-outgoing-external: - $ref: '#/components/examples/post-balancePlatform.transfer.updated-balancePlatform-transfer-updated-booked-outgoing-external' + 01.payout-authorized: + $ref: '#/components/examples/post-balancePlatform.transfer.updated-01.payout-authorized' + 02.payout-booked: + $ref: '#/components/examples/post-balancePlatform.transfer.updated-02.payout-booked' + 03.internal-authorised: + $ref: '#/components/examples/post-balancePlatform.transfer.updated-03.internal-authorised' + 04.internal-booked: + $ref: '#/components/examples/post-balancePlatform.transfer.updated-04.internal-booked' + 05.directDebit-booked: + $ref: '#/components/examples/post-balancePlatform.transfer.updated-05.directDebit-booked' + 06.directDebit-cancelled: + $ref: '#/components/examples/post-balancePlatform.transfer.updated-06.directDebit-cancelled' + 07.directDebit-failed: + $ref: '#/components/examples/post-balancePlatform.transfer.updated-07.directDebit-failed' + 08.internalDirectDebit-incoming-booked: + $ref: '#/components/examples/post-balancePlatform.transfer.updated-08.internalDirectDebit-incoming-booked' + 09.internalDirectDebit-outgoing-booked: + $ref: '#/components/examples/post-balancePlatform.transfer.updated-09.internalDirectDebit-outgoing-booked' schema: $ref: '#/components/schemas/TransferNotificationRequest' responses: @@ -578,6 +588,28 @@ components: - accountNumber - bankCode type: object + DirectDebitInformation: + additionalProperties: false + properties: + dateOfSignature: + description: The date when the direct debit mandate was accepted by your + user, in [ISO-8601](https://www.w3.org/TR/NOTE-datetime) format. + format: date-time + type: string + dueDate: + description: The date when the funds are deducted from your user's balance + account. + format: date-time + type: string + mandateId: + description: Your unique identifier for the direct debit mandate. + type: string + sequenceType: + description: 'Identifies the direct debit transfer''s type. + + Possible values: **OneOff**, **First**, **Recurring**, **Final**.' + type: string + type: object EstimationTrackingData: additionalProperties: false properties: @@ -883,6 +915,7 @@ components: - paymentCost - paymentCostPending - pendingApproval + - pendingExecution - received - refundPending - refundReversalPending @@ -1367,6 +1400,10 @@ components: Supported characters for **regular** and **fast** transfers to a US counterparty: **[a-z] [A-Z] [0-9] & $ % # @** **~ = + - _ '' " ! ?**' type: string + directDebitInformation: + x-addedInVersion: '3' + description: The details of the direct debit. + $ref: '#/components/schemas/DirectDebitInformation' direction: x-addedInVersion: '2' description: 'The direction of the transfer. @@ -1396,6 +1433,7 @@ components: x-addedInVersion: '2' description: Additional information about the status of the transfer. enum: + - accountHierarchyNotActive - amountLimitExceeded - approved - balanceAccountTemporarilyBlockedByTransactionRule @@ -1407,12 +1445,15 @@ components: - counterpartyBankUnavailable - declined - declinedByTransactionRule + - directDebitNotSupported - error - notEnoughBalance - pendingApproval + - pendingExecution - refusedByCounterpartyBank - routeNotFound - scaFailed + - transferInstrumentDoesNotExist - unknown type: string reference: @@ -1431,6 +1472,10 @@ components: \ on the `category`.\n\n - **internal**: 80 characters\n\n- **bank**:\ \ 35 characters when transferring to an IBAN, 15 characters for others." type: string + review: + x-addedInVersion: '3' + description: Contains status updates related to additional reviews. + $ref: '#/components/schemas/TransferReview' sequenceNumber: x-addedInVersion: '3' description: 'The sequence number of the transfer webhook. The numbers start @@ -1498,6 +1543,7 @@ components: - paymentCost - paymentCostPending - pendingApproval + - pendingExecution - received - refundPending - refundReversalPending @@ -1628,6 +1674,7 @@ components: x-addedInVersion: '3' description: The reason for the transfer status. enum: + - accountHierarchyNotActive - amountLimitExceeded - approved - balanceAccountTemporarilyBlockedByTransactionRule @@ -1639,12 +1686,15 @@ components: - counterpartyBankUnavailable - declined - declinedByTransactionRule + - directDebitNotSupported - error - notEnoughBalance - pendingApproval + - pendingExecution - refusedByCounterpartyBank - routeNotFound - scaFailed + - transferInstrumentDoesNotExist - unknown type: string status: @@ -1703,6 +1753,7 @@ components: - paymentCost - paymentCostPending - pendingApproval + - pendingExecution - received - refundPending - refundReversalPending @@ -1826,6 +1877,30 @@ components: description: The type of the validation fact. type: string type: object + TransferReview: + additionalProperties: false + properties: + numberOfApprovalsCompleted: + description: Shows the number of approvals completed for the transfer. + format: int32 + type: integer + numberOfApprovalsRequired: + description: Shows the number of [approvals](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) + required to process the transfer. + format: int32 + type: integer + scaOnApproval: + description: 'Shows the status of the Strong Customer Authentication (SCA) + process. + + + Possible values: **required**, **completed**, **notApplicable**.' + enum: + - completed + - notApplicable + - required + type: string + type: object UKLocalAccountIdentification: additionalProperties: false properties: @@ -1979,59 +2054,65 @@ components: type: bankTransfer environment: test type: balancePlatform.transfer.created - post-balancePlatform.transfer.updated-balancePlatform-transfer-updated-authorised-incoming-internal: - summary: Authorized incoming internal transfer - description: Example webhook of an authorised incoming transfer + post-balancePlatform.transfer.updated-01.payout-authorized: + summary: Authorized payout to a transfer instrument + description: Example webhook of an authorised outgoing bank transfer value: data: - id: 2WT1N05XXY7P9XH9 - type: internalTransfer accountHolder: - description: Your description of the account holder of the target balance - account - id: AH00000000000000000000002 + description: Your description of the account holder + id: AH00000000000000000000001 reference: Your reference for the account holder amount: currency: EUR - value: 1000 + value: 10000 balanceAccount: - description: Your description of the target balance account - id: BA00000000000000000000002 + description: Your description of the balance account from where the amount + is debited + id: BA00000000000000000000001 + reference: Your reference for the balance account balancePlatform: YOUR_BALANCE_PLATFORM balances: - currency: EUR received: 0 - reserved: 1000 - category: internal + reserved: -10000 + category: bank + categoryData: + priority: regular + type: bank creationDate: '2023-02-28T13:30:05+02:00' - description: Your description of the transfer - direction: incoming + description: Your user description of the transfer + direction: outgoing events: - bookingDate: '2023-02-28T13:30:18+02:00' - id: JDRF00000000000000000000000001 + id: EVJN00000000000000000000000001 mutations: - currency: EUR - received: 1000 + received: -10000 status: received type: accounting - bookingDate: '2023-02-28T13:30:18+02:00' - id: JDRF00000000000000000000000002 + id: EVJN00000000000000000000000002 mutations: - currency: EUR - received: -1000 - reserved: 1000 + received: 10000 + reserved: -10000 status: authorised type: accounting + id: 6JKRLZ8LOT47J7RY reason: approved - reference: Your reference for the transfer - referenceForBeneficiary: Your-reference-for-the-recipient-of-the-transfer-request + reference: Your user reference for the transfer + referenceForBeneficiary: Your user reference for the beneficiary sequenceNumber: 2 + transactionRulesResult: + allHardBlockRulesPassed: true status: authorised + type: bankTransfer environment: test type: balancePlatform.transfer.updated - post-balancePlatform.transfer.updated-balancePlatform-transfer-updated-authorised-outgoing-external: - summary: Authorized payout to a transfer instrument - description: Example webhook of an authorised outgoing bank transfer + post-balancePlatform.transfer.updated-02.payout-booked: + summary: Booked payout to a transfer instrument + description: Example webhook of a booked outgoing bank transfer value: data: accountHolder: @@ -2048,13 +2129,16 @@ components: reference: Your reference for the balance account balancePlatform: YOUR_BALANCE_PLATFORM balances: - - currency: EUR + - balance: -10000 + currency: EUR received: 0 - reserved: -10000 + reserved: 0 category: bank categoryData: priority: regular type: bank + counterparty: + transferInstrumentId: SE00000000000000000000001 creationDate: '2023-02-28T13:30:05+02:00' description: Your user description of the transfer direction: outgoing @@ -2074,18 +2158,79 @@ components: reserved: -10000 status: authorised type: accounting + - bookingDate: '2023-02-28T13:30:18+02:00' + id: EVJN00000000000000000000000003 + mutations: + - balance: -10000 + currency: EUR + received: 0 + reserved: 10000 + status: booked + transactionId: EVJN00000000000000000000000003EUR + type: accounting + valueDate: '2023-03-01T12:58:25+01:00' id: 6JKRLZ8LOT47J7RY reason: approved reference: Your user reference for the transfer referenceForBeneficiary: Your user reference for the beneficiary - sequenceNumber: 2 + sequenceNumber: 3 transactionRulesResult: allHardBlockRulesPassed: true - status: authorised + status: booked type: bankTransfer environment: test type: balancePlatform.transfer.updated - post-balancePlatform.transfer.updated-balancePlatform-transfer-updated-booked-incoming-internal: + post-balancePlatform.transfer.updated-03.internal-authorised: + summary: Authorized incoming internal transfer + description: Example webhook of an authorised incoming transfer + value: + data: + id: 2WT1N05XXY7P9XH9 + type: internalTransfer + accountHolder: + description: Your description of the account holder of the target balance + account + id: AH00000000000000000000002 + reference: Your reference for the account holder + amount: + currency: EUR + value: 1000 + balanceAccount: + description: Your description of the target balance account + id: BA00000000000000000000002 + balancePlatform: YOUR_BALANCE_PLATFORM + balances: + - currency: EUR + received: 0 + reserved: 1000 + category: internal + creationDate: '2023-02-28T13:30:05+02:00' + description: Your description of the transfer + direction: incoming + events: + - bookingDate: '2023-02-28T13:30:18+02:00' + id: JDRF00000000000000000000000001 + mutations: + - currency: EUR + received: 1000 + status: received + type: accounting + - bookingDate: '2023-02-28T13:30:18+02:00' + id: JDRF00000000000000000000000002 + mutations: + - currency: EUR + received: -1000 + reserved: 1000 + status: authorised + type: accounting + reason: approved + reference: Your reference for the transfer + referenceForBeneficiary: Your-reference-for-the-recipient-of-the-transfer-request + sequenceNumber: 2 + status: authorised + environment: test + type: balancePlatform.transfer.updated + post-balancePlatform.transfer.updated-04.internal-booked: summary: Booked incoming internal transfer description: Example webhook of a booked incoming transfer value: @@ -2149,73 +2294,340 @@ components: status: booked environment: test type: balancePlatform.transfer.updated - post-balancePlatform.transfer.updated-balancePlatform-transfer-updated-booked-outgoing-external: - summary: Booked payout to a transfer instrument - description: Example webhook of a booked outgoing bank transfer + post-balancePlatform.transfer.updated-05.directDebit-booked: + summary: Business accounts - Successful external direct debit + description: Example webhook of a booked external direct debit transfer value: data: accountHolder: description: Your description of the account holder - id: AH00000000000000000000001 + id: AH00000000000000000000002 reference: Your reference for the account holder amount: currency: EUR - value: 10000 + value: 1000 balanceAccount: - description: Your description of the balance account from where the amount - is debited - id: BA00000000000000000000001 - reference: Your reference for the balance account + description: Your description of the target balance account + id: BA00000000000000000000002 balancePlatform: YOUR_BALANCE_PLATFORM balances: - - balance: -10000 + - balance: -1000 currency: EUR received: 0 reserved: 0 category: bank categoryData: - priority: regular type: bank counterparty: - transferInstrumentId: SE00000000000000000000001 - creationDate: '2023-02-28T13:30:05+02:00' - description: Your user description of the transfer - direction: outgoing + bankAccount: + accountHolder: + fullName: John Smith + type: unknown + accountIdentification: + iban: FR0000000000000000000000117 + type: iban + creationDate: '2024-08-28T13:30:05+02:00' + directDebitInformation: + dateOfSignature: '2023-01-01T01:00:00+01:00' + dueDate: '2024-08-23T02:00:00+02:00' + mandateId: EBAClearing-MANDAT001 + sequenceType: FRST + direction: incoming events: - - bookingDate: '2023-02-28T13:30:18+02:00' - id: EVJN00000000000000000000000001 + - bookingDate: '2024-08-28T13:30:18+02:00' + id: JDRF00000000000000000000000001 mutations: - currency: EUR - received: -10000 + received: -1000 status: received type: accounting - - bookingDate: '2023-02-28T13:30:18+02:00' - id: EVJN00000000000000000000000002 + - bookingDate: '2024-08-28T13:30:18+02:00' + id: JDRF00000000000000000000000002 mutations: - currency: EUR - received: 10000 - reserved: -10000 + received: 1000 + reserved: -1000 status: authorised type: accounting - - bookingDate: '2023-02-28T13:30:18+02:00' - id: EVJN00000000000000000000000003 + - bookingDate: '2024-08-28T13:30:18+02:00' + id: JDRF00000000000000000000000003 mutations: - - balance: -10000 + - balance: -1000 currency: EUR received: 0 - reserved: 10000 + reserved: 1000 status: booked - transactionId: EVJN00000000000000000000000003EUR + transactionId: JDRF00000000000000000000000MEUR type: accounting - valueDate: '2023-03-01T12:58:25+01:00' - id: 6JKRLZ8LOT47J7RY + valueDate: '2024-08-28T14:00:00+02:00' + id: 2WT1N05XXY7P9XH9 + paymentInstrument: + description: Your reference for the payment instrument + id: PI00000000000000000000001 reason: approved - reference: Your user reference for the transfer - referenceForBeneficiary: Your user reference for the beneficiary + reference: Your reference for the transfer + referenceForBeneficiary: The sender's reference for the beneficiary sequenceNumber: 3 + status: booked transactionRulesResult: allHardBlockRulesPassed: true + type: bankDirectDebit + environment: test + type: balancePlatform.transfer.updated + post-balancePlatform.transfer.updated-06.directDebit-cancelled: + summary: Business accounts - Cancelled external direct debit + description: Example webhook of a cancelled external direct debit transfer + value: + data: + accountHolder: + description: Your description of the account holder + id: AH00000000000000000000002 + reference: Your reference for the account holder + amount: + currency: EUR + value: 1000 + balanceAccount: + description: Your description of the target balance account + id: BA00000000000000000000002 + balancePlatform: YOUR_BALANCE_PLATFORM + balances: + - currency: EUR + received: -1000 + category: bank + categoryData: + type: bank + counterparty: + bankAccount: + accountHolder: + fullName: John Smith + type: unknown + accountIdentification: + iban: FR0000000000000000000000117 + type: iban + creationDate: '2024-08-28T13:30:05+02:00' + directDebitInformation: + dateOfSignature: '2023-01-01T01:00:00+01:00' + dueDate: '2024-08-23T02:00:00+02:00' + mandateId: EBAClearing-MANDAT001 + sequenceType: FRST + direction: incoming + events: + - bookingDate: '2024-08-28T13:30:18+02:00' + id: JDRF00000000000000000000000001 + mutations: + - currency: EUR + received: -1000 + status: received + type: accounting + - bookingDate: '2024-08-28T13:30:18+02:00' + id: JDRF00000000000000000000000002 + mutations: + - currency: EUR + received: 1000 + reason: unknown + status: cancelled + type: accounting + id: 2WT1N05XXY7P9XH9 + paymentInstrument: + description: Your reference for the payment instrument + id: PI00000000000000000000001 + reason: approved + reference: Your reference for the transfer + referenceForBeneficiary: The sender's reference for the beneficiary + sequenceNumber: 2 + status: refused + transactionRulesResult: + allHardBlockRulesPassed: true + type: bankDirectDebit + environment: test + type: balancePlatform.transfer.updated + post-balancePlatform.transfer.updated-07.directDebit-failed: + summary: Business accounts - Failed external direct debit + description: Example webhook of a failed external direct debit transfer + value: + data: + accountHolder: + description: Your description of the account holder + id: AH00000000000000000000002 + reference: Your reference for the account holder + amount: + currency: EUR + value: 1000 + balanceAccount: + description: Your description of the target balance account + id: BA00000000000000000000002 + balancePlatform: YOUR_BALANCE_PLATFORM + balances: + - currency: EUR + received: -1000 + category: bank + categoryData: + type: bank + counterparty: + bankAccount: + accountHolder: + fullName: John Smith + type: unknown + accountIdentification: + iban: FR0000000000000000000000117 + type: iban + creationDate: '2024-08-28T13:30:05+02:00' + directDebitInformation: + dateOfSignature: '2023-01-01T01:00:00+01:00' + dueDate: '2024-08-23T02:00:00+02:00' + mandateId: EBAClearing-MANDAT001 + sequenceType: FRST + direction: incoming + events: + - bookingDate: '2024-08-28T13:30:18+02:00' + id: JDRF00000000000000000000000001 + mutations: + - currency: EUR + received: -1000 + status: received + type: accounting + - bookingDate: '2024-08-28T13:30:18+02:00' + id: JDRF00000000000000000000000002 + mutations: + - currency: EUR + received: 1000 + status: refused + type: accounting + id: 2WT1N05XXY7P9XH9 + paymentInstrument: + description: Your reference for the payment instrument + id: PI00000000000000000000001 + reason: unknown + reference: Your reference for the transfer + referenceForBeneficiary: The sender's reference for the beneficiary + sequenceNumber: 2 + status: cancelled + transactionRulesResult: + allHardBlockRulesPassed: true + type: bankDirectDebit + environment: test + type: balancePlatform.transfer.updated + post-balancePlatform.transfer.updated-08.internalDirectDebit-incoming-booked: + summary: Business accounts - Successful internal direct debit (incoming) + description: Example webhook of a booked incoming internal direct debit transfer + value: + data: + accountHolder: + id: AH00000000000000000000002 + reference: Your reference for the account holder + amount: + currency: EUR + value: 1000 + balanceAccount: + description: Your description for the balance account + id: BA00000000000000000000002 + balancePlatform: YOUR_BALANCE_PLATFORM + balances: + - balance: -1000 + currency: EUR + received: 0 + reserved: 0 + category: internal + categoryData: + type: internal + counterparty: + balanceAccountId: BA00000000000000000LIABLE + creationDate: '2024-08-28T13:30:05+02:00' + direction: incoming + events: + - bookingDate: '2024-08-28T13:30:18+02:00' + id: JDRF00000000000000000000000001 + mutations: + - currency: EUR + received: -1000 + status: received + type: accounting + - bookingDate: '2024-08-28T13:30:18+02:00' + id: JDRF00000000000000000000000002 + mutations: + - currency: EUR + received: 1000 + reserved: -1000 + status: authorised + type: accounting + - bookingDate: '2024-08-28T13:30:18+02:00' + id: JDRF00000000000000000000000003 + mutations: + - balance: -1000 + currency: EUR + received: 0 + reserved: 1000 + status: booked + transactionId: JDRF00000000000000000000000MEUR + type: accounting + valueDate: '2024-08-28T14:00:00+02:00' + id: 2WT1N05XXY7P9XH9 + reason: approved + reference: Your reference for the transfer + sequenceNumber: 3 status: booked - type: bankTransfer + type: internalDirectDebit + environment: test + type: balancePlatform.transfer.updated + post-balancePlatform.transfer.updated-09.internalDirectDebit-outgoing-booked: + summary: Business accounts - Successful internal direct debit (outgoing) + description: Example webhook of a booked outgoing internal direct debit transfer + value: + data: + accountHolder: + id: AH000000000000000000LIABLE + reference: Your reference for the account holder + amount: + currency: EUR + value: 1000 + balanceAccount: + description: Your description for the balance account + id: BA000000000000000000LIABLE + balancePlatform: YOUR_BALANCE_PLATFORM + balances: + - balance: 1000 + currency: EUR + received: 0 + reserved: 0 + category: internal + categoryData: + type: internal + counterparty: + balanceAccountId: BA00000000000000000000002 + creationDate: '2024-08-28T13:30:05+02:00' + direction: outgoing + events: + - bookingDate: '2024-08-28T13:30:18+02:00' + id: JDRF00000000000000000000000001 + mutations: + - currency: EUR + received: 1000 + status: received + type: accounting + - bookingDate: '2024-08-28T13:30:18+02:00' + id: JDRF00000000000000000000000002 + mutations: + - currency: EUR + received: -1000 + reserved: 1000 + status: authorised + type: accounting + - bookingDate: '2024-08-28T13:30:18+02:00' + id: JDRF00000000000000000000000003 + mutations: + - balance: 1000 + currency: EUR + received: 0 + reserved: -1000 + status: booked + transactionId: JDRF00000000000000000000000MEUR + type: accounting + valueDate: '2024-08-28T14:00:00+02:00' + id: 2WT1N05XXY7P9XH9 + reason: approved + reference: Your reference for the transfer + sequenceNumber: 3 + status: booked + type: internalDirectDebit environment: test type: balancePlatform.transfer.updated diff --git a/yaml/TransferService-v2.yaml b/yaml/TransferService-v2.yaml index b1af40d..140fa94 100644 --- a/yaml/TransferService-v2.yaml +++ b/yaml/TransferService-v2.yaml @@ -261,15 +261,29 @@ paths: are just starting your implementation, use the latest version. - Starts a request to transfer funds to [balance accounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts), - [transfer instruments](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments), - or third-party bank accounts. Adyen sends the outcome of the transfer request - through webhooks. + Starts a request to transfer funds to: + - [Balance accounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts) - To use this endpoint, you need an additional role for your API credential - and transfers must be enabled for the source balance account. Your Adyen contact - will set these up for you.' + - [Transfer instruments](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments) + + - [Third-party bank accounts](https://docs.adyen.com/payouts/payout-service/pay-out-to-bank-accounts) + + - [Third-party cards](https://docs.adyen.com/payouts/payout-service/pay-out-to-cards) + + + Adyen sends the outcome of the transfer request through webhooks. + + + To use this endpoint: + + - Your API credential must have the **TransferService Webservice Initiate** + [role](https://docs.adyen.com/platforms/manage-access/webservice-roles/?tab=transfers_3). + + - The account holder must have the required [capabilities](https://docs.adyen.com/platforms/verification-overview/capabilities). + + + Reach out to your Adyen contact to set up these permissions.' x-addedInVersion: '2' operationId: post-transfers x-sortIndex: 1 @@ -933,6 +947,7 @@ components: x-addedInVersion: '2' description: Additional information about the status of the transfer. enum: + - accountHierarchyNotActive - amountLimitExceeded - approved - balanceAccountTemporarilyBlockedByTransactionRule @@ -944,12 +959,15 @@ components: - counterpartyBankUnavailable - declined - declinedByTransactionRule + - directDebitNotSupported - error - notEnoughBalance - pendingApproval + - pendingExecution - refusedByCounterpartyBank - routeNotFound - scaFailed + - transferInstrumentDoesNotExist - unknown type: string reference: @@ -1024,6 +1042,7 @@ components: - paymentCost - paymentCostPending - pendingApproval + - pendingExecution - received - refundPending - refundReversalPending diff --git a/yaml/TransferService-v3.yaml b/yaml/TransferService-v3.yaml index e896686..dfc7283 100644 --- a/yaml/TransferService-v3.yaml +++ b/yaml/TransferService-v3.yaml @@ -456,15 +456,29 @@ paths: are just starting your implementation, use the latest version. - Starts a request to transfer funds to [balance accounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts), - [transfer instruments](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments), - or third-party bank accounts. Adyen sends the outcome of the transfer request - through webhooks. + Starts a request to transfer funds to: + - [Balance accounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts) - To use this endpoint, you need an additional role for your API credential - and transfers must be enabled for the source balance account. Your Adyen contact - will set these up for you.' + - [Transfer instruments](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments) + + - [Third-party bank accounts](https://docs.adyen.com/payouts/payout-service/pay-out-to-bank-accounts) + + - [Third-party cards](https://docs.adyen.com/payouts/payout-service/pay-out-to-cards) + + + Adyen sends the outcome of the transfer request through webhooks. + + + To use this endpoint: + + - Your API credential must have the **TransferService Webservice Initiate** + [role](https://docs.adyen.com/platforms/manage-access/webservice-roles/?tab=transfers_3). + + - The account holder must have the required [capabilities](https://docs.adyen.com/platforms/verification-overview/capabilities). + + + Reach out to your Adyen contact to set up these permissions.' x-addedInVersion: '2' operationId: post-transfers x-sortIndex: 1 @@ -542,6 +556,134 @@ paths: schema: $ref: '#/components/schemas/TransferServiceRestServiceError' description: Internal Server Error - the server could not process the request. + /transfers/approve: + post: + tags: + - Transfers + summary: Approve initiated transfers + description: 'Initiates the approval of a list of transfers that triggered an + additional [review](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-review). + Adyen sends the outcome of the approval request through webhooks. + + + To use this endpoint: + + - Your API credential must have the **TransferService Approve** [role](https://docs.adyen.com/platforms/manage-access/webservice-roles/?tab=transfers_3). + + - The account holder must have the required [capabilities](https://docs.adyen.com/platforms/verification-overview/capabilities). + + + Reach out to your Adyen contact to set up these permissions.' + x-addedInVersion: '3' + operationId: post-transfers-approve + x-sortIndex: 2 + x-methodName: approveInitiatedTransfers + security: + - clientKey: [] + - BasicAuth: [] + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ApproveTransfersRequest' + parameters: + - description: Header for authenticating through SCA + example: SCA realm="ApproveTransfers" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl..." + name: WWW-Authenticate + in: header + schema: + type: string + responses: + '200': + description: 'No Content - look at the actual response code for the status + of the request. ' + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceError' + description: Unauthorized - authentication required. + headers: + auth-param1: + $ref: '#/components/headers/auth-param1' + '403': + content: + application/json: + schema: + $ref: '#/components/schemas/TransferServiceRestServiceError' + description: Forbidden - insufficient permissions to process the request. + '422': + content: + application/json: + schema: + $ref: '#/components/schemas/TransferServiceRestServiceError' + description: Unprocessable Entity - a request validation error. + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/TransferServiceRestServiceError' + description: Internal Server Error - the server could not process the request. + /transfers/cancel: + post: + tags: + - Transfers + summary: Cancel initiated transfers + description: 'Initiates the cancellation of a list of transfers that triggered + an additional [review](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-review). + Adyen sends the outcome of the cancel request through webhooks. + + + To use this endpoint: + + - Your API credential must have the **TransferService Approve** [role](https://docs.adyen.com/platforms/manage-access/webservice-roles/?tab=transfers_3). + + - The account holder must have the required [capabilities](https://docs.adyen.com/platforms/verification-overview/capabilities). + + + Reach out to your Adyen contact to set up these permissions.' + x-addedInVersion: '3' + operationId: post-transfers-cancel + x-sortIndex: 3 + x-methodName: cancelInitiatedTransfers + security: + - clientKey: [] + - BasicAuth: [] + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CancelTransfersRequest' + responses: + '200': + description: 'No Content - look at the actual response code for the status + of the request. ' + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/TransferServiceRestServiceError' + description: Unauthorized - authentication required. + '403': + content: + application/json: + schema: + $ref: '#/components/schemas/TransferServiceRestServiceError' + description: Forbidden - insufficient permissions to process the request. + '422': + content: + application/json: + schema: + $ref: '#/components/schemas/TransferServiceRestServiceError' + description: Unprocessable Entity - a request validation error. + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/TransferServiceRestServiceError' + description: Internal Server Error - the server could not process the request. /transfers/{transferId}/returns: post: tags: @@ -551,7 +693,7 @@ paths: a new `transferId`. x-addedInVersion: '3' operationId: post-transfers-transferId-returns - x-sortIndex: 2 + x-sortIndex: 4 x-methodName: returnTransfer security: - clientKey: [] @@ -705,6 +847,16 @@ components: - value - currency type: object + ApproveTransfersRequest: + additionalProperties: false + properties: + transferIds: + description: Contains the unique identifiers of the transfers that you want + to approve. + items: + type: string + type: array + type: object BRLocalAccountIdentification: additionalProperties: false properties: @@ -843,6 +995,16 @@ components: - accountNumber - bankCode type: object + CancelTransfersRequest: + additionalProperties: false + properties: + transferIds: + description: Contains the unique identifiers of the transfers that you want + to cancel. + items: + type: string + type: array + type: object CapitalBalance: additionalProperties: false properties: @@ -1102,6 +1264,28 @@ components: - accountNumber - bankCode type: object + DirectDebitInformation: + additionalProperties: false + properties: + dateOfSignature: + description: The date when the direct debit mandate was accepted by your + user, in [ISO-8601](https://www.w3.org/TR/NOTE-datetime) format. + format: date-time + type: string + dueDate: + description: The date when the funds are deducted from your user's balance + account. + format: date-time + type: string + mandateId: + description: Your unique identifier for the direct debit mandate. + type: string + sequenceType: + description: 'Identifies the direct debit transfer''s type. + + Possible values: **OneOff**, **First**, **Recurring**, **Final**.' + type: string + type: object Fee: additionalProperties: false properties: @@ -1925,6 +2109,10 @@ components: Supported characters for **regular** and **fast** transfers to a US counterparty: **[a-z] [A-Z] [0-9] & $ % # @** **~ = + - _ '' " ! ?**' type: string + directDebitInformation: + x-addedInVersion: '3' + description: The details of the direct debit. + $ref: '#/components/schemas/DirectDebitInformation' direction: x-addedInVersion: '2' description: 'The direction of the transfer. @@ -1995,6 +2183,7 @@ components: x-addedInVersion: '2' description: Additional information about the status of the transfer. enum: + - accountHierarchyNotActive - amountLimitExceeded - approved - balanceAccountTemporarilyBlockedByTransactionRule @@ -2006,12 +2195,15 @@ components: - counterpartyBankUnavailable - declined - declinedByTransactionRule + - directDebitNotSupported - error - notEnoughBalance - pendingApproval + - pendingExecution - refusedByCounterpartyBank - routeNotFound - scaFailed + - transferInstrumentDoesNotExist - unknown type: string reference: @@ -2030,6 +2222,10 @@ components: \ on the `category`.\n\n - **internal**: 80 characters\n\n- **bank**:\ \ 35 characters when transferring to an IBAN, 15 characters for others." type: string + review: + x-addedInVersion: '3' + description: Contains status updates related to additional reviews. + $ref: '#/components/schemas/TransferReview' status: x-addedInVersion: '2' description: "The result of the transfer.\n\n For example, **authorised**,\ @@ -2087,6 +2283,7 @@ components: - paymentCost - paymentCostPending - pendingApproval + - pendingExecution - received - refundPending - refundReversalPending @@ -2267,6 +2464,10 @@ components: \ depends on the `category`.\n\n- **internal**: 80 characters\n\n- **bank**:\ \ 35 characters when transferring to an IBAN, 15 characters for others." type: string + review: + x-addedInVersion: '3' + description: 'Contains information required for triggering transfer reviews. ' + $ref: '#/components/schemas/TransferRequestReview' type: x-addedInVersion: '3' description: "The type of transfer.\n\nPossible values:\n\n - **bankTransfer**:\ @@ -2290,6 +2491,47 @@ components: - amount - counterparty type: object + TransferRequestReview: + additionalProperties: false + properties: + numberOfApprovalsRequired: + description: Specifies the number of [approvals](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) + required to process the transfer. + format: int32 + type: integer + scaOnApproval: + description: 'Specifies whether you will initiate Strong Customer Authentication + (SCA) in thePOST [/transfers/approve](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) + request. + + + Only applies to transfers made with an Adyen [business account](https://docs.adyen.com/platforms/business-accounts).' + type: boolean + type: object + TransferReview: + additionalProperties: false + properties: + numberOfApprovalsCompleted: + description: Shows the number of approvals completed for the transfer. + format: int32 + type: integer + numberOfApprovalsRequired: + description: Shows the number of [approvals](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) + required to process the transfer. + format: int32 + type: integer + scaOnApproval: + description: 'Shows the status of the Strong Customer Authentication (SCA) + process. + + + Possible values: **required**, **completed**, **notApplicable**.' + enum: + - completed + - notApplicable + - required + type: string + type: object TransferServiceRestServiceError: additionalProperties: false properties: diff --git a/yaml/TransferService-v4.yaml b/yaml/TransferService-v4.yaml index cd642dd..7c4b379 100644 --- a/yaml/TransferService-v4.yaml +++ b/yaml/TransferService-v4.yaml @@ -473,7 +473,7 @@ paths: ' x-addedInVersion: '4' operationId: get-transfers - x-sortIndex: 3 + x-sortIndex: 5 x-methodName: getAllTransfers security: - clientKey: [] @@ -639,15 +639,29 @@ paths: are just starting your implementation, use the latest version. - Starts a request to transfer funds to [balance accounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts), - [transfer instruments](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments), - or third-party bank accounts. Adyen sends the outcome of the transfer request - through webhooks. + Starts a request to transfer funds to: + + - [Balance accounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts) + + - [Transfer instruments](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments) + + - [Third-party bank accounts](https://docs.adyen.com/payouts/payout-service/pay-out-to-bank-accounts) + + - [Third-party cards](https://docs.adyen.com/payouts/payout-service/pay-out-to-cards) + + + Adyen sends the outcome of the transfer request through webhooks. + + + To use this endpoint: + + - Your API credential must have the **TransferService Webservice Initiate** + [role](https://docs.adyen.com/platforms/manage-access/webservice-roles/?tab=transfers_3). + - The account holder must have the required [capabilities](https://docs.adyen.com/platforms/verification-overview/capabilities). - To use this endpoint, you need an additional role for your API credential - and transfers must be enabled for the source balance account. Your Adyen contact - will set these up for you.' + + Reach out to your Adyen contact to set up these permissions.' x-addedInVersion: '2' operationId: post-transfers x-sortIndex: 1 @@ -725,15 +739,143 @@ paths: schema: $ref: '#/components/schemas/TransferServiceRestServiceError' description: Internal Server Error - the server could not process the request. + /transfers/approve: + post: + tags: + - Transfers + summary: Approve initiated transfers + description: 'Initiates the approval of a list of transfers that triggered an + additional [review](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-review). + Adyen sends the outcome of the approval request through webhooks. + + + To use this endpoint: + + - Your API credential must have the **TransferService Approve** [role](https://docs.adyen.com/platforms/manage-access/webservice-roles/?tab=transfers_3). + + - The account holder must have the required [capabilities](https://docs.adyen.com/platforms/verification-overview/capabilities). + + + Reach out to your Adyen contact to set up these permissions.' + x-addedInVersion: '3' + operationId: post-transfers-approve + x-sortIndex: 2 + x-methodName: approveInitiatedTransfers + security: + - clientKey: [] + - BasicAuth: [] + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ApproveTransfersRequest' + parameters: + - description: Header for authenticating through SCA + example: SCA realm="ApproveTransfers" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl..." + name: WWW-Authenticate + in: header + schema: + type: string + responses: + '200': + description: 'No Content - look at the actual response code for the status + of the request. ' + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceError' + description: Unauthorized - authentication required. + headers: + auth-param1: + $ref: '#/components/headers/auth-param1' + '403': + content: + application/json: + schema: + $ref: '#/components/schemas/TransferServiceRestServiceError' + description: Forbidden - insufficient permissions to process the request. + '422': + content: + application/json: + schema: + $ref: '#/components/schemas/TransferServiceRestServiceError' + description: Unprocessable Entity - a request validation error. + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/TransferServiceRestServiceError' + description: Internal Server Error - the server could not process the request. + /transfers/cancel: + post: + tags: + - Transfers + summary: Cancel initiated transfers + description: 'Initiates the cancellation of a list of transfers that triggered + an additional [review](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers#request-review). + Adyen sends the outcome of the cancel request through webhooks. + + + To use this endpoint: + + - Your API credential must have the **TransferService Approve** [role](https://docs.adyen.com/platforms/manage-access/webservice-roles/?tab=transfers_3). + + - The account holder must have the required [capabilities](https://docs.adyen.com/platforms/verification-overview/capabilities). + + + Reach out to your Adyen contact to set up these permissions.' + x-addedInVersion: '3' + operationId: post-transfers-cancel + x-sortIndex: 3 + x-methodName: cancelInitiatedTransfers + security: + - clientKey: [] + - BasicAuth: [] + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CancelTransfersRequest' + responses: + '200': + description: 'No Content - look at the actual response code for the status + of the request. ' + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/TransferServiceRestServiceError' + description: Unauthorized - authentication required. + '403': + content: + application/json: + schema: + $ref: '#/components/schemas/TransferServiceRestServiceError' + description: Forbidden - insufficient permissions to process the request. + '422': + content: + application/json: + schema: + $ref: '#/components/schemas/TransferServiceRestServiceError' + description: Unprocessable Entity - a request validation error. + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/TransferServiceRestServiceError' + description: Internal Server Error - the server could not process the request. /transfers/{id}: get: tags: - Transfers summary: Get a transfer - description: Returns a transfer. + description: Returns the details of a specified transfer. x-addedInVersion: '4' operationId: get-transfers-id - x-sortIndex: 4 + x-sortIndex: 6 x-methodName: getTransfer security: - clientKey: [] @@ -789,7 +931,7 @@ paths: a new `transferId`. x-addedInVersion: '3' operationId: post-transfers-transferId-returns - x-sortIndex: 2 + x-sortIndex: 4 x-methodName: returnTransfer security: - clientKey: [] @@ -974,6 +1116,16 @@ components: format: int32 type: integer type: object + ApproveTransfersRequest: + additionalProperties: false + properties: + transferIds: + description: Contains the unique identifiers of the transfers that you want + to approve. + items: + type: string + type: array + type: object BRLocalAccountIdentification: additionalProperties: false properties: @@ -1186,6 +1338,16 @@ components: - accountNumber - bankCode type: object + CancelTransfersRequest: + additionalProperties: false + properties: + transferIds: + description: Contains the unique identifiers of the transfers that you want + to cancel. + items: + type: string + type: array + type: object CapitalBalance: additionalProperties: false properties: @@ -1465,6 +1627,28 @@ components: - accountNumber - bankCode type: object + DirectDebitInformation: + additionalProperties: false + properties: + dateOfSignature: + description: The date when the direct debit mandate was accepted by your + user, in [ISO-8601](https://www.w3.org/TR/NOTE-datetime) format. + format: date-time + type: string + dueDate: + description: The date when the funds are deducted from your user's balance + account. + format: date-time + type: string + mandateId: + description: Your unique identifier for the direct debit mandate. + type: string + sequenceType: + description: 'Identifies the direct debit transfer''s type. + + Possible values: **OneOff**, **First**, **Recurring**, **Final**.' + type: string + type: object EstimationTrackingData: additionalProperties: false properties: @@ -1827,6 +2011,7 @@ components: - paymentCost - paymentCostPending - pendingApproval + - pendingExecution - received - refundPending - refundReversalPending @@ -2581,6 +2766,10 @@ components: Supported characters for **regular** and **fast** transfers to a US counterparty: **[a-z] [A-Z] [0-9] & $ % # @** **~ = + - _ '' " ! ?**' type: string + directDebitInformation: + x-addedInVersion: '3' + description: The details of the direct debit. + $ref: '#/components/schemas/DirectDebitInformation' direction: x-addedInVersion: '2' description: 'The direction of the transfer. @@ -2603,6 +2792,7 @@ components: x-addedInVersion: '2' description: Additional information about the status of the transfer. enum: + - accountHierarchyNotActive - amountLimitExceeded - approved - balanceAccountTemporarilyBlockedByTransactionRule @@ -2614,12 +2804,15 @@ components: - counterpartyBankUnavailable - declined - declinedByTransactionRule + - directDebitNotSupported - error - notEnoughBalance - pendingApproval + - pendingExecution - refusedByCounterpartyBank - routeNotFound - scaFailed + - transferInstrumentDoesNotExist - unknown type: string reference: @@ -2638,6 +2831,10 @@ components: \ on the `category`.\n\n - **internal**: 80 characters\n\n- **bank**:\ \ 35 characters when transferring to an IBAN, 15 characters for others." type: string + review: + x-addedInVersion: '3' + description: Contains status updates related to additional reviews. + $ref: '#/components/schemas/TransferReview' status: x-addedInVersion: '2' description: "The result of the transfer.\n\n For example, **authorised**,\ @@ -2695,6 +2892,7 @@ components: - paymentCost - paymentCostPending - pendingApproval + - pendingExecution - received - refundPending - refundReversalPending @@ -2833,6 +3031,10 @@ components: Supported characters for **regular** and **fast** transfers to a US counterparty: **[a-z] [A-Z] [0-9] & $ % # @** **~ = + - _ '' " ! ?**' type: string + directDebitInformation: + x-addedInVersion: '3' + description: The details of the direct debit. + $ref: '#/components/schemas/DirectDebitInformation' direction: x-addedInVersion: '2' description: 'The direction of the transfer. @@ -2862,6 +3064,7 @@ components: x-addedInVersion: '2' description: Additional information about the status of the transfer. enum: + - accountHierarchyNotActive - amountLimitExceeded - approved - balanceAccountTemporarilyBlockedByTransactionRule @@ -2873,12 +3076,15 @@ components: - counterpartyBankUnavailable - declined - declinedByTransactionRule + - directDebitNotSupported - error - notEnoughBalance - pendingApproval + - pendingExecution - refusedByCounterpartyBank - routeNotFound - scaFailed + - transferInstrumentDoesNotExist - unknown type: string reference: @@ -2897,6 +3103,10 @@ components: \ on the `category`.\n\n - **internal**: 80 characters\n\n- **bank**:\ \ 35 characters when transferring to an IBAN, 15 characters for others." type: string + review: + x-addedInVersion: '3' + description: Contains status updates related to additional reviews. + $ref: '#/components/schemas/TransferReview' sequenceNumber: x-addedInVersion: '3' description: 'The sequence number of the transfer webhook. The numbers start @@ -2964,6 +3174,7 @@ components: - paymentCost - paymentCostPending - pendingApproval + - pendingExecution - received - refundPending - refundReversalPending @@ -3094,6 +3305,7 @@ components: x-addedInVersion: '3' description: The reason for the transfer status. enum: + - accountHierarchyNotActive - amountLimitExceeded - approved - balanceAccountTemporarilyBlockedByTransactionRule @@ -3105,12 +3317,15 @@ components: - counterpartyBankUnavailable - declined - declinedByTransactionRule + - directDebitNotSupported - error - notEnoughBalance - pendingApproval + - pendingExecution - refusedByCounterpartyBank - routeNotFound - scaFailed + - transferInstrumentDoesNotExist - unknown type: string status: @@ -3169,6 +3384,7 @@ components: - paymentCost - paymentCostPending - pendingApproval + - pendingExecution - received - refundPending - refundReversalPending @@ -3358,6 +3574,10 @@ components: \ depends on the `category`.\n\n- **internal**: 80 characters\n\n- **bank**:\ \ 35 characters when transferring to an IBAN, 15 characters for others." type: string + review: + x-addedInVersion: '3' + description: 'Contains information required for triggering transfer reviews. ' + $ref: '#/components/schemas/TransferRequestReview' type: x-addedInVersion: '3' description: "The type of transfer.\n\nPossible values:\n\n - **bankTransfer**:\ @@ -3435,6 +3655,47 @@ components: description: The type of the validation fact. type: string type: object + TransferRequestReview: + additionalProperties: false + properties: + numberOfApprovalsRequired: + description: Specifies the number of [approvals](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) + required to process the transfer. + format: int32 + type: integer + scaOnApproval: + description: 'Specifies whether you will initiate Strong Customer Authentication + (SCA) in thePOST [/transfers/approve](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) + request. + + + Only applies to transfers made with an Adyen [business account](https://docs.adyen.com/platforms/business-accounts).' + type: boolean + type: object + TransferReview: + additionalProperties: false + properties: + numberOfApprovalsCompleted: + description: Shows the number of approvals completed for the transfer. + format: int32 + type: integer + numberOfApprovalsRequired: + description: Shows the number of [approvals](https://docs.adyen.com/api-explorer/transfers/latest/post/transfers/approve) + required to process the transfer. + format: int32 + type: integer + scaOnApproval: + description: 'Shows the status of the Strong Customer Authentication (SCA) + process. + + + Possible values: **required**, **completed**, **notApplicable**.' + enum: + - completed + - notApplicable + - required + type: string + type: object TransferServiceRestServiceError: additionalProperties: false properties: