> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/api-reference/pay-by-bank/pay-by-bank-payin-object/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.
# The Pay by Bank PayIn object
### Description
The Pay by Bank PayIn object allows platforms to process open banking payments, where the user authenticates directly with their bank to confirm the payment. [Read more](/guides/payment-methods/banking/pay-by-bank) **→**
### Attributes
### Schema (`PayByBankPayInResponse`)
```yaml
components:
schemas:
Id:
type: string
description: >-
Max length: 128 characters (see [data
formats](/api-reference/overview/data-formats) for details)
The unique identifier of the object.
title: Id
Tag:
type: string
description: >-
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}"`.
title: Tag
CreationDate:
type: integer
description: Unix timestamp (UTC) of the date and time the object was created.
title: CreationDate
AuthorId:
type: string
description: The unique identifier of the user at the source of the transaction.
title: AuthorId
Currency:
type: string
description: >-
**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.
title: Currency
Amount:
type: integer
description: >-
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`.
title: Amount
PayByBankPayInResponseDebitedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: Information about the debited funds.
title: PayByBankPayInResponseDebitedFunds
PayByBankPayInResponseCreditedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: >-
Information about the credited funds (`CreditedFunds` = `DebitedFunds` -
`Fees`).
title: PayByBankPayInResponseCreditedFunds
PayByBankPayInResponseFees:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: Information about the fees.
title: PayByBankPayInResponseFees
TransactionStatus:
type: string
description: |-
**Returned values:** `CREATED`, `SUCCEEDED`, `FAILED`
The status of the transaction.
title: TransactionStatus
ResultCode:
type: string
description: >-
The code indicating the result of the operation. This information is
mostly used to handle errors or for
filtering purposes.
title: ResultCode
ResultMessage:
type: string
description: The explanation of the result code.
title: ResultMessage
TransactionExecutionDate:
type: integer
description: >-
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`.
title: TransactionExecutionDate
TransactionType:
type: string
description: |-
**Returned values:** `PAYIN`, `TRANSFER`, `CONVERSION`, `PAYOUT`
The type of the transaction.
title: TransactionType
TransactionNature:
type: string
description: >-
**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.
title: TransactionNature
CreditedUserId:
type: string
description: >-
**Default value:** The unique identifier of the owner of the credited
wallet.
The unique identifier of the user whose wallet is credited.
title: CreditedUserId
FlowDescriptorResponseBeneficiariesItems:
type: object
properties:
UserId:
type: string
description: >-
The unique identifier of the Natural User or Legal User declared as
a beneficiary of the pay-in.
title: FlowDescriptorResponseBeneficiariesItems
FlowDescriptorResponse:
type: object
properties:
FlowId:
type: string
description: >-
Unique identifier of the payment flow, used by Mangopay for internal
purposes.
Beneficiaries:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/FlowDescriptorResponseBeneficiariesItems'
description: >-
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.
description: >
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`.
title: FlowDescriptorResponse
ReturnURL_255:
type: string
description: >-
Max. length: 255 characters
The URL to which the user is returned after the payment, whether the
transaction is successful or not.
title: ReturnURL_255
StatementDescriptor:
type: string
description: >-
Max. length: 10 characters; only alphanumeric and spaces
Custom description to appear on the user’s bank statement along with the
platform name. Different banks may show more or less information. See
the Customizing bank statement references
article for details.
title: StatementDescriptor
PayByBankPayInResponse:
type: object
properties:
Id:
$ref: '#/components/schemas/Id'
Tag:
$ref: '#/components/schemas/Tag'
CreationDate:
$ref: '#/components/schemas/CreationDate'
AuthorId:
$ref: '#/components/schemas/AuthorId'
DebitedFunds:
$ref: '#/components/schemas/PayByBankPayInResponseDebitedFunds'
description: Information about the debited funds.
CreditedFunds:
$ref: '#/components/schemas/PayByBankPayInResponseCreditedFunds'
description: >-
Information about the credited funds (`CreditedFunds` =
`DebitedFunds` - `Fees`).
Fees:
$ref: '#/components/schemas/PayByBankPayInResponseFees'
description: Information about the fees.
Status:
$ref: '#/components/schemas/TransactionStatus'
ResultCode:
$ref: '#/components/schemas/ResultCode'
ResultMessage:
$ref: '#/components/schemas/ResultMessage'
ExecutionDate:
$ref: '#/components/schemas/TransactionExecutionDate'
Type:
$ref: '#/components/schemas/TransactionType'
Nature:
$ref: '#/components/schemas/TransactionNature'
CreditedWalletId:
type: string
description: The unique identifier of the credited wallet.
CreditedUserId:
$ref: '#/components/schemas/CreditedUserId'
FlowDescriptor:
$ref: '#/components/schemas/FlowDescriptorResponse'
PaymentType:
type: string
description: |-
**Returned values:** `PAY_BY_BANK`
The payment type of the pay-in.
ExecutionType:
type: string
description: |-
**Returned values:** `WEB`
The execution type of the pay-in.
ReturnURL:
$ref: '#/components/schemas/ReturnURL_255'
RedirectURL:
type: string
description: >-
The URL to which to redirect the user to complete the payment.
**Caution:** This variable URL is specific to each payment. You must
rely on the returned URL in full (host, path, and queries) and not
hardcode any part of it.
StatementDescriptor:
$ref: '#/components/schemas/StatementDescriptor'
Country:
type: string
description: >-
**Allowed values:** `AT`, `DE`, `DK`, `EE`, `ES`, `FI`, `FR`, `GB`,
`IE`, `IT`, `LV`, `LT`, `NL`, `NO`, `PL`, `PT`.
The country of residence of the user.
BIC:
type: string
description: >-
The BIC of the user's bank account, which is only returned if it was
sent.
If both the `IBAN` and `BIC` are provided, one of the two
authentication steps required by certain banks may be avoided.
IBAN:
type: string
description: >-
The IBAN of the user's bank account, which is only returned if it
was sent.
If both the `IBAN` and `BIC` are provided, one of the two
authentication steps required by certain banks may be avoided.
PaymentFlow:
type: string
description: >-
**Allowed values:** `WEB`, `APP`
**Default value:** `WEB`
The platform environment of the post-payment flow. The `PaymentFlow`
value combines with the `ReturnURL` to manage the redirection
behavior after payment:
- Set the value to `APP` to send the user to your platform's mobile
app
- Set the value to `WEB` to send the user to a web browser
In both cases you need to provide the relevant `ReturnURL`, whether
to your app or website.
BankName:
type: string
description: >-
**Allowed values:** One of the [supported bank
names](/guides/payment-methods/banking/pay-by-bank#banks-and-schemes).
The name of the bank, which is only returned if it was sent.
If the `BankName` is provided, the user doesn't have to select their
bank when they are redirected.
Culture:
type: string
description: >-
**Allowed values:** `DA`, `CS`, `DE`, `EN`, `ET`, `ES`, `FI`, `FR`,
`IT`, `LT`, `LV`, `NL`, `NO`, `PL`, `PT`, `SV`
**Default value:** `EN`
The language in which the Tink open banking page is to be displayed.
Scheme:
type: string
description: >-
**Allowed values:** One of the [supported
schemes](/guides/payment-methods/banking/pay-by-bank#banks-and-schemes)
for the `Country`.
**Default value:** The [listed instant
scheme](/guides/payment-methods/banking/pay-by-bank#banks-and-schemes)
for the `Country`. If `Country` is `DK`, there is no default and the
`Scheme` must be specified.
The scheme to use to process the payment. Note that some banks may
charge additional fees to the user for instant payment schemes.
ProcessingStatus:
type: string
description: >-
**Possible values:** `PENDING_SUCCEEDED`
Parameter that is only returned once the bank wire has been
successfully authenticated and initiated by the user but has not yet
been received by Mangopay. When the funds are received, the `Status`
changes from `CREATED` to `SUCCEEDED` and the `ProcessingStatus` is
no longer returned.
For non-instant schemes, processing can take up to 72 hours but is
typically completed within 2 days.
title: PayByBankPayInResponse
```