Getting Started

This guide covers Magnolia API v2 (payments-core): how to open customer accounts, verify identity, fund them, convert between USD and Bitcoin, and withdraw.

The flow below is the usual path from a new customer to a funded, tradable account.

---

Core Concepts

Organization

Your organization is the top-level entity that represents you (the partner) on the platform. All customers and accounts live under your organization.

• Provisioned by the MagFi team during initial setup
• Scoped automatically from your API credentials. You do not pass an organization ID on day-to-day payments-core calls

User

A user is the end customer under your organization. Create the user first, then attach one or more accounts to them.

• Create with POST /user: optional externalId (your own customer key; unique per org; write-once; generated if omitted) and optional name
• Store the returned userId: pass it on POST /account
• List / get / update (name only) / delete via /user routes; delete is refused with 422 USER_HAS_ACCOUNTS while the user still owns accounts

Account

An account is a funded wallet / operational surface for a user. For payments-core flows in this guide series, create accounts with provider: "BITGO" and include userId.

• One user can have one or more accounts; each account returns an accountId
• Store accountId: it is the primary key for identity, agreements, balances, funding, trade, and withdrawals
• Account status starts as pending and moves to open after identity and required agreements are complete

Use provider: "BITGO" for payments-core

API v2 also supports other providers. This guide series covers the payments-core lifecycle with provider: "BITGO", validated on DEV.

Identity

The identity holds KYC/KYB data for the account.

• Submit via POST /identity after the account exists
• KYC can leave the account pending until the identity is approved
• Poll GET /account/{id} and watch status / statusReason while verification runs

Agreements

Legal agreements are seeded when the account is created. Typical payments-core set for provider: "BITGO":

Type	Role
MAGFI_AGREEMENT_TERMS_OF_SERVICE	Magnolia TOS
BITGO_AGREEMENT_CSA	Custody Service Agreement
BITGO_AGREEMENT_MPA	Master Purchase Agreement (when present)

• List with GET /agreement, then PUT /agreement/{id}/agree for each required row
• Agreements must reach status confirmed before the account can open
• Custody agreements become confirmed only after the provider accepts the signature

Balances

Balances are account-scoped totals, not Go Account trading wallets from API v1.

• Fiat: GET /account-fiat-total?accountId={accountId}
• Assets (e.g. BTC): GET /account-asset-total?accountId={accountId}

ACH settlement is asynchronous. Settled fiat can remain 0 until the deposit clears.

---

Integration Overview

The standard integration follows these steps. Each step is covered in detail in its own guide.

Some onboarding steps are conditional

Document upload is not part of every onboarding flow. Many US customers move from account creation to identity submission, agreements, and open without uploading documents. Documents are usually only needed for non-US citizens or when verification data does not match.

Step	What	Guide
1–5	Create user, create account (provider: "BITGO" + userId), submit identity, confirm agreements, wait for open	User Onboarding
6	Link ACH bank method, deposit fiat (or crypto)	Funding
7	Place trade orders	Conversions
8	Disburse fiat or assets out	Withdrawals

---

Key ID Reference

Concept	ID Field	Source
End customer	userId	POST /user (also returned on account reads)
Customer account	accountId	POST /account
KYC record	identityId	POST /identity
Agreement	agreementId	GET /agreement
Bank rail	fiatTransferMethodId	POST /fiat-transfer-method
Fiat currency	fiatId	GET /fiat
Asset	assetId	GET /asset
Trade order	orderId	POST /trade/order

---

Next Steps

• User Onboarding: Create user, account, identity, agreements, open
• Funding: ACH deposit or crypto contribution
• Conversions: Buy or sell Bitcoin
• Withdrawals: Send funds out