The Unified Bank Wire PayIn object
Description
Note – Sandbox only
This unified object is currently only returned in the Sandbox environment. In Production, the same PaymentType/ExecutionType combinations still return the existing Bank Wire PayIn object or External Instruction Bank Wire PayIn object.
The new object, which is fully backwards compatible with both legacy objects, will be rolled out to Production at a later date.
The Unified Bank Wire PayIn object harmonizes the shape of the data returned for two bank wire pay-in variants (with PaymentType of BANK_WIRE):
- A pre-declared pay-in to a pooled Mangopay account (
ExecutionTypeofDIRECT) - A pay-in to a Virtual Account (
ExecutionTypeofEXTERNAL_INSTRUCTION)
These payment and execution types remain the same in each case, but the shape of the object is now harmonized.
The new object is backwards compatible with both legacy objects to facilitate adoption once it is deployed in Production.
It introduces a new structured CreditedAccount object, a simplified DebitedAccount (replacing the legacy DebitedBankAccount), and ReconciliationDetails with the received funds and wire reference. The Virtual Account variant now includes the wire transfer’s TransactionDetails, which was previously only returned on a pre-declared pay-in. The object also introduces VirtualAccountId as a replacement for BankingAliasId, with the same value returned in both.
Attributes
The Unified Bank Wire PayIn object can be retrieved from the GET View a PayIn endpoint.
Max length: 128 characters (see data formats for details)
The unique identifier of the object.
Max. length: 255 characters
Custom data that you can add to this object, such as unique identifiers in your system. To store multiple values, you can serialize them into a single string, for example a JSON object: "{\"id_1\":AB123,\"id_2\":DE456}".
Returned values: CREATED, SUCCEEDED, FAILED
The status of the transaction.
Returned values: PAYIN, TRANSFER, CONVERSION, PAYOUT
The type of the transaction.
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.
Returned values: BANK_WIRE
The payment type of the pay-in.
Returned values: DIRECT, EXTERNAL_INSTRUCTION
The execution type of the pay-in.
Unix timestamp (UTC) of the date and time the object was created.
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.
The code indicating the result of the operation. This information is mostly used to handle errors or for filtering purposes.
Default value: The unique identifier of the owner of the credited wallet.
The unique identifier of the user whose wallet is credited.
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.
The unique identifier of the Virtual Account (or legacy banking alias) targeted by this pay-in. Returned null for a pre-declared (DIRECT) bank wire to a Mangopay account.
Note: The same value is returned in both VirtualAccountId and BankingAliasId, but use VirtualAccountId going forward.
Information about the declared debited funds.
Returned null for a pay-in to a Virtual Account.
Information about the declared fees.
Returned null for a pay-in to a Virtual Account (Fees cannot be taken on this type of pay-in).
Information about the debited funds.
For a pre-declared (DIRECT) bank wire to a Mangopay account, the DebitedFunds displays placeholder values (currency XXX and amount 0) while the Status is CREATED, i.e. until the bank wire is received.
Information about the credited funds (CreditedFunds = DebitedFunds - Fees).
For a pre-declared (DIRECT) bank wire to a Mangopay account, the CreditedFunds displays placeholder values (currency XXX and amount 0) while the Status is CREATED, i.e. until the bank wire is received.
Information about the fees taken by the platform for this transaction (and hence transferred to the Fees Wallet).
Max. length: 255 characters
For a pre-declared (DIRECT) bank wire to a Mangopay account: 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 pay-in object.
Caution: For pre-declared bank wires, this reference is specific to each payment and must be retrieved dynamically.
For a bank wire to a Virtual Account (EXTERNAL_INSTRUCTION): The reference of the bank wire received on the virtual IBAN, as provided by the user. If no reference was provided, then this value is null.
Information about the bank account to which the bank wire must be made by the end user, for a pre-declared (DIRECT) bank wire to a Mangopay account. Returned null for a bank wire to a Virtual Account, which has CreditedAccount populated funds arrive instead.
Caution: Do not hardcode the returned values. Mangopay may change the underlying bank details without prior notice.
Information about the account credited by the bank wire.
Returned null for a pay-in to a Virtual Account, for which the Virtual Account is the source of truth for its own account details instead.
Information about the account debited to fund the pay-in.
For a pre-declared (DIRECT) bank wire to a Mangopay account, this property is returned null while the Status is CREATED, i.e. until the bank wire is received.
Information about an action pending on the pay-in, if any.
For example, when CREATED, a pre-declared bank wire shows PAYMENT_REQUIRED as the action.
Details of the reconciliation between the declared and received funds for the bank wire.
For a pre-declared (DIRECT) bank wire pay-in, returned null while the Status is CREATED, i.e. until the bank wire is received.
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.
Returned null for now.
Returned null for now. It is not yet possible to declare Owner beneficiaries on a bank wire pay-in, but it will be in future.
Replaced by VirtualAccountId. Retained in the response for backwards compatibility only — new integrations should use VirtualAccountId instead.
The unique identifier of the banking alias. Returned null for a pre-declared (DIRECT) bank wire to a Mangopay account.
Replaced by DebitedAccount.
Information about the debited bank account. For a pre-declared (DIRECT) bank wire to a Mangopay account, this property is returned null while the Status is CREATED, i.e. until the bank wire is received.