Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.joinbankroll.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Quickstart

This guide takes you from zero to a working Bankroll Connect integration. Have your code editor and a terminal open.

​
Step 1 — Configure your partner account

Sign in to the Partner Portal and open Settings.
  1. Copy your Public key and Secret key.
  2. Configure the Webhook URL where Bankroll should deliver deposit.completed events.
Your secret key signs every Connect token. Store it as an environment variable on your backend. Never embed it in mobile or web client code — anyone who extracts it can mint tokens for any user on your platform.

​
Step 2 — Mint a Connect token

On your backend, sign a JWT with your secret key. The token uses HS256 and includes four claims:
ClaimValue
issYour partner public key
subYour stable identifier for the user (echoed back as userId in webhooks)
audbankroll-connect
expExpiration timestamp (recommend 30 minutes)
require 'jwt'

PARTNER_PUBLIC_KEY = ENV.fetch('BANKROLL_PUBLIC_KEY')
PARTNER_SECRET_KEY = ENV.fetch('BANKROLL_SECRET_KEY')

def mint_connect_token(user_id)
  payload = {
    iss: PARTNER_PUBLIC_KEY,
    sub: user_id,
    aud: 'bankroll-connect',
    exp: (Time.now + 30 * 60).to_i
  }
  JWT.encode(payload, PARTNER_SECRET_KEY, 'HS256')
end

​
Step 3 — Open the Connect URL in your app

Your app calls your backend to get a token, then opens the Connect URL in an in-app browser. Pass the deposit amount in cents as a query parameter. 
import SafariServices

func openBankrollConnect(token: String, amountCents: Int, from vc: UIViewController) {
    var components = URLComponents(string: "https://api.joinbankroll.com/connect/start")!
    components.queryItems = [
        URLQueryItem(name: "token", value: token),
        URLQueryItem(name: "amountCents", value: String(amountCents))
    ]
    let safariVC = SFSafariViewController(url: components.url!)
    vc.present(safariVC, animated: true)
}
That’s it for the client side. Your user now sees the Connect flow.

​
Step 4 — Receive the deposit webhook

When the user finishes funding, Bankroll sends a deposit.completed webhook to your configured webhook URL. 
{
  "type": "deposit.completed",
  "id": "<uuid>",
  "source": "cashapp",
  "userId": "your-stable-user-id",
  "amountCents": 2500
}
FieldDescription
typeEvent type. Always deposit.completed for funded deposits.
idUnique deposit identifier (UUID). Use it for idempotency on your side.
sourceThe funding method the user picked (e.g. cashapp).
userIdThe same value you put in the JWT’s sub claim. Use it to credit the right user on your platform.
amountCentsThe funded amount in U.S. cents.
Treat the webhook as authoritative. There is no client-side success callback when Connect closes — your in-app browser will dismiss whether the user completed payment, backed out, or hit an error. Always reconcile against the deposit.completed webhook before crediting the user’s account.

​
Step 5 — Test it

Run the flow end-to-end with a test user. You should see:
  1. The Connect intro screen with your partner name and logo.
  2. The phone-number entry screen.
  3. The OTP entry screen.
  4. The account-selection screen with Cash App as an option.
  5. A success screen confirming the user can close the window.
  6. A deposit.completed webhook delivered to your endpoint.

​
Error handling

If something goes wrong before Connect can render — bad token, missing amount — the user lands on https://api.joinbankroll.com/connect/error?reason=<reason> and sees a generic “Something went wrong” page asking them to return to your app and try again.
reasonCause
missing_tokenThe token query parameter wasn’t present.
invalid_tokenToken was malformed, signed with the wrong secret, expired before reaching us, or referenced a partner that doesn’t exist.
invalid_amountamountCents was missing, zero, negative, or not an integer.
You will not receive a callback when these errors fire — monitor your token-mint endpoint’s logs to detect failures.