The Currencycloud connector polls a Currencycloud account and surfaces sub-accounts, multi-currency balances, beneficiaries, and transactions (including FX conversions). It also initiates transfers between sub-accounts and payouts to registered beneficiaries.
Prerequisites#
You need a Currencycloud account and a loginID + apiKey pair. Currencycloud uses a session token derived from those credentials; the connector manages the session and re-authenticates on expiry.
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/currencycloud \
-H "Content-Type: application/json" \
-d @config.jsonConfiguration fields#
| Field | Type | Required | Default |
|---|---|---|---|
apiKey | string | Yes | |
endpoint | string | Yes | |
loginID | string | Yes | |
pageSize | integer | No | 25 |
pollingPeriod | string | No | 30m |
endpoint is https://devapi.currencycloud.com/v2/ for demo/sandbox, https://api.currencycloud.com/v2/ for production.
Capabilities#
FETCH_ACCOUNTS— sub-accounts viaGET /accounts/find.FETCH_BALANCES— per-account, per-currency balances.FETCH_EXTERNAL_ACCOUNTS— beneficiaries viaGET /beneficiaries/find.FETCH_PAYMENTS— transactions and conversions, classified PAY-IN / PAYOUT / TRANSFER.CREATE_TRANSFER—POST /transfers/createbetween two sub-accounts.CREATE_PAYOUT—POST /payments/createto a registered beneficiary.
CREATE_BANK_ACCOUNT is not implemented; manage beneficiaries through Currencycloud directly. Webhooks are not wired.
Account model#
Every Connectivity internal account is one Currencycloud sub-account (POST /v2/accounts/find). The reference is the account id; name is account_name; defaultAsset is null — sub-accounts are multi-currency, with one balance row per asset via FETCH_BALANCES. EXTERNAL accounts come from /beneficiaries/find. See Accounts for the cross-connector model.
Asset model#
Multi-currency, formatted to UMN at ISO 4217 precision. Amounts arrive as decimal strings; the connector applies major-to-minor scaling.
Status mapping#
Currencycloud status | Payment status |
|---|---|
pending, awaiting_authorization, submitted | PENDING |
completed, released, settled | SUCCEEDED |
failed, deleted (reversed) | FAILED |
cancelled, cancellation_requested | CANCELLED |
CREATE_TRANSFER and CREATE_PAYOUT schedule PollTransferStatus / PollPayoutStatus against /transfers/{id} or /payments/{id} until terminal.
Metadata keys#
Under com.currencycloud.spec/:
- Account:
account_id,account_name,legal_entity_type,your_reference,status. - External account:
beneficiary_id,beneficiary_country,currency,account_number,iban,bic_swift,routing_code_value_1. - Payment:
transaction_id,payment_id,transfer_id,conversion_id(for FX legs),payment_type(regular/priority),reason.
Workflow tree#
FetchAccounts (periodic)
├── FetchBalances (periodic) — per account
└── FetchPayments (periodic) — per account
FetchExternalAccounts (periodic)
CreateTransfer / CreatePayout (event-driven)
└── PollTransferStatus / PollPayoutStatus until terminalPagination and recovery#
1-indexed page + per_page. The connector persists the watermark per stream in platform-managed State; restarts resume from the last committed page boundary.
Known gaps#
- Webhooks are not implemented.
- Beneficiary creation through Connectivity is not wired — beneficiaries must be created upstream before payouts can target them.
- FX conversions surface as
PSPPayments withcom.currencycloud.spec/conversion_id, not as separate Conversion entries (the Conversion resource is exchange-flavoured and gated to 3.3.0+).