{"files":{"SKILL.md":"---\nname: transfers-api\ndescription: \"Transfers API skill. Use when working with Transfers for grants, transactions, transfers. Covers 9 endpoints.\"\nversion: 1.0.0\ngenerator: lapsh\n---\n\n# Transfers API\nAPI version: 3\n\n## Auth\nApiKey X-API-Key in header | Bearer basic | ApiKey clientKey in query\n\n## Base URL\nhttps://balanceplatform-api-test.adyen.com/btl/v3\n\n## Setup\n1. Set Authorization header with Bearer token\n2. GET /grants -- get a capital account\n3. POST /grants -- create first grant\n\n## Endpoints\n9 endpoints across 3 groups. See references/api-spec.lap for full details.\n\n### Grants\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /grants | Get a capital account |\n| POST | /grants | Request a grant payout |\n| GET | /grants/{id} | Get grant reference details |\n\n### Transactions\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /transactions | Get all transactions |\n| GET | /transactions/{id} | Get a transaction |\n\n### Transfers\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /transfers | Transfer funds |\n| POST | /transfers/approve | Approve initiated transfers |\n| POST | /transfers/cancel | Cancel initiated transfers |\n| POST | /transfers/{transferId}/returns | Return a transfer |\n\n## Common Questions\nMatch user requests to endpoints in references/api-spec.lap. Key patterns:\n- \"List all grants?\" -> GET /grants\n- \"Create a grant?\" -> POST /grants\n- \"Get grant details?\" -> GET /grants/{id}\n- \"List all transactions?\" -> GET /transactions\n- \"Get transaction details?\" -> GET /transactions/{id}\n- \"Create a transfer?\" -> POST /transfers\n- \"Create a approve?\" -> POST /transfers/approve\n- \"Create a cancel?\" -> POST /transfers/cancel\n- \"Create a return?\" -> POST /transfers/{transferId}/returns\n- \"How to authenticate?\" -> See Auth section above\n\n## Response Tips\n- Check response schemas in references/api-spec.lap for field details\n- Paginated endpoints accept limit/offset or cursor parameters\n- Create/update endpoints return the modified resource on success\n- Error responses include status codes and descriptions in the spec\n\n## References\n- Full spec: See references/api-spec.lap for complete endpoint details, parameter tables, and response schemas\n\n> Generated from the official API spec by [LAP](https://lap.sh)\n","references/api-spec.lap":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api Transfers API\n@base https://balanceplatform-api-test.adyen.com/btl/v3\n@version 3\n@auth ApiKey X-API-Key in header | Bearer basic | ApiKey clientKey in query\n@endpoints 9\n@toc grants(3), transactions(2), transfers(4)\n\n@group grants\n@endpoint GET /grants\n@desc Get a capital account\n@optional {counterpartyAccountHolderId: str # The counterparty account holder id.}\n@returns(200) {grants: [map]} # OK - the request has succeeded.\n@errors {400: Bad Request - a problem reading or understanding the request., 401: Unauthorized - authentication required., 403: Forbidden - insufficient permissions to process the request., 404: Not Found - the payment was not found, 422: Unprocessable Entity - a request validation error., 500: Internal Server Error - the server could not process the request.}\n\n@endpoint POST /grants\n@desc Request a grant payout\n@required {grantAccountId: str # The identifier of the grant account used for the grant., grantOfferId: str # The identifier of the grant offer that has been selected and from which the grant details will be used.}\n@optional {Idempotency-Key: str # A unique identifier for the message with a maximum of 64 characters (we recommend a UUID)., counterparty: map{balanceAccountId: str, transferInstrumentId: str}}\n@returns(200) {amount: map{currency: str, value: int(int64)}, balances: map{currency: str, fee: int(int64), principal: int(int64), total: int(int64)}, counterparty: map{accountHolderId: str, balanceAccountId: str, transferInstrumentId: str}, fee: map{amount: map{currency: str, value: int(int64)}}, grantAccountId: str, grantOfferId: str, id: str, repayment: map{basisPoints: int(int32), term: map{estimatedDays: int(int32), maximumDays: int(int32)}, threshold: map{amount: map{currency: str, value: int(int64)}}}, status: str} # OK - the request has succeeded.\n@errors {400: Bad Request - a problem reading or understanding the request., 401: Unauthorized - authentication required., 403: Forbidden - insufficient permissions to process the request., 404: Not Found - the payment was not found, 422: Unprocessable Entity - a request validation error., 500: Internal Server Error - the server could not process the request.}\n@example_request {\"grantAccountId\":\"CG00000000000000000000001\",\"grantOfferId\":\"0000000000000001\",\"counterparty\":{\"balanceAccountId\":\"BA00000000000000000000001\"}}\n\n@endpoint GET /grants/{id}\n@desc Get grant reference details\n@required {id: str # The unique identifier of the grant.}\n@returns(200) {amount: map{currency: str, value: int(int64)}, balances: map{currency: str, fee: int(int64), principal: int(int64), total: int(int64)}, counterparty: map{accountHolderId: str, balanceAccountId: str, transferInstrumentId: str}, fee: map{amount: map{currency: str, value: int(int64)}}, grantAccountId: str, grantOfferId: str, id: str, repayment: map{basisPoints: int(int32), term: map{estimatedDays: int(int32), maximumDays: int(int32)}, threshold: map{amount: map{currency: str, value: int(int64)}}}, status: str} # OK - the request has succeeded.\n@errors {400: Bad Request - a problem reading or understanding the request., 401: Unauthorized - authentication required., 403: Forbidden - insufficient permissions to process the request., 404: Not Found - the payment was not found, 422: Unprocessable Entity - a request validation error., 500: Internal Server Error - the server could not process the request.}\n\n@endgroup\n\n@group transactions\n@endpoint GET /transactions\n@desc Get all transactions\n@required {createdSince: str(date-time) # Only include transactions that have been created on or after this point in time. The value must be in ISO 8601 format. For example, **2021-05-30T15:07:40Z**., createdUntil: str(date-time) # Only include transactions that have been created on or before this point in time. The value must be in ISO 8601 format. For example, **2021-05-30T15:07:40Z**.}\n@optional {balancePlatform: str # The unique identifier of the [balance platform](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/balancePlatforms/{id}__queryParam_id).  Required if you don't provide a `balanceAccountId` or `accountHolderId`., paymentInstrumentId: str # The unique identifier of the [payment instrument](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/paymentInstruments/_id_).  To use this parameter, you must also provide a `balanceAccountId`, `accountHolderId`, or `balancePlatform`.  The `paymentInstrumentId` must be related to the `balanceAccountId` or `accountHolderId` that you provide., accountHolderId: str # The unique identifier of the [account holder](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}__queryParam_id).  Required if you don't provide a `balanceAccountId` or `balancePlatform`.  If you provide a `balanceAccountId`, the `accountHolderId` must be related to the `balanceAccountId`., balanceAccountId: str # The unique identifier of the [balance account](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/balanceAccounts/{id}__queryParam_id).  Required if you don't provide an `accountHolderId` or `balancePlatform`.  If you provide an `accountHolderId`, the `balanceAccountId` must be related to the `accountHolderId`., cursor: str # The `cursor` returned in the links of the previous response., sortOrder: str(asc/desc) # Determines the sort order of the returned transactions. The sort order is based on the creation date of the transaction.  Possible values:   - **asc**: Ascending order, from oldest to most recent.  - **desc**: Descending order, from most recent to oldest.  Default value: **asc**., limit: int(int32) # The number of items returned per page, maximum of 100 items. By default, the response returns 10 items per page.}\n@returns(200) {_links: map{next: map{href: str}, prev: map{href: str}}, data: [map]} # OK - the request has succeeded.\n@errors {401: Unauthorized - authentication required., 403: Forbidden - insufficient permissions to process the request., 422: Unprocessable Entity - a request validation error., 500: Internal Server Error - the server could not process the request.}\n\n@endpoint GET /transactions/{id}\n@desc Get a transaction\n@required {id: str # The unique identifier of the transaction.}\n@returns(200) {accountHolderId: str, amount: map{currency: str, value: int(int64)}, balanceAccountId: str, balancePlatform: str, bookingDate: str(date-time), category: str, counterparty: map{balanceAccountId: str, bankAccount: map{accountHolder: map{address: map, dateOfBirth: str(date), email: str, firstName: str, fullName: str, lastName: str, reference: str, type: str, url: str}, accountIdentification: any, storedPaymentMethodId: str}, card: map{cardHolder: map{address: map, dateOfBirth: str(date), email: str, firstName: str, fullName: str, lastName: str, reference: str, type: str, url: str}, cardIdentification: map{expiryMonth: str, expiryYear: str, issueNumber: str, number: str, startMonth: str, startYear: str, storedPaymentMethodId: str}}, merchant: map{acquirerId: str, mcc: str, merchantId: str, nameLocation: map{city: str, country: str, countryOfOrigin: str, name: str, rawData: str, state: str}, postalCode: str}, transferInstrumentId: str}, createdAt: str(date-time), creationDate: str(date-time), description: str, eventId: str, id: str, instructedAmount: map{currency: str, value: int(int64)}, paymentInstrumentId: str, reference: str, referenceForBeneficiary: str, status: str, transferId: str, type: str, valueDate: str(date-time)} # OK - the request has succeeded.\n@errors {401: Unauthorized - authentication required., 403: Forbidden - insufficient permissions to process the request., 422: Unprocessable Entity - a request validation error., 500: Internal Server Error - the server could not process the request.}\n\n@endgroup\n\n@group transfers\n@endpoint POST /transfers\n@desc Transfer funds\n@required {amount: map{currency!: str, value!: int(int64)}, category: str(bank/card/internal/issuedCard/platformPayment/topUp) # The category of the transfer.  Possible values:   - **bank**: A transfer involving a [transfer instrument](https://docs.adyen.com/api-explorer/legalentity/latest/post/transferInstruments#responses-200-id) or a bank account.  - **card**: A transfer involving a third-party card.  - **internal**: A transfer between [balance accounts](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts#responses-200-id) within your platform.  - **issuedCard**: A transfer initiated by an Adyen-issued card.  - **platformPayment**: Funds movements related to payments that are acquired for your users.  - **topUp**: An incoming transfer initiated by your user to top up their balance account., counterparty: map{balanceAccountId: str, bankAccount: map, card: map, transferInstrumentId: str}}\n@optional {Idempotency-Key: str # A unique identifier for the message with a maximum of 64 characters (we recommend a UUID)., WWW-Authenticate: str # Header for authenticating through SCA, balanceAccountId: str # The unique identifier of the source [balance account](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts#responses-200-id).  If you want to make a transfer using a **virtual** **bankAccount** assigned to the balance account, you must specify the [payment instrument ID](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/paymentInstruments#responses-200-id) of the **virtual** **bankAccount**. If you only specify a balance account ID, Adyen uses the default **physical** **bankAccount** payment instrument assigned to the balance account., description: str # 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.  Supported characters: **[a-z] [A-Z] [0-9] / - ?** **: ( ) . , ' + Space**  Supported characters for **regular** and **fast** transfers to a US counterparty: **[a-z] [A-Z] [0-9] & $ % # @** **~ = + - _ ' \" ! ?**, executionDate: map{date: str(date), timezone: str}, paymentInstrumentId: str # The unique identifier of the source [payment instrument](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/paymentInstruments#responses-200-id).  If you want to make a transfer using a **virtual** **bankAccount**, you must specify the payment instrument ID of the **virtual** **bankAccount**. If you only specify a balance account ID, Adyen uses the default **physical** **bankAccount** payment instrument assigned to the balance account., priority: str(crossBorder/fast/instant/internal/regular/wire) # The priority for the bank transfer. This sets the speed at which the transfer is sent and the fees that you have to pay. Required for transfers with `category` **bank**.  Possible values:  * **regular**: For normal, low-value transactions.  * **fast**: A faster way to transfer funds, but the fees are higher. Recommended for high-priority, low-value transactions.  * **wire**: The fastest way to transfer funds, but this has the highest fees. Recommended for high-priority, high-value transactions.  * **instant**: For instant funds transfers within the United States and in [SEPA locations](https://www.ecb.europa.eu/paym/integration/retail/sepa/html/index.en.html).  * **crossBorder**: For high-value transfers to a recipient in a different country.  * **internal**: For transfers to an Adyen-issued business bank account (by bank account number/IBAN)., reference: str # Your reference for the transfer, used internally within your platform. If you don't provide this in the request, Adyen generates a unique reference., referenceForBeneficiary: str # 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.   Supported characters: **a-z**, **A-Z**, **0-9**. The maximum length depends on the `category`.  - **internal**: 80 characters  - **bank**: 35 characters when transferring to an IBAN, 15 characters for others., review: map{numberOfApprovalsRequired: int(int32), scaOnApproval: bool}, type: str(bankTransfer/internalTransfer/internalDirectDebit) # The type of transfer.  Possible values:   - **bankTransfer**: for push transfers to a transfer instrument or a bank account. The `category` must be **bank**. - **internalTransfer**: for push transfers between balance accounts. The `category` must be **internal**. - **internalDirectDebit**: for pull transfers (direct debits) between balance accounts. The `category` must be **internal**., ultimateParty: map{address: map, dateOfBirth: str(date), email: str, firstName: str, fullName: str, fundingInstrument: map, lastName: str, reference: str, type: str, url: str}}\n@returns(202) {accountHolder: map{description: str, id: str, reference: str}, amount: map{currency: str, value: int(int64)}, balanceAccount: map{description: str, id: str, reference: str}, balanceAccountId: str, category: str, counterparty: map{balanceAccountId: str, bankAccount: map{accountHolder: map{address: map, dateOfBirth: str(date), email: str, firstName: str, fullName: str, lastName: str, reference: str, type: str, url: str}, accountIdentification: any, storedPaymentMethodId: str}, card: map{cardHolder: map{address: map, dateOfBirth: str(date), email: str, firstName: str, fullName: str, lastName: str, reference: str, type: str, url: str}, cardIdentification: map{expiryMonth: str, expiryYear: str, issueNumber: str, number: str, startMonth: str, startYear: str, storedPaymentMethodId: str}}, merchant: map{acquirerId: str, mcc: str, merchantId: str, nameLocation: map{city: str, country: str, countryOfOrigin: str, name: str, rawData: str, state: str}, postalCode: str}, transferInstrumentId: str}, createdAt: str(date-time), creationDate: str(date-time), description: str, directDebitInformation: map{dateOfSignature: str(date-time), dueDate: str(date-time), mandateId: str, sequenceType: str}, direction: str, executionDate: map{date: str(date), timezone: str}, id: str, paymentInstrument: map{description: str, id: str, reference: str, tokenType: str}, paymentInstrumentId: str, priority: str, reason: str, reference: str, referenceForBeneficiary: str, review: map{numberOfApprovalsRequired: int(int32), scaOnApproval: str}, status: str, type: str} # Accepted - the request has been accepted for processing, but the processing has not been completed.\n@errors {401: Unauthorized - authentication required., 403: Forbidden - insufficient permissions to process the request., 422: Unprocessable Entity - a request validation error., 500: Internal Server Error - the server could not process the request.}\n@example_request {\"amount\":{\"value\":110000,\"currency\":\"EUR\"},\"balanceAccountId\":\"BAB8B2C3D4E5F6G7H8D9J6GD4\",\"category\":\"bank\",\"counterparty\":{\"bankAccount\":{\"accountHolder\":{\"fullName\":\"A. Klaassen\",\"address\":{\"city\":\"San Francisco\",\"country\":\"US\",\"postalCode\":\"94678\",\"stateOrProvince\":\"CA\",\"line1\":\"274\",\"line2\":\"Brannan Street\"}},\"accountIdentification\":{\"type\":\"numberAndBic\",\"accountNumber\":\"123456789\",\"bic\":\"BOFAUS3NXXX\"}}},\"priority\":\"crossBorder\",\"referenceForBeneficiary\":\"Your-reference-sent-to-the-beneficiary\",\"reference\":\"Your internal reference for the transfer\",\"description\":\"Your description for the transfer\"}\n\n@endpoint POST /transfers/approve\n@desc Approve initiated transfers\n@optional {Idempotency-Key: str # A unique identifier for the message with a maximum of 64 characters (we recommend a UUID)., WWW-Authenticate: str # Header for authenticating through SCA, transferIds: [str] # Contains the unique identifiers of the transfers that you want to approve.}\n@returns(200) No Content - look at the actual response code for the status of the request.\n@errors {401: Unauthorized - authentication required., 403: Forbidden - insufficient permissions to process the request., 422: Unprocessable Entity - a request validation error., 500: Internal Server Error - the server could not process the request.}\n\n@endpoint POST /transfers/cancel\n@desc Cancel initiated transfers\n@optional {Idempotency-Key: str # A unique identifier for the message with a maximum of 64 characters (we recommend a UUID)., transferIds: [str] # Contains the unique identifiers of the transfers that you want to cancel.}\n@returns(200) No Content - look at the actual response code for the status of the request.\n@errors {401: Unauthorized - authentication required., 403: Forbidden - insufficient permissions to process the request., 422: Unprocessable Entity - a request validation error., 500: Internal Server Error - the server could not process the request.}\n\n@endpoint POST /transfers/{transferId}/returns\n@desc Return a transfer\n@required {transferId: str # The unique identifier of the transfer to be returned., amount: map{currency!: str, value!: int(int64)}}\n@optional {Idempotency-Key: str # A unique identifier for the message with a maximum of 64 characters (we recommend a UUID)., reference: str # Your internal reference for the return. If you don't provide this in the request, Adyen generates a unique reference. This reference is used in all communication with you about the instruction status.  We recommend using a unique value per instruction. If you need to provide multiple references for a transaction, separate them with hyphens (\"-\").}\n@returns(200) {id: str, reference: str, status: str, transferId: str} # OK - the request has succeeded.\n@errors {401: Unauthorized - authentication required., 403: Forbidden - insufficient permissions to process the request., 422: Unprocessable Entity - a request validation error., 500: Internal Server Error - the server could not process the request.}\n\n@endgroup\n\n@end\n"}}