# finAPI

## Create money transfer
### POST /api/v1/payments/moneyTransfers

| Field | Type | Description |
| -------- | -------- | -------- |
| [x] singleBooking | boolean | Default: false <br/> This field is only relevant when you pass multiple orders. It determines whether the orders should be processed by the bank as one collective booking |
| [x] accountId | integer | Identifier of the account that should be used for the money transfer. If you want to do a standalone money transfer leave this field unset. |
| [x] iban | string | IBAN of the account that should be used for the money transfer. Use this field only if you want to do a standalone money transfer |
| [x] executionDate | string | Format: 'YYYY-MM-DD' <br/> Execution date for the money transfer(s). May not be in the past. |
| - moneyTransfers* | array of object | Min Items: 1 Max Items: 15000 <br/> Type: MoneyTransferOrderParams <br/> List of money transfer orders (may contain at most 15000 items). |
| -> [x] counterpartName | string | Name of the counterpart. Has to be provided for the SEPA EUR transfers. |
| -> [x] counterpartIban* | string | IBAN of the counterpart's account. |
| -> [x] counterpartBic | string | BIC of the counterpart's account. |
| -> [x] amount* | number | The amount of the payment. Must be a positive decimal number with at most two decimal places. |
| -> purpose | string | The purpose of the transfer transaction |
| -> [x] sepaPurposeCode | string | SEPA purpose code, according to ISO 20022 |
| -> [x] endToEndId | string | End-To-End ID for the transfer transaction. Only applicable for the SEPA EUR transfers and will be discarded for other transfers. |
| -> structuredRemittanceInformation* | \[string\] | Structure Remittance Information. |
| instantPayment | boolean | Default: false <br/> Whether the order should be submitted to the bank as an instant SEPA order. |

### RESPONSES
#### 201 CREATED_PAYMENT
| Field | Type | Description |
| -------- | -------- | -------- |
| id* | integer | Payment identifier |
| accountId* | integer┃null | Identifier of the account to which this payment relates. This field is only set if it was specified upon creation of the payment. |
| iban* | string┃null | IBAN of the account to which this payment relates. This field is only set if it was specified upon creation of the payment. |
| type* | enum | Allowed: MONEY_TRANSFER┃DIRECT_DEBIT <br/> Type: PaymentType |
| amount* | number | Total money amount of the payment order(s), as absolute value |
| orderCount* | integer | Total count of orders included in this payment |
| status* | enum | Allowed: <br/> OPEN┃PENDING┃SUCCESSFUL┃<br/>NOT_SUCCESSFUL┃DISCARDED <br/> Type: OrderInitiationStatus <br/> <br/> • OPEN: payment was created in finAPI, but not yet submitted to the bank. <br/> • PENDING: payment was requested at the bank, but not confirmed yet. <br/> • SUCCESSFUL: payment was successfully initiated. <br/> • NOT_SUCCESSFUL: payment could not be initiated. <br/> • DISCARDED: payment was discarded. |
| bankMessage* | string┃null | The bank's response to the most recent request for this payment. <br/> Initial submission of the payment ┃ execution request ┃ subsequent status checks. |
| requestDate* | string┃null | Format: 'YYYY-MM-DD HH:MM:SS.SSS' (german time) <br/> Time of when finAPI submitted this payment to the bank. |
| executionDate* | string┃null | Format: 'YYYY-MM-DD HH:MM:SS.SSS' (german time) <br/> Time of when the execution of this payment has completed. |
| instructedExecutionDate* | string┃null | Format: 'YYYY-MM-DD' <br/> The date that was specified as 'executionDate' upon creation of the payment. This field may not be set if no 'executionDate' was specified upon payment creation. |

#### 400 BAD_REQUEST
#### 403 Incorrect authorization role or you are not allowed to call this service for other reasons (see error message)
#### 404 Given account not found
#### 422 ILLEGAL_FIELD_VALUE (if the given execution date is invalid) ┃ ILLEGAL_ENTITY_STATE ┃ (if the mandator is not configured correctly to use this service. Please contact our support) ┃ UNSUPPORTED_ORDER (if the request doesn't fit to the capabilities of any of the interfaces connected to the given account; or if the given IBAN relates to a bank that is unknown or not available to you (you may want to use the 'Get and search all banks' service to check the IBAN prior to calling this service))
#### 500 An unexpected error occurred

| Field | Type | Description |
| -------- | -------- | -------- |
| - errors* | array of object | Type: ErrorDetails <br/> List of errors
| -> message* | string┃null | Error message |
| -> code* | enum | Allowed: <br/> ADDITIONAL_AUTHENTICATION_REQUIRED┃BAD_REQUEST┃BANK_SERVER_REJECTION┃COLLECTIVE_MONEY_TRANSFER_NOT_SUPPORTED┃ENTITY_EXISTS┃FORBIDDEN┃IBAN_ONLY_DIRECT_DEBIT_NOT_SUPPORTED┃IBAN_ONLY_MONEY_TRANSFER_NOT_SUPPORTED┃ILLEGAL_ENTITY_STATE┃ILLEGAL_FIELD_VALUE┃ILLEGAL_PAGE_SIZE┃INVALID_CONSENT┃INVALID_FILTER_OPTIONS┃INVALID_TOKEN┃INVALID_TWO_STEP_PROCEDURE┃LOCKED┃LOGIN_FIELDS_MISMATCH┃METHOD_NOT_ALLOWED┃MISSING_CREDENTIALS┃MISSING_FIELD┃MISSING_TWO_STEP_PROCEDURE┃NO_ACCOUNTS_FOR_TYPE_LIST┃NO_CERTIFICATE┃NO_EXISTING_CHALLENGE┃NO_TPP_CLIENT_CREDENTIALS┃NO_PSU_METADATA┃TOO_MANY_IDS┃UNAUTHORIZED_ACCESS┃UNEXPECTED_ERROR┃UNKNOWN_ENTITY┃UNSUPPORTED_BANK┃UNSUPPORTED_FEATURE┃UNSUPPORTED_MEDIA_TYPE┃UNSUPPORTED_ORDER┃USER_ALREADY_VERIFIED┃USER_NOT_VERIFIED┃WEB_FORM_ABORTED┃WEB_FORM_REQUIRED <br/> Type: ErrorCode |
| -> type* | enum | Allowed: BUSINESS┃TECHNICAL <br/> Type: ErrorType |
| - multiStepAuthentication* | object | Type: MultiStepAuthenticationChallenge |
| -> hash* | string | Hash for this multi-step authentication flow. Must be passed back to finAPI when continuing the flow. |
| -> status* | enum | Allowed: <br/> CHALLENGE_RESPONSE_REQUIRED┃<br/>TWO_STEP_PROCEDURE_REQUIRED┃<br/>REDIRECT_REQUIRED┃<br/>DECOUPLED_AUTH_REQUIRED┃<br/>DECOUPLED_AUTH_IN_PROGRESS <br/> Type: MsaStatus <br/> <br/> TWO_STEP_PROCEDURE_REQUIRED means that the bank has requested an SCA method selection for the user. In this case, the service should be recalled with a chosen TSP-ID set to the 'twoStepProcedureId' field. <br/> CHALLENGE_RESPONSE_REQUIRED means that the bank has requested a challenge code for the previously given TSP (SCA). This status can be completed by setting the 'challengeResponse' field. <br/> REDIRECT_REQUIRED user must be redirected to the bank's website, to finish authentication. <br/> DECOUPLED_AUTH_REQUIRED bank ssked for the decoupled authentication. In this case, the 'decoupledCallback' field must be set to true to complete the authentication. <br/> DECOUPLED_AUTH_IN_PROGRESS bank is waiting for the completion of the decoupled authentication by the user. Until this is done, the service should be recalled at most every 5 seconds with the 'decoupledCallback' field set to 'true'. Once the decoupled authentication is completed by the user, the service returns a successful response. |
| -> challengeMessage* | string┃null | In case of status = CHALLENGE_RESPONSE_REQUIRED, this field contains a message from the bank containing instructions for the user on how to proceed with the authorization. |
| -> answerFieldLabel* | string┃null | Suggestion from the bank on how you can label your input field where the user should enter his challenge response. |
| -> redirectUrl* | string┃null | In case of status = REDIRECT_REQUIRED, this field contains the URL to which you must direct the user. It already includes the redirect URL back to your client that you have passed when initiating the service call. |
| -> redirectContext* | string┃null | Set in case of status = REDIRECT_REQUIRED. When the bank redirects the user back to your client, the redirect URL will contain this string, which you must process to identify the user context for the callback on your side. |
| -> redirectContextField* | string┃null | Set in case of status = REDIRECT_REQUIRED. This field is set to the name of the query parameter that contains the 'redirectContext' in the redirect URL from the bank back to your client. |
| -> - twoStepProcedures* | array of object | Type: TwoStepProcedure <br/> In case of status = TWO_STEP_PROCEDURE_REQUIRED, this field contains the available two-step procedures. |
| -> -> procedureId* | string | Bank-given ID of the procedure |
| -> -> procedureName* | string | Bank-given name of the procedure |
| -> -> procedureChallengeType* | string┃null | The challenge type of the procedure. Possible values are: <br/> • TEXT - the challenge will be a text that contains instructions for the user on how to proceed with the authorization. <br/> • PHOTO - the challenge will contain a BASE-64 string depicting a photo (or any kind of QR-code-like data) that must be shown to the user. <br/> • FLICKER_CODE - the challenge will contain a BASE-64 string depicting a flicker code animation that must be shown to the user. |
| -> -> implicitExecute* | boolean | If 'true', then there is no need for your client to pass back anything to finAPI to continue the authorization. |
| -> photoTanMimeType* | string┃null | In case that the 'photoTanData' field is set (i.e. not null), this field contains the MIME type to use for interpreting the photo data (e.g.: 'image/png') |
| -> photoTanData* | string┃null | In case that the bank server has instructed the user to scan a photo (or more generally speaking, any kind of QR-code-like data), then this field will contain the raw data of the photo as a BASE-64 string. |
| -> opticalData* | string┃null | In case that the bank server has instructed the user to scan a flicker code, then this field will contain the raw data for the flicker animation as a BASE-64 string. |
| -> opticalDataAsReinerSct* | boolean | This field is only relevant when the field 'opticalData' is set. It depicts whether the optical data should be processed with the use of the Reiner SCT flicker algorithm. For more details, see: Flicker Code Template |
| date* | string | Format: 'YYYY-MM-DD HH:MM:SS.SSS' (german time) <br/> Server date of when the error(s) occurred |
| endpoint* | string | The service endpoint that was called |
| authContext* | string | Information about the authorization context of the service call |
| bank* | string┃null | BLZ and name (in format " - ") of a bank that was used for the original request |

#### 401 Not authenticated or invalid access_token

| Field | Type | Description |
| -------- | -------- | -------- |
| error* | string | Error type |
| error_description* | string | Error description |

## GET /api/v1/payments

| Field | Type | Description |
| -------- | -------- | -------- |
| ids | array of integer | A comma-separated list of payment identifiers (maximum number of identifiers is 1000.) |
| accountIds | array of integer | A comma-separated list of account identifiers. (maximum number of identifiers is 1000.) |
| minAmount | number | only payments whose (absolute) total amount is equal or greater than the given (positive) amount. |
| maxAmount | number | only payments whose (absolute) total amount is equal or less than the given (positive) amount.
| status | array of string | A comma-separated list of payment statuses. Allowed values: 'OPEN', 'PENDING', 'SUCCESSFUL', 'NOT_SUCCESSFUL' or 'DISCARDED'. Example: 'OPEN,PENDING'. |
| page | integer | Default: 1 <br/> Min 1 <br/> Result page that you want to retrieve |
| perPage | integer | Default: 20 <br/> Min 1┃Max 500 <br/> Maximum number of records per page. |
| order | array of string | Default: id,ASC <br/> ('id', 'amount', 'requestDate', 'executionDate' and 'instructedExecutionDate') |

#### 200 List of requested payments

| Field | Type | Description |
| -------- | -------- | -------- |
| - payments* | array of object | Type: Payment <br/> List of received account payments |
| -> id* | integer | Payment identifier |
| -> accountId* | integer┃null | Identifier of the account to which this payment relates. This field is only set if it was specified upon creation of the payment. |
| -> iban* | string┃null | IBAN of the account to which this payment relates. This field is only set if it was specified upon creation of the payment. |
| -> type* | enum | Allowed: MONEY_TRANSFER┃DIRECT_DEBIT <br/> Type: PaymentType |
| -> amount* | number | Total money amount of the payment order(s), as absolute value |
| -> orderCount* | integer | Total count of orders included in this payment |
| -> status* | enum | Allowed: OPEN┃PENDING┃SUCCESSFUL┃NOT_SUCCESSFUL┃DISCARDED <br/> Type: OrderInitiationStatus <br/> <br/> • OPEN: means that this payment has been created in finAPI, but not yet submitted to the bank. <br/> • PENDING: means that this payment has been requested at the bank, but has not been confirmed yet. <br/> • SUCCESSFUL: means that this payment has been successfully initiated. <br/> • NOT_SUCCESSFUL: means that this payment could not be initiated successfully. <br/> • DISCARDED: means that this payment was discarded, either because another payment was requested for the same account before this payment was initiated and the bank does not support this, or because the user has aborted the initiation (when using finAPI's Web Form).
| -> bankMessage* | string┃null | The bank's response to the most recent request for this payment. Possible requests are: Initial submission of the payment, execution request or subsequent status checks. Note that this field may not always (or never) be set. Also, as long as the payment has not reached its final status, this field can always change. |
| -> requestDate*|string┃null|Format: 'YYYY-MM-DD HH:MM:SS.SSS' (german time) <br/> Time of when finAPI submitted this payment to the bank.|
| -> executionDate*|string┃null|Format: 'YYYY-MM-DD HH:MM:SS.SSS' (german time) <br/> Time of when the execution of this payment has completed.|
| -> instructedExecutionDate* | string┃null | Format: 'YYYY-MM-DD' <br/> The date that was specified as 'executionDate' upon creation of the payment. This field may not be set if no 'executionDate' was specified upon payment creation.|
| - paging* | object | Type: Paging <br/> Information for pagination |
| -> page* | integer | Constraints: Min 1 <br/> Current page number |
| -> perPage* | integer | Constraints: Min 1 <br/> Current page size (number of entries in this page) |
| -> pageCount* | integer | Constraints: Min 0 <br/> Total number of pages |
| -> totalCount* | integer | Constraints: Min 0 <br/> Total number of entries across all pages |

### 400 (wie oben) BAD_REQUEST
### 403 (wie oben) Incorrect authorization role or you are not allowed to call this service for other reasons (see error message).
### 500 (wie oben) Unexpected error occurred
### 401 (wie oben) Authentication required

## POST /api/v1/payments/submit

| Field | Type | Description |
| -------- | -------- | -------- |
| paymentId* | integer | Payment identifier |
| interface* | enum | Allowed: WEB_SCRAPER┃FINTS_SERVER┃XS2A <br/> Type: BankingInterface <br/> <br/>• FINTS_SERVER - means that finAPI will execute the payment via the bank's FinTS interface.<br/> • WEB_SCRAPER - means that finAPI will parse data from the bank's online banking website. <br/> • XS2A - means that finAPI will execute the payment via the bank's XS2A interface.Please note that XS2A doesn't support direct debits yet. |
| - loginCredentials | array of object | Type: LoginCredential |
| -> label* | string | The login field label, as defined by the respective bank interface. |
| -> value* | string | The value for the login field |
| redirectUrl | string | Must only be passed when the used interface has the property REDIRECT_APPROACH. The user will be redirected to the given URL from the bank's website after completing the bank login and (possibly) the SCA. |
| - multiStepAuthentication | object | Type: MultiStepAuthenticationCallback <br/> Container for multi-step authentication data. Required when a previous service call initiated a multi-step authentication. |
| -> hash* | string | Hash that was returned in the previous multi-step authentication error. |
| -> challengeResponse | string | Challenge response. Must be set when the previous multi-step authentication error had status 'CHALLENGE_RESPONSE_REQUIRED'. |
| -> twoStepProcedureId | string | The bank-given ID of the two-step-procedure that should be used for authentication. Must be set when the previous multi-step authentication error had status 'TWO_STEP_PROCEDURE_REQUIRED'. |
| -> redirectCallback | string | Must be passed when the previous multi-step authentication error had status 'REDIRECT_REQUIRED'. The value must consist of the complete query parameter list that was contained in the received redirect from the bank. |
| -> decoupledCallback | boolean | Must be passed when the previous multi-step authentication error had status 'DECOUPLED_AUTH_REQUIRED' or 'DECOUPLED_AUTH_IN_PROGRESS'. The field represents the state of the decoupled authentication meaning that when it's set to 'true', the end-user has completed the authentication process on bank's side. |

### 200 Submitted payment with updated status

| Field | Type | Description |
| -------- | -------- | -------- |
| id* | integer | Payment identifier |
| accountId* | integer┃null | Identifier of the account to which this payment relates. This field is only set if it was specified upon creation of the payment. |
| iban* | string┃null | IBAN of the account to which this payment relates. This field is only set if it was specified upon creation of the payment. |
| type* | enum | Allowed: MONEY_TRANSFER┃DIRECT_DEBIT <br/> Type: PaymentType |
| amount* | number | Total money amount of the payment order(s), as absolute value |
| orderCount* | integer | Total count of orders included in this payment |
| status* | enum | Allowed: OPEN┃PENDING┃SUCCESSFUL┃NOT_SUCCESSFUL┃DISCARDED <br/> Type: OrderInitiationStatus <br/> <br/> • OPEN: means that this payment has been created in finAPI, but not yet submitted to the bank. <br/> • PENDING: means that this payment has been requested at the bank, but has not been confirmed yet. <br/> • SUCCESSFUL: means that this payment has been successfully initiated. <br/> • NOT_SUCCESSFUL: means that this payment could not be initiated successfully. <br/> • DISCARDED: means that this payment was discarded, either because another payment was requested for the same account before this payment was initiated and the bank does not support this, or because the user has aborted the initiation (when using finAPI's Web Form). |
| bankMessage* | string┃null | The bank's response to the most recent request for this payment. Possible requests are: Initial submission of the payment, execution request or subsequent status checks. Note that this field may not always (or never) be set. Also, as long as the payment has not reached its final status, this field can always change. |
| requestDate* | string┃null | Format: 'YYYY-MM-DD HH:MM:SS.SSS' (german time) <br/> Time of when finAPI submitted this payment to the bank. |
| executionDate* | string┃null | Format: 'YYYY-MM-DD HH:MM:SS.SSS' (german time) <br/> Time of when the execution of this payment has completed. |
| instructedExecutionDate* | string┃null | Format: 'YYYY-MM-DD' <br/> The date that was specified as 'executionDate' upon creation of the payment. This field may not be set if no 'executionDate' was specified upon payment creation. |

### 400 (wie oben) BAD_REQUEST
### 403 (wie oben) Incorrect authorization role or you are not allowed to call this service for other reasons (see error message).
### 404 (wie oben) Given payment not found
### 422 (wie oben) ILLEGAL_ENTITY_STATE (finAPI supports only web scraping for the bank, but web scraping is disabled for the client ┃ not all login fields required by the bank connection interface are provided ┃ given interface doesn't exist for the account or has deprecated status) ┃ ILLEGAL_FIELD_VALUE ('redirectUrl' is not given, but the bank connection's interface has the REDIRECT_APPROACH property set ┃ 'redirectUrl' is given, but the bank connection's interface doesn't have the REDIRECT_APPROACH property set or the Web Form flow is used) ┃ ILLEGAL_ENTITY_STATE (mandator is not configured correctly to use this service) ┃ UNSUPPORTED_ORDER (given interface doesn't have the required capabilities to submit the payment ┃ payment relates to a bank that is unknown or not available to you) ┃ UNSUPPORTED_FEATURE (bank rejects the payment because it requires a feature that the bank does not support (e.g. FUTURE_DATED_PAYMENT)) ┃ BANK_SERVER_REJECTION (bank rejects the payment for an unexpected/unknown reason) ┃ NO_EXISTING_CHALLENGE
### 500 (wie oben) An unexpected error occurred
### 501 (wie oben) The bank associated with the payment is currently not supported by finAPI
### 510 (wie oben) TWO_STEP_PROCEDURE_REQUIRED (bank requested an SCA method selection for the user) ┃ CHALLENGE_RESPONSE_REQUIRED (bank requested a challenge code for the previously given TSP (SCA)) ┃ REDIRECT_REQUIRED (user must be redirected to the bank's website to finish authentication.) ┃ DECOUPLED_AUTH_REQUIRED (bank asked for the decoupled authentication.) ┃ DECOUPLED_AUTH_IN_PROGRESS (bank waits for the completion of the decoupled authentication by the user)
### 401 (wie oben) Not authenticated or invalid access_token