Integrating for an FI

If you’re a technology partner, such as a digital banking provider, you can run the Moov Money integration for the FIs you serve. You make the API calls and host the ledger endpoints Moov calls. Each FI stays the merchant of record.

Money doesn’t pass through you. It moves between the FI’s wallet and the FI’s users.

Two connections #

Each FI you serve needs two connections. Both must be in place before you can register senders.

Connection	Between	Set up by	Allows
Program	Moov Money and the FI	The FI, by accepting the Moov Money onboarding link	Moov Money to move money from the FI’s wallet
Delegation	You and the FI	You already have it through your existing relationship with the FI. Moov enables it for Moov Money.	You to call Moov Money on the FI’s behalf

Setup stages #

Moov moves each FI you serve through these stages. What you can call depends on the stage.

Stage	What you can do
Setting up	Set up receiver configuration, create signing secrets, and verify endpoints. Other calls, such as creating participants or minting tokens, return `409`.
Live	Everything listed under what you can call. Moov makes the FI live once it has verified your endpoints.
Offboarding	No new payments. Open payments finish. Moov makes the FI the receiver again, clears the URLs, and revokes your signing secrets for that FI.
Offboarded	Nothing. To bring the FI back, Moov sets it up again.

If an FI moves to another integrator, Moov offboards it from you first, then sets it up with the new integrator. The FI can’t take payments in between.

Who hosts the ledger #

The receiver is the account Moov calls to authorize, capture, release, and credit. The receiver.type field in receiver configuration says which account that is:

`receiver.type`	Who hosts the four URLs	`receiver.accountID`
`fi`	The FI	The FI’s provider account
`integrator`	You	Your account

Once you’re the receiver, only you can change the URLs, credential references, and timeouts. The FI can make itself the receiver again, but can’t change those values in the same request.

You can revoke only signing secrets that were created while you were the receiver. Secrets created before that belong to the FI.

Getting an FI live #

The FI accepts the onboarding link #

Moov sends the FI an onboarding link. The FI signs in with the login that owns its existing Moov account, then selects that account. If someone creates a new account instead, the FI ends up with two. Make sure the link goes to the person who owns that login.

Moov enables your access #

Moov checks the FI’s account and enables your delegation connection for Moov Money. The FI is now setting up.

You set up the ledger #

While the FI is setting up, make these calls with its providerID in the path:

Make yourself the receiver with update receiver configuration. Set receiver to { "type": "integrator", "accountID": "<your account>" } and include your four URLs.
Create a signing secret. Do this after step 1. A secret belongs to whoever is the receiver when it’s created, so a secret created before step 1 would belong to the FI.
If your endpoints require OAuth, set up a credential reference under your own account.
Run verify receiver endpoints until all four checks pass.

Moov activates the FI #

Moov runs its own check of your endpoints. For your first FI, Moov also approves a test payment. Then the FI is live.

What you can call #

You call the same provider endpoints an FI does. Use your own API key, and put the FI’s providerID in the path.

Area	Calls
Setup	Receiver configuration, endpoint verification, signing secrets, provider updates
Participants	Register and look up participants, participant tokens
Funding sources	Create, update, and remove each participant’s funding sources
Limits	Limit policy, groups and members, participant overrides, and effective limits
Payment reviews	Flag a payment and manage the review queue

When your backend mints participant tokens, set clientType to service.

Errors #

Status	Meaning
`403`	You aren’t allowed to act for this FI, or you tried to change routing you don’t own. Check with Moov that your delegation connection is in place.
`409`	The FI is still setting up or is being offboarded, or the change isn’t allowed at this stage.
`409` (`state-conflict`)	This operation isn’t available for this FI right now.
`409` on credential references	Your account is registered as both an FI and an integrator.