TOPii API integration & OpenFinance remittance data services

1. Authentication & session

Reproduces the in-app login (email/phone + OTP) and session refresh used by com.topii.shopper, including device-binding checks observed during protocol analysis. Output: a server-side token broker your platform can call.

Typical use: multi-user back office where operators act on behalf of end users under explicit consent.

2. Cash-in barcode generator

Endpoint to create a send quote (amount, destination country, payout channel) and return the EAN/Code128 barcode payload, reference number, FX rate lock and expiry. Output: embeddable into web, POS or in-branch flows.

Typical use: immigrant-serving neighborhood stores wanting to offer TOPii top-ups at their own till.

3. Transfer statement & history

Paginated transfer list with filters (from_date, to_date, status, corridor, payout_channel) and a detail endpoint returning the full payment breakdown (principal, fee, markup, beneficiary, status log).

Typical use: monthly reconciliation, year-end tax documentation, family-finance dashboards.

4. Payout status webhooks

Subscription API for state transitions: QUOTED → CASH_IN_PENDING → FUNDED → PAYOUT_READY → PAID → (REFUNDED). Signed payloads and retries guarantee idempotent delivery.

Typical use: notify recipients, update ERP AR/AP, or trigger compliance screening on high-value transfers.

5. Cashback & loyalty sync

Extraction of the cashback ledger (up to 4% at partnered retailers in the EU flow), with merchant, SKU category and accrual date, exportable as CSV or JSON.

Typical use: reward aggregation tools that unify cashback across remittance apps and banking apps.

6. Contact & chat coordination

Structured export of in-app chat threads linked to a transfer, plus contact metadata (destination country, preferred payout channel). Always subject to user consent and data-minimization rules.

Typical use: customer-support analytics and fraud investigations.

Scenario A — Immigrant-serving retailer embeds TOPii cash-in

Context: a chain of Latino bodegas in the US wants to offer TOPii top-ups at its own till without redirecting customers to a separate app.

Data / API: POST /quote (amount, destination, payout channel) → GET /barcode/{id} → webhook payout.paid.

OpenFinance mapping: treat TOPii as a non-bank PIS-like provider; the retailer acts as an “initiator surface” collecting cash and confirming settlement through TOPii’s rails.

Scenario B — Family-finance dashboard aggregates transfers

Context: a personal-finance app in Spain unifies bank accounts (via PSD2 AIS) with remittance activity from TOPii for a holistic view of a household’s spending.

Data / API: GET /statement?from=&to= normalized to the same schema as Open Banking account transactions.

OpenFinance mapping: TOPii output becomes a secondary data source next to AIS feeds, closing the blind spot around cash-funded cross-border transfers.

Scenario C — AML/CTF screening for a partner money-services business

Context: an MSB partner needs to verify that high-value transfers funneled through TOPii cash-in have been AML-screened before they hit a downstream payout correspondent.

Data / API: webhook transfer.funded + GET /transfer/{id}/compliance returning KYC level, sanctions screen outcome and risk score.

OpenFinance mapping: aligns with FinCEN BSA expectations — transaction monitoring, sanctions screening against OFAC lists, and five-year record retention.

Scenario D — Accounting sync for small US-LatAm businesses

Context: a US SMB owner sends recurring payroll-style transfers via TOPii to contractors in Guatemala and wants the records inside QuickBooks / Xero.

Data / API: paginated GET /transfers → CSV / JSON → import pipeline to accounting software with chart-of-accounts mapping.

OpenFinance mapping: classic Open Data accounting sync, enriched with FX and fee breakdown per transfer.

Scenario E — Customer-support console for recipients in Venezuela

Context: a local partner in Venezuela handling cash pickup wants a unified support console that surfaces each transfer, its chat thread and its payout state.

Data / API: GET /transfer/{id} + GET /chat/{transfer_id} + event log.

OpenFinance mapping: a consent-scoped “support view” API, constrained to a specific transfer and timeframe so support agents never see unrelated data.

1. Authenticate & refresh a TOPii session

POST /api/v1/topii/auth/login
Content-Type: application/json

{
  "username": "+1-555-0101",
  "otp": "384129",
  "device_fingerprint": "srv-broker-01"
}

200 OK
{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "rft_0a8b...",
  "expires_in": 1800,
  "user": { "id": "u_9f21", "kyc_level": 2, "country": "US" }
}

// Refresh
POST /api/v1/topii/auth/refresh
Authorization: Bearer <REFRESH_TOKEN>

2. Create a cash-in barcode quote

POST /api/v1/topii/quote
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "amount_send":     200.00,
  "currency_send":   "USD",
  "destination":     "DO",
  "payout_channel":  "CASH_PICKUP",
  "beneficiary_id":  "b_4712"
}

200 OK
{
  "quote_id":      "q_20260420_abc",
  "barcode":       "978020137962",
  "barcode_format":"CODE128",
  "fx_rate":       58.37,
  "fee":           3.99,
  "total_charge":  203.99,
  "expires_at":    "2026-04-20T21:00:00Z"
}

3. Fetch statement & handle webhook

GET /api/v1/topii/statement?from=2026-03-01&to=2026-03-31&page=1
Authorization: Bearer <ACCESS_TOKEN>

200 OK
{
  "items": [
    { "transfer_id":"t_882","status":"PAID","amount_send":200,
      "currency_send":"USD","destination":"GT","fx_rate":7.71,
      "fee":3.99,"payout_channel":"BANK","updated_at":"2026-03-14T10:41Z" }
  ],
  "page":1, "total":42
}

// Webhook (signed with HMAC-SHA256)
POST https://your-app.example.com/hooks/topii
X-TOPii-Signature: t=1745078400,v1=6c1b...

{
  "event":"transfer.paid",
  "transfer_id":"t_882",
  "occurred_at":"2026-03-14T10:41:02Z",
  "payout": { "channel":"BANK","reference":"BCO-DO-9921" }
}

// Error envelope (all endpoints)
4xx/5xx
{ "error":{ "code":"QUOTE_EXPIRED","message":"Regenerate barcode",
            "trace_id":"tr_77fa" } }

Regulatory envelope

• FinCEN / BSA (US): transaction monitoring, OFAC/UN sanctions screening, SAR filing procedures and five-year record retention for all transfer metadata we expose.
• PSD2 / EBA guidelines (EU): strong customer authentication on login flows; consent-scoped data access for family-finance aggregators.
• GDPR (EU) / state privacy laws (US): data-minimization, purpose limitation, and explicit user consent records for every API call that touches personal data.
• AML/KYC alignment: integrations ship with risk thresholds, sanctions screening hooks and audit logs ready for external review.

Privacy safeguards

• Backend-for-Frontend pattern — TOPii credentials are never exposed to client apps.
• Short-lived tokens, encrypted at rest, rotated per session.
• Consent records linked to every data pull, retained for audit.
• PII redaction in logs; selective field masking for support consoles.
• NDAs, SLAs and DPA templates available on request for enterprise clients.

Remitly

Personal remittance app with bank deposit, cash pickup and mobile wallet delivery. Shares many corridor overlaps with TOPii; unified transaction exports are a common request.

Western Union

Global agent network covering 200+ countries. Integration patterns around cash-pickup status and agent-network settlement resemble TOPii’s cash-in flows.

MoneyGram

Hybrid digital + in-person sender with agent locations worldwide. Teams often reconcile MoneyGram and TOPii transfers into a single AR/AP view.

Wise

Multi-currency account and mid-market FX transfers, primarily bank-to-bank. Useful complement to TOPii for families that mix cash and digital funding.

Xoom (a PayPal service)

US-funded transfers to LatAm, Asia and Africa with bank deposit, cash pickup and bill pay. Overlaps TOPii’s Dominican Republic and Guatemala corridors.

WorldRemit

Strong mobile-money integration across Africa and LatAm. Useful for consolidated payout-channel analytics alongside TOPii.

Ria Money Transfer

Large cash-pickup agent network in LatAm; statement aggregation across Ria and TOPii is a frequent accounting-sync request.

BOSS Revolution

Popular with US Hispanic users for money transfer and international calling. Common co-integration alongside TOPii for immigrant-focused back offices.

Small World Money Transfer

Europe-based remittance service with broad LatAm and African corridors; overlaps with TOPii’s Spain distribution network.

Revolut

Neobank with international transfer, card and FX features. Consumers holding both Revolut and TOPii benefit from unified spend-plus-remittance dashboards.

Deliverables checklist

• OpenAPI 3.1 / Swagger specification for all TOPii endpoints in scope
• Protocol & auth flow report (OTP login, token refresh, device binding, signature scheme)
• Runnable source code for login, quote/barcode, statement and webhook handling (Python / Node.js / Go on request)
• Webhook verification library (HMAC-SHA256) and replay-protection logic
• Automated tests (unit + corridor-level integration tests for US→DO, US→GT, US→VE, ES→EU)
• Postman / Insomnia collection + sandbox fixtures
• Compliance guidance pack: KYC level mapping, OFAC screen hooks, SAR triggers, GDPR data map
• Runbook: rotation, observability, rate-limit handling, incident playbook

Engagement models

• Source-code delivery from $300 — you receive runnable API source and documentation; payment is triggered only after delivery meets your acceptance checklist.
• Pay-per-call hosted API — call our managed TOPii endpoints and pay only for successful calls; no upfront fee, best for teams validating a use case or running seasonal volume.
• Optional maintenance retainer — covers TOPii client updates, new corridors, and regulatory changes.
• NDAs, SLAs and DPAs available on request.

About our studio

We are an independent technical studio focused on App interface integration, authorized API integration and OpenFinance-style data pipelines. Team members have hands-on backgrounds in mobile apps, payments, open banking and cross-border fintech.

• Mobile protocol analysis (Android / iOS, native and hybrid stacks)
• Open Banking (PSD2 AIS/PIS), OpenFinance and OpenData design patterns
• Cross-border payment rails, FX, and settlement integrations
• Custom Python / Node.js / Go SDKs, test harnesses and CI pipelines
• End-to-end workflow: protocol analysis → API design → build → validation → compliance review
• Documented, authorized access patterns — no gray-area tactics

Contact & next steps

Ready to scope your TOPii integration? Share your target data (e.g. transfer statements, cash-in barcodes, payout webhooks) and preferred delivery model. We’ll come back with a concrete quote and timeline.

Open contact page

Prefer pay-per-call? Mention “pay-per-call TOPii API” in your message and we’ll enable a sandbox key for immediate testing.

Engagement workflow

1. Scope confirmation — which corridors (US→DO/GT/VE, ES→EU, upcoming LatAm) and which data (quote, statement, webhook).
2. Protocol analysis & API design (2–5 business days depending on depth).
3. Build and internal validation against TOPii live and sandbox traffic (3–8 business days).
4. Docs, SDK snippets, Postman collection and test cases (1–2 business days).
5. Compliance review checklist, then handover / go-live. Typical first delivery: 5–15 business days.

FAQ

What do you need from me?

How long does the first delivery take?

How do you handle compliance?

Do you support other remittance apps?