Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Reference Pay By Bank API
version: 1.0.0
servers:
- url: https://api.sandbox.mangopay.com
description: Sandbox
- url: https://api.mangopay.com
description: Production
- url: https://api-mtls.sandbox.mangopay.com
description: mTLS Sandbox
- url: https://api-mtls.mangopay.com
description: mTLS Production
- url: '%7BCardRegistrationUrl%7D'
description: "The full dynamic URL returned by the Create a Card Registration call, including host, path, and query parameters. \n"
- url: '%7BSettlementFileUploadUrl%7D'
description: 'The unique URL returned by the [POST Create a Settlement and secure URL](/api-reference/settlements/create-settlement) endpoint.
**Note:** Use the full dynamic URL including the host, path, and all query parameters. The URL is already authenticated, so this call does not require an Authorization header.
'
tags:
- name: payByBank
paths:
/v2.01/{ClientId}/payment-methods/openbanking/metadata/supported-banks:
get:
operationId: payByBank_view_supported_banks_pay_by_bank
summary: View supported banks for Pay by Bank
description: 'Retrieve supported banks to present to a user for Pay by Bank pay-ins
This endpoint allows you to retrieve a paginated list of banks that you can present to the user for selection during their Pay by Bank checkout experience. Once they have selected their bank, and optionally the scheme, submit the data of their selection to the POST Create a Pay by Bank PayIn endpoint. Read the guide **→**'
tags:
- payByBank
parameters:
- name: ClientId
in: path
description: Platform's API account identifier, associated with the API key.
required: true
schema:
type: string
- name: CountryCodes
in: query
description: '**Allowed values:** `AT`, `DE`, `DK`, `EE`, `ES`, `FI`, `FR`, `GB`, `IE`, `IT`, `LV`, `LT`, `NL`, `NO`, `PL`, `PT`
The countries for which to return supported banks. You can combine query values in a comma-separated list.'
required: false
schema:
type: string
- name: per_page
in: query
description: 'Min. value: `1`; max. value: `100`
**Default value:** `10`
The number of `Banks` objects returned for each page of the pagination.
On this endpoint, the pagination refers to the number of `Banks` objects, regardless of whether they span multiple `Countries` objects.'
required: false
schema:
type: integer
- name: page
in: query
description: 'Start value: `1`
**Default value:** `1`
Indicates the index of the page for the pagination.'
required: false
schema:
type: integer
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ViewSupportedBanksForPayByBankResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- oauth2: []
/v2.01/{ClientId}/payins/payment-methods/openbanking:
post:
operationId: payByBank_create_pay_by_bank_payin
summary: Create a Pay by Bank PayIn
description: 'Initiate a Pay by Bank pay-in request.
**Note – Session timeout 9 minutes**
The Pay by Bank session lasts for 9 minutes, at which point the pay-in fails automatically if no action has been taken by the user.
Related: test data, guide'
tags:
- payByBank
parameters:
- name: ClientId
in: path
description: Platform's API account identifier, associated with the API key.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/PayByBankPayInResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAPayByBankPayInRequest'
security:
- oauth2: []
components:
schemas:
CreateAPayByBankPayInRequest:
type: object
properties:
Tag:
$ref: '#/components/schemas/Tag'
AuthorId:
$ref: '#/components/schemas/AuthorId'
DebitedFunds:
$ref: '#/components/schemas/CreateAPayByBankPayInRequestDebitedFunds'
description: Information about the debited funds.
Fees:
$ref: '#/components/schemas/CreateAPayByBankPayInRequestFees'
description: Information about the fees.
CreditedWalletId:
type: string
description: The unique identifier of the credited wallet.
FlowDescriptor:
$ref: '#/components/schemas/FlowDescriptorRequest'
ReturnURL:
$ref: '#/components/schemas/ReturnURL_255'
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.'
required:
- AuthorId
- DebitedFunds
- Fees
- CreditedWalletId
- ReturnURL
- Country
title: CreateAPayByBankPayInRequest
ViewSupportedBanksForPayByBankResponse:
type: object
properties:
SupportedBanks:
$ref: '#/components/schemas/ViewSupportedBanksForPayByBankResponseSupportedBanks'
description: The supported banks listed by country.
title: ViewSupportedBanksForPayByBankResponse
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 <a href="/bank-statements">Customizing bank statement references</a> article for details.'
title: StatementDescriptor
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
FlowDescriptorRequestBeneficiariesItems:
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: FlowDescriptorRequestBeneficiariesItems
CreateAPayByBankPayInRequestDebitedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
required:
- Currency
- Amount
description: Information about the debited funds.
title: CreateAPayByBankPayInRequestDebitedFunds
ViewSupportedBanksForPayByBankResponseSupportedBanksCountriesItems:
type: object
properties:
Banks:
type: array
items:
$ref: '#/components/schemas/ViewSupportedBanksForPayByBankResponseSupportedBanksCountriesItemsBanksItems'
description: List of paginated banks for the country. Display the list of banks for the user to choose before submitting their selection in the [POST Create a Pay by Bank PayIn](/api-reference/pay-by-bank/create-pay-by-bank-payin) request.
Country:
type: string
description: The `Country` value for the paginated list of `Banks` objects.
title: ViewSupportedBanksForPayByBankResponseSupportedBanksCountriesItems
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
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
AuthorId:
type: string
description: The unique identifier of the user at the source of the transaction.
title: AuthorId
FlowDescriptorRequest:
type: object
properties:
Beneficiaries:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/FlowDescriptorRequestBeneficiariesItems'
description: '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.'
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)).\n\nIf the `FlowDescriptor.Beneficiaries` is sent in the API request, then:\n- The transaction's `CreditedWalletId` holder is disregarded in KYC/KYB checks.\n- **ALL** `UserId` values in the array must be one of:\n - `OWNER` whose `KYCLevel` is `REGULAR`\n - `PLATFORM`\n \nThe pay-in `Status` becomes `FAILED` with `ResultCode` [002951](/errors/codes/002951) if at least one `FlowDescriptor.Beneficiaries.UserId` is:\n- `PAYER`\n- `OWNER` whose `KYCLevel` is `LIGHT`\n\nIf 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`. \n"
title: FlowDescriptorRequest
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
PayByBankPayInResponseDebitedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: Information about the debited funds.
title: PayByBankPayInResponseDebitedFunds
TransactionStatus:
type: string
description: '**Returned values:** `CREATED`, `SUCCEEDED`, `FAILED`
The status of the transaction.'
title: TransactionStatus
ViewSupportedBanksForPayByBankResponseSupportedBanks:
type: object
properties:
Countries:
type: array
items:
$ref: '#/components/schemas/ViewSupportedBanksForPayByBankResponseSupportedBanksCountriesItems'
description: Array of objects listing the paginated `Banks` per `Country`.
description: The supported banks listed by country.
title: ViewSupportedBanksForPayByBankResponseSupportedBanks
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
ResultMessage:
type: string
description: The explanation of the result code.
title: ResultMessage
Currency:
type: string
description: '**Allowed values:** The three-letter <a href="/api-reference/overview/data-formats" target="_blank">ISO 4217 code</a> (EUR, GBP, etc.) of a <a href="/guides/currencies" target="_blank">supported currency</a> (depends on feature, contract, and activation settings).
The currency of the amount.'
title: Currency
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)).\n\nIf the `FlowDescriptor.Beneficiaries` is sent in the API request, then:\n- The transaction's `CreditedWalletId` holder is disregarded in KYC/KYB checks.\n- **ALL** `UserId` values in the array must be one of:\n - `OWNER` whose `KYCLevel` is `REGULAR`\n - `PLATFORM`\n \nThe pay-in `Status` becomes `FAILED` with `ResultCode` [002951](/errors/codes/002951) if at least one `FlowDescriptor.Beneficiaries.UserId` is:\n- `PAYER`\n- `OWNER` whose `KYCLevel` is `LIGHT`\n\nIf 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`.\n"
title: FlowDescriptorResponse
CreateAPayByBankPayInRequestFees:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
required:
- Currency
- Amount
description: Information about the fees.
title: CreateAPayByBankPayInRequestFees
ViewSupportedBanksForPayByBankResponseSupportedBanksCountriesItemsBanksItems:
type: object
properties:
BankName:
type: string
description: The bank's `BankName` to identify it in the pay-in request.
Scheme:
type: array
items:
type: string
description: List of `Scheme` values supported by the bank, which can be presented to the user for selection before submission in the pay-in request.
Name:
type: string
description: The bank's display name to show to the user for selection.
title: ViewSupportedBanksForPayByBankResponseSupportedBanksCountriesItemsBanksItems
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
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
Error:
type: object
properties:
Message:
type: string
description: Description of the error.
Type:
type: string
description: 'The category of the error.
'
Id:
type: string
description: Unique identifier of the error instance, useful when contacting Mangopay for support.
Date:
type: number
format: double
description: Unix timestamp (UTC) of the date and time the error was triggered.
errors:
type:
- object
- 'null'
additionalProperties:
type: string
description: 'Object containing one or more field-level errors.
'
description: 'The error body typically returned by the Mangopay API for any non-2xx HTTP status code.
'
title: Error
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
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
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.'
description: 'A Pay by Bank pay-in:
- `PaymentType` – `PAY_BY_BANK`
- `ExecutionType` – `WEB`'
title: PayByBankPayInResponse
PayByBankPayInResponseFees:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: Information about the fees.
title: PayByBankPayInResponseFees
ResultCode:
type: string
description: The code indicating the result of the operation. This information is mostly used to <a href="/errors/codes">handle errors</a> or for filtering purposes.
title: ResultCode
TransactionType:
type: string
description: '**Returned values:** `PAYIN`, `TRANSFER`, `CONVERSION`, `PAYOUT`
The type of the transaction.'
title: TransactionType
securitySchemes:
oauth2:
type: http
scheme: bearer
description: "Bearer authentication of the form `Bearer <token>`, where token is your auth token. \n\nIf your platform is using a [proxy](/guides/sca/proxy-management) to take SCA-triggering action on behalf of users, you also need to integrate [mTLS authentication](/guides/sca/platform) and use the `api-mtls` base URL."
x-provenance:
method: harvested
publisher: Mangopay
source: https://docs.mangopay.com/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)