Payment rails: Aeropay & Aerosync

The rail model

Round-ups accrue in SideBet regardless of rail. The rail only decides two things: how a user’s bank gets linked, and which processor pulls the batched transfer when their threshold is reached. Every merchant runs in one of two modes.

Aeropay

Aeropay is a pay-by-bank network. A user is identified by mobile number, holds an Aeropay account that spans every merchant on the network, and links one or more bank accounts to it. Merchants debit those accounts through Aeropay’s API. SideBet uses it for the single batched round-up transfer, never per purchase.

Set up the rail

What changes for the user

Aeropay needs a legal name and mobile number to create the user, and it sends a one-time code that must be confirmed before any bank can be linked. The Link SDK handles both. Pass name and phone in the link token and the details screen is skipped, but the code step always applies to a new Aeropay user.

Aerosync

Aerosync is Aeropay’s bank-linking widget, the equivalent of Plaid Link or Stripe Financial Connections. The user searches for their institution, signs in with their bank credentials inside the widget, and picks an account. Credentials go to the bank; neither SideBet nor your servers see them. Aerosync returns a connectionId, which SideBet exchanges with Aeropay for a verified bank account.

In production the SDK loads the widget from Aeropay’s CDN and mounts it in your page. In sandbox mode SideBet serves a built-in replica so you can test the whole flow without Aeropay credentials.

Two sandboxes

Aeropay’s own sandbox is the real thing: real tokens, real Aerosync at sandbox.aerosync.com. It needs credentials from Aeropay. Alongside it we run a built-in replica so you can build the whole flow before those arrive. Which one a merchant uses is decided by its credentials, so both run against the same deployment.

The link flow, end to end

The Link SDK drives this for you. The endpoints are documented so you can build your own UI or debug a session; all of them take the link token as a bearer credential and run on your origin.

// Aeropay needs name and phone first
{ "session": { "kind": "collect_details", "requiredFields": ["lastName", "phone"] },
  "rail": { "railMode": "BYO", "pspType": "AEROPAY" } }

// That phone already has an Aeropay account
{ "session": { "kind": "confirm_mfa" }, "rail": { "railMode": "BYO", "pspType": "AEROPAY" } }

// Ready to link: open the Aerosync widget with this token
{ "session": { "kind": "aerosync_widget", "widgetUrl": "…", "token": "wtok_…", "environment": "sandbox" },
  "rail": { "railMode": "BYO", "pspType": "AEROPAY" } }

{ "firstName": "Ada", "lastName": "Lovelace", "phone": "+14155550123" }

{ "code": "123456" }

// wrong code → 400
{ "error": "Aeropay POST /v2/confirmUser failed: Invalid verification code (AP111)" }
// The SDK rewrites this as "That code didn't match. Check the last 6 digits we texted you and try again."

{ "payload": { "connectionId": "conn_…" },
  "mandate": { "userAgent": "…", "acceptedAt": "2026-09-02T20:11:28Z" } }

// → 200
{ "profile": { "pspType": "AEROPAY", "status": "VERIFIED", "bankName": "Chase", "bankLast4": "4321",
               "mandateAcceptedAt": "2026-09-02T20:11:28Z" },
  "rail": { "railMode": "BYO", "pspType": "AEROPAY" } }

Transfers and webhooks

When a user’s accrued round-ups reach their threshold, SideBet creates one Aeropay transaction for the total. Aeropay reports the outcome by webhook; SideBet verifies the signed URL token, updates the ledger, and forwards a roundup.settled or roundup.returned event to your webhook URL.

Sandbox controls

In sandbox the replica settles every transaction after five seconds. Force a different outcome to test your webhook handling:

curl -X POST https://api-production-610a.up.railway.app/mock/aeropay/control/transactions/$TXN_ID/declined
# outcomes: declined · voided · processed