_Docs/
Get StartedModulesPlatformDeployCookbookChangelogReference
_Stack
_Modules
  • Ledger
  • Numscript
  • Connectivity
    • Capabilities
    • Operations
    • Accounts
    • Payments
    • Orders
    • Conversions
    • Payment Initiation
    • Account Pools
    • Payment Service Users
    • Connectors
      • Generic Connector
        • Getting Started
        • How it Works
      • PSP Connectors
        • Adyen
        • Atlar
        • Banking Circle
        • Column
        • Currencycloud
        • Increase
        • Mangopay
        • Modulr
        • Moneycorp
        • Qonto
        • Stripe
        • Wise
        • Banking BridgeEE
        • RoutableEE
      • Exchange Connectors
        • Coinbase PrimeEE
        • FireblocksEE
        • BitstampEE
      • Open Banking
        • Getting Started with Open Banking
        • Plaid
        • Tink
        • Powens
      • Build a connector
  • WalletsEE
  • FlowsEE
  • ReconciliationEE
  1. Modules
  3. Connectivity
  5. Connectors
  7. PSP Connectors
  9. Mangopay
Mangopay
PSP Connectors

Mangopay

Connect a Mangopay account to Formance Connectivity to sync e-wallets, balances, payouts, transfers, and beneficiaries, with full outbound initiation and webhook ingest.

The Mangopay connector polls a Mangopay client and surfaces multi-currency e-wallets, balances, bank accounts (external), and transactional events. It also initiates transfers and payouts, registers bank accounts, and ingests webhooks.

Prerequisites#

You need a Mangopay client and an API key pair. Mangopay uses HTTP Basic Auth (clientID:apiKey); the connector sets the header on every request.

Make sure to create an API key dedicated to Formance. Doing so will improve your auditability and security and will allow you to revoke access to Formance at any time if needed.

Installation#

curl -X POST $FORMANCE_API_URL/api/payments/v3/connectors/install/mangopay \
  -H "Content-Type: application/json" \
  -d @config.json
POST/api/payments/v3/connectors/install/mangopay

Configuration fields#

FieldTypeRequiredDefault
apiKeystringYes
clientIDstringYes
endpointstringYes
pageSizeintegerNo25
pollingPeriodstringNo30m

endpoint is https://api.mangopay.com for production, https://api.sandbox.mangopay.com for sandbox.

Capabilities#

  • FETCH_ACCOUNTS — e-wallets, grouped by UserId.
  • FETCH_BALANCES — per-wallet balance via Mangopay's Balance resource.
  • FETCH_EXTERNAL_ACCOUNTS — bank accounts attached to each user.
  • FETCH_PAYMENTS — payins, transfers, payouts, refunds, and disputes, unified into PSPPayment.
  • FETCH_OTHERS — KYC documents and mandates, surfaced under mangopay-* on v3ListPaymentsOther.
  • CREATE_BANK_ACCOUNT — IBAN / US / GB / CA / OTHER variants.
  • CREATE_TRANSFER — wallet-to-wallet via POST /transfers.
  • CREATE_PAYOUT — wallet-to-bank-account via POST /payouts/bankwire.
  • CREATE_WEBHOOKS + TRANSLATE_WEBHOOKS — one hook per consumed EventType.

Account model#

Every Connectivity internal account is one Mangopay e-wallet (single-currency, scoped to a UserId). The reference is the wallet ID; defaultAsset is the wallet's currency at ISO 4217 precision. Accounts are emitted per user (one fetch cycle per user from the workflow's parent payload). EXTERNAL accounts come from /users/{UserId}/bankaccounts; v3CreateBankAccount registers new ones (IBAN / US / GB / CA / OTHER). See Accounts for the cross-connector model.

Asset model#

Multi-currency (EUR / USD / GBP, …), formatted to UMN at ISO 4217 precision. Amounts are already in minor units — no scaling.

Status mapping#

Mangopay Status (Transactions)Payment status
CREATED, IN_PROGRESSPENDING
SUCCEEDEDSUCCEEDED
FAILEDFAILED
CANCELLEDCANCELLED

CREATE_* initiations schedule PollTransferStatus / PollPayoutStatus against the relevant endpoint until terminal.

Metadata keys#

Under com.mangopay.spec/:

  • Account: wallet_id, description, owners (comma-joined UserId list), currency.
  • External account: bank_account_id, type (IBAN / US / GB / CA / OTHER), iban, bic, owner_name, owner_address.
  • Payment: transaction_id, transaction_type (PAYIN / PAYOUT / TRANSFER / REFUND), nature (REGULAR / REPUDIATION / REFUND / SETTLEMENT), result_code, result_message.

Bank-account creation uses com.mangopay.spec/bank_account_type on the v3CreateBankAccount body to select the variant (default IBAN).

Workflow tree#

FetchAccounts (periodic) — paginated over UserList → WalletList
  ├── FetchBalances (FromPayload — no extra API call)
  └── FetchPayments (periodic) — per wallet
FetchExternalAccounts (periodic) — per user
FetchOthers (periodic) — KYC docs, mandates
CreateBankAccount / CreateTransfer / CreatePayout (event-driven)
  └── PollTransferStatus / PollPayoutStatus until terminal
CreateWebhooks (one-shot at install) — one hook per EventType

Pagination and recovery#

1-indexed Page + Per_Page (max 100). The connector persists the watermark per stream in platform-managed State. Webhook deliveries dedupe by (EventType, ResourceId) against PSPPayment.Reference.

Known gaps#

  • Pre-authorisations: not surfaced; only successful captures land as PSPPayments.
  • Disputes: arrive via webhooks as PSPPayment rows tagged transaction_type=DISPUTE; the full lifecycle lives in Mangopay's dashboard.
  • KYC: documents surface via FETCH_OTHERS only — submission happens in Mangopay's UI.
IncreaseModulr
On This Page
  • Prerequisites
  • Installation
  • Configuration fields
  • Capabilities
  • Account model
  • Asset model
  • Status mapping
  • Metadata keys
  • Workflow tree
  • Pagination and recovery
  • Known gaps