Skip to main content

Funding

Before funding, the customer needs an open account. For fiat funding, link an ACH incoming transfer method, then create a fiat contribution. Crypto deposits use asset contribution / awaiting-deposit.

Resolve currency IDs first:

  • GET /fiat: pick the USD fiatId
  • GET /asset: pick the Bitcoin assetId when depositing crypto

Connect the customer's bank for ACH deposits.

  • POST /fiat-transfer-method
  • transferDirection: "INCOMING"
  • fundsTransferType: "ACH"

Example payload:

{
  "accountId": "<accountId>",
  "fiatId": "<fiatId>",
  "transferDirection": "INCOMING",
  "fundsTransferType": "ACH",
  "label": "Customer ACH in",
  "bankName": "Test Bank",
  "bankAccountName": "Jane Doe",
  "bankAccountNumber": "1234567890",
  "bankAccountType": "CHECKING",
  "routingNumber": "021000021",
  "last4": "7890",
  "bankAddress1": "1 Federal Reserve Plaza",
  "bankCity": "New York",
  "bankState": "NY",
  "bankPostalCode": "10045",
  "bankCountryCode": "US",
  "async": false
}

Store the returned fiatTransferMethodId.

Bank verification can lag

Creating the method does not always make it immediately usable for every rail. Outbound ACH especially may return FIAT_TRANSFER_METHOD_NOT_READY until verificationState is approved. See Withdrawals.

Fiat Funding (ACH Contribution)​

Pull USD from the linked incoming method into the account.

  • POST /fiat-contribution
  • unitCount: amount in USD cents as a string (e.g. "10000" = $100.00)
  • acceptAchAuthorizationTerms: true: required for ACH deposits
  • currencyType: "USD"

Example payload:

{
  "accountId": "<accountId>",
  "fiatTransferMethodId": "<incomingFiatTransferMethodId>",
  "fiatId": "<fiatId>",
  "unitCount": "10000",
  "currencyType": "USD",
  "acceptAchAuthorizationTerms": true
}
ACH settlement is asynchronous

After a successful contribution create, settled balance on account-fiat-total may stay 0 until the ACH clears. Poll balances rather than treating the create response as immediately available cash.

Check Fiat Balances​

  • GET /account-fiat-total?accountId={accountId}

Use this to confirm deposits after settlement. For crypto balances, use GET /account-asset-total?accountId={accountId}.

Crypto Funding (Optional)​

To receive crypto into a payments-core account:

  • POST /asset-contribution: record / initiate an asset contribution when you already have the transfer-method context
  • POST /asset-contribution/awaiting-deposit: declare that you are waiting on an inbound deposit (deposit-address / pending inbound flow)

Exact body fields depend on your asset transfer method setup. Reach out if you need the deposit-address path enabled for your org.

Next Steps​