HOPPA API Quickstart

1. Create a user

Every card, wallet, and transaction belongs to a user. Create one with your internal ID so you can reconcile later.

const res = await fetch('https://{base_url}/api/v2/users', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstName: 'John',
    lastName: 'Doe',
    email: 'john@example.com',
    phone: '+49151XXXXXXXX',
    externalUserId: 'your-internal-user-id'
  })
});
const user = await res.json(); // → { id: 'usr_...', ... }

Users API reference →

2. Issue a card

Order a virtual or physical card for the user. The card ID returned here is used for funding, controls, and transaction queries.

const res = await fetch('https://{base_url}/api/v2/cards', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: '{userId}',
    cardTypeId: '{cardTypeId}',
    currency: 'USD',
    cardName: 'John Doe',
    phone: '+49151XXXXXXXX',
    phoneCode: '49',
    externalCardId: 'your-internal-card-id',
    billingAddress: {
      city: 'Ljubljana',
      line1: 'Slovenska Cesta 54',
      state: '',
      country: 'SVN',
      postalCode: '1000'
    }
  })
});
const card = await res.json(); // → { id: 'crd_...', status: 'PENDING', ... }

Cards API reference →

3. Fund the card

Top up the card so it can spend. In the sandbox you can fund from a test balance; in production top-ups draw from your program's funding account.

const res = await fetch('https://{base_url}/api/v2/cards/topup', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    cardId: '{cardId}',
    amount: '100.00',
    currency: 'USD'
  })
});
const topup = await res.json();

Cards API reference →

4. Transact & reconcile

Once funded, the card can transact. Pull transactions for the card (or your whole program) to reconcile and power your ledger.

const res = await fetch(
  'https://{base_url}/api/v2/cards/{cardId}/transactions',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const transactions = await res.json();

// Or program-wide, with stats:
// GET /api/v2/transactions
// GET /api/v2/transactions/stats

Transactions API reference →

Frequently asked questions

How do I authenticate HOPPA API requests?

Send your API key in the x-api-key header on every request. Sandbox keys work against the sandbox base URL provided with your access; production keys are issued when you go live.

How do I get a sandbox API key?

Sandbox access is granted on request, not self-service. Submit the form at hoppa.global/sandbox with your company and use case, and the HOPPA team will set you up.

How do I issue a card with the HOPPA API?

Create a user with POST /api/v2/users, then order a card with POST /api/v2/cards passing the userId, cardTypeId, currency, and billing address. Fund it with POST /api/v2/cards/topup and it is ready to transact.

Is there a machine-readable API specification?

Yes — the full OpenAPI 3.0 spec is served at https://hoppa.global/api/openapi-spec (JSON). The interactive reference at hoppa.global/docs renders the same spec, so both are always in sync with the live API.

Which currencies and rails does HOPPA support?

HOPPA supports multi-currency accounts and wallets, card programs (including crypto-enabled cards), currency exchange, and money movement across UK and EU rails. See the Banking, Swap, and Transfers sections of the API reference for the full endpoint list.