# Approve or reject incoming wire transfers

Endpoint: POST /bank_transfers_in/authorisation_request
Version: v3
Security: webhooks_key

## Security:

  - `webhooks_key` (unknown)
    apiKey in header webhooks-key

## Header parameters:

  - `request-ref` (string)
    A unique call reference included in every call, that enables the receiver to avoid duplicate handling of a webhook request (e.g. webhook was resent).

  - `published-timestamp` (integer, required)
    The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

  - `signature` (string, required)
    The signature to verify the authenticity of this request.  This is the base64 hash (HmacSHA256) of the `published-timestamp` using your API key.

  - `signature-v2` (string, required)
    The signature to verify the authenticity of this request.  This is the base64 hash (HmacSHA256) of the `call-ref + payload + published-timestamp` using your API key.

## Request fields (application/json):

  - `id` (string, required)
    The unique identifier of the bank transfer

  - `source` (object, required)

  - `source.instrument` (object, required)

  - `source.instrument.type` (string, required)
    Enum: "linked_accounts", "unknown_sender_accounts"

  - `source.instrument.instrument` (any, required)

  - `source.instrument.instrument.id` (string, required)
    The unique identifier of the linked account.

  - `source.instrument.instrument.profileId` (string, required)
    The profile Id which a specific identity, instrument or transaction type is linked to.

Profiles contain configuration and determine behavioral aspects of the newly created transaction, for example, fees that may apply.

You can have one or more profiles linked to your application, and these can be used to drive different behaviors according to your product's needs.

Profile Ids can be found in the Multi Portal, in the API Credentials page.

  - `source.instrument.instrument.tag` (string)
    The tag field is a custom field that can be used to search and filter.

  - `source.instrument.instrument.friendlyName` (string)
    A user-friendly label assigned to the Linked Account to help end-users easily identify it within the application. This name can be updated at any time using the `PATCH` endpoint

  - `source.instrument.instrument.name` (string, required)
    The full name or corporate name of the account holder as registered with the external bank or payment service provider. This is the name under which the account is officially held.

  - `source.instrument.instrument.type` (string)
    An account can be of two types, Personal or Business:
- PERSONAL means that the account held at the external bank or PSP is registered under the ownership of a natural person or consumer identity;
- BUSINESS means that the account held at the external bank or PSP is registered under the ownership of a corporate entity.
    Enum: "BUSINESS", "PERSONAL"

  - `source.instrument.instrument.currency` (string)
    The currency expressed in ISO-4217 code. Example: GBP, EUR, USD.

  - `source.instrument.instrument.country` (string, required)
    The country of the bank or institution at which the account is held.

  - `source.instrument.instrument.accountReference` (any)
    The IBAN or Account Number and Sort Code of the account held at the external bank or payment service provider.

  - `source.instrument.instrument.accountReference.accountNumber` (string, required)
    Account number

  - `source.instrument.instrument.accountReference.sortCode` (string, required)
    Sort code

  - `source.instrument.instrument.accountReference.secondaryReference` (string)
    Optional secondary reference for accounts without unique sort codes.

  - `source.instrument.instrument.accountReference.iban` (string, required)
    International Bank Account Number, required for wire transfer.

  - `source.instrument.instrument.accountReference.bankIdentifierCode` (string)
    BIC, for wire transfer over SEPA or RIX.

  - `source.instrument.instrument.accountReference.accountDescriptor` (string, required)

  - `source.instrument.instrument.state` (string, required)
    The state of the linked account:
- **PENDING_VERIFICATION**: The Linked Account is pending the completion of the required verification steps.
- **ACTIVE**: The Linked Account is verified and active, ready to be used for self-to-self wire transfers.
- **BLOCKED**: The Linked Account is temporarily blocked, preventing any use of this external account in self-to-self wire transfers. A Linked Account can be unblocked by calling the Multi API endpoint `POST /linked_accounts/{id}/unblock`.
- **REMOVED**: The Linked Account has been removed from the platform and can no longer be used for self-to-self wire transfers unless a new verification is completed in future.
- **REJECTED**: The Linked Account failed the verification process and cannot be used for self-to-self wire transfers unless a new verification is completed in future.
A Linked Account can transition through these different overall states, starting at the `PENDING_VERIFICATION` state until all verification steps are followed through.
    Enum: "PENDING_VERIFICATION", "BLOCKED", "ACTIVE", "REJECTED", "REMOVED"

  - `source.instrument.instrument.creationTimestamp` (integer)
    The timestamp when the linked account was created, expressed in Epoch timestamp using millisecond precision.

  - `source.instrument.instrument.owner` (object)

  - `source.instrument.instrument.owner.type` (string, required)

  - `source.instrument.instrument.owner.id` (string, required)

  - `source.instrument.instrument.name` (string)

  - `source.instrument.instrument.accountReference` (any)

  - `source.instrument.reference` (string)
    This is an external reference (if available), input by the sender when creating the payment, and intended for the recipient.

  - `destination` (object, required)

  - `destination.instrument` (object, required)

  - `destination.instrument.type` (string, required)
    Enum: "managed_accounts"

  - `destination.instrument.instrument` (any, required)

  - `destination.instrument.instrument.id` (string, required)
    The unique identifier of a Managed Account.

  - `destination.instrument.instrument.friendlyName` (string, required)
    The friendly name given to the managed account.

  - `destination.instrument.instrument.balances` (object, required)
    Instruments with funds have 2 balances, the `availableBalance` indicating the funds that are available for transactions such as purchases, and the `actualBalance` indicating the funds that are actually on the instrument.

  - `destination.instrument.instrument.balances.availableBalance` (integer)
    The funds available for transactions on the instrument. Funds that are blocked or pending are not included in the available balance.

  - `destination.instrument.instrument.balances.actualBalance` (integer)
    The funds that are actually on the instrument. Funds that are blocked or pending, due to for example, a purchase authorisation or a pending deposit, are included in the actual balance.

  - `destination.instrument.instrument.state` (object, required)

  - `destination.instrument.instrument.state.state` (string, required)
    The state of the instrument indicating what it can and cannot do as follows:
- ACTIVE: The instrument is in an active state and can be used in transactions.
- BLOCKED: The instrument is temporarily blocked and cannot be used. Any funds on the instrument are also frozen. The `blockedReason` provides more information as to why it was blocked.
- DESTROYED: The instrument has been permanently destroyed. The `destroyReason` provides more information as to why it was destroyed.
- NOT_ENABLED: The instrument is not enabled for use, since the linked user has not completed all necessary verification steps.
    Enum: "ACTIVE", "BLOCKED", "DESTROYED", "NOT_ENABLED"

  - `destination.instrument.instrument.state.blockedReason` (string)
    The reason why the instrument has been blocked:
- USER: The root, or an authorised user, of the identity owning the instrument has temporarily blocked the instrument.
- SYSTEM: The platform or an administrator of the platform has temporarily blocked the instrument.
- LOST: The instrument has been blocked because it was marked as lost.
- SINGLE_SPEND: The instrument has been automatically blocked after its first successful transaction (single-spend card).
    Enum: "USER", "SYSTEM", "LOST", "SINGLE_SPEND"

  - `destination.instrument.instrument.state.destroyedReason` (string)
    The reason why the instrument has been destroyed:
- SYSTEM: The platform or an administrator of the platform has destroyed the instrument.
- USER: The root, or an authorised user, of the identity owning the instrument has destroyed the instrument.
- LOST: The instrument was automatically destroyed as it was marked as lost.
- STOLEN: The instrument was automatically destroyed as it was marked as stolen.
- EXPIRED: The instrument was automatically destroyed as it expired.
- COMPROMISED: The instrument was automatically destroyed as it was marked as compromised.
- SINGLE_SPEND: The instrument was automatically destroyed as it was a single-spend card that was used.
    Enum: "SYSTEM", "USER", "LOST", "STOLEN", "EXPIRED", "COMPROMISED", "SINGLE_SPEND"

  - `destination.instrument.instrument.creationTimestamp` (integer, required)
    The time when the managed account was created, expressed in Epoch timestamp using millisecond precision.

  - `destination.instrument.instrument.lowBalanceThreshold` (integer)
    Sends a low balance notification webhook when the available balance drops below this amount. Currency is inherited from the managed account.

  - `destination.owner` (object, required)

  - `destination.owner.type` (string, required)
    Enum: "consumers", "corporates"

  - `destination.owner.owner` (any, required)

  - `destination.owner.owner.id` (object, required)

  - `destination.owner.owner.id.type` (string, required)
    Indicates the identity type.
    Enum: "CONSUMER", "CORPORATE"

  - `destination.owner.owner.id.id` (string, required)
    The identifier for the identity.

  - `destination.owner.owner.rootUser` (object, required)

  - `destination.owner.owner.rootUser.name` (string, required)
    First name of the root user.

  - `destination.owner.owner.rootUser.surname` (string, required)
    Last name of the root user.

  - `destination.owner.owner.rootUser.email` (string, required)
    E-mail Address of the user

  - `destination.owner.owner.rootUser.mobile` (object, required)

  - `destination.owner.owner.rootUser.mobile.countryCode` (string, required)
    The country code of the user mobile number (e.g. +44).

  - `destination.owner.owner.rootUser.mobile.number` (string, required)
    The mobile number of the user - excluding country code.

  - `destination.owner.owner.rootUser.companyPosition` (string, required)
    The company position of the Corporate Root User.
    Enum: "DIRECTOR", "AUTHORISED_REPRESENTATIVE"

  - `destination.owner.owner.rootUser.active` (boolean, required)
    The state of the root user. If false, then the user will not be able to log in.

  - `destination.owner.owner.rootUser.emailVerified` (boolean, required)
    Indicates if the root user's email has been verified.

  - `destination.owner.owner.rootUser.mobileNumberVerified` (boolean, required)
    Indicates if the root user's mobile number has been verified.

  - `destination.owner.owner.rootUser.dateOfBirth` (object)

  - `destination.owner.owner.rootUser.dateOfBirth.year` (integer, required)

  - `destination.owner.owner.rootUser.dateOfBirth.month` (integer, required)

  - `destination.owner.owner.rootUser.dateOfBirth.day` (integer, required)

  - `destination.owner.owner.rootUser.locale` (string)
    BCP47 locale code (e.g. en, en-US). The locale determines which email and SMS user notification templates are used.
    Example: en-GB

  - `destination.owner.owner.rootUser.brand` (string)
    Brand identifier used to determine the set of email and SMS user notification templates. Must be alphanumeric, up to 25 characters, and contain no spaces.

  - `destination.owner.owner.company` (object, required)

  - `destination.owner.owner.company.name` (string, required)
    The registered name of the company.

  - `destination.owner.owner.company.type` (string, required)
    Supported company types - if company type is not listed, please contact our support team to check if the company type can be supported.
    Enum: "SOLE_TRADER", "LLC", "PUBLIC_LIMITED_COMPANY", "LIMITED_LIABILITY_PARTNERSHIP", "NON_PROFIT_ORGANISATION"

  - `destination.owner.owner.company.registrationNumber` (string)
    The company registration number.

  - `destination.owner.owner.company.registeredAddress` (object)
    The legal address of the company. This information is captured via the Due Diligence (KYB) process.

  - `destination.owner.owner.company.registeredAddress.addressLine1` (string, required)

  - `destination.owner.owner.company.registeredAddress.addressLine2` (string)

  - `destination.owner.owner.company.registeredAddress.city` (string, required)

  - `destination.owner.owner.company.registeredAddress.postCode` (string)

  - `destination.owner.owner.company.registeredAddress.state` (string)

  - `destination.owner.owner.company.registeredAddress.country` (string, required)
    Country of the identity in ISO 3166 alpha-2 format.

  - `destination.owner.owner.company.businessAddress` (object)

  - `destination.owner.owner.company.businessAddress.addressLine1` (string, required)
    The first line of the address.

  - `destination.owner.owner.company.businessAddress.addressLine2` (string)
    The second line of the address.

  - `destination.owner.owner.company.businessAddress.city` (string, required)
    The city of the address.

  - `destination.owner.owner.company.businessAddress.postCode` (string, required)
    The post code associated with the address.

  - `destination.owner.owner.company.businessAddress.state` (string)
    The state of the address.

  - `destination.owner.owner.company.businessAddress.country` (string, required)
    The country of the address expressed in ISO 3166 alpha-2 format.

  - `destination.owner.owner.company.countryOfRegistration` (string, required)
    The country of company registration in ISO 3166 alpha-2.

  - `destination.owner.owner.industry` (string)
    The industry of the identity.
    Enum: "ACCOUNTING", "AUDIT", "FINANCE", "PUBLIC_SECTOR_ADMINISTRATION", "ART_ENTERTAINMENT", "AUTO_AVIATION", "BANKING_LENDING", "BUSINESS_CONSULTANCY_LEGAL", "CONSTRUCTION_REPAIR", "EDUCATION_PROFESSIONAL_SERVICES", "INFORMATIONAL_TECHNOLOGIES", "TOBACCO_ALCOHOL", "GAMING_GAMBLING", "MEDICAL_SERVICES", "MANUFACTURING", "PR_MARKETING", "PRECIOUS_GOODS_JEWELRY", "NON_GOVERNMENTAL_ORGANIZATION", "INSURANCE_SECURITY", "RETAIL_WHOLESALE", "TRAVEL_TOURISM", "FREELANCER"

  - `destination.owner.owner.sourceOfFunds` (string)
    The corporate's source of funds.
    Enum: "LABOUR_CONTRACT", "CIVIL_CONTRACT", "RENT", "FUNDS_FROM_OTHER_AUXILIARY_SOURCES", "SALE_OF_MOVABLE_ASSETS", "SALE_OF_REAL_ESTATE", "ORDINARY_BUSINESS_ACTIVITY", "DIVIDENDS", "LOAN_FROM_FINANCIAL_INSTITUTIONS_CREDIT_UNIONS", "LOAN_FROM_THIRD_PARTIES", "SALE_OF_COMPANY_SHARES_BUSINESS", "OTHER", "DONATION", "INHERITANCE", "ORIGIN_OF_FUNDS_UNKNOWN"

  - `destination.owner.owner.sourceOfFundsOther` (string)
    Description of source of funds in case `OTHER` was chosen.

  - `destination.owner.owner.acceptedTerms` (boolean)
    Must be set to *true* to indicate that the root user has accepted the terms and conditions.

  - `destination.owner.owner.ipAddress` (string, required)
    The IP address of the user doing the registration.

  - `destination.owner.owner.feeGroup` (string)
    Fee groups allow the possibility to charge different fees to users under the same profile. If fee groups are not required, ignore this field.

  - `destination.owner.owner.creationTimestamp` (integer, required)
    The time when the Corporate was created, expressed in Epoch timestamp using millisecond precision.

  - `destination.owner.owner.retailQualifier` (string)
    Indicates the type of corporate entity based on its retail status.
    Enum: "RETAIL", "NON_RETAIL", "UNKNOWN"

  - `destination.owner.owner.creationTimestamp` (integer, required)
    The time when this consumer was created, expressed in Epoch timestamp using millisecond precision.

  - `destination.owner.owner.ipAddress` (string, required)
    The IP address of the consumer user doing the registration.

  - `destination.owner.owner.acceptedTerms` (boolean)
    Must be set to *true* to indicate that the consumer root user has accepted the terms and conditions.

  - `destination.owner.owner.feeGroup` (string)
    The fee group which the consumer is bound to.

  - `destination.owner.owner.sourceOfFunds` (string)
    The consumer's source of funds.
    Enum: "PERSONAL_SAVINGS", "FAMILY_SAVINGS", "LABOUR_CONTRACT", "CIVIL_CONTRACT", "RENT", "FUNDS_FROM_OTHER_AUXILIARY_SOURCES", "SALE_OF_MOVABLE_ASSETS", "SALE_OF_REAL_ESTATE", "ORDINARY_BUSINESS_ACTIVITY", "DIVIDENDS", "LOAN_FROM_FINANCIAL_INSTITUTIONS_CREDIT_UNIONS", "LOAN_FROM_THIRD_PARTIES", "INHERITANCE", "SALE_OF_COMPANY_SHARES_BUSINESS", "OTHER"

  - `amount` (object, required)
    The object representing a monetary amount in a particular currency.

  - `amount.amount` (integer, required)
    The monetary amount, scaled to the lowest denomination of the currency.

Example, an amount of 1000 for a EUR currency is actually 1000 Euro cents or EUR 10.00.

  - `timestamp` (integer, required)
    The timestamp of the transaction, using epoch timestamp with millisecond precision.

## Response 200:

  - `200` (unknown)
    Authorisation event received with `APPROVED` or `DECLINED` decision.

## Response 200 fields (application/json):

  - `result` (string)
    Enum: "APPROVED", "DENIED"

## Response 404:

  - `404` (unknown)
    Not found - The requested resource couldn't be found.

## Response 404 fields (application/json):

  - `code` (string)

  - `message` (string)

## Response 404 headers (application/json):

  - `request-ref` (string, required)
    A request identifier. Providing this reference when contacting our support team will help us investigate your query.

## Response default:

  - `default` (unknown)
    Error

## Response default fields (application/json):

  - `code` (string)

  - `message` (string)