--- title: "Create a Bank Wire PayIn" method: POST path: "/v2.01/{ClientId}/payins/bankwire/direct" tags: ["bankWirePayins"] --- # Create a Bank Wire PayIn `POST /v2.01/{ClientId}/payins/bankwire/direct` **Caution – Retrieve the returned bank details dynamically** In addition to the `WireReference`, ensure you implement the `BankAccount` object parameter dynamically so the `IBAN`, `BIC`, and other response values appear as returned in for each pay-in. Mangopay may change the underlying bank account without prior notice and mismatched data my lead to delays. See the bank wire pay-in guide for more details. Create a Bank Wire PayIn This call declares the payment to be made by the end user and returns the `BankAccount` details and `WireReference` they must use. ## Path parameters - `ClientId` string, required ## Headers - `Authorization` string, required ## Request body - CreateABankWirePayInRequest - `Tag` string — Max. length: 255 characters Custom data that you can add to this object. - `AuthorId` string, required — The unique identifier of the user at the source of the transaction. - `CreditedUserId` string — **Default value:** The unique identifier of the owner of the credited wallet. The unique identifier of the user whose wallet is credited. - `CreditedWalletId` string, required — The unique identifier of the credited wallet. - `FlowDescriptor` FlowDescriptorRequest — Information about the Owner beneficiaries targeted by the pay-in and its subsequent transfers, who must all be KYC/KYB verified when the pay-in request is made ([read more](/guides/payin-beneficiaries)). If the `FlowDescriptor.Beneficiaries` is sent in the API request, then: - The transaction's `CreditedWalletId` holder is disregarded in KYC/KYB checks. - **ALL** `UserId` values in the array must be one of: - `OWNER` whose `KYCLevel` is `REGULAR` - `PLATFORM` The pay-in `Status` becomes `FAILED` with `ResultCode` [002951](/errors/codes/002951) if at least one `FlowDescriptor.Beneficiaries.UserId` is: - `PAYER` - `OWNER` whose `KYCLevel` is `LIGHT` If the `FlowDescriptor.Beneficiaries` is not sent in the API request, then the `CreditedWalletId` holder is subject to KYC/KYB checks. This property is optional for backwards compatibility but is recommended for all pay-in flows, even when the `CreditedWalletId` holder is a `PAYER` or the same value as one of the `FlowDescriptor.Beneficiaries`. - `Beneficiaries` FlowDescriptorRequestBeneficiariesItems[], nullable — Max. length: 5 items The list of up to 5 Natural or Legal Users declared as beneficiaries of the pay-in and its subsequent transfers, who must all be KYC/KYB verified when the pay-in request is made. The pay-in also fails if the `Beneficiaries` array contains nulled objects or invalid `UserId` values. - `UserId` string — The unique identifier of the Natural User or Legal User declared as a beneficiary of the pay-in. - `DeclaredDebitedFunds` CreateABankWirePayInRequestDeclaredDebitedFunds, required — Information about the declared funds to be wired by the end user to the returned bank account. - `Currency` string, required — **Allowed values:** The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings). The currency of the amount. - `Amount` integer, required — The amount of the currency in its minor unit. For example, EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`. - `DeclaredFees` CreateABankWirePayInRequestDeclaredFees, required — Information about the fees to be taken by the platform for this transaction (and hence transferred to the Fees Wallet). - `Currency` string, required — **Allowed values:** The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings). The currency of the amount. - `Amount` integer, required — The amount of the currency in its minor unit. For example, EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`. - `ProfilingAttemptReference` string — The unique reference generated for the profiling session, used by the fraud prevention solution to produce recommendations for the transaction using the profiling data. **Note:** Parameter not returned by the API. Profiling feature available on request – contact Mangopay via the Dashboard for more information. ## Response `200` Success - BankWirePayInResponse — A direct bank wire pay-in: - `PaymentType` – `BANK_WIRE` - `ExecutionType` – `DIRECT` - `Id` string — Max length: 128 characters (see [data formats](/api-reference/overview/data-formats) for details) The unique identifier of the object. - `Tag` string — Max. length: 255 characters Custom data that you can add to this object. - `CreationDate` integer — Unix timestamp (UTC) of the date and time the object was created. - `ResultCode` string — The code indicating the result of the operation. This information is mostly used to handle errors or for filtering purposes. - `ResultMessage` string — The explanation of the result code. - `AuthorId` string — The unique identifier of the user at the source of the transaction. - `CreditedUserId` string — **Default value:** The unique identifier of the owner of the credited wallet. The unique identifier of the user whose wallet is credited. - `FlowDescriptor` FlowDescriptorResponse — Information about the Owner beneficiaries targeted by the pay-in and its subsequent transfers, who must all be KYC/KYB verified when the pay-in request is made ([read more](/guides/payin-beneficiaries)). If the `FlowDescriptor.Beneficiaries` is sent in the API request, then: - The transaction's `CreditedWalletId` holder is disregarded in KYC/KYB checks. - **ALL** `UserId` values in the array must be one of: - `OWNER` whose `KYCLevel` is `REGULAR` - `PLATFORM` The pay-in `Status` becomes `FAILED` with `ResultCode` [002951](/errors/codes/002951) if at least one `FlowDescriptor.Beneficiaries.UserId` is: - `PAYER` - `OWNER` whose `KYCLevel` is `LIGHT` If the `FlowDescriptor.Beneficiaries` is not sent in the API request, then the `CreditedWalletId` holder is subject to KYC/KYB checks. This property is optional for backwards compatibility but is recommended for all pay-in flows, even when the `CreditedWalletId` holder is a `PAYER` or the same value as one of the `FlowDescriptor.Beneficiaries`. - `FlowId` string — Unique identifier of the payment flow, used by Mangopay for internal purposes. - `Beneficiaries` FlowDescriptorResponseBeneficiariesItems[], nullable — Max. length: 5 items The list of up to 5 Natural or Legal Users declared as beneficiaries of the pay-in, who must all be KYC/KYB verified when the pay-in request is made. The pay-in also fails if the `Beneficiaries` array contains nulled objects or invalid `UserId` values. - `UserId` string — The unique identifier of the Natural User or Legal User declared as a beneficiary of the pay-in. - `DebitedFunds` BankWirePayInResponseDebitedFunds — Information about the debited funds. For a direct bank wire pay-in, the `DebitedFunds` displays placeholder values (currency `XXX` and amount `0`) until the `Status` changes to `SUCCEEDED`. - `Currency` string — **Allowed values:** The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings). The currency of the amount. - `Amount` integer — The amount of the currency in its minor unit. For example, EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`. - `CreditedFunds` BankWirePayInResponseCreditedFunds — Information about the credited funds (`CreditedFunds` = `DebitedFunds` - `Fees`). For a direct bank wire pay-in, the `CreditedFunds` displays placeholder values (currency `XXX` and amount `0`) until the `Status` changes to `SUCCEEDED`. - `Currency` string — **Allowed values:** The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings). The currency of the amount. - `Amount` integer — The amount of the currency in its minor unit. For example, EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`. - `Fees` BankWirePayInResponseFees — Information about the fees taken by the platform for this transaction (and hence transferred to the Fees Wallet). - `Currency` string — **Allowed values:** The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings). The currency of the amount. - `Amount` integer — The amount of the currency in its minor unit. For example, EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`. - `Status` string — **Returned values:** `CREATED`, `SUCCEEDED`, `FAILED` The status of the transaction. - `ExecutionDate` integer — Unix timestamp (UTC) of the date and time the status changed to `SUCCEEDED`, indicating that the transaction occurred. The statuses `CREATED` and `FAILED` return an `ExecutionDate` of `null`. - `Type` string — **Returned values:** `PAYIN`, `TRANSFER`, `CONVERSION`, `PAYOUT` The type of the transaction. - `Nature` string — **Returned values:** `REGULAR`, `REPUDIATION`, `REFUND`, `SETTLEMENT` The nature of the transaction, providing more information about the context in which the transaction occurred: - `REGULAR` – Relative to most of the transactions (pay-ins, payouts, and transfers) in a usual workflow. - `REPUDIATION` – Automatic withdrawal of funds from the platform's repudiation wallet as part of the dispute process (when the user has requested a chargeback). - `REFUND` – Reimbursement of a transaction to the user (pay-in refund), to a wallet (transfer refund), or of a payout (payout refund, only initiated by Mangopay). - `SETTLEMENT` – Transfer made to the repudiation wallet by the platform to settle a lost dispute. - `CreditedWalletId` string — The unique identifier of the credited wallet. - `DebitedWalletId` string — The unique identifier of the debited wallet. In the case of a pay-in, this value is always `null` since there is no debited wallet. - `PaymentType` string — **Returned values:** `BANK_WIRE` The payment type of the pay-in. - `ExecutionType` string — **Returned values:** `DIRECT` The execution type of the pay-in. - `DeclaredDebitedFunds` BankWirePayInResponseDeclaredDebitedFunds — Information about the declared debited funds. - `Currency` string — **Allowed values:** The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings). The currency of the amount. - `Amount` integer — The amount of the currency in its minor unit. For example, EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`. - `DeclaredFees` BankWirePayInResponseDeclaredFees — Information about the declared fees. - `Currency` string — **Allowed values:** The three-letter ISO 4217 code (EUR, GBP, etc.) of a supported currency (depends on feature, contract, and activation settings). The currency of the amount. - `Amount` integer — The amount of the currency in its minor unit. For example, EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`. - `WireReference` string — Max. length: 255 characters The reference which the end user must provide when making the bank wire. The `WireReference` is used to reconcile the funds that arrive on the bank account with the `DeclaredDebitedFunds` in the Direct Bank Wire PayIn object. **Caution:** This reference is specific to each payment and must be retrieved dynamically. - `BankAccount` BankWirePayInResponseBankAccount — Information about the bank account to which the bank wire must be made by the end user. **Caution:** Do not hardcode the returned values. Mangopay may change the underlying bank details without prior notice. - `OwnerAddress` Address — The postal address. - `AddressLine1` string — The first line of the address. - `AddressLine2` string — The second line of the address. - `City` string — The city of the address. - `Region` string — Required if `Country` is US, CA, or MX. The region of the address. - `PostalCode` string — The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces. - `Country` string — Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats)) The country of the address. - `Type` string — **Returned values:** `IBAN`, `US`, `CA`, `GB`, `OTHER` The type of the bank account. - `OwnerName` string — The full name of the owner of the bank account. - `IBAN` string — The IBAN (international bank account number) for the bank account. - `BIC` string — The BIC (international identifier of the bank) for the bank account. - `TransactionDetails` BankWirePayInResponseTransactionDetailsItems[] — Max. length: 50 characters Information received from banking partners for the transaction, based on the cash management (Camt) messages of ISO 20022. This information is only returned when the pay-in `Status` becomes `SUCCEEDED`. If data is not available then an empty array, `null`, or nulled fields are returned. If multiple wire payments are received for a single pay-in, then multiple objects are returned. - `BankTransactionDomainCode` string — Max. length: 50 characters The bank transaction domain code (e.g. PMNT). - `BankTransactionDomainFamilyCode` string — Max. length: 50 characters The bank transaction domain family code (e.g. ICDT). - `BankTransactionDomainSubFamilyCode` string — Max. length: 50 characters The domain sub-family code (e.g. ACDT). - `References` BankWirePayInResponseTransactionDetailsItemsReferencesItems[] — References for the transaction. If multiple references are available, multiple objects are returned. - `Type` string — Max. length: 50 characters The type of the reference. - `Value` string — Max. length: 100 characters The value of the reference. - `DebtorName` string — Max. length: 100 characters The name of the debtor (i.e. the registered owner of the account that was debited). - `DebtorAccount` string — Max. length: 50 characters The account identifier of the debtor (e.g. the account number). - `DebtorAgent` string — Max. length: 50 characters The agent of the debtor (e.g. the BIC or bank code). - `DebtorAddressLine1` string — Max. length: 500 characters The first line of the debtor's address. - `DebtorAddressLine2` string — Max. length: 500 characters The second line of the debtor's address. - `DebtorAddressLine3` string — Max. length: 500 characters The third line of the debtor's address. - `RemittanceInformationLine1` string — Max. length: 1,000 characters Remittance information for the transaction. - `RemittanceInformationLine2` string — Max. length: 1,000 characters Remittance information for the transaction. - `RemittanceInformationLine3` string — Max. length: 1,000 characters Remittance information for the transaction. - `RemittanceInformationLine4` string — Max. length: 1,000 characters Remittance information for the transaction. --- [API](https://skmtc.dev/mangopay/apis/api-reference.md) · [All operations](https://skmtc.dev/mangopay/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mangopay/api-reference/revisions/fafbd0c69654/schema)