Make one safe request.
All operations in the current public integration contract use company API-key authentication. Dashboard sign-in and self-service onboarding are separate private session APIs. Dual Balance is different: the white-label partner hosts its own API and HOPPA authenticates to it with the partner-issued X-API-Key.
Store it as HOPPA_API_KEY in your server’s secret manager.
Base URL: https://staging.hoppa.global
x-api-key: YOUR_API_KEY on every request.
Verify credentials by listing tiers
curl --request GET 'https://staging.hoppa.global/api/v2/tiers' \
-H 'X-API-Key: YOUR_API_KEY'Example 200 responseJSON · collapse
{
"Tiers": [
{
"Id": 123,
"Name": "string",
"Description": "Example description",
"TierLevel": 1,
"AccountType": "string",
"MonthlyFee": 100,
"YearlyFee": 100,
"Features": [
"string"
],
"Limits": {},
"IsDefault": true,
"IsActive": true,
"IsHidden": true,
"StripeAccountOwnerOverride": "string",
"IncludesEqualsCards": true,
"IncludesEqualsIban": true,
"EuPriceTableId": "string",
"UkPriceTableId": "string",
"UsPriceTableId": "string",
"UpPriceTableId": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}
]
}Choose the authentication surface first
x-api-keyCore partner operations, MOR public endpoints and company-scoped resource management.
Authorization: BearerPrivate dashboard flows only; excluded from the public integration catalogue.
X-API-KeyThe white-label partner issues this key to HOPPA and validates it on all six partner-hosted endpoints.
X-Hoppacard-SignatureVerify the HMAC against the exact raw webhook body before parsing or acknowledging it.
Create, verify, then provision.
Create the Hoppa user once, then choose exactly one of four KYC input methods: hosted SumSub, mobile SDK, reusable SumSub sharing, or a complete manual payload. Each selected bank still has an independent approval state.
IdStep 1 — create the customer
/api/v2/users- ExternalUserId must be your stable customer ID, not an email address that may change.
- Phone should be E.164, for example
+447700900123. - Send AccountType: personal explicitly.
- Keep the returned Hoppa Id; every following call uses it.
Create a personal user
curl --request POST 'https://staging.hoppa.global/api/v2/users' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Email": "jane.doe@example.com",
"FirstName": "Jane",
"LastName": "Doe",
"Phone": "+447700900123",
"ExternalUserId": "customer_1042",
"AccountType": "personal",
"DateOfBirth": "1990-01-15",
"Address": "10 Market Street",
"City": "London",
"Country": "GB",
"ZipCode": "SW1A 1AA"
}'Example 201 responseJSON · collapse
{
"Id": 123,
"ExternalUserId": "external_reference_123",
"Email": "user@example.com",
"FirstName": "Jane",
"LastName": "Doe",
"Status": "PENDING",
"KycStatus": "SUBMITTED",
"KycLevel": "HOPPA_PRODUCTION",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CompanyId": 123,
"PackageId": 123,
"BusinessName": "string",
"BusinessExternalId": "external_reference_123",
"BusinessParentId": 123,
"AccountType": "business",
"PrimaryExternalWalletId": "external_reference_123",
"SelectedTierId": 123,
"TierBillingCycle": "string",
"OnboardingProductPreference": "external_reference_123",
"ReferralAttribution": {
"Status": "PENDING",
"Reason": "string",
"Remedy": "string",
"RelationshipId": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"AcceptedTermsVersion": 1
}
}Step 2 — choose how to provide KYC
/api/v2/users/{userId}/sumsub/kyc-urlUse the returned short-lived AccessToken and Configuration to launch the SumSub WebSDK. Your backend still owns status polling and provider provisioning.
Create a hosted SumSub KYC link
curl --request POST 'https://staging.hoppa.global/api/v2/users/123/sumsub/kyc-url' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Occupation": "STUDENT",
"AnnualSalary": "0-10000",
"AccountPurpose": "PERSONAL_USE",
"ExpectedMonthlyVolume": "0-1000",
"DocumentIssueDate": "2022-01-01",
"IpAddress": "203.0.113.10"
}'Example 200 responseJSON · collapse
{
"Success": true,
"ErrorCode": "string",
"ErrorMessage": "string",
"AccessToken": "PLACEHOLDER_TOKEN",
"ApplicantId": "string",
"ExternalUserId": "external_reference_123",
"KycSubmissionId": 123,
"Status": "PENDING",
"ExistingStatus": "PENDING",
"ExpiresAt": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z",
"IsNewApplicant": true,
"Message": "string",
"Configuration": {
"LevelName": "string",
"TokenValidityHours": 1,
"Provider": "string",
"IsTestMode": true,
"SdkVersion": "string",
"RequiredDocuments": [
"string"
]
}
}Step 3 — wait for the right approval
/api/v2/users/{userId}/kyc/detailed-statusBase KYC approved → ensure Crypto cards account exists.
Required for selected setupBase KYC approved → submit Banking application and any requested documents.
Not selectedStep 4 — run provider onboarding
When Crypto cards is the company default, user creation provisions the account. Treat /users/create-interlace-account/{userId} as an idempotent repair path.
Submit the multipart application below after SumSub is approved. The proof of address must be JPG, JPEG, PNG or PDF and not older than three months.
Submit Banking personal onboarding
curl --request POST 'https://staging.hoppa.global/api/v2/banking/equalsmoney-onboarding?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'RequestedFeatures=PAYMENTS' \
-F 'RequestedFeatures=CARDS' \
-F 'MainPurpose=PERSONAL_TRANSFERS_OR_LIVING_EXPENSES' \
-F 'SourceOfFunds=RECEIVING_SALARY_PENSION_OR_DIVIDENDS' \
-F 'DestinationOfFunds=GB' \
-F 'CurrenciesRequired=GBP' \
-F 'AnnualVolume=10001-50000' \
-F 'NumberOfPayments=5-10' \
-F 'CardPurposes=TRAVEL' \
-F 'AtmWithdrawalsRequired=false' \
-F 'NumberOfCardsRequired=0-10' \
-F 'CardAnnualSpend=10001-50000' \
-F 'ProofOfAddress=@/absolute/path/proof-of-address.pdf'Example 202 responseJSON · collapse
{
"Success": true,
"Message": "Application accepted for review",
"CorrelationId": "eq_onboarding_551",
"AccountId": "eq_account_771"
}Keep company KYB separate from personal KYC.
Create the Hoppa user with AccountType: business. The public full KYB application shown here is the Banking path; Crypto cards business availability is programme-specific.
Read workflow state and select an eligible tier
/api/v2/business-onboarding?userId=321Select a returned business onboarding tier
curl --request POST 'https://staging.hoppa.global/api/v2/business-onboarding/tier?userId=321' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"TierId": 12
}'Example 200 responseJSON · collapse
{
"success": true
}Use a tier returned for this business user. The new workflow’s response models are not yet specified in Scalar; do not infer field names from these request examples.
/api/v2/business/onboarding/associated-people?userId=321/api/v2/business/onboarding/application?userId=321/api/v2/business/onboarding/application/documents?userId=321/api/v2/business/onboarding/associated-people/{personId}/documents?userId=321/api/v2/business/onboarding/application/submit?userId=321Create a Banking business application
curl --request POST 'https://staging.hoppa.global/api/v2/business/onboarding/application?userId=321' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Market": "UK",
"BusinessType": "PRIVATE_COMPANY",
"CountryOfIncorporation": "GB",
"RegisteredName": "Example Trading Ltd",
"RegistrationNumber": "12345678",
"BusinessOverview": "Online retail of consumer electronics",
"IndustryMain": "TRADE_COMMERCE",
"IndustrySub": "ECOMMERCE",
"EmployeeCount": "ELEVEN_TO_FIFTY",
"IncorporationDate": "2020-03-12",
"Website": "https://example.com"
}'Example 200 responseJSON · collapse
{
"isActionRequired": true,
"id": "string",
"status": "PENDING",
"accountId": "string",
"market": "string",
"type": "string",
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z",
"firstName": "Jane",
"lastName": "Doe",
"dob": "2026-08-05",
"email": "user@example.com",
"phoneNumber": "+447700900123",
"nationalities": [
"string"
],
"identityDocumentNumber": "string",
"taxId": "string",
"countryOfIncorporation": "GB",
"regionOfIncorporation": "string",
"registeredName": "string",
"registrationNumber": "string",
"tradingNames": [
"string"
],
"businessOverview": "string",
"industry": {
"main": "string",
"sub": "string"
},
"employeeCount": "string",
"incorporationDate": "2026-08-05",
"website": "string",
"businessPromotionDescription": "Example description",
"featureInformation": {
"requestedFeatures": [
"CARDS"
],
"cardsInformation": {
"purposes": [
"SALARY_OR_INCOME"
],
"estimatedAnnualSpend": "0-10000",
"atmWithdrawalsRequired": true,
"businessDisplayName": "string",
"numberOfCardsRequired": "0-10",
"cardsAreForEmployees": true
},
"paymentsInformation": {
"purposes": [
"SALARY_OR_INCOME"
],
"estimatedPaymentCount": "FEWER-THAN-5",
"estimatedPaymentVolume": "0-10000",
"inboundCurrencies": [
"AED"
],
"outboundCurrencies": [
"AED"
],
"receivingCountries": [
"AD"
],
"sendingCountries": [
"AD"
],
"accountFundingSource": [
"RECEIVING_FUNDS_FROM_OWN_ACCOUNTS"
]
}
},
"addresses": [
{
"addressType": "REGISTERED",
"streetName": "string",
"postcode": "SW1A 1AA",
"city": "London",
"countryCode": "AD",
"buildingNumber": "string",
"buildingName": "string",
"region": "string"
}
],
"associatedPeople": [
{
"associatedPersonId": "string",
"associationType": "string",
"jobTitle": "string",
"ownershipPercentage": 1
}
]
}Discover resources; never manufacture IDs.
After onboarding, ask the API what this customer has. When both banks are selected, each returned resource identifies the provider that owns the operation.
/api/v2/banking/providers?userId=123Which providers are available.
/api/v2/banking/accounts?userId=123Accounts, currencies and provider IDs.
/api/v2/banking/balance?userId=123Aggregated balances across providers.
/api/v2/banking/users/123/budgetsBanking budgets used by cards and payouts.
/api/v2/banking/users/123/equals-banking-infoBanking account and IBAN details.
/api/v2/users/123/assetsCrypto cards/crypto wallet assets.
Display friendly provider and currency labels in your UI, but pass the exact returned accountId, balanceId, budgetId, payeeId or local cardId back to the API.
Resolve the product before ordering.
GET /tiersPOST /users/{id}/tierGET /tiers/card-tier/{tierId}POST /cardsOrder a virtual card
curl --request POST 'https://staging.hoppa.global/api/v2/cards' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: card-order-customer-1042-v1' \
--data '{
"UserId": 123,
"CardTypeId": 456,
"Phone": "+447700900123",
"Currency": "GBP",
"CardName": "Jane main card",
"BudgetId": "budget_only_for_equals_money",
"AutoLockEnabled": false
}'Example 201 responseJSON · collapse
{
"DiscountCode": "string",
"Id": 123,
"UserId": 123,
"ExternalCardId": "external_reference_123",
"Provider": "string",
"BudgetId": "string",
"DeliveryAddressId": "string",
"Nickname": "string",
"CardType": "string",
"CardNetwork": "string",
"CardNumber": "****-****-****-1234",
"ExpiryDate": "2026-08-05",
"Status": "PENDING",
"Balance": {
"Available": "string",
"Pending": "string",
"Frozen": "string",
"Currency": "USD"
},
"Currency": "USD",
"VelocityControl": {
"Type": "string",
"Limit": "string"
},
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CardTypeId": 123,
"CardTypeTierId": 123,
"TierId": 123,
"CanSetPin": true,
"AutoLockEnabled": true,
"AutoLockActiveUntil": "2026-08-05T09:30:00Z",
"TransakOrder": "string",
"RequiredAmount": "100.00",
"AvailableAmount": "100.00",
"Shortfall": "string",
"Message": "string",
"Errors": [
{
"key": "string",
"reason": "string"
}
]
}Remove BudgetId for Crypto cards. For Banking it is required. For a physical card also send complete DeliveryAddress and, where configured, a design ID.
Physical Crypto cards
- Quote production and mailing fees with
GET /api/v2/cards/physical-card-fees?userId=123&country=GB&cardTypeId=456. - Show both fee rows and the total to the customer.
- Order the card. For an existing pending card, quote
GET /cards/{cardId}/bulk-ship/quoteand executePOST /cards/{cardId}/bulk-ship.
Manage an issued card
/api/v2/cards?userId=123List local cards. Use the returned local Id for all card actions.
/api/v2/cards/789?userId=123Fetch status and safe details.
/api/v2/cards/789/activate?userId=123Physical card after delivery.
/api/v2/cards/789/freeze?userId=123Temporary stop; supported across providers.
/api/v2/cards/789/enable?userId=123Re-enable unless system-blocked.
/api/v2/cards/789/pin?userId=123PIN must satisfy documented six-digit rules.
/api/v2/cards/789/widget?userId=123Short-lived secure iframe URL. Never persist card data.
/api/v2/cards/789?userId=123Crypto cards only. Permanent cancellation.
Move money using the card’s provider.
The public card endpoints look the same, but the source and destination are provider-specific.
Quantum USD → card. Unload returns card funds to the Quantum wallet.
Budget → card balance. Ensure the budget has enough USD-equivalent funds.
Top up a card
curl --request POST 'https://staging.hoppa.global/api/v2/cards/topup' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: topup-card-789-20260805-001' \
--data '{
"CardId": 789,
"Token": "USD",
"Value": 100
}'Example 200 responseJSON · collapse
{
"Success": true,
"TransakUrl": "https://example.com/callback",
"OrderId": "string",
"Token": "USDC",
"Value": 100,
"WalletAddress": "0x1111111111111111111111111111111111111111",
"Message": "string",
"ErrorCode": "string",
"ErrorMessage": "string",
"Fee": 100,
"RequestedValue": 100,
"GrossValue": 100,
"IsPartial": true,
"CreatedAt": "2026-08-05T09:30:00Z",
"Configuration": {
"FiatCurrency": "USD",
"CryptoCurrency": "USDC",
"Network": "string",
"MinAmount": 100,
"MaxAmount": 100,
"IsTestMode": true
}
}Unload a card
curl --request POST 'https://staging.hoppa.global/api/v2/cards/unload-card' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: unload-card-789-20260805-001' \
--data '{
"CardId": 789,
"Currency": "USD",
"Value": 25
}'Example 200 responseJSON · collapse
{
"Success": true,
"CardId": 123,
"ExternalCardId": "external_reference_123",
"RequestedAmount": 100,
"ActualAmount": 100,
"Fee": 100,
"NetAmount": 100,
"Currency": "USD",
"Status": "PENDING",
"TransactionId": "string",
"ExternalTransactionId": "external_reference_123",
"RequestedAt": "2026-08-05T09:30:00Z",
"ProcessedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z",
"Destination": {
"Type": "string",
"AccountNumber": "string",
"WalletAddress": "0x1111111111111111111111111111111111111111",
"BankName": "string",
"RoutingNumber": "string",
"SwiftCode": "string",
"AccountHolderName": "string",
"IsVerified": true
},
"BalanceAfter": {
"AvailableBalance": 100,
"PendingBalance": 100,
"TotalBalance": 100,
"Currency": "USD",
"UpdatedAt": "2026-08-05T09:30:00Z"
},
"ErrorCode": "string",
"ErrorMessage": "string",
"Message": "string",
"Audit": {
"RequestedBy": "string",
"RequestedAt": "2026-08-05T09:30:00Z",
"RequestSource": "string",
"IPAddress": "string",
"UserAgent": "string",
"IsSecureConnection": true,
"AuthenticationMethod": "string",
"AdditionalNotes": "string"
}
}Use the four-step payout state machine.
First create and, when required, verify a payee. Then quote, check, initiate and finally create the payout.
A. Create the IBAN payee
/api/v2/banking/payees/required-fields?userId=123&paymentType=COMPANY&paymentMethod=SEPA.CREDITTRANSFER¤cy=EURBuild the form from this response. For SEPA, send the IBAN in Iban and the BIC in Bic when requested.
Validate and create a payee
curl --request POST 'https://staging.hoppa.global/api/v2/banking/payees?userId=123' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: payee-acme-eur-v1' \
--data '{
"Name": "Acme Supplies Ltd",
"PaymentType": "COMPANY",
"PaymentMethod": "SEPA.CREDITTRANSFER",
"Currency": "EUR",
"Iban": "DE89370400440532013000",
"Bic": "COBADEFFXXX",
"BankName": "Example Bank",
"Comments": "Approved supplier"
}'Example 202 responseJSON · collapse
{
"Approval": {
"VerificationToken": "PLACEHOLDER_TOKEN",
"DeviceId": "00000000-0000-4000-8000-000000000123",
"Operation": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"SigningPayload": "string",
"DetailsJson": "string",
"TermsJson": "string",
"Algorithm": "ECDSA_P256_SHA256_DER",
"PublicKey": {}
},
"TermsJson": "string",
"Success": true,
"VerificationToken": "PLACEHOLDER_TOKEN",
"Message": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"RecipientName": "string",
"AccountNumberLast4": "string",
"VerificationResult": {
"Status": "PENDING",
"Title": "string",
"Message": "string",
"ReasonCode": "string",
"NameMatch": true,
"CanProceed": true
}
}B. Quote and pay
Quote a payout
curl --request POST 'https://staging.hoppa.global/api/v2/banking/quotations?userId=123' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: payout-invoice-2026-018-quote' \
--data '{
"PayeeId": 902,
"FromCurrency": "EUR",
"Amount": 125.5,
"FeeMethod": "INCLUDED",
"BalanceId": "provider_balance_or_budget_id"
}'Example 200 responseJSON · collapse
{
"IsAvailable": true,
"UnavailableReason": "string",
"RetryAfterSeconds": 1,
"Id": "string",
"QuoteRequestId": "string",
"Rate": "string",
"Fees": [
{
"Currency": "USD",
"Amount": "100.00",
"FeeType": 1
}
],
"ExpirationTime": "string",
"CreateTime": "string"
}2 Check the payout
POST /api/v2/banking/payouts/check?userId=123
{
"PayeeId": 902,
"QuotationId": "id-from-quotation",
"Amount": "125.50",
"Currency": "EUR",
"BalanceId": "provider_balance_or_budget_id",
"Memo": "Invoice 2026-018"
}3 Initiate and send OTP
POST /api/v2/banking/payouts/initiate?userId=123
{
"CheckId": "check-id",
"QuoteRequestId": "quote-request-id",
"PayeeId": 902,
"Amount": "125.50",
"Currency": "EUR",
"FromCurrency": "EUR",
"BalanceId": "provider_balance_or_budget_id"
}4 Verify OTP
POST /api/v2/banking/otp/verify?userId=123
{
"verificationId": "id-from-initiate",
"code": "123456"
}5 Create the payout
POST /api/v2/banking/payouts?userId=123
{
"VerificationToken": "verified-token",
"CheckId": "check-id",
"QuoteRequestId": "quote-request-id",
"PayeeId": 902,
"Amount": "125.50",
"Currency": "EUR",
"FromCurrency": "EUR",
"BalanceId": "provider_balance_or_budget_id"
}Treat API responses as acceptance, not settlement.
Store the local Hoppa ID immediately, then update your state from webhooks and scheduled reconciliation.
List unified banking transactions
curl --request GET 'https://staging.hoppa.global/api/v2/banking/transactions?userId=123&page=1&pageSize=50' \
-H 'X-API-Key: YOUR_API_KEY'Example 200 responseJSON · collapse
{
"Transactions": [
{
"TransactionId": "string",
"TradeId": "string",
"AccountId": "string",
"Type": "string",
"Amount": 100,
"Currency": "USD",
"Description": "Example description",
"Status": "PENDING",
"Provider": "EqualsMoney",
"CreatedAt": "2026-08-05T09:30:00Z"
}
],
"Total": 1,
"Page": 1,
"PageSize": 1
}/api/v2/banking/transactionsUnified view across provider accounts.
/api/v2/transactionsFees, card links and metadata.
/api/v2/cards/{cardId}/transactionsAuthorisations and card movements.
/api/v2/banking/payouts/{payoutId}Provider-refreshed payout state.
Webhook receiver rules
Browse every webhook event and payload →
user.registeredcardholder.createdcardholder.approvedcard.createdcard.updatedcard.deletedcard.3ds.otpMove money only between discovered balances.
Use account and budget IDs returned for this user. The banking layer can create and maintain Banking budgets, move funds internally, and quote then execute foreign-exchange trades.
Create a Banking budget
curl --request POST 'https://staging.hoppa.global/api/v2/banking/users/123/budgets' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Name": "Operations GBP",
"Currencies": [
"GBP",
"EUR"
],
"Type": "individual",
"Features": [
"peopleCards"
],
"AllowCurrencyAlignment": true
}'Example 201 responseJSON · collapse
{
"BudgetId": "string",
"AccountId": "string",
"Name": "string",
"Type": "string",
"ParentId": "string",
"Status": "PENDING",
"AllowCurrencyAlignment": true,
"Currencies": [
"string"
],
"Balances": [
{
"Currency": "USD",
"AvailableBalance": 100,
"LedgerBalance": 100,
"PendingBalance": 100
}
],
"SettlementDetails": {
"BalanceReference": "100.00",
"CurrencyDetails": [
{
"CurrencyCode": "USD",
"Local": {},
"International": {}
}
]
},
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}Transfer between a user’s balances
curl --request POST 'https://staging.hoppa.global/api/v2/banking/transfers/internal' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"SourceBalanceId": "balance_gbp_primary",
"DestinationBalanceId": "budget_gbp_cards",
"Amount": 250,
"Currency": "GBP",
"Reference": "Fund card budget"
}'Example 201 responseJSON · collapse
{
"Success": true,
"TransferId": "string",
"Status": "PENDING",
"Amount": 100,
"Currency": "USD",
"Provider": "EqualsMoney",
"CreatedAt": "2026-08-05T09:30:00Z",
"ErrorMessage": "string"
}Quote a foreign-exchange trade
curl --request POST 'https://staging.hoppa.global/api/v2/banking/trades/quote?userId=123' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"AccountId": "account_from_banking_accounts",
"BaseCurrency": "GBP",
"QuoteCurrency": "EUR",
"Amount": 500,
"Side": "sell"
}'Example 200 responseJSON · collapse
{
"QuoteId": "string",
"BaseCurrency": "USD",
"QuoteCurrency": "USD",
"Amount": 100,
"QuoteAmount": 100,
"ExchangeRate": 100,
"Provider": "EqualsMoney",
"ExpiresAt": "2026-08-05T09:30:00Z"
}/api/v2/banking/users/{userId}/budgets/{budgetId}/api/v2/banking/users/{userId}/budgets/{budgetId}/transfer/api/v2/banking/trades/execute/api/v2/banking/orders/quote/api/v2/banking/orders/tradeChoose the route from the source and destination.
“Transfer” is not one operation. First identify who owns the source balance and where money must finish. The selected products below identify matching routes. Actual availability still depends on programme enablement, customer approval, supported assets and balances.
User crypto wallet→Company treasury
POST /transfers/user-to-masterCompany treasury→User crypto wallet
POST /transfers/master-to-userUSDC / USDT→Crypto cards Quantum USD
POST /transfers/crypto-to-quantum-transferCrypto cards Quantum USD→USDC / USDT
POST /transfers/quantum-usd-to-crypto-exchangeBanking budget→Another budget on same account
POST /banking/users/{userId}/budgets/{budgetId}/transferBanking budget→User Crypto cards USDC address
POST /crypto-virtual-accounts/equals-to-interlaceBanking budget→USDC / USDT address + chain
POST /crypto-virtual-accounts/equals-to-wallet/*Exchange source account→Exchange settlement account
POST /crypto-virtual-accounts/exchange/quote → /acceptCrypto cards wallet→Banking budget
POST /crypto-virtual-accounts/interlace-to-equals/initiate → /confirmUser crypto balance→Blockchain wallet
POST /transfers/withdrawals/cryptoCompany treasury transfers
Use these only for movement between the authenticated company master wallet and one of its users. UserId is always the customer side of the transfer.
Sweep a user balance to the master wallet
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/user-to-master' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"Amount": "100.00",
"Currency": "USDC",
"Description": "Move user funds to company treasury",
"ExternalReferenceId": "treasury_sweep_1042_001",
"Metadata": {
"customerId": "customer_1042"
}
}'Example 201 responseJSON · collapse
{
"Id": 123,
"UserId": 123,
"Status": "PENDING",
"Amount": "100.00",
"Currency": "USD",
"SourceType": "CRYPTO_ASSETS",
"DestinationType": "CRYPTO_ASSETS",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"Metadata": {},
"TransferType": "string",
"Message": "string",
"ErrorCode": "string",
"FeeAmount": "100.00",
"FeeCurrency": "USD",
"FeeType": "None",
"NetAmount": "100.00"
}Fund a user from the master wallet
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/master-to-user' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"Amount": "75.00",
"Currency": "USDC",
"Description": "Fund customer wallet",
"ExternalReferenceId": "customer_funding_1042_001",
"Metadata": {
"approvedBy": "treasury-system"
}
}'Example 201 responseJSON · collapse
{
"Id": 123,
"UserId": 123,
"Status": "PENDING",
"Amount": "100.00",
"Currency": "USD",
"SourceType": "CRYPTO_ASSETS",
"DestinationType": "CRYPTO_ASSETS",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"Metadata": {},
"TransferType": "string",
"Message": "string",
"ErrorCode": "string",
"FeeAmount": "100.00",
"FeeCurrency": "USD",
"FeeType": "None",
"NetAmount": "100.00"
}Crypto cards Quantum conversions
The destination of crypto-to-Quantum is always USD. The reverse path accepts only the supported target crypto currencies. Each operation currently has its own one-request-per-15-seconds limit; respect Retry-After after a 429.
Convert crypto to Quantum USD
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/crypto-to-quantum-transfer?userId=123' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"SourceCurrency": "USDC",
"DestinationCurrency": "USD",
"Amount": 125
}'Example 200 responseJSON · collapse
{
"Success": true,
"TransferId": "string",
"Message": "string",
"ErrorCode": "string",
"ErrorMessage": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"Details": {
"SourceCurrency": "USD",
"DestinationCurrency": "USD",
"Amount": 100,
"Status": "PENDING",
"InterlaceAccountId": "string",
"TransferPath": "string",
"RequiresExchange": true,
"ExchangeRate": 100,
"AvailableBalances": {
"FIELD_FROM_APPLICATION": 100
},
"RequiredAmount": 100,
"TotalAvailableValue": 100
}
}Convert Quantum USD to crypto
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/quantum-usd-to-crypto-exchange?userId=123' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Currency": "USDC",
"Amount": 100
}'Example 200 responseJSON · collapse
{
"Success": true,
"Message": "string",
"ErrorCode": "string",
"SourceAmount": 100,
"TargetCurrency": "USD",
"CryptoAmountReceived": 100,
"Rate": 100,
"Fee": 100,
"TradeId": "string",
"Status": "PENDING",
"InitiatedAt": "2026-08-05T09:30:00Z",
"Details": {
"FinalCryptoBalance": 100,
"FinalQuantumBalance": 100
}
}Banking cross-provider transfers
Transfer a Banking budget to Crypto cards
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/equals-to-interlace' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"IdempotencyKey": "equals-to-interlace-customer-123-001",
"UserId": 123,
"FiatCurrency": "GBP",
"Amount": 250,
"BudgetId": "equals_budget_from_banking_api"
}'Example 200 responseJSON · collapse
{
"Success": true,
"Message": "string",
"Reference": "external_reference_123",
"UserId": 123,
"BudgetId": "string",
"FiatCurrency": "USD",
"FiatAmount": "100.00",
"CryptoCurrency": "USDC",
"EstimatedCryptoAmount": "100.00",
"EstimatedFeeAmount": "100.00",
"Rate": "string",
"ChainId": 123,
"Chain": "string",
"DepositAddress": "string",
"BoomFiPayout": {}
}Banking → external wallet through Exchange
Initiate a Banking budget transfer to a wallet
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/equals-to-wallet/initiate' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"FiatCurrency": "EUR",
"Amount": 150,
"BudgetId": "equals_budget_from_banking_api",
"CryptoCurrency": "USDC",
"Chain": "ethereum",
"Address": "0x1111111111111111111111111111111111111111"
}'Example 200 responseJSON · collapse
{
"Success": true,
"VerificationToken": "PLACEHOLDER_TOKEN",
"Message": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"Reference": "external_reference_123",
"UserId": 123,
"BudgetId": "string",
"FiatCurrency": "USD",
"FiatAmount": "100.00",
"CryptoCurrency": "USDC",
"EstimatedCryptoAmount": "100.00",
"EstimatedFeeAmount": "100.00",
"Rate": "string",
"ChainId": 123,
"Chain": "string",
"DestinationAddress": "0x1111111111111111111111111111111111111111",
"DestinationAddressMasked": "0x1111111111111111111111111111111111111111"
}For an external wallet, display the quote and send the OTP, then finish with POST /api/v2/crypto-virtual-accounts/equals-to-wallet/confirm using UserId, VerificationToken and OtpCode.
Complete transfer endpoint inventory
/api/v2/transfers/api/v2/transfers/{transferId}/api/v2/transfers/wallet-topup/api/v2/transactions/top-up/api/v2/transfers/withdrawals/fee-and-quota/api/v2/transfers/withdrawals/available-balance/api/v2/transfers/withdrawals/validate/api/v2/transfers/withdrawals/crypto/api/v2/transfers/withdrawals/crypto/confirm/api/v2/transfers/crypto-transactions/api/v2/transfers/crypto-refunds/api/v2/transfers/crypto-refunds/gas-fee/api/v2/transfers/crypto-refundsSeparate deposits, conversions and withdrawals.
A wallet address, crypto virtual account, Quantum balance and payment card are different resources. Show the network and currency together, and never infer a chain from the token symbol.
Use /transfers/wallet-topup for the hosted Transak route, or a returned deposit address for a direct on-chain deposit.
Use /crypto-to-quantum-transfer and /quantum-usd-to-crypto-exchange for Crypto cards wallet conversions.
Open a Exchange crypto account, request pay-in addresses, register fiat external accounts, get ramp quotes and discover supported swap targets.
Use the dedicated Banking-to-Crypto cards or Banking-to-wallet initiate/confirm operations. Do not imitate them with a generic transfer.
Crypto virtual account
Open a crypto virtual account
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"Name": "Customer settlement",
"Providers": [
"boomfi"
],
"Chains": [
{
"ChainId": 1,
"Currencies": [
"USDC",
"USDT"
]
}
]
}'Example 201 responseJSON · collapse
{
"Success": true,
"Message": "string",
"Results": [
{
"Provider": "string",
"Status": "PENDING",
"Reference": "external_reference_123",
"Message": "string",
"VerificationUrl": "https://example.com/callback",
"Account": {
"id": 123,
"name": "string",
"address": "string",
"chain_id": 123,
"currencies": [
{}
],
"enabled": true,
"created_at": "2026-08-05T09:30:00Z"
},
"Wallets": [
{
"Id": 123,
"WalletAddress": "0x1111111111111111111111111111111111111111",
"CryptoAsset": "string",
"Status": "PENDING",
"ExternalWalletId": "external_reference_123",
"WalletType": "string"
}
]
}
]
}/api/v2/crypto-virtual-accounts/trading-overview/api/v2/crypto-virtual-accounts/swap-targets/api/v2/crypto-virtual-accounts/payin-address/api/v2/crypto-virtual-accounts/bank-address-book/api/v2/crypto-virtual-accounts/equals-to-wallet/initiate/api/v2/crypto-virtual-accounts/equals-to-wallet/confirmExternal withdrawal
- Show fee, quota and spendable balance from
GET /transfers/withdrawals/fee-and-quotaandGET /transfers/withdrawals/available-balance. - Validate currency, chain, amount and destination with
GET /transfers/withdrawals/validate. - Create the withdrawal. Expect HTTP
201,Status: "OTP_REQUIRED",OtpRequired: true, aWithdrawalRequestIdandOtpExpiresAt. This starts the challenge; it does not complete the withdrawal. - Show an OTP input and tell the customer the code was sent by email. Keep
WithdrawalRequestIdon your server and never accept it from an unrelated browser session. - Confirm through
POST /transfers/withdrawals/crypto/confirmwith the sameUserId, the returnedWithdrawalRequestId, and the customer'sOtpCode. - Treat HTTP
200or202as accepted, then reconcile usingTransactionIdandInterlaceTransferId. Continue tracking the returned status until it reaches a terminal state.
Step 1 — Create withdrawal and send OTP
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/withdrawals/crypto' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"Currency": "USDC",
"Chain": "ethereum",
"Amount": "50.00",
"DestinationAddress": "0x1111111111111111111111111111111111111111",
"ConfirmExchangeRate": true,
"Description": "Customer withdrawal",
"Metadata": {
"externalReferenceId": "withdrawal_9081"
}
}'Example 201 responseJSON · collapse
{
"Success": true,
"VerificationToken": "PLACEHOLDER_TOKEN",
"TransactionId": "string",
"InterlaceTransferId": "string",
"WithdrawalRequestId": 123,
"Status": "PENDING",
"ActualAmount": 100,
"Currency": "USD",
"Fees": [
{
"Amount": "100.00",
"Currency": "USD",
"Type": "string"
}
],
"Message": "string",
"OtpRequired": true,
"OtpExpiresAt": "2026-08-05T09:30:00Z"
}Step 2 — Confirm withdrawal with OTP
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/withdrawals/crypto/confirm' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"WithdrawalRequestId": 9081,
"VerificationToken": "TOKEN_FROM_WITHDRAWAL_INITIATION",
"OtpCode": "123456"
}'Example 200 responseJSON · collapse
{
"Success": true,
"VerificationToken": "PLACEHOLDER_TOKEN",
"TransactionId": "string",
"InterlaceTransferId": "string",
"WithdrawalRequestId": 123,
"Status": "PENDING",
"ActualAmount": 100,
"Currency": "USD",
"Fees": [
{
"Amount": "100.00",
"Currency": "USD",
"Type": "string"
}
],
"Message": "string",
"OtpRequired": true,
"OtpExpiresAt": "2026-08-05T09:30:00Z"
}Do not retry forever or use the banking OTP endpoints. Show the API error and restart the withdrawal challenge to obtain a new request ID and OTP.
This flow does not use /api/v2/banking/otp/verify or /resend. Crypto withdrawal confirmation has its own endpoint and request model.
Some previously provisioned programmes may return OtpRequired: false. That compatibility path is deprecated; never use it as the design for a new integration.
Do not create a second withdrawal after an ambiguous network timeout until you have reconciled the first request. Duplicate blockchain withdrawals cannot be reversed.
Token swap
Swap supported tokens
curl --request POST 'https://staging.hoppa.global/api/v2/swaptokens/swap' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"TokenIn": "USDC",
"TokenOut": "USDT",
"AmountIn": "100.00",
"Slippage": 0.5,
"ChainIdIn": 1,
"ChainIdOut": 1,
"FromAddress": "wallet_address_from_api",
"ToAddress": "wallet_address_from_api"
}'Example 200 responseJSON · collapse
{
"Transaction": {
"to": "string",
"data": "string",
"value": "string",
"abi": "string",
"args": [
{}
]
},
"Route": {
"query": {
"params": {
"chainIdIn": 1,
"chainIdOut": 1,
"tokenIn": "string",
"tokenOut": "string",
"amountIn": "100.00"
},
"slippage": 100,
"from": "string",
"recipient": "string"
},
"route": [
{
"pool": {
"lp": {
"chainId": {},
"address": {},
"name": {},
"symbol": {},
"decimals": {},
"tags": {},
"permit": {}
},
"decimals": [
{}
],
"coins": [
{}
],
"address": "string",
"underlyingCoins": [
{}
],
"type": "string"
},
"fees": [
{
"type": {},
"token": {},
"percent": {},
"amount": {}
}
],
"priceImpact": "string",
"params": {
"tokenIn": {
"chainId": {},
"address": {},
"name": {},
"symbol": {},
"decimals": {},
"chainName": {},
"originalName": {},
"originalSymbol": {},
"tags": {},
"synthTags": {},
"permit": {}
},
"chainIdIn": 1,
"tokenOut": {
"chainId": {},
"address": {},
"name": {},
"symbol": {},
"decimals": {},
"chainName": {},
"originalName": {},
"originalSymbol": {},
"tags": {},
"synthTags": {},
"permit": {}
},
"chainIdOut": 1,
"amountIn": "100.00",
"amountInWithoutSlippage": "100.00",
"amountOut": "100.00",
"amountOutWithoutSlippage": "100.00",
"slippage": 100
},
"type": "string",
"chainId": 123
}
],
"amountIn": "100.00",
"amountInWithoutSlippage": "100.00",
"amountOut": "100.00",
"amountOutWithoutSlippage": "100.00",
"tokenInPrice": 100,
"tokenOutPrice": 100,
"priceImpact": 100,
"totalFee": {
"type": "string",
"amount": "100.00",
"percent": "string"
},
"signature": "string"
},
"TransactionId": 123
}List previous swaps with GET /api/v2/swaptokens/history. The slippage value is a percentage; show it to the customer before submitting.
Implement exchange and cross-provider transfers through one HOPPA contract.
Your integration selects the customer, source balance, destination and amount. HOPPA coordinates the asynchronous workflow and exposes one transfer state for your application to follow.
From product selection to the first completed exchange.
Adding Exchange introduces its own verification, funding and settlement steps. Follow this order whether you use it alone or alongside Banking and Crypto cards.
- Enable Exchange and identify the customer
Confirm Exchange is enabled for your company programme and outgoing transfers are enabled before offering payment confirmation. Use one company-owned Hoppa user and keep x-api-key on your backend. Reuse this user when adding Banking or Crypto cards.
Open this step → - Complete Exchange verification
Read GET /api/v2/crypto-virtual-accounts/verification with userId. Follow the returned application, session or business verification action; supply authorisation, TIN or EDD only when requested. Banking or card approval does not establish Exchange approval. Complete account activation when requested after verification; reuse SumSub answers only when the application supports it. Submission alone is not approval.
Open verification guide → - Discover accounts and funding details
Read GET /api/v2/crypto-virtual-accounts/verification/settlement-accounts and GET /api/v2/crypto-virtual-accounts/trading-overview. An approved application can still be waiting for settlement accounts. Resolve a missing exchange account only when required and wait for provisioned details before offering deposits. Use returned account IDs, balances, currencies, networks and limits. Fund only the provisioned destination and reconcile receipt before spending.
Open this step → - Choose the route for your selected products
For direct exchange, request POST /api/v2/crypto-virtual-accounts/exchange/quote using the returned Exchange account IDs, show rate, fees, output and expiry, then accept the exact unexpired QuoteId after customer confirmation. For a connected transfer, use the matching source-and-destination workflow below instead of starting a second independent conversion.
Open this step → - Confirm and follow the workflow
Complete any OTP step and keep stable idempotency keys where documented. Store returned references and reconcile through the relevant status, transfer list and balances. When a transfer requires a new quote or funds decision, show the current terms and ask the customer. Never repeat a source transfer just because a webhook is late.
Open this step → - Reconcile before updating the app
HTTP success can mean accepted rather than settled. Refresh the destination balance and confirm the final result before showing funds as spendable. Read the documented response schema and status code; acknowledgement-only operations return no body. Test pending verification, expired quotes, failed funding and duplicate retries in staging.
Open this step →
Follow the Flutter implementation
Keep Flutter behind your backend
Flutter calls /api/v1/mobile/exchange on the example backend. That backend derives the Hoppa user ID from the authenticated session and calls /api/v2/crypto-virtual-accounts with the company API key. Do not put the key in Dart or accept another customer's user ID from the client.
Separate verification, activation and readiness
The app follows the verification action, offers account activation when needed, and can reuse supported SumSub answers with UseSumsubAnswers. It shows pending review and settlement-account preparation separately. Refresh state after an ambiguous submission instead of sending the application twice. Read the current contract before relying on response properties from the example app.
Fund from Banking with an exact destination
The Flutter funding screen refreshes budget balances, checks available currency and limits, and sends the explicit /equals-to-interlace/fund request with IdempotencyKey, SourceBudgetId, FiatCurrency, FiatAmount, CryptoCurrency, ChainId and DestinationAddress. Keep that key stable for retries. This is different from the original route's UserId, BudgetId and Amount body.
Review the quote and delivery before confirmation
The app checks supported currencies and exact networks, available balance, funding and withdrawal limits, and quote expiry. For supported card-wallet delivery it supplies InterlaceDestinationAddress on the quote; it can also include BankWithdrawal for bank delivery. Changing the destination or amount requires a fresh review. Customer confirmation must precede acceptance; block duplicate submissions and disabled outflows, then refresh transfers and balances.
How Exchange fits your setup
Use provisioned funding rails and Exchange account IDs for direct quote/accept and supported payouts. You do not need to order a card or open a Banking budget for this flow. Only expose currencies, networks and actions supported by the customer's returned account state and company programme.
Follow this route →Complete Banking onboarding and select the approved source budget. For Banking → external wallet, use equals-to-wallet/initiate then /confirm with the documented OTP flow. For direct Exchange conversion, use the provisioned funding details and quote/accept flow. Crypto cards is needed only when a route uses its wallet or card resources.
Follow this route →Complete Crypto cards onboarding as well as Exchange verification. Direct quote/accept uses Exchange balances; a Crypto cards wallet balance is separate. For supported fiat-to-crypto delivery, the Flutter app includes InterlaceDestinationAddress on the quote after matching the Crypto cards wallet currency and network. Review and accept that quote; do not add a duplicate payout. Separate crypto withdrawals use payout-address. Fund the card through its normal card-funding flow. Banking transfer routes additionally require Banking.
Follow this route →After all three approvals, select the Banking budget and Crypto cards currency, network and address. The Flutter app funds this route with equals-to-interlace/fund. The original equals-to-interlace route remains available with a different body. For the reverse direction, use interlace-to-equals/initiate then /confirm. Keep all resource and workflow IDs separate.
Follow this route →Complete Exchange verification and activate the account
Use the same company-owned Hoppa user throughout this flow. Banking or Crypto cards approval does not approve Exchange.
1. Read the current state
Check verificationType, eligible, status and provider. For individuals, complete the existing Hoppa identity verification before starting Exchange. For businesses, follow the business branch below.
Read Exchange verification
curl --request GET 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/verification?userId=123' \
-H 'X-API-Key: YOUR_API_KEY'Example 200 responseJSON · collapse
{
"tier": "sdd",
"status": "approved",
"eligible": true,
"hasProviderAccount": true,
"usesSharedStagingOrganization": false,
"verificationType": "individual",
"provider": {
"status": "ready",
"kycStatus": "accepted",
"nextAction": null,
"verificationUrl": null,
"reason": null,
"actionSubmitted": false,
"cryptoDepositAccountReady": true,
"eurAccountReady": true
},
"applicationSupported": true,
"applicationUnavailableReason": null,
"businessOnboardingSupported": false
}2. Start or resume the appropriate verification
Choose sdd or cdd for an individual, according to the required programme limits. Open verificationUrl when returned. A null URL can mean there is no hosted action to perform; use the returned status and poll the state endpoint.
Start individual Exchange verification
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/verification/session?userId=123' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Tier": "sdd"
}'Example 200 responseJSON · collapse
{
"tier": "sdd",
"status": "in_progress",
"verificationUrl": "https://verify.example.com/session"
}3. Review and submit the personal application
After verification approval, read supported, answers, kycLevel, missingFields and readyToSubmit. Resolve missing declarations. To reuse the approved Exchange SumSub questionnaire, send an empty Answers object with UseSumsubAnswers: true. For manual submission, use the documented field IDs and string option values.
Review the Exchange application
curl --request GET 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/verification/application?userId=123' \
-H 'X-API-Key: YOUR_API_KEY'Example 200 responseJSON · collapse
{
"supported": true,
"message": null,
"answers": {
"sdd_country_select": "GB",
"investment_citizenship": "81",
"employment_type_or_status": "15",
"industry": "20",
"employment_jurisdiction": "GB",
"acting_capacity": "156"
},
"kycLevel": "SDD",
"missingFields": [],
"readyToSubmit": true
}Activate Exchange using approved SumSub answers
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/verification/application?userId=123' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Answers": {},
"UseSumsubAnswers": true
}'Example 200 responseJSON · collapse
{
"tier": "sdd",
"status": "approved",
"eligible": true,
"hasProviderAccount": true,
"usesSharedStagingOrganization": false,
"verificationType": "individual",
"provider": {
"status": "ready",
"kycStatus": "accepted",
"nextAction": null,
"verificationUrl": null,
"reason": null,
"actionSubmitted": false,
"cryptoDepositAccountReady": true,
"eurAccountReady": true
},
"applicationSupported": true,
"applicationUnavailableReason": null,
"businessOnboardingSupported": false
}Business accounts
Use GET /verification/business to review the business details and issues, then POST /verification/business to start provider-hosted verification. These paths share the /api/v2/crypto-virtual-accounts prefix. If the response is authorisation_required, send and confirm the business authorisation code before retrying. Personal application answers cannot be submitted for a business. The separate session endpoint accepts kyb for business verification.
Business request and response schemas →
4. Follow the next action and confirm readiness
Refresh verification after submission. Supply TIN or EDD only when provider.nextAction requests it. Submission is not approval: provider KYC must be accepted and the required settlement accounts must be provisioned before trading or deposits.
Read the customer's accounts after verification
Read the returned account IDs, currencies, balances, chains, deposit addresses and pending workflows. Use these returned IDs in subsequent requests; do not guess an account from its position or reuse another customer's ID.
Load exchange accounts, balances and workflows
curl --request GET 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/trading-overview?userId=123' \
-H 'X-API-Key: YOUR_API_KEY'Example 200 responseJSON · collapse
{
"fiat_funding_fees_and_limits": {},
"restricted_trading_currencies": [
"string"
],
"deposits": [
{
"Id": 123,
"PaymentId": "string",
"Amount": "100.00",
"Currency": "USD",
"ChainId": 123,
"Status": "PENDING",
"ProviderStatus": "PENDING",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"TransactionHash": "string",
"ActionUrl": "https://example.com/callback",
"SettlementTransactionHash": "",
"PaymentMethod": "Deposit"
}
],
"payments": [
{
"Id": 123,
"PaymentId": "string",
"Amount": "100.00",
"Currency": "USD",
"ChainId": 123,
"Status": "PENDING",
"ProviderStatus": "PENDING",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"TransactionHash": "string",
"ActionUrl": "https://example.com/callback",
"SettlementTransactionHash": "",
"PaymentMethod": "Deposit"
}
],
"account": {
"fees_and_limits": {},
"id": 123,
"reference": "external_reference_123",
"name": "string",
"account_type": "string",
"enabled": true,
"state": "string",
"sub_accounts": [
{
"fees_and_limits": {},
"id": 123,
"chain_id": 123,
"address": "string",
"chain": {
"id": {},
"name": {},
"native_currency_symbol": {}
},
"state": "string",
"status": "PENDING"
}
]
},
"balances": {
"balances": [
{
"fees_and_limits": {},
"account_id": 123,
"chain": {
"id": {},
"name": {},
"native_currency_symbol": {}
},
"currency": "USD",
"token_address": "string",
"amount": "100.00",
"amount_billing_currency": "USD",
"pending_amount": "100.00",
"pending_amount_billing_currency": "USD"
}
],
"total_balance": "100.00"
},
"currencies": {
"FIELD_FROM_APPLICATION": {
"symbol": "string",
"name": "string",
"type": "string",
"tokens": [
{
"chain_id": 123,
"address": "string",
"name": "string"
}
]
}
},
"settlement_accounts": [
{
"id": 123,
"name": "string",
"currency": "USD",
"bank_name": "string",
"account_number": "string",
"account_number_hint": "string",
"account_holder_name": "string",
"country": "GB",
"enabled": true,
"state": "string",
"status": "PENDING"
}
],
"fiat_funding_currencies": [
"string"
]
}/api/v2/crypto-virtual-accounts/trading-overview?userId={userId}/api/v2/crypto-virtual-accounts/api/v2/crypto-virtual-accounts/payin-address/api/v2/crypto-virtual-accounts/transfers?userId={userId}Direct fiat ↔ crypto exchange
For crypto-to-fiat, the crypto balance is the sell account and the fiat balance is the buy account. Reverse them for fiat-to-crypto. A quote is immutable and expires; if any input changes or it expires, request a new quote.
Step 1 — Request an exact exchange quote
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/exchange/quote' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"SellCurrency": "USDC",
"BuyCurrency": "EUR",
"SellAmount": "5.00",
"DepositAccountId": 3,
"SettlementAccountId": 4,
"SellChainId": 1,
"SellTokenAddress": "0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}'Example 200 responseJSON · collapse
{
"buy_currency": "USD",
"buy_amount": "100.00",
"sell_currency": "USD",
"sell_amount": "100.00",
"payment_method": "string",
"quote_time": "2026-08-05T09:30:00Z",
"expiry": "2026-08-05T09:30:00Z",
"rate": "string",
"fees": {
"fee_ccy": "100.00",
"network_fee": "100.00",
"boomfi_fee": "100.00",
"total_fee": "100.00"
},
"quote_amount": "100.00",
"settlement_ccy": "string",
"settlement_chain_id": 123,
"settlement_token_address": "string",
"session": "string"
}Step 2 — Accept the displayed quote
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/exchange/accept' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"QuoteId": "quote_from_previous_response"
}'Example 200 responseJSON · collapse
{}Explicit funding and payouts
Choose the destination and route before confirmation. Funding from Banking uses POST /equals-to-interlace/fund with userId in the query and IdempotencyKey, SourceBudgetId, FiatCurrency, FiatAmount, CryptoCurrency, ChainId and DestinationAddress in the body. Keep the same idempotency key for retries.
Use POST /payout-address for a crypto destination and POST /payout-fiat for a bank destination. All three routes share the /api/v2/crypto-virtual-accounts prefix. Read supported currencies, networks and limits from the customer’s trading overview. Payout replies are provider-defined JSON; do not infer completion from HTTP success.
Funding contract → · Crypto payout contract → · Fiat payout contract →
Crypto cards → Banking
This route requires Crypto cards, Banking and Exchange approval. The customer chooses a Crypto cards crypto wallet and a Banking destination budget. The initiate call returns an indicative rate, fee, funding address and OTP challenge. The confirm call authorises the source withdrawal and returns the workflow to monitor.
Step 1 — Initiate Crypto cards to Banking
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/interlace-to-equals/initiate' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"Reference": "customer-order-1042-001",
"BoomFiAccountId": "3",
"Currency": "USDC",
"CryptoAmount": "5.00",
"ChainId": 1,
"FiatCurrency": "EUR",
"TargetBudgetId": "equals_budget_from_banking_api"
}'Example 200 responseJSON · collapse
{
"Success": true,
"VerificationToken": "PLACEHOLDER_TOKEN",
"Message": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"DepositAddress": "string",
"DepositWallet": {},
"IndicativeQuote": {
"buy_currency": "USD",
"buy_amount": "100.00",
"sell_currency": "USD",
"sell_amount": "100.00",
"payment_method": "string",
"quote_time": "2026-08-05T09:30:00Z",
"expiry": "2026-08-05T09:30:00Z",
"rate": "string",
"fees": {
"fee_ccy": "100.00",
"network_fee": "100.00",
"boomfi_fee": "100.00",
"total_fee": "100.00"
},
"quote_amount": "100.00",
"settlement_ccy": "string",
"settlement_chain_id": 123,
"settlement_token_address": "string",
"session": "string"
},
"AutoExecutionTolerancePercent": 100,
"ExchangeRateNotice": "string"
}Step 2 — Confirm with the customer OTP
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/interlace-to-equals/confirm' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"VerificationToken": "verification_token_from_initiate",
"OtpCode": "123456"
}'Example 200 responseJSON · collapse
{
"Success": true,
"Message": "string",
"TransferId": "string",
"TransferStatus": "PENDING",
"TargetBudgetId": "string",
"DepositWallet": {},
"OtcRequest": {
"BoomFiDepositPaymentId": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"DestinationCryptoAddress": "0x1111111111111111111111111111111111111111",
"Id": 123,
"Status": "PENDING",
"BoomFiVirtualAccountId": "string",
"CryptoCurrency": "USDC",
"CryptoAmount": "100.00",
"ChainId": 123,
"FiatCurrency": "USD",
"BoomFiOrderId": "string",
"BoomFiQuoteId": "string",
"BoomFiOrderStatus": "PENDING",
"BoomFiSettlementStatus": "PENDING",
"ToAmount": "100.00",
"EffectiveRate": "string",
"FailureMessage": "string",
"SlackChannelId": "string",
"SlackThreadTs": "string",
"SlackPermalink": "string",
"CompletedAt": "2026-08-05T09:30:00Z",
"CompletionMessage": "string",
"TransferDirection": "string",
"InitialExchangeRate": "string",
"InitialFeeAmount": "100.00",
"InitialFeeCurrency": "USD",
"CurrentFeeAmount": "100.00",
"CurrentFeeCurrency": "USD",
"RateDeviationPercent": 100,
"AutoExecutionTolerancePercent": 100,
"QuoteDecisionStatus": "PENDING",
"QuoteExpiresAt": "2026-08-05T09:30:00Z",
"FundsDecision": "string",
"ReturnFeeAmount": "100.00",
"ReturnFeeCurrency": "USD",
"SourceTransferId": "string",
"NextAction": "string",
"ActionUrl": "https://example.com/callback",
"FiatSettledAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalDeadlineAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalOverdue": true
}
}Banking → Crypto cards
This route requires Banking, Crypto cards and Exchange approval. The customer chooses the Banking source budget, fiat currency and amount. HOPPA resolves that same user's Crypto cards USDC destination. Use a stable idempotency key for the business transfer and reuse it after an ambiguous timeout.
Fund the customer’s Crypto cards wallet from Banking
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/equals-to-interlace' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"IdempotencyKey": "equals-to-interlace-customer-123-001",
"UserId": 123,
"FiatCurrency": "GBP",
"Amount": 250,
"BudgetId": "equals_budget_from_banking_api"
}'Example 200 responseJSON · collapse
{
"Success": true,
"Message": "string",
"Reference": "external_reference_123",
"UserId": 123,
"BudgetId": "string",
"FiatCurrency": "USD",
"FiatAmount": "100.00",
"CryptoCurrency": "USDC",
"EstimatedCryptoAmount": "100.00",
"EstimatedFeeAmount": "100.00",
"Rate": "string",
"ChainId": 123,
"Chain": "string",
"DepositAddress": "string",
"BoomFiPayout": {}
}Explicit-destination funding
Use the separate /fund contract when selecting the currency, network and destination explicitly. The user ID is a query parameter; use SourceBudgetId and FiatAmount in the body. Copy the destination from this customer’s provisioned settlement details.
Fund an explicit exchange destination
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/equals-to-interlace/fund?userId=123' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"IdempotencyKey": "exchange-fund-1042-001",
"SourceBudgetId": "budget_from_banking_api",
"FiatCurrency": "EUR",
"FiatAmount": 100,
"CryptoCurrency": "USDC",
"ChainId": 1,
"DestinationAddress": "address_from_settlement_accounts"
}'Example 200 responseJSON · collapse
{
"Success": true,
"Message": "string",
"EqualsPaymentId": "string",
"IndicativeQuote": {
"buy_currency": "USD",
"buy_amount": "100.00",
"sell_currency": "USD",
"sell_amount": "100.00",
"payment_method": "string",
"quote_time": "2026-08-05T09:30:00Z",
"expiry": "2026-08-05T09:30:00Z",
"rate": "string",
"fees": {
"fee_ccy": "100.00",
"network_fee": "100.00",
"boomfi_fee": "100.00",
"total_fee": "100.00"
},
"quote_amount": "100.00",
"settlement_ccy": "string",
"settlement_chain_id": 123,
"settlement_token_address": "string",
"session": "string"
},
"Transfer": {
"BoomFiDepositPaymentId": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"DestinationCryptoAddress": "0x1111111111111111111111111111111111111111",
"Id": 123,
"Status": "PENDING",
"BoomFiVirtualAccountId": "string",
"CryptoCurrency": "USDC",
"CryptoAmount": "100.00",
"ChainId": 123,
"FiatCurrency": "USD",
"BoomFiOrderId": "string",
"BoomFiQuoteId": "string",
"BoomFiOrderStatus": "PENDING",
"BoomFiSettlementStatus": "PENDING",
"ToAmount": "100.00",
"EffectiveRate": "string",
"FailureMessage": "string",
"SlackChannelId": "string",
"SlackThreadTs": "string",
"SlackPermalink": "string",
"CompletedAt": "2026-08-05T09:30:00Z",
"CompletionMessage": "string",
"TransferDirection": "string",
"InitialExchangeRate": "string",
"InitialFeeAmount": "100.00",
"InitialFeeCurrency": "USD",
"CurrentFeeAmount": "100.00",
"CurrentFeeCurrency": "USD",
"RateDeviationPercent": 100,
"AutoExecutionTolerancePercent": 100,
"QuoteDecisionStatus": "PENDING",
"QuoteExpiresAt": "2026-08-05T09:30:00Z",
"FundsDecision": "string",
"ReturnFeeAmount": "100.00",
"ReturnFeeCurrency": "USD",
"SourceTransferId": "string",
"NextAction": "string",
"ActionUrl": "https://example.com/callback",
"FiatSettledAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalDeadlineAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalOverdue": true
},
"AutoExecutionTolerancePercent": 100
}The published response schema is unspecified. Confirm the actual response contract before implementing automated status parsing.
Track quote changes and customer decisions
Each multi-step request stores its original rate and fee. If the executable rate stays within ±0.5%, the workflow continues automatically. A larger move enters awaiting_quote_approval; show the replacement rate, fee, output and expiry before asking the customer.
List the customer’s exchange transfers
curl --request GET 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/transfers?userId=123' \
-H 'X-API-Key: YOUR_API_KEY'Example 200 responseJSON · collapse
[
{
"BoomFiDepositPaymentId": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"DestinationCryptoAddress": "0x1111111111111111111111111111111111111111",
"Id": 123,
"Status": "PENDING",
"BoomFiVirtualAccountId": "string",
"CryptoCurrency": "USDC",
"CryptoAmount": "100.00",
"ChainId": 123,
"FiatCurrency": "USD",
"BoomFiOrderId": "string",
"BoomFiQuoteId": "string",
"BoomFiOrderStatus": "PENDING",
"BoomFiSettlementStatus": "PENDING",
"ToAmount": "100.00",
"EffectiveRate": "string",
"FailureMessage": "string",
"SlackChannelId": "string",
"SlackThreadTs": "string",
"SlackPermalink": "string",
"CompletedAt": "2026-08-05T09:30:00Z",
"CompletionMessage": "string",
"TransferDirection": "string",
"InitialExchangeRate": "string",
"InitialFeeAmount": "100.00",
"InitialFeeCurrency": "USD",
"CurrentFeeAmount": "100.00",
"CurrentFeeCurrency": "USD",
"RateDeviationPercent": 100,
"AutoExecutionTolerancePercent": 100,
"QuoteDecisionStatus": "PENDING",
"QuoteExpiresAt": "2026-08-05T09:30:00Z",
"FundsDecision": "string",
"ReturnFeeAmount": "100.00",
"ReturnFeeCurrency": "USD",
"SourceTransferId": "string",
"NextAction": "string",
"ActionUrl": "https://example.com/callback",
"FiatSettledAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalDeadlineAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalOverdue": true
}
]Read one transfer and its latest quote
curl --request GET 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/transfers/301?userId=123' \
-H 'X-API-Key: YOUR_API_KEY'Example 200 responseJSON · collapse
{
"BoomFiDepositPaymentId": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"DestinationCryptoAddress": "0x1111111111111111111111111111111111111111",
"Id": 123,
"Status": "PENDING",
"BoomFiVirtualAccountId": "string",
"CryptoCurrency": "USDC",
"CryptoAmount": "100.00",
"ChainId": 123,
"FiatCurrency": "USD",
"BoomFiOrderId": "string",
"BoomFiQuoteId": "string",
"BoomFiOrderStatus": "PENDING",
"BoomFiSettlementStatus": "PENDING",
"ToAmount": "100.00",
"EffectiveRate": "string",
"FailureMessage": "string",
"SlackChannelId": "string",
"SlackThreadTs": "string",
"SlackPermalink": "string",
"CompletedAt": "2026-08-05T09:30:00Z",
"CompletionMessage": "string",
"TransferDirection": "string",
"InitialExchangeRate": "string",
"InitialFeeAmount": "100.00",
"InitialFeeCurrency": "USD",
"CurrentFeeAmount": "100.00",
"CurrentFeeCurrency": "USD",
"RateDeviationPercent": 100,
"AutoExecutionTolerancePercent": 100,
"QuoteDecisionStatus": "PENDING",
"QuoteExpiresAt": "2026-08-05T09:30:00Z",
"FundsDecision": "string",
"ReturnFeeAmount": "100.00",
"ReturnFeeCurrency": "USD",
"SourceTransferId": "string",
"NextAction": "string",
"ActionUrl": "https://example.com/callback",
"FiatSettledAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalDeadlineAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalOverdue": true
}Approve the replacement quote
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/transfers/{transferId}/decision' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"Decision": "approve"
}'Example 200 responseJSON · collapse
{
"BoomFiDepositPaymentId": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"DestinationCryptoAddress": "0x1111111111111111111111111111111111111111",
"Id": 123,
"Status": "PENDING",
"BoomFiVirtualAccountId": "string",
"CryptoCurrency": "USDC",
"CryptoAmount": "100.00",
"ChainId": 123,
"FiatCurrency": "USD",
"BoomFiOrderId": "string",
"BoomFiQuoteId": "string",
"BoomFiOrderStatus": "PENDING",
"BoomFiSettlementStatus": "PENDING",
"ToAmount": "100.00",
"EffectiveRate": "string",
"FailureMessage": "string",
"SlackChannelId": "string",
"SlackThreadTs": "string",
"SlackPermalink": "string",
"CompletedAt": "2026-08-05T09:30:00Z",
"CompletionMessage": "string",
"TransferDirection": "string",
"InitialExchangeRate": "string",
"InitialFeeAmount": "100.00",
"InitialFeeCurrency": "USD",
"CurrentFeeAmount": "100.00",
"CurrentFeeCurrency": "USD",
"RateDeviationPercent": 100,
"AutoExecutionTolerancePercent": 100,
"QuoteDecisionStatus": "PENDING",
"QuoteExpiresAt": "2026-08-05T09:30:00Z",
"FundsDecision": "string",
"ReturnFeeAmount": "100.00",
"ReturnFeeCurrency": "USD",
"SourceTransferId": "string",
"NextAction": "string",
"ActionUrl": "https://example.com/callback",
"FiatSettledAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalDeadlineAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalOverdue": true
}approveAccept the displayed replacement quote before its expiry and continue the conversion.
declineReject the changed quote. The workflow waits for the customer's funds decision.
keepAfter decline, leave funds in the customer's exchange balance for a later action.
returnAfter decline, request return to the recorded source. Display returned network/provider costs before confirmation.
Bring your integration up to date.
The guide and catalogue now use the current staging OpenAPI contract. Review these workflow changes when upgrading an existing integration.
Crypto Exchange verification and settlement accounts
Before funding or trading, read the user’s exchange verification state and follow the action it requests. The published contract now exposes application read/submit, session creation, business verification, business authorisation code delivery/confirmation, tax identification (TIN), enhanced due diligence (EDD), and provisioned settlement accounts. Send the company-owned userId in the query with company API-key requests. Application answers are a dictionary and UseSumsubAnswers is optional. Required nullable TIN/EDD fields must still be present: null and an omitted field are different. The request and response schemas now document the application draft, verification status and session URL. Use tier sdd or cdd for individuals, or kyb for business. To reuse approved SumSub answers, send Answers: {} with UseSumsubAnswers: true. Read provisioned addresses and bank details from settlement-accounts; submission alone does not establish approval.
GET /api/v2/crypto-virtual-accounts/verificationGET /api/v2/crypto-virtual-accounts/verification/applicationPOST /api/v2/crypto-virtual-accounts/verification/applicationPOST /api/v2/crypto-virtual-accounts/verification/sessionGET /api/v2/crypto-virtual-accounts/verification/businessPOST /api/v2/crypto-virtual-accounts/verification/businessPOST /api/v2/crypto-virtual-accounts/verification/business/authorisation/send-codePOST /api/v2/crypto-virtual-accounts/verification/business/authorisationPOST /api/v2/crypto-virtual-accounts/verification/tinPOST /api/v2/crypto-virtual-accounts/verification/eddGET /api/v2/crypto-virtual-accounts/verification/settlement-accounts
Explicit exchange funding, crypto payouts and fiat payouts
POST /api/v2/crypto-virtual-accounts/equals-to-interlace/fund is a separate explicit-destination contract: userId is in the query, and the JSON uses IdempotencyKey, SourceBudgetId, FiatCurrency, FiatAmount, CryptoCurrency, ChainId and DestinationAddress. Its IdempotencyKey must be 8–128 characters. The original Banking-to-Crypto cards route remains available with its original UserId, BudgetId and Amount fields; do not mix the two request shapes. Crypto payouts use payout-address with Amount, Ccy and WalletAddress plus the selected network. Fiat payouts use payout-fiat and can refer to an ExternalAccountId. Register crypto destinations through crypto-address-book using lowercase name, currency, chain_id and address. Quote requests also expose InterlaceDestinationAddress and BankWithdrawal.ExternalAccountId. Trading overview adds deposits, payments, restricted_trading_currencies and fiat_funding_fees_and_limits; read current limits before presenting actions. Funding now has a typed response contract. Payouts return provider-defined JSON; do not assume a transfer ID or settlement status field without checking the returned payload.
POST /api/v2/crypto-virtual-accounts/equals-to-interlace/fundPOST /api/v2/crypto-virtual-accounts/equals-to-interlacePOST /api/v2/crypto-virtual-accounts/payout-addressPOST /api/v2/crypto-virtual-accounts/payout-fiatPOST /api/v2/crypto-virtual-accounts/crypto-address-bookPOST /api/v2/crypto-virtual-accounts/exchange/quoteGET /api/v2/crypto-virtual-accounts/trading-overview
Business onboarding tier, assessment and payment workflow
The new /api/v2/business-onboarding workflow complements the existing /api/v2/business/onboarding KYB application and evidence routes. Read workflow state, choose a returned tier with TierId, and use the assessment and payment actions only when appropriate for that state. Company API-key callers must supply the target business userId in the query. Checkout takes a payment UUID and TermsAccepted; invoice retrieval uses the payment UUID. Workflow status, tier selection and checkout now have response schemas; assessment returns HTTP 202 with status ASSESSMENT_PENDING and invoices return PDF content. Do not invent response properties or infer completion from HTTP success; reconcile through the workflow read endpoint. The /api/v2/admin/business-onboarding routes are separately restricted by AdminAccess in the implementation; appearing in Scalar does not grant integration API keys administrator access.
GET /api/v2/business-onboardingPOST /api/v2/business-onboarding/tierPOST /api/v2/business-onboarding/assessPOST /api/v2/business-onboarding/payments/{paymentId}/checkoutGET /api/v2/business-onboarding/payments/{paymentId}/invoiceGET /api/v2/business/onboarding/options
MOR retry protection, pagination and response casing
The current published MOR contract now documents optional Idempotency-Key on POST mutations. Strongly prefer one stable key per company/business action; retries must preserve method, path, query, content type and body. Completed results replay the original status/body, including partial success and errors. A changed request produces IDEMPOTENCY_KEY_CONFLICT; an unresolved operation produces IDEMPOTENCY_OUTCOME_PENDING. Reconcile pending outcomes rather than changing keys. LabelPrefix is not deduplication. Cards/page provides bounded pages (default 25, maximum 100) with stored balances. Success and business-error properties are camelCase; validation/authentication/rate-limit errors can use other formats. Merchant and assigned-card transactions expose recorded fee fields; a null fee is not zero. New outbound events cover card assignment, unassignment, load requests and KYB updates.
GET /api/v2/mor/public/cards/pagePOST /api/v2/mor/public/cards/{cardId}/loadPOST /api/v2/mor/public/cards/{cardId}/unloadGET /api/v2/mor/public/transactionsPOST /webhooks/outbound/mor.card.assignedPOST /webhooks/outbound/mor.card.unassignedPOST /webhooks/outbound/mor.kyb.updated
Cost reporting, customer nationality and referral policy fields
POST /api/v2/reporting/costs accepts From and To timestamps plus required nullable ExcludedUserIds. Its response separates currencies and includes Complete: do not treat incomplete coverage as zero cost or combine currency totals without conversion. GET users/{userId} now includes Nationality from the linked Sumsub applicant with saved-profile fallback; nationality differs from address country. Referral community policy responses add DirectRewardBps, AvailableCommunityBps and HasTopupMargin; use the returned policy instead of assuming available reward margin.
POST /api/v2/reporting/costsGET /api/v2/users/{userId}
Personal onboarding and KYC before ordering cards
Create a personal user, start one KYC entry flow (hosted URL, SDK, reusable SumSub or manual evidence), and poll detailed KYC status. Require the relevant provider's approval, not only a generic KYC flag. Crypto cards accounts are created with the user when Crypto cards is the company default; use the /api/v2/users/create-interlace-account/{userId} repair route when needed. Banking requires its personal onboarding application and approved account/budget. Then discover a tier and card product and order the card. Never invent IDs or assume provider approvals are interchangeable.
POST /api/v2/usersPOST /api/v2/users/{userId}/sumsub/kyc-urlGET /api/v2/users/{userId}/kyc/detailed-statusPOST /api/v2/banking/equalsmoney-onboardingGET /api/v2/tiersGET /api/v2/tiers/card-tier/{cardTierId}POST /api/v2/cards
Issue or order a virtual card
Complete user/provider onboarding first, list tiers, assign the selected tier and read its card products. BankProviderType identifies Crypto cards (1) and Banking (2) for the card providers covered here. POST /api/v2/cards requires UserId, CardTypeId and Phone. BudgetId is required for Banking; obtain it from the user's budgets rather than inventing one. Use the local returned card Id for later controls. Physical cards also require their documented delivery fields; check fee quotes and supported shipping first. Read current status after creation and never treat a pending provider action as complete.
GET /api/v2/tiersPOST /api/v2/users/{userId}/tierGET /api/v2/tiers/card-tier/{cardTierId}GET /api/v2/banking/users/{userId}/budgetsPOST /api/v2/cardsGET /api/v2/cards/{cardId}
Public API authentication and scope
Use x-api-key from a trusted backend; the key supplies company scope. Pass the target userId when required. Dashboard JWT, /Users/Me, self-service onboarding and loyalty administration are outside the current public OpenAPI contract. Absence from this contract does not mean the dashboard feature was deleted. Outbound webhook entries describe requests Hoppa sends to your receiver; never call those paths on Hoppa.
KYC, business KYB and additional information
KYC requests accept Nationality and Ssn. Effective US/USA nationality requires exactly nine SSN digits. Use the business options endpoint for canonical IndustryMain, IndustrySub and EmployeeCount values; employee count is an enum string, not a number. Banking RFI supports text responses with optional AssociatedPersonId and batches of up to ten PDF, JPEG or PNG files. Business onboarding also has compliance read, requirements, draft and submission operations.
GET /api/v2/business/onboarding/optionsPOST /api/v2/users/{userId}/kyc/equalsmoney/informationPOST /api/v2/users/{userId}/kyc/equalsmoney/documentsPOST /api/v2/business/onboarding/compliance
Card auto top-up and Auto Lock
Read current settings and current-month usage before editing. Low-balance, failed-transaction and deposit modes are mutually exclusive on a card. Enabling requires explicit DisclaimerAccepted. Deposit mode supports USDC/USDT on Crypto cards, updates only supplied currencies, and allows each currency on only one card per user. Pass userId on every auto-top-up request. Auto Lock now has explicit enable/disable POST routes in addition to the existing PUT route.
GET /api/v2/cards/{cardId}/auto-topupPOST /api/v2/cards/auto-topup/low-balancePOST /api/v2/cards/auto-topup/failed-txPOST /api/v2/cards/auto-topup/depositPOST /api/v2/cards/{cardId}/auto-lock/enablePOST /api/v2/cards/{cardId}/auto-lock/disable
Crypto Exchange quotes, funding and decisions
The Crypto Exchange group keeps the /api/v2/crypto-virtual-accounts prefix. Discover account IDs through trading-overview, request an exact exchange quote and accept its identifier before expiry. Crypto cards-to-Banking supports quote, initiate and confirm. Banking-to-Crypto cards requires a stable IdempotencyKey in the JSON body, uses Exchange funding and webhook-driven re-quoting, and requests user approval for moves beyond ±0.5%. Track the returned transfer and submit decisions only when its state requires them. External accounts and bank address-book routes replace assumptions based on the old settlement-account and swap-quote entries.
GET /api/v2/crypto-virtual-accounts/trading-overviewPOST /api/v2/crypto-virtual-accounts/exchange/quotePOST /api/v2/crypto-virtual-accounts/exchange/acceptPOST /api/v2/crypto-virtual-accounts/equals-to-interlaceGET /api/v2/crypto-virtual-accounts/transfers/{id}POST /api/v2/crypto-virtual-accounts/transfers/{transferId}/decision
Banking payment approval
Read approval capabilities for the target user. Email OTP remains the baseline; native device and browser passkey approval depend on programme enablement, enrollment and client readiness. Pass userId with company API-key requests. Send the selected ApprovalDeviceId or ApprovalPasskeyId at initiation. Enroll first, verify the issued challenge through the matching approval endpoint, then complete the original payee/payout action. An active approval must be cancelled before changing to email fallback. Keep the stored quote and terms; changed or expired terms require renewed initiation and approval. A pending execution must be reconciled, not recreated.
GET /api/v2/banking/approvals/capabilitiesPOST /api/v2/banking/approvals/devices/enrollPOST /api/v2/banking/approvals/verifyPOST /api/v2/banking/approvals/passkeys/enrollPOST /api/v2/banking/approvals/passkeys/verifyDELETE /api/v2/banking/approvals/{verificationToken}
MOR discovery and card lifecycle
All public MOR operations require MOR enablement on the API key’s company. Discover products with GET /api/v2/mor/public/cards/available before selecting CardTypeId. Simple-user creation now requires Phone. The public surface also exposes company provisioning and merchant tiers, merchant transactions, card analytics, unassignment, cancellation, assigned-user card transactions and load requests. Use these MOR routes for MOR resources; the core card DELETE guidance does not replace the MOR cancel operation.
GET /api/v2/mor/public/cards/availablePOST /api/v2/mor/public/usersPOST /api/v2/mor/public/cards/{cardId}/unassignPOST /api/v2/mor/public/cards/{cardId}/cancelPOST /api/v2/mor/public/users/{userId}/cards/{cardId}/load-requests
Crypto withdrawal verification and resends
Initiate the withdrawal, keep the returned VerificationToken and WithdrawalRequestId, and send VerificationToken with OtpCode to confirm. The contract also provides a resend endpoint. Handle RemainingAttempts, IsExpired and IsLocked; a 202 response means processing remains asynchronous. Reconcile uncertain outcomes before initiating another irreversible withdrawal.
POST /api/v2/transfers/withdrawals/cryptoPOST /api/v2/transfers/withdrawals/crypto/confirmPOST /api/v2/transfers/withdrawals/crypto/resend
Referral programmes and customer attribution
The current contract includes programme versions/drafts/publishing, capabilities, geographic and risk policies, member and level lifecycle, links, invitations, attribution commands, community earnings, vouchers, reviews, bulk jobs and reporting. Read capabilities/options before presenting actions; do not infer that a programme supports every operation. Link edits use PATCH. Use preview/simulation operations before committing supported programme changes.
GET /api/v2/referrals/capabilitiesGET /api/v2/referrals/optionsPATCH /api/v2/referrals/links/{linkId}PATCH /api/v2/users/{userId}/referrals/links/{linkId}POST /api/v2/referrals/programs/{programId}/simulate
Webhook delivery and fee events
Verify X-Hoppacard-Signature as lowercase-hex HMAC-SHA256 over the exact raw request body using your webhook secret. Return 2xx after durable acceptance and deduplicate webhook identifiers. Network failures, timeouts, 408, 429 and 5xx are retried up to fifteen times after the initial delivery over approximately 76 hours. Other 4xx responses are permanent failures. This update highlights fee.charged and kyc.resubmission_required; the full webhook index includes all documented events and payloads.
POST /webhooks/outbound/fee.chargedPOST /webhooks/outbound/kyc.resubmission_required
Account linking, prices and authorization
The public contract also adds account-claim challenges and verification, account-link scan/exchange/status, price lookup and conversion, discount-code validation, Banking deposit tracking, and real-time authorization configuration, capabilities, BINs, cards, rules and decisions. Availability is programme-specific; read capabilities before enabling controls. Consult each current schema for required values and ownership constraints.
POST /api/v2/users/account-claim/challengesPOST /api/v2/users/account-links/scanGET /api/v2/pricesGET /api/v2/authorization/capabilitiesPOST /api/v2/discount-codes/validate
Add product modules without changing the core customer ID.
These modules reuse your company-scoped API key and Hoppa resources, but they have separate lifecycles. Enable only the modules included in your commercial programme.
Create hosted payment requests, recurring mandates, payouts and withdrawals. Persist the returned ID and status.
/api/v2/payments/*Complete merchant KYB, create the company cardholder, add lightweight users, order 1–20 cards, assign, load and unload.
/api/v2/mor/public/*Manage groups and codes, assignments, verification, reversals, imports, liability and reports. Redemption is idempotent.
/api/v2/vouchers/*Configure programmes, merchants and MIDs, auto-assign points, import transactions, show dashboards and redemption options.
Dashboard functionalityAdmins can manage discount codes and associate a discount with a card. Do not expose company-admin credentials to end users.
Dashboard administrationCompany cost reporting
Read company costs by currency
curl --request POST 'https://staging.hoppa.global/api/v2/reporting/costs' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"From": "2026-10-01T00:00:00Z",
"To": "2026-10-25T23:59:59Z",
"ExcludedUserIds": []
}'Example 200 responseJSON · collapse
{
"Complete": true,
"Currencies": [
{
"Currency": "USD",
"ProviderCost": 100,
"ReferralFees": 100
}
]
}Check Complete before using the result. Incomplete coverage is not zero cost; keep Currencies separate.
Create a hosted payment request
curl --request POST 'https://staging.hoppa.global/api/v2/payments/requests' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"Amount": "49.99",
"Currency": "GBP",
"Description": "Invoice 2026-042",
"ExternalReferenceId": "invoice_2026_042",
"CallbackUrl": "https://api.example.com/webhooks/hoppa/payments",
"SuccessUrl": "https://app.example.com/payment/success",
"FailureUrl": "https://app.example.com/payment/failed",
"Metadata": {
"orderId": "order_5531"
}
}'Example 201 responseJSON · collapse
{
"Id": 123,
"UserId": 123,
"CompanyId": 123,
"Amount": "100.00",
"Currency": "USD",
"Status": "PENDING",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"CallbackUrl": "https://example.com/callback",
"SuccessUrl": "https://example.com/callback",
"FailureUrl": "https://example.com/callback",
"PaymentUrl": "https://example.com/callback",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}Order a MOR prepaid-card batch
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/cards/batch' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: orderMorCards-operation-001' \
--data '{
"CardTypeId": 456,
"Quantity": 10,
"AutoLockEnabled": true,
"LabelPrefix": "EVENT-2026"
}'Example 207 responseJSON · collapse
{
"success": true,
"requestedQuantity": 1,
"createdQuantity": 1,
"cards": [
{
"id": 123,
"externalCardId": "external_reference_123",
"status": "PENDING",
"cardType": "string",
"productName": "string",
"currency": "USD",
"availableBalance": 100,
"pendingBalance": 100,
"maskedCardNumber": "string",
"cardNumberLastFour": "string",
"cardholderName": "string",
"companyCardholderId": "string",
"assignedUserId": 123,
"assignedUserEmail": "user@example.com",
"assignedUserName": "string",
"isVirtual": true,
"isPhysical": true,
"isLocked": true,
"pendingLoadRequest": {
"id": 123,
"cardId": 123,
"requestedByUserId": 123,
"requestedByName": "string",
"requestedByEmail": "user@example.com",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"note": "string",
"adminEmailSent": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
},
"createdAt": "2026-08-05T09:30:00Z"
}
],
"errors": [
"string"
]
}/api/v2/mor/public/kyb/api/v2/mor/public/onboarding-status/api/v2/mor/public/cardholder/api/v2/mor/public/users/api/v2/mor/public/cards/{cardId}/assign/api/v2/mor/public/cards/{cardId}/load/api/v2/mor/public/cards/{cardId}/unload/api/v2/mor/public/cards/{cardId}/secure-widgetRedeem a voucher for a user
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/redemptions' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: voucher-welcome-25-customer-1042' \
--data '{
"UserId": 123,
"Code": "WELCOME-25-ABCD"
}'Example 200 responseJSON · collapse
{
"Id": "00000000-0000-4000-8000-000000000123",
"VoucherId": "00000000-0000-4000-8000-000000000123",
"VoucherName": "string",
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"TransactionReference": "external_reference_123",
"ErrorCode": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}Run merchant cards on one Crypto cards account.
MOR is a separate, API-key-authenticated product surface. The merchant company owns the Crypto cards account, company cardholder and prepaid cards; lightweight users receive assignments without individual KYC.
/api/v2/mor/public/*New merchant events cover assignment, unassignment, load requests and KYB changes. Deduplicate event IDs and read current state. For bounded reconciliation use GET /api/v2/mor/public/cards/page with page size up to 100; balances there are stored values. Existing GET /cards keeps its full-list behavior.
Step 1 — submit merchant KYB
Submit the legal entity and UBO data once. A 409 means the registration number or active submission conflicts with an existing record; do not create a second company to bypass it.
Submit MOR merchant KYB
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/kyb' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: submitMorKyb-operation-001' \
--data '{
"CompanyName": "Example Commerce Ltd",
"RegistrationNumber": "12345678",
"RegistrationCountry": "GB",
"Industry": "E_COMMERCE",
"Website": "https://merchant.example",
"IncorporationDate": "2020-03-12",
"BusinessDescription": "Online retail of consumer electronics",
"AddressLine1": "10 Market Street",
"City": "London",
"Country": "GB",
"PostalCode": "SW1A 1AA",
"PhoneNumber": "7700900123",
"PhoneCountryCode": "+44",
"UboInformation": {
"UboFirstName": "Jane",
"UboLastName": "Doe",
"UboGender": "F",
"UboCountryCode": "GB",
"UboIdType": "PASSPORT",
"UboIdNumber": "123456789",
"UboDob": "1990-01-15"
},
"Ubos": [
{
"FirstName": "Jane",
"LastName": "Doe",
"Dob": "1990-01-15",
"Nationality": "GB",
"OwnershipPercentage": 100,
"IdNumber": "123456789",
"Gender": "F",
"CountryCode": "GB",
"IdType": "PASSPORT"
}
]
}'Example 200 responseJSON · collapse
{
"id": 123,
"status": "PENDING",
"provider": "string",
"profileId": "string",
"interlaceAccountId": "string",
"rejectionReason": "string",
"submittedAt": "2026-08-05T09:30:00Z",
"reviewedAt": "2026-08-05T09:30:00Z",
"lastPolledAt": "2026-08-05T09:30:00Z",
"companyCardholderId": "string",
"companyCardholderStatus": "PENDING",
"companyCardholderCreatedAt": "2026-08-05T09:30:00Z"
}/api/v2/mor/public/onboarding-status/api/v2/mor/public/onboarding-status?refresh=truePoll the local status normally. Use refresh=true only as a recovery check when a Crypto cards update may have been missed. Continue only when status is PASSED; display rejectionReason before resubmission.
Step 2 — ensure the one company cardholder
Create or return the CORPORATE_MANAGED cardholder
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/cardholder' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: createMorCardholder-operation-001' \
--data '{
"Dob": "1990-01-15"
}'Example 200 responseJSON · collapse
{
"cardholderId": "string",
"status": "PENDING",
"created": true,
"error": "string"
}Step 3 — create a lightweight card user
Create an MOR user_simple
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/users' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: createMorSimpleUser-operation-001' \
--data '{
"Email": "card.user@example.com",
"Phone": "+447700900124",
"FirstName": "Alex",
"LastName": "Taylor",
"Password": "GENERATE_A_STRONG_ONE_TIME_PASSWORD"
}'Example 201 responseJSON · collapse
{
"userId": 123,
"email": "user@example.com",
"firstName": "Jane",
"lastName": "Doe",
"phone": "+447700900123",
"invitationEmailSent": true
}user_simple is invitation-only and does not run personal KYC under the Crypto cards CORPORATE_MANAGED model. Store the returned userId; assignment rejects users from another company.
Step 4 — order company-owned cards
Order 1–20 MOR prepaid cards
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/cards/batch' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: orderMorCards-operation-001' \
--data '{
"CardTypeId": 456,
"Quantity": 10,
"AutoLockEnabled": true,
"LabelPrefix": "EVENT-2026"
}'Example 207 responseJSON · collapse
{
"success": true,
"requestedQuantity": 1,
"createdQuantity": 1,
"cards": [
{
"id": 123,
"externalCardId": "external_reference_123",
"status": "PENDING",
"cardType": "string",
"productName": "string",
"currency": "USD",
"availableBalance": 100,
"pendingBalance": 100,
"maskedCardNumber": "string",
"cardNumberLastFour": "string",
"cardholderName": "string",
"companyCardholderId": "string",
"assignedUserId": 123,
"assignedUserEmail": "user@example.com",
"assignedUserName": "string",
"isVirtual": true,
"isPhysical": true,
"isLocked": true,
"pendingLoadRequest": {
"id": 123,
"cardId": 123,
"requestedByUserId": 123,
"requestedByName": "string",
"requestedByEmail": "user@example.com",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"note": "string",
"adminEmailSent": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
},
"createdAt": "2026-08-05T09:30:00Z"
}
],
"errors": [
"string"
]
}A partially successful batch can return 207 Multi-Status. Persist every created card in cards and every item in errors; retry only the quantity that was not created.
Step 5 — assign, then fund
Assign a merchant card to a simple user
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/cards/9101/assign' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: assignMorCard-operation-001' \
--data '{
"AssignedUserId": 2401
}'Example 200 responseJSON · collapse
{
"id": 123,
"externalCardId": "external_reference_123",
"status": "PENDING",
"cardType": "string",
"productName": "string",
"currency": "USD",
"availableBalance": 100,
"pendingBalance": 100,
"maskedCardNumber": "string",
"cardNumberLastFour": "string",
"cardholderName": "string",
"companyCardholderId": "string",
"assignedUserId": 123,
"assignedUserEmail": "user@example.com",
"assignedUserName": "string",
"isVirtual": true,
"isPhysical": true,
"isLocked": true,
"pendingLoadRequest": {
"id": 123,
"cardId": 123,
"requestedByUserId": 123,
"requestedByName": "string",
"requestedByEmail": "user@example.com",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"note": "string",
"adminEmailSent": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
},
"createdAt": "2026-08-05T09:30:00Z"
}Load a merchant card from the Crypto cards account
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/cards/9101/load' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: loadMorCard-operation-001' \
--data '{
"Amount": 100
}'Example 200 responseJSON · collapse
{
"card": {
"id": 123,
"externalCardId": "external_reference_123",
"status": "PENDING",
"cardType": "string",
"productName": "string",
"currency": "USD",
"availableBalance": 100,
"pendingBalance": 100,
"maskedCardNumber": "string",
"cardNumberLastFour": "string",
"cardholderName": "string",
"companyCardholderId": "string",
"assignedUserId": 123,
"assignedUserEmail": "user@example.com",
"assignedUserName": "string",
"isVirtual": true,
"isPhysical": true,
"isLocked": true,
"pendingLoadRequest": {
"id": 123,
"cardId": 123,
"requestedByUserId": 123,
"requestedByName": "string",
"requestedByEmail": "user@example.com",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"note": "string",
"adminEmailSent": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
},
"createdAt": "2026-08-05T09:30:00Z"
},
"grossAmount": 100,
"netAmount": 100,
"feeAmount": 100,
"transferAmount": 100,
"merchantAccountDelta": 100,
"feeCurrency": "USD"
}Unload a merchant card to the Crypto cards account
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/cards/9101/unload' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: unloadMorCard-operation-001' \
--data '{
"Amount": 25
}'Example 200 responseJSON · collapse
{
"card": {
"id": 123,
"externalCardId": "external_reference_123",
"status": "PENDING",
"cardType": "string",
"productName": "string",
"currency": "USD",
"availableBalance": 100,
"pendingBalance": 100,
"maskedCardNumber": "string",
"cardNumberLastFour": "string",
"cardholderName": "string",
"companyCardholderId": "string",
"assignedUserId": 123,
"assignedUserEmail": "user@example.com",
"assignedUserName": "string",
"isVirtual": true,
"isPhysical": true,
"isLocked": true,
"pendingLoadRequest": {
"id": 123,
"cardId": 123,
"requestedByUserId": 123,
"requestedByName": "string",
"requestedByEmail": "user@example.com",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"note": "string",
"adminEmailSent": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
},
"createdAt": "2026-08-05T09:30:00Z"
},
"grossAmount": 100,
"netAmount": 100,
"feeAmount": 100,
"transferAmount": 100,
"merchantAccountDelta": 100,
"feeCurrency": "USD"
}/api/v2/mor/public/cards/api/v2/mor/public/users/{userId}/cards/api/v2/mor/public/wallets/api/v2/mor/public/cards/{cardId}/secure-widgetUse the company list for portfolio balances and the user list for assignments and aggregate user balances.
Open the returned hosted widget only in the intended session. Never cache, log or proxy sensitive card data.
Use cards/available for product discovery and the documented card unassign and cancel POST routes for lifecycle actions. Keep these actions scoped to the MOR company.
Implement the six APIs that HOPPA will call.
The white-label partner hosts this API and remains the system of record for its users’ USD, USDT and USDC balances. HOPPA is the API client and performs the Crypto cards settlement and card load.
X-API-KeyWho owns each part
Host the six HTTPS endpoints, map externalUserId, return source balances, and atomically reserve, confirm or release funds with durable idempotency.
Display the WLP balances separately, validate USD values, orchestrate the durable funding request, move USD through Crypto cards and apply the existing card top-up fee.
Convert treasury USDT/USDC when required, move USD from the WLP Quantum Account to the user Quantum Account, and load the active Crypto cards USD card.
Required endpoint checklist
/api/v1/health — prove the integration is ready/api/v1/users/{externalUserId}/balances — return 1–3 USD/USDT/USDC balances/api/v1/users/{externalUserId}/balance-reservations — atomically hold the source asset/api/v1/users/{externalUserId}/balance-reservations/{reservationId} — reconcile durable state/api/v1/users/{externalUserId}/balance-reservations/{reservationId}/confirm — permanently deduct once/api/v1/users/{externalUserId}/balance-reservations/{reservationId}/cancel — release the hold onceHost the same paths in sandbox and production under separate HTTPS base URLs. Every request contains the WLP-issued X-API-Key; reserve, confirm and cancel also contain an Idempotency-Key.
1 — health and balance discovery
Contract test: health endpoint hosted by the WLP
curl --request GET 'https://api.partner.example/api/v1/health' \
-H 'X-API-Key: wlp_live_REDACTED'Example 200 responseJSON · collapse
{
"status": "healthy",
"version": "1.0.0",
"timestamp": "2026-08-05T09:30:00Z"
}Why: HOPPA uses health during activation and monitoring. Return a current UTC timestamp, a non-empty version and healthy, ok or available.
Contract test: read the WLP user balances
curl --request GET 'https://api.partner.example/api/v1/users/partner-user-123/balances' \
-H 'X-API-Key: wlp_live_REDACTED'Example 200 responseJSON · collapse
{
"externalUserId": "partner-user-123",
"totalUsdValue": 405.25,
"timestamp": "2026-08-05T09:30:00Z",
"balances": [
{
"balanceId": "usd-primary",
"type": "fiat",
"currency": "USD",
"balance": 150.25,
"availableBalance": 125.25,
"usdValue": 150.25,
"timestamp": "2026-08-05T09:30:00Z"
},
{
"balanceId": "usdt-primary",
"type": "crypto",
"currency": "USDT",
"balance": 200,
"availableBalance": 175,
"usdValue": 200,
"timestamp": "2026-08-05T09:30:00Z"
},
{
"balanceId": "usdc-primary",
"type": "crypto",
"currency": "USDC",
"balance": 55,
"availableBalance": 55,
"usdValue": 55,
"timestamp": "2026-08-05T09:30:00Z"
}
]
}Why: this is the only source for balances shown as WLP funds. Return one to three unique currencies—USD, USDT and/or USDC—with availableBalance ≤ balance, fresh timestamps and a consistent totalUsdValue.
2 — reserve before HOPPA moves money
Contract test: create an atomic balance reservation
curl --request POST 'https://api.partner.example/api/v1/users/partner-user-123/balance-reservations' \
-H 'X-API-Key: wlp_live_REDACTED' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: dual-balance:4146cd79:reserve' \
--data '{
"requestId": "4146cd79-491b-43f6-b237-f6372a38051a",
"balanceId": "usdt-primary",
"currency": "USDT",
"amount": 25,
"purpose": "card_funding",
"expiry": "2026-08-05T10:00:00Z"
}'Example 201 responseJSON · collapse
{
"reservationId": "reservation-456",
"currency": "USDT",
"reservedAmount": 25,
"status": "reserved",
"expiry": "2026-08-05T10:00:00Z"
}Why: the hold prevents concurrent requests from spending the same asset. In one transaction, validate the user, balance, currency, amount and expiry; reduce only availableBalance; persist the request ID, idempotency key, payload fingerprint and original response.
3 — expose durable reservation state
Contract test: read a reservation for reconciliation
curl --request GET 'https://api.partner.example/api/v1/users/partner-user-123/balance-reservations/reservation-456' \
-H 'X-API-Key: wlp_live_REDACTED'Example 200 responseJSON · collapse
{
"reservationId": "reservation-456",
"currency": "USDT",
"reservedAmount": 25,
"status": "confirmed",
"expiry": "2026-08-05T10:00:00Z"
}Why: a timeout after a financial mutation is ambiguous. HOPPA reads this endpoint before taking another action. The state must survive restarts and must never expose a reservation belonging to another user.
4 — confirm or cancel exactly once
Contract test: confirm the reservation
curl --request POST 'https://api.partner.example/api/v1/users/partner-user-123/balance-reservations/reservation-456/confirm' \
-H 'X-API-Key: wlp_live_REDACTED' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: dual-balance:4146cd79:confirm' \
--data '{}'Example 200 responseJSON · collapse
{
"reservationId": "reservation-456",
"currency": "USDT",
"reservedAmount": 25,
"status": "confirmed",
"expiry": "2026-08-05T10:00:00Z"
}Why: confirmation is the authoritative instruction to deduct the WLP-side source asset after the Crypto cards user credit succeeds. Reduce balance once, update USD values consistently and do not reduce availableBalance again.
Contract test: cancel the reservation
curl --request POST 'https://api.partner.example/api/v1/users/partner-user-123/balance-reservations/reservation-456/cancel' \
-H 'X-API-Key: wlp_live_REDACTED' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: dual-balance:4146cd79:cancel' \
--data '{}'Example 200 responseJSON · collapse
{
"reservationId": "reservation-456",
"currency": "USDT",
"reservedAmount": 25,
"status": "cancelled",
"expiry": "2026-08-05T10:00:00Z"
}Why: cancellation releases the hold only after a definite Crypto cards transfer failure. Restore availableBalance once and leave balance and USD values unchanged.
Required reservation states
Active hold. availableBalance is reduced; total balance is unchanged.
Terminal debit. Balance and total USD value are reduced.
Terminal release. Available balance is restored.
Optional terminal state. Release the hold and never allow later confirmation.
End-to-end order of operations
After a successful Crypto cards user credit, HOPPA confirms the WLP reservation and then loads the selected Crypto cards USD card. If the card load fails after the user credit, the WLP debit remains confirmed and the USD stays available in HOPPA; it must not be deducted or transferred again.
What the WLP provides before activation
Sandbox and production HTTPS base URLs with public DNS and trusted TLS.
Separate high-entropy API keys delivered through a secure channel.
Test externalUserId and USD/USDT/USDC balanceId values.
Technical/security contacts, SLA, maintenance process and completed acceptance tests.
Design the back office before go-live.
Support teams need the same IDs and states as your code. Cover user maintenance, onboarding gates, transaction exports, card controls and reconciliation—not only the happy path.
Core-flow coverage recheck
Registration orchestration
Hosted customer registration uses the dashboard’s signed-in onboarding experience. Its private session routes are excluded from the public contract. Company API-key integrations create users through POST /api/v2/users and follow the direct user/KYC flow.
User maintenance after creation
Cover GET and PUT /api/v2/users/{userId}, occupation codes, detailed KYC status, additional Banking document upload, provider assets, crypto addresses and wallets.
Complete card controls
After ordering, implement limits, activate, freeze, enable, auto-lock, PIN update, secure widget, card transaction history and Crypto cards-only cancellation. Hide unsupported actions by provider.
Transaction investigation and exports
Use list filters, transaction detail, provider sync, statistics and exports. For company treasury views, use the white-label transaction list/sync/export endpoints instead of impersonating a customer.
Asynchronous recovery
Persist request IDs, idempotency keys and provider IDs. Verify signed webhooks, but also poll or sync when delivery is delayed. Never convert an accepted or processing state into completed locally.
User profile and compliance
List and update users, collect occupation/referral data, inspect detailed KYC state, verify users, upload requested Banking documents, and retrieve wallets, assets, crypto addresses and tier.
GET/PUT /api/v2/users/{userId}Config-driven onboarding
Load the gate configuration, check out the required gate, create KYC1/KYC2 sessions, poll onboarding status and assign the approved tier.
Dashboard onboarding · not a public APICard controls and activity
Fetch holders and limits, update limits and auto-lock, list card transactions, estimate Quantum top-up costs, and handle physical-card shipping.
GET /api/v2/cards/{cardId}/limitsTransactions and exports
List, inspect, sync, aggregate and export platform transactions; retrieve Banking payment confirmations; repeat the equivalent workflow for whitelabel accounts.
GET /api/v2/transactions/exportDual-balance card funding
The WLP hosts the six partner endpoints. HOPPA reads the source balance, creates a hold, moves USD through Crypto cards, then confirms or cancels the WLP reservation.
POST WLP /api/v1/users/{externalUserId}/balance-reservationsSupport escalation
Send the local user and transaction identifiers, a clear customer-visible problem description and your external reference through the transaction-reporting endpoint.
POST /api/v2/admin/support/messages/report-transactionWebhook contract families
Scalar contains receiver contracts for authentication, customer, cardholder, card, transfer, transaction, payment and 3DS event families. Implement one hardened receiver, dispatch by event type, and keep unknown events for later replay instead of dropping them.
Find every documented operation.
This searchable snapshot covers all 446 intentionally exposed operations in the current staging OpenAPI document. Use the guided sections above to choose the correct workflow, then open Scalar for the exact live request and response schema.
AdminBusinessOnboarding12 operations
GET/api/v2/admin/business-onboardingOpen request and response documentationadminRequest & responses +
# Restricted admin operation: GET /api/v2/admin/business-onboarding
# Requires the AdminAccess authorization policy.
# This is not a company API-key integration example. Use the authorized admin workflow.Parameters
companyIdqueryintegeroptionalExample: 123pagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 50statequerystringoptionalExample: ALLsearchquerystringoptionalExample: example200OKAdminBusinessOnboardingListResponse
{
"cases": [
{
"application": {
"id": "00000000-0000-4000-8000-000000000123",
"company_id": 123,
"user_id": 123,
"selected_tier_id": 123,
"highest_tier_id": 123,
"gate_configuration_id": 123,
"fees_enabled": true,
"initial_fee": 100,
"highest_fee": 100,
"workflow_version": 1,
"tier_quotes_json": "string",
"complex_case_fee": 100,
"complexity_status": "PENDING",
"complexity_confirmed": true,
"final_tier_id": 123,
"final_fee": 100,
"currency": "USD",
"stripe_account_owner": "string",
"state": "string",
"input_hash": "string",
"risk_score": 1,
"policy_high_risk": true,
"requires_edd": true,
"assessment_json": "string",
"assessment_model": "string",
"policy_version": "string",
"decision": "string",
"reviewed_by": 1,
"review_reason": "string",
"reviewed_at": "2026-08-05T09:30:00Z",
"last_error": "string",
"retry_count": 1,
"next_attempt_at": "2026-08-05T09:30:00Z",
"created_at": "2026-08-05T09:30:00Z",
"updated_at": "2026-08-05T09:30:00Z",
"CompanyId": 123
},
"userId": 123,
"businessName": "string",
"email": "user@example.com",
"workflowState": "string",
"equalsApplicationId": "string",
"equalsStatus": "PENDING",
"equalsAccountId": "string",
"equalsProgress": "string"
}
],
"total": 1,
"page": 1,
"pageSize": 1,
"payments": [
{
"id": "00000000-0000-4000-8000-000000000123",
"case_id": "00000000-0000-4000-8000-000000000123",
"company_id": 123,
"purpose": "Example description",
"amount": 100,
"bank_amount": 100,
"currency": "USD",
"stripe_account_owner": "string",
"status": "PENDING",
"checkout_session_id": "string",
"checkout_url": "https://example.com/callback",
"payment_intent_id": "string",
"checkout_expires_at": "2026-08-05T09:30:00Z",
"terms_accepted_at": "2026-08-05T09:30:00Z",
"terms_version": "string",
"terms_text": "string",
"invoice_number": "string",
"invoice_details_json": "string",
"invoice_sent_at": "2026-08-05T09:30:00Z",
"paid_at": "2026-08-05T09:30:00Z",
"created_at": "2026-08-05T09:30:00Z",
"CompanyId": 123
}
],
"billing": {
"company_id": 123,
"issuer_details": "string",
"bank_instructions": "string",
"tax_description": "Example description",
"invoice_settings_json": "string",
"next_invoice_number": 1,
"CompanyId": 123
}
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/admin/business-onboarding/{userId}/decisionOpen request and response documentationadminRequest & responses +
# Restricted admin operation: POST /api/v2/admin/business-onboarding/{userId}/decision
# Requires the AdminAccess authorization policy.
# This is not a company API-key integration example. Use the authorized admin workflow.Parameters
userIdpathintegerrequiredExample: 123Request fields and validation
CompanyId · integer or null · requiredPattern: ^-?(?:0|[1-9]\d*)$
Decision · string · requiredReason · string · requiredTargetTierId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
ComplexCase · boolean or null · optionalExample request body · replace placeholders
{
"CompanyId": 123,
"Decision": "string",
"Reason": "string",
"TargetTierId": 123,
"ComplexCase": true
}200OKAdminBusinessOnboardingDecideResponse
{
"success": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/admin/business-onboarding/{userId}/payments/{paymentId}/bank-transferOpen request and response documentationadminRequest & responses +
# Restricted admin operation: POST /api/v2/admin/business-onboarding/{userId}/payments/{paymentId}/bank-transfer
# Requires the AdminAccess authorization policy.
# This is not a company API-key integration example. Use the authorized admin workflow.Parameters
userIdpathintegerrequiredExample: 123paymentIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
CompanyId · integer or null · requiredPattern: ^-?(?:0|[1-9]\d*)$
Amount · number · requiredPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Reference · string · requiredReceivedAt · string · requiredEvidence · string · requiredExample request body · replace placeholders
{
"CompanyId": 123,
"Amount": 100,
"Reference": "external_reference_123",
"ReceivedAt": "2026-08-05T09:30:00Z",
"Evidence": "string"
}200OKAdminBusinessOnboardingBankResponse
{
"success": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/admin/business-onboarding/{userId}/documents/{documentId}Open request and response documentationadminRequest & responses +
# Restricted admin operation: GET /api/v2/admin/business-onboarding/{userId}/documents/{documentId}
# Requires the AdminAccess authorization policy.
# This is not a company API-key integration example. Use the authorized admin workflow.Parameters
userIdpathintegerrequiredExample: 123documentIdpathintegerrequiredExample: 123companyIdqueryintegeroptionalExample: 123200OKapplication/octet-stream
<binary file>Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/admin/business-onboarding/{userId}/historyOpen request and response documentationadminRequest & responses +
# Restricted admin operation: GET /api/v2/admin/business-onboarding/{userId}/history
# Requires the AdminAccess authorization policy.
# This is not a company API-key integration example. Use the authorized admin workflow.Parameters
userIdpathintegerrequiredExample: 123companyIdqueryintegeroptionalExample: 123200OKapplication/json
[
{
"id": "00000000-0000-4000-8000-000000000123",
"case_id": "00000000-0000-4000-8000-000000000123",
"company_id": 123,
"kind": "string",
"actor_id": 123,
"details": "string",
"external_reference": "external_reference_123",
"created_at": "2026-08-05T09:30:00Z",
"CompanyId": 123
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/admin/business-onboarding/{userId}/reconcile-submissionOpen request and response documentationadminRequest & responses +
# Restricted admin operation: POST /api/v2/admin/business-onboarding/{userId}/reconcile-submission
# Requires the AdminAccess authorization policy.
# This is not a company API-key integration example. Use the authorized admin workflow.Parameters
userIdpathintegerrequiredExample: 123Request fields and validation
CompanyId · integer or null · requiredPattern: ^-?(?:0|[1-9]\d*)$
ProviderApplicationId · string or null · requiredConfirmedNoProviderApplication · boolean · requiredReason · string · requiredExample request body · replace placeholders
{
"CompanyId": 123,
"ProviderApplicationId": "string",
"ConfirmedNoProviderApplication": true,
"Reason": "string"
}200OKAdminBusinessOnboardingReconcileResponse
{
"state": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/admin/business-onboarding/billingOpen request and response documentationadminRequest & responses +
# Restricted admin operation: PUT /api/v2/admin/business-onboarding/billing
# Requires the AdminAccess authorization policy.
# This is not a company API-key integration example. Use the authorized admin workflow.Request fields and validation
CompanyId · integer or null · requiredPattern: ^-?(?:0|[1-9]\d*)$
IssuerDetails · string · requiredBankInstructions · string · requiredTaxDescription · string · requiredBranding · object or null · optionalNextInvoiceNumber · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
ExpectedNextInvoiceNumber · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"CompanyId": 123,
"IssuerDetails": "string",
"BankInstructions": "string",
"TaxDescription": "Example description",
"Branding": {
"LegalName": "string",
"Address": "string",
"RegistrationNumber": "string",
"TaxNumber": "string",
"Email": "user@example.com",
"Phone": "+447700900123",
"Website": "string",
"Prefix": "string",
"NumberPadding": 1,
"DueDays": 1,
"Footer": "string",
"LogoDataUrl": "https://example.com/callback"
},
"NextInvoiceNumber": 1,
"ExpectedNextInvoiceNumber": 1
}200OKBusinessOnboardingBilling
{
"company_id": 123,
"issuer_details": "string",
"bank_instructions": "string",
"tax_description": "Example description",
"invoice_settings_json": "string",
"next_invoice_number": 1,
"CompanyId": 123
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/admin/business-onboarding/billing/previewOpen request and response documentationadminRequest & responses +
# Restricted admin operation: POST /api/v2/admin/business-onboarding/billing/preview
# Requires the AdminAccess authorization policy.
# This is not a company API-key integration example. Use the authorized admin workflow.Request fields and validation
CompanyId · integer or null · requiredPattern: ^-?(?:0|[1-9]\d*)$
IssuerDetails · string · requiredBankInstructions · string · requiredTaxDescription · string · requiredBranding · object or null · optionalNextInvoiceNumber · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
ExpectedNextInvoiceNumber · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"CompanyId": 123,
"IssuerDetails": "string",
"BankInstructions": "string",
"TaxDescription": "Example description",
"Branding": {
"LegalName": "string",
"Address": "string",
"RegistrationNumber": "string",
"TaxNumber": "string",
"Email": "user@example.com",
"Phone": "+447700900123",
"Website": "string",
"Prefix": "string",
"NumberPadding": 1,
"DueDays": 1,
"Footer": "string",
"LogoDataUrl": "https://example.com/callback"
},
"NextInvoiceNumber": 1,
"ExpectedNextInvoiceNumber": 1
}200OKapplication/pdf
<binary file>Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/admin/business-onboarding/price-tablesOpen request and response documentationadminRequest & responses +
# Restricted admin operation: GET /api/v2/admin/business-onboarding/price-tables
# Requires the AdminAccess authorization policy.
# This is not a company API-key integration example. Use the authorized admin workflow.Parameters
companyIdqueryintegeroptionalExample: 123200OKAdminBusinessOnboardingPriceTablesResponse
{
"data": [
{
"id": 123,
"tierId": 123,
"region": "string",
"tierLabel": "string",
"accountType": "string",
"sections": {}
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/admin/business-onboarding/configurationOpen request and response documentationadminRequest & responses +
# Restricted admin operation: GET /api/v2/admin/business-onboarding/configuration
# Requires the AdminAccess authorization policy.
# This is not a company API-key integration example. Use the authorized admin workflow.Parameters
companyIdqueryintegeroptionalExample: 123200OKAdminBusinessOnboardingConfigurationResponse
{
"tiers": [
{
"id": 123,
"name": "string",
"tier_level": 1
}
],
"complexCasePricing": {
"company_id": 123,
"complex_case_fee": 100,
"currency": "USD",
"CompanyId": 123
},
"gates": [
{
"id": 123,
"company_id": 123,
"tier_id": 123,
"gate_number": "string",
"enabled": true,
"amount": 100,
"currency": "USD",
"stripe_account_owner_override": "string",
"description": "Example description",
"terms_url": "https://example.com/callback",
"max_retries": 1,
"refund_policy": "string",
"failure_policy": "string",
"version": 1,
"is_active": true,
"created_at": "2026-08-05T09:30:00Z",
"updated_at": "2026-08-05T09:30:00Z",
"CompanyId": 123
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/admin/business-onboarding/complex-case-pricingOpen request and response documentationadminRequest & responses +
# Restricted admin operation: PUT /api/v2/admin/business-onboarding/complex-case-pricing
# Requires the AdminAccess authorization policy.
# This is not a company API-key integration example. Use the authorized admin workflow.Request fields and validation
CompanyId · integer or null · requiredPattern: ^-?(?:0|[1-9]\d*)$
Amount · number · requiredPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Currency · string · requiredExample request body · replace placeholders
{
"CompanyId": 123,
"Amount": 100,
"Currency": "USD"
}200OKBusinessOnboardingPricingSettings
{
"company_id": 123,
"complex_case_fee": 100,
"currency": "USD",
"CompanyId": 123
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/admin/business-onboarding/configuration/{tierId}Open request and response documentationadminRequest & responses +
# Restricted admin operation: PUT /api/v2/admin/business-onboarding/configuration/{tierId}
# Requires the AdminAccess authorization policy.
# This is not a company API-key integration example. Use the authorized admin workflow.Parameters
tierIdpathintegerrequiredExample: 123Request fields and validation
CompanyId · integer or null · requiredPattern: ^-?(?:0|[1-9]\d*)$
Enabled · boolean · requiredAmount · number · requiredPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Currency · string · requiredExample request body · replace placeholders
{
"CompanyId": 123,
"Enabled": true,
"Amount": 100,
"Currency": "USD"
}200OKOnboardingGateConfiguration
{
"id": 123,
"company_id": 123,
"tier_id": 123,
"gate_number": "string",
"enabled": true,
"amount": 100,
"currency": "USD",
"stripe_account_owner_override": "string",
"description": "Example description",
"terms_url": "https://example.com/callback",
"max_retries": 1,
"refund_policy": "string",
"failure_policy": "string",
"version": 1,
"is_active": true,
"created_at": "2026-08-05T09:30:00Z",
"updated_at": "2026-08-05T09:30:00Z",
"CompanyId": 123
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
Authorization10 operations
GET/api/v2/authorization/capabilitiesOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/authorization/capabilities' \
-H 'x-api-key: YOUR_API_KEY'200OKAuthorizationRulesCapabilitiesResponse
{
"scopes": [
"string"
],
"ruleTypes": [
"string"
],
"merchantMatchModes": [
"string"
],
"precedence": "string",
"binRequirement": "string",
"subscriptionLimitation": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/authorization/binsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/authorization/bins' \
-H 'x-api-key: YOUR_API_KEY'200OKapplication/json
[
{
"BinRangeId": 123,
"Bin": "string",
"Description": "Example description",
"ExternalBinId": "external_reference_123",
"RealTimeAuthorizationEnabled": true
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/authorization/cardsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/authorization/cards?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123200OKapplication/json
[
{
"CardId": 123,
"OwnerUserId": 123,
"EffectiveUserId": 123,
"MaskedCardNumber": "string",
"BinRangeId": 123,
"RealTimeAuthorizationEnabled": true
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/authorization/configurationOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/authorization/configuration?environment=example' \
-H 'x-api-key: YOUR_API_KEY'Parameters
environmentquerystringoptionalExample: example200OKAuthorizationEndpointResponse
{
"PublicId": "00000000-0000-4000-8000-000000000123",
"Environment": "string",
"Enabled": true,
"DefaultResponseCode": "string",
"FailureResponseCode": "string",
"CallbackPath": "https://example.com/callback",
"CallbackUrl": "https://example.com/callback",
"SupportedCredentialKeys": [
"string"
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/authorization/configurationOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/authorization/configuration' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Environment": "string",
"Enabled": true,
"DefaultResponseCode": "string",
"FailureResponseCode": "string"
}'Request fields and validation
Environment · string · optionalEnabled · boolean · optionalDefaultResponseCode · string · optionalFailureResponseCode · string · optionalExample request body · replace placeholders
{
"Environment": "string",
"Enabled": true,
"DefaultResponseCode": "string",
"FailureResponseCode": "string"
}200OKAuthorizationEndpointResponse
{
"PublicId": "00000000-0000-4000-8000-000000000123",
"Environment": "string",
"Enabled": true,
"DefaultResponseCode": "string",
"FailureResponseCode": "string",
"CallbackPath": "https://example.com/callback",
"CallbackUrl": "https://example.com/callback",
"SupportedCredentialKeys": [
"string"
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/authorization/rulesOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/authorization/rules' \
-H 'x-api-key: YOUR_API_KEY'200OKapplication/json
[
{
"Id": 123,
"Name": "string",
"Description": "Example description",
"ScopeType": "string",
"UserId": 123,
"CardId": 123,
"BinRangeId": 123,
"AuthorityType": "string",
"RuleType": "string",
"ResponseCode": "string",
"Priority": 1,
"Active": true,
"Configuration": {
"MerchantNames": [
"string"
],
"MerchantMids": [
"string"
],
"MerchantMatchMode": "string",
"Values": [
"string"
],
"MaximumAmount": 100,
"Currency": "USD",
"TimeZone": "string",
"DaysOfWeek": [
"string"
],
"StartTime": "string",
"EndTime": "string"
},
"EffectiveFrom": "2026-08-05T09:30:00Z",
"EffectiveTo": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/authorization/rulesOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/authorization/rules' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Name": "string",
"Description": "Example description",
"ScopeType": "string",
"UserId": 123,
"CardId": 123,
"BinRangeId": 123,
"RuleType": "string",
"ResponseCode": "string",
"Priority": 1,
"Active": true,
"Configuration": {
"MerchantNames": [
"string"
],
"MerchantMids": [
"string"
],
"MerchantMatchMode": "string",
"Values": [
"string"
],
"MaximumAmount": 100,
"Currency": "USD",
"TimeZone": "string",
"DaysOfWeek": [
"string"
],
"StartTime": "string",
"EndTime": "string"
},
"EffectiveFrom": "2026-08-05T09:30:00Z",
"EffectiveTo": "2026-08-05T09:30:00Z"
}'Request fields and validation
Name · string · optionalDescription · string or null · optionalScopeType · string · optionalUserId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
CardId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
BinRangeId · integer or null · optionalRequired for COMPANY and USER rules. CARD rules derive the BIN from the card product and reject a conflicting supplied value.
Pattern: ^-?(?:0|[1-9]\d*)$
RuleType · string · optionalResponseCode · string · optionalPriority · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
Active · boolean · optionalConfiguration · object · optionalEffectiveFrom · string or null · optionalEffectiveTo · string or null · optionalExample request body · replace placeholders
{
"Name": "string",
"Description": "Example description",
"ScopeType": "string",
"UserId": 123,
"CardId": 123,
"BinRangeId": 123,
"RuleType": "string",
"ResponseCode": "string",
"Priority": 1,
"Active": true,
"Configuration": {
"MerchantNames": [
"string"
],
"MerchantMids": [
"string"
],
"MerchantMatchMode": "string",
"Values": [
"string"
],
"MaximumAmount": 100,
"Currency": "USD",
"TimeZone": "string",
"DaysOfWeek": [
"string"
],
"StartTime": "string",
"EndTime": "string"
},
"EffectiveFrom": "2026-08-05T09:30:00Z",
"EffectiveTo": "2026-08-05T09:30:00Z"
}201CreatedAuthorizationRuleResponse
{
"Id": 123,
"Name": "string",
"Description": "Example description",
"ScopeType": "string",
"UserId": 123,
"CardId": 123,
"BinRangeId": 123,
"AuthorityType": "string",
"RuleType": "string",
"ResponseCode": "string",
"Priority": 1,
"Active": true,
"Configuration": {
"MerchantNames": [
"string"
],
"MerchantMids": [
"string"
],
"MerchantMatchMode": "string",
"Values": [
"string"
],
"MaximumAmount": 100,
"Currency": "USD",
"TimeZone": "string",
"DaysOfWeek": [
"string"
],
"StartTime": "string",
"EndTime": "string"
},
"EffectiveFrom": "2026-08-05T09:30:00Z",
"EffectiveTo": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/authorization/rules/{ruleId}Open request and response documentationRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/authorization/rules/123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Name": "string",
"Description": "Example description",
"ScopeType": "string",
"UserId": 123,
"CardId": 123,
"BinRangeId": 123,
"RuleType": "string",
"ResponseCode": "string",
"Priority": 1,
"Active": true,
"Configuration": {
"MerchantNames": [
"string"
],
"MerchantMids": [
"string"
],
"MerchantMatchMode": "string",
"Values": [
"string"
],
"MaximumAmount": 100,
"Currency": "USD",
"TimeZone": "string",
"DaysOfWeek": [
"string"
],
"StartTime": "string",
"EndTime": "string"
},
"EffectiveFrom": "2026-08-05T09:30:00Z",
"EffectiveTo": "2026-08-05T09:30:00Z"
}'Parameters
ruleIdpathintegerrequiredExample: 123Request fields and validation
Name · string · optionalDescription · string or null · optionalScopeType · string · optionalUserId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
CardId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
BinRangeId · integer or null · optionalRequired for COMPANY and USER rules. CARD rules derive the BIN from the card product and reject a conflicting supplied value.
Pattern: ^-?(?:0|[1-9]\d*)$
RuleType · string · optionalResponseCode · string · optionalPriority · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
Active · boolean · optionalConfiguration · object · optionalEffectiveFrom · string or null · optionalEffectiveTo · string or null · optionalExample request body · replace placeholders
{
"Name": "string",
"Description": "Example description",
"ScopeType": "string",
"UserId": 123,
"CardId": 123,
"BinRangeId": 123,
"RuleType": "string",
"ResponseCode": "string",
"Priority": 1,
"Active": true,
"Configuration": {
"MerchantNames": [
"string"
],
"MerchantMids": [
"string"
],
"MerchantMatchMode": "string",
"Values": [
"string"
],
"MaximumAmount": 100,
"Currency": "USD",
"TimeZone": "string",
"DaysOfWeek": [
"string"
],
"StartTime": "string",
"EndTime": "string"
},
"EffectiveFrom": "2026-08-05T09:30:00Z",
"EffectiveTo": "2026-08-05T09:30:00Z"
}200OKAuthorizationRuleResponse
{
"Id": 123,
"Name": "string",
"Description": "Example description",
"ScopeType": "string",
"UserId": 123,
"CardId": 123,
"BinRangeId": 123,
"AuthorityType": "string",
"RuleType": "string",
"ResponseCode": "string",
"Priority": 1,
"Active": true,
"Configuration": {
"MerchantNames": [
"string"
],
"MerchantMids": [
"string"
],
"MerchantMatchMode": "string",
"Values": [
"string"
],
"MaximumAmount": 100,
"Currency": "USD",
"TimeZone": "string",
"DaysOfWeek": [
"string"
],
"StartTime": "string",
"EndTime": "string"
},
"EffectiveFrom": "2026-08-05T09:30:00Z",
"EffectiveTo": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
DELETE/api/v2/authorization/rules/{ruleId}Open request and response documentationRequest & responses +
curl --request DELETE 'https://staging.hoppa.global/api/v2/authorization/rules/123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
ruleIdpathintegerrequiredExample: 123204No ContentNo response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/authorization/decisionsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/authorization/decisions?take=100' \
-H 'x-api-key: YOUR_API_KEY'Parameters
takequeryintegeroptionalExample: 100200OKapplication/json
[
{
"Id": 123,
"UserId": 123,
"CardId": 123,
"RequestId": "string",
"TransactionId": "string",
"ResponseCode": "string",
"Reason": "string",
"MatchedRuleId": 123,
"MerchantName": "string",
"MerchantMid": "string",
"Mcc": "string",
"TransactionAmount": 100,
"TransactionCurrency": "USD",
"LatencyMs": 1,
"UsedFallback": true,
"CreatedAt": "2026-08-05T09:30:00Z"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
Banking42 operations
GET/api/v2/banking/approvals/capabilitiesOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/banking/approvals/capabilities?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123200OKapplication/json
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/approvals/devices/enrollOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/banking/approvals/devices/enroll?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"PublicKey": "string",
"Name": "string"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
PublicKey · string · requiredMinimum length: 0
Maximum length: 200
Name · string · requiredMinimum length: 0
Maximum length: 80
Example request body · replace placeholders
{
"PublicKey": "string",
"Name": "string"
}200OKapplication/json
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/approvals/devices/confirmOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/banking/approvals/devices/confirm?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Signature": "string",
"VerificationToken": "PLACEHOLDER_TOKEN",
"OtpCode": "string"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
Signature · string · requiredMinimum length: 0
Maximum length: 200
VerificationToken · string · requiredMinimum length: 0
Maximum length: 100
OtpCode · string · requiredMinimum length: 0
Maximum length: 10
Example request body · replace placeholders
{
"Signature": "string",
"VerificationToken": "PLACEHOLDER_TOKEN",
"OtpCode": "string"
}200OKapplication/json
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
DELETE/api/v2/banking/approvals/devices/{deviceId}Open request and response documentationRequest & responses +
curl --request DELETE 'https://staging.hoppa.global/api/v2/banking/approvals/devices/00000000-0000-4000-8000-000000000123?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
deviceIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123userIdqueryintegeroptionalExample: 123200OKapplication/json
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
DELETE/api/v2/banking/approvals/{verificationToken}Open request and response documentationRequest & responses +
curl --request DELETE 'https://staging.hoppa.global/api/v2/banking/approvals/PLACEHOLDER_TOKEN?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
verificationTokenpathstringrequiredExample: PLACEHOLDER_TOKENuserIdqueryintegeroptionalExample: 123200OKapplication/json
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/approvals/verifyOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/banking/approvals/verify?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"VerificationToken": "PLACEHOLDER_TOKEN",
"Signature": "string"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
VerificationToken · string · requiredMinimum length: 0
Maximum length: 100
Signature · string · requiredMinimum length: 0
Maximum length: 200
Example request body · replace placeholders
{
"VerificationToken": "PLACEHOLDER_TOKEN",
"Signature": "string"
}200OKapplication/json
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/approvals/passkeys/enrollOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/banking/approvals/passkeys/enroll?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Name": "string"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
Name · string · requiredMinimum length: 0
Maximum length: 80
Example request body · replace placeholders
{
"Name": "string"
}200OKapplication/json
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/approvals/passkeys/confirmOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/banking/approvals/passkeys/confirm?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Credential": {
"id": "string",
"rawId": "BASE64_ENCODED_DATA",
"type": "public-key",
"response": {
"attestationObject": "BASE64_ENCODED_DATA",
"clientDataJSON": "BASE64_ENCODED_DATA",
"transports": [
"usb"
]
},
"clientExtensionResults": {
"example.extension.bool": true,
"appid": true,
"exts": [
"string"
],
"uvm": [
[
"string"
]
],
"credProps": {
"rk": true,
"authenticatorDisplayName": "string"
},
"prf": {
"enabled": true,
"results": {
"first": {},
"second": {}
}
},
"largeBlob": {
"supported": true,
"blob": "BASE64_ENCODED_DATA",
"written": true
},
"credProtect": "userVerificationOptional"
},
"extensions": {
"example.extension.bool": true,
"appid": true,
"exts": [
"string"
],
"uvm": [
[
"string"
]
],
"credProps": {
"rk": true,
"authenticatorDisplayName": "string"
},
"prf": {
"enabled": true,
"results": {
"first": {},
"second": {}
}
},
"largeBlob": {
"supported": true,
"blob": "BASE64_ENCODED_DATA",
"written": true
},
"credProtect": "userVerificationOptional"
}
},
"VerificationToken": "PLACEHOLDER_TOKEN",
"OtpCode": "string"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
Credential · object · requiredVerificationToken · string · requiredMinimum length: 0
Maximum length: 100
OtpCode · string · requiredMinimum length: 0
Maximum length: 10
Example request body · replace placeholders
{
"Credential": {
"id": "string",
"rawId": "BASE64_ENCODED_DATA",
"type": "public-key",
"response": {
"attestationObject": "BASE64_ENCODED_DATA",
"clientDataJSON": "BASE64_ENCODED_DATA",
"transports": [
"usb"
]
},
"clientExtensionResults": {
"example.extension.bool": true,
"appid": true,
"exts": [
"string"
],
"uvm": [
[
"string"
]
],
"credProps": {
"rk": true,
"authenticatorDisplayName": "string"
},
"prf": {
"enabled": true,
"results": {
"first": {},
"second": {}
}
},
"largeBlob": {
"supported": true,
"blob": "BASE64_ENCODED_DATA",
"written": true
},
"credProtect": "userVerificationOptional"
},
"extensions": {
"example.extension.bool": true,
"appid": true,
"exts": [
"string"
],
"uvm": [
[
"string"
]
],
"credProps": {
"rk": true,
"authenticatorDisplayName": "string"
},
"prf": {
"enabled": true,
"results": {
"first": {},
"second": {}
}
},
"largeBlob": {
"supported": true,
"blob": "BASE64_ENCODED_DATA",
"written": true
},
"credProtect": "userVerificationOptional"
}
},
"VerificationToken": "PLACEHOLDER_TOKEN",
"OtpCode": "string"
}200OKapplication/json
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
DELETE/api/v2/banking/approvals/passkeys/{passkeyId}Open request and response documentationRequest & responses +
curl --request DELETE 'https://staging.hoppa.global/api/v2/banking/approvals/passkeys/00000000-0000-4000-8000-000000000123?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
passkeyIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123userIdqueryintegeroptionalExample: 123200OKapplication/json
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/approvals/passkeys/verifyOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/banking/approvals/passkeys/verify?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"VerificationToken": "PLACEHOLDER_TOKEN",
"Credential": {
"id": "string",
"rawId": "BASE64_ENCODED_DATA",
"type": "public-key",
"clientExtensionResults": {
"example.extension.bool": true,
"appid": true,
"exts": [
"string"
],
"uvm": [
[
"string"
]
],
"credProps": {
"rk": true,
"authenticatorDisplayName": "string"
},
"prf": {
"enabled": true,
"results": {
"first": {},
"second": {}
}
},
"largeBlob": {
"supported": true,
"blob": "BASE64_ENCODED_DATA",
"written": true
},
"credProtect": "userVerificationOptional"
},
"response": {
"authenticatorData": "BASE64_ENCODED_DATA",
"signature": "BASE64_ENCODED_DATA",
"clientDataJSON": "BASE64_ENCODED_DATA",
"userHandle": "BASE64_ENCODED_DATA"
},
"extensions": {
"example.extension.bool": true,
"appid": true,
"exts": [
"string"
],
"uvm": [
[
"string"
]
],
"credProps": {
"rk": true,
"authenticatorDisplayName": "string"
},
"prf": {
"enabled": true,
"results": {
"first": {},
"second": {}
}
},
"largeBlob": {
"supported": true,
"blob": "BASE64_ENCODED_DATA",
"written": true
},
"credProtect": "userVerificationOptional"
}
}
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
VerificationToken · string · requiredMinimum length: 0
Maximum length: 100
Credential · object · requiredExample request body · replace placeholders
{
"VerificationToken": "PLACEHOLDER_TOKEN",
"Credential": {
"id": "string",
"rawId": "BASE64_ENCODED_DATA",
"type": "public-key",
"clientExtensionResults": {
"example.extension.bool": true,
"appid": true,
"exts": [
"string"
],
"uvm": [
[
"string"
]
],
"credProps": {
"rk": true,
"authenticatorDisplayName": "string"
},
"prf": {
"enabled": true,
"results": {
"first": {},
"second": {}
}
},
"largeBlob": {
"supported": true,
"blob": "BASE64_ENCODED_DATA",
"written": true
},
"credProtect": "userVerificationOptional"
},
"response": {
"authenticatorData": "BASE64_ENCODED_DATA",
"signature": "BASE64_ENCODED_DATA",
"clientDataJSON": "BASE64_ENCODED_DATA",
"userHandle": "BASE64_ENCODED_DATA"
},
"extensions": {
"example.extension.bool": true,
"appid": true,
"exts": [
"string"
],
"uvm": [
[
"string"
]
],
"credProps": {
"rk": true,
"authenticatorDisplayName": "string"
},
"prf": {
"enabled": true,
"results": {
"first": {},
"second": {}
}
},
"largeBlob": {
"supported": true,
"blob": "BASE64_ENCODED_DATA",
"written": true
},
"credProtect": "userVerificationOptional"
}
}
}200OKapplication/json
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/banking/accountsGet all accounts across all banking providersRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/banking/accounts?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123200OKUnifiedAccountsResponse
{
"Accounts": [
{
"AccountId": "string",
"ParentAccountId": "string",
"BudgetId": "string",
"DisplayName": "string",
"AccountType": "string",
"Status": "PENDING",
"Provider": "EqualsMoney",
"SupportedCurrencies": [
"string"
],
"CreatedAt": "2026-08-05T09:30:00Z"
}
],
"TotalCount": 1
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/accounts/fund-testFund a Banking account with a sandbox test credit.testRequest & responses +
Staging only. This endpoint uses the Banking sandbox budget-credit simulator and will not work in production. Use AccountId from GET /api/v2/banking/accounts. Amount defaults to 100.00 when omitted.
curl --request POST 'https://staging.hoppa.global/api/v2/banking/accounts/fund-test?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"AccountId": "string",
"BalanceId": "100.00",
"Currency": "USD",
"Amount": {}
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
AccountId · string · requiredBanking account or budget ID to fund. Use AccountId from GET /api/v2/banking/accounts.
BalanceId · string or null · optionalOptional provider balance ID returned with the account.
Currency · string or null · optionalCredit currency. Defaults to the selected account currency when omitted.
Amount · value · optionalCredit amount. Defaults to 100.00 when omitted.
Example request body · replace placeholders
{
"AccountId": "string",
"BalanceId": "100.00",
"Currency": "USD",
"Amount": {}
}200OKFundAccountResponse
{
"Success": true,
"Message": "string",
"AccountId": "string",
"BudgetId": "string",
"Currency": "USD",
"Amount": "100.00"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/equalsmoney-onboardingCreate a Banking personal onboarding applicationRequest & responses +
Personal onboarding only. Creates a Banking payments/cards application for the authenticated API user. Contact and account details are populated from the user profile; the client provides only the personal KYC fields and documents.
curl --request POST 'https://staging.hoppa.global/api/v2/banking/equalsmoney-onboarding?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'RequestedFeatures=CARDS' \
-F 'MainPurpose=SALARY_OR_INCOME' \
-F 'SourceOfFunds=RECEIVING_FUNDS_FROM_OWN_ACCOUNTS' \
-F 'DestinationOfFunds=AD' \
-F 'CurrenciesRequired=AED' \
-F 'AnnualVolume=0-10000' \
-F 'NumberOfPayments=FEWER-THAN-5' \
-F 'CardPurposes=SALARY_OR_INCOME' \
-F 'CardAnnualSpend=0-10000' \
-F 'NumberOfCardsRequired=0-10' \
-F 'AtmWithdrawalsRequired=true' \
-F 'ProofOfAddress=@/absolute/path/document.pdf'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
RequestedFeatures · array · optionalAllowed values: PAYMENTS, CARDS. PAYMENTS is required.
MainPurpose · array · optionalPossible values: SALARY_OR_INCOME, PERSONAL_TRANSFERS_OR_LIVING_EXPENSES, FAMILY_SUPPORT, MORTGAGE_OR_RENT_OR_UTILITY_BILLS, SAVINGS, INVESTMENT_PURPOSES, INVESTMENT_OR_TRADING_IN_CRYPTOCURRENCIES, RECEIVING_OR_SENDING_LOAN_PAYMENTS, PURCHASE_OF_GOODS_OR_SERVICES, TRAVEL, EDUCATION, MEDICAL_EXPENSES, CHARITABLE_DONATIONS.
SourceOfFunds · array · optionalPossible values: RECEIVING_FUNDS_FROM_OWN_ACCOUNTS, RECEIVING_SALARY_PENSION_OR_DIVIDENDS, RECEIVING_GIFTS_OR_INHERITANCES, PROCEEDS_FROM_INVESTMENTS, PROCEEDS_FROM_CRYPTOCURRENCY_SALES_OR_TRADING, PROCEEDS_FROM_SALE_OF_A_PROPERTY_OR_PHYSICAL_ASSET, OTHER.
DestinationOfFunds · array · optionalPossible values: AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW.
CurrenciesRequired · array · optionalPossible values: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SEK, SGD, SHN, SLL, SOS, SRD, SSP, STN, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VND, VUV, WST, XAF, XAG, XAU, XCD, XOF, XPD, XPF, XPT, YER, ZAR, ZMK, ZMW, ZWD.
AnnualVolume · string · optionalPossible values: 0-10000, 10001-50000, 50001-100000, 100001-250000, 250001-1000000, 1000001-5000000, 5000000+.
Allowed: 0-10000, 10001-50000, 50001-100000, 100001-250000, 250001-1000000, 1000001-5000000, 5000000+
NumberOfPayments · string · optionalPossible values: FEWER-THAN-5, 5-10, 10-20, MORE-THAN-20.
Allowed: FEWER-THAN-5, 5-10, 10-20, MORE-THAN-20
CardPurposes · array · optionalPossible values: SALARY_OR_INCOME, PERSONAL_TRANSFERS_OR_LIVING_EXPENSES, FAMILY_SUPPORT, MORTGAGE_OR_RENT_OR_UTILITY_BILLS, SAVINGS, INVESTMENT_PURPOSES, INVESTMENT_OR_TRADING_IN_CRYPTOCURRENCIES, RECEIVING_OR_SENDING_LOAN_PAYMENTS, PURCHASE_OF_GOODS_OR_SERVICES, TRAVEL, EDUCATION, MEDICAL_EXPENSES, CHARITABLE_DONATIONS.
CardAnnualSpend · string · optionalPossible values: 0-10000, 10001-50000, 50001-100000, 100001-250000, 250001-1000000, 1000001-5000000, 5000000+.
Allowed: 0-10000, 10001-50000, 50001-100000, 100001-250000, 250001-1000000, 1000001-5000000, 5000000+
NumberOfCardsRequired · string · optionalPossible values: 0-10, 11-50, 51-100, 101+.
Allowed: 0-10, 11-50, 51-100, 101+
AtmWithdrawalsRequired · boolean · optionalProofOfAddress · string · optionalDocument file to upload for the Banking associated person.
Example request body · replace placeholders
{
"RequestedFeatures": [
"CARDS"
],
"MainPurpose": [
"SALARY_OR_INCOME"
],
"SourceOfFunds": [
"RECEIVING_FUNDS_FROM_OWN_ACCOUNTS"
],
"DestinationOfFunds": [
"AD"
],
"CurrenciesRequired": [
"AED"
],
"AnnualVolume": "0-10000",
"NumberOfPayments": "FEWER-THAN-5",
"CardPurposes": [
"SALARY_OR_INCOME"
],
"CardAnnualSpend": "0-10000",
"NumberOfCardsRequired": "0-10",
"AtmWithdrawalsRequired": true,
"ProofOfAddress": "<binary file>"
}202AcceptedEqualsMoneyOnboardingDashboardResponse
{
"Success": true,
"Message": "string",
"CorrelationId": "string",
"AccountId": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/banking/users/{userId}/equals-banking-infoGet Banking banking information for a specific user in the authenticated company.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/banking/users/123/equals-banking-info?currency=USD' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123currencyquerystringoptionalExample: USD200OKapplication/json
[
{
"UserId": 123,
"BudgetId": "string",
"AccountId": "string",
"FirstName": "Jane",
"LastName": "Doe",
"UserName": "string",
"MaskedEmail": "user@example.com",
"MaskedPhone": "+447700900123",
"PaymentType": "string",
"PaymentMethod": "string",
"Currency": "USD",
"Country": "GB",
"AccountNumber": "string",
"BankName": "string",
"RoutingCodes": [
{
"RoutingCodeType": "string",
"RoutingCodeValue": "string"
}
],
"BankAddress": {
"Country": "GB",
"City": "London",
"State": "string",
"PostalCode": "SW1A 1AA",
"AddressLine1": "string",
"AddressLine2": "string"
},
"PayeeAddress": {
"Country": "GB",
"City": "London",
"State": "string",
"PostalCode": "SW1A 1AA",
"AddressLine1": "string",
"AddressLine2": "string"
}
}
]400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/banking/balanceGet aggregated balance across all banking providersRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/banking/balance?userId=123¤cy=USD' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123currencyquerystringoptionalExample: USD200OKUnifiedBalanceResponse
{
"Balances": [
{
"AccountId": "string",
"Currency": "USD",
"Available": 100,
"Current": 100,
"Provider": "EqualsMoney",
"UpdatedAt": "2026-08-05T09:30:00Z"
}
],
"TotalAvailableUsd": 100
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/banking/transactionsGet transactions across all banking providersRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/banking/transactions?Currency=USD&TradeId=123&From=2026-08-05T09%3A30%3A00Z&To=2026-08-05T09%3A30%3A00Z&Page=1&PageSize=1' \
-H 'x-api-key: YOUR_API_KEY'Parameters
CurrencyquerystringoptionalExample: USDTradeIdquerystringoptionalExample: 123FromquerystringoptionalExample: 2026-08-05T09:30:00ZToquerystringoptionalExample: 2026-08-05T09:30:00ZPagequeryintegeroptionalExample: 1PageSizequeryintegeroptionalExample: 1ProviderquerystringoptionalExample: EqualsMoneyuserIdqueryintegeroptionalExample: 123200OKUnifiedTransactionsResponse
{
"Transactions": [
{
"TransactionId": "string",
"TradeId": "string",
"AccountId": "string",
"Type": "string",
"Amount": 100,
"Currency": "USD",
"Description": "Example description",
"Status": "PENDING",
"Provider": "EqualsMoney",
"CreatedAt": "2026-08-05T09:30:00Z"
}
],
"Total": 1,
"Page": 1,
"PageSize": 1
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/banking/users/{userId}/budgetsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/banking/users/123/budgets' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123200OKUserBudgetListResponse
{
"UserId": 123,
"Total": 1,
"Budgets": [
{
"BudgetId": "string",
"AccountId": "string",
"Name": "string",
"Type": "string",
"ParentId": "string",
"Status": "PENDING",
"AllowCurrencyAlignment": true,
"Currencies": [
"string"
],
"Balances": [
{
"Currency": "USD",
"AvailableBalance": 100,
"LedgerBalance": 100,
"PendingBalance": 100
}
],
"SettlementDetails": {
"BalanceReference": "100.00",
"CurrencyDetails": [
{}
]
},
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}
]
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/users/{userId}/budgetsOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/banking/users/123/budgets' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Name": "string",
"Currencies": [
"string"
],
"Type": "string",
"Features": [
"string"
],
"AllowCurrencyAlignment": true
}'Parameters
userIdpathintegerrequiredExample: 123Request fields and validation
Name · string · requiredBudget display name.
Maximum length: 75
Currencies · array · requiredISO 4217 currency codes enabled for the budget, for example EUR or GBP.
Type · string or null · optionalOptional requested budget type. Banking personal accounts are created as individual budgets and business accounts as shared budgets.
Features · array or null · optionalOptional budget features. Supported value: peopleCards.
AllowCurrencyAlignment · boolean or null · optionalExample request body · replace placeholders
{
"Name": "string",
"Currencies": [
"string"
],
"Type": "string",
"Features": [
"string"
],
"AllowCurrencyAlignment": true
}201CreatedUserBudgetResponse
{
"BudgetId": "string",
"AccountId": "string",
"Name": "string",
"Type": "string",
"ParentId": "string",
"Status": "PENDING",
"AllowCurrencyAlignment": true,
"Currencies": [
"string"
],
"Balances": [
{
"Currency": "USD",
"AvailableBalance": 100,
"LedgerBalance": 100,
"PendingBalance": 100
}
],
"SettlementDetails": {
"BalanceReference": "100.00",
"CurrencyDetails": [
{
"CurrencyCode": "USD",
"Local": {},
"International": {}
}
]
},
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/banking/users/{userId}/budgets/{budgetId}Open request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/banking/users/123/budgets/123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123budgetIdpathstringrequiredExample: 123200OKUserBudgetResponse
{
"BudgetId": "string",
"AccountId": "string",
"Name": "string",
"Type": "string",
"ParentId": "string",
"Status": "PENDING",
"AllowCurrencyAlignment": true,
"Currencies": [
"string"
],
"Balances": [
{
"Currency": "USD",
"AvailableBalance": 100,
"LedgerBalance": 100,
"PendingBalance": 100
}
],
"SettlementDetails": {
"BalanceReference": "100.00",
"CurrencyDetails": [
{
"CurrencyCode": "USD",
"Local": {},
"International": {}
}
]
},
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/banking/users/{userId}/budgets/{budgetId}Updates user-editable budget details. Budget status is managed by Banking and is read-only.Request & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/banking/users/123/budgets/123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Name": "string",
"AllowCurrencyAlignment": true
}'Parameters
userIdpathintegerrequiredExample: 123budgetIdpathstringrequiredExample: 123Request fields and validation
Name · string or null · optionalBudget display name.
Maximum length: 75
AllowCurrencyAlignment · boolean or null · optionalWhether to allow currency alignment.
Example request body · replace placeholders
{
"Name": "string",
"AllowCurrencyAlignment": true
}200OKUserBudgetResponse
{
"BudgetId": "string",
"AccountId": "string",
"Name": "string",
"Type": "string",
"ParentId": "string",
"Status": "PENDING",
"AllowCurrencyAlignment": true,
"Currencies": [
"string"
],
"Balances": [
{
"Currency": "USD",
"AvailableBalance": 100,
"LedgerBalance": 100,
"PendingBalance": 100
}
],
"SettlementDetails": {
"BalanceReference": "100.00",
"CurrencyDetails": [
{
"CurrencyCode": "USD",
"Local": {},
"International": {}
}
]
},
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/users/{userId}/budgets/{budgetId}/transferOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/banking/users/123/budgets/123/transfer' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"DestinationBudgetId": "string",
"Amount": 100,
"Currency": "USD",
"Reference": "external_reference_123"
}'Parameters
userIdpathintegerrequiredExample: 123budgetIdpathstringrequiredExample: 123Request fields and validation
DestinationBudgetId · string · requiredAmount · number · requiredMinimum: 0.01
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Currency · string · requiredMinimum length: 3
Maximum length: 3
Pattern: ^[A-Za-z]{3}$
Reference · string or null · optionalMinimum length: 0
Maximum length: 200
Example request body · replace placeholders
{
"DestinationBudgetId": "string",
"Amount": 100,
"Currency": "USD",
"Reference": "external_reference_123"
}200OKUserBudgetTransferResponse
{
"Success": true,
"TransferId": "string",
"SourceBudgetId": "string",
"DestinationBudgetId": "string",
"Currency": "USD",
"Amount": "100.00",
"Reference": "external_reference_123"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/banking/payeesList payees across all banking providersRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/banking/payees?Limit=1&Page=1&Currency=USD&SearchName=example&userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
LimitqueryintegeroptionalExample: 1PagequeryintegeroptionalExample: 1CurrencyquerystringoptionalExample: USDSearchNamequerystringoptionalExample: exampleuserIdqueryintegeroptionalExample: 123200OKUnifiedPayeesResponse
{
"Payees": [
{
"PayeeId": 123,
"Name": "string",
"BankName": "string",
"Currency": "USD",
"AccountNumber": "string",
"Iban": "string",
"Status": "PENDING",
"Providers": [
"EqualsMoney"
],
"ProviderRecords": [
{
"Provider": "EqualsMoney",
"ExternalPayeeId": "external_reference_123",
"LocalPayeeId": 123
}
],
"CreatedAt": "2026-08-05T09:30:00Z"
}
],
"Total": 1,
"Page": 1,
"Limit": 1
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/payeesPayee Step 1: validate a new payee and send the OTP required by Banking.Request & responses +
This endpoint does not create the payee immediately. Banking requires recipient OTP approval before creation.
curl --request POST 'https://staging.hoppa.global/api/v2/banking/payees?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"PaymentType": "COMPANY",
"Currency": "USD",
"ApprovalDeviceId": "00000000-0000-4000-8000-000000000123",
"ApprovalPasskeyId": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"AccountNumber": "string",
"Iban": "string",
"Bic": "string",
"BankCode": "string",
"BankName": "string",
"FirstName": "Jane",
"LastName": "Doe",
"RoutingCodeList": [
{
"RoutingCodeType": "string",
"RoutingCodeValue": "string"
}
],
"routingCodes": [
{
"RoutingCodeType": "string",
"RoutingCodeValue": "string"
}
],
"BankAddress": {
"Country": "GB",
"City": "London",
"State": "string",
"PostalCode": "SW1A 1AA",
"AddressLine1": "string",
"AddressLine2": "string"
},
"PayeeAddress": {
"Country": "GB",
"City": "London",
"State": "string",
"PostalCode": "SW1A 1AA",
"AddressLine1": "string",
"AddressLine2": "string"
},
"Comments": "string",
"PaymentMethod": "SWIFT",
"VerificationMethod": "string"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
ApprovalDeviceId · string or null · optionalPublic banking API only. Omit for email OTP; never itself proof of approval.
ApprovalPasskeyId · string or null · optionalName · string or null · optionalRecipient display name. For INDIVIDUAL this is split into FirstName/LastName when those fields are omitted. Recipient display name. Matches required-fields fieldName "name".
PaymentType · string · requiredAllowed values: COMPANY, INDIVIDUAL.
Allowed: COMPANY, INDIVIDUAL
Currency · string · requiredAccountNumber · string or null · optionalIban · string or null · optionalIBAN alias for AccountNumber. If AccountNumber is omitted, Iban is used as the account identifier. Alias for AccountNumber. If AccountNumber is omitted, Iban is used as the account identifier.
Bic · string or null · optionalBIC/SWIFT alias used when required-fields returns bic. BIC/SWIFT alias. Matches required-fields fieldName "bic".
BankCode · string or null · optionalBank code alias used when required-fields returns bankCode. Bank code alias. Matches required-fields fieldName "bankCode".
BankName · string or null · optionalFirstName · string or null · optionalLastName · string or null · optionalRoutingCodeList · array or null · optionalroutingCodes · array or null · optionalDashboard/public API alias for RoutingCodeList.
BankAddress · object or null · optionalPayeeAddress · object or null · optionalComments · string or null · optionalPaymentMethod · string or null · optionalSupported values: SWIFT, SEPA.INSTANT, SEPA.CREDITTRANSFER, CHAPS, UKFPS, ACH, WIRETRANSFER, OFF_PLATFORM. Allowed values: SWIFT, SEPA.INSTANT, SEPA.CREDITTRANSFER, CHAPS, UKFPS, ACH, WIRETRANSFER, OFF_PLATFORM.
Allowed: SWIFT, SEPA.INSTANT, SEPA.CREDITTRANSFER, CHAPS, UKFPS, ACH, WIRETRANSFER, OFF_PLATFORM
VerificationMethod · string or null · optionalExample request body · replace placeholders
{
"PaymentType": "COMPANY",
"Currency": "USD",
"ApprovalDeviceId": "00000000-0000-4000-8000-000000000123",
"ApprovalPasskeyId": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"AccountNumber": "string",
"Iban": "string",
"Bic": "string",
"BankCode": "string",
"BankName": "string",
"FirstName": "Jane",
"LastName": "Doe",
"RoutingCodeList": [
{
"RoutingCodeType": "string",
"RoutingCodeValue": "string"
}
],
"routingCodes": [
{
"RoutingCodeType": "string",
"RoutingCodeValue": "string"
}
],
"BankAddress": {
"Country": "GB",
"City": "London",
"State": "string",
"PostalCode": "SW1A 1AA",
"AddressLine1": "string",
"AddressLine2": "string"
},
"PayeeAddress": {
"Country": "GB",
"City": "London",
"State": "string",
"PostalCode": "SW1A 1AA",
"AddressLine1": "string",
"AddressLine2": "string"
},
"Comments": "string",
"PaymentMethod": "SWIFT",
"VerificationMethod": "string"
}202AcceptedPayeeInitiateResponse
{
"Approval": {
"VerificationToken": "PLACEHOLDER_TOKEN",
"DeviceId": "00000000-0000-4000-8000-000000000123",
"Operation": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"SigningPayload": "string",
"DetailsJson": "string",
"TermsJson": "string",
"Algorithm": "ECDSA_P256_SHA256_DER",
"PublicKey": {}
},
"TermsJson": "string",
"Success": true,
"VerificationToken": "PLACEHOLDER_TOKEN",
"Message": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"RecipientName": "string",
"AccountNumberLast4": "string",
"VerificationResult": {
"Status": "PENDING",
"Title": "string",
"Message": "string",
"ReasonCode": "string",
"NameMatch": true,
"CanProceed": true
}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/payees/confirmPayee Step 2: create and confirm the payee after OTP verification.Request & responses +
Use the VerificationToken returned from POST /api/v2/banking/payees after it has been verified through POST /api/v2/banking/otp/verify.
curl --request POST 'https://staging.hoppa.global/api/v2/banking/payees/confirm?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"VerificationToken": "PLACEHOLDER_TOKEN"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
VerificationToken · string · requiredExample request body · replace placeholders
{
"VerificationToken": "PLACEHOLDER_TOKEN"
}201CreatedPayeeResponse
{
"Id": 123,
"ExternalId": "external_reference_123",
"FirstName": "Jane",
"LastName": "Doe",
"UserName": "string",
"PaymentType": "string",
"PaymentMethod": "string",
"Currency": "USD",
"AccountNumber": "string",
"BankName": "string",
"RoutingCodeList": [
{
"RoutingCodeType": "string",
"RoutingCodeValue": "string"
}
],
"routingCodes": [
{
"RoutingCodeType": "string",
"RoutingCodeValue": "string"
}
],
"BankAddress": {
"Country": "GB",
"City": "London",
"State": "string",
"PostalCode": "SW1A 1AA",
"AddressLine1": "string",
"AddressLine2": "string"
},
"PayeeAddress": {
"Country": "GB",
"City": "London",
"State": "string",
"PostalCode": "SW1A 1AA",
"AddressLine1": "string",
"AddressLine2": "string"
},
"Comments": "string",
"Provider": "string",
"RequiresConfirmation": true,
"Status": "PENDING",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/banking/payees/required-fieldsGet required fields for payee creationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/banking/payees/required-fields?PaymentType=example&Currency=USD&Country=GB' \
-H 'x-api-key: YOUR_API_KEY'Parameters
PaymentTypequerystringoptionalExample: exampleCurrencyquerystringoptionalExample: USDCountryquerystringoptionalExample: GB200OKPayeeRequiredFieldsResponse
{
"Data": [
{
"PaymentMethod": "SWIFT",
"Fields": [
{
"FieldName": "string",
"ValidationRules": [
{}
]
}
]
}
]
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
DELETE/api/v2/banking/payees/{payeeId}Delete a payee from ALL banking providers where user has accountsRequest & responses +
curl --request DELETE 'https://staging.hoppa.global/api/v2/banking/payees/123?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
payeeIdpathintegerrequiredExample: 123userIdqueryintegeroptionalExample: 123200OKUnifiedPayeeDeleteResponse
{
"Success": true,
"Results": [
{
"Provider": "EqualsMoney",
"Success": true,
"ExternalPayeeId": "external_reference_123",
"ErrorMessage": "string"
}
]
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/quotationsPayout Step 1: create a quote for an existing payee.Request & responses +
Use this before external payouts. The returned Id is used as QuotationId in POST /api/v2/banking/payouts/check, and QuoteRequestId must be preserved for later payout steps when returned.
curl --request POST 'https://staging.hoppa.global/api/v2/banking/quotations?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"PayeeId": 123,
"FromCurrency": "USD",
"Amount": 100,
"FeeMethod": "100.00",
"BalanceId": "100.00"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
PayeeId · integer · requiredLocal payee ID from the payee list endpoint. Local payee ID from GET /api/v2/banking/payees.
Pattern: ^-?(?:0|[1-9]\d*)$
FromCurrency · string · requiredSource currency to fund the payout from, for example GBP, EUR, or USD. Source currency to fund the payout from, for example GBP, EUR, or USD.
Amount · number · requiredPayout amount.
Minimum: 1e-08
Maximum: 7.922816251426434e+28
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
FeeMethod · string · optionalFee handling method. The dashboard flow sends INCLUDED. Fee handling method. The accounts page uses INCLUDED.
BalanceId · string or null · optionalOptional provider balance or budget ID to fund the payout from. Optional provider balance or Banking budget ID used as funding source.
Example request body · replace placeholders
{
"PayeeId": 123,
"FromCurrency": "USD",
"Amount": 100,
"FeeMethod": "100.00",
"BalanceId": "100.00"
}200OKQuotationResponse
{
"IsAvailable": true,
"UnavailableReason": "string",
"RetryAfterSeconds": 1,
"Id": "string",
"QuoteRequestId": "string",
"Rate": "string",
"Fees": [
{
"Currency": "USD",
"Amount": "100.00",
"FeeType": 1
}
],
"ExpirationTime": "string",
"CreateTime": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/payouts/checkPayout Step 2: check the quoted payout before OTP approval.Request & responses +
Send the quote Id from POST /api/v2/banking/quotations as QuotationId. The returned CheckId is used in POST /api/v2/banking/payouts/initiate.
curl --request POST 'https://staging.hoppa.global/api/v2/banking/payouts/check?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"PayeeId": 123,
"QuotationId": "string",
"Amount": "100.00",
"Currency": "USD",
"BalanceId": "100.00",
"Memo": "Example description",
"Reason": "string"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
PayeeId · integer · requiredLocal payee ID from the payee list endpoint. Local payee ID from GET /api/v2/banking/payees.
Pattern: ^-?(?:0|[1-9]\d*)$
QuotationId · string · requiredQuotation Id returned by POST /api/v2/banking/quotations. Quotation Id returned by POST /api/v2/banking/quotations.
Amount · string · requiredPayout amount as a decimal string.
Currency · string · requiredPayout currency, usually the payee currency.
BalanceId · string or null · optionalOptional provider balance or budget ID to fund the payout from. Optional provider balance or Banking budget ID used as funding source.
Memo · string or null · optionalOptional memo/reference for the payout.
Reason · string or null · optionalOptional payout reason.
Example request body · replace placeholders
{
"PayeeId": 123,
"QuotationId": "string",
"Amount": "100.00",
"Currency": "USD",
"BalanceId": "100.00",
"Memo": "Example description",
"Reason": "string"
}200OKCheckPayoutResponse
{
"CheckId": "string",
"Pass": true,
"DetailMessage": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/payouts/initiatePayout Step 3: send the OTP for a checked payout.Request & responses +
Send the CheckId from POST /api/v2/banking/payouts/check. The VerificationToken returned here must be verified through POST /api/v2/banking/otp/verify before calling POST /api/v2/banking/payouts.
curl --request POST 'https://staging.hoppa.global/api/v2/banking/payouts/initiate?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"CheckId": "string",
"PayeeId": 123,
"Amount": "100.00",
"Currency": "USD",
"ApprovalDeviceId": "00000000-0000-4000-8000-000000000123",
"ApprovalPasskeyId": "00000000-0000-4000-8000-000000000123",
"QuoteRequestId": "string",
"FromCurrency": "USD",
"BalanceId": "100.00"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
ApprovalDeviceId · string or null · optionalPublic banking API only. Omit for email OTP; an enrolled device ID requests a signed challenge.
ApprovalPasskeyId · string or null · optionalCheckId · string · requiredCheckId from POST /api/v2/banking/payouts/check. If the quote is refreshed on the OTP screen, send the latest quote/order ID here. CheckId returned by POST /api/v2/banking/payouts/check. When refreshing quotes during OTP, send the latest quote/order ID here.
QuoteRequestId · string or null · optionalQuoteRequestId returned by POST /api/v2/banking/quotations. QuoteRequestId returned by POST /api/v2/banking/quotations.
PayeeId · integer · requiredLocal payee ID from the payee list endpoint. Local payee ID from GET /api/v2/banking/payees.
Pattern: ^-?(?:0|[1-9]\d*)$
Amount · string · requiredPayout amount as a decimal string.
Currency · string · requiredPayout currency, usually the payee currency.
FromCurrency · string or null · optionalCurrency to fund the payout from. When omitted, the payout currency is used. This must reflect the currency selected by the caller, because a Banking budget can hold multiple currencies under the same budget ID.
Minimum length: 3
Maximum length: 3
BalanceId · string or null · optionalOptional provider balance or budget ID to fund the payout from. Optional provider balance or Banking budget ID used as funding source.
Example request body · replace placeholders
{
"CheckId": "string",
"PayeeId": 123,
"Amount": "100.00",
"Currency": "USD",
"ApprovalDeviceId": "00000000-0000-4000-8000-000000000123",
"ApprovalPasskeyId": "00000000-0000-4000-8000-000000000123",
"QuoteRequestId": "string",
"FromCurrency": "USD",
"BalanceId": "100.00"
}200OKPayoutInitiateResponse
{
"Approval": {
"VerificationToken": "PLACEHOLDER_TOKEN",
"DeviceId": "00000000-0000-4000-8000-000000000123",
"Operation": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"SigningPayload": "string",
"DetailsJson": "string",
"TermsJson": "string",
"Algorithm": "ECDSA_P256_SHA256_DER",
"PublicKey": {}
},
"TermsJson": "string",
"Success": true,
"VerificationToken": "PLACEHOLDER_TOKEN",
"Message": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"RecipientName": "string",
"Amount": 100,
"Currency": "USD"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/banking/payoutsList payout transactions for the authenticated user or API-key selected user.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/banking/payouts?limit=10&page=1¤cy=USD&clientTransactionId=123&userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
limitqueryintegeroptionalExample: 10pagequeryintegeroptionalExample: 1currencyquerystringoptionalExample: USDclientTransactionIdquerystringoptionalExample: 123userIdqueryintegeroptionalExample: 123200OKPayoutListResponse
{
"Total": 1,
"List": [
{
"Id": 123,
"ExternalId": "external_reference_123",
"ClientTransactionId": "string",
"BusinessId": "string",
"BusinessTypeCode": 1,
"BalanceId": "100.00",
"PayeeId": 123,
"FromAmount": "100.00",
"FromCurrency": "USD",
"ToAmount": "100.00",
"ToCurrency": "USD",
"Status": "PENDING",
"Message": "string",
"Refund": {
"Amount": "100.00",
"Currency": "USD"
},
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"Fees": [
{
"Currency": "USD",
"Amount": "100.00",
"FeeType": 1
}
]
}
]
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/payoutsPayout Step 4: create the payout after OTP verification.Request & responses +
Use the VerificationToken returned from POST /api/v2/banking/payouts/initiate after it has been verified by POST /api/v2/banking/otp/verify. New public Banking approvals use the server quote captured at initiation. Changed or expired terms require a new initiation and approval. This unified payout route requires the existing verified approval for company API-key callers as well as JWT callers. Approval is bound to PAYOUT_CREATE and the stored payee, amount and currency. A token issued for another operation cannot authorize a payout. The existing permitted CheckId/QuoteRequestId refresh during email payout confirmation remains supported.
curl --request POST 'https://staging.hoppa.global/api/v2/banking/payouts?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"CheckId": "string",
"PayeeId": 123,
"Amount": "100.00",
"Currency": "USD",
"VerificationToken": "PLACEHOLDER_TOKEN",
"ApprovalDeviceId": "00000000-0000-4000-8000-000000000123",
"ApprovalPasskeyId": "00000000-0000-4000-8000-000000000123",
"QuoteRequestId": "string",
"FromCurrency": "USD",
"BalanceId": "100.00"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
VerificationToken · string or null · optionalToken returned by POST /api/v2/banking/payouts/initiate after it has been verified through the OTP endpoint. Required for POST /api/v2/banking/payouts. Token returned by POST /api/v2/banking/payouts/initiate after it has been verified through the OTP endpoint. Required for final payout creation.
ApprovalDeviceId · string or null · optionalPublic banking API only. Omit for email OTP; an enrolled device ID requests a signed challenge.
ApprovalPasskeyId · string or null · optionalCheckId · string · requiredCheckId from POST /api/v2/banking/payouts/check. If the quote is refreshed on the OTP screen, send the latest quote/order ID here. CheckId returned by POST /api/v2/banking/payouts/check. When refreshing quotes during OTP, send the latest quote/order ID here.
QuoteRequestId · string or null · optionalQuoteRequestId returned by POST /api/v2/banking/quotations. QuoteRequestId returned by POST /api/v2/banking/quotations.
PayeeId · integer · requiredLocal payee ID from the payee list endpoint. Local payee ID from GET /api/v2/banking/payees.
Pattern: ^-?(?:0|[1-9]\d*)$
Amount · string · requiredPayout amount as a decimal string.
Currency · string · requiredPayout currency, usually the payee currency.
FromCurrency · string or null · optionalCurrency to fund the payout from. When omitted, the payout currency is used. This must reflect the currency selected by the caller, because a Banking budget can hold multiple currencies under the same budget ID.
Minimum length: 3
Maximum length: 3
BalanceId · string or null · optionalOptional provider balance or budget ID to fund the payout from. Optional provider balance or Banking budget ID used as funding source.
Example request body · replace placeholders
{
"CheckId": "string",
"PayeeId": 123,
"Amount": "100.00",
"Currency": "USD",
"VerificationToken": "PLACEHOLDER_TOKEN",
"ApprovalDeviceId": "00000000-0000-4000-8000-000000000123",
"ApprovalPasskeyId": "00000000-0000-4000-8000-000000000123",
"QuoteRequestId": "string",
"FromCurrency": "USD",
"BalanceId": "100.00"
}201CreatedCreatePayoutResponse
{
"Id": 123,
"ExternalId": "external_reference_123",
"ClientTransactionId": "string",
"Status": "PENDING",
"Message": "string",
"FromAmount": "100.00",
"FromCurrency": "USD",
"ToAmount": "100.00",
"ToCurrency": "USD",
"Fees": [
{
"Currency": "USD",
"Amount": "100.00",
"FeeType": 1
}
],
"CreatedAt": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/banking/payouts/{payoutId}Get a payout transaction by ID for the authenticated user or API-key selected user.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/banking/payouts/123?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
payoutIdpathintegerrequiredExample: 123userIdqueryintegeroptionalExample: 123200OKPayoutResponse
{
"Id": 123,
"ExternalId": "external_reference_123",
"ClientTransactionId": "string",
"BusinessId": "string",
"BusinessTypeCode": 1,
"BalanceId": "100.00",
"PayeeId": 123,
"FromAmount": "100.00",
"FromCurrency": "USD",
"ToAmount": "100.00",
"ToCurrency": "USD",
"Status": "PENDING",
"Message": "string",
"Refund": {
"Amount": "100.00",
"Currency": "USD"
},
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"Fees": [
{
"Currency": "USD",
"Amount": "100.00",
"FeeType": 1
}
]
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/otp/verifyVerify an OTP code for a pending banking operation such as payout creation.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/banking/otp/verify?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"VerificationToken": "PLACEHOLDER_TOKEN",
"OtpCode": "string"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
VerificationToken · string · optionalVerification token received when OTP was initiated
OtpCode · string · optional8-digit OTP code from email
Example request body · replace placeholders
{
"VerificationToken": "PLACEHOLDER_TOKEN",
"OtpCode": "string"
}200OKOtpVerifyResponse
{
"Success": true,
"Message": "string",
"ErrorCode": "string",
"VerificationToken": "PLACEHOLDER_TOKEN",
"RemainingAttempts": 1,
"IsExpired": true,
"IsLocked": true
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/otp/resendResend the OTP code for a pending banking operation.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/banking/otp/resend?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"VerificationToken": "PLACEHOLDER_TOKEN"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
VerificationToken · string · optionalVerification token received when OTP was initiated
Example request body · replace placeholders
{
"VerificationToken": "PLACEHOLDER_TOKEN"
}200OKOtpResendResponse
{
"Success": true,
"Message": "string",
"ExpiresAt": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/transfers/internalExecute an internal transfer between balances for a specific user within the authenticated company.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/banking/transfers/internal' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"SourceBalanceId": "100.00",
"DestinationBalanceId": "100.00",
"Amount": 100,
"Currency": "USD",
"Reference": "external_reference_123"
}'Request fields and validation
UserId · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
SourceBalanceId · string · requiredDestinationBalanceId · string · requiredAmount · number · requiredMinimum: 0.01
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Currency · string · requiredMinimum length: 3
Maximum length: 3
Pattern: ^[A-Za-z]{3}$
Reference · string or null · optionalMinimum length: 0
Maximum length: 200
Example request body · replace placeholders
{
"UserId": 123,
"SourceBalanceId": "100.00",
"DestinationBalanceId": "100.00",
"Amount": 100,
"Currency": "USD",
"Reference": "external_reference_123"
}201CreatedUnifiedTransferResponse
{
"Success": true,
"TransferId": "string",
"Status": "PENDING",
"Amount": 100,
"Currency": "USD",
"Provider": "EqualsMoney",
"CreatedAt": "2026-08-05T09:30:00Z",
"ErrorMessage": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/quotesGet a quote for a transferRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/banking/quotes?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"SourceAccountId": "string",
"PayeeId": 123,
"Amount": 100,
"SourceCurrency": "USD",
"TargetCurrency": "USD"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
SourceAccountId · string · optionalPayeeId · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
Amount · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
SourceCurrency · string · optionalTargetCurrency · string · optionalExample request body · replace placeholders
{
"SourceAccountId": "string",
"PayeeId": 123,
"Amount": 100,
"SourceCurrency": "USD",
"TargetCurrency": "USD"
}200OKUnifiedQuoteResponse
{
"QuoteId": "string",
"SourceAmount": 100,
"SourceCurrency": "USD",
"TargetAmount": 100,
"TargetCurrency": "USD",
"ExchangeRate": 100,
"Fee": 100,
"Provider": "EqualsMoney",
"ExpiresAt": "2026-08-05T09:30:00Z"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/orders/quoteOpen request and response documentationRequest & responses +
Company API-key integrations retain raw Banking quote execution; accountId must belong to the key's company even when optional userId is omitted. When userId is supplied, the account must belong to that selected company user. JWT callers can quote only balance-to-balance conversion (type.from=balance and type.to=balance) with no recipientId and owned sourceCurrency.currency.budgetId and targetCurrency.currency.budgetId. JWT payment quotes must use the approved banking payout flow. Keep both existing orderId and quoteRequestId from the response for trade execution; the JWT conversion binding expires after two minutes.
curl --request POST 'https://staging.hoppa.global/api/v2/banking/orders/quote?accountId=123&userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"sourceCurrency": {
"amount": 100,
"currency": {
"budgetId": "string",
"currencyCode": "USD"
}
},
"targetCurrency": {
"amount": 100,
"currency": {
"budgetId": "string",
"currencyCode": "USD"
}
},
"settlementDate": "20260505",
"type": {
"from": "balance",
"to": "payment",
"recipientId": "string"
}
}'Parameters
accountIdquerystringoptionalExample: 123userIdqueryintegeroptionalExample: 123Request fields and validation
sourceCurrency · object · optionalCurrency details for quote request
targetCurrency · object · optionalCurrency details for quote request
settlementDate · string · optionalSettlement date in yyyyMMdd format, for example 20260505. The public API also accepts yyyy-MM-dd and converts it before calling Banking. Preferred format: yyyyMMdd, for example 20260505. The public API also accepts yyyy-MM-dd and converts it before calling Banking.
Pattern: ^(\d{8}|\d{4}-\d{2}-\d{2})$
type · object · optionalQuote type information
Example request body · replace placeholders
{
"sourceCurrency": {
"amount": 100,
"currency": {
"budgetId": "string",
"currencyCode": "USD"
}
},
"targetCurrency": {
"amount": 100,
"currency": {
"budgetId": "string",
"currencyCode": "USD"
}
},
"settlementDate": "20260505",
"type": {
"from": "balance",
"to": "payment",
"recipientId": "string"
}
}200OKEqualsMoneyQuoteResponse
{
"orderId": "string",
"quoteRequestId": "string",
"settlement": {
"date": "2026-08-05",
"price": {
"amount": 100,
"currency": "USD"
},
"charges": {
"fee": 100,
"margin": 100,
"other": 100
}
},
"quote": {
"rate": 100,
"inverseRate": 100,
"fromGbpAmount": 100,
"from": {
"amount": 100,
"currency": "USD"
},
"to": {
"amount": 100,
"currency": "USD"
},
"direction": 1
}
}400INVALID_REQUEST for missing owned budget IDs or invalid request; provider validation errors retain their validation code.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404NOT_FOUND: account/user is outside the company or a JWT conversion budget is not owned by the user.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}503Service UnavailableErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}403APPROVED_BANKING_FLOW_REQUIRED: JWT payment quote/recipient requires the approved payout flow.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/orders/tradeOpen request and response documentationRequest & responses +
Company API-key integrations retain raw Banking trade execution for an authorized company account, with optional selected userId. JWT conversions must send both existing orderId and quoteRequestId from that user's prior conversion quote, without payments or moveMoneyRequestId. A completed conversion replay returns its stored receipt. An in-progress or uncertain submission cannot dispatch again; reconcile it. The quote binding does not introduce an OTP field or change the company API-key flow.
curl --request POST 'https://staging.hoppa.global/api/v2/banking/orders/trade?accountId=123&userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"orderId": "string",
"quoteRequestId": "string",
"moveMoneyRequestId": "string",
"payments": {
"amount": 100,
"currency": {
"budgetId": "string",
"currencyCode": "USD"
},
"recipientId": "string",
"internalReference": "external_reference_123",
"externalReference": "external_reference_123"
}
}'Parameters
accountIdquerystringoptionalExample: 123userIdqueryintegeroptionalExample: 123Request fields and validation
orderId · string · optionalOrder ID returned by the quote response. This identifies the provider quote/order to execute. OrderId returned by POST /api/v2/banking/orders/quote. For JWT conversions, must match the authenticated user's prior quote together with quoteRequestId; binding expires after two minutes. Company API-key raw trade execution remains supported.
quoteRequestId · string · optionalQuote request ID returned by the quote response. This is different from OrderId and must be sent back with the trade request. QuoteRequestId returned by POST /api/v2/banking/orders/quote. This is separate from OrderId. For JWT conversions, send the existing quoteRequestId together with orderId from that user's quote. This is not a new approval-token field.
moveMoneyRequestId · string or null · optionalOptional move-money request ID. Omit it unless the upstream quote/payment flow returned one. Optional. Omit unless the upstream quote/payment flow returned a moveMoneyRequestId. Omit for JWT conversions; supplying a nonblank value returns 403 APPROVED_BANKING_FLOW_REQUIRED. Existing company API-key provider flow remains supported.
payments · object or null · optionalCompany API-key payment flow only on the raw order route. Omit for JWT conversions; supplying it returns 403 APPROVED_BANKING_FLOW_REQUIRED.
Example request body · replace placeholders
{
"orderId": "string",
"quoteRequestId": "string",
"moveMoneyRequestId": "string",
"payments": {
"amount": 100,
"currency": {
"budgetId": "string",
"currencyCode": "USD"
},
"recipientId": "string",
"internalReference": "external_reference_123",
"externalReference": "external_reference_123"
}
}200OKEqualsMoneyTradeResponse
{
"orderId": "string",
"bank": "string",
"settlement": {
"date": "2026-08-05",
"price": {
"amount": 100,
"currency": "USD"
},
"charges": {
"fee": 100,
"margin": 100,
"other": 100
}
},
"trade": {
"rate": 100,
"inverseRate": 100,
"from": {
"amount": 100,
"currency": "USD"
},
"to": {
"amount": 100,
"currency": "USD"
}
}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404NOT_FOUND: account/user is outside the company or a JWT conversion budget is not owned by the user.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}403APPROVED_BANKING_FLOW_REQUIRED for JWT payment execution, or CONVERSION_QUOTE_REQUIRED when no owned conversion quote matches both IDs.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}409CONVERSION_QUOTE_EXPIRED after two minutes, or CONVERSION_IN_PROGRESS for an already submitted, uncertain or concurrent conversion.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/budgets/{budgetId}/transferOpen request and response documentationRequest & responses +
Company API-key requests require the target userId query parameter. The selected account and source/target budgets must belong to that company user. JWT requests use the authenticated user and owned source/target budgets.
curl --request POST 'https://staging.hoppa.global/api/v2/banking/budgets/123/transfer?accountId=123&userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"destinationBudgetId": "string",
"currency": "USD",
"amount": "100.00",
"reference": "external_reference_123"
}'Parameters
budgetIdpathstringrequiredExample: 123accountIdquerystringoptionalExample: 123userIdqueryintegeroptionalExample: 123Request fields and validation
destinationBudgetId · string · optionalDestination budget ID for the transfer
currency · string · optionalCurrency code for the transfer (e.g., USD, GBP, EUR)
amount · string · optionalAmount to transfer
reference · string · optionalReference for the transfer
Example request body · replace placeholders
{
"destinationBudgetId": "string",
"currency": "USD",
"amount": "100.00",
"reference": "external_reference_123"
}200OKEqualsMoneyTransferResponse
{
"success": true,
"debitBoxTransactionId": {},
"creditBoxTransactionId": {}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/trades/quoteGet FX trade quoteRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/banking/trades/quote?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"AccountId": "string",
"BaseCurrency": "USD",
"QuoteCurrency": "USD",
"Amount": 100,
"Side": "buy"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
AccountId · string · optionalBaseCurrency · string · optionalQuoteCurrency · string · optionalAmount · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Side · string · optionalAllowed values: buy, sell. Allowed values: buy, sell.
Allowed: buy, sell
Example request body · replace placeholders
{
"AccountId": "string",
"BaseCurrency": "USD",
"QuoteCurrency": "USD",
"Amount": 100,
"Side": "buy"
}200OKUnifiedTradeQuoteResponse
{
"QuoteId": "string",
"BaseCurrency": "USD",
"QuoteCurrency": "USD",
"Amount": 100,
"QuoteAmount": 100,
"ExchangeRate": 100,
"Provider": "EqualsMoney",
"ExpiresAt": "2026-08-05T09:30:00Z"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/banking/trades/executeExecute FX tradeRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/banking/trades/execute?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"QuoteId": "string",
"AccountId": "string"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
QuoteId · string · optionalAccountId · string · optionalExample request body · replace placeholders
{
"QuoteId": "string",
"AccountId": "string"
}201CreatedUnifiedTradeResponse
{
"Success": true,
"TradeId": "string",
"Status": "PENDING",
"Amount": 100,
"ReceivedAmount": 100,
"ExchangeRate": 100,
"Provider": "EqualsMoney",
"ExecutedAt": "2026-08-05T09:30:00Z",
"ErrorMessage": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/banking/providersGet list of banking providers the current user has accounts withRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/banking/providers?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123200OKapplication/json
[
"string"
]400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
BusinessOnboarding12 operations
POST/api/v2/business/onboarding/compliance/requirementsOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/business/onboarding/compliance/requirements?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"BusinessType": "string",
"IndustryMain": "string",
"IndustrySub": "string",
"Country": "GB",
"Region": "string",
"Website": "string",
"PromotionDescription": "Example description",
"TaxId": "string",
"IncorporationDate": "2026-08-05T09:30:00Z",
"Addresses": [
{
"addressType": "REGISTERED",
"streetName": "string",
"postcode": "SW1A 1AA",
"city": "London",
"countryCode": "AD",
"buildingNumber": "string",
"buildingName": "string",
"region": "string"
}
],
"PaymentCountries": [
"string"
],
"Compliance": {
"PolicyVersion": "string",
"IsDropshipping": true,
"HasTrustOwnership": true,
"OperationalExpensesOnly": true,
"FundManagerApprovedRegulator": true,
"SourceOfFundsRoute": "string",
"NoWebsiteEvidenceRoute": "string",
"OwnershipExplanation": "string",
"NoProhibitedRegionalExposure": true,
"Answers": {
"FIELD_FROM_APPLICATION": {
"Text": "string",
"NotApplicableReason": "string",
"DocumentIds": [
1
]
}
}
}
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
BusinessType · string · optionalIndustryMain · string · optionalIndustrySub · string · optionalCountry · string · optionalRegion · string or null · optionalWebsite · string or null · optionalPromotionDescription · string or null · optionalTaxId · string or null · optionalIncorporationDate · string · optionalAddresses · array · optionalPaymentCountries · array · optionalCompliance · object · optionalExample request body · replace placeholders
{
"BusinessType": "string",
"IndustryMain": "string",
"IndustrySub": "string",
"Country": "GB",
"Region": "string",
"Website": "string",
"PromotionDescription": "Example description",
"TaxId": "string",
"IncorporationDate": "2026-08-05T09:30:00Z",
"Addresses": [
{
"addressType": "REGISTERED",
"streetName": "string",
"postcode": "SW1A 1AA",
"city": "London",
"countryCode": "AD",
"buildingNumber": "string",
"buildingName": "string",
"region": "string"
}
],
"PaymentCountries": [
"string"
],
"Compliance": {
"PolicyVersion": "string",
"IsDropshipping": true,
"HasTrustOwnership": true,
"OperationalExpensesOnly": true,
"FundManagerApprovedRegulator": true,
"SourceOfFundsRoute": "string",
"NoWebsiteEvidenceRoute": "string",
"OwnershipExplanation": "string",
"NoProhibitedRegionalExposure": true,
"Answers": {
"FIELD_FROM_APPLICATION": {
"Text": "string",
"NotApplicableReason": "string",
"DocumentIds": [
1
]
}
}
}
}200OKBusinessOnboardingComplianceRequirementsResponse
{
"PolicyVersion": "string",
"HighRisk": true,
"Errors": [
"string"
],
"Requirements": [
{
"Id": "string",
"Label": "string",
"DocumentPurpose": "Example description",
"AllowNotApplicable": false
}
],
"eligibilityErrors": [
"string"
],
"requiresDirector": true,
"requiresSoleTraderOwner": true,
"asksOperationalExpenses": true,
"asksFundRegulator": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/business/onboarding/complianceOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/business/onboarding/compliance?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123200OKBusinessOnboardingGetComplianceResponse
{
"profile": {
"BusinessType": "string",
"IndustryMain": "string",
"IndustrySub": "string",
"Country": "GB",
"Region": "string",
"Website": "string",
"PromotionDescription": "Example description",
"TaxId": "string",
"IncorporationDate": "2026-08-05T09:30:00Z",
"Addresses": [
{
"addressType": "REGISTERED",
"streetName": "string",
"postcode": "SW1A 1AA",
"city": "London",
"countryCode": "AD",
"buildingNumber": "string",
"buildingName": "string",
"region": "string"
}
],
"PaymentCountries": [
"string"
],
"Compliance": {
"PolicyVersion": "string",
"IsDropshipping": true,
"HasTrustOwnership": true,
"OperationalExpensesOnly": true,
"FundManagerApprovedRegulator": true,
"SourceOfFundsRoute": "string",
"NoWebsiteEvidenceRoute": "string",
"OwnershipExplanation": "string",
"NoProhibitedRegionalExposure": true,
"Answers": {
"FIELD_FROM_APPLICATION": {
"Text": "string",
"NotApplicableReason": "string",
"DocumentIds": [
{}
]
}
}
}
},
"data": {
"PolicyVersion": "string",
"IsDropshipping": true,
"HasTrustOwnership": true,
"OperationalExpensesOnly": true,
"FundManagerApprovedRegulator": true,
"SourceOfFundsRoute": "string",
"NoWebsiteEvidenceRoute": "string",
"OwnershipExplanation": "string",
"NoProhibitedRegionalExposure": true,
"Answers": {
"FIELD_FROM_APPLICATION": {
"Text": "string",
"NotApplicableReason": "string",
"DocumentIds": [
1
]
}
}
},
"documents": [
{
"complianceDocumentId": 123,
"Purpose": "Example description",
"FileName": "string"
}
],
"application": {},
"people": [
{
"Id": 123,
"UserId": 123,
"ExternalId": "external_reference_123",
"FirstName": "Jane",
"LastName": "Doe",
"Email": "user@example.com",
"DateOfBirth": "2026-08-05",
"Nationalities": "string",
"TaxId": "string",
"Phone": "+447700900123",
"AssociationType": "string",
"JobTitle": "string",
"OwnershipPercentage": 1,
"Address": "string",
"City": "London",
"Region": "string",
"Postcode": "SW1A 1AA",
"Country": "GB",
"IdentityDocumentUploaded": true,
"AddressDocumentUploaded": true,
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"User": {},
"Documents": [
{}
]
}
],
"applicationId": "string",
"status": "PENDING"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/business/onboarding/complianceOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/business/onboarding/compliance?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"PolicyVersion": "string",
"IsDropshipping": true,
"HasTrustOwnership": true,
"OperationalExpensesOnly": true,
"FundManagerApprovedRegulator": true,
"SourceOfFundsRoute": "string",
"NoWebsiteEvidenceRoute": "string",
"OwnershipExplanation": "string",
"NoProhibitedRegionalExposure": true,
"Answers": {
"FIELD_FROM_APPLICATION": {
"Text": "string",
"NotApplicableReason": "string",
"DocumentIds": [
1
]
}
}
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
PolicyVersion · string · optionalIsDropshipping · boolean or null · optionalHasTrustOwnership · boolean or null · optionalOperationalExpensesOnly · boolean or null · optionalFundManagerApprovedRegulator · boolean or null · optionalSourceOfFundsRoute · string · optionalNoWebsiteEvidenceRoute · string · optionalOwnershipExplanation · string or null · optionalNoProhibitedRegionalExposure · boolean or null · optionalAnswers · object · optionalExample request body · replace placeholders
{
"PolicyVersion": "string",
"IsDropshipping": true,
"HasTrustOwnership": true,
"OperationalExpensesOnly": true,
"FundManagerApprovedRegulator": true,
"SourceOfFundsRoute": "string",
"NoWebsiteEvidenceRoute": "string",
"OwnershipExplanation": "string",
"NoProhibitedRegionalExposure": true,
"Answers": {
"FIELD_FROM_APPLICATION": {
"Text": "string",
"NotApplicableReason": "string",
"DocumentIds": [
1
]
}
}
}200OKSuccessResponse
{
"success": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/business/onboarding/compliance/draftOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/business/onboarding/compliance/draft?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"PolicyVersion": "string",
"IsDropshipping": true,
"HasTrustOwnership": true,
"OperationalExpensesOnly": true,
"FundManagerApprovedRegulator": true,
"SourceOfFundsRoute": "string",
"NoWebsiteEvidenceRoute": "string",
"OwnershipExplanation": "string",
"NoProhibitedRegionalExposure": true,
"Answers": {
"FIELD_FROM_APPLICATION": {
"Text": "string",
"NotApplicableReason": "string",
"DocumentIds": [
1
]
}
}
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
PolicyVersion · string · optionalIsDropshipping · boolean or null · optionalHasTrustOwnership · boolean or null · optionalOperationalExpensesOnly · boolean or null · optionalFundManagerApprovedRegulator · boolean or null · optionalSourceOfFundsRoute · string · optionalNoWebsiteEvidenceRoute · string · optionalOwnershipExplanation · string or null · optionalNoProhibitedRegionalExposure · boolean or null · optionalAnswers · object · optionalExample request body · replace placeholders
{
"PolicyVersion": "string",
"IsDropshipping": true,
"HasTrustOwnership": true,
"OperationalExpensesOnly": true,
"FundManagerApprovedRegulator": true,
"SourceOfFundsRoute": "string",
"NoWebsiteEvidenceRoute": "string",
"OwnershipExplanation": "string",
"NoProhibitedRegionalExposure": true,
"Answers": {
"FIELD_FROM_APPLICATION": {
"Text": "string",
"NotApplicableReason": "string",
"DocumentIds": [
1
]
}
}
}200OKSuccessResponse
{
"success": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/business/onboarding/optionsGet canonical Banking KYB onboarding option values for client select fields.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/business/onboarding/options' \
-H 'x-api-key: YOUR_API_KEY'200OKKybOnboardingOptionsResponse
{
"EligibilityPolicyVersion": "string",
"ProhibitedCountries": [
"string"
],
"Markets": [
{
"Key": "string",
"Value": "string"
}
],
"BusinessTypes": [
{
"Key": "string",
"Value": "string"
}
],
"EmployeeCounts": [
{
"Key": "string",
"Value": "string"
}
],
"AssociationTypes": [
{
"Key": "string",
"Value": "string"
}
],
"Industries": [
{
"SubIndustries": [
{
"Key": "string",
"Value": "string"
}
],
"Key": "string",
"Value": "string"
}
],
"RequestedFeatures": [
{
"Key": "string",
"Value": "string"
}
],
"CardPurposes": [
{
"Key": "string",
"Value": "string"
}
],
"CardEstimatedAnnualSpendRanges": [
{
"Key": "string",
"Value": "string"
}
],
"CardCountRanges": [
{
"Key": "string",
"Value": "string"
}
]
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/business/onboarding/applicationGet the current application statusRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/business/onboarding/application?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123200OKEqualsMoneyApplicationResponse
{
"isActionRequired": true,
"id": "string",
"status": "PENDING",
"accountId": "string",
"market": "string",
"type": "string",
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z",
"firstName": "Jane",
"lastName": "Doe",
"dob": "2026-08-05",
"email": "user@example.com",
"phoneNumber": "+447700900123",
"nationalities": [
"string"
],
"identityDocumentNumber": "string",
"taxId": "string",
"countryOfIncorporation": "GB",
"regionOfIncorporation": "string",
"registeredName": "string",
"registrationNumber": "string",
"tradingNames": [
"string"
],
"businessOverview": "string",
"industry": {
"main": "string",
"sub": "string"
},
"employeeCount": "string",
"incorporationDate": "2026-08-05",
"website": "string",
"businessPromotionDescription": "Example description",
"featureInformation": {
"requestedFeatures": [
"CARDS"
],
"cardsInformation": {
"purposes": [
"SALARY_OR_INCOME"
],
"estimatedAnnualSpend": "0-10000",
"atmWithdrawalsRequired": true,
"businessDisplayName": "string",
"numberOfCardsRequired": "0-10",
"cardsAreForEmployees": true
},
"paymentsInformation": {
"purposes": [
"SALARY_OR_INCOME"
],
"estimatedPaymentCount": "FEWER-THAN-5",
"estimatedPaymentVolume": "0-10000",
"inboundCurrencies": [
"AED"
],
"outboundCurrencies": [
"AED"
],
"receivingCountries": [
"AD"
],
"sendingCountries": [
"AD"
],
"accountFundingSource": [
"RECEIVING_FUNDS_FROM_OWN_ACCOUNTS"
]
}
},
"addresses": [
{
"addressType": "REGISTERED",
"streetName": "string",
"postcode": "SW1A 1AA",
"city": "London",
"countryCode": "AD",
"buildingNumber": "string",
"buildingName": "string",
"region": "string"
}
],
"associatedPeople": [
{
"associatedPersonId": "string",
"associationType": "string",
"jobTitle": "string",
"ownershipPercentage": 1
}
]
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/business/onboarding/applicationCreate a business application for KYBRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/business/onboarding/application?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"BusinessType": "PRIVATE_COMPANY",
"CountryOfIncorporation": "AD",
"RegisteredName": "string",
"BusinessOverview": "string",
"IndustryMain": "ACCOMMODATION_FOOD",
"IndustrySub": "ACCOMMODATION",
"EmployeeCount": "ONE_TO_TEN",
"IncorporationDate": "2026-08-05",
"Market": "UK",
"RegionOfIncorporation": "string",
"RegistrationNumber": "string",
"TradingNames": [
"string"
],
"PhoneNumber": "+447700900123",
"TaxId": "string",
"Website": "string",
"BusinessPromotionDescription": "Example description",
"RequestedFeatures": [
"CARDS"
],
"CardsInformation": {
"BusinessDisplayName": "string",
"Purposes": [
"ADVERTISING_AND_MARKETING"
],
"EstimatedAnnualSpend": "0-10000",
"NumberOfCardsRequired": "0-10",
"CardsAreForEmployees": true,
"AtmWithdrawalsRequired": true
},
"PaymentsInformation": {
"Purposes": [
"PAYING_SUPPLIERS"
],
"AccountFundingSource": [
"RECEIVING_FUNDS_FROM_OWN_ACCOUNTS"
],
"EstimatedPaymentCount": "FEWER-THAN-5-PAYMENTS",
"EstimatedPaymentVolume": "0-10000",
"InboundCurrencies": [
"AED"
],
"OutboundCurrencies": [
"AED"
],
"ReceivingCountries": [
"AD"
],
"SendingCountries": [
"AD"
]
},
"Addresses": [
{
"AddressType": "REGISTERED",
"StreetName": "string",
"Postcode": "SW1A 1AA",
"City": "London",
"CountryCode": "AD",
"BuildingNumber": "string",
"BuildingName": "string",
"Region": "string"
}
],
"AssociatedPeople": [
{
"AssociatedPersonId": "string",
"AssociationType": "APPLICANT",
"JobTitle": "string",
"OwnershipPercentage": 1
}
]
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
Market · string or null · optionalPossible values: UK, EU.
Allowed: UK, EU
BusinessType · string · requiredPossible values: PRIVATE_COMPANY, SOLE_TRADER, PUBLIC_COMPANY_LISTED, PUBLIC_COMPANY_UNLISTED, PARTNERSHIP, CHARITY, NON_PROFIT, SOCIAL_ENTERPRISE, PENSION, FUND, TRUST, SEGREGATED_PORTFOLIO_COMPANY, COOPERATIVE, OTHER.
Allowed: PRIVATE_COMPANY, SOLE_TRADER, PUBLIC_COMPANY_LISTED, PUBLIC_COMPANY_UNLISTED, PARTNERSHIP, CHARITY, NON_PROFIT, SOCIAL_ENTERPRISE, PENSION, FUND, TRUST, SEGREGATED_PORTFOLIO_COMPANY, COOPERATIVE, OTHER
CountryOfIncorporation · string · requiredPossible values: AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW.
Allowed: AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW
RegionOfIncorporation · string or null · optionalRequired when CountryOfIncorporation is US, FR, or DE.
RegisteredName · string · requiredRegistrationNumber · string or null · optionalTradingNames · array or null · optionalBusinessOverview · string · requiredIndustryMain · string · requiredPossible values: ACCOMMODATION_FOOD, ADMIN_SUPPORT, ADULT_SERVICES, AGRICULTURE_FORESTRY_FISHING, ARTS_ENTERTAINMENT, CFD_SPREADBETTING, CHARITIES, CONSTRUCTION, CRYPTO_ASSETS, EDUCATION, ENERGY_FOSSIL_FUELS, EXTRATERRITORIAL_ORGS, FINANCIAL_AND_INSURANCE_ACTIVITIES, GOVERNMENT, HEALTH_SOCIAL_WORK, HOUSEHOLD_ACTIVITIES, INFORMATION_AND_COMMUNICATION, MANUFACTURING, MARINE_VESSELS, MINING_AND_QUARRYING, MOTOR_VEHICLES, OTHER_SERVICES_ACTIVITIES, PHARMACEUTICALS, PROFESSIONAL_TECHNICAL, PUBLIC_ADMINISTRATION_AND_DEFENCE, PUBLIC_ADMIN_DEFENCE, REAL_ESTATE_ACTIVITIES, TRADE_COMMERCE, TRANSPORTATION_AND_STORAGE, UTILITIES_SUPPLY, WATER_WASTE_MANAGEMENT, WEAPONS_BLADES_SELF_DEFENCE_AND_MILITARY.
Allowed: ACCOMMODATION_FOOD, ADMIN_SUPPORT, ADULT_SERVICES, AGRICULTURE_FORESTRY_FISHING, ARTS_ENTERTAINMENT, CFD_SPREADBETTING, CHARITIES, CONSTRUCTION, CRYPTO_ASSETS, EDUCATION, ENERGY_FOSSIL_FUELS, EXTRATERRITORIAL_ORGS, FINANCIAL_AND_INSURANCE_ACTIVITIES, GOVERNMENT, HEALTH_SOCIAL_WORK, HOUSEHOLD_ACTIVITIES, INFORMATION_AND_COMMUNICATION, MANUFACTURING, MARINE_VESSELS, MINING_AND_QUARRYING, MOTOR_VEHICLES, OTHER_SERVICES_ACTIVITIES, PHARMACEUTICALS, PROFESSIONAL_TECHNICAL, PUBLIC_ADMINISTRATION_AND_DEFENCE, PUBLIC_ADMIN_DEFENCE, REAL_ESTATE_ACTIVITIES, TRADE_COMMERCE, TRANSPORTATION_AND_STORAGE, UTILITIES_SUPPLY, WATER_WASTE_MANAGEMENT, WEAPONS_BLADES_SELF_DEFENCE_AND_MILITARY
IndustrySub · string · requiredAllowed values depend on IndustryMain.
Allowed: ACCOMMODATION, ACTIVITIES_OF_HOUSEHOLDS_AS_EMPLOYERS, ACTIVITIES_OF_POLITICAL_ORGANISATIONS, ACTIVITIES_OF_RELIGIOUS_ORGANISATIONS, ADULT_CONTENT_CREATION_AND_MANAGEMENT, ADULT_ONLINE_MEDIA_PLATFORMS, ADVERTISING_AND_MARKET_RESEARCH, AGENTS_AND_BROKERS_OF_MOTOR_VEHICLES, AIR_TRANSPORT, ALCOHOLIC_BEVERAGES, ANIMAL_PRODUCTION_BREEDING, ARCHITECTURAL_AND_ENGINEERING_ACTIVITIES, ARTS_AND_ANTIQUITIES, ATM_OPERATORS, AUCTION_HOUSES_ONLINE_MARKETPLACES, AUXILIARY_FINANCIAL_SERVICES, BANKS, BROADCASTING, BUILDING_AND_LANDSCAPE_SERVICES, BUILDING_COMPLETION, BUILDING_REPAIR_OF_MARINE_VESSELS_WATERCRAFT, BUSINESS_SUPPORT_SERVICES, CALL_CENTRES, CANNABIS_MEDICAL_IMPORT_EXPORT, CANNABIS_PHARMACEUTICAL_RESEARCH, CAR_WASH_TAXI_VALET_SERVICES, CASINOS, CBD, CENTRAL_GOVERNMENT_OFFICE, CHARITY, CHARITY_UNREGULATED, CHEMICALS_AND_RUBBER_PRODUCTS, CIVIL_ENGINEERING, CLEANING_SERVICES, COAL_MINING, COMMODITY_BROKERS, COMMUNITY_INTEREST_COMPANY, COMPULSORY_SOCIAL_SECURITY, COMPUTER_PROGRAMMING, CONCIERGE, CONSTRUCTION_OTHER_SERVICES, CONVERTIBLE_VIRTUAL_CURRENCY_AND_TOKENS_ON_PLATFORMS_AND_DIGITAL_SKINS, CREATION_AND_SUPPLY_OF_DEFENSE_SOFTWARE, CREATIVE_AND_PERFORMING_ARTS, CREDIT_REPAIR_AND_COUNSELLING_COMPANIES, CREDIT_SERVICES, CROP_AND_PLANT_PRODUCTION, CRUDE_PETROLEUM_AND_GAS, CRYPTO_ATMS, CRYPTO_CURRENCY_EXCHANGE_LIQUIDITY_PROVISION_TO_INSTITUTIONS, CRYPTO_CURRENCY_EXCHANGE_OTC_INVESTMENT, CRYPTO_CURRENCY_EXCHANGE_REMITTANCE_MONEY_SERVICE, CRYPTO_RELATED_BLOCKCHAIN_TECHNOLOGY_AND_SOFTWARE, CULTURAL_AND_OTHER_ACTIVITIES, CYBERLOCKERS, DATA_PROCESSING_AND_WEB_PORTALS, DEALERS_IN_DIAMONDS, DEALERS_IN_JEWELLERY_PRECIOUS_METALS_AND_STONES, DEFENCE_ACTIVITIES, DEFENSE_CONSULTANCY_AND_TRAINING, DELIVERY_OF_ADMINISTRATIVE_DOCUMENTS, DEVELOPMENT_AND_BUILDING, DRIVING_INSTRUCTOR, DROPSHIPPING, DRUGS_AND_NARCOTICS, EARLY_CHILDHOOD_AND_PRIMARY_EDUCATION, ECOMMERCE, EDUCATIONAL_COURSES_BY_UNREGULATED_CFD_INVESTMENT_COMPANIES, EDUCATIONAL_SUPPORT_SERVICES, ELECTRICITY_SUPPLY, EMPLOYMENT_ACTIVITIES, EVENT_ORGANISATION, EVENT_TICKETING, EXTRATERRITORIAL_ACTIVITIES, FARMING, FINANCIAL_SERVICES, FINANCING_OF_MARINE_VESSELS_WATERCRAFT, FIRE_SERVICE_ACTIVITIES, FIREWORKS_PYROTECHNICS, FISHING_AQUACULTURE, FOOD_AND_BEVERAGE_SERVICE, FOOD_AND_DRINK, FOREIGN_AFFAIRS, FOREIGN_EMBASSIES_MISSIONS_OR_CONSULATES, FORESTRY, FOSSIL_FUELS_EXTRACTION_AND_REFINEMENT, FREIGHT_SERVICES, FUND_MANAGEMENT, FUNERAL_AND_RELATED_ACTIVITIES, FURNITURE_HOUSEHOLD_GOODS_AND_MISCELLANEOUS, GAMBLING_BETTING, GAMING, GAS_FUEL_STATION, GAS_SUPPLY, GENERAL_PUBLIC_ADMINISTRATION, GENTLEMANS_CLUBS_AND_LAPDANCING_BARS, HAIRDRESSING_MASSAGE_OTHER_BEAUTY_TREATMENT, HIRE_OR_CHARTER_OF_MARINE_VESSELS_WATERCRAFT, HOLDING_COMPANIES, HOSPITAL_ACTIVITIES, INSURANCE_SERVICES, INTERIOR_DESIGN, INVESTMENT_SERVICES, IT_AND_COMPUTER_SERVICES, JUSTICE_AND_JUDICIAL_ACTIVITIES, LAND_TRANSPORT, LEGAL_AND_ACCOUNTING_ACTIVITIES, LICENSED_CANNABIS_DISPENSARY, LICENSED_CRYPTO_CUSTODIAL_WALLET, LOCAL_GOVERNMENT, LOOT_BOXES, LUXURY_SHOPPERS, LUXURY_YACHTS, MACHINERY_AND_ELECTRONICS, MAIL_ONLINE_TELEPHONE_ORDER_SALES, MANAGEMENT_AND_CONSULTANCY, MANUFACTURE_AND_SUPPLY_MILITARY_AND_POLICE_GRADE_ANTI_RIOT_EQUIPMENT, MANUFACTURE_AND_SUPPLY_MILITARY_AND_POLICE_UNIFORM_AND_ASSOCIATED_EQUIPMENT, MANUFACTURE_AND_SUPPLY_MILITARY_VEHICLES_AND_HEAVY_EQUIPMENT, MANUFACTURE_OF_BLADES_OFFENSIVE_WEAPONS, MANUFACTURE_SUPPLY_OF_PHARMACEUTICAL_PRODUCTS, MATERIAL_RECOVERY, MEDICAL_AND_DENTAL_PRACTICE_ACTIVITIES, MEMBERSHIP_ORGANISATIONS, METAL_MANUFACTURING, METAL_ORES_MINING, MILITARY_RESEARCH, MILITARY_WATERCRAFT, MINERAL_EXTRACTION_GEMSTONES_AND_PRECIOUS_METALS, MONEY_SERVICE_BUSINESSES, MOTION_PICTURE_PRODUCTION, NIGHTCLUBS_PUBS_BARS, NON_CRYPTO_BLOCKCHAIN_TECHNOLOGY, NON_DIGITAL_ADVERTISING_AGENCIES, NON_DOMESTIC_LOCAL_GOVERNMENT_INCLUDING_COUNCILS_PARISH_COUNCILS, NON_PRECIOUS_METALS, NON_REGULATED_CFDS, NUCLEAR_MATERIAL_POWER, NUCLEAR_POWER_PLANT_MAINTENANCE, NUCLEAR_RESEARCH_DEVELOPMENT, NUCLEAR_WEAPONS_DEVELOPMENT_AND_MANUFACTURING_WASTE_MANAGEMENT_AND_ILLICIT_NUCLEAR_MATERIAL_TRADE, OFFICE_ADMINISTRATIVE_SERVICES, ONLINE_DATING_SERVICES, ONLINE_EDUCATION, OPERATIONAL_EXPENSES, OPERATIONAL_EXPENSES_OF_MARINE_VESSELS_WATERCRAFT, OTHER_ADULT_SERVICES_INCLUDING_MEMBERSHIP_ORGANISATIONS, OTHER_HUMAN_HEALTH_ACTIVITIES, OTHER_PROFESSIONAL_ACTIVITIES, P2P_PLATFORMS, PAWN_SHOPS_CASH_FOR_GOLD_BUSINESSES, PAYDAY_LOAN_COMPANIES, PAYMENT_AGENTS, PENSION_FUNDING, PHARMACEUTICAL_TESTING_DIAGNOSTICS, PHOTOGRAPHY, PHYSICAL_WELL_BEING_ACTIVITIES, POST_SECONDARY_AND_HIGHER_EDUCATION, POSTAL_AND_COURIER_ACTIVITIES_LICENSED, POSTAL_AND_COURIER_ACTIVITIES_UNLICENSED, PREPAID_CARDS, PROPRIETARY_TRADING_PLATFORM_PORTAL_OR_BUSINESS, PUBLIC_ADMINISTRATION, PUBLIC_ORDER_AND_SAFETY, PUBLISHING_ACTIVITIES, PURCHASE_AND_SUPPLY_OF_ANTIQUE_WEAPONRY, QUARRYING, QUASI_NON_GOVERNMENTAL_ORGANISATION, REAL_ESTATE_AGENCY_ACTIVITIES, REAL_ESTATE_MANAGEMENT, REAL_ESTATE_TRANSACTIONS, REGULATED_CFDS, REGULATED_PEER_TO_PEER_CROWDFUNDING, REMEDIATION_AND_WASTE_MANAGEMENT, REMOVAL_SERVICES, RENTAL_AND_LEASING_ACTIVITIES, RENTAL_AND_LEASING_ACTIVITIES_CARS, RENTAL_AND_LEASING_ACTIVITIES_TRUCKS_HEAVY_VEHICLES, RENTAL_LEASING_ACTIVITIES_NOT_INCLUDING_AUTOMOBILES_TRUCKS_PROPERTIES, RENTING_AND_OPERATING_REAL_ESTATE, REPAIR_OF_MOTOR_VEHICLES, REPAIR_SERVICES, RESEARCH_AND_DEVELOPMENT, RESIDENTIAL_CARE_ACTIVITIES, RETAIL_STORES, RETAIL_TRADE_NOT_INCLUDING_CLOTHING_OR_ELECTRONICS, RETAIL_TRADE_OF_CLOTHING_AND_SECOND_HAND_TEXTILES, RETAIL_TRADE_OF_PORTABLE_ELECTRONICS, SALE_CONSULTANCY_AND_BROKERAGE, SALE_OF_MOTOR_VEHICLES, SALE_OF_USED_MOTOR_VEHICLES, SALE_OR_PURCHASE_OF_MARINE_VESSEL_WATERCRAFT, SCRAP_METAL, SECONDARY_EDUCATION, SECURITY_AND_INVESTIGATION_ACTIVITIES, SEO_SCO_DIGITAL_MARKETING_AND_AFFILIATE_MARKETING, SEWERAGE, SOCIAL_MEDIA, SOCIAL_WORK_ACTIVITIES, SOFT_DRINKS, SOFTWARE_DESIGN_AND_MAINTENANCE, SOUND_AND_MUSIC_PUBLISHING, SPECIALISED_CONSTRUCTION, SPECIALISED_DESIGN_ACTIVITIES, SPORTS_RECREATION, STEAM_AND_AIR_CONDITIONING_SUPPLY, SUBSCRIPTION_WEBSITES, SUPPLY_OF_BLADES_OFFENSIVE_WEAPONS_FIREARMS_DEFENCE_EQUIPMENT_AS_WELL_AS_AMMUNITION, SUPPORT_ACTIVITIES, SUPPORT_ACTIVITIES_FOR_OTHER_MINING_AND_QUARRYING, SUPPORT_ACTIVITIES_FOR_TRANSPORTATION, TAILOR, TECHNICAL_TESTING_AND_ANALYSIS, TELECOMMUNICATIONS, TEXTILES, TOBACCO_VAPES, TRADE_OF_LIVESTOCK, TRANSLATION_AND_INTERPRETATION, TRANSPORT_EQUIPMENT, TRAVEL_AND_RESERVATION_SERVICES, TRUST_AND_COMPANY_SERVICE_PROVIDERS, UNDIFFERENTIATED_GOODS_PRODUCTION, UNREGISTERED_CHARITIES, UNREGULATED_FINANCIAL_FIRMS_INVESTMENT_MORTGAGE_CONSULTING, UNREGULATED_NFT_TRADING_PLATFORMS_UNREGULATED_CRYPTOCURRENCY_EXCHANGES_UNREGULATED_TOKENS_OR_ICOS, VETERINARY_ACTIVITIES, VIRTUAL_ASSETS_AND_DIGITAL_GOODS, WAREHOUSING_PACKAGING_AND_STORAGE, WASHING_CLEANING_OF_TEXTILE_AND_FUR_PRODUCTS, WASTE_COLLECTION, WASTE_TREATMENT_AND_DISPOSAL, WATER_SUPPLY, WATER_TRANSPORT, WEALTH_MANAGEMENT, WEBSITE_DESIGN_AND_CONSULTANCY, WHOLESALE_TRADE_ALCOHOL_WINE_BEER_SPIRITS_ALCOHOLIC_BEVERAGES, WHOLESALE_TRADE_CHEMICAL_PRODUCTS, WHOLESALE_TRADE_CHOCOLATE_CONFECTIONARY, WHOLESALE_TRADE_CONSTRUCTION_MATERIALS_WOOD_SUPPLIES, WHOLESALE_TRADE_ELECTRONICS_PARTS_TELECOMMUNICATION_COMPUTER_SOFTWARE, WHOLESALE_TRADE_FRUIT_VEGETABLES_GRAINS_ANIMAL_FEED_LIVESTOCK, WHOLESALE_TRADE_MEAT_FISH_DAIRY_EGGS_OILS, WHOLESALE_TRADE_NON_SPECIALISED_FOODS_BEVERAGES, WHOLESALE_TRADE_PHARMACEUTICALS, WHOLESALE_TRADE_SUGAR_SPICES, WHOLESALE_TRADE_TEXTILES_FOOTWEAR_FURNITURE, WHOLESALE_TRADE_TOBACCO, WOOD
EmployeeCount · string · requiredPossible values: ONE_TO_TEN, ELEVEN_TO_FIFTY, FIFTY_ONE_TO_TWO_HUNDRED, TWO_HUNDRED_AND_ONE_TO_FIVE_HUNDRED, FIVE_HUNDRED_AND_ONE_TO_ONE_THOUSAND, ONE_THOUSAND_AND_ONE_TO_FIVE_THOUSAND, FIVE_THOUSAND_AND_ONE_TO_TEN_THOUSAND, TEN_THOUSAND_PLUS.
Allowed: ONE_TO_TEN, ELEVEN_TO_FIFTY, FIFTY_ONE_TO_TWO_HUNDRED, TWO_HUNDRED_AND_ONE_TO_FIVE_HUNDRED, FIVE_HUNDRED_AND_ONE_TO_ONE_THOUSAND, ONE_THOUSAND_AND_ONE_TO_FIVE_THOUSAND, FIVE_THOUSAND_AND_ONE_TO_TEN_THOUSAND, TEN_THOUSAND_PLUS
IncorporationDate · string · requiredFormat: YYYY-MM-DD.
PhoneNumber · string or null · optionalTaxId · string or null · optionalWebsite · string or null · optionalBusinessPromotionDescription · string or null · optionalRequestedFeatures · array or null · optionalPossible values: CARDS, PAYMENTS.
CardsInformation · object or null · optionalPaymentsInformation · object or null · optionalAddresses · array or null · optionalAssociatedPeople · array or null · optionalExample request body · replace placeholders
{
"BusinessType": "PRIVATE_COMPANY",
"CountryOfIncorporation": "AD",
"RegisteredName": "string",
"BusinessOverview": "string",
"IndustryMain": "ACCOMMODATION_FOOD",
"IndustrySub": "ACCOMMODATION",
"EmployeeCount": "ONE_TO_TEN",
"IncorporationDate": "2026-08-05",
"Market": "UK",
"RegionOfIncorporation": "string",
"RegistrationNumber": "string",
"TradingNames": [
"string"
],
"PhoneNumber": "+447700900123",
"TaxId": "string",
"Website": "string",
"BusinessPromotionDescription": "Example description",
"RequestedFeatures": [
"CARDS"
],
"CardsInformation": {
"BusinessDisplayName": "string",
"Purposes": [
"ADVERTISING_AND_MARKETING"
],
"EstimatedAnnualSpend": "0-10000",
"NumberOfCardsRequired": "0-10",
"CardsAreForEmployees": true,
"AtmWithdrawalsRequired": true
},
"PaymentsInformation": {
"Purposes": [
"PAYING_SUPPLIERS"
],
"AccountFundingSource": [
"RECEIVING_FUNDS_FROM_OWN_ACCOUNTS"
],
"EstimatedPaymentCount": "FEWER-THAN-5-PAYMENTS",
"EstimatedPaymentVolume": "0-10000",
"InboundCurrencies": [
"AED"
],
"OutboundCurrencies": [
"AED"
],
"ReceivingCountries": [
"AD"
],
"SendingCountries": [
"AD"
]
},
"Addresses": [
{
"AddressType": "REGISTERED",
"StreetName": "string",
"Postcode": "SW1A 1AA",
"City": "London",
"CountryCode": "AD",
"BuildingNumber": "string",
"BuildingName": "string",
"Region": "string"
}
],
"AssociatedPeople": [
{
"AssociatedPersonId": "string",
"AssociationType": "APPLICANT",
"JobTitle": "string",
"OwnershipPercentage": 1
}
]
}200OKEqualsMoneyApplicationResponse
{
"isActionRequired": true,
"id": "string",
"status": "PENDING",
"accountId": "string",
"market": "string",
"type": "string",
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z",
"firstName": "Jane",
"lastName": "Doe",
"dob": "2026-08-05",
"email": "user@example.com",
"phoneNumber": "+447700900123",
"nationalities": [
"string"
],
"identityDocumentNumber": "string",
"taxId": "string",
"countryOfIncorporation": "GB",
"regionOfIncorporation": "string",
"registeredName": "string",
"registrationNumber": "string",
"tradingNames": [
"string"
],
"businessOverview": "string",
"industry": {
"main": "string",
"sub": "string"
},
"employeeCount": "string",
"incorporationDate": "2026-08-05",
"website": "string",
"businessPromotionDescription": "Example description",
"featureInformation": {
"requestedFeatures": [
"CARDS"
],
"cardsInformation": {
"purposes": [
"SALARY_OR_INCOME"
],
"estimatedAnnualSpend": "0-10000",
"atmWithdrawalsRequired": true,
"businessDisplayName": "string",
"numberOfCardsRequired": "0-10",
"cardsAreForEmployees": true
},
"paymentsInformation": {
"purposes": [
"SALARY_OR_INCOME"
],
"estimatedPaymentCount": "FEWER-THAN-5",
"estimatedPaymentVolume": "0-10000",
"inboundCurrencies": [
"AED"
],
"outboundCurrencies": [
"AED"
],
"receivingCountries": [
"AD"
],
"sendingCountries": [
"AD"
],
"accountFundingSource": [
"RECEIVING_FUNDS_FROM_OWN_ACCOUNTS"
]
}
},
"addresses": [
{
"addressType": "REGISTERED",
"streetName": "string",
"postcode": "SW1A 1AA",
"city": "London",
"countryCode": "AD",
"buildingNumber": "string",
"buildingName": "string",
"region": "string"
}
],
"associatedPeople": [
{
"associatedPersonId": "string",
"associationType": "string",
"jobTitle": "string",
"ownershipPercentage": 1
}
]
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/business/onboarding/application/submitSubmit the application for reviewRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/business/onboarding/application/submit?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123200OKEqualsMoneyApplicationResponse
{
"isActionRequired": true,
"id": "string",
"status": "PENDING",
"accountId": "string",
"market": "string",
"type": "string",
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z",
"firstName": "Jane",
"lastName": "Doe",
"dob": "2026-08-05",
"email": "user@example.com",
"phoneNumber": "+447700900123",
"nationalities": [
"string"
],
"identityDocumentNumber": "string",
"taxId": "string",
"countryOfIncorporation": "GB",
"regionOfIncorporation": "string",
"registeredName": "string",
"registrationNumber": "string",
"tradingNames": [
"string"
],
"businessOverview": "string",
"industry": {
"main": "string",
"sub": "string"
},
"employeeCount": "string",
"incorporationDate": "2026-08-05",
"website": "string",
"businessPromotionDescription": "Example description",
"featureInformation": {
"requestedFeatures": [
"CARDS"
],
"cardsInformation": {
"purposes": [
"SALARY_OR_INCOME"
],
"estimatedAnnualSpend": "0-10000",
"atmWithdrawalsRequired": true,
"businessDisplayName": "string",
"numberOfCardsRequired": "0-10",
"cardsAreForEmployees": true
},
"paymentsInformation": {
"purposes": [
"SALARY_OR_INCOME"
],
"estimatedPaymentCount": "FEWER-THAN-5",
"estimatedPaymentVolume": "0-10000",
"inboundCurrencies": [
"AED"
],
"outboundCurrencies": [
"AED"
],
"receivingCountries": [
"AD"
],
"sendingCountries": [
"AD"
],
"accountFundingSource": [
"RECEIVING_FUNDS_FROM_OWN_ACCOUNTS"
]
}
},
"addresses": [
{
"addressType": "REGISTERED",
"streetName": "string",
"postcode": "SW1A 1AA",
"city": "London",
"countryCode": "AD",
"buildingNumber": "string",
"buildingName": "string",
"region": "string"
}
],
"associatedPeople": [
{
"associatedPersonId": "string",
"associationType": "string",
"jobTitle": "string",
"ownershipPercentage": 1
}
]
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/business/onboarding/application/documentsUpload a Banking business onboarding documentRequest & responses +
Uploads one document for the authenticated user's active Banking business onboarding application. Standard business documents normally cover formation, ownership/control, registration, finances/funds, identity, address, and liveness where applicable. Banking may request further Enhanced Due Diligence (EDD) documents as onboarding progresses. Use `Purpose` to classify the file. Use `OTHER` for industry-specific EDD documents where no more specific proof category fits. ## Standard EDD documents that may be requested | Requirement area | Examples | | --- | --- | | Customer base | Overview of customer count, type, industries, and jurisdictions. | | Third-party funds | Names of third-party payers and the purpose of those payments. | | Beneficiaries | Key beneficiaries/payees and geographic locations. | | Source of funds | Latest audited financial statements, or 3 months corporate bank statements with 3 customer invoices, or eligible unaudited financial statements. | ## Industry-specific additional document requirements | Industry | Additional documents/evidence commonly required | | --- | --- | | Regulated financial services | FinCrime/AML policy, fraud policy, enterprise-wide risk assessment for MSBs, client risk assessment methodology, external AML audit, AML questionnaire for crypto/gaming/MSB/CFD, top clients list, regulatory licences. | | Investment funds | Funds questionnaire, PPM/OM or other offering documents, investor report where applicable, investment agreement, AML policy/procedures, AML comfort letter. | | Consultancy | Customer and beneficiary/supplier lists, serviced-industries confirmation, client sourcing explanation, customer-base breakdown, 3 months corporate bank statements, AML/CFT supervision status. | | Luxury yachts - management | Service confirmation, yacht owner details, yacht purchase/source-of-funds evidence or owner agreements, owner/client due diligence evidence, sanctions controls, cash payment thresholds. | | Luxury yachts - chartering/buying/selling | Yacht owner details, yacht purchase/source-of-funds evidence or owner agreements, due diligence policies for clients and yacht owners, sanctions controls, website yacht-list confirmation, cash payment thresholds. | | SEO/SCO/digital marketing/affiliate marketing | 3 customer invoices, 3 months corporate bank statements, customer-base overview, customer sourcing explanation, SEO tracking platform screenshots for SEO companies. | | Real estate | AML/CFT registration status, property ownership details, client/investor funds arrangements, third-party payer or beneficiary details, source of funds/source of wealth evidence, loan agreements, sale/reservation agreements, prospectus for real-estate investment funds. | | Maritime shipping | Vessel list, vessel ownership evidence, owner/yacht manager details, vessel activity monitoring documents, shipping manifest. | | Jewellery - lab-grown diamonds/watches | High-value dealer confirmation, AML policy/procedures if registered, revenue channel split, jurisdiction risk ratings, customer threshold breakdown, supplier list, additional products list. | | Jewellery - natural diamonds/gemstones | High-value dealer confirmation, AML policy/procedures, supplier due diligence, Kimberly Process confirmation, licences/memberships, Ethical Diamond Policy, Modern Slavery Policy, bank statements, supplier/client shipping invoices. | | Jewellery - gold/silver | High-value dealer confirmation, AML policy/procedures, supplier list, licences/memberships, Modern Slavery Policy, bank statements, supplier/client shipping invoices. | | Adult content and dating services | Modern Slavery Policy, website URLs, age verification evidence, user profile verification process, content monitoring/audit process, consent checks, payer/beneficiary lists, bank statements. | | Military and defence | Licence/permit to sell military goods, military/defence goods list, ECJU export licence where applicable, manufacturing/source details, banned goods confirmation, buyer due diligence. | | Weapons and firearms | Licences/permits, manufacturing details, 3 invoices and contractual agreements, buyer due diligence, under-18 controls, customer type confirmation. | | Cannabidiol products (CBD) | Supplier invoices, bank statements, Home Office/DEFRA licences where applicable, THC evidence, no medicinal claims evidence, GMP/EMA or Home Office evidence for medical CBD. | | Vaping/e-cigarettes/e-liquid sellers | Supplier list, 3 supplier invoices, wholesale shipping documents, bank statements with 3 client invoices, operating model, cash due diligence, THC/nicotine/liquid-volume confirmations. | | Mining | Jurisdiction licences/permits, Modern Slavery Policy, ABC policy, ESG policy, government/third-party agreements, onsite mining audit, project details, bank statements, supplier invoices. | | Dropshipping | Supplier/beneficiary list with websites, product and sale-jurisdiction details, 3 supplier invoices, supplier agreements, bank statements, wholesale customer-base breakdown, payment methods, dual-use goods policy. | | Art | High-value dealer and HMRC Art Market Participant status, AML policy/procedures where applicable, cash due diligence, crypto due diligence, sales/storage explanation, bank statements, artwork source. | | Trust/nominee/fiduciary ownership | Beneficial owner identity documents, trust deeds, nominee agreements or fiduciary service agreements, official documents for trustees/settlors/beneficiaries, legal rationale for structure. | | Aviation - spares/parts/repairs | Sourcing details, military aircraft confirmation, 3 supplier invoices, bank statements, licences/certifications, dual-use goods policy, plane ownership/source-of-funds evidence, due diligence policies, sanctions controls. | | Aviation - hire/chartering/selling planes | Plane owner details, plane purchase/source-of-funds evidence or owner agreements, airspace monitoring confirmation, client due diligence policies, sanctions controls, website plane-list confirmation. | | Portable electronics | Supplier/beneficiary list, 3 supplier invoices, wholesale shipping documents, bank statements with 3 client invoices, operating model, cash due diligence. |
curl --request POST 'https://staging.hoppa.global/api/v2/business/onboarding/application/documents?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'File=@/absolute/path/document.pdf' \
-F 'Purpose=PROOF_OF_FORMATION'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
File · string · optionalDocument file to upload for the Banking associated person.
Purpose · string · optionalUse OTHER for industry-specific or EDD documents that do not fit one of the standard proof categories. Possible values: PROOF_OF_FORMATION, PROOF_OF_OWNERSHIP_STRUCTURE, PROOF_OF_OWNERSHIP, PROOF_OF_CONTROL_PERSONS, PROOF_OF_REGISTRATION, PROOF_OF_FINANCES, PROOF_OF_FUNDS, PROOF_OF_IDENTITY, PROOF_OF_ADDRESS, PROOF_OF_LIVENESS, OTHER.
Allowed: PROOF_OF_FORMATION, PROOF_OF_OWNERSHIP_STRUCTURE, PROOF_OF_OWNERSHIP, PROOF_OF_CONTROL_PERSONS, PROOF_OF_REGISTRATION, PROOF_OF_FINANCES, PROOF_OF_FUNDS, PROOF_OF_IDENTITY, PROOF_OF_ADDRESS, PROOF_OF_LIVENESS, OTHER
Example request body · replace placeholders
{
"File": "<binary file>",
"Purpose": "PROOF_OF_FORMATION"
}200OKEqualsMoneyDocumentResponse
{
"complianceDocumentId": 123,
"id": "string",
"applicationId": "string",
"associatedPersonId": "string",
"purpose": "Example description",
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/business/onboarding/associated-peopleGet associated people for the current userRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/business/onboarding/associated-people?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123200OKapplication/json
[
{
"Id": 123,
"ExternalId": "external_reference_123",
"FirstName": "Jane",
"LastName": "Doe",
"Email": "user@example.com",
"AssociationType": "string",
"JobTitle": "string",
"OwnershipPercentage": 1,
"IdentityDocumentUploaded": true,
"AddressDocumentUploaded": true,
"CreatedAt": "2026-08-05T09:30:00Z"
}
]401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/business/onboarding/associated-peopleCreate associated people for a business application (Directors, UBOs, Applicants)Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/business/onboarding/associated-people?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"People": [
{
"firstName": "Jane",
"lastName": "Doe",
"dateOfBirth": "2026-08-05",
"emailAddress": "user@example.com",
"nationalities": [
"string"
],
"taxId": "string",
"phoneNumber": "+447700900123",
"address": {
"addressLine1": "string",
"townCity": "London",
"postcode": "SW1A 1AA",
"countryCode": "GB",
"addressLine2": "string",
"streetName": "string",
"buildingNumber": "string",
"buildingName": "string",
"region": "string",
"city": "London",
"country": "GB",
"address": "string"
}
}
]
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
People · array · optionalExample request body · replace placeholders
{
"People": [
{
"firstName": "Jane",
"lastName": "Doe",
"dateOfBirth": "2026-08-05",
"emailAddress": "user@example.com",
"nationalities": [
"string"
],
"taxId": "string",
"phoneNumber": "+447700900123",
"address": {
"addressLine1": "string",
"townCity": "London",
"postcode": "SW1A 1AA",
"countryCode": "GB",
"addressLine2": "string",
"streetName": "string",
"buildingNumber": "string",
"buildingName": "string",
"region": "string",
"city": "London",
"country": "GB",
"address": "string"
}
}
]
}200OKapplication/json
[
{
"id": "string",
"firstName": "Jane",
"lastName": "Doe",
"dateOfBirth": "2026-08-05",
"emailAddress": "user@example.com",
"nationalities": [
"string"
],
"taxId": "string",
"phoneNumber": "+447700900123",
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
}
]400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/business/onboarding/associated-people/{associatedPersonId}/documentsUpload a Banking associated person onboarding documentRequest & responses +
Uploads one identity, address, or supporting document for a Banking associated person.
curl --request POST 'https://staging.hoppa.global/api/v2/business/onboarding/associated-people/123/documents?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'File=@/absolute/path/document.pdf' \
-F 'Purpose=PROOF_OF_IDENTITY'Parameters
associatedPersonIdpathstringrequiredExample: 123userIdqueryintegeroptionalExample: 123Request fields and validation
File · string · optionalDocument file to upload for the Banking associated person.
Purpose · string · optionalUse PROOF_OF_IDENTITY for identity documents, PROOF_OF_ADDRESS for address documents, or OTHER for requested supporting documents. Possible values: PROOF_OF_IDENTITY, PROOF_OF_ADDRESS, OTHER.
Allowed: PROOF_OF_IDENTITY, PROOF_OF_ADDRESS, OTHER
Example request body · replace placeholders
{
"File": "<binary file>",
"Purpose": "PROOF_OF_IDENTITY"
}200OKEqualsMoneyDocumentResponse
{
"complianceDocumentId": 123,
"id": "string",
"applicationId": "string",
"associatedPersonId": "string",
"purpose": "Example description",
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
BusinessOnboardingWorkflow5 operations
GET/api/v2/business-onboardingOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/business-onboarding?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123200OKBusinessOnboardingWorkflowStatusResponse
{
"state": "string",
"selectedTierId": 123,
"finalTierId": 123,
"feesEnabled": true,
"message": "string",
"complexCasePricing": {
"amount": 100,
"currency": "USD",
"replacement": true
},
"workflowVersion": 1,
"complexCase": true,
"finalFee": 100,
"tiers": [
{
"id": 123,
"name": "string",
"description": "Example description",
"monthly_fee": 100,
"yearly_fee": 100
}
],
"gates": [
{
"tier_id": 123,
"enabled": true,
"amount": 100,
"currency": "USD"
}
],
"payments": [
{
"id": "00000000-0000-4000-8000-000000000123",
"purpose": "Example description",
"amount": 100,
"bank_amount": 100,
"currency": "USD",
"status": "PENDING",
"invoice_number": "string",
"invoice_details_json": "string"
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/business-onboarding/tierOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/business-onboarding/tier?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"TierId": 123
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
TierId · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"TierId": 123
}200OKBusinessOnboardingWorkflowTierResponse
{
"success": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/business-onboarding/assessOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/business-onboarding/assess?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123202AcceptedBusinessOnboardingWorkflowAssessResponse
{
"status": "PENDING"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/business-onboarding/payments/{paymentId}/checkoutOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/business-onboarding/payments/00000000-0000-4000-8000-000000000123/checkout?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"TermsAccepted": true
}'Parameters
paymentIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123userIdqueryintegeroptionalExample: 123Request fields and validation
TermsAccepted · boolean · requiredExample request body · replace placeholders
{
"TermsAccepted": true
}200OKBusinessCheckoutResponse
{
"status": "PENDING",
"url": "https://example.com/callback",
"error": "string",
"terms": {
"Region": "string",
"Version": "string",
"Title": "string",
"Intro": "string",
"SecondaryIntro": "string",
"ListStyle": "string",
"Items": [
"string"
],
"CheckboxLabel": "string"
}
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/business-onboarding/payments/{paymentId}/invoiceOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/business-onboarding/payments/00000000-0000-4000-8000-000000000123/invoice?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
paymentIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123userIdqueryintegeroptionalExample: 123200OKapplication/pdf
<binary file>Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
Cards26 operations
GET/api/v2/cards/quantum-topup/estimateEstimate Quantum top-up conversion using CryptoConnect quotes for USD to USDT/USDC and USDT/USDC to USDRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/cards/quantum-topup/estimate?userId=123&amount=100' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123amountquerynumberoptionalExample: 100200OKQuantumTopUpEstimateResponse
{
"success": true,
"message": "string",
"usdAmount": 100,
"usdToUsdt": {
"baseCurrency": "USD",
"quoteCurrency": "USD",
"baseAmount": "100.00",
"rfqAmount": "100.00",
"rfqCurrency": "USD",
"fee": "100.00",
"feeCurrency": "USD",
"rate": "string",
"quoteId": "string",
"quoteTime": "string",
"ttlMs": "string"
},
"usdToUsdc": {
"baseCurrency": "USD",
"quoteCurrency": "USD",
"baseAmount": "100.00",
"rfqAmount": "100.00",
"rfqCurrency": "USD",
"fee": "100.00",
"feeCurrency": "USD",
"rate": "string",
"quoteId": "string",
"quoteTime": "string",
"ttlMs": "string"
},
"usdtToUsd": {
"baseCurrency": "USD",
"quoteCurrency": "USD",
"baseAmount": "100.00",
"rfqAmount": "100.00",
"rfqCurrency": "USD",
"fee": "100.00",
"feeCurrency": "USD",
"rate": "string",
"quoteId": "string",
"quoteTime": "string",
"ttlMs": "string"
},
"usdcToUsd": {
"baseCurrency": "USD",
"quoteCurrency": "USD",
"baseAmount": "100.00",
"rfqAmount": "100.00",
"rfqCurrency": "USD",
"fee": "100.00",
"feeCurrency": "USD",
"rate": "string",
"quoteId": "string",
"quoteTime": "string",
"ttlMs": "string"
},
"usdt": {
"baseCurrency": "USD",
"quoteCurrency": "USD",
"baseAmount": "100.00",
"rfqAmount": "100.00",
"rfqCurrency": "USD",
"fee": "100.00",
"feeCurrency": "USD",
"rate": "string",
"quoteId": "string",
"quoteTime": "string",
"ttlMs": "string"
},
"usdc": {
"baseCurrency": "USD",
"quoteCurrency": "USD",
"baseAmount": "100.00",
"rfqAmount": "100.00",
"rfqCurrency": "USD",
"fee": "100.00",
"feeCurrency": "USD",
"rate": "string",
"quoteId": "string",
"quoteTime": "string",
"ttlMs": "string"
},
"topupfee": 100,
"topupfeepercent": 100
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}403ForbiddenErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/cards/{cardId}/limitsUpdate card spending limits (daily/weekly/monthly) for a specific user and cardRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/cards/123/limits?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Daily": 100,
"Weekly": 100,
"Monthly": 100
}'Parameters
userIdqueryintegeroptionalExample: 123cardIdpathintegerrequiredExample: 123Request fields and validation
Daily · number or null · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Weekly · number or null · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Monthly · number or null · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Example request body · replace placeholders
{
"Daily": 100,
"Weekly": 100,
"Monthly": 100
}200OKCardUpdateLimitsResponseV2
{
"Success": true,
"Message": "string",
"Daily": 100,
"Weekly": 100,
"Monthly": 100
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/cardsGet list of cards for a userRequest & responses +
Card numbers are always masked (for example ****-****-****-1234), including company API-key responses. Sensitive PAN/CVV are available through GET /api/v2/cards/{cardId}/widget.
curl --request GET 'https://staging.hoppa.global/api/v2/cards?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123200OKCardListResponseV2
{
"Cards": [
{
"DiscountCode": "string",
"Id": 123,
"UserId": 123,
"ExternalCardId": "external_reference_123",
"Provider": "string",
"BudgetId": "string",
"DeliveryAddressId": "string",
"Nickname": "string",
"CardType": "string",
"CardNetwork": "string",
"CardNumber": "****-****-****-1234",
"ExpiryDate": "2026-08-05",
"Status": "PENDING",
"Balance": {
"Available": "string",
"Pending": "string",
"Frozen": "string",
"Currency": "USD"
},
"Currency": "USD",
"VelocityControl": {
"Type": "string",
"Limit": "string"
},
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CardTypeId": 123,
"CardTypeTierId": 123,
"TierId": 123,
"CanSetPin": true,
"AutoLockEnabled": true,
"AutoLockActiveUntil": "2026-08-05T09:30:00Z",
"TransakOrder": "string",
"RequiredAmount": "100.00",
"AvailableAmount": "100.00",
"Shortfall": "string",
"Message": "string",
"Errors": [
{
"key": "string",
"reason": "string"
}
]
}
],
"Total": 1,
"PageTotal": 1
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/cardsCreate a new cardRequest & responses +
UserId remains a required positive body field. Company API keys and platform administrators retain supported selected-user operations within tenant authorization; an ordinary JWT caller's valid body UserId is replaced by the authenticated user.
curl --request POST 'https://staging.hoppa.global/api/v2/cards' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"CardTypeId": 123,
"Phone": "+447700900123",
"ExternalCardId": "external_reference_123",
"Nickname": "string",
"Currency": "USD",
"CardName": "string",
"BudgetId": "string",
"BillingAddress": {
"Line1": "string",
"Line2": "string",
"City": "London",
"State": "string",
"Country": "GB",
"PostalCode": "SW1A 1AA"
},
"DeliveryAddress": {
"Line1": "string",
"Line2": "string",
"City": "London",
"State": "string",
"Country": "GB",
"PostalCode": "SW1A 1AA"
},
"DeliveryAddressId": "string",
"PhoneCode": "+447700900123",
"DesignId": "string",
"PhysicalCardDesignId": "string",
"DiscountCode": "string",
"AutoLockEnabled": true
}'Request fields and validation
UserId · integer · requiredRequired positive selected company user for API-key integrations. Ordinary JWT callers resolve this valid body value to the authenticated user.
Minimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
CardTypeId · integer · requiredMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
ExternalCardId · string or null · optionalOptional external identifier. The card provider assigns its own identifier when this value is omitted.
Nickname · string or null · optionalCurrency · string or null · optionalCardName · string or null · optionalBudgetId · string or null · optionalRequired when the selected card type uses Banking; optional for Crypto cards types.
BillingAddress · object or null · optionalDeliveryAddress · object or null · optionalDeliveryAddressId · string or null · optionalPhone · string or null · requiredPhoneCode · string or null · optionalOptional when Phone is supplied in E.164 format. Otherwise provide the country calling code.
DesignId · string or null · optionalPhysicalCardDesignId · string or null · optionalDiscountCode · string or null · optionalAutoLockEnabled · boolean · optionalExample request body · replace placeholders
{
"UserId": 123,
"CardTypeId": 123,
"Phone": "+447700900123",
"ExternalCardId": "external_reference_123",
"Nickname": "string",
"Currency": "USD",
"CardName": "string",
"BudgetId": "string",
"BillingAddress": {
"Line1": "string",
"Line2": "string",
"City": "London",
"State": "string",
"Country": "GB",
"PostalCode": "SW1A 1AA"
},
"DeliveryAddress": {
"Line1": "string",
"Line2": "string",
"City": "London",
"State": "string",
"Country": "GB",
"PostalCode": "SW1A 1AA"
},
"DeliveryAddressId": "string",
"PhoneCode": "+447700900123",
"DesignId": "string",
"PhysicalCardDesignId": "string",
"DiscountCode": "string",
"AutoLockEnabled": true
}201CreatedCardResponseV2
{
"DiscountCode": "string",
"Id": 123,
"UserId": 123,
"ExternalCardId": "external_reference_123",
"Provider": "string",
"BudgetId": "string",
"DeliveryAddressId": "string",
"Nickname": "string",
"CardType": "string",
"CardNetwork": "string",
"CardNumber": "****-****-****-1234",
"ExpiryDate": "2026-08-05",
"Status": "PENDING",
"Balance": {
"Available": "string",
"Pending": "string",
"Frozen": "string",
"Currency": "USD"
},
"Currency": "USD",
"VelocityControl": {
"Type": "string",
"Limit": "string"
},
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CardTypeId": 123,
"CardTypeTierId": 123,
"TierId": 123,
"CanSetPin": true,
"AutoLockEnabled": true,
"AutoLockActiveUntil": "2026-08-05T09:30:00Z",
"TransakOrder": "string",
"RequiredAmount": "100.00",
"AvailableAmount": "100.00",
"Shortfall": "string",
"Message": "string",
"Errors": [
{
"key": "string",
"reason": "string"
}
]
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/cards/physical-card-feesGet Crypto cards physical card production and mailing fees for a user and destination countryRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/cards/physical-card-fees?userId=123&country=GB&cardTypeId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123countryquerystringoptionalExample: GBcardTypeIdqueryintegeroptionalExample: 123200OKCardPhysicalCardFeesResponseV2
{
"Success": true,
"UserId": 123,
"AccountId": "string",
"BinId": "string",
"ExternalBinId": "external_reference_123",
"Zone": "string",
"Fees": [
{
"Amount": "100.00",
"Currency": "USD",
"FeeType": "100.00",
"FeeTypeLabel": "100.00"
}
],
"Message": "string",
"ErrorCode": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/cards/{cardId}/bulk-ship/quoteQuote Crypto cards physical card shipment fees for the authenticated user's card.Request & responses +
Company API-key integrations may supply a target userId within their company or omit/default it to infer the user from the company-owned card. Ordinary JWT callers resolve omitted/default userId to themselves; supported administrator selection remains tenant-authorized.
curl --request GET 'https://staging.hoppa.global/api/v2/cards/123/bulk-ship/quote?userId=0' \
-H 'x-api-key: YOUR_API_KEY'Parameters
cardIdpathintegerrequiredExample: 123userIdqueryintegeroptionalExample: 0200OKCardBulkShipResponseV2
{
"Success": true,
"CardId": 123,
"UserId": 123,
"ExternalCardId": "external_reference_123",
"ShipmentExecuted": true,
"Fees": [
{
"Amount": "100.00",
"Currency": "USD",
"FeeType": "100.00",
"FeeTypeLabel": "100.00"
}
],
"FeeZone": "100.00",
"FeeBinId": "100.00",
"CustomerPaysForProduction": true,
"CustomerPaysForShippment": true,
"CustomerProductionAmount": "100.00",
"CustomerShippingAmount": "100.00",
"RequiredAmount": "100.00",
"RequiredQuantumAmount": "100.00",
"CompanyFundingAmount": "100.00",
"AvailableAmount": "100.00",
"Shortfall": "string",
"CardUnloadAttempted": true,
"CardUnloadSucceeded": true,
"CardUnloadAmount": "100.00",
"TaskId": "string",
"Status": "PENDING",
"Message": "string",
"ErrorCode": "string"
}400Bad RequestCardBulkShipResponseV2
{
"Success": true,
"CardId": 123,
"UserId": 123,
"ExternalCardId": "external_reference_123",
"ShipmentExecuted": true,
"Fees": [
{
"Amount": "100.00",
"Currency": "USD",
"FeeType": "100.00",
"FeeTypeLabel": "100.00"
}
],
"FeeZone": "100.00",
"FeeBinId": "100.00",
"CustomerPaysForProduction": true,
"CustomerPaysForShippment": true,
"CustomerProductionAmount": "100.00",
"CustomerShippingAmount": "100.00",
"RequiredAmount": "100.00",
"RequiredQuantumAmount": "100.00",
"CompanyFundingAmount": "100.00",
"AvailableAmount": "100.00",
"Shortfall": "string",
"CardUnloadAttempted": true,
"CardUnloadSucceeded": true,
"CardUnloadAmount": "100.00",
"TaskId": "string",
"Status": "PENDING",
"Message": "string",
"ErrorCode": "string"
}404Not FoundCardBulkShipResponseV2
{
"Success": true,
"CardId": 123,
"UserId": 123,
"ExternalCardId": "external_reference_123",
"ShipmentExecuted": true,
"Fees": [
{
"Amount": "100.00",
"Currency": "USD",
"FeeType": "100.00",
"FeeTypeLabel": "100.00"
}
],
"FeeZone": "100.00",
"FeeBinId": "100.00",
"CustomerPaysForProduction": true,
"CustomerPaysForShippment": true,
"CustomerProductionAmount": "100.00",
"CustomerShippingAmount": "100.00",
"RequiredAmount": "100.00",
"RequiredQuantumAmount": "100.00",
"CompanyFundingAmount": "100.00",
"AvailableAmount": "100.00",
"Shortfall": "string",
"CardUnloadAttempted": true,
"CardUnloadSucceeded": true,
"CardUnloadAmount": "100.00",
"TaskId": "string",
"Status": "PENDING",
"Message": "string",
"ErrorCode": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/cards/{cardId}/bulk-ship/quoteQuote Crypto cards physical card shipment fees for the authenticated user's card.Request & responses +
Company API-key integrations may supply a target userId within their company or omit/default it to infer the user from the company-owned card. Ordinary JWT callers resolve omitted/default userId to themselves; supported administrator selection remains tenant-authorized.
curl --request POST 'https://staging.hoppa.global/api/v2/cards/123/bulk-ship/quote?userId=0' \
-H 'x-api-key: YOUR_API_KEY'Parameters
cardIdpathintegerrequiredExample: 123userIdqueryintegeroptionalExample: 0200OKCardBulkShipResponseV2
{
"Success": true,
"CardId": 123,
"UserId": 123,
"ExternalCardId": "external_reference_123",
"ShipmentExecuted": true,
"Fees": [
{
"Amount": "100.00",
"Currency": "USD",
"FeeType": "100.00",
"FeeTypeLabel": "100.00"
}
],
"FeeZone": "100.00",
"FeeBinId": "100.00",
"CustomerPaysForProduction": true,
"CustomerPaysForShippment": true,
"CustomerProductionAmount": "100.00",
"CustomerShippingAmount": "100.00",
"RequiredAmount": "100.00",
"RequiredQuantumAmount": "100.00",
"CompanyFundingAmount": "100.00",
"AvailableAmount": "100.00",
"Shortfall": "string",
"CardUnloadAttempted": true,
"CardUnloadSucceeded": true,
"CardUnloadAmount": "100.00",
"TaskId": "string",
"Status": "PENDING",
"Message": "string",
"ErrorCode": "string"
}400Bad RequestCardBulkShipResponseV2
{
"Success": true,
"CardId": 123,
"UserId": 123,
"ExternalCardId": "external_reference_123",
"ShipmentExecuted": true,
"Fees": [
{
"Amount": "100.00",
"Currency": "USD",
"FeeType": "100.00",
"FeeTypeLabel": "100.00"
}
],
"FeeZone": "100.00",
"FeeBinId": "100.00",
"CustomerPaysForProduction": true,
"CustomerPaysForShippment": true,
"CustomerProductionAmount": "100.00",
"CustomerShippingAmount": "100.00",
"RequiredAmount": "100.00",
"RequiredQuantumAmount": "100.00",
"CompanyFundingAmount": "100.00",
"AvailableAmount": "100.00",
"Shortfall": "string",
"CardUnloadAttempted": true,
"CardUnloadSucceeded": true,
"CardUnloadAmount": "100.00",
"TaskId": "string",
"Status": "PENDING",
"Message": "string",
"ErrorCode": "string"
}404Not FoundCardBulkShipResponseV2
{
"Success": true,
"CardId": 123,
"UserId": 123,
"ExternalCardId": "external_reference_123",
"ShipmentExecuted": true,
"Fees": [
{
"Amount": "100.00",
"Currency": "USD",
"FeeType": "100.00",
"FeeTypeLabel": "100.00"
}
],
"FeeZone": "100.00",
"FeeBinId": "100.00",
"CustomerPaysForProduction": true,
"CustomerPaysForShippment": true,
"CustomerProductionAmount": "100.00",
"CustomerShippingAmount": "100.00",
"RequiredAmount": "100.00",
"RequiredQuantumAmount": "100.00",
"CompanyFundingAmount": "100.00",
"AvailableAmount": "100.00",
"Shortfall": "string",
"CardUnloadAttempted": true,
"CardUnloadSucceeded": true,
"CardUnloadAmount": "100.00",
"TaskId": "string",
"Status": "PENDING",
"Message": "string",
"ErrorCode": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/cards/{cardId}/bulk-shipExecute Crypto cards physical card shipment for the authenticated user's card.Request & responses +
Company API-key integrations may supply a target userId within their company or omit/default it to infer the user from the company-owned card. Ordinary JWT callers resolve omitted/default userId to themselves; supported administrator selection remains tenant-authorized.
curl --request POST 'https://staging.hoppa.global/api/v2/cards/123/bulk-ship?userId=0' \
-H 'x-api-key: YOUR_API_KEY'Parameters
cardIdpathintegerrequiredExample: 123userIdqueryintegeroptionalExample: 0200OKCardBulkShipResponseV2
{
"Success": true,
"CardId": 123,
"UserId": 123,
"ExternalCardId": "external_reference_123",
"ShipmentExecuted": true,
"Fees": [
{
"Amount": "100.00",
"Currency": "USD",
"FeeType": "100.00",
"FeeTypeLabel": "100.00"
}
],
"FeeZone": "100.00",
"FeeBinId": "100.00",
"CustomerPaysForProduction": true,
"CustomerPaysForShippment": true,
"CustomerProductionAmount": "100.00",
"CustomerShippingAmount": "100.00",
"RequiredAmount": "100.00",
"RequiredQuantumAmount": "100.00",
"CompanyFundingAmount": "100.00",
"AvailableAmount": "100.00",
"Shortfall": "string",
"CardUnloadAttempted": true,
"CardUnloadSucceeded": true,
"CardUnloadAmount": "100.00",
"TaskId": "string",
"Status": "PENDING",
"Message": "string",
"ErrorCode": "string"
}400Bad RequestCardBulkShipResponseV2
{
"Success": true,
"CardId": 123,
"UserId": 123,
"ExternalCardId": "external_reference_123",
"ShipmentExecuted": true,
"Fees": [
{
"Amount": "100.00",
"Currency": "USD",
"FeeType": "100.00",
"FeeTypeLabel": "100.00"
}
],
"FeeZone": "100.00",
"FeeBinId": "100.00",
"CustomerPaysForProduction": true,
"CustomerPaysForShippment": true,
"CustomerProductionAmount": "100.00",
"CustomerShippingAmount": "100.00",
"RequiredAmount": "100.00",
"RequiredQuantumAmount": "100.00",
"CompanyFundingAmount": "100.00",
"AvailableAmount": "100.00",
"Shortfall": "string",
"CardUnloadAttempted": true,
"CardUnloadSucceeded": true,
"CardUnloadAmount": "100.00",
"TaskId": "string",
"Status": "PENDING",
"Message": "string",
"ErrorCode": "string"
}404Not FoundCardBulkShipResponseV2
{
"Success": true,
"CardId": 123,
"UserId": 123,
"ExternalCardId": "external_reference_123",
"ShipmentExecuted": true,
"Fees": [
{
"Amount": "100.00",
"Currency": "USD",
"FeeType": "100.00",
"FeeTypeLabel": "100.00"
}
],
"FeeZone": "100.00",
"FeeBinId": "100.00",
"CustomerPaysForProduction": true,
"CustomerPaysForShippment": true,
"CustomerProductionAmount": "100.00",
"CustomerShippingAmount": "100.00",
"RequiredAmount": "100.00",
"RequiredQuantumAmount": "100.00",
"CompanyFundingAmount": "100.00",
"AvailableAmount": "100.00",
"Shortfall": "string",
"CardUnloadAttempted": true,
"CardUnloadSucceeded": true,
"CardUnloadAmount": "100.00",
"TaskId": "string",
"Status": "PENDING",
"Message": "string",
"ErrorCode": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/cards/cardHoldersGet list of card holders for a userRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/cards/cardHolders?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123200OKapplication/json
[
{
"Id": 123,
"UserId": 123,
"CompanyId": 123,
"AccountId": "string",
"CardHolderId": "string",
"BinRangeId": 123,
"CardHolderStatus": "PENDING",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}
]400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/cards/{cardId}Get sanitized card details with a masked card numberRequest & responses +
Returns sanitized card details: cardNumber is masked, cardNo is an empty string, and cvv is the placeholder ***. Use the existing secure widget for PAN/CVV.
curl --request GET 'https://staging.hoppa.global/api/v2/cards/123?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123cardIdpathintegerrequiredExample: 123200OKCardDetailsResponseV2
{
"CardNo": "",
"CVV": "***",
"ExpYear": "string",
"ExpMonth": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"DiscountCode": "string",
"Id": 123,
"UserId": 123,
"ExternalCardId": "external_reference_123",
"Provider": "string",
"BudgetId": "string",
"DeliveryAddressId": "string",
"Nickname": "string",
"CardType": "string",
"CardNetwork": "string",
"CardNumber": "****-****-****-1234",
"ExpiryDate": "2026-08-05",
"Status": "PENDING",
"Balance": {
"Available": "string",
"Pending": "string",
"Frozen": "string",
"Currency": "USD"
},
"Currency": "USD",
"VelocityControl": {
"Type": "string",
"Limit": "string"
},
"CardTypeId": 123,
"CardTypeTierId": 123,
"TierId": 123,
"CanSetPin": true,
"AutoLockEnabled": true,
"AutoLockActiveUntil": "2026-08-05T09:30:00Z",
"TransakOrder": "string",
"RequiredAmount": "100.00",
"AvailableAmount": "100.00",
"Shortfall": "string",
"Message": "string",
"Errors": [
{
"key": "string",
"reason": "string"
}
]
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
DELETE/api/v2/cards/{cardId}Permanently delete a Crypto cards.Request & responses +
curl --request DELETE 'https://staging.hoppa.global/api/v2/cards/123?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123cardIdpathintegerrequiredExample: 123200OKCardDeleteResponseV2
{
"Success": true,
"Message": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}409ConflictErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/cards/{cardId}/activateActivate a physical cardRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/cards/123/activate?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123cardIdpathintegerrequiredExample: 123200OKCardActivateResponseV2
{
"Success": true,
"Message": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/cards/{cardId}/freezeFreeze a card to temporarily disable itRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/cards/123/freeze?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123cardIdpathintegerrequiredExample: 123200OKCardFreezeResponseV2
{
"Success": true,
"Message": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/cards/{cardId}/enableEnable (unfreeze) a card to re-enable itRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/cards/123/enable?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123cardIdpathintegerrequiredExample: 123200OKCardEnableResponseV2
{
"Success": true,
"Message": "string",
"AutoLockActiveUntil": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/cards/{cardId}/auto-lockEnable or disable Auto Lock for a cardRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/cards/123/auto-lock?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Enabled": true
}'Parameters
userIdqueryintegeroptionalExample: 123cardIdpathintegerrequiredExample: 123Request fields and validation
Enabled · boolean · optionalExample request body · replace placeholders
{
"Enabled": true
}200OKCardAutoLockResponseV2
{
"Success": true,
"Message": "string",
"AutoLockEnabled": true,
"AutoLockActiveUntil": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/cards/{cardId}/auto-lock/enableEnable Auto Lock (automatic re-freeze) for a cardRequest & responses +
Enabling Auto Lock on an active card freezes it immediately through the card provider. Each later unfreeze (`POST /{cardId}/enable`) opens a 10-minute active window, after which the card is frozen again automatically. No request body is required.
curl --request POST 'https://staging.hoppa.global/api/v2/cards/123/auto-lock/enable?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123cardIdpathintegerrequiredExample: 123200OKCardAutoLockResponseV2
{
"Success": true,
"Message": "string",
"AutoLockEnabled": true,
"AutoLockActiveUntil": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/cards/{cardId}/auto-lock/disableDisable Auto Lock for a cardRequest & responses +
Clears any pending automatic freeze window. The card's current status is not changed; a frozen card stays frozen until it is unfrozen. No request body is required.
curl --request POST 'https://staging.hoppa.global/api/v2/cards/123/auto-lock/disable?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123cardIdpathintegerrequiredExample: 123200OKCardAutoLockResponseV2
{
"Success": true,
"Message": "string",
"AutoLockEnabled": true,
"AutoLockActiveUntil": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/cards/{cardId}/transactionsGet card transactions for a specific user and cardRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/cards/123/transactions?userId=123&limit=25&page=1' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123cardIdpathintegerrequiredExample: 123limitqueryintegeroptionalExample: 25pagequeryintegeroptionalExample: 1200OKCardTransactionsResponseV2
{
"Transactions": [
{
"Id": "string",
"AccountId": "string",
"CardId": "string",
"Currency": "USD",
"Amount": 100,
"Fee": 100,
"Type": "string",
"ClientTransactionId": "string",
"Remark": "string",
"Detail": "string",
"Status": "PENDING",
"TransactionTime": "2026-08-05T09:30:00Z",
"TransactionCurrency": "USD",
"TransactionAmount": 100,
"MerchantName": "string",
"Mcc": "string",
"MccCategory": "string",
"MerchantCity": "London",
"MerchantCountry": "GB",
"MerchantState": "string",
"MerchantZipcode": "SW1A 1AA",
"MerchantMid": "string"
}
],
"Total": 1,
"PageTotal": 1,
"CurrentPage": 1,
"HasMorePages": true
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/cards/{cardId}/pinUpdate card PINRequest & responses +
**PIN Code Rules** 1. **Length** The PIN must be exactly 6 digits. 2. **No repeated digits** It must not contain any sequence of three identical digits. Not allowed: `111`, `222`, `999` 3. **No sequential digits** No three consecutive increasing or decreasing digits. Examples not allowed: `123`, `234`, `789`, `890`, `098`, `321`
curl --request PUT 'https://staging.hoppa.global/api/v2/cards/123/pin?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Pin": "246805"
}'Parameters
userIdqueryintegeroptionalExample: 123cardIdpathintegerrequiredExample: 123Request fields and validation
Pin · string · required**PIN Code Rules** 1. **Length** The PIN must be exactly 6 digits. 2. **No repeated digits** It must not contain any sequence of three identical digits. Not allowed: `111`, `222`, `999` 3. **No sequential digits** No three consecutive increasing or decreasing digits. Examples not allowed: `123`, `234`, `789`, `890`, `098`, `321`
Minimum length: 6
Maximum length: 6
Pattern: ^[0-9]{6}$
Example request body · replace placeholders
{
"Pin": "246805"
}200OKCardUpdatePinResponseV2
{
"Success": true,
"Message": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/cards/topupTopUp - Direct card top-up with card IDRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/cards/topup' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"CardId": 123,
"Token": "USDC",
"Value": 100
}'Request fields and validation
CardId · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
Token · string · optionalValue · number · optionalMinimum: 5
Maximum: 250000
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Example request body · replace placeholders
{
"CardId": 123,
"Token": "USDC",
"Value": 100
}200OKTopUpResponse
{
"Success": true,
"TransakUrl": "https://example.com/callback",
"OrderId": "string",
"Token": "USDC",
"Value": 100,
"WalletAddress": "0x1111111111111111111111111111111111111111",
"Message": "string",
"ErrorCode": "string",
"ErrorMessage": "string",
"Fee": 100,
"RequestedValue": 100,
"GrossValue": 100,
"IsPartial": true,
"CreatedAt": "2026-08-05T09:30:00Z",
"Configuration": {
"FiatCurrency": "USD",
"CryptoCurrency": "USDC",
"Network": "string",
"MinAmount": 100,
"MaxAmount": 100,
"IsTestMode": true
}
}400Bad RequestProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/cards/unload-cardUnloadFromCard - Unload funds from a card to quantum walletRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/cards/unload-card' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"CardId": 123,
"Currency": "USD",
"Value": 100
}'Request fields and validation
CardId · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
Currency · string · optionalValue · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Example request body · replace placeholders
{
"CardId": 123,
"Currency": "USD",
"Value": 100
}200OKCardUnloadResponse
{
"Success": true,
"CardId": 123,
"ExternalCardId": "external_reference_123",
"RequestedAmount": 100,
"ActualAmount": 100,
"Fee": 100,
"NetAmount": 100,
"Currency": "USD",
"Status": "PENDING",
"TransactionId": "string",
"ExternalTransactionId": "external_reference_123",
"RequestedAt": "2026-08-05T09:30:00Z",
"ProcessedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z",
"Destination": {
"Type": "string",
"AccountNumber": "string",
"WalletAddress": "0x1111111111111111111111111111111111111111",
"BankName": "string",
"RoutingNumber": "string",
"SwiftCode": "string",
"AccountHolderName": "string",
"IsVerified": true
},
"BalanceAfter": {
"AvailableBalance": 100,
"PendingBalance": 100,
"TotalBalance": 100,
"Currency": "USD",
"UpdatedAt": "2026-08-05T09:30:00Z"
},
"ErrorCode": "string",
"ErrorMessage": "string",
"Message": "string",
"Audit": {
"RequestedBy": "string",
"RequestedAt": "2026-08-05T09:30:00Z",
"RequestSource": "string",
"IPAddress": "string",
"UserAgent": "string",
"IsSecureConnection": true,
"AuthenticationMethod": "string",
"AdditionalNotes": "string"
}
}400Bad RequestProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/cards/{cardId}/widgetGet secure widget URL for displaying card details in an iframeRequest & responses +
Returns the existing secure reveal widget for a card owned by or assigned to the selected user. Company API-key integrations supply userId within their company and do not need a verificationToken. JWT callers must supply a verified CARD_SECURE_DATA token bound to this card. Reveal responses use no-store caching.
curl --request GET 'https://staging.hoppa.global/api/v2/cards/123/widget?userId=123&verificationToken=PLACEHOLDER_TOKEN' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123verificationTokenquerystringoptionalExample: PLACEHOLDER_TOKENcardIdpathintegerrequiredExample: 123200OKCardWidgetResponse
{
"Success": true,
"WidgetUrl": "https://example.com/callback",
"WidgetToken": "string",
"ExpiresIn": 1,
"ErrorCode": "string",
"ErrorMessage": "string",
"CardId": 123,
"Config": {
"PrimaryColor": "string",
"BackgroundColor": "string",
"TextColor": "string",
"Width": "string",
"Height": "string"
}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}403JWT reveal requires card-data verification: CARD_DATA_VERIFICATION_REQUIRED or INVALID_CARD_DATA_VERIFICATION.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/cards/{cardId}/auto-topupGet all auto top-up settings and current UTC-month usage for a user's card.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/cards/123/auto-topup?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
cardIdpathintegerrequiredExample: 123userIdqueryintegerrequiredExample: 123200OKPublicAutoTopUpSettingsResponse
{
"Success": true,
"Message": "string",
"CardId": 123,
"LowBalanceEnabled": true,
"Watermark": 100,
"TargetBalance": 100,
"LowBalanceMonthlyLimit": 100,
"LowBalanceDisclaimerAccepted": true,
"LowBalanceDisclaimerAcceptedAt": "2026-08-05T09:30:00Z",
"FailedTxEnabled": true,
"FailedTxMaxAmount": 100,
"FailedTxMonthlyLimit": 100,
"FailedTxDisclaimerAccepted": true,
"FailedTxDisclaimerAcceptedAt": "2026-08-05T09:30:00Z",
"DepositEnabled": true,
"DepositSettings": [
{
"Currency": "USD",
"Enabled": true,
"MaxAmount": 100,
"DisclaimerAccepted": true,
"DisclaimerAcceptedAt": "2026-08-05T09:30:00Z",
"UsedThisMonth": 100
}
],
"AssignedDepositCurrencies": [
{
"Currency": "USD",
"CardId": 123,
"MaskedCardNumber": "string"
}
],
"LowBalanceUsedThisMonth": 100,
"FailedTxUsedThisMonth": 100
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}403ForbiddenProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/cards/auto-topup/low-balanceEnable, update or disable low-balance auto top-up.Request & responses +
Enabling this mode disables failed-transaction and deposit auto top-up on the same card.
curl --request POST 'https://staging.hoppa.global/api/v2/cards/auto-topup/low-balance?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"CardId": 123,
"Enabled": true,
"Watermark": 100,
"TargetBalance": 100,
"MonthlyLimit": 100,
"DisclaimerAccepted": true
}'Parameters
userIdqueryintegerrequiredExample: 123Request fields and validation
CardId · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
Enabled · boolean · optionalWatermark · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
TargetBalance · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
MonthlyLimit · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
DisclaimerAccepted · boolean · optionalExample request body · replace placeholders
{
"CardId": 123,
"Enabled": true,
"Watermark": 100,
"TargetBalance": 100,
"MonthlyLimit": 100,
"DisclaimerAccepted": true
}200OKPublicAutoTopUpSettingsResponse
{
"Success": true,
"Message": "string",
"CardId": 123,
"LowBalanceEnabled": true,
"Watermark": 100,
"TargetBalance": 100,
"LowBalanceMonthlyLimit": 100,
"LowBalanceDisclaimerAccepted": true,
"LowBalanceDisclaimerAcceptedAt": "2026-08-05T09:30:00Z",
"FailedTxEnabled": true,
"FailedTxMaxAmount": 100,
"FailedTxMonthlyLimit": 100,
"FailedTxDisclaimerAccepted": true,
"FailedTxDisclaimerAcceptedAt": "2026-08-05T09:30:00Z",
"DepositEnabled": true,
"DepositSettings": [
{
"Currency": "USD",
"Enabled": true,
"MaxAmount": 100,
"DisclaimerAccepted": true,
"DisclaimerAcceptedAt": "2026-08-05T09:30:00Z",
"UsedThisMonth": 100
}
],
"AssignedDepositCurrencies": [
{
"Currency": "USD",
"CardId": 123,
"MaskedCardNumber": "string"
}
],
"LowBalanceUsedThisMonth": 100,
"FailedTxUsedThisMonth": 100
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}403ForbiddenProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/cards/auto-topup/failed-txEnable, update or disable failed-transaction auto top-up.Request & responses +
Enabling this mode disables low-balance and deposit auto top-up on the same card.
curl --request POST 'https://staging.hoppa.global/api/v2/cards/auto-topup/failed-tx?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"CardId": 123,
"Enabled": true,
"MaxAmount": 100,
"MonthlyLimit": 100,
"DisclaimerAccepted": true
}'Parameters
userIdqueryintegerrequiredExample: 123Request fields and validation
CardId · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
Enabled · boolean · optionalMaxAmount · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
MonthlyLimit · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
DisclaimerAccepted · boolean · optionalExample request body · replace placeholders
{
"CardId": 123,
"Enabled": true,
"MaxAmount": 100,
"MonthlyLimit": 100,
"DisclaimerAccepted": true
}200OKPublicAutoTopUpSettingsResponse
{
"Success": true,
"Message": "string",
"CardId": 123,
"LowBalanceEnabled": true,
"Watermark": 100,
"TargetBalance": 100,
"LowBalanceMonthlyLimit": 100,
"LowBalanceDisclaimerAccepted": true,
"LowBalanceDisclaimerAcceptedAt": "2026-08-05T09:30:00Z",
"FailedTxEnabled": true,
"FailedTxMaxAmount": 100,
"FailedTxMonthlyLimit": 100,
"FailedTxDisclaimerAccepted": true,
"FailedTxDisclaimerAcceptedAt": "2026-08-05T09:30:00Z",
"DepositEnabled": true,
"DepositSettings": [
{
"Currency": "USD",
"Enabled": true,
"MaxAmount": 100,
"DisclaimerAccepted": true,
"DisclaimerAcceptedAt": "2026-08-05T09:30:00Z",
"UsedThisMonth": 100
}
],
"AssignedDepositCurrencies": [
{
"Currency": "USD",
"CardId": 123,
"MaskedCardNumber": "string"
}
],
"LowBalanceUsedThisMonth": 100,
"FailedTxUsedThisMonth": 100
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}403ForbiddenProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/cards/auto-topup/depositUpdate USDC/USDT deposit auto top-up settings on a Crypto cards.Request & responses +
Only supplied currencies are updated. Enabling a currency disables other auto top-up modes on this card. Each deposit currency can be enabled on only one card per user. Explicit disclaimer acceptance is required when enabling any mode.
curl --request POST 'https://staging.hoppa.global/api/v2/cards/auto-topup/deposit?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"CardId": 123,
"Settings": [
{
"Currency": "USD",
"Enabled": true,
"MaxAmount": 100
}
],
"DisclaimerAccepted": true
}'Parameters
userIdqueryintegerrequiredExample: 123Request fields and validation
CardId · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
Settings · array · optionalDisclaimerAccepted · boolean · optionalExample request body · replace placeholders
{
"CardId": 123,
"Settings": [
{
"Currency": "USD",
"Enabled": true,
"MaxAmount": 100
}
],
"DisclaimerAccepted": true
}200OKPublicAutoTopUpSettingsResponse
{
"Success": true,
"Message": "string",
"CardId": 123,
"LowBalanceEnabled": true,
"Watermark": 100,
"TargetBalance": 100,
"LowBalanceMonthlyLimit": 100,
"LowBalanceDisclaimerAccepted": true,
"LowBalanceDisclaimerAcceptedAt": "2026-08-05T09:30:00Z",
"FailedTxEnabled": true,
"FailedTxMaxAmount": 100,
"FailedTxMonthlyLimit": 100,
"FailedTxDisclaimerAccepted": true,
"FailedTxDisclaimerAcceptedAt": "2026-08-05T09:30:00Z",
"DepositEnabled": true,
"DepositSettings": [
{
"Currency": "USD",
"Enabled": true,
"MaxAmount": 100,
"DisclaimerAccepted": true,
"DisclaimerAcceptedAt": "2026-08-05T09:30:00Z",
"UsedThisMonth": 100
}
],
"AssignedDepositCurrencies": [
{
"Currency": "USD",
"CardId": 123,
"MaskedCardNumber": "string"
}
],
"LowBalanceUsedThisMonth": 100,
"FailedTxUsedThisMonth": 100
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}403ForbiddenProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
Company Referrals72 operations
GET/api/v2/referrals/programs/{programId}/boosts/capabilitiesOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/boosts/capabilities' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKReferralBoostCapabilities
{
"Enabled": true,
"SupportedKinds": [
"string"
],
"Cohort": "string",
"StackingAllowed": true,
"SupportedDeliveryMode": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programs/{programId}/boostsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/boosts' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"Kind": "string",
"Status": "PENDING",
"StartsAt": "2026-08-05T09:30:00Z",
"EndsAt": "2026-08-05T09:30:00Z",
"Multiplier": 100,
"QualifiedFriendCount": 1,
"MilestoneAmount": 100,
"MaximumIncrementalReward": 100,
"MaximumAwards": 1,
"FundedBudget": 100,
"Currency": "USD",
"AllocatedAwards": 1,
"ReservedBudget": 100,
"PolicyHash": "string"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/programs/{programId}/boostsOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/boosts' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Name": "string",
"Kind": "string",
"StartsAt": "2026-08-05T09:30:00Z",
"EndsAt": "2026-08-05T09:30:00Z",
"Multiplier": 100,
"QualifiedFriendCount": 1,
"MilestoneAmount": 100,
"MaximumIncrementalReward": 100,
"MaximumAwards": 1,
"FundedBudget": 100,
"Currency": "USD",
"ExpectedProgramRevision": 1
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
Name · string · optionalKind · string · optionalStartsAt · string · optionalEndsAt · string · optionalMultiplier · number or null · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
QualifiedFriendCount · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
MilestoneAmount · number or null · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
MaximumIncrementalReward · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
MaximumAwards · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
FundedBudget · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Currency · string · optionalExpectedProgramRevision · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"Name": "string",
"Kind": "string",
"StartsAt": "2026-08-05T09:30:00Z",
"EndsAt": "2026-08-05T09:30:00Z",
"Multiplier": 100,
"QualifiedFriendCount": 1,
"MilestoneAmount": 100,
"MaximumIncrementalReward": 100,
"MaximumAwards": 1,
"FundedBudget": 100,
"Currency": "USD",
"ExpectedProgramRevision": 1
}200OKReferralBoostResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"Kind": "string",
"Status": "PENDING",
"StartsAt": "2026-08-05T09:30:00Z",
"EndsAt": "2026-08-05T09:30:00Z",
"Multiplier": 100,
"QualifiedFriendCount": 1,
"MilestoneAmount": 100,
"MaximumIncrementalReward": 100,
"MaximumAwards": 1,
"FundedBudget": 100,
"Currency": "USD",
"AllocatedAwards": 1,
"ReservedBudget": 100,
"PolicyHash": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/programs/{programId}/boosts/{boostId}/activateOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/boosts/00000000-0000-4000-8000-000000000123/activate' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"ExpectedProgramRevision": 1
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123boostIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
ExpectedProgramRevision · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"ExpectedProgramRevision": 1
}200OKReferralBoostResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"Kind": "string",
"Status": "PENDING",
"StartsAt": "2026-08-05T09:30:00Z",
"EndsAt": "2026-08-05T09:30:00Z",
"Multiplier": 100,
"QualifiedFriendCount": 1,
"MilestoneAmount": 100,
"MaximumIncrementalReward": 100,
"MaximumAwards": 1,
"FundedBudget": 100,
"Currency": "USD",
"AllocatedAwards": 1,
"ReservedBudget": 100,
"PolicyHash": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/programs/{programId}/boosts/{boostId}/pauseOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/boosts/00000000-0000-4000-8000-000000000123/pause' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"ExpectedProgramRevision": 1
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123boostIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
ExpectedProgramRevision · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"ExpectedProgramRevision": 1
}200OKReferralBoostResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"Kind": "string",
"Status": "PENDING",
"StartsAt": "2026-08-05T09:30:00Z",
"EndsAt": "2026-08-05T09:30:00Z",
"Multiplier": 100,
"QualifiedFriendCount": 1,
"MilestoneAmount": 100,
"MaximumIncrementalReward": 100,
"MaximumAwards": 1,
"FundedBudget": 100,
"Currency": "USD",
"AllocatedAwards": 1,
"ReservedBudget": 100,
"PolicyHash": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programs/{programId}/geo-policyOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/geo-policy' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKReferralGeoPolicySnapshot
{
"VersionId": "00000000-0000-4000-8000-000000000123",
"Revision": 1,
"Enabled": true,
"AllowedCountryCodes": [
"GB"
],
"PendingExpiryDays": 1,
"DefaultLocale": "string",
"TermsVersion": 1,
"TermsByLocale": {
"FIELD_FROM_APPLICATION": "string"
},
"ExcludedCountryCodes": [
"GB"
],
"CountryBasis": "GB",
"PendingDeadlineBasis": "string",
"PendingDeadlineExplanation": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/referrals/programs/{programId}/geo-policyOpen request and response documentationRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/geo-policy' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"ExpectedRevision": 1,
"Enabled": true,
"AllowedCountryCodes": [
"GB"
],
"PendingExpiryDays": 1,
"DefaultLocale": "string",
"TermsVersion": 1,
"TermsByLocale": {
"FIELD_FROM_APPLICATION": "string"
},
"ExcludedCountryCodes": [
"GB"
],
"CountryBasis": "GB"
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
ExpectedRevision · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
Enabled · boolean · requiredAllowedCountryCodes · array · requiredPendingExpiryDays · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
DefaultLocale · string · requiredTermsVersion · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
TermsByLocale · object · requiredExcludedCountryCodes · array or null · optionalCountryBasis · string · optionalExample request body · replace placeholders
{
"ExpectedRevision": 1,
"Enabled": true,
"AllowedCountryCodes": [
"GB"
],
"PendingExpiryDays": 1,
"DefaultLocale": "string",
"TermsVersion": 1,
"TermsByLocale": {
"FIELD_FROM_APPLICATION": "string"
},
"ExcludedCountryCodes": [
"GB"
],
"CountryBasis": "GB"
}200OKReferralGeoPolicySnapshot
{
"VersionId": "00000000-0000-4000-8000-000000000123",
"Revision": 1,
"Enabled": true,
"AllowedCountryCodes": [
"GB"
],
"PendingExpiryDays": 1,
"DefaultLocale": "string",
"TermsVersion": 1,
"TermsByLocale": {
"FIELD_FROM_APPLICATION": "string"
},
"ExcludedCountryCodes": [
"GB"
],
"CountryBasis": "GB",
"PendingDeadlineBasis": "string",
"PendingDeadlineExplanation": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programs/{programId}/localized-termsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/localized-terms?locale=example' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123localequerystringoptionalExample: example200OKReferralGeoLocalizedTerms
{
"RequestedLocale": "string",
"Locale": "string",
"IsFallback": true,
"TermsVersion": 1,
"ContentHash": "string",
"Text": "string",
"PolicyVersionId": "00000000-0000-4000-8000-000000000123",
"EligibilityRequired": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/capabilitiesOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/capabilities' \
-H 'x-api-key: YOUR_API_KEY'200OKReferralBuildCapabilities
{
"MarginSharingEnabled": true,
"SubpartnersEnabled": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/programs/{programId}/simulateOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/simulate' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"LevelCode": "string",
"Draft": {
"Policy": {
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"EarningWindowStart": "string",
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"Levels": [
{
"Code": {},
"Name": {},
"Icon": {},
"Color": {},
"QualificationCalculationType": {},
"TopupCalculationType": {},
"VolumeCapMode": {},
"VolumeCapAmount": {},
"RecurringRewardCapMode": {},
"RecurringRewardCapAmount": {},
"Id": {},
"DisplayOrder": {},
"MinimumMetricValue": {},
"MinimumQualifiedReferrals": {},
"MinimumTopupVolume": {},
"QualificationRate": {},
"TopupRate": {},
"Hidden": {}
}
],
"PromoCodePolicyEnabled": true,
"MaximumRecurringReward": 100,
"Description": "Example description",
"Revision": 1,
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishNewTermsVersion": true
},
"Margin": {
"Direct": {
"CompanyBps": {},
"AffiliateBps": {},
"SubpartnerBps": {},
"CustomerBps": {},
"BudgetBps": {}
},
"Team": {}
},
"DraftRevision": 1
},
"CreditedAmount": 100,
"SettledFee": 100,
"ProviderCost": 100,
"EligibleVolumeRemaining": 100,
"PaidCardFee": 100,
"CompletesQualification": true,
"PromoCodeUsed": true,
"Team": true
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
LevelCode · string · requiredDraft · object or null · optionalCreditedAmount · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
SettledFee · number or null · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
ProviderCost · number or null · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
EligibleVolumeRemaining · number or null · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
PaidCardFee · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
CompletesQualification · boolean · optionalPromoCodeUsed · boolean · optionalTeam · boolean · optionalExample request body · replace placeholders
{
"LevelCode": "string",
"Draft": {
"Policy": {
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"EarningWindowStart": "string",
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"Levels": [
{
"Code": {},
"Name": {},
"Icon": {},
"Color": {},
"QualificationCalculationType": {},
"TopupCalculationType": {},
"VolumeCapMode": {},
"VolumeCapAmount": {},
"RecurringRewardCapMode": {},
"RecurringRewardCapAmount": {},
"Id": {},
"DisplayOrder": {},
"MinimumMetricValue": {},
"MinimumQualifiedReferrals": {},
"MinimumTopupVolume": {},
"QualificationRate": {},
"TopupRate": {},
"Hidden": {}
}
],
"PromoCodePolicyEnabled": true,
"MaximumRecurringReward": 100,
"Description": "Example description",
"Revision": 1,
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishNewTermsVersion": true
},
"Margin": {
"Direct": {
"CompanyBps": {},
"AffiliateBps": {},
"SubpartnerBps": {},
"CustomerBps": {},
"BudgetBps": {}
},
"Team": {}
},
"DraftRevision": 1
},
"CreditedAmount": 100,
"SettledFee": 100,
"ProviderCost": 100,
"EligibleVolumeRemaining": 100,
"PaidCardFee": 100,
"CompletesQualification": true,
"PromoCodeUsed": true,
"Team": true
}200OKReferralSimulationResponse
{
"CalculationVersion": "string",
"Currency": "USD",
"Basis": "string",
"EligibleAmount": 100,
"InviterReward": 100,
"CustomerRecurringReward": 100,
"SubpartnerReward": 100,
"CompanyRetained": 100,
"QualificationReward": 100,
"WelcomeReward": 100,
"Status": "PENDING",
"Warnings": [
"string"
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programs/{programId}/versionsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/versions' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"BaseRevision": 1,
"DraftRevision": 1,
"Status": "PENDING",
"Draft": {
"Policy": {
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"EarningWindowStart": "string",
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"Levels": [
{
"Code": {},
"Name": {},
"Icon": {},
"Color": {},
"QualificationCalculationType": {},
"TopupCalculationType": {},
"VolumeCapMode": {},
"VolumeCapAmount": {},
"RecurringRewardCapMode": {},
"RecurringRewardCapAmount": {},
"Id": {},
"DisplayOrder": {},
"MinimumMetricValue": {},
"MinimumQualifiedReferrals": {},
"MinimumTopupVolume": {},
"QualificationRate": {},
"TopupRate": {},
"Hidden": {}
}
],
"PromoCodePolicyEnabled": true,
"MaximumRecurringReward": 100,
"Description": "Example description",
"Revision": 1,
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishNewTermsVersion": true
},
"Margin": {
"Direct": {
"CompanyBps": {},
"AffiliateBps": {},
"SubpartnerBps": {},
"CustomerBps": {},
"BudgetBps": {}
},
"Team": {}
},
"DraftRevision": 1
},
"EffectiveAt": "2026-08-05T09:30:00Z",
"Reason": "string"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/programs/{programId}/draftsOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/drafts' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Policy": {
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"EarningWindowStart": "string",
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"Levels": [
{
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"QualificationCalculationType": "string",
"TopupCalculationType": "string",
"VolumeCapMode": "100.00",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "string",
"RecurringRewardCapAmount": 100,
"Id": "00000000-0000-4000-8000-000000000123",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"QualificationRate": 100,
"TopupRate": 100,
"Hidden": true
}
],
"PromoCodePolicyEnabled": true,
"MaximumRecurringReward": 100,
"Description": "Example description",
"Revision": 1,
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishNewTermsVersion": true
},
"Margin": {
"Direct": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
},
"Team": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
}
},
"DraftRevision": 1
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
Policy · object · requiredMargin · object or null · optionalDraftRevision · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"Policy": {
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"EarningWindowStart": "string",
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"Levels": [
{
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"QualificationCalculationType": "string",
"TopupCalculationType": "string",
"VolumeCapMode": "100.00",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "string",
"RecurringRewardCapAmount": 100,
"Id": "00000000-0000-4000-8000-000000000123",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"QualificationRate": 100,
"TopupRate": 100,
"Hidden": true
}
],
"PromoCodePolicyEnabled": true,
"MaximumRecurringReward": 100,
"Description": "Example description",
"Revision": 1,
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishNewTermsVersion": true
},
"Margin": {
"Direct": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
},
"Team": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
}
},
"DraftRevision": 1
}200OKReferralDraftResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"BaseRevision": 1,
"DraftRevision": 1,
"Status": "PENDING",
"Draft": {
"Policy": {
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"EarningWindowStart": "string",
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"Levels": [
{
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"QualificationCalculationType": "string",
"TopupCalculationType": "string",
"VolumeCapMode": "100.00",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "string",
"RecurringRewardCapAmount": 100,
"Id": "00000000-0000-4000-8000-000000000123",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"QualificationRate": 100,
"TopupRate": 100,
"Hidden": true
}
],
"PromoCodePolicyEnabled": true,
"MaximumRecurringReward": 100,
"Description": "Example description",
"Revision": 1,
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishNewTermsVersion": true
},
"Margin": {
"Direct": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
},
"Team": {
"CompanyBps": {},
"AffiliateBps": {},
"SubpartnerBps": {},
"CustomerBps": {},
"BudgetBps": {}
}
},
"DraftRevision": 1
},
"EffectiveAt": "2026-08-05T09:30:00Z",
"Reason": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/referrals/programs/{programId}/drafts/{draftId}Open request and response documentationRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/drafts/00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Policy": {
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"EarningWindowStart": "string",
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"Levels": [
{
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"QualificationCalculationType": "string",
"TopupCalculationType": "string",
"VolumeCapMode": "100.00",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "string",
"RecurringRewardCapAmount": 100,
"Id": "00000000-0000-4000-8000-000000000123",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"QualificationRate": 100,
"TopupRate": 100,
"Hidden": true
}
],
"PromoCodePolicyEnabled": true,
"MaximumRecurringReward": 100,
"Description": "Example description",
"Revision": 1,
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishNewTermsVersion": true
},
"Margin": {
"Direct": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
},
"Team": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
}
},
"DraftRevision": 1
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123draftIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
Policy · object · requiredMargin · object or null · optionalDraftRevision · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"Policy": {
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"EarningWindowStart": "string",
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"Levels": [
{
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"QualificationCalculationType": "string",
"TopupCalculationType": "string",
"VolumeCapMode": "100.00",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "string",
"RecurringRewardCapAmount": 100,
"Id": "00000000-0000-4000-8000-000000000123",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"QualificationRate": 100,
"TopupRate": 100,
"Hidden": true
}
],
"PromoCodePolicyEnabled": true,
"MaximumRecurringReward": 100,
"Description": "Example description",
"Revision": 1,
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishNewTermsVersion": true
},
"Margin": {
"Direct": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
},
"Team": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
}
},
"DraftRevision": 1
}200OKReferralDraftResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"BaseRevision": 1,
"DraftRevision": 1,
"Status": "PENDING",
"Draft": {
"Policy": {
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"EarningWindowStart": "string",
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"Levels": [
{
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"QualificationCalculationType": "string",
"TopupCalculationType": "string",
"VolumeCapMode": "100.00",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "string",
"RecurringRewardCapAmount": 100,
"Id": "00000000-0000-4000-8000-000000000123",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"QualificationRate": 100,
"TopupRate": 100,
"Hidden": true
}
],
"PromoCodePolicyEnabled": true,
"MaximumRecurringReward": 100,
"Description": "Example description",
"Revision": 1,
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishNewTermsVersion": true
},
"Margin": {
"Direct": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
},
"Team": {
"CompanyBps": {},
"AffiliateBps": {},
"SubpartnerBps": {},
"CustomerBps": {},
"BudgetBps": {}
}
},
"DraftRevision": 1
},
"EffectiveAt": "2026-08-05T09:30:00Z",
"Reason": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/programs/{programId}/drafts/{draftId}/change-previewOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/drafts/00000000-0000-4000-8000-000000000123/change-preview' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"DraftRevision": 1,
"EffectiveAt": "2026-08-05T09:30:00Z"
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123draftIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
DraftRevision · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
EffectiveAt · string · optionalExample request body · replace placeholders
{
"DraftRevision": 1,
"EffectiveAt": "2026-08-05T09:30:00Z"
}200OKReferralChangePreview
{
"DraftId": "00000000-0000-4000-8000-000000000123",
"DraftRevision": 1,
"Hash": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"EffectiveAt": "2026-08-05T09:30:00Z",
"ExistingQualified": 1,
"ExistingUnqualified": 1,
"Cohort": "string",
"ChangedFields": [
"string"
],
"TermsAcceptanceRequired": true,
"Warnings": [
"string"
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/programs/{programId}/drafts/{draftId}/publishOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/drafts/00000000-0000-4000-8000-000000000123/publish' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"PreviewHash": "string",
"IdempotencyKey": "operation-customer-1042-001",
"Reason": "string"
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123draftIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
PreviewHash · string · requiredMaximum length: 100
IdempotencyKey · string · requiredMaximum length: 100
Reason · string · requiredMaximum length: 2000
Example request body · replace placeholders
{
"PreviewHash": "string",
"IdempotencyKey": "operation-customer-1042-001",
"Reason": "string"
}200OKReferralDraftResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"BaseRevision": 1,
"DraftRevision": 1,
"Status": "PENDING",
"Draft": {
"Policy": {
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"EarningWindowStart": "string",
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"Levels": [
{
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"QualificationCalculationType": "string",
"TopupCalculationType": "string",
"VolumeCapMode": "100.00",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "string",
"RecurringRewardCapAmount": 100,
"Id": "00000000-0000-4000-8000-000000000123",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"QualificationRate": 100,
"TopupRate": 100,
"Hidden": true
}
],
"PromoCodePolicyEnabled": true,
"MaximumRecurringReward": 100,
"Description": "Example description",
"Revision": 1,
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishNewTermsVersion": true
},
"Margin": {
"Direct": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
},
"Team": {
"CompanyBps": {},
"AffiliateBps": {},
"SubpartnerBps": {},
"CustomerBps": {},
"BudgetBps": {}
}
},
"DraftRevision": 1
},
"EffectiveAt": "2026-08-05T09:30:00Z",
"Reason": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programs/{programId}/teamOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/team' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKapplication/json
{
"FIELD_FROM_APPLICATION": 1
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/referrals/programs/{programId}/team/{childId}/{parentId}Open request and response documentationRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/team/123/123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123childIdpathintegerrequiredExample: 123parentIdpathintegerrequiredExample: 123204No ContentNo response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs' \
-H 'x-api-key: YOUR_API_KEY'200OKapplication/json
[
{
"Exists": true,
"Id": "00000000-0000-4000-8000-000000000123",
"Provider": "string",
"Status": "PENDING",
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"EarningWindowStart": "string",
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"ReservedExposure": 100,
"TermsVersion": 1,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishedAt": "2026-08-05T09:30:00Z",
"Levels": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
}
],
"UpdatedAt": "2026-08-05T09:30:00Z",
"Name": "Public referral program",
"Visibility": "PUBLIC",
"Description": "Example description",
"Revision": 1,
"OfferVersionId": "00000000-0000-4000-8000-000000000123",
"MarginPolicy": {
"Direct": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
},
"Team": {
"CompanyBps": {},
"AffiliateBps": {},
"SubpartnerBps": {},
"CustomerBps": {},
"BudgetBps": {}
}
},
"MaximumRecurringReward": 100,
"PromoCodePolicyEnabled": false
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/programsOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/programs' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"EarningWindowStart": "string",
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"Levels": [
{
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"QualificationCalculationType": "string",
"TopupCalculationType": "string",
"VolumeCapMode": "100.00",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "string",
"RecurringRewardCapAmount": 100,
"Id": "00000000-0000-4000-8000-000000000123",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"QualificationRate": 100,
"TopupRate": 100,
"Hidden": true
}
],
"PromoCodePolicyEnabled": true,
"MaximumRecurringReward": 100,
"Description": "Example description",
"Revision": 1,
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishNewTermsVersion": true
}'Request fields and validation
PromoCodePolicyEnabled · boolean or null · optionalNull preserves the setting for older admin clients.
MaximumRecurringReward · number or null · optionalMinimum: 0
Maximum: 999999999999
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Name · string · requiredMaximum length: 80
Description · string or null · optionalShown to members on the offer panel instead of the generated explanation when set.
Maximum length: 2000
Visibility · string · requiredRevision · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
Status · string · requiredLevelBasis · string or null · optionalDeprecated and optional. SUCCESSFUL_REFERRAL_COUNT or REFERRED_TOPUP_VOLUME; stored as is, decides nothing.
LevelLookbackMonths · integer · optionalMinimum: 0
Maximum: 1200
Pattern: ^-?(?:0|[1-9]\d*)$
EarningWindowDays · integer · optionalMinimum: 0
Maximum: 36500
Pattern: ^-?(?:0|[1-9]\d*)$
EarningWindowStart · string · requiredQualifyRequiresKyc · boolean · optionalQualifyRequiresPaidCard · boolean · optionalQualifyRequiresTopup · boolean · optionalQualifyMinimumTopup · number or null · optionalNull means the platform card top-up minimum applies.
Minimum: 0
Maximum: 9999999999
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
WelcomeAmount · number · optionalMinimum: 0
Maximum: 9999999999
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
WelcomeCurrency · string · requiredDeliveryMode · string · requiredPayoutCurrency · string · requiredVoucherClaimDays · integer · optionalMinimum: 1
Maximum: 365
Pattern: ^-?(?:0|[1-9]\d*)$
MinimumCreditAmount · number · optionalMinimum: 0
Maximum: 9999999999
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
MaxEligibleVolumePerRelationship · number or null · optionalMinimum: 0
Maximum: 9999999999
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
ExposureLimit · number or null · optionalMinimum: 0
Maximum: 9999999999
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
TermsText · string or null · optionalMaximum length: 20000
PrivacyNotice · string or null · optionalMaximum length: 5000
PublishNewTermsVersion · boolean · optionalWhen true the terms version is bumped even if rates did not change.
Levels · array · requiredExample request body · replace placeholders
{
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"EarningWindowStart": "string",
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"Levels": [
{
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"QualificationCalculationType": "string",
"TopupCalculationType": "string",
"VolumeCapMode": "100.00",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "string",
"RecurringRewardCapAmount": 100,
"Id": "00000000-0000-4000-8000-000000000123",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"QualificationRate": 100,
"TopupRate": 100,
"Hidden": true
}
],
"PromoCodePolicyEnabled": true,
"MaximumRecurringReward": 100,
"Description": "Example description",
"Revision": 1,
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishNewTermsVersion": true
}200OKReferralProgramResponse
{
"Exists": true,
"Id": "00000000-0000-4000-8000-000000000123",
"Provider": "string",
"Status": "PENDING",
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"EarningWindowStart": "string",
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"ReservedExposure": 100,
"TermsVersion": 1,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishedAt": "2026-08-05T09:30:00Z",
"Levels": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
}
],
"UpdatedAt": "2026-08-05T09:30:00Z",
"Name": "Public referral program",
"Visibility": "PUBLIC",
"Description": "Example description",
"Revision": 1,
"OfferVersionId": "00000000-0000-4000-8000-000000000123",
"MarginPolicy": {
"Direct": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
},
"Team": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
}
},
"MaximumRecurringReward": 100,
"PromoCodePolicyEnabled": false
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/program?programId=00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123200OKReferralProgramResponse
{
"Exists": true,
"Id": "00000000-0000-4000-8000-000000000123",
"Provider": "string",
"Status": "PENDING",
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"EarningWindowStart": "string",
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"ReservedExposure": 100,
"TermsVersion": 1,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishedAt": "2026-08-05T09:30:00Z",
"Levels": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
}
],
"UpdatedAt": "2026-08-05T09:30:00Z",
"Name": "Public referral program",
"Visibility": "PUBLIC",
"Description": "Example description",
"Revision": 1,
"OfferVersionId": "00000000-0000-4000-8000-000000000123",
"MarginPolicy": {
"Direct": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
},
"Team": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
}
},
"MaximumRecurringReward": 100,
"PromoCodePolicyEnabled": false
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/referrals/programOpen request and response documentationRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/referrals/program?programId=00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"EarningWindowStart": "string",
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"Levels": [
{
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"QualificationCalculationType": "string",
"TopupCalculationType": "string",
"VolumeCapMode": "100.00",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "string",
"RecurringRewardCapAmount": 100,
"Id": "00000000-0000-4000-8000-000000000123",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"QualificationRate": 100,
"TopupRate": 100,
"Hidden": true
}
],
"PromoCodePolicyEnabled": true,
"MaximumRecurringReward": 100,
"Description": "Example description",
"Revision": 1,
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishNewTermsVersion": true
}'Parameters
programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123Request fields and validation
PromoCodePolicyEnabled · boolean or null · optionalNull preserves the setting for older admin clients.
MaximumRecurringReward · number or null · optionalMinimum: 0
Maximum: 999999999999
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Name · string · requiredMaximum length: 80
Description · string or null · optionalShown to members on the offer panel instead of the generated explanation when set.
Maximum length: 2000
Visibility · string · requiredRevision · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
Status · string · requiredLevelBasis · string or null · optionalDeprecated and optional. SUCCESSFUL_REFERRAL_COUNT or REFERRED_TOPUP_VOLUME; stored as is, decides nothing.
LevelLookbackMonths · integer · optionalMinimum: 0
Maximum: 1200
Pattern: ^-?(?:0|[1-9]\d*)$
EarningWindowDays · integer · optionalMinimum: 0
Maximum: 36500
Pattern: ^-?(?:0|[1-9]\d*)$
EarningWindowStart · string · requiredQualifyRequiresKyc · boolean · optionalQualifyRequiresPaidCard · boolean · optionalQualifyRequiresTopup · boolean · optionalQualifyMinimumTopup · number or null · optionalNull means the platform card top-up minimum applies.
Minimum: 0
Maximum: 9999999999
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
WelcomeAmount · number · optionalMinimum: 0
Maximum: 9999999999
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
WelcomeCurrency · string · requiredDeliveryMode · string · requiredPayoutCurrency · string · requiredVoucherClaimDays · integer · optionalMinimum: 1
Maximum: 365
Pattern: ^-?(?:0|[1-9]\d*)$
MinimumCreditAmount · number · optionalMinimum: 0
Maximum: 9999999999
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
MaxEligibleVolumePerRelationship · number or null · optionalMinimum: 0
Maximum: 9999999999
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
ExposureLimit · number or null · optionalMinimum: 0
Maximum: 9999999999
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
TermsText · string or null · optionalMaximum length: 20000
PrivacyNotice · string or null · optionalMaximum length: 5000
PublishNewTermsVersion · boolean · optionalWhen true the terms version is bumped even if rates did not change.
Levels · array · requiredExample request body · replace placeholders
{
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"EarningWindowStart": "string",
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"Levels": [
{
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"QualificationCalculationType": "string",
"TopupCalculationType": "string",
"VolumeCapMode": "100.00",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "string",
"RecurringRewardCapAmount": 100,
"Id": "00000000-0000-4000-8000-000000000123",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"QualificationRate": 100,
"TopupRate": 100,
"Hidden": true
}
],
"PromoCodePolicyEnabled": true,
"MaximumRecurringReward": 100,
"Description": "Example description",
"Revision": 1,
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishNewTermsVersion": true
}200OKReferralProgramResponse
{
"Exists": true,
"Id": "00000000-0000-4000-8000-000000000123",
"Provider": "string",
"Status": "PENDING",
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"EarningWindowStart": "string",
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"ReservedExposure": 100,
"TermsVersion": 1,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishedAt": "2026-08-05T09:30:00Z",
"Levels": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
}
],
"UpdatedAt": "2026-08-05T09:30:00Z",
"Name": "Public referral program",
"Visibility": "PUBLIC",
"Description": "Example description",
"Revision": 1,
"OfferVersionId": "00000000-0000-4000-8000-000000000123",
"MarginPolicy": {
"Direct": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
},
"Team": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
}
},
"MaximumRecurringReward": 100,
"PromoCodePolicyEnabled": false
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/overviewOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/overview?programId=00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123200OKReferralAdminOverviewResponse
{
"Program": {
"Exists": true,
"Id": "00000000-0000-4000-8000-000000000123",
"Provider": "string",
"Status": "PENDING",
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"EarningWindowStart": "string",
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"ReservedExposure": 100,
"TermsVersion": 1,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishedAt": "2026-08-05T09:30:00Z",
"Levels": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
}
],
"UpdatedAt": "2026-08-05T09:30:00Z",
"Name": "Public referral program",
"Visibility": "PUBLIC",
"Description": "Example description",
"Revision": 1,
"OfferVersionId": "00000000-0000-4000-8000-000000000123",
"MarginPolicy": {
"Direct": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
},
"Team": {
"CompanyBps": {},
"AffiliateBps": {},
"SubpartnerBps": {},
"CustomerBps": {},
"BudgetBps": {}
}
},
"MaximumRecurringReward": 100,
"PromoCodePolicyEnabled": false
},
"TotalRelationships": 1,
"QualifiedReferrals": 1,
"QualifyingTopupVolume": 100,
"PendingLiability": 100,
"PaidRewards": 100,
"WelcomePaid": 100,
"ReservedExposure": 100,
"ExposureLimit": 100,
"CreditsPaid": 123,
"FailedCredits": 1,
"ExcludedEvents": 1,
"Currency": "USD",
"TopupRewardLimits": {
"MaxFixedAmount": 100,
"MaxPercentOfTopup": 100,
"MaxPercentOfWlFee": 100,
"MinimumGrossTopupAmount": 100,
"CapSources": [
{
"Calculation": "string",
"Maximum": 100,
"ScheduleKind": "string",
"TierId": 123,
"TierName": "string",
"FeeRate": 100,
"CostRate": 100,
"Formula": "string",
"Availability": "string"
}
]
},
"UnboundedCommitmentCount": 0,
"ExposureAccountingDescription": "Reserved exposure includes bounded accepted commitments and known accrued liabilities. Offers without a determinable recurring ceiling may accrue further rewards. The exposure limit controls new admissions and does not reduce accepted rewards."
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/invite-benefitsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/invite-benefits?programId=00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123200OKapplication/json
[
{
"OwnerUserId": 123,
"OwnerName": "string",
"OwnerEmail": "user@example.com",
"ReferralCode": "string",
"ReferredTierId": 123,
"ReferredTierName": "string",
"DiscountCodeId": 123,
"DiscountCode": "string",
"DiscountDescription": "Example description",
"InheritBenefits": true,
"UpdatedAt": "2026-08-05T09:30:00Z"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/referrals/invite-benefitsOpen request and response documentationRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/referrals/invite-benefits?programId=00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"OwnerUserId": 123,
"ReferredTierId": 123,
"DiscountCodeId": 123,
"InheritBenefits": true
}'Parameters
programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123Request fields and validation
OwnerUserId · integer · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
ReferredTierId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
DiscountCodeId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
InheritBenefits · boolean · optionalExample request body · replace placeholders
{
"OwnerUserId": 123,
"ReferredTierId": 123,
"DiscountCodeId": 123,
"InheritBenefits": true
}200OKReferralInviteBenefitResponse
{
"OwnerUserId": 123,
"OwnerName": "string",
"OwnerEmail": "user@example.com",
"ReferralCode": "string",
"ReferredTierId": 123,
"ReferredTierName": "string",
"DiscountCodeId": 123,
"DiscountCode": "string",
"DiscountDescription": "Example description",
"InheritBenefits": true,
"UpdatedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programs/{programId}/membersOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/members' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKapplication/json
[
{
"UserId": 123,
"Name": "string",
"Email": "user@example.com",
"Status": "PENDING",
"AssignedAt": "2026-08-05T09:30:00Z",
"ExpiresAt": "2026-08-05T09:30:00Z",
"AgreementReference": "external_reference_123",
"EffectiveFrom": "2026-08-05T09:30:00Z",
"EffectiveUntil": "2026-08-05T09:30:00Z",
"CampaignOwnerUserId": 123,
"Channels": [
"string"
],
"FundingAllocation": 100,
"Notes": "string",
"ApprovedByUserId": 123,
"ApprovedAt": "2026-08-05T09:30:00Z"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/referrals/programs/{programId}/members/{userId}Open request and response documentationRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/members/123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Active": true,
"ExpiresAt": "2026-08-05T09:30:00Z",
"AgreementReference": "external_reference_123",
"EffectiveFrom": "2026-08-05T09:30:00Z",
"EffectiveUntil": "2026-08-05T09:30:00Z",
"CampaignOwnerUserId": 123,
"Channels": [
"string"
],
"FundingAllocation": 100,
"Notes": "string",
"Approve": true
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123userIdpathintegerrequiredExample: 123Request fields and validation
Active · boolean · optionalFalse revokes. True creates as PENDING (or keeps the current status); set Approve to activate.
ExpiresAt · string or null · optionalAgreementReference · string or null · optionalMaximum length: 200
EffectiveFrom · string or null · optionalEffectiveUntil · string or null · optionalCampaignOwnerUserId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
Channels · array or null · optionalFundingAllocation · number or null · optionalMinimum: 0
Maximum: 9999999999
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Notes · string or null · optionalMaximum length: 2000
Approve · boolean · optionalApproves the partner: status becomes ACTIVE and approved_by/approved_at are recorded.
Example request body · replace placeholders
{
"Active": true,
"ExpiresAt": "2026-08-05T09:30:00Z",
"AgreementReference": "external_reference_123",
"EffectiveFrom": "2026-08-05T09:30:00Z",
"EffectiveUntil": "2026-08-05T09:30:00Z",
"CampaignOwnerUserId": 123,
"Channels": [
"string"
],
"FundingAllocation": 100,
"Notes": "string",
"Approve": true
}204No ContentNo response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programs/{programId}/members/{userId}/reportWhat one partner produced: counts, volume, rewards and pseudonymised friends.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/members/123/report' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123userIdpathintegerrequiredExample: 123200OKReferralPartnerReportResponse
{
"UserId": 123,
"Name": "string",
"Attributed": 1,
"Qualified": 1,
"Earning": 1,
"EligibleVolume": 100,
"RewardsPending": 100,
"RewardsPaid": 100,
"Currency": "USD",
"Friends": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"Alias": "string",
"Stage": "string",
"AttributedAt": "2026-08-05T09:30:00Z",
"KycCompletedAt": "2026-08-05T09:30:00Z",
"FirstCardAt": "2026-08-05T09:30:00Z",
"FirstTopupAt": "2026-08-05T09:30:00Z",
"QualifiedAt": "2026-08-05T09:30:00Z",
"EarningUntil": "2026-08-05T09:30:00Z",
"EarnedAmount": 100,
"Currency": "USD",
"RecipientName": "string"
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programs/{programId}/level-assignmentsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/level-assignments' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKapplication/json
[
{
"UserId": 123,
"Name": "string",
"Email": "user@example.com",
"LevelId": "00000000-0000-4000-8000-000000000123",
"LevelCode": "string",
"LevelName": "string",
"AssignedAt": "2026-08-05T09:30:00Z",
"ExpiresAt": "2026-08-05T09:30:00Z",
"RevokedAt": "2026-08-05T09:30:00Z",
"Notes": "string"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/referrals/programs/{programId}/level-assignments/{userId}Assigns (or revokes) a program level directly to a user, e.g. a hidden influencer rate.Request & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/level-assignments/123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"LevelId": "00000000-0000-4000-8000-000000000123",
"ExpiresAt": "2026-08-05T09:30:00Z",
"Notes": "string",
"Active": true
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123userIdpathintegerrequiredExample: 123Request fields and validation
LevelId · string · requiredExpiresAt · string or null · optionalNotes · string or null · optionalMaximum length: 2000
Active · boolean · optionalFalse revokes the assignment; the user falls back to the metric-based level.
Example request body · replace placeholders
{
"LevelId": "00000000-0000-4000-8000-000000000123",
"ExpiresAt": "2026-08-05T09:30:00Z",
"Notes": "string",
"Active": true
}200OKReferralLevelAssignmentResponse
{
"UserId": 123,
"Name": "string",
"Email": "user@example.com",
"LevelId": "00000000-0000-4000-8000-000000000123",
"LevelCode": "string",
"LevelName": "string",
"AssignedAt": "2026-08-05T09:30:00Z",
"ExpiresAt": "2026-08-05T09:30:00Z",
"RevokedAt": "2026-08-05T09:30:00Z",
"Notes": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/rewardsReward ledger across the company's programs.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/rewards?programId=00000000-0000-4000-8000-000000000123&status=PENDING&beneficiaryRole=example&eventType=example&page=1&pageSize=50' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123statusquerystringoptionalExample: PENDINGbeneficiaryRolequerystringoptionalExample: exampleeventTypequerystringoptionalExample: examplepagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 50200OKapplication/json
[
{
"Reward": {
"Id": "00000000-0000-4000-8000-000000000123",
"EventType": "string",
"BeneficiaryRole": "string",
"LevelCode": "string",
"BasisAmount": 100,
"BasisCurrency": "USD",
"Amount": 100,
"Currency": "USD",
"DeliveryMode": "string",
"Status": "PENDING",
"Stage": "string",
"CreditId": "00000000-0000-4000-8000-000000000123",
"VoucherId": "00000000-0000-4000-8000-000000000123",
"FriendAlias": "string",
"OccurredAt": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"PaidAt": "2026-08-05T09:30:00Z",
"Explanation": {
"Basis": "string",
"Rate": 100,
"OfferVersionId": "00000000-0000-4000-8000-000000000123",
"TermsVersion": 1,
"EligibleAmount": 100,
"VolumeCap": 100,
"Rounding": "string",
"DeliveryExplanation": "string"
},
"Balance": {
"CashPaid": 100,
"OffsetSettled": 100,
"ReservedCash": 100,
"RemainingPayable": 100,
"LegacyCashUnknown": true
},
"Holds": [
{
"Reason": "string",
"ReleaseAt": "2026-08-05T09:30:00Z"
}
]
},
"BeneficiaryUserId": 123,
"BeneficiaryEmail": "user@example.com",
"SubjectUserId": 123,
"SubjectEmail": "user@example.com"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/metricsWeekly funnel metrics, credit success rate and contribution.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/metrics?programId=00000000-0000-4000-8000-000000000123&from=2026-08-05T09%3A30%3A00Z&to=2026-08-05T09%3A30%3A00Z' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123fromquerystringoptionalExample: 2026-08-05T09:30:00ZtoquerystringoptionalExample: 2026-08-05T09:30:00Z200OKReferralMetricsResponse
{
"Weeks": [
{
"WeekStart": "2026-08-05T09:30:00Z",
"Attributed": 1,
"Qualified": 1,
"FirstPurchaseWithin30Days": 1,
"RepeatUseWithin30Days": 1
}
],
"CreditsAttempted": 1,
"CreditsPaid": 123,
"CreditSuccessRate": 100,
"FeesCollected": 100,
"ProviderCost": 100,
"RewardCost": 100,
"Contribution": 100,
"Currency": "USD"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/analyticsBusiness-intelligence view: funnel, leaderboard, cost, weekly series, program stats, exclusions and contribution (defaults: all programs, last 90 days, top 10).Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/analytics?programId=00000000-0000-4000-8000-000000000123&from=2026-08-05T09%3A30%3A00Z&to=2026-08-05T09%3A30%3A00Z&top=10' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123fromquerystringoptionalExample: 2026-08-05T09:30:00ZtoquerystringoptionalExample: 2026-08-05T09:30:00ZtopqueryintegeroptionalExample: 10200OKReferralAnalyticsResponse
{
"From": "2026-08-05T09:30:00Z",
"To": "2026-08-05T09:30:00Z",
"Currency": "USD",
"Funnel": {
"Invited": 1,
"KycCompleted": 1,
"CardIssued": 1,
"Qualified": 1,
"Earning": 1,
"WindowEnded": 1,
"KycRate": 100,
"CardRate": 100,
"QualificationRate": 100,
"MedianHoursToQualify": 100,
"AverageHoursToQualify": 100
},
"Leaderboard": [
{
"UserId": 123,
"Name": "string",
"Email": "user@example.com",
"LevelCode": "string",
"Partner": true,
"Attributed": 1,
"Qualified": 1,
"EligibleVolume": 100,
"RewardsAccrued": 100,
"RewardsPaid": 100
}
],
"Cost": {
"Welcome": 100,
"Qualification": 100,
"Topup": 100,
"Adjustments": 100,
"Accrued": 100,
"Paid": 100,
"Outstanding": 100,
"Currency": "USD"
},
"Weekly": [
{
"WeekStart": "2026-08-05T09:30:00Z",
"Attributed": 1,
"Qualified": 1,
"TopupVolume": 100,
"RewardsAccrued": 100,
"RewardsPaid": 100,
"CreditsPaid": 123
}
],
"Programs": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"Relationships": 1,
"Qualified": 1,
"RewardsOutstanding": 100,
"RewardsPaid": 100,
"ReservedExposure": 100,
"ExposureLimit": 100
}
],
"Exclusions": [
{
"Reason": "string",
"Count": 1,
"Amount": 100
}
],
"FeesCollected": 100,
"ProviderCost": 100,
"Contribution": 100,
"AverageTopupPerQualifiedFriend": 100,
"AverageRewardPerQualifiedFriend": 100
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/linksCampaign links across the company's members (owner fields filled). status filters on the reported status.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/links?programId=00000000-0000-4000-8000-000000000123&ownerUserId=123&status=PENDING' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123ownerUserIdqueryintegeroptionalExample: 123statusquerystringoptionalExample: PENDING200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"ProgramName": "string",
"Name": "string",
"Code": "string",
"Channel": "string",
"Locale": "string",
"Destination": "string",
"Status": "PENDING",
"ActiveFrom": "2026-08-05T09:30:00Z",
"ExpiresAt": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"ShareUrl": "https://example.com/callback",
"SignupCount": 1,
"QualifiedCount": 1,
"ClickCount": 1,
"UniqueClickCount": 1,
"OfferVersionId": "00000000-0000-4000-8000-000000000123",
"SuggestedCaption": "string",
"OwnerUserId": 123,
"OwnerName": "string",
"OwnerEmail": "user@example.com"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PATCH/api/v2/referrals/links/{linkId}Status only: ACTIVE, PAUSED or ARCHIVED. Pausing stops new attribution and leaves existing relationships untouched.Request & responses +
curl --request PATCH 'https://staging.hoppa.global/api/v2/referrals/links/00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Status": "PENDING"
}'Parameters
linkIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
Status · string · requiredMaximum length: 16
Example request body · replace placeholders
{
"Status": "PENDING"
}200OKReferralCampaignLinkResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"ProgramName": "string",
"Name": "string",
"Code": "string",
"Channel": "string",
"Locale": "string",
"Destination": "string",
"Status": "PENDING",
"ActiveFrom": "2026-08-05T09:30:00Z",
"ExpiresAt": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"ShareUrl": "https://example.com/callback",
"SignupCount": 1,
"QualifiedCount": 1,
"ClickCount": 1,
"UniqueClickCount": 1,
"OfferVersionId": "00000000-0000-4000-8000-000000000123",
"SuggestedCaption": "string",
"OwnerUserId": 123,
"OwnerName": "string",
"OwnerEmail": "user@example.com"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/links/{linkId}/performanceClicks, sign-ups, qualified and earning friends and the owner's rewards of any member's link. range = 7d | 30d | 90d | month | all (default 30d).Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/links/00000000-0000-4000-8000-000000000123/performance?range=example' \
-H 'x-api-key: YOUR_API_KEY'Parameters
linkIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123rangequerystringoptionalExample: example200OKReferralCampaignLinkPerformanceResponse
{
"Clicks": 1,
"UniqueClicks": 1,
"ClickToSignupRate": 100,
"Signups": 1,
"Verified": 1,
"Qualified": 1,
"Earning": 1,
"RewardsAccrued": 100,
"RewardsPaid": 100,
"Currency": "USD"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/links/{code}/clicksA visitor opened the sign-up page with a campaign code. Counted once per visitor per UTC day when VisitorId is sent (every call counts, none as unique, without it). 200 with the link's destination when counted; 204 for crawlers and previews (UserAgentHint) and for paused, expired or archived links; 404 for an unknown code. IPs are never stored.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/links/example/clicks' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"VisitorId": "string",
"Locale": "string",
"UserAgentHint": "string"
}'Parameters
codepathstringrequiredExample: exampleExample request body · replace placeholders
{
"VisitorId": "string",
"Locale": "string",
"UserAgentHint": "string"
}200OKReferralCampaignClickResponse
{
"LinkId": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Destination": "string",
"Unique": true
}204No ContentNo response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/optionsEligible offer choices and up to 50 company users matching a search.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/options?search=example' \
-H 'x-api-key: YOUR_API_KEY'Parameters
searchquerystringoptionalExample: example200OKReferralAdminOptionsResponse
{
"Users": [
{
"Id": 123,
"Name": "string",
"Email": "user@example.com"
}
],
"HasMoreUsers": true,
"Tiers": [
{
"Id": 123,
"Name": "string"
}
],
"DiscountCodes": [
{
"Id": 123,
"Code": "string",
"Description": "Example description",
"CompanyId": 123,
"DiscountType": "string",
"BuyDiscountPercent": 100,
"MonthlyDiscountPercent": 100,
"YearlyDiscountPercent": 100,
"BuyDiscountFixed": 100,
"MonthlyDiscountFixed": 100,
"YearlyDiscountFixed": 100,
"CardDiscountDurationMonths": 1,
"TierDiscountDurationMonths": 1,
"TierMonthlyDiscountPercent": 100,
"TierYearlyDiscountPercent": 100,
"TierMonthlyDiscountFixed": 100,
"TierYearlyDiscountFixed": 100,
"MaxUsesTotal": 1,
"MaxUsesPerUser": 1,
"CurrentUses": 1,
"ValidFrom": "2026-08-05T09:30:00Z",
"ValidTill": "2026-08-05T09:30:00Z",
"ApplicableUserIds": [
1
],
"IsActive": true,
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CreatedBy": 1
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/alert-settingsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/alert-settings' \
-H 'x-api-key: YOUR_API_KEY'200OKReferralAlertSettingsResponse
{
"Settings": {
"Enabled": true,
"EmailRecipients": [
"user@example.com"
],
"SlackWebhookSecretReference": "external_reference_123",
"ExposureThresholdPercent": 100,
"ExposureRecoveryPercent": 100,
"StaleCreditMinutes": 1,
"SampleWindowMinutes": 1,
"MinimumSampleSize": 1,
"CreditFailureThresholdPercent": 100,
"ExcludedEventThresholdPercent": 100,
"CooldownMinutes": 1
},
"SlackWebhookConfigured": true,
"UpdatedAt": "2026-08-05T09:30:00Z",
"UpdatedByUserId": 123,
"WorkerEnabled": false
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/referrals/alert-settingsOpen request and response documentationRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/referrals/alert-settings' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Enabled": true,
"EmailRecipients": [
"user@example.com"
],
"SlackWebhookSecretReference": "external_reference_123",
"ExposureThresholdPercent": 100,
"ExposureRecoveryPercent": 100,
"StaleCreditMinutes": 1,
"SampleWindowMinutes": 1,
"MinimumSampleSize": 1,
"CreditFailureThresholdPercent": 100,
"ExcludedEventThresholdPercent": 100,
"CooldownMinutes": 1
}'Request fields and validation
Enabled · boolean · optionalEmailRecipients · array · optionalSlackWebhookSecretReference · string or null · optionalDeployment-managed alias, never a webhook URL or token. Null removes Slack delivery.
ExposureThresholdPercent · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
ExposureRecoveryPercent · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
StaleCreditMinutes · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
SampleWindowMinutes · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
MinimumSampleSize · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
CreditFailureThresholdPercent · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
ExcludedEventThresholdPercent · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
CooldownMinutes · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"Enabled": true,
"EmailRecipients": [
"user@example.com"
],
"SlackWebhookSecretReference": "external_reference_123",
"ExposureThresholdPercent": 100,
"ExposureRecoveryPercent": 100,
"StaleCreditMinutes": 1,
"SampleWindowMinutes": 1,
"MinimumSampleSize": 1,
"CreditFailureThresholdPercent": 100,
"ExcludedEventThresholdPercent": 100,
"CooldownMinutes": 1
}200OKReferralAlertSettingsResponse
{
"Settings": {
"Enabled": true,
"EmailRecipients": [
"user@example.com"
],
"SlackWebhookSecretReference": "external_reference_123",
"ExposureThresholdPercent": 100,
"ExposureRecoveryPercent": 100,
"StaleCreditMinutes": 1,
"SampleWindowMinutes": 1,
"MinimumSampleSize": 1,
"CreditFailureThresholdPercent": 100,
"ExcludedEventThresholdPercent": 100,
"CooldownMinutes": 1
},
"SlackWebhookConfigured": true,
"UpdatedAt": "2026-08-05T09:30:00Z",
"UpdatedByUserId": 123,
"WorkerEnabled": false
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/alert-incidentsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/alert-incidents?programId=00000000-0000-4000-8000-000000000123&status=PENDING&page=1&pageSize=50' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123statusquerystringoptionalExample: PENDINGpagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 50200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"Currency": "USD",
"Kind": "string",
"Status": "PENDING",
"Severity": "string",
"ObservedValue": 100,
"SampleSize": 1,
"Occurrence": 1,
"OpenedAt": "2026-08-05T09:30:00Z",
"LastObservedAt": "2026-08-05T09:30:00Z",
"ResolvedAt": "2026-08-05T09:30:00Z"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/alert-delivery-healthOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/alert-delivery-health' \
-H 'x-api-key: YOUR_API_KEY'200OKReferralAlertDeliveryHealthResponse
{
"Pending": 1,
"Delivering": 1,
"Delivered": 1,
"DeadLetter": 1,
"OldestPendingAt": "2026-08-05T09:30:00Z",
"RecentFailures": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"IncidentId": "00000000-0000-4000-8000-000000000123",
"Channel": "string",
"Status": "PENDING",
"Attempts": 1,
"LastErrorCode": "string",
"NextAttemptAt": "2026-08-05T09:30:00Z"
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programs/{programId}/attribution-readinessOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/attribution-readiness' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKReferralAttributionReadinessResponse
{
"Ready": true,
"Reason": "string",
"Remedy": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/auditOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/audit?programId=00000000-0000-4000-8000-000000000123&actorId=123&action=example&from=2026-08-05T09%3A30%3A00Z&to=2026-08-05T09%3A30%3A00Z&beforeId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123actorIdquerystringoptionalExample: 123actionquerystringoptionalExample: examplefromquerystringoptionalExample: 2026-08-05T09:30:00ZtoquerystringoptionalExample: 2026-08-05T09:30:00ZbeforeIdqueryintegeroptionalExample: 123pageSizequeryintegeroptionalExample: 50200OKReferralAuditPage
{
"Items": [
{
"Id": 123,
"ProgramId": "00000000-0000-4000-8000-000000000123",
"ActorType": "string",
"ActorId": "string",
"ExecutorId": "string",
"OriginalActorId": "string",
"Action": "string",
"TargetType": "string",
"TargetId": "string",
"Changes": {},
"Reason": "string",
"CorrelationId": "string",
"RecordedAt": "2026-08-05T09:30:00Z"
}
],
"NextBeforeId": 123
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/programs/{programId}/bulk/previewOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/bulk/preview' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Csv": "string",
"ExpectedProgramRevision": 1
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
Csv · string · requiredMaximum length: 262144
ExpectedProgramRevision · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"Csv": "string",
"ExpectedProgramRevision": 1
}200OKReferralBulkResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"ProgramRevision": 1,
"PayloadHash": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"Status": "PENDING",
"ExecutedAt": "2026-08-05T09:30:00Z",
"Rows": [
{
"Row": 1,
"Action": "string",
"UserId": 123,
"Status": "PENDING",
"ErrorCode": "string",
"Message": "string"
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/programs/{programId}/bulk/{jobId}/executeOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/bulk/00000000-0000-4000-8000-000000000123/execute' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"PayloadHash": "string",
"IdempotencyKey": "operation-customer-1042-001",
"SelectedRows": [
1
]
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123jobIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
PayloadHash · string · requiredMaximum length: 64
IdempotencyKey · string · requiredMaximum length: 100
SelectedRows · array or null · optionalOmit for all-or-nothing. Explicit row numbers opt in to executing only these valid rows atomically.
Example request body · replace placeholders
{
"PayloadHash": "string",
"IdempotencyKey": "operation-customer-1042-001",
"SelectedRows": [
1
]
}200OKReferralBulkResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"ProgramRevision": 1,
"PayloadHash": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"Status": "PENDING",
"ExecutedAt": "2026-08-05T09:30:00Z",
"Rows": [
{
"Row": 1,
"Action": "string",
"UserId": 123,
"Status": "PENDING",
"ErrorCode": "string",
"Message": "string"
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programs/{programId}/bulk/{jobId}Open request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/bulk/00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123jobIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKReferralBulkResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"ProgramRevision": 1,
"PayloadHash": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"Status": "PENDING",
"ExecutedAt": "2026-08-05T09:30:00Z",
"Rows": [
{
"Row": 1,
"Action": "string",
"UserId": 123,
"Status": "PENDING",
"ErrorCode": "string",
"Message": "string"
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programs/{programId}/bulk/{jobId}/errors.csvOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/bulk/00000000-0000-4000-8000-000000000123/errors.csv' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123jobIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKtext/csv
stringExamples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programs/{programId}/community/policyOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/community/policy' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKReferralCommunityPolicyResponse
{
"Enabled": true,
"Revision": 1,
"BudgetBps": 1,
"CommunityL2Bps": 1,
"CommunityL3Bps": 1,
"LeaderL2Bps": 1,
"LeaderL3Bps": 1,
"DirectRewardBps": 0,
"AvailableCommunityBps": 0,
"HasTopupMargin": false
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/referrals/programs/{programId}/community/policyOpen request and response documentationRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/community/policy' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Enabled": true,
"Revision": 1,
"CommunityL2Bps": 1000,
"CommunityL3Bps": 500,
"LeaderL2Bps": 1500,
"LeaderL3Bps": 500
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
Enabled · boolean · requiredRevision · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
CommunityL2Bps · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
CommunityL3Bps · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
LeaderL2Bps · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
LeaderL3Bps · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"Enabled": true,
"Revision": 1,
"CommunityL2Bps": 1000,
"CommunityL3Bps": 500,
"LeaderL2Bps": 1500,
"LeaderL3Bps": 500
}200OKReferralCommunityPolicyResponse
{
"Enabled": true,
"Revision": 1,
"BudgetBps": 1,
"CommunityL2Bps": 1,
"CommunityL3Bps": 1,
"LeaderL2Bps": 1,
"LeaderL3Bps": 1,
"DirectRewardBps": 0,
"AvailableCommunityBps": 0,
"HasTopupMargin": false
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programs/{programId}/community/membersOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/community/members' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"UserId": 123,
"Plan": "string",
"ParentUserId": 123,
"PlanRevision": 1,
"L2Bps": 1,
"L3Bps": 1,
"EnabledAt": "2026-08-05T09:30:00Z",
"ExpiresAt": "2026-08-05T09:30:00Z",
"RevokedAt": "2026-08-05T09:30:00Z",
"Status": "PENDING",
"AgreementReference": "external_reference_123",
"Notes": "string"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/programs/{programId}/community/members/{userId}/enableOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/community/members/123/enable' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Plan": "string",
"ParentUserId": 123,
"ExpiresAt": "2026-08-05T09:30:00Z",
"AgreementReference": "external_reference_123",
"Notes": "string"
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123userIdpathintegerrequiredExample: 123Request fields and validation
Plan · string · requiredParentUserId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
ExpiresAt · string or null · optionalAgreementReference · string or null · optionalNotes · string or null · optionalExample request body · replace placeholders
{
"Plan": "string",
"ParentUserId": 123,
"ExpiresAt": "2026-08-05T09:30:00Z",
"AgreementReference": "external_reference_123",
"Notes": "string"
}200OKReferralCommunityMembershipResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"UserId": 123,
"Plan": "string",
"ParentUserId": 123,
"PlanRevision": 1,
"L2Bps": 1,
"L3Bps": 1,
"EnabledAt": "2026-08-05T09:30:00Z",
"ExpiresAt": "2026-08-05T09:30:00Z",
"RevokedAt": "2026-08-05T09:30:00Z",
"Status": "PENDING",
"AgreementReference": "external_reference_123",
"Notes": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/programs/{programId}/community/members/{userId}/revokeOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/community/members/123/revoke' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Reason": "string"
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123userIdpathintegerrequiredExample: 123Request fields and validation
Reason · string · requiredExample request body · replace placeholders
{
"Reason": "string"
}200OKReferralCommunityMembershipResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"UserId": 123,
"Plan": "string",
"ParentUserId": 123,
"PlanRevision": 1,
"L2Bps": 1,
"L3Bps": 1,
"EnabledAt": "2026-08-05T09:30:00Z",
"ExpiresAt": "2026-08-05T09:30:00Z",
"RevokedAt": "2026-08-05T09:30:00Z",
"Status": "PENDING",
"AgreementReference": "external_reference_123",
"Notes": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/relationshipsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/relationships?ProgramId=00000000-0000-4000-8000-000000000123&Search=example&Stage=example&Source=example&InviterUserId=123&FriendUserId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
ProgramIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123SearchquerystringoptionalExample: exampleStagequerystringoptionalExample: exampleSourcequerystringoptionalExample: exampleInviterUserIdqueryintegeroptionalExample: 123FriendUserIdqueryintegeroptionalExample: 123AfterIdqueryintegeroptionalExample: 123PageSizequeryintegeroptionalExample: 1200OKReferralRelationshipsPage
{
"Items": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"Cursor": 1,
"ProgramId": "00000000-0000-4000-8000-000000000123",
"ProgramName": "string",
"Inviter": {
"Id": 123,
"Name": "string",
"Email": "user@example.com"
},
"Friend": {
"Id": 123,
"Name": "string",
"Email": "user@example.com"
},
"Status": "PENDING",
"Stage": "string",
"AttributionSource": "string",
"AttributedAt": "2026-08-05T09:30:00Z",
"QualifiedAt": "2026-08-05T09:30:00Z",
"EarningWindowEndsAt": "2026-08-05T09:30:00Z",
"MissingConditions": [
"string"
],
"ProtectedOffer": true,
"OfferVersionId": "00000000-0000-4000-8000-000000000123"
}
],
"NextCursor": 1
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/relationships/{relationshipId}Open request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/relationships/00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
relationshipIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKReferralRelationshipDetail
{
"Relationship": {
"Id": "00000000-0000-4000-8000-000000000123",
"Cursor": 1,
"ProgramId": "00000000-0000-4000-8000-000000000123",
"ProgramName": "string",
"Inviter": {
"Id": 123,
"Name": "string",
"Email": "user@example.com"
},
"Friend": {
"Id": 123,
"Name": "string",
"Email": "user@example.com"
},
"Status": "PENDING",
"Stage": "string",
"AttributionSource": "string",
"AttributedAt": "2026-08-05T09:30:00Z",
"QualifiedAt": "2026-08-05T09:30:00Z",
"EarningWindowEndsAt": "2026-08-05T09:30:00Z",
"MissingConditions": [
"string"
],
"ProtectedOffer": true,
"OfferVersionId": "00000000-0000-4000-8000-000000000123"
},
"Conditions": [
{
"Code": "string",
"Label": "string",
"Required": true,
"Met": true,
"MetAt": "2026-08-05T09:30:00Z",
"Evidence": "string"
}
],
"Events": [
{
"EventType": "string",
"SourceEventKey": "string",
"OccurredAt": "2026-08-05T09:30:00Z",
"Amount": 100,
"Currency": "USD",
"FundingSource": "string",
"Status": "PENDING",
"ExcludedReason": "string"
}
],
"TermsVersionAccepted": 1,
"AcceptedAt": "2026-08-05T09:30:00Z",
"CampaignLinkId": "00000000-0000-4000-8000-000000000123",
"EligibleVolumeTotal": 100,
"ReservedExposure": 100,
"AsOf": "2026-08-05T09:30:00Z",
"EventsTruncated": false
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/users/{userId}/relationshipsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/users/123/relationships?ProgramId=00000000-0000-4000-8000-000000000123&Search=example&Stage=example&Source=example&InviterUserId=123&FriendUserId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123ProgramIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123SearchquerystringoptionalExample: exampleStagequerystringoptionalExample: exampleSourcequerystringoptionalExample: exampleInviterUserIdqueryintegeroptionalExample: 123FriendUserIdqueryintegeroptionalExample: 123AfterIdqueryintegeroptionalExample: 123PageSizequeryintegeroptionalExample: 1directionquerystringoptionalExample: example200OKReferralRelationshipsPage
{
"Items": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"Cursor": 1,
"ProgramId": "00000000-0000-4000-8000-000000000123",
"ProgramName": "string",
"Inviter": {
"Id": 123,
"Name": "string",
"Email": "user@example.com"
},
"Friend": {
"Id": 123,
"Name": "string",
"Email": "user@example.com"
},
"Status": "PENDING",
"Stage": "string",
"AttributionSource": "string",
"AttributedAt": "2026-08-05T09:30:00Z",
"QualifiedAt": "2026-08-05T09:30:00Z",
"EarningWindowEndsAt": "2026-08-05T09:30:00Z",
"MissingConditions": [
"string"
],
"ProtectedOffer": true,
"OfferVersionId": "00000000-0000-4000-8000-000000000123"
}
],
"NextCursor": 1
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/customers/{userId}/relationshipsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/customers/123/relationships?ProgramId=00000000-0000-4000-8000-000000000123&Search=example&Stage=example&Source=example&InviterUserId=123&FriendUserId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123ProgramIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123SearchquerystringoptionalExample: exampleStagequerystringoptionalExample: exampleSourcequerystringoptionalExample: exampleInviterUserIdqueryintegeroptionalExample: 123FriendUserIdqueryintegeroptionalExample: 123AfterIdqueryintegeroptionalExample: 123PageSizequeryintegeroptionalExample: 1directionquerystringoptionalExample: example200OKReferralRelationshipsPage
{
"Items": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"Cursor": 1,
"ProgramId": "00000000-0000-4000-8000-000000000123",
"ProgramName": "string",
"Inviter": {
"Id": 123,
"Name": "string",
"Email": "user@example.com"
},
"Friend": {
"Id": 123,
"Name": "string",
"Email": "user@example.com"
},
"Status": "PENDING",
"Stage": "string",
"AttributionSource": "string",
"AttributedAt": "2026-08-05T09:30:00Z",
"QualifiedAt": "2026-08-05T09:30:00Z",
"EarningWindowEndsAt": "2026-08-05T09:30:00Z",
"MissingConditions": [
"string"
],
"ProtectedOffer": true,
"OfferVersionId": "00000000-0000-4000-8000-000000000123"
}
],
"NextCursor": 1
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/programs/{programId}/qualification-scenariosOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/qualification-scenarios' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"LevelCode": "string",
"DraftId": "00000000-0000-4000-8000-000000000123",
"DraftRevision": 1,
"Draft": {
"Policy": {
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"EarningWindowStart": "string",
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"Levels": [
{
"Code": {},
"Name": {},
"Icon": {},
"Color": {},
"QualificationCalculationType": {},
"TopupCalculationType": {},
"VolumeCapMode": {},
"VolumeCapAmount": {},
"RecurringRewardCapMode": {},
"RecurringRewardCapAmount": {},
"Id": {},
"DisplayOrder": {},
"MinimumMetricValue": {},
"MinimumQualifiedReferrals": {},
"MinimumTopupVolume": {},
"QualificationRate": {},
"TopupRate": {},
"Hidden": {}
}
],
"PromoCodePolicyEnabled": true,
"MaximumRecurringReward": 100,
"Description": "Example description",
"Revision": 1,
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishNewTermsVersion": true
},
"Margin": {
"Direct": {
"CompanyBps": {},
"AffiliateBps": {},
"SubpartnerBps": {},
"CustomerBps": {},
"BudgetBps": {}
},
"Team": {}
},
"DraftRevision": 1
},
"AttributedAt": "2026-08-05T09:30:00Z",
"AsOf": "2026-08-05T09:30:00Z",
"AlreadyUsedVolume": 100,
"AlreadyRewarded": 100,
"BoostId": "00000000-0000-4000-8000-000000000123",
"AlreadyBoostRewarded": 100,
"AlreadyQualifiedFriends": 1,
"Team": true,
"VerifiedCountry": "GB",
"Events": [
{
"Key": "string",
"Type": "string",
"Currency": "USD",
"PromoCodeUsed": true,
"At": "2026-08-05T09:30:00Z",
"Amount": 100,
"FundingSource": "string",
"SettledFee": 100,
"ProviderCost": 100
}
]
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
DraftId · string or null · optionalDraftRevision · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
Draft · object or null · optionalLevelCode · string · requiredMaximum length: 50
AttributedAt · string · optionalAsOf · string · optionalAlreadyUsedVolume · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
AlreadyRewarded · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
BoostId · string or null · optionalAlreadyBoostRewarded · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
AlreadyQualifiedFriends · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
Team · boolean · optionalVerifiedCountry · string or null · optionalEvents · array · optionalExample request body · replace placeholders
{
"LevelCode": "string",
"DraftId": "00000000-0000-4000-8000-000000000123",
"DraftRevision": 1,
"Draft": {
"Policy": {
"Name": "string",
"Visibility": "string",
"Status": "PENDING",
"EarningWindowStart": "string",
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"Levels": [
{
"Code": {},
"Name": {},
"Icon": {},
"Color": {},
"QualificationCalculationType": {},
"TopupCalculationType": {},
"VolumeCapMode": {},
"VolumeCapAmount": {},
"RecurringRewardCapMode": {},
"RecurringRewardCapAmount": {},
"Id": {},
"DisplayOrder": {},
"MinimumMetricValue": {},
"MinimumQualifiedReferrals": {},
"MinimumTopupVolume": {},
"QualificationRate": {},
"TopupRate": {},
"Hidden": {}
}
],
"PromoCodePolicyEnabled": true,
"MaximumRecurringReward": 100,
"Description": "Example description",
"Revision": 1,
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishNewTermsVersion": true
},
"Margin": {
"Direct": {
"CompanyBps": {},
"AffiliateBps": {},
"SubpartnerBps": {},
"CustomerBps": {},
"BudgetBps": {}
},
"Team": {}
},
"DraftRevision": 1
},
"AttributedAt": "2026-08-05T09:30:00Z",
"AsOf": "2026-08-05T09:30:00Z",
"AlreadyUsedVolume": 100,
"AlreadyRewarded": 100,
"BoostId": "00000000-0000-4000-8000-000000000123",
"AlreadyBoostRewarded": 100,
"AlreadyQualifiedFriends": 1,
"Team": true,
"VerifiedCountry": "GB",
"Events": [
{
"Key": "string",
"Type": "string",
"Currency": "USD",
"PromoCodeUsed": true,
"At": "2026-08-05T09:30:00Z",
"Amount": 100,
"FundingSource": "string",
"SettledFee": 100,
"ProviderCost": 100
}
]
}200OKReferralQualificationScenarioResponse
{
"CalculationVersion": "string",
"DraftId": "00000000-0000-4000-8000-000000000123",
"DraftRevision": 1,
"Qualification": {
"CanQualify": true,
"QualifiedAt": "2026-08-05T09:30:00Z",
"Stage": "string",
"Conditions": [
{
"Code": "string",
"Label": "string",
"Required": true,
"Met": true,
"MetAt": "2026-08-05T09:30:00Z",
"Evidence": "string"
}
],
"MissingConditions": [
"string"
],
"WindowEndsAt": "2026-08-05T09:30:00Z"
},
"Steps": [
{
"EventKey": "string",
"EventType": "string",
"At": "2026-08-05T09:30:00Z",
"Decision": "string",
"Qualification": {
"CanQualify": true,
"QualifiedAt": "2026-08-05T09:30:00Z",
"Stage": "string",
"Conditions": [
{
"Code": {},
"Label": {},
"Required": {},
"Met": {},
"MetAt": {},
"Evidence": {}
}
],
"MissingConditions": [
"string"
],
"WindowEndsAt": "2026-08-05T09:30:00Z"
},
"Calculation": {
"CalculationVersion": "string",
"Currency": "USD",
"Basis": "string",
"EligibleAmount": 100,
"InviterReward": 100,
"CustomerRecurringReward": 100,
"SubpartnerReward": 100,
"CompanyRetained": 100,
"QualificationReward": 100,
"WelcomeReward": 100,
"Status": "PENDING",
"Warnings": [
{}
]
},
"BoostReward": 0
}
],
"EligibleVolumeUsed": 100,
"RecurringRewardUsed": 100,
"Warnings": [
"string"
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programs/{programId}/members/{userId}/level-lifecycleOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/members/123/level-lifecycle' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123userIdpathintegerrequiredExample: 123200OKReferralLevelLifecycleResponse
{
"ProgramId": "00000000-0000-4000-8000-000000000123",
"UserId": 123,
"AsOf": "2026-08-05T09:30:00Z",
"ObservedAt": "2026-08-05T09:30:00Z",
"CurrentLevel": {
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
},
"Assigned": true,
"Progress": {
"Basis": "string",
"CurrentValue": 100,
"NextThreshold": 100,
"Remaining": 100,
"LookbackMonths": 1,
"QualifiedReferrals": 0,
"TopupVolume": 0,
"TopupVolumeCurrency": "USD",
"NextMinimumQualifiedReferrals": 1,
"NextMinimumTopupVolume": 100,
"RemainingQualifiedReferrals": 1,
"RemainingTopupVolume": 100
},
"Forecast": {
"EffectiveAt": "2026-08-05T09:30:00Z",
"DaysUntil": 1,
"Level": {
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
},
"Assigned": true,
"Reason": "string"
},
"ProtectedRelationshipCount": 1,
"ExistingOffersProtected": true,
"ForecastAssumption": "NO_FUTURE_ACTIVITY_OR_POLICY_CHANGES"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programs/{programId}/members/{userId}/level-historyOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/members/123/level-history?page=1&pageSize=25' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123userIdpathintegerrequiredExample: 123pagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 25200OKReferralLevelHistoryResponse
{
"Items": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"UserId": 123,
"Sequence": 1,
"Kind": "string",
"EffectiveAt": "2026-08-05T09:30:00Z",
"ObservedAt": "2026-08-05T09:30:00Z",
"EffectiveTimeBasis": "string",
"PreviousLevel": {
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
},
"CurrentLevel": {
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
},
"Assigned": true,
"DeliveryStatus": "PENDING"
}
],
"Page": 1,
"PageSize": 1,
"HasMore": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/exports/{kind}Open request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/exports/example?ProgramId=00000000-0000-4000-8000-000000000123&Status=PENDING&Currency=USD&BeneficiaryRole=example&EventType=example&UserId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
kindpathstringrequiredExample: exampleProgramIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123StatusquerystringoptionalExample: PENDINGCurrencyquerystringoptionalExample: USDBeneficiaryRolequerystringoptionalExample: exampleEventTypequerystringoptionalExample: exampleUserIdqueryintegeroptionalExample: 123FromquerystringoptionalExample: 2026-08-05T09:30:00ZToquerystringoptionalExample: 2026-08-05T09:30:00Z200OKtext/csv
stringExamples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/accounting/monthlyOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/accounting/monthly?month=example¤cy=USD&programId=00000000-0000-4000-8000-000000000123&asOf=2026-08-05T09%3A30%3A00Z' \
-H 'x-api-key: YOUR_API_KEY'Parameters
monthquerystringoptionalExample: examplecurrencyquerystringoptionalExample: USDprogramIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123asOfquerystringoptionalExample: 2026-08-05T09:30:00Z200OKReferralMonthlyAccountingReport
{
"Month": "string",
"Currency": "USD",
"PeriodStart": "2026-08-05T09:30:00Z",
"PeriodEndExclusive": "2026-08-05T09:30:00Z",
"AsOf": "2026-08-05T09:30:00Z",
"IsComplete": true,
"IsRestated": true,
"OpeningEarnedBalance": 100,
"Accrued": 100,
"EntitlementAdjustments": 100,
"ActualCashPaid": 100,
"Offsets": 100,
"ClosingEarnedBalance": 100,
"OpeningReservedExposure": 100,
"ReservationMovement": 100,
"ClosingReservedExposure": 100,
"UnearnedReservedExposure": 100,
"Programs": [
{
"ProgramId": "00000000-0000-4000-8000-000000000123",
"ProgramName": "string",
"OpeningReconciled": true,
"OpeningAt": "2026-08-05T09:30:00Z",
"OpeningEarnedBalance": 100,
"Accrued": 100,
"EntitlementAdjustments": 100,
"ActualCashPaid": 100,
"Offsets": 100,
"ClosingEarnedBalance": 100,
"OpeningReservedExposure": 100,
"ReservationMovement": 100,
"ClosingReservedExposure": 100,
"UnearnedReservedExposure": 100,
"LateRecordedMovements": 1,
"ClosingEarnedLiability": 100,
"ClosingRecoveryReceivable": 100
}
],
"Warnings": [
"string"
],
"ClosingEarnedLiability": 100,
"ClosingRecoveryReceivable": 100
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/accounting/openingsOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/accounting/openings' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"ProgramId": "00000000-0000-4000-8000-000000000123",
"Currency": "USD",
"OpeningAt": "2026-08-05T09:30:00Z",
"EarnedBalance": 100,
"ReservedExposure": 100,
"Evidence": "string",
"BeneficiaryBalances": {
"FIELD_FROM_APPLICATION": 100
}
}'Request fields and validation
ProgramId · string · optionalCurrency · string · optionalOpeningAt · string · optionalEarnedBalance · number · optionalSigned earned obligation: accrued entitlement less confirmed cash. May include recovery debt.
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
ReservedExposure · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Evidence · string · optionalBeneficiaryBalances · object or null · optionalOptional evidenced signed balance by beneficiary; sum must equal EarnedBalance. Needed to distinguish owed rewards from recovery receivables.
Example request body · replace placeholders
{
"ProgramId": "00000000-0000-4000-8000-000000000123",
"Currency": "USD",
"OpeningAt": "2026-08-05T09:30:00Z",
"EarnedBalance": 100,
"ReservedExposure": 100,
"Evidence": "string",
"BeneficiaryBalances": {
"FIELD_FROM_APPLICATION": 100
}
}204No ContentNo response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/signup-signalsAuthenticated signup services only. Never forward a browser-supplied observed IP.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/signup-signals' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"SourceEventKey": "string",
"ServerObservedIp": "string",
"InstallationToken": "string"
}'Request fields and validation
UserId · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
SourceEventKey · string · requiredServerObservedIp · string or null · requiredInstallationToken · string or null · requiredExample request body · replace placeholders
{
"UserId": 123,
"SourceEventKey": "string",
"ServerObservedIp": "string",
"InstallationToken": "string"
}200OKReferralSignupSignalResponse
{
"Status": "PENDING",
"SignalsRecorded": 1,
"RelationshipFlagged": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/programs/{programId}/risk-policyOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/risk-policy' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKReferralRiskPolicyResponse
{
"ProgramId": "00000000-0000-4000-8000-000000000123",
"Revision": 1,
"PayoutHoldDays": 1,
"DailyAttributionLimit": 1,
"AutomaticClawbackEnabled": true,
"DayBoundary": "string",
"SupportedDeliveryModes": [
"string"
],
"SignalAvailability": [
{
"Signal": "string",
"Status": "PENDING",
"Detail": "string"
}
],
"SignupSignalsEnabled": false
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/referrals/programs/{programId}/risk-policyOpen request and response documentationRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/referrals/programs/00000000-0000-4000-8000-000000000123/risk-policy' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"ExpectedRevision": 1,
"PayoutHoldDays": 1,
"DailyAttributionLimit": 1,
"AutomaticClawbackEnabled": true,
"Reason": "string",
"SignupSignalsEnabled": false
}'Parameters
programIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
ExpectedRevision · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
PayoutHoldDays · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
DailyAttributionLimit · integer or null · requiredPattern: ^-?(?:0|[1-9]\d*)$
AutomaticClawbackEnabled · boolean · requiredReason · string · requiredSignupSignalsEnabled · boolean · optionalExample request body · replace placeholders
{
"ExpectedRevision": 1,
"PayoutHoldDays": 1,
"DailyAttributionLimit": 1,
"AutomaticClawbackEnabled": true,
"Reason": "string",
"SignupSignalsEnabled": false
}200OKReferralRiskPolicyResponse
{
"ProgramId": "00000000-0000-4000-8000-000000000123",
"Revision": 1,
"PayoutHoldDays": 1,
"DailyAttributionLimit": 1,
"AutomaticClawbackEnabled": true,
"DayBoundary": "string",
"SupportedDeliveryModes": [
"string"
],
"SignalAvailability": [
{
"Signal": "string",
"Status": "PENDING",
"Detail": "string"
}
],
"SignupSignalsEnabled": false
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/reviewsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/reviews?programId=00000000-0000-4000-8000-000000000123&status=PENDING&page=1&pageSize=50' \
-H 'x-api-key: YOUR_API_KEY'Parameters
programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123statusquerystringoptionalExample: PENDINGpagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 50200OKReferralRiskReviewPage
{
"Items": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"RelationshipId": "00000000-0000-4000-8000-000000000123",
"InviterUserId": 123,
"FriendUserId": 123,
"Status": "PENDING",
"Revision": 1,
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"Signals": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"Reason": "string",
"Source": "string",
"OccurredAt": "2026-08-05T09:30:00Z",
"AcknowledgedAt": "2026-08-05T09:30:00Z"
}
]
}
],
"Page": 1,
"PageSize": 1,
"Total": 1
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/reviews/{reviewId}Open request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/reviews/00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
reviewIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKReferralRiskReviewResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"RelationshipId": "00000000-0000-4000-8000-000000000123",
"InviterUserId": 123,
"FriendUserId": 123,
"Status": "PENDING",
"Revision": 1,
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"Signals": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"Reason": "string",
"Source": "string",
"OccurredAt": "2026-08-05T09:30:00Z",
"AcknowledgedAt": "2026-08-05T09:30:00Z"
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/reviews/{reviewId}/decisionsOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/reviews/00000000-0000-4000-8000-000000000123/decisions' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Decision": "string",
"Reason": "string",
"ExpectedRevision": 1,
"IdempotencyKey": "operation-customer-1042-001"
}'Parameters
reviewIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
Decision · string · requiredReason · string · requiredExpectedRevision · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
IdempotencyKey · string · requiredExample request body · replace placeholders
{
"Decision": "string",
"Reason": "string",
"ExpectedRevision": 1,
"IdempotencyKey": "operation-customer-1042-001"
}200OKReferralRiskReviewResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"RelationshipId": "00000000-0000-4000-8000-000000000123",
"InviterUserId": 123,
"FriendUserId": 123,
"Status": "PENDING",
"Revision": 1,
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"Signals": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"Reason": "string",
"Source": "string",
"OccurredAt": "2026-08-05T09:30:00Z",
"AcknowledgedAt": "2026-08-05T09:30:00Z"
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/creditsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/credits?status=PENDING&page=1&pageSize=50' \
-H 'x-api-key: YOUR_API_KEY'Parameters
statusquerystringoptionalExample: PENDINGpagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 50200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"UserId": 123,
"UserEmail": "user@example.com",
"Destination": "string",
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"Attempts": 1,
"LastError": "string",
"NextAttemptAt": "2026-08-05T09:30:00Z",
"ProviderReference": "external_reference_123",
"ProviderConfirmedAt": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"RewardIds": [
"00000000-0000-4000-8000-000000000123"
]
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/credits/{creditId}/retryOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/credits/00000000-0000-4000-8000-000000000123/retry' \
-H 'x-api-key: YOUR_API_KEY'Parameters
creditIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123204No ContentNo response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/referrals/credits/{creditId}/cancelOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referrals/credits/00000000-0000-4000-8000-000000000123/cancel' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Reason": "string"
}'Parameters
creditIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Example request body · replace placeholders
{
"Reason": "string"
}204No ContentNo response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/referrals/reconciliationOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referrals/reconciliation' \
-H 'x-api-key: YOUR_API_KEY'200OKReferralReconciliationResponse
{
"GeneratedAt": "2026-08-05T09:30:00Z",
"RewardsReady": 1,
"RewardsCrediting": 1,
"RewardsFailed": 1,
"CreditsPending": 1,
"CreditsTransferring": 1,
"CreditsConfirming": 1,
"CreditsFailed": 1,
"CreditsStale": 1,
"ReservedExposure": 100,
"ExposureLimit": 100,
"Currency": "USD"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
Company Reporting1 operations
POST/api/v2/reporting/costsOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/reporting/costs' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"From": "2026-08-05T09:30:00Z",
"To": "2026-08-05T09:30:00Z",
"ExcludedUserIds": [
1
]
}'Request fields and validation
From · string · requiredTo · string · requiredExcludedUserIds · array or null · requiredExample request body · replace placeholders
{
"From": "2026-08-05T09:30:00Z",
"To": "2026-08-05T09:30:00Z",
"ExcludedUserIds": [
1
]
}200OKCostResponse
{
"Complete": true,
"Currencies": [
{
"Currency": "USD",
"ProviderCost": 100,
"ReferralFees": 100
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
Crypto Exchange35 operations
GET/api/v2/crypto-virtual-accounts/trading-overviewOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/trading-overview?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123200OKBoomFiTradingOverview
{
"fiat_funding_fees_and_limits": {},
"restricted_trading_currencies": [
"string"
],
"deposits": [
{
"Id": 123,
"PaymentId": "string",
"Amount": "100.00",
"Currency": "USD",
"ChainId": 123,
"Status": "PENDING",
"ProviderStatus": "PENDING",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"TransactionHash": "string",
"ActionUrl": "https://example.com/callback",
"SettlementTransactionHash": "",
"PaymentMethod": "Deposit"
}
],
"payments": [
{
"Id": 123,
"PaymentId": "string",
"Amount": "100.00",
"Currency": "USD",
"ChainId": 123,
"Status": "PENDING",
"ProviderStatus": "PENDING",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"TransactionHash": "string",
"ActionUrl": "https://example.com/callback",
"SettlementTransactionHash": "",
"PaymentMethod": "Deposit"
}
],
"account": {
"fees_and_limits": {},
"id": 123,
"reference": "external_reference_123",
"name": "string",
"account_type": "string",
"enabled": true,
"state": "string",
"sub_accounts": [
{
"fees_and_limits": {},
"id": 123,
"chain_id": 123,
"address": "string",
"chain": {
"id": {},
"name": {},
"native_currency_symbol": {}
},
"state": "string",
"status": "PENDING"
}
]
},
"balances": {
"balances": [
{
"fees_and_limits": {},
"account_id": 123,
"chain": {
"id": {},
"name": {},
"native_currency_symbol": {}
},
"currency": "USD",
"token_address": "string",
"amount": "100.00",
"amount_billing_currency": "USD",
"pending_amount": "100.00",
"pending_amount_billing_currency": "USD"
}
],
"total_balance": "100.00"
},
"currencies": {
"FIELD_FROM_APPLICATION": {
"symbol": "string",
"name": "string",
"type": "string",
"tokens": [
{
"chain_id": 123,
"address": "string",
"name": "string"
}
]
}
},
"settlement_accounts": [
{
"id": 123,
"name": "string",
"currency": "USD",
"bank_name": "string",
"account_number": "string",
"account_number_hint": "string",
"account_holder_name": "string",
"country": "GB",
"enabled": true,
"state": "string",
"status": "PENDING"
}
],
"fiat_funding_currencies": [
"string"
]
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/crypto-virtual-accounts/external-accountsList registered Exchange payout destinationsRequest & responses +
Lists destinations in the user's Exchange organisation. Optionally filter by type=Fiat or type=Digital. Bank details are masked; enabled indicates whether a destination can receive payouts.
curl --request GET 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/external-accounts?userId=123&type=example' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123typequerystringoptionalExample: example200OKapplication/json
[
{
"Id": 123,
"Type": "string",
"Reference": "external_reference_123",
"Name": "string",
"Currencies": [
"string"
],
"chain_id": 123,
"Address": "string",
"account_number_hint": "string",
"account_holder_name_hint": "string",
"bank_name": "string",
"Country": "GB",
"beneficiary_type": "string",
"payment_rail": "string",
"Enabled": true,
"created_at": "2026-08-05T09:30:00Z"
}
]400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
DELETE/api/v2/crypto-virtual-accounts/external-accounts/{accountId}Remove a registered Exchange payout destinationRequest & responses +
Removes a destination from the user's Exchange organisation. Payouts already in progress are unaffected. Returns 204 on success.
curl --request DELETE 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/external-accounts/123?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
accountIdpathintegerrequiredExample: 123userIdqueryintegeroptionalExample: 123204No Contentapplication/json
Response body is not specified in Scalar; do not assume it is empty.400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/crypto-address-bookOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/crypto-address-book?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"name": "string",
"currency": "USD",
"chain_id": 123,
"address": "string"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
name · string · optionalcurrency · string · optionalchain_id · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
address · string · optionalExample request body · replace placeholders
{
"name": "string",
"currency": "USD",
"chain_id": 123,
"address": "string"
}201CreatedBoomFiExternalAccount
{
"Id": 123,
"Type": "string",
"Reference": "external_reference_123",
"Name": "string",
"Currencies": [
"string"
],
"chain_id": 123,
"Address": "string",
"account_number_hint": "string",
"account_holder_name_hint": "string",
"bank_name": "string",
"Country": "GB",
"beneficiary_type": "string",
"payment_rail": "string",
"Enabled": true,
"created_at": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/bank-address-bookRegister a Exchange fiat external accountRequest & responses +
Registers a fiat external account in the user's Exchange organisation as a payout destination.
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/bank-address-book?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"beneficiary_type": "string",
"first_name": "Jane",
"last_name": "Doe",
"name": "string",
"account_number": "string",
"bank_name": "string",
"account_holder_name": "string",
"country": "GB",
"currency": "USD"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
beneficiary_type · string · optionalfirst_name · string or null · optionallast_name · string or null · optionalname · string · optionalaccount_number · string · optionalbank_name · string · optionalaccount_holder_name · string · optionalcountry · string · optionalcurrency · string · optionalExample request body · replace placeholders
{
"beneficiary_type": "string",
"first_name": "Jane",
"last_name": "Doe",
"name": "string",
"account_number": "string",
"bank_name": "string",
"account_holder_name": "string",
"country": "GB",
"currency": "USD"
}201CreatedBoomFiBankAddressBookAccount
{
"id": 123,
"name": "string",
"currency": "USD",
"bank_name": "string",
"account_number": "string",
"account_number_hint": "string",
"account_holder_name": "string",
"country": "GB",
"enabled": true,
"state": "string",
"status": "PENDING"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accountsOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Name": "string",
"Providers": [
"boomfi"
],
"Chains": [
{
"Currencies": [
"string"
],
"ChainId": 123
}
],
"UserId": 123
}'Request fields and validation
UserId · integer · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
Name · string · requiredMinimum length: 1
Maximum length: 100
Providers · array · requiredAllowed value: Exchange. Possible values: Exchange.
Chains · array · requiredExample request body · replace placeholders
{
"Name": "string",
"Providers": [
"boomfi"
],
"Chains": [
{
"Currencies": [
"string"
],
"ChainId": 123
}
],
"UserId": 123
}201CreatedOpenCryptoVirtualAccountResponse
{
"Success": true,
"Message": "string",
"Results": [
{
"Provider": "string",
"Status": "PENDING",
"Reference": "external_reference_123",
"Message": "string",
"VerificationUrl": "https://example.com/callback",
"Account": {
"id": 123,
"name": "string",
"address": "string",
"chain_id": 123,
"currencies": [
{}
],
"enabled": true,
"created_at": "2026-08-05T09:30:00Z"
},
"Wallets": [
{
"Id": 123,
"WalletAddress": "0x1111111111111111111111111111111111111111",
"CryptoAsset": "string",
"Status": "PENDING",
"ExternalWalletId": "external_reference_123",
"WalletType": "string"
}
]
}
]
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/payin-addressOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/payin-address' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"crypto_currency": "USDC",
"chain_id": 1,
"userId": 123
}'Request fields and validation
userId · integer · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
crypto_currency · string · requiredPossible values: USDC, USDT. Digital currency returned by GET /api/v2/crypto-virtual-accounts/trading-overview for the selected ready chain sub-account.
Allowed: USDC, USDT
chain_id · integer · requiredExchange chain IDs: Ethereum 1, Tron -200, Polygon 137, Arbitrum 42161. Possible values: 1, -200, 137, 42161.
Allowed: 1, -200, 137, 42161
Pattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"crypto_currency": "USDC",
"chain_id": 1,
"userId": 123
}201CreatedCreateCryptoDepositAddressResponse
{
"DepositWallet": {},
"OtcRequest": {
"BoomFiDepositPaymentId": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"DestinationCryptoAddress": "0x1111111111111111111111111111111111111111",
"Id": 123,
"Status": "PENDING",
"BoomFiVirtualAccountId": "string",
"CryptoCurrency": "USDC",
"CryptoAmount": "100.00",
"ChainId": 123,
"FiatCurrency": "USD",
"BoomFiOrderId": "string",
"BoomFiQuoteId": "string",
"BoomFiOrderStatus": "PENDING",
"BoomFiSettlementStatus": "PENDING",
"ToAmount": "100.00",
"EffectiveRate": "string",
"FailureMessage": "string",
"SlackChannelId": "string",
"SlackThreadTs": "string",
"SlackPermalink": "string",
"CompletedAt": "2026-08-05T09:30:00Z",
"CompletionMessage": "string",
"TransferDirection": "string",
"InitialExchangeRate": "string",
"InitialFeeAmount": "100.00",
"InitialFeeCurrency": "USD",
"CurrentFeeAmount": "100.00",
"CurrentFeeCurrency": "USD",
"RateDeviationPercent": 100,
"AutoExecutionTolerancePercent": 100,
"QuoteDecisionStatus": "PENDING",
"QuoteExpiresAt": "2026-08-05T09:30:00Z",
"FundsDecision": "string",
"ReturnFeeAmount": "100.00",
"ReturnFeeCurrency": "USD",
"SourceTransferId": "string",
"NextAction": "string",
"ActionUrl": "https://example.com/callback",
"FiatSettledAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalDeadlineAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalOverdue": true
}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/equals-to-interlaceTransfer Banking fiat to Crypto cards crypto through ExchangeRequest & responses +
Creates a Banking payment to the user's Exchange fiat account, waits for the Exchange deposit webhook, compares the funded quote with the stored request quote, and exchanges/pays the selected Crypto cards address. Rate moves beyond ±0.5% require user approval.
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/equals-to-interlace' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"IdempotencyKey": "operation-customer-1042-001",
"UserId": 123,
"FiatCurrency": "USD",
"Amount": 100,
"BudgetId": "string"
}'Request fields and validation
IdempotencyKey · string · requiredMinimum length: 8
Maximum length: 128
UserId · integer · requiredMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
FiatCurrency · string · requiredFiat source currency. Exchange must return matching bank funding instructions and fiat-to-crypto balances for the user's organisation.
Minimum length: 3
Maximum length: 3
Pattern: ^[A-Za-z]{3}$
Amount · number · requiredMinimum: 0.01
Maximum: 7.922816251426434e+28
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
BudgetId · string · requiredBanking source budget debited to fund the user's Exchange fiat account.
Example request body · replace placeholders
{
"IdempotencyKey": "operation-customer-1042-001",
"UserId": 123,
"FiatCurrency": "USD",
"Amount": 100,
"BudgetId": "string"
}200OKPublicEqualsToInterlaceResponse
{
"Success": true,
"Message": "string",
"Reference": "external_reference_123",
"UserId": 123,
"BudgetId": "string",
"FiatCurrency": "USD",
"FiatAmount": "100.00",
"CryptoCurrency": "USDC",
"EstimatedCryptoAmount": "100.00",
"EstimatedFeeAmount": "100.00",
"Rate": "string",
"ChainId": 123,
"Chain": "string",
"DepositAddress": "string",
"BoomFiPayout": {}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/equals-to-wallet/initiateOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/equals-to-wallet/initiate' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"FiatCurrency": "USD",
"Amount": 100,
"BudgetId": "string",
"CryptoCurrency": "USDC",
"Chain": "string",
"Address": "string"
}'Request fields and validation
UserId · integer · requiredMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
FiatCurrency · string · requiredMinimum length: 3
Maximum length: 3
Pattern: ^[A-Za-z]{3}$
Amount · number · requiredMinimum: 0.01
Maximum: 7.922816251426434e+28
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
BudgetId · string · requiredCryptoCurrency · string · requiredChain · string · requiredAddress · string · requiredExample request body · replace placeholders
{
"UserId": 123,
"FiatCurrency": "USD",
"Amount": 100,
"BudgetId": "string",
"CryptoCurrency": "USDC",
"Chain": "string",
"Address": "string"
}200OKPublicEqualsToWalletInitiateResponse
{
"Success": true,
"VerificationToken": "PLACEHOLDER_TOKEN",
"Message": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"Reference": "external_reference_123",
"UserId": 123,
"BudgetId": "string",
"FiatCurrency": "USD",
"FiatAmount": "100.00",
"CryptoCurrency": "USDC",
"EstimatedCryptoAmount": "100.00",
"EstimatedFeeAmount": "100.00",
"Rate": "string",
"ChainId": 123,
"Chain": "string",
"DestinationAddress": "0x1111111111111111111111111111111111111111",
"DestinationAddressMasked": "0x1111111111111111111111111111111111111111"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/equals-to-wallet/confirmOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/equals-to-wallet/confirm' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"VerificationToken": "PLACEHOLDER_TOKEN",
"OtpCode": "string"
}'Request fields and validation
UserId · integer · requiredMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
VerificationToken · string · requiredOtpCode · string · requiredExample request body · replace placeholders
{
"UserId": 123,
"VerificationToken": "PLACEHOLDER_TOKEN",
"OtpCode": "string"
}200OKPublicEqualsToWalletConfirmResponse
{
"Status": "PENDING",
"Notice": "string",
"Success": true,
"VerificationToken": "PLACEHOLDER_TOKEN",
"Message": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"Reference": "external_reference_123",
"UserId": 123,
"BudgetId": "string",
"FiatCurrency": "USD",
"FiatAmount": "100.00",
"CryptoCurrency": "USDC",
"EstimatedCryptoAmount": "100.00",
"EstimatedFeeAmount": "100.00",
"Rate": "string",
"ChainId": 123,
"Chain": "string",
"DestinationAddress": "0x1111111111111111111111111111111111111111",
"DestinationAddressMasked": "0x1111111111111111111111111111111111111111"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/ramp-quoteOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/ramp-quote' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"CryptoCurrency": "USDC",
"FiatCurrency": "USD",
"CryptoAmount": "100.00",
"UserId": 123,
"AccountId": "string",
"AccountReference": "external_reference_123",
"SettlementAccountId": 123,
"ChainId": 123
}'Request fields and validation
UserId · integer · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
AccountId · string or null · optionalExchange virtual parent account ID used as the source account for the dry-run quote.
AccountReference · string or null · optionalSettlementAccountId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
CryptoCurrency · string · requiredDigital currency held in the user's Exchange organisation.
FiatCurrency · string · requiredTarget fiat currency. Pricing is returned by Exchange Quick Trade with dry_run=true and is net of all Exchange and network fees.
CryptoAmount · string · requiredChainId · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"CryptoCurrency": "USDC",
"FiatCurrency": "USD",
"CryptoAmount": "100.00",
"UserId": 123,
"AccountId": "string",
"AccountReference": "external_reference_123",
"SettlementAccountId": 123,
"ChainId": 123
}200OKBoomFiRampQuoteData
{
"buy_currency": "USD",
"buy_amount": "100.00",
"sell_currency": "USD",
"sell_amount": "100.00",
"payment_method": "string",
"quote_time": "2026-08-05T09:30:00Z",
"expiry": "2026-08-05T09:30:00Z",
"rate": "string",
"fees": {
"fee_ccy": "100.00",
"network_fee": "100.00",
"boomfi_fee": "100.00",
"total_fee": "100.00"
},
"quote_amount": "100.00",
"settlement_ccy": "string",
"settlement_chain_id": 123,
"settlement_token_address": "string",
"session": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/exchange/quoteRequest an exact Exchange balance-to-balance quoteRequest & responses +
Returns an expiring quote for fiat-to-crypto or crypto-to-fiat conversion between the selected Exchange account IDs. Read account IDs from trading-overview and never calculate a rate locally.
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/exchange/quote' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"SellCurrency": "USD",
"BuyCurrency": "USD",
"SellAmount": "100.00",
"UserId": 123,
"DepositAccountId": 123,
"SettlementAccountId": 123,
"SellChainId": 123,
"SellTokenAddress": "string",
"BuyChainId": 123,
"BuyTokenAddress": "string",
"BankWithdrawal": {
"ExternalAccountId": 123,
"Name": "string",
"AccountNumber": "string",
"BankName": "string",
"AccountHolderName": "string",
"Country": "GB",
"BeneficiaryType": "string",
"FirstName": "Jane",
"LastName": "Doe"
},
"InterlaceDestinationAddress": "0x1111111111111111111111111111111111111111"
}'Request fields and validation
UserId · integer · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
SellCurrency · string · requiredBuyCurrency · string · requiredSellAmount · string · requiredDepositAccountId · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
SettlementAccountId · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
SellChainId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
SellTokenAddress · string or null · optionalBuyChainId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
BuyTokenAddress · string or null · optionalBankWithdrawal · object or null · optionalInterlaceDestinationAddress · string or null · optionalExample request body · replace placeholders
{
"SellCurrency": "USD",
"BuyCurrency": "USD",
"SellAmount": "100.00",
"UserId": 123,
"DepositAccountId": 123,
"SettlementAccountId": 123,
"SellChainId": 123,
"SellTokenAddress": "string",
"BuyChainId": 123,
"BuyTokenAddress": "string",
"BankWithdrawal": {
"ExternalAccountId": 123,
"Name": "string",
"AccountNumber": "string",
"BankName": "string",
"AccountHolderName": "string",
"Country": "GB",
"BeneficiaryType": "string",
"FirstName": "Jane",
"LastName": "Doe"
},
"InterlaceDestinationAddress": "0x1111111111111111111111111111111111111111"
}200OKBoomFiRampQuoteData
{
"buy_currency": "USD",
"buy_amount": "100.00",
"sell_currency": "USD",
"sell_amount": "100.00",
"payment_method": "string",
"quote_time": "2026-08-05T09:30:00Z",
"expiry": "2026-08-05T09:30:00Z",
"rate": "string",
"fees": {
"fee_ccy": "100.00",
"network_fee": "100.00",
"boomfi_fee": "100.00",
"total_fee": "100.00"
},
"quote_amount": "100.00",
"settlement_ccy": "string",
"settlement_chain_id": 123,
"settlement_token_address": "string",
"session": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/exchange/acceptAccept an exact Exchange quoteRequest & responses +
Accepts an unexpired quote returned by exchange/quote. Do not retry an expired quote; request a new one.
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/exchange/accept' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"QuoteId": "string",
"UserId": 123
}'Request fields and validation
UserId · integer · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
QuoteId · string · requiredExample request body · replace placeholders
{
"QuoteId": "string",
"UserId": 123
}200OKapplication/json
{}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/interlace-to-equals/quoteQuote a Crypto cards-to-Banking transfer through ExchangeRequest & responses +
Returns the indicative exchange rate, received amount, fees, and expiry before an OTP is requested or funds are moved.
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/interlace-to-equals/quote' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Reference": "external_reference_123",
"UserId": 123,
"AccountRef": "string",
"BoomFiAccountId": "string",
"SettlementAccountId": 123,
"ChainId": 1,
"Currency": "USDC",
"CryptoAmount": "100.00",
"FiatCurrency": "USD",
"TargetBudgetId": "string"
}'Request fields and validation
UserId · integer · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
AccountRef · string or null · optionalBoomFiAccountId · string or null · optionalSettlementAccountId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
Reference · string · requiredChainId · integer · optionalExchange chain IDs: Ethereum 1, Tron -200, Polygon 137, Arbitrum 42161. Possible values: 1, -200, 137, 42161.
Allowed: 1, -200, 137, 42161
Pattern: ^-?(?:0|[1-9]\d*)$
Currency · string or null · optionalCrypto asset withdrawn from Crypto cards and deposited into Exchange. Possible values: USDC, USDT.
Allowed: USDC, USDT
CryptoAmount · string or null · optionalFiatCurrency · string or null · optionalFiat settlement currency credited to Banking. Possible values: USD, EUR, GBP.
Allowed: USD, EUR, GBP
TargetBudgetId · string or null · optionalOptional Banking budget to credit. When omitted, the service selects the user's budget that supports FiatCurrency.
Example request body · replace placeholders
{
"Reference": "external_reference_123",
"UserId": 123,
"AccountRef": "string",
"BoomFiAccountId": "string",
"SettlementAccountId": 123,
"ChainId": 1,
"Currency": "USDC",
"CryptoAmount": "100.00",
"FiatCurrency": "USD",
"TargetBudgetId": "string"
}200OKBoomFiRampQuoteData
{
"buy_currency": "USD",
"buy_amount": "100.00",
"sell_currency": "USD",
"sell_amount": "100.00",
"payment_method": "string",
"quote_time": "2026-08-05T09:30:00Z",
"expiry": "2026-08-05T09:30:00Z",
"rate": "string",
"fees": {
"fee_ccy": "100.00",
"network_fee": "100.00",
"boomfi_fee": "100.00",
"total_fee": "100.00"
},
"quote_amount": "100.00",
"settlement_ccy": "string",
"settlement_chain_id": 123,
"settlement_token_address": "string",
"session": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/interlace-to-equals/initiateInitiate a Crypto cards-to-Banking transfer through ExchangeRequest & responses +
After the customer reviews a quote, validates the Crypto cards withdrawal route, prepares the Exchange deposit instruction, resolves the target Banking budget, and sends an OTP. This step does not withdraw funds.
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/interlace-to-equals/initiate' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Reference": "external_reference_123",
"UserId": 123,
"AccountRef": "string",
"BoomFiAccountId": "string",
"SettlementAccountId": 123,
"ChainId": 1,
"Currency": "USDC",
"CryptoAmount": "100.00",
"FiatCurrency": "USD",
"TargetBudgetId": "string"
}'Request fields and validation
UserId · integer · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
AccountRef · string or null · optionalBoomFiAccountId · string or null · optionalSettlementAccountId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
Reference · string · requiredChainId · integer · optionalExchange chain IDs: Ethereum 1, Tron -200, Polygon 137, Arbitrum 42161. Possible values: 1, -200, 137, 42161.
Allowed: 1, -200, 137, 42161
Pattern: ^-?(?:0|[1-9]\d*)$
Currency · string or null · optionalCrypto asset withdrawn from Crypto cards and deposited into Exchange. Possible values: USDC, USDT.
Allowed: USDC, USDT
CryptoAmount · string or null · optionalFiatCurrency · string or null · optionalFiat settlement currency credited to Banking. Possible values: USD, EUR, GBP.
Allowed: USD, EUR, GBP
TargetBudgetId · string or null · optionalOptional Banking budget to credit. When omitted, the service selects the user's budget that supports FiatCurrency.
Example request body · replace placeholders
{
"Reference": "external_reference_123",
"UserId": 123,
"AccountRef": "string",
"BoomFiAccountId": "string",
"SettlementAccountId": 123,
"ChainId": 1,
"Currency": "USDC",
"CryptoAmount": "100.00",
"FiatCurrency": "USD",
"TargetBudgetId": "string"
}200OKBoomFiInterlaceToEqualsInitiateResponse
{
"Success": true,
"VerificationToken": "PLACEHOLDER_TOKEN",
"Message": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"DepositAddress": "string",
"DepositWallet": {},
"IndicativeQuote": {
"buy_currency": "USD",
"buy_amount": "100.00",
"sell_currency": "USD",
"sell_amount": "100.00",
"payment_method": "string",
"quote_time": "2026-08-05T09:30:00Z",
"expiry": "2026-08-05T09:30:00Z",
"rate": "string",
"fees": {
"fee_ccy": "100.00",
"network_fee": "100.00",
"boomfi_fee": "100.00",
"total_fee": "100.00"
},
"quote_amount": "100.00",
"settlement_ccy": "string",
"settlement_chain_id": 123,
"settlement_token_address": "string",
"session": "string"
},
"AutoExecutionTolerancePercent": 100,
"ExchangeRateNotice": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/interlace-to-equals/confirmConfirm a Crypto cards-to-Banking transfer through ExchangeRequest & responses +
Verifies the OTP, submits the Crypto cards crypto withdrawal to the prepared Exchange address, and queues the Exchange conversion. After fiat settlement, Hoppa credits the resolved Banking budget.
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/interlace-to-equals/confirm' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"VerificationToken": "PLACEHOLDER_TOKEN",
"OtpCode": "string",
"UserId": 123
}'Request fields and validation
UserId · integer · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
VerificationToken · string · requiredOtpCode · string · requiredExample request body · replace placeholders
{
"VerificationToken": "PLACEHOLDER_TOKEN",
"OtpCode": "string",
"UserId": 123
}200OKBoomFiInterlaceToEqualsConfirmResponse
{
"Success": true,
"Message": "string",
"TransferId": "string",
"TransferStatus": "PENDING",
"TargetBudgetId": "string",
"DepositWallet": {},
"OtcRequest": {
"BoomFiDepositPaymentId": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"DestinationCryptoAddress": "0x1111111111111111111111111111111111111111",
"Id": 123,
"Status": "PENDING",
"BoomFiVirtualAccountId": "string",
"CryptoCurrency": "USDC",
"CryptoAmount": "100.00",
"ChainId": 123,
"FiatCurrency": "USD",
"BoomFiOrderId": "string",
"BoomFiQuoteId": "string",
"BoomFiOrderStatus": "PENDING",
"BoomFiSettlementStatus": "PENDING",
"ToAmount": "100.00",
"EffectiveRate": "string",
"FailureMessage": "string",
"SlackChannelId": "string",
"SlackThreadTs": "string",
"SlackPermalink": "string",
"CompletedAt": "2026-08-05T09:30:00Z",
"CompletionMessage": "string",
"TransferDirection": "string",
"InitialExchangeRate": "string",
"InitialFeeAmount": "100.00",
"InitialFeeCurrency": "USD",
"CurrentFeeAmount": "100.00",
"CurrentFeeCurrency": "USD",
"RateDeviationPercent": 100,
"AutoExecutionTolerancePercent": 100,
"QuoteDecisionStatus": "PENDING",
"QuoteExpiresAt": "2026-08-05T09:30:00Z",
"FundsDecision": "string",
"ReturnFeeAmount": "100.00",
"ReturnFeeCurrency": "USD",
"SourceTransferId": "string",
"NextAction": "string",
"ActionUrl": "https://example.com/callback",
"FiatSettledAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalDeadlineAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalOverdue": true
}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}422Unprocessable EntityErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/crypto-virtual-accounts/transfersList Exchange transfer workflowsRequest & responses +
Returns the latest persisted Crypto cards-to-Banking and Banking-to-Crypto cards workflows for the selected user. Poll this endpoint when signed webhook delivery is delayed.
curl --request GET 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/transfers?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123200OKapplication/json
[
{
"BoomFiDepositPaymentId": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"DestinationCryptoAddress": "0x1111111111111111111111111111111111111111",
"Id": 123,
"Status": "PENDING",
"BoomFiVirtualAccountId": "string",
"CryptoCurrency": "USDC",
"CryptoAmount": "100.00",
"ChainId": 123,
"FiatCurrency": "USD",
"BoomFiOrderId": "string",
"BoomFiQuoteId": "string",
"BoomFiOrderStatus": "PENDING",
"BoomFiSettlementStatus": "PENDING",
"ToAmount": "100.00",
"EffectiveRate": "string",
"FailureMessage": "string",
"SlackChannelId": "string",
"SlackThreadTs": "string",
"SlackPermalink": "string",
"CompletedAt": "2026-08-05T09:30:00Z",
"CompletionMessage": "string",
"TransferDirection": "string",
"InitialExchangeRate": "string",
"InitialFeeAmount": "100.00",
"InitialFeeCurrency": "USD",
"CurrentFeeAmount": "100.00",
"CurrentFeeCurrency": "USD",
"RateDeviationPercent": 100,
"AutoExecutionTolerancePercent": 100,
"QuoteDecisionStatus": "PENDING",
"QuoteExpiresAt": "2026-08-05T09:30:00Z",
"FundsDecision": "string",
"ReturnFeeAmount": "100.00",
"ReturnFeeCurrency": "USD",
"SourceTransferId": "string",
"NextAction": "string",
"ActionUrl": "https://example.com/callback",
"FiatSettledAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalDeadlineAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalOverdue": true
}
]400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/crypto-virtual-accounts/transfers/{id}Get a Exchange transfer workflowRequest & responses +
Returns funding, quote, approval, exchange, settlement, payout, return-fee, and completion state for one transfer.
curl --request GET 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/transfers/123?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
idpathintegerrequiredExample: 123userIdqueryintegeroptionalExample: 123200OKBoomFiOtcTradeRequestResponse
{
"BoomFiDepositPaymentId": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"DestinationCryptoAddress": "0x1111111111111111111111111111111111111111",
"Id": 123,
"Status": "PENDING",
"BoomFiVirtualAccountId": "string",
"CryptoCurrency": "USDC",
"CryptoAmount": "100.00",
"ChainId": 123,
"FiatCurrency": "USD",
"BoomFiOrderId": "string",
"BoomFiQuoteId": "string",
"BoomFiOrderStatus": "PENDING",
"BoomFiSettlementStatus": "PENDING",
"ToAmount": "100.00",
"EffectiveRate": "string",
"FailureMessage": "string",
"SlackChannelId": "string",
"SlackThreadTs": "string",
"SlackPermalink": "string",
"CompletedAt": "2026-08-05T09:30:00Z",
"CompletionMessage": "string",
"TransferDirection": "string",
"InitialExchangeRate": "string",
"InitialFeeAmount": "100.00",
"InitialFeeCurrency": "USD",
"CurrentFeeAmount": "100.00",
"CurrentFeeCurrency": "USD",
"RateDeviationPercent": 100,
"AutoExecutionTolerancePercent": 100,
"QuoteDecisionStatus": "PENDING",
"QuoteExpiresAt": "2026-08-05T09:30:00Z",
"FundsDecision": "string",
"ReturnFeeAmount": "100.00",
"ReturnFeeCurrency": "USD",
"SourceTransferId": "string",
"NextAction": "string",
"ActionUrl": "https://example.com/callback",
"FiatSettledAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalDeadlineAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalOverdue": true
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/transfers/{transferId}/decisionRespond to a changed Exchange quoteRequest & responses +
Use approve or decline while the transfer awaits quote approval. After decline, use keep to leave funds at Exchange or return to send them back to the recorded source; provider/network return costs are reported when Exchange supplies them.
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/transfers/123/decision' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Decision": "string",
"UserId": 123
}'Parameters
transferIdpathintegerrequiredExample: 123Request fields and validation
UserId · integer · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
Decision · string · requiredExample request body · replace placeholders
{
"Decision": "string",
"UserId": 123
}200OKBoomFiOtcTradeRequestResponse
{
"BoomFiDepositPaymentId": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"DestinationCryptoAddress": "0x1111111111111111111111111111111111111111",
"Id": 123,
"Status": "PENDING",
"BoomFiVirtualAccountId": "string",
"CryptoCurrency": "USDC",
"CryptoAmount": "100.00",
"ChainId": 123,
"FiatCurrency": "USD",
"BoomFiOrderId": "string",
"BoomFiQuoteId": "string",
"BoomFiOrderStatus": "PENDING",
"BoomFiSettlementStatus": "PENDING",
"ToAmount": "100.00",
"EffectiveRate": "string",
"FailureMessage": "string",
"SlackChannelId": "string",
"SlackThreadTs": "string",
"SlackPermalink": "string",
"CompletedAt": "2026-08-05T09:30:00Z",
"CompletionMessage": "string",
"TransferDirection": "string",
"InitialExchangeRate": "string",
"InitialFeeAmount": "100.00",
"InitialFeeCurrency": "USD",
"CurrentFeeAmount": "100.00",
"CurrentFeeCurrency": "USD",
"RateDeviationPercent": 100,
"AutoExecutionTolerancePercent": 100,
"QuoteDecisionStatus": "PENDING",
"QuoteExpiresAt": "2026-08-05T09:30:00Z",
"FundsDecision": "string",
"ReturnFeeAmount": "100.00",
"ReturnFeeCurrency": "USD",
"SourceTransferId": "string",
"NextAction": "string",
"ActionUrl": "https://example.com/callback",
"FiatSettledAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalDeadlineAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalOverdue": true
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/payout-addressOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/payout-address?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Amount": "100.00",
"Ccy": "string",
"WalletAddress": "0x1111111111111111111111111111111111111111",
"AccountRef": "string",
"ChainId": 123,
"Reference": "external_reference_123",
"TokenAddress": "string"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
AccountRef · string or null · optionalAmount · string · requiredCcy · string · requiredChainId · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
WalletAddress · string · requiredReference · string or null · optionalTokenAddress · string or null · optionalExample request body · replace placeholders
{
"Amount": "100.00",
"Ccy": "string",
"WalletAddress": "0x1111111111111111111111111111111111111111",
"AccountRef": "string",
"ChainId": 123,
"Reference": "external_reference_123",
"TokenAddress": "string"
}200OKapplication/json
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/payout-fiatOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/payout-fiat?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Amount": "100.00",
"Currency": "USD",
"ExternalAccountId": 123,
"Name": "string",
"AccountNumber": "string",
"BankName": "string",
"AccountHolderName": "string",
"Country": "GB",
"Reference": "external_reference_123",
"BeneficiaryType": "string",
"FirstName": "Jane",
"LastName": "Doe"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
ExternalAccountId · integer or null · optionalMinimum: 1
Maximum: 9223372036854776000
Pattern: ^-?(?:0|[1-9]\d*)$
Amount · string · requiredCurrency · string · requiredName · string · optionalAccountNumber · string · optionalBankName · string · optionalAccountHolderName · string · optionalCountry · string · optionalReference · string or null · optionalBeneficiaryType · string · optionalFirstName · string or null · optionalLastName · string or null · optionalExample request body · replace placeholders
{
"Amount": "100.00",
"Currency": "USD",
"ExternalAccountId": 123,
"Name": "string",
"AccountNumber": "string",
"BankName": "string",
"AccountHolderName": "string",
"Country": "GB",
"Reference": "external_reference_123",
"BeneficiaryType": "string",
"FirstName": "Jane",
"LastName": "Doe"
}200OKapplication/json
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/equals-to-interlace/fundOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/equals-to-interlace/fund?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"IdempotencyKey": "operation-customer-1042-001",
"SourceBudgetId": "string",
"FiatCurrency": "USD",
"CryptoCurrency": "USDC",
"DestinationAddress": "0x1111111111111111111111111111111111111111",
"FiatAmount": 100,
"ChainId": 123
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
IdempotencyKey · string · requiredMinimum length: 8
Maximum length: 128
SourceBudgetId · string · requiredFiatCurrency · string · requiredFiatAmount · number · optionalMinimum: 0.01
Maximum: 7.922816251426434e+28
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
CryptoCurrency · string · requiredChainId · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
DestinationAddress · string · requiredExample request body · replace placeholders
{
"IdempotencyKey": "operation-customer-1042-001",
"SourceBudgetId": "string",
"FiatCurrency": "USD",
"CryptoCurrency": "USDC",
"DestinationAddress": "0x1111111111111111111111111111111111111111",
"FiatAmount": 100,
"ChainId": 123
}200OKBoomFiEqualsToInterlaceResponse
{
"Success": true,
"Message": "string",
"EqualsPaymentId": "string",
"IndicativeQuote": {
"buy_currency": "USD",
"buy_amount": "100.00",
"sell_currency": "USD",
"sell_amount": "100.00",
"payment_method": "string",
"quote_time": "2026-08-05T09:30:00Z",
"expiry": "2026-08-05T09:30:00Z",
"rate": "string",
"fees": {
"fee_ccy": "100.00",
"network_fee": "100.00",
"boomfi_fee": "100.00",
"total_fee": "100.00"
},
"quote_amount": "100.00",
"settlement_ccy": "string",
"settlement_chain_id": 123,
"settlement_token_address": "string",
"session": "string"
},
"Transfer": {
"BoomFiDepositPaymentId": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"DestinationCryptoAddress": "0x1111111111111111111111111111111111111111",
"Id": 123,
"Status": "PENDING",
"BoomFiVirtualAccountId": "string",
"CryptoCurrency": "USDC",
"CryptoAmount": "100.00",
"ChainId": 123,
"FiatCurrency": "USD",
"BoomFiOrderId": "string",
"BoomFiQuoteId": "string",
"BoomFiOrderStatus": "PENDING",
"BoomFiSettlementStatus": "PENDING",
"ToAmount": "100.00",
"EffectiveRate": "string",
"FailureMessage": "string",
"SlackChannelId": "string",
"SlackThreadTs": "string",
"SlackPermalink": "string",
"CompletedAt": "2026-08-05T09:30:00Z",
"CompletionMessage": "string",
"TransferDirection": "string",
"InitialExchangeRate": "string",
"InitialFeeAmount": "100.00",
"InitialFeeCurrency": "USD",
"CurrentFeeAmount": "100.00",
"CurrentFeeCurrency": "USD",
"RateDeviationPercent": 100,
"AutoExecutionTolerancePercent": 100,
"QuoteDecisionStatus": "PENDING",
"QuoteExpiresAt": "2026-08-05T09:30:00Z",
"FundsDecision": "string",
"ReturnFeeAmount": "100.00",
"ReturnFeeCurrency": "USD",
"SourceTransferId": "string",
"NextAction": "string",
"ActionUrl": "https://example.com/callback",
"FiatSettledAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalDeadlineAt": "2026-08-05T09:30:00Z",
"FiatWithdrawalOverdue": true
},
"AutoExecutionTolerancePercent": 100
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/equalsmoney-depositsDeposit crypto into a Banking budget through ExchangeRequest & responses +
Creates an asynchronous crypto-to-fiat deposit. Hoppa returns a Exchange funding instruction, monitors conversion and settlement into the configured platform Banking account, then transfers the settled fiat to the target user's Banking budget. Send a stable Idempotency-Key when retrying the same deposit.
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/equalsmoney-deposits' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"CryptoCurrency": "USDC",
"CryptoAmount": "100.00",
"FiatCurrency": "USD",
"UserId": 123,
"ChainId": 1,
"TargetBudgetId": "string",
"BoomFiAccountId": "string",
"BoomFiAccountReference": "external_reference_123"
}'Parameters
Idempotency-KeyheaderstringrequiredExample: operation-customer-1042-001Request fields and validation
UserId · integer · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
CryptoCurrency · string · requiredCrypto asset deposited into the user's Exchange virtual account. Possible values: USDC, USDT.
Allowed: USDC, USDT
CryptoAmount · string · requiredPositive decimal amount encoded as a string; do not send a JSON floating-point number.
ChainId · integer · optionalExchange chain IDs: Ethereum 1, Tron -200, Polygon 137, Arbitrum 42161. Possible values: 1, -200, 137, 42161.
Allowed: 1, -200, 137, 42161
Pattern: ^-?(?:0|[1-9]\d*)$
FiatCurrency · string · requiredSettlement currency must be enabled in the company provider configuration. Possible values: USD, EUR, GBP.
Allowed: USD, EUR, GBP
Pattern: ^(USD|EUR|GBP|usd|eur|gbp)$
TargetBudgetId · string or null · optionalOptional Banking budget to credit. When omitted, the service selects the user's budget that supports FiatCurrency.
BoomFiAccountId · string or null · optionalOptional Exchange virtual parent account ID override. Normally omit it so Hoppa resolves the user's linked Exchange account.
BoomFiAccountReference · string or null · optionalOptional Exchange account_reference override. Normally omit it so Hoppa resolves the user's linked Exchange account.
Example request body · replace placeholders
{
"CryptoCurrency": "USDC",
"CryptoAmount": "100.00",
"FiatCurrency": "USD",
"UserId": 123,
"ChainId": 1,
"TargetBudgetId": "string",
"BoomFiAccountId": "string",
"BoomFiAccountReference": "external_reference_123"
}202AcceptedBoomFiEqualsMoneyDepositResponse
{
"Id": 123,
"Status": "PENDING",
"UserId": 123,
"TargetBudgetId": "string",
"CryptoCurrency": "USDC",
"CryptoAmount": "100.00",
"ChainId": 123,
"FiatCurrency": "USD",
"EstimatedFiatAmount": "100.00",
"SettledFiatAmount": "100.00",
"DepositInstruction": {
"account_id": 123,
"sub_account_id": 123,
"chain_id": 123,
"chain_name": "string",
"currency": "USD",
"address": "string"
},
"BoomFiOrderId": "string",
"BoomFiOrderStatus": "PENDING",
"BoomFiSettlementStatus": "PENDING",
"EqualsTransferId": "string",
"FailureMessage": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/crypto-virtual-accounts/equalsmoney-deposits/{id}Get a Exchange-to-Banking depositRequest & responses +
Returns the current funding, Exchange trade, settlement, and Banking budget-credit status. Poll until Status is completed or failed.
curl --request GET 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/equalsmoney-deposits/123?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
idpathintegerrequiredExample: 123userIdqueryintegeroptionalExample: 123200OKBoomFiEqualsMoneyDepositResponse
{
"Id": 123,
"Status": "PENDING",
"UserId": 123,
"TargetBudgetId": "string",
"CryptoCurrency": "USDC",
"CryptoAmount": "100.00",
"ChainId": 123,
"FiatCurrency": "USD",
"EstimatedFiatAmount": "100.00",
"SettledFiatAmount": "100.00",
"DepositInstruction": {
"account_id": 123,
"sub_account_id": 123,
"chain_id": 123,
"chain_name": "string",
"currency": "USD",
"address": "string"
},
"BoomFiOrderId": "string",
"BoomFiOrderStatus": "PENDING",
"BoomFiSettlementStatus": "PENDING",
"EqualsTransferId": "string",
"FailureMessage": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/crypto-virtual-accounts/verificationRead the current Exchange verification and provider account state.Request & responses +
Supply the company-owned userId query parameter and the company x-api-key. Exchange must be enabled for the company. Verification responses use no-store caching.
curl --request GET 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/verification?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegerrequiredExample: 123400Bad RequestVerificationErrorResponse
{
"message": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403ForbiddenProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}404Not FoundVerificationErrorResponse
{
"message": "string"
}409ConflictVerificationErrorResponse
{
"message": "string"
}502Bad GatewayVerificationErrorResponse
{
"message": "string"
}200OKExchangeVerificationStatus
{
"tier": "sdd",
"status": "approved",
"eligible": true,
"hasProviderAccount": true,
"usesSharedStagingOrganization": false,
"verificationType": "individual",
"provider": {
"status": "ready",
"kycStatus": "accepted",
"nextAction": null,
"verificationUrl": null,
"reason": null,
"actionSubmitted": false,
"cryptoDepositAccountReady": true,
"eurAccountReady": true
},
"applicationSupported": true,
"applicationUnavailableReason": null,
"businessOnboardingSupported": false
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/crypto-virtual-accounts/verification/settlement-accountsRead the authenticated user's provisioned crypto addresses and bank settlement details.Request & responses +
Supply the company-owned userId query parameter and the company x-api-key. Exchange must be enabled for the company. Verification responses use no-store caching.
curl --request GET 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/verification/settlement-accounts?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegerrequiredExample: 123400Bad RequestVerificationErrorResponse
{
"message": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403ForbiddenProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}404Not FoundVerificationErrorResponse
{
"message": "string"
}409ConflictVerificationErrorResponse
{
"message": "string"
}502Bad GatewayVerificationErrorResponse
{
"message": "string"
}200OKBoomFiSettlementAccounts
{
"organizationId": "string",
"kycStatus": "PENDING",
"accounts": [
{
"id": 123,
"reference": "external_reference_123",
"name": "string",
"chainId": 123,
"currencies": [
"string"
],
"address": "string",
"ready": true,
"bank": {
"name": "string",
"bic": "string",
"accountHolderName": "string",
"country": "GB",
"address": "string"
}
}
],
"restrictedTradingCurrencies": [
"string"
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/crypto-virtual-accounts/verification/applicationRead the personal application answers, missing fields and submission readiness.Request & responses +
Supply the company-owned userId query parameter and the company x-api-key. Exchange must be enabled for the company. Verification responses use no-store caching.
curl --request GET 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/verification/application?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegerrequiredExample: 123400Bad RequestVerificationErrorResponse
{
"message": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403ForbiddenProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}404Not FoundVerificationErrorResponse
{
"message": "string"
}409ConflictVerificationErrorResponse
{
"message": "string"
}502Bad GatewayVerificationErrorResponse
{
"message": "string"
}200OKBoomFiApplicationDraft
{
"supported": true,
"message": null,
"answers": {
"sdd_country_select": "GB",
"investment_citizenship": "81",
"employment_type_or_status": "15",
"industry": "20",
"employment_jurisdiction": "GB",
"acting_capacity": "156"
},
"kycLevel": "SDD",
"missingFields": [],
"readyToSubmit": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/verification/applicationSubmit personal application answers or reuse the approved SumSub questionnaire. Returns the current verification state; submission does not imply approval.Request & responses +
Supply the company-owned userId query parameter and the company x-api-key. Exchange must be enabled for the company. Verification responses use no-store caching.
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/verification/application?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Answers": {},
"UseSumsubAnswers": true
}'Parameters
userIdqueryintegerrequiredExample: 123Request fields and validation
Answers · object · requiredManual questionnaire field IDs and string values. Read GET application for the user's kycLevel and missingFields. All applicable fields must be supplied for manual submission. With UseSumsubAnswers=true send Answers={} instead. Numeric options are strings; never infer financial declarations.
UseSumsubAnswers · boolean · optionalWhen true, reuse the approved Exchange SumSub questionnaire. Answers must still be present but is ignored. Defaults to false.
Example request body · replace placeholders
{
"Answers": {},
"UseSumsubAnswers": true
}400Bad RequestVerificationErrorResponse
{
"message": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403ForbiddenProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}404Not FoundVerificationErrorResponse
{
"message": "string"
}409ConflictVerificationErrorResponse
{
"message": "string"
}502Bad GatewayVerificationErrorResponse
{
"message": "string"
}200OKExchangeVerificationStatus
{
"tier": "sdd",
"status": "approved",
"eligible": true,
"hasProviderAccount": true,
"usesSharedStagingOrganization": false,
"verificationType": "individual",
"provider": {
"status": "ready",
"kycStatus": "accepted",
"nextAction": null,
"verificationUrl": null,
"reason": null,
"actionSubmitted": false,
"cryptoDepositAccountReady": true,
"eurAccountReady": true
},
"applicationSupported": true,
"applicationUnavailableReason": null,
"businessOnboardingSupported": false
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/crypto-virtual-accounts/verification/businessRead business application details and issues that must be resolved before submission.Request & responses +
Supply the company-owned userId query parameter and the company x-api-key. Exchange must be enabled for the company. Verification responses use no-store caching.
curl --request GET 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/verification/business?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegerrequiredExample: 123400Bad RequestVerificationErrorResponse
{
"message": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403ForbiddenProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}404Not FoundVerificationErrorResponse
{
"message": "string"
}409ConflictVerificationErrorResponse
{
"message": "string"
}502Bad GatewayVerificationErrorResponse
{
"message": "string"
}200OKBoomFiBusinessApplicationDraft
{
"legalName": "string",
"contactName": "string",
"contactEmail": "user@example.com",
"contactPhone": "+447700900123",
"issues": [
"string"
],
"readyToSubmit": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/verification/businessStart provider-hosted business verification. An authorisation_required status requires the business authorisation code flow.Request & responses +
Supply the company-owned userId query parameter and the company x-api-key. Exchange must be enabled for the company. Verification responses use no-store caching.
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/verification/business?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegerrequiredExample: 123400Bad RequestVerificationErrorResponse
{
"message": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403ForbiddenProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}404Not FoundVerificationErrorResponse
{
"message": "string"
}409ConflictVerificationErrorResponse
{
"message": "string"
}502Bad GatewayVerificationErrorResponse
{
"message": "string"
}200OKExchangeVerificationSession
{
"tier": "string",
"status": "PENDING",
"verificationUrl": "https://example.com/callback"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/verification/business/authorisation/send-codeSend the business authorisation code to the account owner.Request & responses +
Supply the company-owned userId query parameter and the company x-api-key. Exchange must be enabled for the company. Verification responses use no-store caching.
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/verification/business/authorisation/send-code?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegerrequiredExample: 123400Bad RequestVerificationErrorResponse
{
"message": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403ForbiddenProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}404Not FoundVerificationErrorResponse
{
"message": "string"
}409ConflictVerificationErrorResponse
{
"message": "string"
}502Bad GatewayVerificationErrorResponse
{
"message": "string"
}200OKBusinessCodeSentResponse
{
"sent": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/verification/business/authorisationConfirm the business authorisation code.Request & responses +
Supply the company-owned userId query parameter and the company x-api-key. Exchange must be enabled for the company. Verification responses use no-store caching.
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/verification/business/authorisation?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Code": "string"
}'Parameters
userIdqueryintegerrequiredExample: 123Request fields and validation
Code · string · requiredExample request body · replace placeholders
{
"Code": "string"
}400Bad RequestVerificationErrorResponse
{
"message": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403ForbiddenProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}404Not FoundVerificationErrorResponse
{
"message": "string"
}409ConflictVerificationErrorResponse
{
"message": "string"
}502Bad GatewayVerificationErrorResponse
{
"message": "string"
}200OKBusinessAuthorisedResponse
{
"authorised": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/verification/sessionStart or resume Exchange verification for the selected tier. Open verificationUrl when present; poll verification for the current state.Request & responses +
Supply the company-owned userId query parameter and the company x-api-key. Exchange must be enabled for the company. Verification responses use no-store caching.
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/verification/session?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Tier": "sdd"
}'Parameters
userIdqueryintegerrequiredExample: 123Request fields and validation
Tier · string · requiredVerification tier: sdd or cdd for individuals; kyb for business accounts. Values are lowercase.
Example request body · replace placeholders
{
"Tier": "sdd"
}400Bad RequestVerificationErrorResponse
{
"message": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403ForbiddenProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}404Not FoundVerificationErrorResponse
{
"message": "string"
}409ConflictVerificationErrorResponse
{
"message": "string"
}502Bad GatewayVerificationErrorResponse
{
"message": "string"
}200OKExchangeVerificationSession
{
"tier": "sdd",
"status": "in_progress",
"verificationUrl": "https://verify.example.com/session"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/verification/tinSubmit requested tax identification information and return the updated verification state.Request & responses +
Supply the company-owned userId query parameter and the company x-api-key. Exchange must be enabled for the company. Verification responses use no-store caching.
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/verification/tin?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"TaxResidency": "string",
"Tin": "string",
"TinNotAvailable": true,
"TinNotAvailableReason": "string",
"TinNotAvailableReasonDescription": "Example description"
}'Parameters
userIdqueryintegerrequiredExample: 123Request fields and validation
TaxResidency · string · requiredTin · string or null · requiredTinNotAvailable · boolean · requiredTinNotAvailableReason · string or null · requiredTinNotAvailableReasonDescription · string or null · requiredExample request body · replace placeholders
{
"TaxResidency": "string",
"Tin": "string",
"TinNotAvailable": true,
"TinNotAvailableReason": "string",
"TinNotAvailableReasonDescription": "Example description"
}400Bad RequestVerificationErrorResponse
{
"message": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403ForbiddenProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}404Not FoundVerificationErrorResponse
{
"message": "string"
}409ConflictVerificationErrorResponse
{
"message": "string"
}502Bad GatewayVerificationErrorResponse
{
"message": "string"
}200OKExchangeVerificationStatus
{
"tier": "sdd",
"status": "approved",
"eligible": true,
"hasProviderAccount": true,
"usesSharedStagingOrganization": false,
"verificationType": "individual",
"provider": {
"status": "ready",
"kycStatus": "accepted",
"nextAction": null,
"verificationUrl": null,
"reason": null,
"actionSubmitted": false,
"cryptoDepositAccountReady": true,
"eurAccountReady": true
},
"applicationSupported": true,
"applicationUnavailableReason": null,
"businessOnboardingSupported": false
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/crypto-virtual-accounts/verification/eddSubmit requested enhanced due diligence information and return the updated verification state.Request & responses +
Supply the company-owned userId query parameter and the company x-api-key. Exchange must be enabled for the company. Verification responses use no-store caching.
curl --request POST 'https://staging.hoppa.global/api/v2/crypto-virtual-accounts/verification/edd?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"CapitalOfCompany": "string",
"GiftOrInheritance": "string",
"ProfessionalSalary": {
"NameOfEmployer": "string",
"Occupation": "string",
"AddressOfEmployer": "string",
"NoOfYearsInEmployment": "string",
"GrossAnnualIncome": "string"
},
"ProfitFromSoldOrMaturingInvestments": "https://example.com/callback",
"ProfitsFromPropertySale": "string",
"ProfitsFromSaleOfCompany": "string",
"CompensationPayment": "string",
"Pension": "string",
"Other": "string",
"FileUrls": [
"https://example.com/callback"
]
}'Parameters
userIdqueryintegerrequiredExample: 123Request fields and validation
CapitalOfCompany · string or null · requiredGiftOrInheritance · string or null · requiredProfessionalSalary · object or null · requiredProfitFromSoldOrMaturingInvestments · string or null · requiredProfitsFromPropertySale · string or null · requiredProfitsFromSaleOfCompany · string or null · requiredCompensationPayment · string or null · requiredPension · string or null · requiredOther · string or null · requiredFileUrls · array or null · requiredExample request body · replace placeholders
{
"CapitalOfCompany": "string",
"GiftOrInheritance": "string",
"ProfessionalSalary": {
"NameOfEmployer": "string",
"Occupation": "string",
"AddressOfEmployer": "string",
"NoOfYearsInEmployment": "string",
"GrossAnnualIncome": "string"
},
"ProfitFromSoldOrMaturingInvestments": "https://example.com/callback",
"ProfitsFromPropertySale": "string",
"ProfitsFromSaleOfCompany": "string",
"CompensationPayment": "string",
"Pension": "string",
"Other": "string",
"FileUrls": [
"https://example.com/callback"
]
}400Bad RequestVerificationErrorResponse
{
"message": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403ForbiddenProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}404Not FoundVerificationErrorResponse
{
"message": "string"
}409ConflictVerificationErrorResponse
{
"message": "string"
}502Bad GatewayVerificationErrorResponse
{
"message": "string"
}200OKExchangeVerificationStatus
{
"tier": "sdd",
"status": "approved",
"eligible": true,
"hasProviderAccount": true,
"usesSharedStagingOrganization": false,
"verificationType": "individual",
"provider": {
"status": "ready",
"kycStatus": "accepted",
"nextAction": null,
"verificationUrl": null,
"reason": null,
"actionSubmitted": false,
"cryptoDepositAccountReady": true,
"eurAccountReady": true
},
"applicationSupported": true,
"applicationUnavailableReason": null,
"businessOnboardingSupported": false
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
MOR23 operations
POST/api/v2/mor/public/kybSubmit or resubmit KYB for the API key's MoR merchant.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/kyb' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"CompanyName": "string",
"RegistrationNumber": "string",
"RegistrationCountry": "GB",
"Industry": "string",
"Website": "string",
"IncorporationDate": "2026-08-05",
"BusinessDescription": "Example description",
"AddressLine1": "string",
"AddressLine2": "string",
"City": "London",
"State": "string",
"Country": "GB",
"PostalCode": "SW1A 1AA",
"PhoneNumber": "+447700900123",
"PhoneCountryCode": "+447700900123",
"UboInformation": {
"UboFirstName": "Jane",
"UboLastName": "Doe",
"UboGender": "string",
"UboCountryCode": "GB",
"UboIdType": "string",
"UboIdNumber": "string",
"UboDob": "2026-08-05"
},
"Ubos": [
{
"FirstName": "Jane",
"LastName": "Doe",
"Dob": "2026-08-05",
"Nationality": "string",
"OwnershipPercentage": 100,
"IdNumber": "string",
"Gender": "string",
"CountryCode": "GB",
"IdType": "string"
}
]
}'Parameters
Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
CompanyName · string · requiredRegistrationNumber · string · requiredRegistrationCountry · string · requiredIndustry · string · requiredIncorporationDate · string or null · optionalWebsite · string · requiredBusinessDescription · string or null · optionalAddressLine1 · string or null · optionalAddressLine2 · string or null · optionalCity · string or null · optionalState · string or null · optionalCountry · string or null · optionalPostalCode · string or null · optionalPhoneNumber · string or null · optionalPhoneCountryCode · string or null · optionalUboInformation · object or null · optionalUbos · array or null · optionalExample request body · replace placeholders
{
"CompanyName": "string",
"RegistrationNumber": "string",
"RegistrationCountry": "GB",
"Industry": "string",
"Website": "string",
"IncorporationDate": "2026-08-05",
"BusinessDescription": "Example description",
"AddressLine1": "string",
"AddressLine2": "string",
"City": "London",
"State": "string",
"Country": "GB",
"PostalCode": "SW1A 1AA",
"PhoneNumber": "+447700900123",
"PhoneCountryCode": "+447700900123",
"UboInformation": {
"UboFirstName": "Jane",
"UboLastName": "Doe",
"UboGender": "string",
"UboCountryCode": "GB",
"UboIdType": "string",
"UboIdNumber": "string",
"UboDob": "2026-08-05"
},
"Ubos": [
{
"FirstName": "Jane",
"LastName": "Doe",
"Dob": "2026-08-05",
"Nationality": "string",
"OwnershipPercentage": 100,
"IdNumber": "string",
"Gender": "string",
"CountryCode": "GB",
"IdType": "string"
}
]
}400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
{
"id": 123,
"status": "PENDING",
"provider": "string",
"profileId": "string",
"interlaceAccountId": "string",
"rejectionReason": "string",
"submittedAt": "2026-08-05T09:30:00Z",
"reviewedAt": "2026-08-05T09:30:00Z",
"lastPolledAt": "2026-08-05T09:30:00Z",
"companyCardholderId": "string",
"companyCardholderStatus": "PENDING",
"companyCardholderCreatedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/mor/public/onboarding-statusGet the merchant onboarding status; optionally refresh it from Crypto cards.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request GET 'https://staging.hoppa.global/api/v2/mor/public/onboarding-status?refresh=false' \
-H 'x-api-key: YOUR_API_KEY'Parameters
refreshquerybooleanoptionalExample: false400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
{
"id": 123,
"status": "PENDING",
"provider": "string",
"profileId": "string",
"interlaceAccountId": "string",
"rejectionReason": "string",
"submittedAt": "2026-08-05T09:30:00Z",
"reviewedAt": "2026-08-05T09:30:00Z",
"lastPolledAt": "2026-08-05T09:30:00Z",
"companyCardholderId": "string",
"companyCardholderStatus": "PENDING",
"companyCardholderCreatedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/mor/public/cardholderCreate or return the merchant's company-level CORPORATE_MANAGED cardholder.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/cardholder' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"Dob": "2026-08-05"
}'Parameters
Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Example request body · replace placeholders
{
"Dob": "2026-08-05"
}400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
{
"cardholderId": "string",
"status": "PENDING",
"created": true,
"error": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/mor/public/usersAdd a user_simple to the API key's MoR company.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/users' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"Email": "user@example.com",
"FirstName": "Jane",
"LastName": "Doe",
"Phone": "+447700900123",
"Password": "string"
}'Parameters
Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
Email · string · requiredFirstName · string · requiredLastName · string · requiredPhone · string · requiredPassword · string · requiredExample request body · replace placeholders
{
"Email": "user@example.com",
"FirstName": "Jane",
"LastName": "Doe",
"Phone": "+447700900123",
"Password": "string"
}400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}201Createdapplication/json
{
"userId": 123,
"email": "user@example.com",
"firstName": "Jane",
"lastName": "Doe",
"phone": "+447700900123",
"invitationEmailSent": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/mor/public/cards/batchOrder 1-20 prepaid cards in a batch.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/cards/batch' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"CardTypeId": 123,
"Quantity": 1,
"AutoLockEnabled": true,
"LabelPrefix": "string"
}'Parameters
Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
CardTypeId · integer · optionalcard_type_tiers.id, same value used by dashboard cards/order.
Pattern: ^-?(?:0|[1-9]\d*)$
Quantity · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
AutoLockEnabled · boolean · optionalLabelPrefix · string or null · optionalExample request body · replace placeholders
{
"CardTypeId": 123,
"Quantity": 1,
"AutoLockEnabled": true,
"LabelPrefix": "string"
}400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}207Multi-Statusapplication/json
{
"success": true,
"requestedQuantity": 1,
"createdQuantity": 1,
"cards": [
{
"id": 123,
"externalCardId": "external_reference_123",
"status": "PENDING",
"cardType": "string",
"productName": "string",
"currency": "USD",
"availableBalance": 100,
"pendingBalance": 100,
"maskedCardNumber": "string",
"cardNumberLastFour": "string",
"cardholderName": "string",
"companyCardholderId": "string",
"assignedUserId": 123,
"assignedUserEmail": "user@example.com",
"assignedUserName": "string",
"isVirtual": true,
"isPhysical": true,
"isLocked": true,
"pendingLoadRequest": {
"id": 123,
"cardId": 123,
"requestedByUserId": 123,
"requestedByName": "string",
"requestedByEmail": "user@example.com",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"note": "string",
"adminEmailSent": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
},
"createdAt": "2026-08-05T09:30:00Z"
}
],
"errors": [
"string"
]
}200OKapplication/json
{
"success": true,
"requestedQuantity": 1,
"createdQuantity": 1,
"cards": [
{
"id": 123,
"externalCardId": "external_reference_123",
"status": "PENDING",
"cardType": "string",
"productName": "string",
"currency": "USD",
"availableBalance": 100,
"pendingBalance": 100,
"maskedCardNumber": "string",
"cardNumberLastFour": "string",
"cardholderName": "string",
"companyCardholderId": "string",
"assignedUserId": 123,
"assignedUserEmail": "user@example.com",
"assignedUserName": "string",
"isVirtual": true,
"isPhysical": true,
"isLocked": true,
"pendingLoadRequest": {
"id": 123,
"cardId": 123,
"requestedByUserId": 123,
"requestedByName": "string",
"requestedByEmail": "user@example.com",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"note": "string",
"adminEmailSent": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
},
"createdAt": "2026-08-05T09:30:00Z"
}
],
"errors": [
"string"
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/mor/public/cards/{cardId}/assignAssign a merchant-owned card to a user_simple in the same company.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/cards/123/assign' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"AssignedUserId": 123
}'Parameters
cardIdpathintegerrequiredExample: 123Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
AssignedUserId · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"AssignedUserId": 123
}400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
{
"id": 123,
"externalCardId": "external_reference_123",
"status": "PENDING",
"cardType": "string",
"productName": "string",
"currency": "USD",
"availableBalance": 100,
"pendingBalance": 100,
"maskedCardNumber": "string",
"cardNumberLastFour": "string",
"cardholderName": "string",
"companyCardholderId": "string",
"assignedUserId": 123,
"assignedUserEmail": "user@example.com",
"assignedUserName": "string",
"isVirtual": true,
"isPhysical": true,
"isLocked": true,
"pendingLoadRequest": {
"id": 123,
"cardId": 123,
"requestedByUserId": 123,
"requestedByName": "string",
"requestedByEmail": "user@example.com",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"note": "string",
"adminEmailSent": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
},
"createdAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/mor/public/cards/{cardId}/loadLoad a merchant-owned card from the merchant's Crypto cards account.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/cards/123/load' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"Amount": 100
}'Parameters
cardIdpathintegerrequiredExample: 123Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
Amount · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Example request body · replace placeholders
{
"Amount": 100
}400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
{
"card": {
"id": 123,
"externalCardId": "external_reference_123",
"status": "PENDING",
"cardType": "string",
"productName": "string",
"currency": "USD",
"availableBalance": 100,
"pendingBalance": 100,
"maskedCardNumber": "string",
"cardNumberLastFour": "string",
"cardholderName": "string",
"companyCardholderId": "string",
"assignedUserId": 123,
"assignedUserEmail": "user@example.com",
"assignedUserName": "string",
"isVirtual": true,
"isPhysical": true,
"isLocked": true,
"pendingLoadRequest": {
"id": 123,
"cardId": 123,
"requestedByUserId": 123,
"requestedByName": "string",
"requestedByEmail": "user@example.com",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"note": "string",
"adminEmailSent": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
},
"createdAt": "2026-08-05T09:30:00Z"
},
"grossAmount": 100,
"netAmount": 100,
"feeAmount": 100,
"transferAmount": 100,
"merchantAccountDelta": 100,
"feeCurrency": "USD"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/mor/public/cards/{cardId}/unloadUnload a merchant-owned card to the merchant's Crypto cards account.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/cards/123/unload' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"Amount": 100
}'Parameters
cardIdpathintegerrequiredExample: 123Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
Amount · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Example request body · replace placeholders
{
"Amount": 100
}400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
{
"card": {
"id": 123,
"externalCardId": "external_reference_123",
"status": "PENDING",
"cardType": "string",
"productName": "string",
"currency": "USD",
"availableBalance": 100,
"pendingBalance": 100,
"maskedCardNumber": "string",
"cardNumberLastFour": "string",
"cardholderName": "string",
"companyCardholderId": "string",
"assignedUserId": 123,
"assignedUserEmail": "user@example.com",
"assignedUserName": "string",
"isVirtual": true,
"isPhysical": true,
"isLocked": true,
"pendingLoadRequest": {
"id": 123,
"cardId": 123,
"requestedByUserId": 123,
"requestedByName": "string",
"requestedByEmail": "user@example.com",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"note": "string",
"adminEmailSent": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
},
"createdAt": "2026-08-05T09:30:00Z"
},
"grossAmount": 100,
"netAmount": 100,
"feeAmount": 100,
"transferAmount": 100,
"merchantAccountDelta": 100,
"feeCurrency": "USD"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/mor/public/cardsGet all merchant cards with their current available and pending balances.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request GET 'https://staging.hoppa.global/api/v2/mor/public/cards' \
-H 'x-api-key: YOUR_API_KEY'400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
[
{
"id": 123,
"externalCardId": "external_reference_123",
"status": "PENDING",
"cardType": "string",
"productName": "string",
"currency": "USD",
"availableBalance": 100,
"pendingBalance": 100,
"maskedCardNumber": "string",
"cardNumberLastFour": "string",
"cardholderName": "string",
"companyCardholderId": "string",
"assignedUserId": 123,
"assignedUserEmail": "user@example.com",
"assignedUserName": "string",
"isVirtual": true,
"isPhysical": true,
"isLocked": true,
"pendingLoadRequest": {
"id": 123,
"cardId": 123,
"requestedByUserId": 123,
"requestedByName": "string",
"requestedByEmail": "user@example.com",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"note": "string",
"adminEmailSent": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
},
"createdAt": "2026-08-05T09:30:00Z"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/mor/public/users/{userId}/cardsGet one user_simple's assigned cards and aggregate card balances.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request GET 'https://staging.hoppa.global/api/v2/mor/public/users/123/cards' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
{
"userId": 123,
"cards": [
{
"id": 123,
"externalCardId": "external_reference_123",
"status": "PENDING",
"cardType": "string",
"productName": "string",
"currency": "USD",
"availableBalance": 100,
"pendingBalance": 100,
"maskedCardNumber": "string",
"cardNumberLastFour": "string",
"cardholderName": "string",
"companyCardholderId": "string",
"assignedUserId": 123,
"assignedUserEmail": "user@example.com",
"assignedUserName": "string",
"isVirtual": true,
"isPhysical": true,
"isLocked": true,
"pendingLoadRequest": {
"id": 123,
"cardId": 123,
"requestedByUserId": 123,
"requestedByName": "string",
"requestedByEmail": "user@example.com",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"note": "string",
"adminEmailSent": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
},
"createdAt": "2026-08-05T09:30:00Z"
}
],
"totalAvailableBalance": 100,
"totalPendingBalance": 100
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/mor/public/cards/{cardId}/secure-widgetGet a secure hosted card-information widget.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present. Returns widgetToken, widgetUrl and expiresIn (currently 300 seconds). The hosted URL remains supported for the reference app; never cache or log either credential. Provider single-use/origin restrictions are not guaranteed by this endpoint.
curl --request GET 'https://staging.hoppa.global/api/v2/mor/public/cards/123/secure-widget' \
-H 'x-api-key: YOUR_API_KEY'Parameters
cardIdpathintegerrequiredExample: 123400Bad Requestapplication/json
{
"success": true,
"widgetUrl": "https://example.com/callback",
"widgetToken": "string",
"expiresIn": 1,
"errorCode": "string",
"errorMessage": "string",
"cardId": 123,
"config": {
"primaryColor": "string",
"backgroundColor": "string",
"textColor": "string",
"width": "string",
"height": "string"
}
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
{
"success": true,
"widgetUrl": "https://example.com/callback",
"widgetToken": "string",
"expiresIn": 1,
"errorCode": "string",
"errorMessage": "string",
"cardId": 123,
"config": {
"primaryColor": "string",
"backgroundColor": "string",
"textColor": "string",
"width": "string",
"height": "string"
}
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/mor/public/walletsGet merchant wallets, deposit addresses, and fiat/crypto balances.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request GET 'https://staging.hoppa.global/api/v2/mor/public/wallets' \
-H 'x-api-key: YOUR_API_KEY'400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
{
"balances": {
"cryptoAssets": [
{
"id": 123,
"token": "USDC",
"balance": 100,
"usdValue": 100,
"walletAddress": "0x1111111111111111111111111111111111111111",
"network": "string",
"status": "PENDING",
"isDefault": true,
"externalId": "external_reference_123",
"walletType": "string",
"lastUpdated": "2026-08-05T09:30:00Z"
}
],
"quantumWallets": [
{
"id": 123,
"walletAddress": "0x1111111111111111111111111111111111111111",
"tokenSymbol": "string",
"network": "string",
"balance": 100,
"usdValue": 100,
"status": "PENDING",
"isDefault": true,
"lastUpdated": "2026-08-05T09:30:00Z",
"walletType": "string",
"externalId": "external_reference_123"
}
],
"isSufficientBalance": true,
"walletSufficiency": {
"FIELD_FROM_APPLICATION": true
},
"totalUsdValue": 100,
"lastUpdated": "2026-08-05T09:30:00Z",
"totalAvailableUSDT": 100,
"totalAvailableUSDC": 100
},
"wallets": {
"wallets": [
{
"id": 123,
"walletAddress": "0x1111111111111111111111111111111111111111",
"tokenSymbol": "string",
"network": "string",
"balance": 100,
"usdValue": 100,
"status": "PENDING",
"provider": "string",
"walletType": "string",
"isDefault": true,
"isPrimary": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z",
"externalWalletId": "external_reference_123",
"onlyDeposit": true
}
],
"totalCount": 1,
"lastRefreshed": "2026-08-05T09:30:00Z",
"refreshSuccessful": true,
"errorMessage": "string",
"walletOutflowsEnabled": true,
"enabledCryptoAssets": [
"string"
],
"disabledCryptoAddresses": [
"0x1111111111111111111111111111111111111111"
]
}
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/mor/public/companiesList only the MoR child companies belonging to the API key's company.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request GET 'https://staging.hoppa.global/api/v2/mor/public/companies' \
-H 'x-api-key: YOUR_API_KEY'400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
[
{
"companyId": 123,
"name": "string",
"tierId": 123,
"tierName": "string",
"kybStatus": "PENDING",
"kybProfileId": "string",
"createdAt": "2026-08-05T09:30:00Z"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/mor/public/companiesProvision a MoR child company and its admin using a company's API key with MoR enabled.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/companies' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"CompanyName": "string",
"LegalName": "string",
"AdminEmail": "user@example.com",
"AdminFirstName": "Jane",
"AdminLastName": "Doe",
"AdminPassword": "string",
"RegistrationNumber": "string",
"Country": "GB",
"TierId": 123
}'Parameters
Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
CompanyName · string · requiredLegalName · string · requiredRegistrationNumber · string or null · optionalCountry · string or null · optionalAdminEmail · string · requiredAdminFirstName · string · requiredAdminLastName · string · requiredAdminPassword · string · requiredTierId · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"CompanyName": "string",
"LegalName": "string",
"AdminEmail": "user@example.com",
"AdminFirstName": "Jane",
"AdminLastName": "Doe",
"AdminPassword": "string",
"RegistrationNumber": "string",
"Country": "GB",
"TierId": 123
}400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}201Createdapplication/json
{
"companyId": 123,
"adminUserId": 123,
"adminEmail": "user@example.com"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/mor/public/companies/merchant-tiersList active business Crypto cards tiers available for provisioning under the API key's company.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request GET 'https://staging.hoppa.global/api/v2/mor/public/companies/merchant-tiers' \
-H 'x-api-key: YOUR_API_KEY'400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
[
{
"tierId": 123,
"name": "string",
"description": "Example description",
"tierLevel": 1,
"monthlyFee": 100,
"yearlyFee": 100,
"virtualCardProductCount": 1
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/mor/public/transactionsList the API key's merchant transactions, with pagination and optional user, status, and type filters.Request & responses +
Page defaults to 1 and is clamped to at least 1. Page size defaults to 25 and is clamped to 1–100. Statistics, transaction types, and user options describe the entire merchant, independently of filters. Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present. pageSize/limit is capped at 100. feeAmount/feeCurrency contain recorded charges when available; null means unknown, not free.
curl --request GET 'https://staging.hoppa.global/api/v2/mor/public/transactions?page=1&pageSize=25&userId=123&status=PENDING&type=example' \
-H 'x-api-key: YOUR_API_KEY'Parameters
pagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 25userIdqueryintegeroptionalExample: 123statusquerystringoptionalExample: PENDINGtypequerystringoptionalExample: example400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
{
"data": [
{
"id": 123,
"userId": 123,
"userName": "string",
"userEmail": "user@example.com",
"userRole": "string",
"companyId": 123,
"accountId": 123,
"cardId": 123,
"transactionType": "string",
"amount": "100.00",
"currency": "USD",
"status": "PENDING",
"description": "Example description",
"externalTransactionId": "external_reference_123",
"transactionDate": "2026-08-05T09:30:00Z",
"createdAt": "2026-08-05T09:30:00Z",
"merchantName": "string",
"mcc": "string",
"feeAmount": 100,
"feeCurrency": "USD"
}
],
"pagination": {
"page": 1,
"pageSize": 1,
"total": 1,
"totalPages": 1
},
"stats": {
"totalTransactions": 1,
"countByStatus": {
"FIELD_FROM_APPLICATION": 1
}
},
"transactionTypes": [
"string"
],
"users": [
{
"userId": 123,
"name": "string",
"email": "user@example.com",
"role": "string"
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/mor/public/cards/analyticsGet the API key's merchant card portfolio and daily usage analytics.Request & responses +
Days defaults to 30 and is clamped to 7–90. Balances use stored values; spend totals include successful USD card payments. Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request GET 'https://staging.hoppa.global/api/v2/mor/public/cards/analytics?days=30' \
-H 'x-api-key: YOUR_API_KEY'Parameters
daysqueryintegeroptionalExample: 30400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
{
"periodDays": 1,
"generatedAt": "2026-08-05T09:30:00Z",
"totalCards": 1,
"activeCards": 1,
"cancelledCards": 1,
"assignedCards": 1,
"unassignedCards": 1,
"cardsUsedInPeriod": 1,
"transactionCount": 1,
"totalAvailableBalance": 100,
"totalPendingBalance": 100,
"totalSpendUsd": 100,
"averageTransactionUsd": 100,
"dailyUsage": [
{
"date": "2026-08-05T09:30:00Z",
"transactionCount": 1,
"uniqueCards": 1,
"spendUsd": 100
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/mor/public/cards/{cardId}/unassignRemove a user assignment from a merchant-owned card and cancel its pending load requests.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/cards/123/unassign' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001'Parameters
cardIdpathintegerrequiredExample: 123Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
{
"id": 123,
"externalCardId": "external_reference_123",
"status": "PENDING",
"cardType": "string",
"productName": "string",
"currency": "USD",
"availableBalance": 100,
"pendingBalance": 100,
"maskedCardNumber": "string",
"cardNumberLastFour": "string",
"cardholderName": "string",
"companyCardholderId": "string",
"assignedUserId": 123,
"assignedUserEmail": "user@example.com",
"assignedUserName": "string",
"isVirtual": true,
"isPhysical": true,
"isLocked": true,
"pendingLoadRequest": {
"id": 123,
"cardId": 123,
"requestedByUserId": 123,
"requestedByName": "string",
"requestedByEmail": "user@example.com",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"note": "string",
"adminEmailSent": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
},
"createdAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/mor/public/cards/availableList the card products available to the API key's merchant.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request GET 'https://staging.hoppa.global/api/v2/mor/public/cards/available' \
-H 'x-api-key: YOUR_API_KEY'400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
[
{
"cardTypeId": 123,
"tierId": 123,
"tierName": "string",
"tierLevel": 1,
"name": "string",
"description": "Example description",
"currencyCode": "USD",
"issuanceFee": 100,
"monthlySubscriptionFee": 100,
"yearlySubscriptionFee": 100,
"isVirtual": true,
"isPhysical": true,
"cardNetwork": "string",
"cardImageUrl": "https://example.com/callback",
"cardPreviewUrl": "https://example.com/callback",
"cardBackImageUrl": "https://example.com/callback",
"cardBackPreviewUrl": "https://example.com/callback",
"cardTextColor": "string",
"provider": "string",
"maxCards": 1
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/mor/public/cards/{cardId}/cancelPermanently cancel a merchant-owned Crypto cards.Request & responses +
Available, pending, and frozen provider balances must all be zero. Repeating cancellation of an already cancelled card succeeds without deleting it again. Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/cards/123/cancel' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001'Parameters
cardIdpathintegerrequiredExample: 123Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
{
"success": true,
"message": "string",
"card": {
"id": 123,
"externalCardId": "external_reference_123",
"status": "PENDING",
"cardType": "string",
"productName": "string",
"currency": "USD",
"availableBalance": 100,
"pendingBalance": 100,
"maskedCardNumber": "string",
"cardNumberLastFour": "string",
"cardholderName": "string",
"companyCardholderId": "string",
"assignedUserId": 123,
"assignedUserEmail": "user@example.com",
"assignedUserName": "string",
"isVirtual": true,
"isPhysical": true,
"isLocked": true,
"pendingLoadRequest": {
"id": 123,
"cardId": 123,
"requestedByUserId": 123,
"requestedByName": "string",
"requestedByEmail": "user@example.com",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"note": "string",
"adminEmailSent": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
},
"createdAt": "2026-08-05T09:30:00Z"
}
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/mor/public/cards/pageList a bounded page of merchant cards using stored balances. The original GET /cards remains unchanged.Request & responses +
Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present. Page defaults to 1 and pageSize to 25, clamped to 1–100. Data uses stored balances; GET /cards retains the existing full-list refresh behavior.
curl --request GET 'https://staging.hoppa.global/api/v2/mor/public/cards/page?page=1&pageSize=25&assignedUserId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
pagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 25assignedUserIdqueryintegeroptionalExample: 123400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
{
"data": [
{
"id": 123,
"externalCardId": "external_reference_123",
"status": "PENDING",
"cardType": "string",
"productName": "string",
"currency": "USD",
"availableBalance": 100,
"pendingBalance": 100,
"maskedCardNumber": "string",
"cardNumberLastFour": "string",
"cardholderName": "string",
"companyCardholderId": "string",
"assignedUserId": 123,
"assignedUserEmail": "user@example.com",
"assignedUserName": "string",
"isVirtual": true,
"isPhysical": true,
"isLocked": true,
"pendingLoadRequest": {
"id": 123,
"cardId": 123,
"requestedByUserId": 123,
"requestedByName": "string",
"requestedByEmail": "user@example.com",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"note": "string",
"adminEmailSent": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
},
"createdAt": "2026-08-05T09:30:00Z"
}
],
"pagination": {
"page": 1,
"pageSize": 1,
"total": 1,
"totalPages": 1
},
"balanceSource": "100.00"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/mor/public/users/{userId}/cards/{cardId}/transactionsGet transaction history for a card currently assigned to a user_simple in the API key's merchant.Request & responses +
Limit defaults to 50 and is clamped to 1–100; offset defaults to 0 and is clamped to at least 0. The existing simple-user service verifies both merchant ownership and the current user assignment. Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present. pageSize/limit is capped at 100. feeAmount/feeCurrency contain recorded charges when available; null means unknown, not free.
curl --request GET 'https://staging.hoppa.global/api/v2/mor/public/users/123/cards/123/transactions?limit=50&offset=0' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123cardIdpathintegerrequiredExample: 123limitqueryintegeroptionalExample: 50offsetqueryintegeroptionalExample: 0400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
{
"data": [
{
"id": 123,
"cardId": 123,
"transactionType": "string",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"description": "Example description",
"merchantName": "string",
"category": "string",
"externalTransactionId": "external_reference_123",
"transactionDate": "2026-08-05T09:30:00Z",
"feeAmount": 100,
"feeCurrency": "USD"
}
],
"total": 1,
"limit": 1,
"offset": 1
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/mor/public/users/{userId}/cards/{cardId}/load-requestsCreate or update a load request for a card currently assigned to a user_simple in the API key's merchant.Request & responses +
Records a request and attempts to notify the merchant admin; it does not fund the card. Amount is rounded to two decimal places and must then be between 0.01 and 250000. Note is optional and limited to 500 characters after trimming. An existing pending request is updated. Company scope comes exclusively from the current API key. MOR success and business-error properties use camelCase. Validation may return application/problem+json; authentication may return plain text. The existing sensitive-operation 429 body uses Message, Code and Status. 429 means the configured request limit was exceeded; honor Retry-After when present.
curl --request POST 'https://staging.hoppa.global/api/v2/mor/public/users/123/cards/123/load-requests' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"Amount": 100,
"Note": "string"
}'Parameters
userIdpathintegerrequiredExample: 123cardIdpathintegerrequiredExample: 123Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
Amount · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Note · string or null · optionalExample request body · replace placeholders
{
"Amount": 100,
"Note": "string"
}400Bad Requestapplication/json
{
"message": "string",
"code": "string"
}401Unauthorizedapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}403Forbiddenapplication/json
{
"message": "string",
"code": "string"
}404Not Foundapplication/json
{
"message": "string",
"code": "string"
}409Conflictapplication/json
{
"message": "string",
"code": "string"
}429Too Many Requestsapplication/json
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
{
"message": "string",
"code": "string"
}503Service Unavailableapplication/json
{
"message": "string",
"code": "string"
}200OKapplication/json
{
"id": 123,
"cardId": 123,
"requestedByUserId": 123,
"requestedByName": "string",
"requestedByEmail": "user@example.com",
"amount": 100,
"currency": "USD",
"status": "PENDING",
"note": "string",
"adminEmailSent": true,
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
Payments13 operations
POST/api/v2/payments/createCreate a payment with automatic currency exchange and transferRequest & responses +
Use the existing optional merchantReferenceId as a stable collection reference within the company/user. Repeating it returns the recorded operation without redispatch, including after a one-time mandate was consumed. Changing amount, currency or an explicitly supplied mandateId returns 400 VALIDATION_ERROR. Without a reference, each call creates a new collection. Returned pending/unknown provider outcomes return HTTP 200 with status processing; confirmed completion returns success and definite rejection failed. Transport errors/timeouts may still return 500 INTERNAL_SERVER_ERROR while retaining the operation and allowance: keep the same reference and reconcile its outcome. Mandate allowance is reserved before provider dispatch across payment collections and user-to-master transfers. Outstanding, uncertain and completed collections count toward the period allowance. A one-time mandate allows one outstanding/completed collection; definite no-debit outcomes release the reservation. Unresolved historical operations also count.
curl --request POST 'https://staging.hoppa.global/api/v2/payments/create' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"Amount": "100.00",
"Currency": "USD",
"Description": "Example description",
"MerchantReferenceId": "external_reference_123",
"MandateId": 123,
"Metadata": {}
}'Request fields and validation
UserId · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
Amount · string · requiredCurrency · string · requiredDescription · string or null · optionalMerchantReferenceId · string or null · optionalOptional stable collection reference within company/user. Reuse it for the same operation; conflicting amount, currency or explicit mandateId returns 400 VALIDATION_ERROR. Omission creates a new collection per call.
MandateId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
Metadata · object or null · optionalExample request body · replace placeholders
{
"UserId": 123,
"Amount": "100.00",
"Currency": "USD",
"Description": "Example description",
"MerchantReferenceId": "external_reference_123",
"MandateId": 123,
"Metadata": {}
}200Recorded payment outcome. status is success only on confirmed completion; returned pending/unknown provider outcomes are processing, and definite rejection is failed.PaymentResponseV2
{
"Id": 123,
"Status": "PENDING",
"Message": "string",
"TransactionId": 123,
"TransferId": "string",
"ExchangeQuote": {
"FromCurrency": "USD",
"ToCurrency": "USD",
"FromAmount": "100.00",
"ToAmount": "100.00",
"ExchangeRate": "string",
"Fee": "100.00"
},
"ExchangeTradeId": "string",
"RequiredAmount": "100.00",
"AvailableAmount": "100.00",
"Shortfall": "string",
"TransakOrder": {
"OrderId": "string",
"RedirectUrl": "https://example.com/callback",
"WidgetUrl": "https://example.com/callback",
"Status": "PENDING",
"Amount": "100.00",
"Currency": "USD",
"CryptoAmount": "100.00",
"CryptoCurrency": "USDC"
},
"Amount": "100.00",
"Currency": "USD",
"UserId": 123,
"CompanyId": 123,
"MandateId": 123,
"CreatedAt": "2026-08-05T09:30:00Z"
}400Invalid terms/mandate or a reused merchantReferenceId with conflicting amount, currency or explicit mandate: VALIDATION_ERROR or INVALID_OPERATION.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500INTERNAL_SERVER_ERROR. A provider transport error may leave an uncertain recorded operation; reconcile or retry with the original merchantReferenceId.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}403UNAUTHORIZED_ACCESS: the caller cannot collect for the selected user.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/payments/mandatesList payment mandates with filtering and paginationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/payments/mandates?pageNumber=1&pageSize=10&userId=123&status=PENDING¤cy=USD&dateFrom=2026-08-05' \
-H 'x-api-key: YOUR_API_KEY'Parameters
pageNumberqueryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 10userIdqueryintegeroptionalExample: 123statusqueryMandateStatusV2optionalExample: PENDINGcurrencyquerystringoptionalExample: USDdateFromquerystringoptionalExample: 2026-08-05dateToquerystringoptionalExample: 2026-08-05200OKPaymentMandateListResponseV2
{
"Mandates": [
{
"Id": 123,
"UserId": 123,
"CompanyId": 123,
"MaxAmount": "100.00",
"Currency": "USD",
"Frequency": "ONE_TIME",
"Status": "PENDING",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"StartDate": "2026-08-05",
"EndDate": "2026-08-05",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}
],
"Total": 1,
"PageNumber": 1,
"PageSize": 1,
"TotalPages": 1
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/payments/mandatesCreate a payment mandateRequest & responses +
Mandate allowance is reserved before provider dispatch across payment collections and user-to-master transfers. Outstanding, uncertain and completed collections count toward the period allowance. A one-time mandate allows one outstanding/completed collection; definite no-debit outcomes release the reservation. Unresolved historical operations also count.
curl --request POST 'https://staging.hoppa.global/api/v2/payments/mandates' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"MaxAmount": "100.00",
"Currency": "USD",
"Frequency": "ONE_TIME",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"StartDate": "2026-08-05",
"EndDate": "2026-08-05",
"Metadata": {}
}'Request fields and validation
UserId · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
MaxAmount · string · requiredMandate allowance is reserved before provider dispatch across payment collections and user-to-master transfers. Outstanding, uncertain and completed collections count toward the period allowance. A one-time mandate allows one outstanding/completed collection; definite no-debit outcomes release the reservation. Unresolved historical operations also count.
Currency · string · requiredFrequency · value · optionalAllowed: ONE_TIME, DAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLY
Description · string or null · optionalExternalReferenceId · string or null · optionalStartDate · string or null · optionalEndDate · string or null · optionalMetadata · object or null · optionalExample request body · replace placeholders
{
"UserId": 123,
"MaxAmount": "100.00",
"Currency": "USD",
"Frequency": "ONE_TIME",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"StartDate": "2026-08-05",
"EndDate": "2026-08-05",
"Metadata": {}
}201CreatedPaymentMandateResponseV2
{
"Id": 123,
"UserId": 123,
"CompanyId": 123,
"MaxAmount": "100.00",
"Currency": "USD",
"Frequency": "ONE_TIME",
"Status": "PENDING",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"StartDate": "2026-08-05",
"EndDate": "2026-08-05",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}403UNAUTHORIZED_ACCESS: JWT caller cannot create a mandate for another user.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/payments/mandates/{mandateId}Get payment mandate by IDRequest & responses +
Company API keys can read a mandate within their company. JWT callers must own the mandate; inaccessible objects return the same 404 as missing objects.
curl --request GET 'https://staging.hoppa.global/api/v2/payments/mandates/123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
mandateIdpathintegerrequiredExample: 123200OKPaymentMandateResponseV2
{
"Id": 123,
"UserId": 123,
"CompanyId": 123,
"MaxAmount": "100.00",
"Currency": "USD",
"Frequency": "ONE_TIME",
"Status": "PENDING",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"StartDate": "2026-08-05",
"EndDate": "2026-08-05",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}404MANDATE_NOT_FOUND: missing or inaccessible mandate.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/payments/mandates/{mandateId}/revokeRevoke a payment mandateRequest & responses +
Company API keys retain company-scoped access. JWT callers must own the mandate to revoke it.
curl --request PUT 'https://staging.hoppa.global/api/v2/payments/mandates/123/revoke' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Reason": "string"
}'Parameters
mandateIdpathintegerrequiredExample: 123Request fields and validation
Reason · string or null · optionalExample request body · replace placeholders
{
"Reason": "string"
}200OKPaymentMandateResponseV2
{
"Id": 123,
"UserId": 123,
"CompanyId": 123,
"MaxAmount": "100.00",
"Currency": "USD",
"Frequency": "ONE_TIME",
"Status": "PENDING",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"StartDate": "2026-08-05",
"EndDate": "2026-08-05",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}403UNAUTHORIZED_ACCESS: JWT caller cannot revoke another user's mandate.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/payments/requestsList payment requests with filtering and paginationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/payments/requests?pageNumber=1&pageSize=10&userId=123&status=PENDING¤cy=USD&dateFrom=2026-08-05' \
-H 'x-api-key: YOUR_API_KEY'Parameters
pageNumberqueryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 10userIdqueryintegeroptionalExample: 123statusqueryPaymentStatusV2optionalExample: PENDINGcurrencyquerystringoptionalExample: USDdateFromquerystringoptionalExample: 2026-08-05dateToquerystringoptionalExample: 2026-08-05200OKPaymentRequestListResponseV2
{
"PaymentRequests": [
{
"Id": 123,
"UserId": 123,
"CompanyId": 123,
"Amount": "100.00",
"Currency": "USD",
"Status": "PENDING",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"CallbackUrl": "https://example.com/callback",
"SuccessUrl": "https://example.com/callback",
"FailureUrl": "https://example.com/callback",
"PaymentUrl": "https://example.com/callback",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}
],
"Total": 1,
"PageNumber": 1,
"PageSize": 1,
"TotalPages": 1
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/payments/requestsCreate a payment requestRequest & responses +
Company API keys can create a request for a user in their company. For JWT callers, body userId must equal the authenticated user.
curl --request POST 'https://staging.hoppa.global/api/v2/payments/requests' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"Amount": "100.00",
"Currency": "USD",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"CallbackUrl": "https://example.com/callback",
"SuccessUrl": "https://example.com/callback",
"FailureUrl": "https://example.com/callback",
"Metadata": {}
}'Request fields and validation
UserId · integer · requiredSelected user in the API key's company. For JWT requests, this must match the authenticated user or the API returns 403 UNAUTHORIZED_ACCESS.
Pattern: ^-?(?:0|[1-9]\d*)$
Amount · string · requiredCurrency · string · requiredDescription · string or null · optionalExternalReferenceId · string or null · optionalCallbackUrl · string or null · optionalSuccessUrl · string or null · optionalFailureUrl · string or null · optionalMetadata · object or null · optionalExample request body · replace placeholders
{
"UserId": 123,
"Amount": "100.00",
"Currency": "USD",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"CallbackUrl": "https://example.com/callback",
"SuccessUrl": "https://example.com/callback",
"FailureUrl": "https://example.com/callback",
"Metadata": {}
}201CreatedPaymentRequestResponseV2
{
"Id": 123,
"UserId": 123,
"CompanyId": 123,
"Amount": "100.00",
"Currency": "USD",
"Status": "PENDING",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"CallbackUrl": "https://example.com/callback",
"SuccessUrl": "https://example.com/callback",
"FailureUrl": "https://example.com/callback",
"PaymentUrl": "https://example.com/callback",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}403UNAUTHORIZED_ACCESS: JWT body userId differs from the authenticated user.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404USER_NOT_FOUND: selected user is missing or outside the company.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/payments/requests/{requestId}Get payment request by IDRequest & responses +
Company API keys retain company-scoped access. A JWT subject must be the request user, requester or payer; other users' requests are hidden with 404 PAYMENT_REQUEST_NOT_FOUND.
curl --request GET 'https://staging.hoppa.global/api/v2/payments/requests/123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
requestIdpathintegerrequiredExample: 123200OKPaymentRequestResponseV2
{
"Id": 123,
"UserId": 123,
"CompanyId": 123,
"Amount": "100.00",
"Currency": "USD",
"Status": "PENDING",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"CallbackUrl": "https://example.com/callback",
"SuccessUrl": "https://example.com/callback",
"FailureUrl": "https://example.com/callback",
"PaymentUrl": "https://example.com/callback",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}404PAYMENT_REQUEST_NOT_FOUND: missing or inaccessible payment request.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/payments/requests/{requestId}/cancelCancel a payment requestRequest & responses +
Company API keys retain company-scoped access. A JWT subject must be the request user, requester or payer; other users' requests are hidden with 404 PAYMENT_REQUEST_NOT_FOUND. Only pending requests can be cancelled, for both JWT and API-key callers.
curl --request PUT 'https://staging.hoppa.global/api/v2/payments/requests/123/cancel' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Reason": "string"
}'Parameters
requestIdpathintegerrequiredExample: 123Request fields and validation
Reason · string or null · optionalExample request body · replace placeholders
{
"Reason": "string"
}200OKPaymentRequestResponseV2
{
"Id": 123,
"UserId": 123,
"CompanyId": 123,
"Amount": "100.00",
"Currency": "USD",
"Status": "PENDING",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"CallbackUrl": "https://example.com/callback",
"SuccessUrl": "https://example.com/callback",
"FailureUrl": "https://example.com/callback",
"PaymentUrl": "https://example.com/callback",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}404PAYMENT_REQUEST_NOT_FOUND: missing or inaccessible payment request.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}409PAYMENT_REQUEST_NOT_PENDING: an accessible request is already processing, completed or cancelled.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/payments/payoutsCreate a payoutRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/payments/payouts' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"Amount": "100.00",
"Currency": "USD",
"DestinationAddress": "0x1111111111111111111111111111111111111111",
"DestinationTag": "string",
"Network": "string",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"Metadata": {}
}'Request fields and validation
UserId · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
Amount · string · requiredCurrency · string · requiredDestinationAddress · string · requiredDestinationTag · string or null · optionalNetwork · string or null · optionalDescription · string or null · optionalExternalReferenceId · string or null · optionalMetadata · object or null · optionalExample request body · replace placeholders
{
"UserId": 123,
"Amount": "100.00",
"Currency": "USD",
"DestinationAddress": "0x1111111111111111111111111111111111111111",
"DestinationTag": "string",
"Network": "string",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"Metadata": {}
}201CreatedPayoutResponseV2
{
"Id": 123,
"UserId": 123,
"CompanyId": 123,
"Amount": "100.00",
"Currency": "USD",
"DestinationAddress": "0x1111111111111111111111111111111111111111",
"DestinationTag": "string",
"Network": "string",
"Status": "PENDING",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"TransactionId": "string",
"TransactionHash": "string",
"Fee": "100.00",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}501Not ImplementedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/payments/withdrawals/feeGet withdrawal fee estimateRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/payments/withdrawals/fee' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Currency": "USD",
"Amount": "100.00",
"Chain": "string",
"Network": "string",
"DestinationAddress": "0x1111111111111111111111111111111111111111"
}'Request fields and validation
Currency · string · requiredAmount · string · requiredChain · string · requiredNetwork · string or null · optionalDestinationAddress · string or null · optionalExample request body · replace placeholders
{
"Currency": "USD",
"Amount": "100.00",
"Chain": "string",
"Network": "string",
"DestinationAddress": "0x1111111111111111111111111111111111111111"
}200OKWithdrawalFeeResponseV2
{
"Currency": "USD",
"Amount": "100.00",
"Fee": "100.00",
"NetAmount": "100.00",
"Network": "string",
"EstimatedConfirmationTime": "string"
}501Not ImplementedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/payments/withdrawalsCreate a withdrawalRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/payments/withdrawals' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Amount": "100.00",
"Currency": "USD",
"Chain": "string",
"DestinationAddress": "0x1111111111111111111111111111111111111111",
"UserId": 123,
"DestinationTag": "string",
"Network": "string",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"Metadata": {}
}'Request fields and validation
UserId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
Amount · string · requiredCurrency · string · requiredChain · string · requiredDestinationAddress · string · requiredDestinationTag · string or null · optionalNetwork · string or null · optionalDescription · string or null · optionalExternalReferenceId · string or null · optionalMetadata · object or null · optionalExample request body · replace placeholders
{
"Amount": "100.00",
"Currency": "USD",
"Chain": "string",
"DestinationAddress": "0x1111111111111111111111111111111111111111",
"UserId": 123,
"DestinationTag": "string",
"Network": "string",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"Metadata": {}
}201CreatedPayoutResponseV2
{
"Id": 123,
"UserId": 123,
"CompanyId": 123,
"Amount": "100.00",
"Currency": "USD",
"DestinationAddress": "0x1111111111111111111111111111111111111111",
"DestinationTag": "string",
"Network": "string",
"Status": "PENDING",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"TransactionId": "string",
"TransactionHash": "string",
"Fee": "100.00",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}501Not ImplementedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/payments/assets/co-brandGet co-brand assetsRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/payments/assets/co-brand?companyId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
companyIdqueryintegeroptionalExample: 123200OKUserAssetsResponseV2
{
"UserId": 123,
"Assets": [
{
"Id": 123,
"Currency": "USD",
"Balance": "100.00",
"AvailableBalance": "100.00",
"FrozenBalance": "100.00",
"PendingBalance": "100.00",
"Network": "string",
"AssetType": "string",
"BalanceType": "100.00",
"BalanceId": "100.00",
"CreatedAt": "2026-08-05T09:30:00Z"
}
],
"RetrievedAt": "string"
}501Not ImplementedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
Prices4 operations
GET/api/v2/pricesReturns the latest database-backed reference prices.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/prices?assetCodes=example' \
-H 'x-api-key: YOUR_API_KEY'Parameters
assetCodesqueryarrayoptionalExample: example200OKapplication/json
[
{
"AssetCode": "string",
"AssetType": "string",
"BaseCurrency": "USD",
"Price": 100,
"Provider": "string",
"ProviderUpdatedAt": "2026-08-05T09:30:00Z",
"LastSyncedAt": "2026-08-05T09:30:00Z",
"IsAvailable": true,
"IsStale": true
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/prices/{assetCode}Returns one latest database-backed reference price.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/prices/example' \
-H 'x-api-key: YOUR_API_KEY'Parameters
assetCodepathstringrequiredExample: example200OKAssetPriceResponse
{
"AssetCode": "string",
"AssetType": "string",
"BaseCurrency": "USD",
"Price": 100,
"Provider": "string",
"ProviderUpdatedAt": "2026-08-05T09:30:00Z",
"LastSyncedAt": "2026-08-05T09:30:00Z",
"IsAvailable": true,
"IsStale": true
}404Not FoundProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/prices/convertReturns a cross-rate derived entirely from stored canonical-base prices.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/prices/convert?from=example&to=example' \
-H 'x-api-key: YOUR_API_KEY'Parameters
fromquerystringoptionalExample: exampletoquerystringoptionalExample: example200OKAssetConversionResponse
{
"FromCurrency": "USD",
"ToCurrency": "USD",
"Rate": 100,
"PriceUpdatedAt": "2026-08-05T09:30:00Z",
"IsStale": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/prices/estimated-total-assetsFetches live provider balances and values them using database-backed reference prices.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/prices/estimated-total-assets?user_id=123¤cy=USD' \
-H 'x-api-key: YOUR_API_KEY'Parameters
user_idqueryintegeroptionalExample: 123currencyquerystringoptionalExample: USD200OKEstimatedUserAssetsResponse
{
"UserId": 123,
"Currency": "USD",
"EstimatedTotalAssets": 100,
"CalculatedAt": "2026-08-05T09:30:00Z",
"Balances": [
{
"Source": "string",
"AssetCode": "string",
"Balance": 100,
"EstimatedValue": 100,
"TargetCurrency": "USD",
"LastBalanceUpdatedAt": "2026-08-05T09:30:00Z",
"BudgetId": "string"
}
],
"ProviderTotals": [
{
"Provider": "string",
"EstimatedTotalAssets": 100,
"Currency": "USD",
"AssetCount": 1,
"IsAvailable": true,
"UnpricedAssetCodes": [
"string"
]
}
],
"UnpricedAssetCodes": [
"string"
],
"IsComplete": true,
"UnavailableProviders": [
"string"
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PublicDiscountCodes1 operations
POST/api/v2/discount-codes/validateOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/discount-codes/validate' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Code": "string",
"UserId": 123
}'Request fields and validation
UserId · integer · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
Code · string · requiredMaximum length: 100
Example request body · replace placeholders
{
"Code": "string",
"UserId": 123
}200OKDiscountCodeValidationResult
{
"IsValid": true,
"ErrorMessage": "string",
"DiscountCode": {
"Id": 123,
"Code": "string",
"Description": "Example description",
"CompanyId": 123,
"DiscountType": "string",
"BuyDiscountPercent": 100,
"MonthlyDiscountPercent": 100,
"YearlyDiscountPercent": 100,
"BuyDiscountFixed": 100,
"MonthlyDiscountFixed": 100,
"YearlyDiscountFixed": 100,
"CardDiscountDurationMonths": 1,
"TierDiscountDurationMonths": 1,
"TierMonthlyDiscountPercent": 100,
"TierYearlyDiscountPercent": 100,
"TierMonthlyDiscountFixed": 100,
"TierYearlyDiscountFixed": 100,
"MaxUsesTotal": 1,
"MaxUsesPerUser": 1,
"CurrentUses": 1,
"ValidFrom": "2026-08-05T09:30:00Z",
"ValidTill": "2026-08-05T09:30:00Z",
"ApplicableUserIds": [
1
],
"IsActive": true,
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CreatedBy": 1
},
"DiscountType": "string",
"BuyDiscountPercent": 100,
"MonthlyDiscountPercent": 100,
"YearlyDiscountPercent": 100,
"BuyDiscountFixed": 100,
"MonthlyDiscountFixed": 100,
"YearlyDiscountFixed": 100,
"CardDiscountDurationMonths": 1,
"TierDiscountDurationMonths": 1,
"TierMonthlyDiscountPercent": 100,
"TierYearlyDiscountPercent": 100,
"TierMonthlyDiscountFixed": 100,
"TierYearlyDiscountFixed": 100,
"ValidTill": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PublicUserReferrals25 operations
GET/api/v2/users/{userId}/referrals/geo-eligibilityOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/referrals/geo-eligibility' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123200OKReferralGeoMemberStatus
{
"Attributed": true,
"Eligibility": {
"Status": "PENDING",
"CanQualify": true,
"CanPayout": true,
"Reason": "string",
"VerifiedCountry": "GB",
"PendingExpiresAt": "2026-08-05T09:30:00Z"
},
"AcceptedTerms": {
"Locale": "string",
"TermsVersion": 1,
"ContentHash": "string",
"Text": "string",
"AcceptedAt": "2026-08-05T09:30:00Z"
}
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/referrals/summaryReturns invite, level progress, referral counts, commission totals, and payout mode.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/referrals/summary?programId=00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123200OKReferralSummaryResponse
{
"Enabled": true,
"Provider": "string",
"ReferralCode": "string",
"ReferralPath": "string",
"InviteOffer": {
"ReferredTierId": 123,
"ReferredTierName": "string",
"DiscountCodeId": 123,
"DiscountCode": "string",
"DiscountDescription": "Example description",
"CardDiscountDurationMonths": 1,
"TierDiscountDurationMonths": 1,
"InheritBenefits": true
},
"CurrentLevel": {
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
},
"NextLevel": {
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
},
"Levels": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
}
],
"Progress": {
"Basis": "string",
"CurrentValue": 100,
"NextThreshold": 100,
"Remaining": 100,
"LookbackMonths": 1,
"QualifiedReferrals": 0,
"TopupVolume": 0,
"TopupVolumeCurrency": "USD",
"NextMinimumQualifiedReferrals": 1,
"NextMinimumTopupVolume": 100,
"RemainingQualifiedReferrals": 1,
"RemainingTopupVolume": 100
},
"Referrals": {
"Invited": 1,
"Qualified": 1,
"InProgress": 1,
"Earning": 1
},
"Rewards": {
"Pending": 100,
"Ready": 100,
"Crediting": 100,
"Paid": 100,
"Failed": 100,
"Currency": "USD"
},
"Offer": {
"WelcomeAmount": 100,
"WelcomeCurrency": "USD",
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"EarningWindowDays": 1,
"EarningWindowStart": "string",
"MaxEligibleVolumePerRelationship": 100,
"RequiresKyc": true,
"RequiresPaidCard": true,
"RequiresTopup": true,
"MinimumTopup": 100,
"MaximumRecurringReward": 100,
"CustomerRecurringRate": 0,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string",
"PromoCodePolicyEnabled": false
},
"Terms": {
"Version": 1,
"Text": "string",
"PrivacyNotice": "string",
"Accepted": true,
"AcceptedVersion": 1,
"AcceptedAt": "2026-08-05T09:30:00Z"
},
"DeliveryMode": "string",
"MinimumCreditAmount": 100,
"AccumulatedTowardsCredit": 100,
"ProgramId": "00000000-0000-4000-8000-000000000123",
"ProgramName": "string",
"CanInvite": true,
"AssignedLevel": false,
"ProgramDescription": "Example description",
"ParticipationEligibility": {
"Status": "PENDING",
"CanQualify": true,
"CanPayout": true,
"Reason": "string",
"VerifiedCountry": "GB",
"PendingExpiresAt": "2026-08-05T09:30:00Z"
}
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/referrals/rewardsReturns the user's referral reward ledger (welcome, qualification and top-up rewards with delivery stage).Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/referrals/rewards?programId=00000000-0000-4000-8000-000000000123&page=1&pageSize=50' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123pagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 50200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"EventType": "string",
"BeneficiaryRole": "string",
"LevelCode": "string",
"BasisAmount": 100,
"BasisCurrency": "USD",
"Amount": 100,
"Currency": "USD",
"DeliveryMode": "string",
"Status": "PENDING",
"Stage": "string",
"CreditId": "00000000-0000-4000-8000-000000000123",
"VoucherId": "00000000-0000-4000-8000-000000000123",
"FriendAlias": "string",
"OccurredAt": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"PaidAt": "2026-08-05T09:30:00Z",
"Explanation": {
"Basis": "string",
"Rate": 100,
"OfferVersionId": "00000000-0000-4000-8000-000000000123",
"TermsVersion": 1,
"EligibleAmount": 100,
"VolumeCap": 100,
"Rounding": "string",
"DeliveryExplanation": "string"
},
"Balance": {
"CashPaid": 100,
"OffsetSettled": 100,
"ReservedCash": 100,
"RemainingPayable": 100,
"LegacyCashUnknown": true
},
"Holds": [
{
"Reason": "string",
"ReleaseAt": "2026-08-05T09:30:00Z"
}
]
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/referrals/commissionsBackward-compatible alias for integrations built before the v2 rename; same rows as `rewards`.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/referrals/commissions?programId=00000000-0000-4000-8000-000000000123&page=1&pageSize=50' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123pagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 50200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"EventType": "string",
"BeneficiaryRole": "string",
"LevelCode": "string",
"BasisAmount": 100,
"BasisCurrency": "USD",
"Amount": 100,
"Currency": "USD",
"DeliveryMode": "string",
"Status": "PENDING",
"Stage": "string",
"CreditId": "00000000-0000-4000-8000-000000000123",
"VoucherId": "00000000-0000-4000-8000-000000000123",
"FriendAlias": "string",
"OccurredAt": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"PaidAt": "2026-08-05T09:30:00Z",
"Explanation": {
"Basis": "string",
"Rate": 100,
"OfferVersionId": "00000000-0000-4000-8000-000000000123",
"TermsVersion": 1,
"EligibleAmount": 100,
"VolumeCap": 100,
"Rounding": "string",
"DeliveryExplanation": "string"
},
"Balance": {
"CashPaid": 100,
"OffsetSettled": 100,
"ReservedCash": 100,
"RemainingPayable": 100,
"LegacyCashUnknown": true
},
"Holds": [
{
"Reason": "string",
"ReleaseAt": "2026-08-05T09:30:00Z"
}
]
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/{userId}/referrals/attributionCreates the immutable rewarded relationship after registration succeeds.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/123/referrals/attribution' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"ReferralCode": "string",
"Source": "string",
"Accepted": true,
"TermsVersion": 1
}'Parameters
userIdpathintegerrequiredExample: 123Request fields and validation
ReferralCode · string · requiredMaximum length: 32
Source · string · requiredMaximum length: 24
Accepted · boolean · optionalThe referred user explicitly accepted that the inviter is credited for their sign-up.
TermsVersion · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"ReferralCode": "string",
"Source": "string",
"Accepted": true,
"TermsVersion": 1
}204No ContentNo response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/referrals/friendsReferred friends with pseudonyms ("user-XXXXX"), stages and per-friend earnings. Never exposes the friend's identity.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/referrals/friends?programId=00000000-0000-4000-8000-000000000123&page=1&pageSize=50' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123pagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 50200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"Alias": "string",
"Stage": "string",
"AttributedAt": "2026-08-05T09:30:00Z",
"KycCompletedAt": "2026-08-05T09:30:00Z",
"FirstCardAt": "2026-08-05T09:30:00Z",
"FirstTopupAt": "2026-08-05T09:30:00Z",
"QualifiedAt": "2026-08-05T09:30:00Z",
"EarningUntil": "2026-08-05T09:30:00Z",
"EarnedAmount": 100,
"Currency": "USD",
"RecipientName": "string"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/referrals/analyticsThe user's own referral performance over a period: conversion journey, totals, weekly trend and top friends (pseudonymised). range = 7d | 30d | 90d | month (default 30d); explicit from/to (ISO, UTC, to exclusive, at most 366 days) win over range.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/referrals/analytics?programId=00000000-0000-4000-8000-000000000123&range=example&from=2026-08-05T09%3A30%3A00Z&to=2026-08-05T09%3A30%3A00Z' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123rangequerystringoptionalExample: examplefromquerystringoptionalExample: 2026-08-05T09:30:00ZtoquerystringoptionalExample: 2026-08-05T09:30:00Z200OKReferralMemberAnalyticsResponse
{
"From": "2026-08-05T09:30:00Z",
"To": "2026-08-05T09:30:00Z",
"Range": "string",
"Currency": "USD",
"GeneratedAt": "2026-08-05T09:30:00Z",
"Journey": {
"Invited": 1,
"Verified": 1,
"CardIssued": 1,
"Qualified": 1,
"Earning": 1,
"WindowEnded": 1
},
"Totals": {
"Attributed": 1,
"Qualified": 1,
"ConversionRate": 100,
"RewardsAccrued": 100,
"RewardsPaid": 100,
"RewardsPending": 100
},
"Weekly": [
{
"WeekStart": "2026-08-05T09:30:00Z",
"Attributed": 1,
"Qualified": 1,
"RewardsAccrued": 100,
"RewardsPaid": 100
}
],
"TopFriends": [
{
"Alias": "string",
"Stage": "string",
"Earned": 100,
"QualifiedAt": "2026-08-05T09:30:00Z"
}
],
"Campaigns": [
{
"LinkId": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"Code": "string",
"Clicks": 1,
"Signups": 1,
"Qualified": 1,
"RewardsAccrued": 100
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/{userId}/referrals/terms-acceptanceRecords the inviter's acceptance of the current program terms.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/123/referrals/terms-acceptance?programId=00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"TermsVersion": 1
}'Parameters
userIdpathintegerrequiredExample: 123programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123Request fields and validation
TermsVersion · integer · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"TermsVersion": 1
}200OKReferralTermsStatusResponse
{
"Version": 1,
"Text": "string",
"PrivacyNotice": "string",
"Accepted": true,
"AcceptedVersion": 1,
"AcceptedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/referrals/invitationsLists the invitations sent by this user.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/referrals/invitations?programId=00000000-0000-4000-8000-000000000123&page=1&pageSize=50' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123pagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 50200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"RecipientEmail": "user@example.com",
"RecipientName": "string",
"RegisteredUserId": 123,
"Source": "string",
"Status": "PENDING",
"DeliveryStatus": "PENDING",
"SendCount": 1,
"CreatedAt": "2026-08-05T09:30:00Z",
"ExpiresAt": "2026-08-05T09:30:00Z",
"LastSentAt": "2026-08-05T09:30:00Z",
"AcceptedAt": "2026-08-05T09:30:00Z"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/{userId}/referrals/invitationsSends or resends an email-bound, expiring referral invitation.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/123/referrals/invitations?programId=00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"RecipientEmail": "user@example.com",
"RecipientName": "string"
}'Parameters
userIdpathintegerrequiredExample: 123programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123Request fields and validation
RecipientEmail · string · requiredMaximum length: 320
RecipientName · string or null · optionalMaximum length: 120
Example request body · replace placeholders
{
"RecipientEmail": "user@example.com",
"RecipientName": "string"
}201CreatedReferralEmailInvitationResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"RecipientEmail": "user@example.com",
"RecipientName": "string",
"RegisteredUserId": 123,
"Source": "string",
"Status": "PENDING",
"DeliveryStatus": "PENDING",
"SendCount": 1,
"CreatedAt": "2026-08-05T09:30:00Z",
"ExpiresAt": "2026-08-05T09:30:00Z",
"LastSentAt": "2026-08-05T09:30:00Z",
"AcceptedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/referrals/vouchersLists assigned vouchers that can be rendered in a WL-hosted user experience.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/referrals/vouchers' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123200OKapplication/json
[
{
"AssignmentId": "00000000-0000-4000-8000-000000000123",
"VoucherId": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"Source": "string",
"ReferralCommissionId": "00000000-0000-4000-8000-000000000123",
"AssignedAt": "2026-08-05T09:30:00Z",
"ValidUntil": "2026-08-05T09:30:00Z",
"Redemption": {
"Id": "00000000-0000-4000-8000-000000000123",
"VoucherId": "00000000-0000-4000-8000-000000000123",
"VoucherName": "string",
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"TransactionReference": "external_reference_123",
"ErrorCode": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
},
"ReferralProgramId": "00000000-0000-4000-8000-000000000123"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/{userId}/referrals/vouchers/{assignmentId}/redeemRedeems an assigned voucher without exposing or typing its voucher code.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/123/referrals/vouchers/00000000-0000-4000-8000-000000000123/redeem' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123assignmentIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKVoucherRedemptionResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"VoucherId": "00000000-0000-4000-8000-000000000123",
"VoucherName": "string",
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"TransactionReference": "external_reference_123",
"ErrorCode": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/{userId}/referrals/vouchers/redeem-allInitiates all eligible assigned vouchers through the existing voucher processor.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/123/referrals/vouchers/redeem-all' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123200OKRedeemAllAssignedVouchersResponse
{
"Eligible": 1,
"Initiated": 1,
"AlreadyProcessing": 1,
"Skipped": 1,
"Failed": 1,
"Results": [
{
"AssignmentId": "00000000-0000-4000-8000-000000000123",
"Status": "PENDING",
"Redemption": {
"Id": "00000000-0000-4000-8000-000000000123",
"VoucherId": "00000000-0000-4000-8000-000000000123",
"VoucherName": "string",
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"TransactionReference": "external_reference_123",
"ErrorCode": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
},
"ErrorCode": "string",
"ErrorMessage": "string"
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/referrals/programsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/referrals/programs' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123200OKapplication/json
[
{
"Exists": true,
"Id": "00000000-0000-4000-8000-000000000123",
"Provider": "string",
"Status": "PENDING",
"LevelBasis": "string",
"LevelLookbackMonths": 1,
"EarningWindowDays": 1,
"EarningWindowStart": "string",
"QualifyRequiresKyc": true,
"QualifyRequiresPaidCard": true,
"QualifyRequiresTopup": true,
"QualifyMinimumTopup": 100,
"WelcomeAmount": 100,
"WelcomeCurrency": "USD",
"DeliveryMode": "string",
"PayoutCurrency": "USD",
"VoucherClaimDays": 1,
"MinimumCreditAmount": 100,
"MaxEligibleVolumePerRelationship": 100,
"ExposureLimit": 100,
"ReservedExposure": 100,
"TermsVersion": 1,
"TermsText": "string",
"PrivacyNotice": "string",
"PublishedAt": "2026-08-05T09:30:00Z",
"Levels": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
}
],
"UpdatedAt": "2026-08-05T09:30:00Z",
"Name": "Public referral program",
"Visibility": "PUBLIC",
"Description": "Example description",
"Revision": 1,
"OfferVersionId": "00000000-0000-4000-8000-000000000123",
"MarginPolicy": {
"Direct": {
"CompanyBps": 1,
"AffiliateBps": 1,
"SubpartnerBps": 1,
"CustomerBps": 1,
"BudgetBps": 1
},
"Team": {
"CompanyBps": {},
"AffiliateBps": {},
"SubpartnerBps": {},
"CustomerBps": {},
"BudgetBps": {}
}
},
"MaximumRecurringReward": 100,
"PromoCodePolicyEnabled": false
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/referrals/linksThe member's campaign links, newest first. status filters on the reported status (ACTIVE, PAUSED, EXPIRED, ARCHIVED).Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/referrals/links?programId=00000000-0000-4000-8000-000000000123&status=PENDING' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123statusquerystringoptionalExample: PENDING200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"ProgramName": "string",
"Name": "string",
"Code": "string",
"Channel": "string",
"Locale": "string",
"Destination": "string",
"Status": "PENDING",
"ActiveFrom": "2026-08-05T09:30:00Z",
"ExpiresAt": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"ShareUrl": "https://example.com/callback",
"SignupCount": 1,
"QualifiedCount": 1,
"ClickCount": 1,
"UniqueClickCount": 1,
"OfferVersionId": "00000000-0000-4000-8000-000000000123",
"SuggestedCaption": "string",
"OwnerUserId": 123,
"OwnerName": "string",
"OwnerEmail": "user@example.com"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/{userId}/referrals/linksCreates a campaign link (code generated from the name unless supplied). Requires invite permission and accepted terms.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/123/referrals/links' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Name": "string",
"Channel": "string",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Locale": "string",
"Destination": "string",
"ExpiresAt": "2026-08-05T09:30:00Z"
}'Parameters
userIdpathintegerrequiredExample: 123Request fields and validation
ProgramId · string or null · optionalDefaults to the company's public programme.
Name · string · requiredMaximum length: 80
Code · string or null · optional6–24 chars of [A-Za-z0-9_-]; generated from the name when omitted. Stored upper-case.
Maximum length: 24
Channel · string · requiredsocial, community, email, website, event or other.
Maximum length: 16
Locale · string or null · optionalBCP-47 tag, at most 8 chars; defaults to en.
Maximum length: 8
Destination · string or null · optionalAllowlisted destination (signup, home, cards, topup, rewards); defaults to signup.
Maximum length: 32
ExpiresAt · string or null · optionalExample request body · replace placeholders
{
"Name": "string",
"Channel": "string",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Locale": "string",
"Destination": "string",
"ExpiresAt": "2026-08-05T09:30:00Z"
}201CreatedReferralCampaignLinkResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"ProgramName": "string",
"Name": "string",
"Code": "string",
"Channel": "string",
"Locale": "string",
"Destination": "string",
"Status": "PENDING",
"ActiveFrom": "2026-08-05T09:30:00Z",
"ExpiresAt": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"ShareUrl": "https://example.com/callback",
"SignupCount": 1,
"QualifiedCount": 1,
"ClickCount": 1,
"UniqueClickCount": 1,
"OfferVersionId": "00000000-0000-4000-8000-000000000123",
"SuggestedCaption": "string",
"OwnerUserId": 123,
"OwnerName": "string",
"OwnerEmail": "user@example.com"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PATCH/api/v2/users/{userId}/referrals/links/{linkId}Renames, re-targets (allowlisted destination), pauses/resumes/archives or re-schedules a link. The code is immutable.Request & responses +
curl --request PATCH 'https://staging.hoppa.global/api/v2/users/123/referrals/links/00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Name": "string",
"Status": "PENDING",
"Destination": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"ClearExpiresAt": true
}'Parameters
userIdpathintegerrequiredExample: 123linkIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Request fields and validation
Name · string or null · optionalMaximum length: 80
Status · string or null · optionalACTIVE, PAUSED or ARCHIVED. Archiving is final.
Maximum length: 16
Destination · string or null · optionalAllowlisted destination (signup, home, cards, topup, rewards). The code never changes.
Maximum length: 32
ExpiresAt · string or null · optionalClearExpiresAt · boolean · optionalExample request body · replace placeholders
{
"Name": "string",
"Status": "PENDING",
"Destination": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"ClearExpiresAt": true
}200OKReferralCampaignLinkResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"ProgramName": "string",
"Name": "string",
"Code": "string",
"Channel": "string",
"Locale": "string",
"Destination": "string",
"Status": "PENDING",
"ActiveFrom": "2026-08-05T09:30:00Z",
"ExpiresAt": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"ShareUrl": "https://example.com/callback",
"SignupCount": 1,
"QualifiedCount": 1,
"ClickCount": 1,
"UniqueClickCount": 1,
"OfferVersionId": "00000000-0000-4000-8000-000000000123",
"SuggestedCaption": "string",
"OwnerUserId": 123,
"OwnerName": "string",
"OwnerEmail": "user@example.com"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/referrals/links/{linkId}/performanceClicks (by UTC day), sign-ups, verified, qualified and earning friends attributed through the link plus the owner's rewards on them. range = 7d | 30d | 90d | month | all.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/referrals/links/00000000-0000-4000-8000-000000000123/performance?range=example' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123linkIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123rangequerystringoptionalExample: example200OKReferralCampaignLinkPerformanceResponse
{
"Clicks": 1,
"UniqueClicks": 1,
"ClickToSignupRate": 100,
"Signups": 1,
"Verified": 1,
"Qualified": 1,
"Earning": 1,
"RewardsAccrued": 100,
"RewardsPaid": 100,
"Currency": "USD"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/{userId}/referrals/attribution-commandsAccepts authenticated server consent provenance and returns a durable, immutable outcome.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/123/referrals/attribution-commands' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"TermsHash": "string",
"PolicyHash": "string",
"Provenance": "string",
"CommandId": "00000000-0000-4000-8000-000000000123",
"QuoteId": "00000000-0000-4000-8000-000000000123",
"Accepted": true,
"ConsentReceivedAt": "2026-08-05T09:30:00Z"
}'Parameters
userIdpathintegerrequiredExample: 123Request fields and validation
CommandId · string · optionalQuoteId · string · optionalAccepted · boolean · optionalTermsHash · string · requiredMinimum length: 0
Maximum length: 64
PolicyHash · string · requiredMinimum length: 0
Maximum length: 64
ConsentReceivedAt · string or null · optionalAuthenticated integration's server-received consent time; never forward a browser timestamp.
Provenance · string · requiredMinimum length: 0
Maximum length: 32
Example request body · replace placeholders
{
"TermsHash": "string",
"PolicyHash": "string",
"Provenance": "string",
"CommandId": "00000000-0000-4000-8000-000000000123",
"QuoteId": "00000000-0000-4000-8000-000000000123",
"Accepted": true,
"ConsentReceivedAt": "2026-08-05T09:30:00Z"
}200OKReferralAttributionCommandResponse
{
"CommandId": "00000000-0000-4000-8000-000000000123",
"Status": "PENDING",
"Reason": "string",
"RelationshipId": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"AcceptedTermsVersion": 1,
"AcceptedPolicyHash": "string",
"AcquisitionOccurredAt": "2026-08-05T09:30:00Z",
"CommittedAt": "2026-08-05T09:30:00Z",
"ReplayStatus": "PENDING",
"ReplayReason": "string",
"AssignedTierId": 123
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/referrals/attribution-commands/{commandId}Open request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/referrals/attribution-commands/00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123commandIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKReferralAttributionCommandResponse
{
"CommandId": "00000000-0000-4000-8000-000000000123",
"Status": "PENDING",
"Reason": "string",
"RelationshipId": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"AcceptedTermsVersion": 1,
"AcceptedPolicyHash": "string",
"AcquisitionOccurredAt": "2026-08-05T09:30:00Z",
"CommittedAt": "2026-08-05T09:30:00Z",
"ReplayStatus": "PENDING",
"ReplayReason": "string",
"AssignedTierId": 123
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/{userId}/referrals/attribution-commands/{commandId}/replayOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/123/referrals/attribution-commands/00000000-0000-4000-8000-000000000123/replay' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123commandIdpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKReferralAttributionCommandResponse
{
"CommandId": "00000000-0000-4000-8000-000000000123",
"Status": "PENDING",
"Reason": "string",
"RelationshipId": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"AcceptedTermsVersion": 1,
"AcceptedPolicyHash": "string",
"AcquisitionOccurredAt": "2026-08-05T09:30:00Z",
"CommittedAt": "2026-08-05T09:30:00Z",
"ReplayStatus": "PENDING",
"ReplayReason": "string",
"AssignedTierId": 123
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/referrals/communityOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/referrals/community?programId=00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123200OKReferralCommunitySummaryResponse
{
"Enabled": true,
"Currency": "USD",
"Membership": {
"Id": "00000000-0000-4000-8000-000000000123",
"UserId": 123,
"Plan": "string",
"ParentUserId": 123,
"PlanRevision": 1,
"L2Bps": 1,
"L3Bps": 1,
"EnabledAt": "2026-08-05T09:30:00Z",
"ExpiresAt": "2026-08-05T09:30:00Z",
"RevokedAt": "2026-08-05T09:30:00Z",
"Status": "PENDING",
"AgreementReference": "external_reference_123",
"Notes": "string"
},
"BudgetBps": 1,
"Generations": [
{
"Depth": 1,
"Descendants": 1,
"Qualified": 1,
"Earning": 1,
"Accrued": 100,
"CashPaid": 100,
"Outstanding": 100
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/referrals/community/earningsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/referrals/community/earnings?programId=00000000-0000-4000-8000-000000000123&page=1&pageSize=25' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123pagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 25200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"Depth": 1,
"FriendAlias": "string",
"Amount": 100,
"CashPaid": 100,
"Outstanding": 100,
"Status": "PENDING",
"RequestedRate": 100,
"AppliedRate": 100,
"ReductionReason": "string",
"OccurredAt": "2026-08-05T09:30:00Z"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/referrals/level-lifecycleOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/referrals/level-lifecycle?programId=00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123200OKReferralLevelLifecycleResponse
{
"ProgramId": "00000000-0000-4000-8000-000000000123",
"UserId": 123,
"AsOf": "2026-08-05T09:30:00Z",
"ObservedAt": "2026-08-05T09:30:00Z",
"CurrentLevel": {
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
},
"Assigned": true,
"Progress": {
"Basis": "string",
"CurrentValue": 100,
"NextThreshold": 100,
"Remaining": 100,
"LookbackMonths": 1,
"QualifiedReferrals": 0,
"TopupVolume": 0,
"TopupVolumeCurrency": "USD",
"NextMinimumQualifiedReferrals": 1,
"NextMinimumTopupVolume": 100,
"RemainingQualifiedReferrals": 1,
"RemainingTopupVolume": 100
},
"Forecast": {
"EffectiveAt": "2026-08-05T09:30:00Z",
"DaysUntil": 1,
"Level": {
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
},
"Assigned": true,
"Reason": "string"
},
"ProtectedRelationshipCount": 1,
"ExistingOffersProtected": true,
"ForecastAssumption": "NO_FUTURE_ACTIVITY_OR_POLICY_CHANGES"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/referrals/level-historyOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/referrals/level-history?programId=00000000-0000-4000-8000-000000000123&page=1&pageSize=25' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123programIdquerystringoptionalExample: 00000000-0000-4000-8000-000000000123pagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 25200OKReferralLevelHistoryResponse
{
"Items": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"UserId": 123,
"Sequence": 1,
"Kind": "string",
"EffectiveAt": "2026-08-05T09:30:00Z",
"ObservedAt": "2026-08-05T09:30:00Z",
"EffectiveTimeBasis": "string",
"PreviousLevel": {
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
},
"CurrentLevel": {
"Id": "00000000-0000-4000-8000-000000000123",
"Code": "string",
"Name": "string",
"Icon": "string",
"Color": "string",
"DisplayOrder": 1,
"MinimumMetricValue": 100,
"QualificationCalculationType": "string",
"QualificationRate": 100,
"TopupCalculationType": "string",
"TopupRate": 100,
"Hidden": true,
"MinimumQualifiedReferrals": 1,
"MinimumTopupVolume": 100,
"VolumeCapMode": "INHERIT",
"VolumeCapAmount": 100,
"RecurringRewardCapMode": "INHERIT",
"RecurringRewardCapAmount": 100,
"EffectiveVolumeCap": 100,
"EffectiveRecurringRewardCap": 100,
"VolumeCapSource": "100.00",
"RecurringRewardCapSource": "string"
},
"Assigned": true,
"DeliveryStatus": "PENDING"
}
],
"Page": 1,
"PageSize": 1,
"HasMore": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PublicVouchers41 operations
GET/api/v2/vouchers/settingsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers/settings' \
-H 'x-api-key: YOUR_API_KEY'200OKVoucherModuleStatusResponse
{
"GlobalEnabled": true,
"CompanyEnabled": true,
"InterlaceEnabled": true,
"EffectiveEnabled": true,
"ShutdownMode": "string",
"LowBalanceWarningPercentage": 100,
"VerificationTtlMinutes": 1,
"DefaultRequiresApproval": true,
"DailyReportRecipients": [
"string"
],
"MaximumBatchSize": 1,
"MaximumImportRows": 1,
"MaximumMassAssignmentSize": 1
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/vouchers/settingsOpen request and response documentationRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/vouchers/settings' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"Enabled": true,
"ShutdownMode": "string",
"LowBalanceWarningPercentage": 100,
"VerificationTtlMinutes": 1,
"DefaultRequiresApproval": true,
"DailyReportRecipients": [
"string"
],
"MaximumBatchSize": 1,
"MaximumImportRows": 1,
"MaximumMassAssignmentSize": 1
}'Parameters
Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
Enabled · boolean · optionalShutdownMode · string · optionalPattern: ^(SUSPEND_NEW_ACTIVITY|REJECT_PENDING)$
LowBalanceWarningPercentage · number · optionalMinimum: 0
Maximum: 100
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
VerificationTtlMinutes · integer · optionalMinimum: 1
Maximum: 60
Pattern: ^-?(?:0|[1-9]\d*)$
DefaultRequiresApproval · boolean · optionalDailyReportRecipients · array · optionalMaximumBatchSize · integer · optionalMinimum: 1
Maximum: 10000
Pattern: ^-?(?:0|[1-9]\d*)$
MaximumImportRows · integer · optionalMinimum: 1
Maximum: 10000
Pattern: ^-?(?:0|[1-9]\d*)$
MaximumMassAssignmentSize · integer · optionalMinimum: 1
Maximum: 10000
Pattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"Enabled": true,
"ShutdownMode": "string",
"LowBalanceWarningPercentage": 100,
"VerificationTtlMinutes": 1,
"DefaultRequiresApproval": true,
"DailyReportRecipients": [
"string"
],
"MaximumBatchSize": 1,
"MaximumImportRows": 1,
"MaximumMassAssignmentSize": 1
}200OKVoucherModuleStatusResponse
{
"GlobalEnabled": true,
"CompanyEnabled": true,
"InterlaceEnabled": true,
"EffectiveEnabled": true,
"ShutdownMode": "string",
"LowBalanceWarningPercentage": 100,
"VerificationTtlMinutes": 1,
"DefaultRequiresApproval": true,
"DailyReportRecipients": [
"string"
],
"MaximumBatchSize": 1,
"MaximumImportRows": 1,
"MaximumMassAssignmentSize": 1
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/vouchers/groupsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers/groups' \
-H 'x-api-key: YOUR_API_KEY'200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"Description": "Example description",
"Status": "PENDING",
"DefaultType": "string",
"DefaultValue": 100,
"DefaultCurrency": "USD",
"DefaultPerUserLimit": 1,
"DefaultTotalUseLimit": 1,
"DefaultAggregateCap": 100,
"DefaultRequiresApproval": true,
"DefaultRequiresEmail2Fa": true,
"DefaultValidFrom": "2026-08-05T09:30:00Z",
"DefaultValidUntil": "2026-08-05T09:30:00Z",
"CampaignReference": "external_reference_123",
"CostCentre": "string",
"Tags": [
"string"
],
"CreatedAt": "2026-08-05T09:30:00Z"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/groupsOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/groups' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"Name": "string",
"Description": "Example description",
"DefaultType": "string",
"DefaultValue": 100,
"DefaultCurrency": "USD",
"DefaultPerUserLimit": 1,
"DefaultTotalUseLimit": 1,
"DefaultAggregateCap": 100,
"DefaultRequiresApproval": true,
"DefaultRequiresEmail2Fa": true,
"DefaultValidFrom": "2026-08-05T09:30:00Z",
"DefaultValidUntil": "2026-08-05T09:30:00Z",
"CampaignReference": "external_reference_123",
"CostCentre": "string",
"Tags": [
"string"
]
}'Parameters
Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
Name · string · requiredMaximum length: 160
Description · string or null · optionalMaximum length: 2000
DefaultType · string · optionalDefaultValue · number or null · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
DefaultCurrency · string or null · optionalDefaultPerUserLimit · integer · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
DefaultTotalUseLimit · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
DefaultAggregateCap · number or null · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
DefaultRequiresApproval · boolean · optionalDefaultRequiresEmail2Fa · boolean · optionalDefaultValidFrom · string or null · optionalDefaultValidUntil · string or null · optionalCampaignReference · string or null · optionalCostCentre · string or null · optionalTags · array · optionalExample request body · replace placeholders
{
"Name": "string",
"Description": "Example description",
"DefaultType": "string",
"DefaultValue": 100,
"DefaultCurrency": "USD",
"DefaultPerUserLimit": 1,
"DefaultTotalUseLimit": 1,
"DefaultAggregateCap": 100,
"DefaultRequiresApproval": true,
"DefaultRequiresEmail2Fa": true,
"DefaultValidFrom": "2026-08-05T09:30:00Z",
"DefaultValidUntil": "2026-08-05T09:30:00Z",
"CampaignReference": "external_reference_123",
"CostCentre": "string",
"Tags": [
"string"
]
}200OKVoucherGroupResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"Description": "Example description",
"Status": "PENDING",
"DefaultType": "string",
"DefaultValue": 100,
"DefaultCurrency": "USD",
"DefaultPerUserLimit": 1,
"DefaultTotalUseLimit": 1,
"DefaultAggregateCap": 100,
"DefaultRequiresApproval": true,
"DefaultRequiresEmail2Fa": true,
"DefaultValidFrom": "2026-08-05T09:30:00Z",
"DefaultValidUntil": "2026-08-05T09:30:00Z",
"CampaignReference": "external_reference_123",
"CostCentre": "string",
"Tags": [
"string"
],
"CreatedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/vouchers/groups/{id}/status/{status}Open request and response documentationRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/vouchers/groups/00000000-0000-4000-8000-000000000123/status/PENDING' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001'Parameters
idpathstringrequiredExample: 00000000-0000-4000-8000-000000000123statuspathstringrequiredExample: PENDINGIdempotency-KeyheaderstringoptionalExample: operation-customer-1042-001200OKVoucherGroupResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"Description": "Example description",
"Status": "PENDING",
"DefaultType": "string",
"DefaultValue": 100,
"DefaultCurrency": "USD",
"DefaultPerUserLimit": 1,
"DefaultTotalUseLimit": 1,
"DefaultAggregateCap": 100,
"DefaultRequiresApproval": true,
"DefaultRequiresEmail2Fa": true,
"DefaultValidFrom": "2026-08-05T09:30:00Z",
"DefaultValidUntil": "2026-08-05T09:30:00Z",
"CampaignReference": "external_reference_123",
"CostCentre": "string",
"Tags": [
"string"
],
"CreatedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/vouchersOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers?page=1&pageSize=50' \
-H 'x-api-key: YOUR_API_KEY'Parameters
pagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 50200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"GroupId": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"Description": "Example description",
"MaskedCode": "string",
"Type": "string",
"Value": 100,
"Currency": "USD",
"Status": "PENDING",
"SuccessfulUses": 1,
"ReservedUses": 1,
"PerUserLimit": 1,
"MaximumTotalUses": 1,
"RedeemedValue": 100,
"ReservedValue": 100,
"MaximumAggregateValue": 100,
"RequiresWhitelabelApproval": true,
"RequiresEmail2Fa": true,
"ValidFrom": "2026-08-05T09:30:00Z",
"ValidUntil": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"PlaintextCode": "string"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchersOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"Name": "string",
"Description": "Example description",
"GroupPublicId": "00000000-0000-4000-8000-000000000123",
"TargetUserId": 123,
"CustomCode": "string",
"Prefix": "string",
"Type": "string",
"Value": 100,
"Currency": "USD",
"PerUserLimit": 1,
"MaximumTotalUses": 1,
"MaximumAggregateValue": 100,
"RequiresWhitelabelApproval": true,
"RequiresEmail2Fa": true,
"ValidFrom": "2026-08-05T09:30:00Z",
"ValidUntil": "2026-08-05T09:30:00Z",
"InitialStatus": "PENDING",
"ExternalReference": "external_reference_123",
"AcceptUnboundedLiability": true
}'Parameters
Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
Name · string · requiredMaximum length: 160
Description · string or null · optionalMaximum length: 2000
GroupPublicId · string or null · optionalTargetUserId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
CustomCode · string or null · optionalPrefix · string or null · optionalMaximum length: 20
Type · string or null · optionalValue · number or null · optionalMinimum: 1e-10
Maximum: 7.922816251426434e+28
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Currency · string or null · optionalPerUserLimit · integer or null · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
MaximumTotalUses · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
MaximumAggregateValue · number or null · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
RequiresWhitelabelApproval · boolean · optionalRequiresEmail2Fa · boolean · optionalValidFrom · string or null · optionalValidUntil · string or null · optionalInitialStatus · string · optionalExternalReference · string or null · optionalAcceptUnboundedLiability · boolean · optionalExample request body · replace placeholders
{
"Name": "string",
"Description": "Example description",
"GroupPublicId": "00000000-0000-4000-8000-000000000123",
"TargetUserId": 123,
"CustomCode": "string",
"Prefix": "string",
"Type": "string",
"Value": 100,
"Currency": "USD",
"PerUserLimit": 1,
"MaximumTotalUses": 1,
"MaximumAggregateValue": 100,
"RequiresWhitelabelApproval": true,
"RequiresEmail2Fa": true,
"ValidFrom": "2026-08-05T09:30:00Z",
"ValidUntil": "2026-08-05T09:30:00Z",
"InitialStatus": "PENDING",
"ExternalReference": "external_reference_123",
"AcceptUnboundedLiability": true
}200OKVoucherResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"GroupId": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"Description": "Example description",
"MaskedCode": "string",
"Type": "string",
"Value": 100,
"Currency": "USD",
"Status": "PENDING",
"SuccessfulUses": 1,
"ReservedUses": 1,
"PerUserLimit": 1,
"MaximumTotalUses": 1,
"RedeemedValue": 100,
"ReservedValue": 100,
"MaximumAggregateValue": 100,
"RequiresWhitelabelApproval": true,
"RequiresEmail2Fa": true,
"ValidFrom": "2026-08-05T09:30:00Z",
"ValidUntil": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"PlaintextCode": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/batchOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/batch' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"Name": "string",
"Count": 1,
"SharedCode": true,
"Description": "Example description",
"GroupPublicId": "00000000-0000-4000-8000-000000000123",
"TargetUserId": 123,
"CustomCode": "string",
"Prefix": "string",
"Type": "string",
"Value": 100,
"Currency": "USD",
"PerUserLimit": 1,
"MaximumTotalUses": 1,
"MaximumAggregateValue": 100,
"RequiresWhitelabelApproval": true,
"RequiresEmail2Fa": true,
"ValidFrom": "2026-08-05T09:30:00Z",
"ValidUntil": "2026-08-05T09:30:00Z",
"InitialStatus": "PENDING",
"ExternalReference": "external_reference_123",
"AcceptUnboundedLiability": true
}'Parameters
Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
Count · integer · optionalMinimum: 1
Maximum: 10000
Pattern: ^-?(?:0|[1-9]\d*)$
SharedCode · boolean · optionalName · string · requiredMaximum length: 160
Description · string or null · optionalMaximum length: 2000
GroupPublicId · string or null · optionalTargetUserId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
CustomCode · string or null · optionalPrefix · string or null · optionalMaximum length: 20
Type · string or null · optionalValue · number or null · optionalMinimum: 1e-10
Maximum: 7.922816251426434e+28
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Currency · string or null · optionalPerUserLimit · integer or null · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
MaximumTotalUses · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
MaximumAggregateValue · number or null · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
RequiresWhitelabelApproval · boolean · optionalRequiresEmail2Fa · boolean · optionalValidFrom · string or null · optionalValidUntil · string or null · optionalInitialStatus · string · optionalExternalReference · string or null · optionalAcceptUnboundedLiability · boolean · optionalExample request body · replace placeholders
{
"Name": "string",
"Count": 1,
"SharedCode": true,
"Description": "Example description",
"GroupPublicId": "00000000-0000-4000-8000-000000000123",
"TargetUserId": 123,
"CustomCode": "string",
"Prefix": "string",
"Type": "string",
"Value": 100,
"Currency": "USD",
"PerUserLimit": 1,
"MaximumTotalUses": 1,
"MaximumAggregateValue": 100,
"RequiresWhitelabelApproval": true,
"RequiresEmail2Fa": true,
"ValidFrom": "2026-08-05T09:30:00Z",
"ValidUntil": "2026-08-05T09:30:00Z",
"InitialStatus": "PENDING",
"ExternalReference": "external_reference_123",
"AcceptUnboundedLiability": true
}200OKVoucherJobResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"Kind": "string",
"Status": "PENDING",
"TotalItems": 1,
"SuccessfulItems": 1,
"FailedItems": 1,
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/assignmentsOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/assignments' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"VoucherId": "00000000-0000-4000-8000-000000000123",
"UserId": 123
}'Parameters
Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
VoucherId · string · requiredUserId · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"VoucherId": "00000000-0000-4000-8000-000000000123",
"UserId": 123
}202AcceptedNo response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/assignments/from-groupOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/assignments/from-group' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"GroupId": "00000000-0000-4000-8000-000000000123",
"UserId": 123
}'Parameters
Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
GroupId · string · requiredUserId · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
Example request body · replace placeholders
{
"GroupId": "00000000-0000-4000-8000-000000000123",
"UserId": 123
}200OKVoucherResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"GroupId": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"Description": "Example description",
"MaskedCode": "string",
"Type": "string",
"Value": 100,
"Currency": "USD",
"Status": "PENDING",
"SuccessfulUses": 1,
"ReservedUses": 1,
"PerUserLimit": 1,
"MaximumTotalUses": 1,
"RedeemedValue": 100,
"ReservedValue": 100,
"MaximumAggregateValue": 100,
"RequiresWhitelabelApproval": true,
"RequiresEmail2Fa": true,
"ValidFrom": "2026-08-05T09:30:00Z",
"ValidUntil": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"PlaintextCode": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/vouchers/{id}/status/{status}Open request and response documentationRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/vouchers/00000000-0000-4000-8000-000000000123/status/PENDING' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001'Parameters
idpathstringrequiredExample: 00000000-0000-4000-8000-000000000123statuspathstringrequiredExample: PENDINGIdempotency-KeyheaderstringoptionalExample: operation-customer-1042-001200OKVoucherResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"GroupId": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"Description": "Example description",
"MaskedCode": "string",
"Type": "string",
"Value": 100,
"Currency": "USD",
"Status": "PENDING",
"SuccessfulUses": 1,
"ReservedUses": 1,
"PerUserLimit": 1,
"MaximumTotalUses": 1,
"RedeemedValue": 100,
"ReservedValue": 100,
"MaximumAggregateValue": 100,
"RequiresWhitelabelApproval": true,
"RequiresEmail2Fa": true,
"ValidFrom": "2026-08-05T09:30:00Z",
"ValidUntil": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"PlaintextCode": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/{id}/revealOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/00000000-0000-4000-8000-000000000123/reveal' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001'Parameters
idpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001200OKVoucherCodeResponse
{
"code": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/redemptionsOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/redemptions' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"Code": "string"
}'Parameters
Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
UserId · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
Code · string · requiredExample request body · replace placeholders
{
"UserId": 123,
"Code": "string"
}200OKVoucherRedemptionResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"VoucherId": "00000000-0000-4000-8000-000000000123",
"VoucherName": "string",
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"TransactionReference": "external_reference_123",
"ErrorCode": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/validateOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/validate' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"Code": "string"
}'Request fields and validation
UserId · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
Code · string · requiredExample request body · replace placeholders
{
"UserId": 123,
"Code": "string"
}200OKVoucherValidationResponse
{
"Valid": true,
"Amount": 100,
"Currency": "USD",
"RequiresEmailVerification": true,
"RequiresApproval": true
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/redemptions/{id}/verification/resendOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/redemptions/00000000-0000-4000-8000-000000000123/verification/resend?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001'Parameters
idpathstringrequiredExample: 00000000-0000-4000-8000-000000000123userIdqueryintegeroptionalExample: 123Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001202AcceptedNo response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/redemptions/{id}/verifyOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/redemptions/00000000-0000-4000-8000-000000000123/verify?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"Code": "string"
}'Parameters
idpathstringrequiredExample: 00000000-0000-4000-8000-000000000123userIdqueryintegeroptionalExample: 123Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
Code · string · requiredExample request body · replace placeholders
{
"Code": "string"
}200OKVoucherRedemptionResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"VoucherId": "00000000-0000-4000-8000-000000000123",
"VoucherName": "string",
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"TransactionReference": "external_reference_123",
"ErrorCode": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/vouchers/redemptions/{id}Open request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers/redemptions/00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
idpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKVoucherRedemptionResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"VoucherId": "00000000-0000-4000-8000-000000000123",
"VoucherName": "string",
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"TransactionReference": "external_reference_123",
"ErrorCode": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
DELETE/api/v2/vouchers/redemptions/{id}Open request and response documentationRequest & responses +
curl --request DELETE 'https://staging.hoppa.global/api/v2/vouchers/redemptions/00000000-0000-4000-8000-000000000123?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001'Parameters
idpathstringrequiredExample: 00000000-0000-4000-8000-000000000123userIdqueryintegeroptionalExample: 123Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001200OKVoucherRedemptionResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"VoucherId": "00000000-0000-4000-8000-000000000123",
"VoucherName": "string",
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"TransactionReference": "external_reference_123",
"ErrorCode": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/vouchers/approvalsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers/approvals' \
-H 'x-api-key: YOUR_API_KEY'200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"VoucherId": "00000000-0000-4000-8000-000000000123",
"VoucherName": "string",
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"TransactionReference": "external_reference_123",
"ErrorCode": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/approvals/{id}Open request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/approvals/00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"Reason": "string",
"Approve": true,
"Notes": "string"
}'Parameters
idpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
Approve · boolean · optionalReason · string · requiredMaximum length: 500
Notes · string or null · optionalMaximum length: 2000
Example request body · replace placeholders
{
"Reason": "string",
"Approve": true,
"Notes": "string"
}200OKVoucherRedemptionResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"VoucherId": "00000000-0000-4000-8000-000000000123",
"VoucherName": "string",
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"TransactionReference": "external_reference_123",
"ErrorCode": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/vouchers/liabilityOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers/liability' \
-H 'x-api-key: YOUR_API_KEY'200OKapplication/json
[
{
"Currency": "USD",
"Outstanding": 100,
"Reserved": 100,
"Unbounded": true
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/liability/previewOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/liability/preview' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Name": "string",
"Description": "Example description",
"GroupPublicId": "00000000-0000-4000-8000-000000000123",
"TargetUserId": 123,
"CustomCode": "string",
"Prefix": "string",
"Type": "string",
"Value": 100,
"Currency": "USD",
"PerUserLimit": 1,
"MaximumTotalUses": 1,
"MaximumAggregateValue": 100,
"RequiresWhitelabelApproval": true,
"RequiresEmail2Fa": true,
"ValidFrom": "2026-08-05T09:30:00Z",
"ValidUntil": "2026-08-05T09:30:00Z",
"InitialStatus": "PENDING",
"ExternalReference": "external_reference_123",
"AcceptUnboundedLiability": true
}'Request fields and validation
Name · string · requiredMaximum length: 160
Description · string or null · optionalMaximum length: 2000
GroupPublicId · string or null · optionalTargetUserId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
CustomCode · string or null · optionalPrefix · string or null · optionalMaximum length: 20
Type · string or null · optionalValue · number or null · optionalMinimum: 1e-10
Maximum: 7.922816251426434e+28
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Currency · string or null · optionalPerUserLimit · integer or null · optionalMinimum: 1
Maximum: 2147483647
Pattern: ^-?(?:0|[1-9]\d*)$
MaximumTotalUses · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
MaximumAggregateValue · number or null · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
RequiresWhitelabelApproval · boolean · optionalRequiresEmail2Fa · boolean · optionalValidFrom · string or null · optionalValidUntil · string or null · optionalInitialStatus · string · optionalExternalReference · string or null · optionalAcceptUnboundedLiability · boolean · optionalExample request body · replace placeholders
{
"Name": "string",
"Description": "Example description",
"GroupPublicId": "00000000-0000-4000-8000-000000000123",
"TargetUserId": 123,
"CustomCode": "string",
"Prefix": "string",
"Type": "string",
"Value": 100,
"Currency": "USD",
"PerUserLimit": 1,
"MaximumTotalUses": 1,
"MaximumAggregateValue": 100,
"RequiresWhitelabelApproval": true,
"RequiresEmail2Fa": true,
"ValidFrom": "2026-08-05T09:30:00Z",
"ValidUntil": "2026-08-05T09:30:00Z",
"InitialStatus": "PENDING",
"ExternalReference": "external_reference_123",
"AcceptUnboundedLiability": true
}200OKapplication/json
[
{
"Currency": "USD",
"Outstanding": 100,
"Reserved": 100,
"Unbounded": true
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/redemptions/{id}/retryOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/redemptions/00000000-0000-4000-8000-000000000123/retry' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001'Parameters
idpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001200OKVoucherRedemptionResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"VoucherId": "00000000-0000-4000-8000-000000000123",
"VoucherName": "string",
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"TransactionReference": "external_reference_123",
"ErrorCode": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/vouchers/rulesOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers/rules' \
-H 'x-api-key: YOUR_API_KEY'200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"TriggerType": "string",
"CampaignMode": "string",
"Enabled": true,
"AssignmentCount": 1,
"AssignedValue": 100
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/rulesOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/rules' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"Name": "string",
"TriggerType": "string",
"CampaignMode": "string",
"VoucherGroupId": "00000000-0000-4000-8000-000000000123",
"SharedVoucherId": "00000000-0000-4000-8000-000000000123",
"ThresholdAmount": 100,
"ThresholdCurrency": "USD",
"MaximumAssignments": 1,
"MaximumAssignedValue": 100,
"ValidFrom": "2026-08-05T09:30:00Z",
"ValidUntil": "2026-08-05T09:30:00Z",
"Criteria": {},
"VoucherTemplate": {}
}'Parameters
Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
Name · string · requiredTriggerType · string · requiredCampaignMode · string · requiredVoucherGroupId · string or null · optionalSharedVoucherId · string or null · optionalThresholdAmount · number or null · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
ThresholdCurrency · string or null · optionalMaximumAssignments · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
MaximumAssignedValue · number or null · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
ValidFrom · string or null · optionalValidUntil · string or null · optionalCriteria · value · optionalVoucherTemplate · value · optionalExample request body · replace placeholders
{
"Name": "string",
"TriggerType": "string",
"CampaignMode": "string",
"VoucherGroupId": "00000000-0000-4000-8000-000000000123",
"SharedVoucherId": "00000000-0000-4000-8000-000000000123",
"ThresholdAmount": 100,
"ThresholdCurrency": "USD",
"MaximumAssignments": 1,
"MaximumAssignedValue": 100,
"ValidFrom": "2026-08-05T09:30:00Z",
"ValidUntil": "2026-08-05T09:30:00Z",
"Criteria": {},
"VoucherTemplate": {}
}200OKVoucherRuleResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"TriggerType": "string",
"CampaignMode": "string",
"Enabled": true,
"AssignmentCount": 1,
"AssignedValue": 100
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/vouchers/rules/{id}/enabled/{enabled}Open request and response documentationRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/vouchers/rules/00000000-0000-4000-8000-000000000123/enabled/true' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001'Parameters
idpathstringrequiredExample: 00000000-0000-4000-8000-000000000123enabledpathbooleanrequiredExample: trueIdempotency-KeyheaderstringoptionalExample: operation-customer-1042-001204No ContentNo response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/imports/previewOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/imports/preview' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data '{
"ContentType": "string",
"ContentDisposition": "string",
"Headers": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Length": 1,
"Name": "string",
"FileName": "string"
}'Parameters
Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
ContentType · string · optionalContentDisposition · string · optionalHeaders · object · optionalLength · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
Name · string · optionalFileName · string · optionalExample request body · replace placeholders
{
"ContentType": "string",
"ContentDisposition": "string",
"Headers": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Length": 1,
"Name": "string",
"FileName": "string"
}200OKVoucherImportPreviewResponse
{
"JobId": "00000000-0000-4000-8000-000000000123",
"Status": "PENDING",
"TotalRows": 1,
"ValidRows": 1,
"InvalidRows": 1,
"Rows": [
{
"Row": 1,
"Valid": true,
"ErrorCode": "string",
"ErrorMessage": "string",
"Name": "string",
"Value": 100,
"Currency": "USD",
"Type": "string",
"UserId": 123
}
]
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/vouchers/imports/templateOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers/imports/template' \
-H 'x-api-key: YOUR_API_KEY'200OKtext/csv
stringExamples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/imports/{id}/confirmOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/imports/00000000-0000-4000-8000-000000000123/confirm' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"Mode": "string"
}'Parameters
idpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
Mode · string · optionalPattern: ^(ALL_OR_NOTHING|VALID_ROWS_ONLY)$
Example request body · replace placeholders
{
"Mode": "string"
}200OKVoucherJobResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"Kind": "string",
"Status": "PENDING",
"TotalItems": 1,
"SuccessfulItems": 1,
"FailedItems": 1,
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/assignments/massOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/assignments/mass' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"VoucherId": "00000000-0000-4000-8000-000000000123",
"UserIds": [
1
],
"UserIdentifiers": [
"string"
],
"TierIds": [
1
],
"CardTypes": [
"string"
],
"TransactionTypes": [
"string"
],
"TransactionFrom": "2026-08-05T09:30:00Z",
"TransactionTo": "2026-08-05T09:30:00Z",
"MinimumCompletedTransactionVolume": 100,
"TransactionCurrency": "USD"
}'Parameters
Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
VoucherId · string · requiredUserIds · array · optionalUserIdentifiers · array · optionalTierIds · array · optionalCardTypes · array · optionalTransactionTypes · array · optionalTransactionFrom · string or null · optionalTransactionTo · string or null · optionalMinimumCompletedTransactionVolume · number or null · optionalMinimum: 0
Maximum: 7.922816251426434e+28
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
TransactionCurrency · string or null · optionalExample request body · replace placeholders
{
"VoucherId": "00000000-0000-4000-8000-000000000123",
"UserIds": [
1
],
"UserIdentifiers": [
"string"
],
"TierIds": [
1
],
"CardTypes": [
"string"
],
"TransactionTypes": [
"string"
],
"TransactionFrom": "2026-08-05T09:30:00Z",
"TransactionTo": "2026-08-05T09:30:00Z",
"MinimumCompletedTransactionVolume": 100,
"TransactionCurrency": "USD"
}200OKVoucherJobResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"Kind": "string",
"Status": "PENDING",
"TotalItems": 1,
"SuccessfulItems": 1,
"FailedItems": 1,
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/vouchers/jobsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers/jobs' \
-H 'x-api-key: YOUR_API_KEY'200OKapplication/json
[
{
"Id": "00000000-0000-4000-8000-000000000123",
"Kind": "string",
"Status": "PENDING",
"TotalItems": 1,
"SuccessfulItems": 1,
"FailedItems": 1,
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/vouchers/jobs/{id}Open request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers/jobs/00000000-0000-4000-8000-000000000123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
idpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKVoucherJobResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"Kind": "string",
"Status": "PENDING",
"TotalItems": 1,
"SuccessfulItems": 1,
"FailedItems": 1,
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/vouchers/jobs/{id}/itemsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers/jobs/00000000-0000-4000-8000-000000000123/items' \
-H 'x-api-key: YOUR_API_KEY'Parameters
idpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKapplication/json
[
{
"ItemIndex": 1,
"Status": "PENDING",
"ExternalKey": "string",
"ErrorCode": "string",
"ErrorMessage": "string",
"Result": "string"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/jobs/{id}/retryOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/jobs/00000000-0000-4000-8000-000000000123/retry' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001'Parameters
idpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001200OKVoucherJobResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"Kind": "string",
"Status": "PENDING",
"TotalItems": 1,
"SuccessfulItems": 1,
"FailedItems": 1,
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/vouchers/jobs/{id}/codes/exportOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers/jobs/00000000-0000-4000-8000-000000000123/codes/export' \
-H 'x-api-key: YOUR_API_KEY'Parameters
idpathstringrequiredExample: 00000000-0000-4000-8000-000000000123200OKtext/csv
stringExamples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/vouchers/redemptions/{id}/reversalOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/vouchers/redemptions/00000000-0000-4000-8000-000000000123/reversal' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Idempotency-Key: operation-customer-1042-001' \
-H 'Content-Type: application/json' \
--data '{
"Reason": "string",
"RestoreUse": true,
"DryRun": true,
"Confirm": true
}'Parameters
idpathstringrequiredExample: 00000000-0000-4000-8000-000000000123Idempotency-KeyheaderstringoptionalExample: operation-customer-1042-001Request fields and validation
Reason · string · requiredMaximum length: 500
RestoreUse · boolean · optionalDryRun · boolean · optionalConfirm · boolean · optionalExample request body · replace placeholders
{
"Reason": "string",
"RestoreUse": true,
"DryRun": true,
"Confirm": true
}200OKVoucherReversalResponse
{
"Id": "00000000-0000-4000-8000-000000000123",
"RedemptionId": "00000000-0000-4000-8000-000000000123",
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"RestoreUse": true,
"DryRun": true,
"TransactionReference": "external_reference_123"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/vouchers/reports/redemptionsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers/reports/redemptions?from=2026-08-05T09%3A30%3A00Z&to=2026-08-05T09%3A30%3A00Z&status=PENDING¤cy=USD' \
-H 'x-api-key: YOUR_API_KEY'Parameters
fromquerystringoptionalExample: 2026-08-05T09:30:00ZtoquerystringoptionalExample: 2026-08-05T09:30:00ZstatusquerystringoptionalExample: PENDINGcurrencyquerystringoptionalExample: USD200OKapplication/json
[
{
"RedemptionId": "00000000-0000-4000-8000-000000000123",
"VoucherId": "00000000-0000-4000-8000-000000000123",
"VoucherName": "string",
"UserId": 123,
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"ErrorCode": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/vouchers/reports/daily-statisticsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers/reports/daily-statistics?from=2026-08-05&to=2026-08-05' \
-H 'x-api-key: YOUR_API_KEY'Parameters
fromquerystringoptionalExample: 2026-08-05toquerystringoptionalExample: 2026-08-05200OKapplication/json
[
{
"Date": "2026-08-05",
"Currency": "USD",
"IssuedCount": 1,
"IssuedValue": 100,
"RedeemedCount": 1,
"RedeemedValue": 100,
"FailedCount": 1,
"ReversedCount": 1
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/vouchers/reports/liability-snapshotsOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers/reports/liability-snapshots?from=2026-08-05&to=2026-08-05' \
-H 'x-api-key: YOUR_API_KEY'Parameters
fromquerystringoptionalExample: 2026-08-05toquerystringoptionalExample: 2026-08-05200OKapplication/json
[
{
"Date": "2026-08-05",
"Currency": "USD",
"Outstanding": 100,
"Reserved": 100,
"Unbounded": true
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/vouchers/reports/{report}/exportOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers/reports/example/export' \
-H 'x-api-key: YOUR_API_KEY'Parameters
reportpathstringrequiredExample: example200OKtext/csv
stringExamples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/vouchers/auditOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/vouchers/audit?page=1&pageSize=100' \
-H 'x-api-key: YOUR_API_KEY'Parameters
pagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 100200OKapplication/json
[
{
"Id": 123,
"UserId": 123,
"ApiKeyId": 123,
"ActorType": "string",
"Action": "string",
"TargetType": "string",
"TargetId": "string",
"Status": "PENDING",
"CorrelationId": "string",
"Timestamp": "2026-08-05T09:30:00Z"
}
]Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
ReferralAttributionQuotes1 operations
POST/api/v2/referral-attribution-quotesService-only preflight. The exact displayed offer is immutable; a quote reserves no funds.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/referral-attribution-quotes' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"ReferralCode": "string",
"Source": "string",
"RegistrationAttemptId": "00000000-0000-4000-8000-000000000123",
"InvitationToken": "string",
"VerifiedEmailInvitationId": "00000000-0000-4000-8000-000000000123",
"VerifiedUserId": 123,
"Locale": "string"
}'Request fields and validation
RegistrationAttemptId · string · optionalReferralCode · string · requiredMinimum length: 0
Maximum length: 128
Source · string · requiredMinimum length: 0
Maximum length: 32
InvitationToken · string or null · optionalMinimum length: 0
Maximum length: 512
VerifiedEmailInvitationId · string or null · optionalVerifiedUserId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
Locale · string · optionalMinimum length: 0
Maximum length: 32
Example request body · replace placeholders
{
"ReferralCode": "string",
"Source": "string",
"RegistrationAttemptId": "00000000-0000-4000-8000-000000000123",
"InvitationToken": "string",
"VerifiedEmailInvitationId": "00000000-0000-4000-8000-000000000123",
"VerifiedUserId": 123,
"Locale": "string"
}200OKReferralAttributionQuoteResponse
{
"QuoteId": "00000000-0000-4000-8000-000000000123",
"RegistrationAttemptId": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"ExpectedOfferVersionId": "00000000-0000-4000-8000-000000000123",
"TermsVersion": 1,
"TermsText": "string",
"TermsHash": "string",
"PolicyHash": "string",
"QuotedAt": "2026-08-05T09:30:00Z",
"ExpiresAt": "2026-08-05T09:30:00Z",
"Status": "PENDING",
"Locale": "string",
"Boosts": [
{
"Id": "00000000-0000-4000-8000-000000000123",
"Name": "string",
"Kind": "string",
"StartsAt": "2026-08-05T09:30:00Z",
"EndsAt": "2026-08-05T09:30:00Z",
"Multiplier": 100,
"QualifiedFriendCount": 1,
"MilestoneAmount": 100,
"MaximumIncrementalReward": 100,
"Currency": "USD"
}
],
"EligibilityNotice": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
ReferralInvitations1 operations
GET/api/v2/referral-invitations/previewResolves a signed invitation so a registration client can prefill its bound email and referral code.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/referral-invitations/preview?token=USDC' \
-H 'x-api-key: YOUR_API_KEY'Parameters
tokenquerystringoptionalExample: USDC200OKReferralInvitationPreviewResponse
{
"Email": "user@example.com",
"ReferralCode": "string",
"InviterDisplayName": "string",
"ExpiresAt": "2026-08-05T09:30:00Z",
"ReferredTierId": 123,
"WelcomeAmount": 0,
"WelcomeCurrency": "USD",
"TermsVersion": 1
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
Swap2 operations
POST/api/v2/swaptokens/swapOpen request and response documentationRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/swaptokens/swap' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"TokenIn": "string",
"TokenOut": "string",
"AmountIn": "100.00",
"Slippage": 100,
"ChainIdIn": 1,
"ChainIdOut": 1,
"FromAddress": "0x1111111111111111111111111111111111111111",
"ToAddress": "0x1111111111111111111111111111111111111111"
}'Request fields and validation
UserId · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
TokenIn · string · optionalTokenOut · string · optionalAmountIn · string · optionalSlippage · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$
ChainIdIn · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
ChainIdOut · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
FromAddress · string · optionalToAddress · string · optionalExample request body · replace placeholders
{
"UserId": 123,
"TokenIn": "string",
"TokenOut": "string",
"AmountIn": "100.00",
"Slippage": 100,
"ChainIdIn": 1,
"ChainIdOut": 1,
"FromAddress": "0x1111111111111111111111111111111111111111",
"ToAddress": "0x1111111111111111111111111111111111111111"
}200OKSwapResponse
{
"Transaction": {
"to": "string",
"data": "string",
"value": "string",
"abi": "string",
"args": [
{}
]
},
"Route": {
"query": {
"params": {
"chainIdIn": 1,
"chainIdOut": 1,
"tokenIn": "string",
"tokenOut": "string",
"amountIn": "100.00"
},
"slippage": 100,
"from": "string",
"recipient": "string"
},
"route": [
{
"pool": {
"lp": {
"chainId": {},
"address": {},
"name": {},
"symbol": {},
"decimals": {},
"tags": {},
"permit": {}
},
"decimals": [
{}
],
"coins": [
{}
],
"address": "string",
"underlyingCoins": [
{}
],
"type": "string"
},
"fees": [
{
"type": {},
"token": {},
"percent": {},
"amount": {}
}
],
"priceImpact": "string",
"params": {
"tokenIn": {
"chainId": {},
"address": {},
"name": {},
"symbol": {},
"decimals": {},
"chainName": {},
"originalName": {},
"originalSymbol": {},
"tags": {},
"synthTags": {},
"permit": {}
},
"chainIdIn": 1,
"tokenOut": {
"chainId": {},
"address": {},
"name": {},
"symbol": {},
"decimals": {},
"chainName": {},
"originalName": {},
"originalSymbol": {},
"tags": {},
"synthTags": {},
"permit": {}
},
"chainIdOut": 1,
"amountIn": "100.00",
"amountInWithoutSlippage": "100.00",
"amountOut": "100.00",
"amountOutWithoutSlippage": "100.00",
"slippage": 100
},
"type": "string",
"chainId": 123
}
],
"amountIn": "100.00",
"amountInWithoutSlippage": "100.00",
"amountOut": "100.00",
"amountOutWithoutSlippage": "100.00",
"tokenInPrice": 100,
"tokenOutPrice": 100,
"priceImpact": 100,
"totalFee": {
"type": "string",
"amount": "100.00",
"percent": "string"
},
"signature": "string"
},
"TransactionId": 123
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/swaptokens/historyOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/swaptokens/history?userId=123&page=1&pageSize=20' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123pagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 20200OKSwapTokensHistoryGetSwapHistoryResponse
{
"transactions": [
{
"id": 123,
"userId": 123,
"companyId": 123,
"tokenIn": "string",
"tokenOut": "string",
"amountIn": 100,
"amountOut": 100,
"txHash": "string",
"status": "PENDING",
"routeDetails": "string",
"createdAt": "2026-08-05T09:30:00Z",
"updatedAt": "2026-08-05T09:30:00Z"
}
],
"pagination": {
"page": 1,
"pageSize": 1,
"totalCount": 1,
"totalPages": 1,
"hasMore": true
}
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
Tiers2 operations
GET/api/v2/tiersGet company tiers for the authenticated companyRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/tiers' \
-H 'x-api-key: YOUR_API_KEY'200OKGetTiersResponseV2
{
"Tiers": [
{
"Id": 123,
"Name": "string",
"Description": "Example description",
"TierLevel": 1,
"AccountType": "string",
"MonthlyFee": 100,
"YearlyFee": 100,
"Features": [
"string"
],
"Limits": {},
"IsDefault": true,
"IsActive": true,
"IsHidden": true,
"StripeAccountOwnerOverride": "string",
"IncludesEqualsCards": true,
"IncludesEqualsIban": true,
"EuPriceTableId": "string",
"UkPriceTableId": "string",
"UsPriceTableId": "string",
"UpPriceTableId": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}
]
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}403ForbiddenErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/tiers/card-tier/{cardTierId}Get all card type tiers for a specific tier ID for the authenticated companyRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/tiers/card-tier/123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
cardTierIdpathintegerrequiredExample: 123200OKGetCardTypeTierResponseV2
{
"CardTypeTiers": [
{
"CardTypeSecondaryId": 123,
"CardTypeId": 123,
"TierId": 123,
"BinRangeOverrideId": 123,
"EffectiveBinRangeId": 123,
"FreeCardsIncluded": 1,
"FreeCardsPeriod": "string",
"MonthlySubscriptionFee": 100,
"YearlySubscriptionFee": 100,
"MaxCards": 1,
"IsActive": true,
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CardType": {
"Id": 123,
"Name": "string",
"Code": "string",
"Description": "Example description",
"Features": [
"string"
],
"MonthlyFee": 100,
"IssuanceFee": 100,
"CurrencyCode": "USD",
"Limits": {},
"Benefits": [
"string"
],
"AvailableDesigns": [
"string"
],
"IssuanceTime": "string",
"IsEnabled": true,
"CompanyId": 123,
"RequiresKycLevel": "string",
"MonthlySubscriptionFee": 100,
"YearlySubscriptionFee": 100,
"SubscriptionFeatures": [
"string"
],
"BaseFeatures": [
"string"
],
"LoadOptions": [
"string"
],
"ReplacementFee": 100,
"AtmWithdrawalFee": 100,
"IsVirtual": true,
"IsPhysical": true,
"CardNetwork": "string",
"CardImageUrl": "https://example.com/callback",
"CardThumbnailUrl": "https://example.com/callback",
"CardPreviewUrl": "https://example.com/callback",
"CardBackImageUrl": "https://example.com/callback",
"CardBackThumbnailUrl": "https://example.com/callback",
"CardBackPreviewUrl": "https://example.com/callback",
"CardImageAlt": "BASE64_ENCODED_DATA",
"CardTextColor": "string",
"Provider": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z"
}
}
]
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}403ForbiddenErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
Transactions7 operations
GET/api/v2/transactionsGet paginated transactions with advanced filteringRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/transactions?page=1&pageSize=20&types=example&statuses=example&startDate=2026-08-05T09%3A30%3A00Z&endDate=2026-08-05T09%3A30%3A00Z' \
-H 'x-api-key: YOUR_API_KEY'Parameters
pagequeryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 20typesqueryarrayoptionalExample: examplestatusesqueryarrayoptionalExample: examplestartDatequerystringoptionalExample: 2026-08-05T09:30:00ZendDatequerystringoptionalExample: 2026-08-05T09:30:00ZsearchquerystringoptionalExample: exampletradeIdquerystringoptionalExample: 123minAmountquerynumberoptionalExample: 100maxAmountquerynumberoptionalExample: 100sourcesqueryarrayoptionalExample: examplecardIdsqueryarrayoptionalExample: 789walletIdsqueryarrayoptionalExample: 123sortByquerystringoptionalExample: datesortOrderquerystringoptionalExample: descuserIdqueryintegeroptionalExample: 123200OKPaginatedTransactionResponse
{
"Data": [
{
"Id": 123,
"ExternalTransactionId": "external_reference_123",
"TradeId": "string",
"RelatedCardTransactionId": "string",
"TransactionGroupId": "string",
"ParentTransactionId": 123,
"RelationType": "string",
"IsPrimary": true,
"Type": "string",
"Description": "Example description",
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"TransactionDate": "2026-08-05T09:30:00Z",
"MerchantName": "string",
"MerchantCategory": "string",
"Category": "string",
"CardId": 123,
"WalletId": 123,
"Source": "string",
"FeeAmount": 100,
"FeeCurrency": "USD",
"Metadata": {}
}
],
"Pagination": {
"Page": 1,
"PageSize": 1,
"Total": 1,
"TotalPages": 1,
"HasPrevious": true,
"HasNext": true
},
"Stats": {
"TotalCount": 1,
"TotalAmount": 100,
"AmountByCurrency": {
"FIELD_FROM_APPLICATION": 100
},
"CountByType": {
"FIELD_FROM_APPLICATION": 1
},
"AmountByType": {
"FIELD_FROM_APPLICATION": 100
},
"CountByStatus": {
"FIELD_FROM_APPLICATION": 1
}
}
}400Bad RequestProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server ErrorBody unspecified
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/transactions/syncSync current user's transactions with Crypto cards (Quantum Account). Adds any missing transactions by external_id.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/transactions/sync?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123200OKapplication/json
{}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server ErrorBody unspecified
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/transactions/{id}Get transaction by IDRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/transactions/123?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
idpathintegerrequiredExample: 123userIdqueryintegeroptionalExample: 123200OKTransactionDetailResponse
{
"UserId": 123,
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"AccountId": 123,
"Id": 123,
"ExternalTransactionId": "external_reference_123",
"TradeId": "string",
"RelatedCardTransactionId": "string",
"TransactionGroupId": "string",
"ParentTransactionId": 123,
"RelationType": "string",
"IsPrimary": true,
"Type": "string",
"Description": "Example description",
"Amount": 100,
"Currency": "USD",
"Status": "PENDING",
"TransactionDate": "2026-08-05T09:30:00Z",
"MerchantName": "string",
"MerchantCategory": "string",
"Category": "string",
"CardId": 123,
"WalletId": 123,
"Source": "string",
"FeeAmount": 100,
"FeeCurrency": "USD",
"Metadata": {}
}404Not FoundProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server ErrorBody unspecified
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/transactions/{id}/equals-money/payment-confirmationOpen request and response documentationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/transactions/123/equals-money/payment-confirmation?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
idpathintegerrequiredExample: 123userIdqueryintegeroptionalExample: 123200OKFileResult
{
"ContentType": "string",
"FileDownloadName": "string",
"LastModified": "2026-08-05T09:30:00Z",
"EntityTag": {
"Tag": {
"Buffer": "string",
"Offset": 1,
"Length": 1,
"Value": "string",
"HasValue": true
},
"IsWeak": true
},
"EnableRangeProcessing": true
}400Bad RequestProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}404Not FoundProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/transactions/statsGet transaction statisticsRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/transactions/stats?startDate=2026-08-05T09%3A30%3A00Z&endDate=2026-08-05T09%3A30%3A00Z&userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
startDatequerystringoptionalExample: 2026-08-05T09:30:00ZendDatequerystringoptionalExample: 2026-08-05T09:30:00ZuserIdqueryintegeroptionalExample: 123200OKTransactionStatisticsResponse
{
"TotalTransactions": 1,
"TotalAmount": 100,
"AverageAmount": 100,
"AmountByCurrency": {
"FIELD_FROM_APPLICATION": 100
},
"CountByType": {
"FIELD_FROM_APPLICATION": 1
},
"CountByStatus": {
"FIELD_FROM_APPLICATION": 1
},
"DailyVolume": [
{
"Date": "2026-08-05T09:30:00Z",
"Volume": 100,
"Count": 1
}
],
"TopMerchants": [
{
"MerchantName": "string",
"TotalAmount": 100,
"TransactionCount": 1
}
]
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server ErrorBody unspecified
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/transactions/exportExport transactions in CSV or PDF formatRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/transactions/export?format=csv&types=example&statuses=example&startDate=2026-08-05T09%3A30%3A00Z&endDate=2026-08-05T09%3A30%3A00Z&search=example' \
-H 'x-api-key: YOUR_API_KEY'Parameters
formatquerystringoptionalExample: csvtypesqueryarrayoptionalExample: examplestatusesqueryarrayoptionalExample: examplestartDatequerystringoptionalExample: 2026-08-05T09:30:00ZendDatequerystringoptionalExample: 2026-08-05T09:30:00ZsearchquerystringoptionalExample: exampleminAmountquerynumberoptionalExample: 100maxAmountquerynumberoptionalExample: 100sourcesqueryarrayoptionalExample: examplecardIdsqueryarrayoptionalExample: 789walletIdsqueryarrayoptionalExample: 123userIdqueryintegeroptionalExample: 123200OKFileResult
{
"ContentType": "string",
"FileDownloadName": "string",
"LastModified": "2026-08-05T09:30:00Z",
"EntityTag": {
"Tag": {
"Buffer": "string",
"Offset": 1,
"Length": 1,
"Value": "string",
"HasValue": true
},
"IsWeak": true
},
"EnableRangeProcessing": true
}400Bad RequestProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server ErrorBody unspecified
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/transactions/top-upProcesses a wallet top-up operation using external payment methods.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/transactions/top-up' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Token": "USDC",
"WalletAddress": "0x1111111111111111111111111111111111111111",
"Value": 100
}'Request fields and validation
Token · string · optionalWalletAddress · string · optionalValue · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Example request body · replace placeholders
{
"Token": "USDC",
"WalletAddress": "0x1111111111111111111111111111111111111111",
"Value": 100
}200OKTopUpResponse
{
"Success": true,
"TransakUrl": "https://example.com/callback",
"OrderId": "string",
"Token": "USDC",
"Value": 100,
"WalletAddress": "0x1111111111111111111111111111111111111111",
"Message": "string",
"ErrorCode": "string",
"ErrorMessage": "string",
"Fee": 100,
"RequestedValue": 100,
"GrossValue": 100,
"IsPartial": true,
"CreatedAt": "2026-08-05T09:30:00Z",
"Configuration": {
"FiatCurrency": "USD",
"CryptoCurrency": "USDC",
"Network": "string",
"MinAmount": 100,
"MaxAmount": 100,
"IsTestMode": true
}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
Transfers18 operations
GET/api/v2/transfers/{transferId}Get transfer by IDRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/transfers/123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
transferIdpathintegerrequiredExample: 123200OKTransferResponseV2
{
"Id": 123,
"UserId": 123,
"Status": "PENDING",
"Amount": "100.00",
"Currency": "USD",
"SourceType": "CRYPTO_ASSETS",
"DestinationType": "CRYPTO_ASSETS",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"Metadata": {},
"TransferType": "string",
"Message": "string",
"ErrorCode": "string",
"FeeAmount": "100.00",
"FeeCurrency": "USD",
"FeeType": "None",
"NetAmount": "100.00"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/transfers/user-to-masterCreate a transfer from user to master accountRequest & responses +
Company API-key operation for a selected user in the key's company; no user identity claim is required on the API key. Implicit mandate selection uses the newest eligible active mandate for that user/company/currency, skipping exhausted or invalid terms before reserving allowance. Use the existing externalReferenceId for durable replay of the original collection, including a completed one-time mandate. Conflicting amount/currency returns 400 INVALID_TRANSFER_REQUEST. Pending/uncertain provider outcomes remain pending/PROCESSING rather than completed; check the recorded transfer and reconcile before another dispatch. Amount must be positive, with at most six decimal places for USDT/USDC and two for other currencies. Invalid precision returns 400 INVALID_TRANSFER_REQUEST. Mandate allowance is reserved before provider dispatch across payment collections and user-to-master transfers. Outstanding, uncertain and completed collections count toward the period allowance. A one-time mandate allows one outstanding/completed collection; definite no-debit outcomes release the reservation. Unresolved historical operations also count.
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/user-to-master' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"Amount": "100.00",
"Currency": "USD",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"Metadata": {}
}'Request fields and validation
UserId · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
Amount · string · requiredAmount must be positive, with at most six decimal places for USDT/USDC and two for other currencies. Invalid precision returns 400 INVALID_TRANSFER_REQUEST.
Currency · string · requiredDescription · string or null · optionalExternalReferenceId · string or null · optionalOptional stable collection reference within company/user. Repeating the same amount/currency replays the recorded transfer without redispatch; conflicting terms return 400 INVALID_TRANSFER_REQUEST.
Metadata · object or null · optionalExample request body · replace placeholders
{
"UserId": 123,
"Amount": "100.00",
"Currency": "USD",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"Metadata": {}
}201CreatedTransferResponseV2
{
"Id": 123,
"UserId": 123,
"Status": "PENDING",
"Amount": "100.00",
"Currency": "USD",
"SourceType": "CRYPTO_ASSETS",
"DestinationType": "CRYPTO_ASSETS",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"Metadata": {},
"TransferType": "string",
"Message": "string",
"ErrorCode": "string",
"FeeAmount": "100.00",
"FeeCurrency": "USD",
"FeeType": "None",
"NetAmount": "100.00"
}400INVALID_TRANSFER_REQUEST: invalid request, currency precision, mandate terms/allowance or conflicting externalReferenceId.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/transfers/master-to-userCreate a transfer from master account to userRequest & responses +
Amount must be positive, with at most six decimal places for USDT/USDC and two for other currencies. Invalid precision returns 400 INVALID_TRANSFER_REQUEST.
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/master-to-user' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"Amount": "100.00",
"Currency": "USD",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"Metadata": {}
}'Request fields and validation
UserId · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
Amount · string · requiredAmount must be positive, with at most six decimal places for USDT/USDC and two for other currencies. Invalid precision returns 400 INVALID_TRANSFER_REQUEST.
Currency · string · requiredDescription · string or null · optionalExternalReferenceId · string or null · optionalMetadata · object or null · optionalExample request body · replace placeholders
{
"UserId": 123,
"Amount": "100.00",
"Currency": "USD",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"Metadata": {}
}201CreatedTransferResponseV2
{
"Id": 123,
"UserId": 123,
"Status": "PENDING",
"Amount": "100.00",
"Currency": "USD",
"SourceType": "CRYPTO_ASSETS",
"DestinationType": "CRYPTO_ASSETS",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"Metadata": {},
"TransferType": "string",
"Message": "string",
"ErrorCode": "string",
"FeeAmount": "100.00",
"FeeCurrency": "USD",
"FeeType": "None",
"NetAmount": "100.00"
}400INVALID_TRANSFER_REQUEST: invalid request or currency precision.ErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/transfersList transfers with filtering and paginationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/transfers?pageNumber=1&pageSize=10&userId=123&status=PENDING¤cy=USD&dateFrom=2026-08-05' \
-H 'x-api-key: YOUR_API_KEY'Parameters
pageNumberqueryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 10userIdqueryintegeroptionalExample: 123statusqueryTransferStatusV2optionalExample: PENDINGcurrencyquerystringoptionalExample: USDdateFromquerystringoptionalExample: 2026-08-05dateToquerystringoptionalExample: 2026-08-05200OKTransferListResponseV2
{
"Transfers": [
{
"Id": 123,
"UserId": 123,
"Status": "PENDING",
"Amount": "100.00",
"Currency": "USD",
"SourceType": "CRYPTO_ASSETS",
"DestinationType": "CRYPTO_ASSETS",
"Description": "Example description",
"ExternalReferenceId": "external_reference_123",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"Metadata": {},
"TransferType": "string",
"Message": "string",
"ErrorCode": "string",
"FeeAmount": "100.00",
"FeeCurrency": "USD",
"FeeType": "None",
"NetAmount": "100.00"
}
],
"Total": 1,
"PageNumber": 1,
"PageSize": 1,
"TotalPages": 1
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/transfers/wallet-topupRequest a wallet top-up via TransakRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/wallet-topup?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Token": "USDC",
"WalletAddress": "0x1111111111111111111111111111111111111111",
"Value": 100
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
Token · string · optionalWalletAddress · string · optionalValue · number · optionalPattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Example request body · replace placeholders
{
"Token": "USDC",
"WalletAddress": "0x1111111111111111111111111111111111111111",
"Value": 100
}200OKTopUpResponse
{
"Success": true,
"TransakUrl": "https://example.com/callback",
"OrderId": "string",
"Token": "USDC",
"Value": 100,
"WalletAddress": "0x1111111111111111111111111111111111111111",
"Message": "string",
"ErrorCode": "string",
"ErrorMessage": "string",
"Fee": 100,
"RequestedValue": 100,
"GrossValue": 100,
"IsPartial": true,
"CreatedAt": "2026-08-05T09:30:00Z",
"Configuration": {
"FiatCurrency": "USD",
"CryptoCurrency": "USDC",
"Network": "string",
"MinAmount": 100,
"MaxAmount": 100,
"IsTestMode": true
}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/transfers/crypto-to-quantum-transferCreate a crypto-to-quantum transfer for internal account transfers (destination is always USD)Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/crypto-to-quantum-transfer?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"SourceCurrency": "USD",
"Amount": 100,
"DestinationCurrency": "USD"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
SourceCurrency · string · requiredDestinationCurrency · string · optionalDestination currency is always USD for quantum transfers
Amount · number · requiredMinimum: 0.01
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Example request body · replace placeholders
{
"SourceCurrency": "USD",
"Amount": 100,
"DestinationCurrency": "USD"
}200OKCryptoToQuantumTransferResponse
{
"Success": true,
"TransferId": "string",
"Message": "string",
"ErrorCode": "string",
"ErrorMessage": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"Details": {
"SourceCurrency": "USD",
"DestinationCurrency": "USD",
"Amount": 100,
"Status": "PENDING",
"InterlaceAccountId": "string",
"TransferPath": "string",
"RequiresExchange": true,
"ExchangeRate": 100,
"AvailableBalances": {
"FIELD_FROM_APPLICATION": 100
},
"RequiredAmount": 100,
"TotalAvailableValue": 100
}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/transfers/quantum-usd-to-crypto-exchangeExchange Quantum USD to Crypto (USDC/USDT)Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/quantum-usd-to-crypto-exchange?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Currency": "USD",
"Amount": 100
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
Currency · string · optionalTarget currency (USDC or USDT)
Amount · number · optionalAmount in USD to exchange from Quantum account
Pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$
Example request body · replace placeholders
{
"Currency": "USD",
"Amount": 100
}200OKQuantumToCryptoExchangeResponse
{
"Success": true,
"Message": "string",
"ErrorCode": "string",
"SourceAmount": 100,
"TargetCurrency": "USD",
"CryptoAmountReceived": 100,
"Rate": 100,
"Fee": 100,
"TradeId": "string",
"Status": "PENDING",
"InitiatedAt": "2026-08-05T09:30:00Z",
"Details": {
"FinalCryptoBalance": 100,
"FinalQuantumBalance": 100
}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/transfers/withdrawals/fee-and-quotaGet withdrawal fee and quota informationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/transfers/withdrawals/fee-and-quota?userId=123&chain=example&address=example¤cy=USD&amount=100.00' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123chainquerystringoptionalExample: exampleaddressquerystringoptionalExample: examplecurrencyquerystringoptionalExample: USDamountquerystringoptionalExample: 100.00200OKFeeAndQuotaResponse
{
"Code": "string",
"Message": "string",
"Data": {
"CrossChainQuota": "string",
"CrossChainFeeRate": "100.00",
"CrossChainAmount": "100.00",
"Fees": [
{
"Amount": "100.00",
"Currency": "USD",
"Type": "string"
}
]
}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/transfers/withdrawals/available-balanceGet available withdrawal balance for a userRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/transfers/withdrawals/available-balance?userId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123200OKAvailableWithdrawalBalanceResponse
{
"TotalAvailableUSDT": 100,
"TotalAvailableUSDC": 100,
"WalletBreakdown": [
{
"WalletType": "string",
"Currency": "USD",
"Balance": 100,
"USDValue": 100,
"USDTEquivalent": 100,
"USDCEquivalent": 100
}
],
"ExchangeRateUSDToUSDT": 100,
"ExchangeRateUSDToUSDC": 100
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/transfers/withdrawals/cryptoCreate an external crypto withdrawal (to blockchain address)Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/withdrawals/crypto' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"UserId": 123,
"Currency": "USD",
"Chain": "string",
"Amount": "100.00",
"DestinationAddress": "0x1111111111111111111111111111111111111111",
"ConfirmExchangeRate": true,
"Description": "Example description",
"Metadata": {}
}'Request fields and validation
UserId · integer · requiredPattern: ^-?(?:0|[1-9]\d*)$
Currency · string · requiredChain · string · requiredAmount · string · requiredDestinationAddress · string · requiredConfirmExchangeRate · boolean · requiredDescription · string or null · optionalMetadata · object or null · optionalExample request body · replace placeholders
{
"UserId": 123,
"Currency": "USD",
"Chain": "string",
"Amount": "100.00",
"DestinationAddress": "0x1111111111111111111111111111111111111111",
"ConfirmExchangeRate": true,
"Description": "Example description",
"Metadata": {}
}201CreatedExternalCryptoWithdrawalResponse
{
"Success": true,
"VerificationToken": "PLACEHOLDER_TOKEN",
"TransactionId": "string",
"InterlaceTransferId": "string",
"WithdrawalRequestId": 123,
"Status": "PENDING",
"ActualAmount": 100,
"Currency": "USD",
"Fees": [
{
"Amount": "100.00",
"Currency": "USD",
"Type": "string"
}
],
"Message": "string",
"OtpRequired": true,
"OtpExpiresAt": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}403ForbiddenErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}422Unprocessable EntityErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/transfers/withdrawals/crypto/confirmConfirm a crypto withdrawal with an emailed OTP codeRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/withdrawals/crypto/confirm' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"VerificationToken": "PLACEHOLDER_TOKEN",
"OtpCode": "string",
"UserId": 123,
"WithdrawalRequestId": 123
}'Request fields and validation
UserId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
WithdrawalRequestId · integer or null · optionalDeprecated legacy field. New requests use VerificationToken.
Pattern: ^-?(?:0|[1-9]\d*)$
VerificationToken · string · requiredOtpCode · string · requiredMinimum length: 8
Maximum length: 8
Example request body · replace placeholders
{
"VerificationToken": "PLACEHOLDER_TOKEN",
"OtpCode": "string",
"UserId": 123,
"WithdrawalRequestId": 123
}200OKExternalCryptoWithdrawalResponse
{
"Success": true,
"VerificationToken": "PLACEHOLDER_TOKEN",
"TransactionId": "string",
"InterlaceTransferId": "string",
"WithdrawalRequestId": 123,
"Status": "PENDING",
"ActualAmount": 100,
"Currency": "USD",
"Fees": [
{
"Amount": "100.00",
"Currency": "USD",
"Type": "string"
}
],
"Message": "string",
"OtpRequired": true,
"OtpExpiresAt": "2026-08-05T09:30:00Z"
}202AcceptedExternalCryptoWithdrawalResponse
{
"Success": true,
"VerificationToken": "PLACEHOLDER_TOKEN",
"TransactionId": "string",
"InterlaceTransferId": "string",
"WithdrawalRequestId": 123,
"Status": "PENDING",
"ActualAmount": 100,
"Currency": "USD",
"Fees": [
{
"Amount": "100.00",
"Currency": "USD",
"Type": "string"
}
],
"Message": "string",
"OtpRequired": true,
"OtpExpiresAt": "2026-08-05T09:30:00Z"
}400Bad RequestCryptoWithdrawalOtpErrorResponse
{
"RemainingAttempts": 1,
"IsExpired": true,
"IsLocked": true,
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundCryptoWithdrawalOtpErrorResponse
{
"RemainingAttempts": 1,
"IsExpired": true,
"IsLocked": true,
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/transfers/withdrawals/crypto/resendResend the OTP for a pending API crypto withdrawal.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/withdrawals/crypto/resend' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"VerificationToken": "PLACEHOLDER_TOKEN",
"UserId": 123
}'Request fields and validation
UserId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
VerificationToken · string · requiredExample request body · replace placeholders
{
"VerificationToken": "PLACEHOLDER_TOKEN",
"UserId": 123
}200OKCryptoWithdrawalOtpResendResponse
{
"Success": true,
"Message": "string",
"ExpiresAt": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/transfers/withdrawals/validateValidate withdrawal requestRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/transfers/withdrawals/validate?userId=123¤cy=USD&amount=100' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123currencyquerystringoptionalExample: USDamountquerynumberoptionalExample: 100200OKWithdrawalValidationResult
{
"IsValid": true,
"UserId": 123,
"RequestedAmount": 100,
"RequestedCurrency": "USD",
"ErrorCode": "string",
"ErrorMessage": "string",
"UserFriendlyMessage": "string",
"AvailableAmount": 100,
"ShortfallAmount": 100,
"BalanceBreakdown": {
"FIELD_FROM_APPLICATION": 100
},
"AvailableBalance": {
"TotalAvailableUSDT": 100,
"TotalAvailableUSDC": 100,
"WalletBreakdown": [
{
"WalletType": "string",
"Currency": "USD",
"Balance": 100,
"USDValue": 100,
"USDTEquivalent": 100,
"USDCEquivalent": 100
}
],
"ExchangeRateUSDToUSDT": 100,
"ExchangeRateUSDToUSDC": 100
},
"OptimalTransferPath": "string",
"RequiresInternalTransfer": true
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/transfers/crypto-transactionsGet user crypto transactions (CryptoConnect transfers)Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/transfers/crypto-transactions?userId=123&id=123&transactionHash=example&referenceId=external_reference_123&startTime=example&endTime=example' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123idquerystringoptionalExample: 123transactionHashquerystringoptionalExample: examplereferenceIdquerystringoptionalExample: external_reference_123startTimequerystringoptionalExample: exampleendTimequerystringoptionalExample: examplelimitqueryintegeroptionalExample: 10pagequeryintegeroptionalExample: 1200OKCryptoTransfersListResponse
{
"Transfers": [
{
"Id": "string",
"AccountId": "string",
"ReferenceId": "external_reference_123",
"Source": {
"Type": "string",
"Id": "string",
"Chain": "string",
"Address": "string"
},
"Destination": {
"Type": "string",
"Id": "string",
"Chain": "string",
"Address": "string"
},
"Amount": {
"Amount": 100,
"Currency": "USD"
},
"Fees": [
{
"Amount": 100,
"Currency": "USD",
"Type": "string"
}
],
"Status": "PENDING",
"CreateTime": "2026-08-05T09:30:00Z",
"CompleteTime": "2026-08-05T09:30:00Z"
}
],
"Total": 1,
"Page": 1,
"Limit": 1
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/transfers/crypto-refundsGet crypto refunds for a userRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/transfers/crypto-refunds?userId=123&id=123&transferId=123&transactionHash=example&referenceId=external_reference_123&startTime=example' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123idquerystringoptionalExample: 123transferIdquerystringoptionalExample: 123transactionHashquerystringoptionalExample: examplereferenceIdquerystringoptionalExample: external_reference_123startTimequerystringoptionalExample: exampleendTimequerystringoptionalExample: examplelimitqueryintegeroptionalExample: 10pagequeryintegeroptionalExample: 1200OKCryptoRefundsListResponse
{
"Refunds": [
{
"Id": "string",
"TransferId": "string",
"AccountId": "string",
"Destination": {
"Type": "string",
"Id": "string",
"Chain": "string",
"Address": "string"
},
"Amount": {
"Amount": 100,
"Currency": "USD"
},
"Fees": [
{
"Amount": 100,
"Currency": "USD",
"Type": "string"
}
],
"Status": "PENDING",
"TransactionHash": "string",
"ReferenceId": "external_reference_123",
"CreateTime": "2026-08-05T09:30:00Z",
"CompleteTime": "2026-08-05T09:30:00Z"
}
],
"Total": 1,
"Page": 1,
"Limit": 1
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/transfers/crypto-refundsCreate a crypto refundRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/crypto-refunds?userId=123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"TransferId": "string",
"Address": "string"
}'Parameters
userIdqueryintegeroptionalExample: 123Request fields and validation
TransferId · string · requiredAddress · string · requiredExample request body · replace placeholders
{
"TransferId": "string",
"Address": "string"
}201CreatedCreateCryptoRefundResponse
{
"Success": true,
"RefundId": "string",
"TransferId": "string",
"AccountId": "string",
"Destination": {
"Type": "string",
"Id": "string",
"Chain": "string",
"Address": "string"
},
"Amount": {
"Amount": 100,
"Currency": "USD"
},
"Fees": [
{
"Amount": 100,
"Currency": "USD",
"Type": "string"
}
],
"Status": "PENDING",
"ReferenceId": "external_reference_123",
"CreateTime": "2026-08-05T09:30:00Z",
"CompleteTime": "2026-08-05T09:30:00Z",
"Message": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/transfers/crypto-refunds/gas-feeGet refund gas fee for a specific currency and chainRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/crypto-refunds/gas-fee' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Currency": "USD",
"Chain": "string"
}'Request fields and validation
Currency · string · requiredChain · string · requiredExample request body · replace placeholders
{
"Currency": "USD",
"Chain": "string"
}200OKGetRefundGasFeeResponse
{
"Fees": [
{
"Amount": 100,
"Currency": "USD",
"Type": "string"
}
],
"Message": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/transfers/test-feesTest endpoint for fee charging flowtestRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/transfers/test-fees?userId=123&completeFee=100&whitelabelFee=100' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdqueryintegeroptionalExample: 123completeFeequerynumberoptionalExample: 100whitelabelFeequerynumberoptionalExample: 100200OKapplication/json
{}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
Users23 operations
POST/api/v2/users/account-claim/challengesSends a six-digit verification code when the email exactly matches a user in the API-key company.Request & responses +
The response is intentionally identical for known and unknown emails. The OTP is sent by Hoppa and is never returned by the API.
curl --request POST 'https://staging.hoppa.global/api/v2/users/account-claim/challenges' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Email": "user@example.com"
}'Request fields and validation
Email · string · requiredMinimum length: 0
Maximum length: 320
Example request body · replace placeholders
{
"Email": "user@example.com"
}202AcceptedAccountClaimChallengeResponse
{
"ChallengeId": "00000000-0000-4000-8000-000000000123",
"ExpiresAt": "2026-08-05T09:30:00Z",
"Message": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}429Too Many RequestsErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/account-claim/challenges/verifyVerifies the emailed code and returns the company-scoped Hoppa identity exactly once.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/account-claim/challenges/verify' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"ChallengeId": "00000000-0000-4000-8000-000000000123",
"Code": "string"
}'Request fields and validation
ChallengeId · string · requiredCode · string · requiredPattern: ^[0-9]{6}$
Example request body · replace placeholders
{
"ChallengeId": "00000000-0000-4000-8000-000000000123",
"Code": "string"
}200OKVerifiedAccountClaimResponse
{
"UserId": 123,
"Email": "user@example.com",
"FirstName": "Jane",
"LastName": "Doe",
"AccountType": "string",
"Status": "PENDING"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}429Too Many RequestsErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/account-links/scanRegisters that a White Label app scanned an account-link QR code.Request & responses +
The QR token is opaque, company-scoped, expires after five minutes, and never contains account data.
curl --request POST 'https://staging.hoppa.global/api/v2/users/account-links/scan' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Token": "USDC",
"ApplicationName": "string",
"DeviceName": "string"
}'Request fields and validation
Token · string · requiredMinimum length: 32
Maximum length: 512
ApplicationName · string · requiredMinimum length: 1
Maximum length: 120
DeviceName · string or null · optionalMinimum length: 0
Maximum length: 160
Example request body · replace placeholders
{
"Token": "USDC",
"ApplicationName": "string",
"DeviceName": "string"
}200OKPublicAccountLinkStatusResponse
{
"ChallengeId": "00000000-0000-4000-8000-000000000123",
"Status": "PENDING",
"ExpiresAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/account-links/statusReturns the approval state for a scanned QR token without exposing user data.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/account-links/status' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Token": "USDC"
}'Request fields and validation
Token · string · requiredMinimum length: 32
Maximum length: 512
Example request body · replace placeholders
{
"Token": "USDC"
}200OKPublicAccountLinkStatusResponse
{
"ChallengeId": "00000000-0000-4000-8000-000000000123",
"Status": "PENDING",
"ExpiresAt": "2026-08-05T09:30:00Z"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/account-links/exchangeConsumes an approved token and returns the company-scoped Hoppa identity exactly once.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/account-links/exchange' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Token": "USDC"
}'Request fields and validation
Token · string · requiredMinimum length: 32
Maximum length: 512
Example request body · replace placeholders
{
"Token": "USDC"
}200OKVerifiedAccountClaimResponse
{
"UserId": 123,
"Email": "user@example.com",
"FirstName": "Jane",
"LastName": "Doe",
"AccountType": "string",
"Status": "PENDING"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/usersList users with filtering and paginationRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users?pageNumber=1&pageSize=10&query=example&status=PENDING&kycStatus=SUBMITTED&externalUserId=external_reference_123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
pageNumberqueryintegeroptionalExample: 1pageSizequeryintegeroptionalExample: 10queryquerystringoptionalExample: examplestatusquerystringoptionalExample: PENDINGkycStatusquerystringoptionalExample: SUBMITTEDexternalUserIdquerystringoptionalExample: external_reference_123dateFromquerystringoptionalExample: 2026-08-05dateToquerystringoptionalExample: 2026-08-05200OKUserListResponseV2
{
"Users": [
{
"Id": 123,
"ExternalUserId": "external_reference_123",
"Email": "user@example.com",
"FirstName": "Jane",
"LastName": "Doe",
"Status": "PENDING",
"KycStatus": "SUBMITTED",
"KycLevel": "HOPPA_PRODUCTION",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CompanyId": 123,
"PackageId": 123,
"BusinessName": "string",
"BusinessExternalId": "external_reference_123",
"BusinessParentId": 123,
"AccountType": "business",
"PrimaryExternalWalletId": "external_reference_123",
"SelectedTierId": 123,
"TierBillingCycle": "string",
"OnboardingProductPreference": "external_reference_123",
"ReferralAttribution": {
"Status": "PENDING",
"Reason": "string",
"Remedy": "string",
"RelationshipId": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"AcceptedTermsVersion": 1
}
}
],
"Total": 1,
"PageNumber": 1,
"PageSize": 1,
"TotalPages": 1
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/usersCreate a new userRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Email": "user@example.com",
"FirstName": "Jane",
"LastName": "Doe",
"ExternalUserId": "external_reference_123",
"Phone": "+447700900123",
"TierId": 123,
"TierBillingCycle": "string",
"Metadata": {},
"InitialKycSource": "SUMSUB",
"DateOfBirth": "2026-08-05",
"Address": "string",
"City": "London",
"State": "string",
"Country": "GB",
"ZipCode": "SW1A 1AA",
"CreateMandate": true,
"MandateMaxAmount": "2026-08-05",
"MandateCurrency": "2026-08-05",
"MandateDescription": "2026-08-05",
"BusinessName": "string",
"BusinessExternalId": "external_reference_123",
"BusinessParentId": 123,
"ReferralId": "string",
"InvitationToken": "string",
"ReferralAccepted": true,
"ReferralTermsVersion": 1,
"AccountType": "business"
}'Request fields and validation
Email · string · requiredFirstName · string · requiredMinimum length: 1
Maximum length: 50
LastName · string · requiredMinimum length: 1
Maximum length: 50
Phone · string · optionalExternalUserId · string · requiredTierId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
TierBillingCycle · string or null · optionalPattern: ^(monthly|yearly)$
Metadata · object or null · optionalInitialKycSource · value or null · optionalDateOfBirth · string or null · optionalAddress · string or null · optionalCity · string or null · optionalState · string or null · optionalCountry · string or null · optionalZipCode · string or null · optionalCreateMandate · boolean or null · optionalMandateMaxAmount · string or null · optionalMandateCurrency · string or null · optionalMandateDescription · string or null · optionalBusinessName · string or null · optionalBusinessExternalId · string or null · optionalBusinessParentId · integer or null · optionalPattern: ^-?(?:0|[1-9]\d*)$
ReferralId · string or null · optionalLegacy signup referral request. Rewarded codes return NEEDS_REVIEW; use quote and command endpoints to accept an offer.
InvitationToken · string or null · optionalOpaque signed email invitation token. When supplied it is authoritative over ReferralId.
Minimum length: 0
Maximum length: 512
ReferralAccepted · boolean or null · optionalLegacy acceptance claim retained as intake evidence. It does not substitute for consent to an immutable quote.
ReferralTermsVersion · integer or null · optionalLegacy terms version claimed by the integration, retained for review without accepting current terms.
Pattern: ^-?(?:0|[1-9]\d*)$
AccountType · string or null · optionalAccount type: "personal" or "business" (defaults to "personal") Allowed values: business, personal. Defaults to personal when omitted.
Allowed: business, personal
Pattern: ^(personal|business)$
Example request body · replace placeholders
{
"Email": "user@example.com",
"FirstName": "Jane",
"LastName": "Doe",
"ExternalUserId": "external_reference_123",
"Phone": "+447700900123",
"TierId": 123,
"TierBillingCycle": "string",
"Metadata": {},
"InitialKycSource": "SUMSUB",
"DateOfBirth": "2026-08-05",
"Address": "string",
"City": "London",
"State": "string",
"Country": "GB",
"ZipCode": "SW1A 1AA",
"CreateMandate": true,
"MandateMaxAmount": "2026-08-05",
"MandateCurrency": "2026-08-05",
"MandateDescription": "2026-08-05",
"BusinessName": "string",
"BusinessExternalId": "external_reference_123",
"BusinessParentId": 123,
"ReferralId": "string",
"InvitationToken": "string",
"ReferralAccepted": true,
"ReferralTermsVersion": 1,
"AccountType": "business"
}201CreatedUserResponseV2
{
"Id": 123,
"ExternalUserId": "external_reference_123",
"Email": "user@example.com",
"FirstName": "Jane",
"LastName": "Doe",
"Status": "PENDING",
"KycStatus": "SUBMITTED",
"KycLevel": "HOPPA_PRODUCTION",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CompanyId": 123,
"PackageId": 123,
"BusinessName": "string",
"BusinessExternalId": "external_reference_123",
"BusinessParentId": 123,
"AccountType": "business",
"PrimaryExternalWalletId": "external_reference_123",
"SelectedTierId": 123,
"TierBillingCycle": "string",
"OnboardingProductPreference": "external_reference_123",
"ReferralAttribution": {
"Status": "PENDING",
"Reason": "string",
"Remedy": "string",
"RelationshipId": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"AcceptedTermsVersion": 1
}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}409ConflictErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}Get user by ID, including address and nationality from the linked Sumsub applicant when available. Saved profile values are returned when Sumsub is unavailable.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123200OKUserDetailResponseV2
{
"Phone": "+447700900123",
"DateOfBirth": "2026-08-05",
"Nationality": "string",
"Address": "string",
"City": "London",
"State": "string",
"Country": "GB",
"ZipCode": "SW1A 1AA",
"ExpectedMonthlyVolume": "100.00",
"KycProvider": "string",
"KycVerificationId": "string",
"KycVerificationDate": "2026-08-05",
"KycRejectionReason": "string",
"KycCompletedAt": "2026-08-05T09:30:00Z",
"SumsubTokenForTransak": "string",
"LastKycSubmissionId": 123,
"LastKycSumsubUserId": "string",
"LastKycProviderStatus": "PENDING",
"LastKycProviderApplicationId": "string",
"ReferralId": "string",
"ReferralAccepted": true,
"ReferralTermsVersion": 1,
"Id": 123,
"ExternalUserId": "external_reference_123",
"Email": "user@example.com",
"FirstName": "Jane",
"LastName": "Doe",
"Status": "PENDING",
"KycStatus": "SUBMITTED",
"KycLevel": "HOPPA_PRODUCTION",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CompanyId": 123,
"PackageId": 123,
"BusinessName": "string",
"BusinessExternalId": "external_reference_123",
"BusinessParentId": 123,
"AccountType": "business",
"PrimaryExternalWalletId": "external_reference_123",
"SelectedTierId": 123,
"TierBillingCycle": "string",
"OnboardingProductPreference": "external_reference_123",
"ReferralAttribution": {
"Status": "PENDING",
"Reason": "string",
"Remedy": "string",
"RelationshipId": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"AcceptedTermsVersion": 1
}
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/users/{userId}Update user informationRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/users/123' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"ExternalUserId": "external_reference_123",
"FirstName": "Jane",
"LastName": "Doe",
"Phone": "+447700900123",
"Metadata": {}
}'Parameters
userIdpathintegerrequiredExample: 123Request fields and validation
ExternalUserId · string or null · optionalFirstName · string or null · optionalMinimum length: 1
Maximum length: 50
LastName · string or null · optionalMinimum length: 1
Maximum length: 50
Phone · string or null · optionalMetadata · object or null · optionalExample request body · replace placeholders
{
"ExternalUserId": "external_reference_123",
"FirstName": "Jane",
"LastName": "Doe",
"Phone": "+447700900123",
"Metadata": {}
}200OKUserResponseV2
{
"Id": 123,
"ExternalUserId": "external_reference_123",
"Email": "user@example.com",
"FirstName": "Jane",
"LastName": "Doe",
"Status": "PENDING",
"KycStatus": "SUBMITTED",
"KycLevel": "HOPPA_PRODUCTION",
"CreatedAt": "2026-08-05T09:30:00Z",
"UpdatedAt": "2026-08-05T09:30:00Z",
"CompanyId": 123,
"PackageId": 123,
"BusinessName": "string",
"BusinessExternalId": "external_reference_123",
"BusinessParentId": 123,
"AccountType": "business",
"PrimaryExternalWalletId": "external_reference_123",
"SelectedTierId": 123,
"TierBillingCycle": "string",
"OnboardingProductPreference": "external_reference_123",
"ReferralAttribution": {
"Status": "PENDING",
"Reason": "string",
"Remedy": "string",
"RelationshipId": "00000000-0000-4000-8000-000000000123",
"ProgramId": "00000000-0000-4000-8000-000000000123",
"AcceptedTermsVersion": 1
}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/occupation-codesGet complete list of occupation codesRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/occupation-codes' \
-H 'x-api-key: YOUR_API_KEY'200OKapplication/json
[
{
"Value": "string",
"Title": "string",
"MajorGroup": "string",
"MinorGroup": "string"
}
]500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/{userId}/kyc/verifyVerify and update user KYC information with comprehensive verification dataRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/123/kyc/verify' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"KycStatus": "SUBMITTED",
"KycLevel": "HOPPA_PRODUCTION",
"Occupation": "string",
"AnnualSalary": "0-10000",
"AccountPurpose": "Example description",
"ExpectedMonthlyVolume": "0-1000",
"DocumentIssueDate": "2026-08-05",
"VerificationId": "string",
"KycProvider": "string",
"FirstName": "Jane",
"LastName": "Doe",
"DateOfBirth": "2026-08-05",
"Gender": "string",
"Nationality": "string",
"Ssn": "string",
"Email": "user@example.com",
"PhoneNumber": "+447700900123",
"IpAddress": "string",
"EqualsMainPurpose": [
"SALARY_OR_INCOME"
],
"EqualsSourceOfFunds": [
"RECEIVING_FUNDS_FROM_OWN_ACCOUNTS"
],
"EqualsCurrenciesRequired": [
"AED"
],
"EqualsDestinationCountries": [
"AD"
],
"EqualsExpectedAnnualVolume": "0-10000",
"EqualsExpectedPayments": "FEWER-THAN-5",
"NationalId": "string",
"DocumentType": "string",
"DocumentNumber": "string",
"DocumentExpiryDate": "2026-08-05",
"DocumentIssuingCountry": "GB",
"DocumentIssuingAuthority": "string",
"DocumentIssuedAt": "string",
"DocumentFrontImage": "BASE64_ENCODED_DATA",
"DocumentBackImage": "BASE64_ENCODED_DATA",
"SelfieImage": "BASE64_ENCODED_DATA",
"DocumentImageFormat": "BASE64_ENCODED_DATA",
"AddressLine1": "string",
"AddressLine2": "string",
"City": "London",
"Region": "string",
"PostalCode": "SW1A 1AA",
"Country": "GB",
"ProofOfAddressType": "string",
"ProofOfAddressImage": "BASE64_ENCODED_DATA",
"ProofOfAddressIssueDate": "2026-08-05",
"ProofOfAddressImageFormat": "BASE64_ENCODED_DATA",
"Metadata": {},
"RejectionReason": "string",
"ReviewNotes": "string",
"KycDetails": "string"
}'Parameters
userIdpathintegerrequiredExample: 123Request fields and validation
KycStatus · string or null · requiredKycLevel · value or null · requiredVerificationId · string or null · optionalKycProvider · string or null · optionalFirstName · string or null · optionalLastName · string or null · optionalDateOfBirth · string or null · optionalGender · string or null · optionalNationality · string or null · optionalISO 3166-1 alpha-3 country code, for example GBR.
Ssn · string or null · optionalRequired when Nationality is USA. Exactly 9 digits, without separators.
Pattern: ^\d{9}$
Email · string or null · optionalPhoneNumber · string or null · optionalOccupation · string or null · requiredAnnualSalary · string or null · requiredPossible values: 0-10000, 10001-30000, 30001-50000, 50001-75000, 75001-100000, 100001-150000, 150001-250000, 250001+.
Allowed: 0-10000, 10001-30000, 30001-50000, 50001-75000, 75001-100000, 100001-150000, 150001-250000, 250001+
AccountPurpose · string or null · requiredExpectedMonthlyVolume · string or null · requiredPossible values: 0-1000, 1001-5000, 5001-15000, 15001-50000, 50001-100000, 100001+.
Allowed: 0-1000, 1001-5000, 5001-15000, 15001-50000, 50001-100000, 100001+
IpAddress · string or null · optionalDocumentIssueDate · string or null · requiredFormat: YYYY-MM-DD.
EqualsMainPurpose · array or null · optionalPossible values: SALARY_OR_INCOME, PERSONAL_TRANSFERS_OR_LIVING_EXPENSES, FAMILY_SUPPORT, MORTGAGE_OR_RENT_OR_UTILITY_BILLS, SAVINGS, INVESTMENT_PURPOSES, INVESTMENT_OR_TRADING_IN_CRYPTOCURRENCIES, RECEIVING_OR_SENDING_LOAN_PAYMENTS, PURCHASE_OF_GOODS_OR_SERVICES, TRAVEL, EDUCATION, MEDICAL_EXPENSES, CHARITABLE_DONATIONS.
EqualsSourceOfFunds · array or null · optionalPossible values: RECEIVING_FUNDS_FROM_OWN_ACCOUNTS, RECEIVING_SALARY_PENSION_OR_DIVIDENDS, RECEIVING_GIFTS_OR_INHERITANCES, PROCEEDS_FROM_INVESTMENTS, PROCEEDS_FROM_CRYPTOCURRENCY_SALES_OR_TRADING, PROCEEDS_FROM_SALE_OF_A_PROPERTY_OR_PHYSICAL_ASSET, OTHER.
EqualsCurrenciesRequired · array or null · optionalPossible values: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SEK, SGD, SHN, SLL, SOS, SRD, SSP, STN, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VND, VUV, WST, XAF, XAG, XAU, XCD, XOF, XPD, XPF, XPT, YER, ZAR, ZMK, ZMW, ZWD.
EqualsDestinationCountries · array or null · optionalPossible values: AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW.
EqualsExpectedAnnualVolume · string or null · optionalPossible values: 0-10000, 10001-50000, 50001-100000, 100001-250000, 250001-1000000, 1000001-5000000, 5000000+.
Allowed: 0-10000, 10001-50000, 50001-100000, 100001-250000, 250001-1000000, 1000001-5000000, 5000000+
EqualsExpectedPayments · string or null · optionalPossible values: FEWER-THAN-5, 5-10, 10-20, MORE-THAN-20.
Allowed: FEWER-THAN-5, 5-10, 10-20, MORE-THAN-20
NationalId · string or null · optionalDocumentType · string or null · optionalDocumentNumber · string or null · optionalDocumentExpiryDate · string or null · optionalDocumentIssuingCountry · string or null · optionalISO 3166-1 alpha-3 country code, for example GBR.
DocumentIssuingAuthority · string or null · optionalDocumentIssuedAt · string or null · optionalDocumentFrontImage · string or null · optionalDocumentBackImage · string or null · optionalSelfieImage · string or null · optionalDocumentImageFormat · string or null · optionalAddressLine1 · string or null · optionalAddressLine2 · string or null · optionalCity · string or null · optionalRegion · string or null · optionalPostalCode · string or null · optionalCountry · string or null · optionalISO 3166-1 alpha-3 country code, for example GBR.
ProofOfAddressType · string or null · optionalProofOfAddressImage · string or null · optionalProofOfAddressIssueDate · string or null · optionalProofOfAddressImageFormat · string or null · optionalMetadata · object or null · optionalRejectionReason · string or null · optionalReviewNotes · string or null · optionalKycDetails · string or null · optionalExample request body · replace placeholders
{
"KycStatus": "SUBMITTED",
"KycLevel": "HOPPA_PRODUCTION",
"Occupation": "string",
"AnnualSalary": "0-10000",
"AccountPurpose": "Example description",
"ExpectedMonthlyVolume": "0-1000",
"DocumentIssueDate": "2026-08-05",
"VerificationId": "string",
"KycProvider": "string",
"FirstName": "Jane",
"LastName": "Doe",
"DateOfBirth": "2026-08-05",
"Gender": "string",
"Nationality": "string",
"Ssn": "string",
"Email": "user@example.com",
"PhoneNumber": "+447700900123",
"IpAddress": "string",
"EqualsMainPurpose": [
"SALARY_OR_INCOME"
],
"EqualsSourceOfFunds": [
"RECEIVING_FUNDS_FROM_OWN_ACCOUNTS"
],
"EqualsCurrenciesRequired": [
"AED"
],
"EqualsDestinationCountries": [
"AD"
],
"EqualsExpectedAnnualVolume": "0-10000",
"EqualsExpectedPayments": "FEWER-THAN-5",
"NationalId": "string",
"DocumentType": "string",
"DocumentNumber": "string",
"DocumentExpiryDate": "2026-08-05",
"DocumentIssuingCountry": "GB",
"DocumentIssuingAuthority": "string",
"DocumentIssuedAt": "string",
"DocumentFrontImage": "BASE64_ENCODED_DATA",
"DocumentBackImage": "BASE64_ENCODED_DATA",
"SelfieImage": "BASE64_ENCODED_DATA",
"DocumentImageFormat": "BASE64_ENCODED_DATA",
"AddressLine1": "string",
"AddressLine2": "string",
"City": "London",
"Region": "string",
"PostalCode": "SW1A 1AA",
"Country": "GB",
"ProofOfAddressType": "string",
"ProofOfAddressImage": "BASE64_ENCODED_DATA",
"ProofOfAddressIssueDate": "2026-08-05",
"ProofOfAddressImageFormat": "BASE64_ENCODED_DATA",
"Metadata": {},
"RejectionReason": "string",
"ReviewNotes": "string",
"KycDetails": "string"
}200OKUserKycVerificationResponseV2
{
"Success": true,
"Message": "string",
"User": {
"Id": 123,
"KycStatus": "SUBMITTED",
"KycLevel": "HOPPA_PRODUCTION",
"KycProvider": "string",
"VerificationId": "string",
"FirstName": "Jane",
"LastName": "Doe",
"Email": "user@example.com",
"PhoneNumber": "+447700900123",
"DateOfBirth": "2026-08-05",
"Nationality": "string",
"DocumentType": "string",
"DocumentNumber": "string",
"AddressLine1": "string",
"AddressLine2": "string",
"City": "London",
"Region": "string",
"Country": "GB",
"PostalCode": "SW1A 1AA",
"RejectionReason": "string",
"ReviewNotes": "string",
"VerifiedAt": "string",
"UpdatedAt": "2026-08-05T09:30:00Z"
}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/crypto-addressesGet user crypto wallet addresses. Passing `userId = 0` returns master account addresses for the authenticated company.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/crypto-addresses' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123200OKUserCryptoAddressListResponseV2
{
"UserId": 123,
"Addresses": [
{
"Address": "string",
"Currency": "USD",
"Chain": "string",
"Tag": "string",
"Network": "string",
"IsActive": true,
"CreatedAt": "2026-08-05T09:30:00Z"
}
],
"CryptoAddresses": [
{
"Address": "string",
"Currency": "USD",
"Chain": "string",
"Tag": "string",
"Network": "string",
"IsActive": true,
"CreatedAt": "2026-08-05T09:30:00Z"
}
]
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/assetsGet user assets (balances). Passing `userId = 0` returns master account balances for the authenticated company.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/assets?interlaceAccountId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123interlaceAccountIdquerystringoptionalExample: 123200OKUserAssetsResponseV2
{
"UserId": 123,
"Assets": [
{
"Id": 123,
"Currency": "USD",
"Balance": "100.00",
"AvailableBalance": "100.00",
"FrozenBalance": "100.00",
"PendingBalance": "100.00",
"Network": "string",
"AssetType": "string",
"BalanceType": "100.00",
"BalanceId": "100.00",
"CreatedAt": "2026-08-05T09:30:00Z"
}
],
"RetrievedAt": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
PUT/api/v2/users/{userId}/kyc/sumsub-tokenUpdate user SumSub KYC tokenRequest & responses +
curl --request PUT 'https://staging.hoppa.global/api/v2/users/123/kyc/sumsub-token' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"SumsubSdkToken": "PLACEHOLDER_TOKEN",
"DocumentIssueDate": "2026-08-05",
"ExpiryDate": "2026-08-05",
"PhoneCountryCode": "+447700900123",
"Phone": "+447700900123",
"Occupation": "string",
"AnnualSalary": "0-10000",
"AccountPurpose": "Example description",
"ExpectedMonthlyVolume": "0-1000",
"FirstName": "Jane",
"LastName": "Doe",
"MiddleName": "string",
"Dob": "2026-08-05",
"Gender": "string",
"Nationality": "string",
"Country": "GB",
"PlaceOfBirth": "string",
"CountryOfBirth": "GB",
"Email": "user@example.com",
"NationalId": "string",
"IdType": "string",
"Ssn": "string",
"IpAddress": "string",
"Street": "string",
"Street2": "string",
"City": "London",
"State": "string",
"PostCode": "SW1A 1AA",
"AddressCountry": "GB"
}'Parameters
userIdpathintegerrequiredExample: 123Request fields and validation
SumsubSdkToken · string · requiredFirstName · string or null · optionalLastName · string or null · optionalMiddleName · string or null · optionalDob · string or null · optionalPattern: ^\d{4}-\d{2}-\d{2}$
Gender · string or null · optionalPattern: ^(M|F)$
Nationality · string or null · optionalISO 3166-1 alpha-2 country code.
Minimum length: 2
Maximum length: 2
Country · string or null · optionalPlaceOfBirth · string or null · optionalCountryOfBirth · string or null · optionalEmail · string or null · optionalNationalId · string or null · optionalIdType · string or null · optionalPattern: ^(CN-RIC|PASSPORT|HK-HKID|DLN|Government-Issued ID Card)$
DocumentIssueDate · string · requiredFormat: YYYY-MM-DD.
Pattern: ^\d{4}-\d{2}-\d{2}$
ExpiryDate · string · requiredPattern: ^\d{4}-\d{2}-\d{2}$
Ssn · string or null · optionalRequired when Nationality is US. Exactly 9 digits, without separators.
Pattern: ^\d{9}$
PhoneCountryCode · string · requiredMaximum length: 3
Pattern: ^\d{1,3}$
Phone · string · requiredMaximum length: 15
Occupation · string · requiredAnnualSalary · string · requiredPossible values: 0-10000, 10001-30000, 30001-50000, 50001-75000, 75001-100000, 100001-150000, 150001-250000, 250001+.
Allowed: 0-10000, 10001-30000, 30001-50000, 50001-75000, 75001-100000, 100001-150000, 150001-250000, 250001+
AccountPurpose · string · requiredExpectedMonthlyVolume · string · requiredPossible values: 0-1000, 1001-5000, 5001-15000, 15001-50000, 50001-100000, 100001+.
Allowed: 0-1000, 1001-5000, 5001-15000, 15001-50000, 50001-100000, 100001+
IpAddress · string · optionalStreet · string or null · optionalStreet2 · string or null · optionalCity · string or null · optionalState · string or null · optionalPostCode · string or null · optionalAddressCountry · string or null · optionalISO 3166-1 alpha-2 country code.
Minimum length: 2
Maximum length: 2
Example request body · replace placeholders
{
"SumsubSdkToken": "PLACEHOLDER_TOKEN",
"DocumentIssueDate": "2026-08-05",
"ExpiryDate": "2026-08-05",
"PhoneCountryCode": "+447700900123",
"Phone": "+447700900123",
"Occupation": "string",
"AnnualSalary": "0-10000",
"AccountPurpose": "Example description",
"ExpectedMonthlyVolume": "0-1000",
"FirstName": "Jane",
"LastName": "Doe",
"MiddleName": "string",
"Dob": "2026-08-05",
"Gender": "string",
"Nationality": "string",
"Country": "GB",
"PlaceOfBirth": "string",
"CountryOfBirth": "GB",
"Email": "user@example.com",
"NationalId": "string",
"IdType": "string",
"Ssn": "string",
"IpAddress": "string",
"Street": "string",
"Street2": "string",
"City": "London",
"State": "string",
"PostCode": "SW1A 1AA",
"AddressCountry": "GB"
}200OKUserKycSumSubTokenUpdateResponse
{
"UserId": 123,
"SumsubSdkToken": "PLACEHOLDER_TOKEN",
"Message": "string",
"Success": true,
"SumsubUserId": "string",
"UpdatedAt": "2026-08-05T09:30:00Z"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/{userId}/kyc/sumsub-access-tokenGet a SumSub access token for the user (for mobile SDK)Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/123/kyc/sumsub-access-token' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Occupation": "string",
"AnnualSalary": "0-10000",
"AccountPurpose": "Example description",
"ExpectedMonthlyVolume": "0-1000",
"DocumentIssueDate": "2026-08-05",
"Nationality": "string",
"Ssn": "string",
"IpAddress": "string"
}'Parameters
userIdpathintegerrequiredExample: 123Request fields and validation
Occupation · string · requiredAnnualSalary · string · requiredPossible values: 0-10000, 10001-30000, 30001-50000, 50001-75000, 75001-100000, 100001-150000, 150001-250000, 250001+.
Allowed: 0-10000, 10001-30000, 30001-50000, 50001-75000, 75001-100000, 100001-150000, 150001-250000, 250001+
AccountPurpose · string · requiredExpectedMonthlyVolume · string · requiredPossible values: 0-1000, 1001-5000, 5001-15000, 15001-50000, 50001-100000, 100001+.
Allowed: 0-1000, 1001-5000, 5001-15000, 15001-50000, 50001-100000, 100001+
DocumentIssueDate · string · requiredFormat: YYYY-MM-DD.
Nationality · string or null · optionalISO 3166-1 alpha-3 country code. When USA, Ssn is required.
Ssn · string or null · optionalRequired for US nationals. Exactly 9 digits, without separators.
Pattern: ^\d{9}$
IpAddress · string or null · optionalExample request body · replace placeholders
{
"Occupation": "string",
"AnnualSalary": "0-10000",
"AccountPurpose": "Example description",
"ExpectedMonthlyVolume": "0-1000",
"DocumentIssueDate": "2026-08-05",
"Nationality": "string",
"Ssn": "string",
"IpAddress": "string"
}200OKSumSubAccessTokenApiResponseV2
{
"Success": true,
"Token": "USDC",
"UserId": "string",
"Error": {}
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/kyc/detailed-statusGet detailed KYC status breakdown for the userRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/kyc/detailed-status' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123200OKDetailedKycStatusResponseV2
{
"HoppaCardKycApproved": true,
"BankKycApproved": true,
"CardIssuerKycApproved": true,
"Interlace": {
"Provider": "string",
"Status": "PENDING",
"Approved": true,
"ExternalId": "external_reference_123",
"LastUpdated": "2026-08-05T09:30:00Z",
"Reason": "string",
"RequiredAction": "string",
"ResubmissionDocSets": [
"string"
],
"Attempts": 1,
"MaxAttempts": 1,
"RejectedAt": "2026-08-05T09:30:00Z",
"CaseId": "string"
},
"EqualsMoney": {
"ApplicationId": "string",
"ApplicationStatus": "PENDING",
"AccountId": "string",
"ActionUrl": "https://example.com/callback",
"additionalDocumentsRequested": [
{
"type": "string",
"text": "string",
"expectedResponseType": "string",
"applicationId": "string",
"informationRequestId": "string",
"additionalInformation": "string",
"associatedPersonId": "string",
"requestedAt": "2026-08-05T09:30:00Z"
}
],
"Provider": "string",
"Status": "PENDING",
"Approved": true,
"ExternalId": "external_reference_123",
"LastUpdated": "2026-08-05T09:30:00Z",
"Reason": "string",
"RequiredAction": "string",
"ResubmissionDocSets": [
"string"
],
"Attempts": 1,
"MaxAttempts": 1,
"RejectedAt": "2026-08-05T09:30:00Z",
"CaseId": "string"
}
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/{userId}/kyc/equalsmoney/documentsRespond to a Banking document requestRequest & responses +
Uploads one or more documents for one item returned in `AdditionalDocumentsRequested`. Send the `Files` multipart field once for each PDF, JPEG, or PNG file. Files are combined into one PDF in the order supplied, then uploaded to Banking as the single document response for that request item. **Multipart example** ```text Type=PROOF_OF_FUNDS AssociatedPersonId=optional-person-id Files=@statement.pdf Files=@invoice.jpg Files=@receipt.png ``` **Limits:** 10 files; 10 MB per input file; 50 MB total input; 100 combined pages; 50 megapixels per image; 10,000,000 bytes for the generated PDF. The legacy singular `File` field remains accepted for existing integrations but is deprecated.
curl --request POST 'https://staging.hoppa.global/api/v2/users/123/kyc/equalsmoney/documents' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'Type=PROOF_OF_FUNDS' \
-F 'File=@/absolute/path/document.pdf' \
-F 'Files=@/absolute/path/document.pdf' \
-F 'AssociatedPersonId=person-123'Parameters
userIdpathintegerrequiredExample: 123Request fields and validation
File · string · optionalDeprecated single-document field retained for compatibility. New integrations should use `Files`, including when uploading only one file.
Files · array · optionalDocuments to combine. Repeat the `Files` multipart field for every file; array order is preserved in the generated PDF.
Type · string · requiredThe exact request item type returned in `AdditionalDocumentsRequested`, for example `PROOF_OF_FUNDS`.
AssociatedPersonId · string · optionalAssociated person identifier from the request item. Omit for company-level or primary-user requests.
Example request body · replace placeholders
{
"Type": "PROOF_OF_FUNDS",
"File": "<binary file>",
"Files": [
"<binary file>"
],
"AssociatedPersonId": "person-123"
}200OKEqualsMoneyAdditionalDocumentUploadResponseV2
{
"Success": true,
"DocumentId": "string",
"Type": "string",
"FileName": "string",
"RemainingAdditionalDocumentsRequested": [
{
"type": "string",
"text": "string",
"expectedResponseType": "string",
"applicationId": "string",
"informationRequestId": "string",
"additionalInformation": "string",
"associatedPersonId": "string",
"requestedAt": "2026-08-05T09:30:00Z"
}
]
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/{userId}/kyc/equalsmoney/informationSubmit a text answer requested by Banking for a user. Requires company API key authentication.Request & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/123/kyc/equalsmoney/information' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Type": "string",
"Response": "string",
"AssociatedPersonId": "string"
}'Parameters
userIdpathintegerrequiredExample: 123Request fields and validation
Type · string · requiredResponse · string · requiredMinimum length: 0
Maximum length: 1000
AssociatedPersonId · string or null · optionalExample request body · replace placeholders
{
"Type": "string",
"Response": "string",
"AssociatedPersonId": "string"
}200OKEqualsMoneyAdditionalInformationAnswerResponseV2
{
"Success": true,
"Type": "string",
"RemainingAdditionalDocumentsRequested": [
{
"type": "string",
"text": "string",
"expectedResponseType": "string",
"applicationId": "string",
"informationRequestId": "string",
"additionalInformation": "string",
"associatedPersonId": "string",
"requestedAt": "2026-08-05T09:30:00Z"
}
]
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/check-referralCheck if a referral code is valid for a companyRequest & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/check-referral?referralCode=example&visitorId=123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
referralCodequerystringoptionalExample: examplevisitorIdquerystringoptionalExample: 123200OKReferralCheckResponse
{
"Valid": true,
"TierId": 123,
"Kind": "string",
"Provider": "string",
"InviterDisplayName": "string",
"WelcomeAmount": 100,
"WelcomeCurrency": "USD",
"TermsVersion": 1,
"Destination": "string"
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
GET/api/v2/users/{userId}/walletsList crypto wallets for a user. Passing `userId = 0` returns master account wallets for the authenticated company.Request & responses +
curl --request GET 'https://staging.hoppa.global/api/v2/users/123/wallets?id=123&nickname=example¤cy=USD&master=true&referenceId=external_reference_123&limit=10' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123idquerystringoptionalExample: 123nicknamequerystringoptionalExample: examplecurrencyquerystringoptionalExample: USDmasterquerybooleanoptionalExample: truereferenceIdquerystringoptionalExample: external_reference_123limitqueryintegeroptionalExample: 10pagequeryintegeroptionalExample: 1200OKCryptoConnectWalletsV3Response
{
"code": "string",
"message": "string",
"data": {
"total": "string",
"list": [
{
"id": "string",
"accountId": "string",
"nickname": "string",
"master": true,
"referenceId": "external_reference_123",
"balances": [
{}
],
"addresses": [
{}
]
}
]
}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/create-interlace-account/{userId}Create a Crypto cards account for the authenticated userRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/create-interlace-account/123' \
-H 'x-api-key: YOUR_API_KEY'Parameters
userIdpathintegerrequiredExample: 123200OKCreateInterlaceAccountResponse
{
"Success": true,
"InterlaceAccountId": "string",
"ExternalUserId": "external_reference_123",
"Message": "string",
"CreatedAt": "2026-08-05T09:30:00Z",
"AccountAlreadyExists": true,
"ErrorCode": "string",
"ErrorMessage": "string"
}400Bad RequestProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}401UnauthorizedProblemDetails
{
"type": "string",
"title": "string",
"status": 1,
"detail": "string",
"instance": "string"
}500Internal Server Errorapplication/json
Response body is not specified in Scalar; do not assume it is empty.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/{userId}/sumsub/kyc-urlGenerate SumSub KYC verification URL for userRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/123/sumsub/kyc-url' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"Occupation": "string",
"AnnualSalary": "string",
"AccountPurpose": "Example description",
"ExpectedMonthlyVolume": "100.00",
"DocumentIssueDate": "2026-08-05",
"Nationality": "string",
"Ssn": "string",
"IpAddress": "string"
}'Parameters
userIdpathintegerrequiredExample: 123Request fields and validation
Occupation · string or null · optionalAnnualSalary · string or null · optionalAccountPurpose · string or null · optionalExpectedMonthlyVolume · string or null · optionalDocumentIssueDate · string or null · optionalNationality · string or null · optionalSsn · string or null · optionalPattern: ^\d{9}$
IpAddress · string or null · optionalExample request body · replace placeholders
{
"Occupation": "string",
"AnnualSalary": "string",
"AccountPurpose": "Example description",
"ExpectedMonthlyVolume": "100.00",
"DocumentIssueDate": "2026-08-05",
"Nationality": "string",
"Ssn": "string",
"IpAddress": "string"
}200Returns the SumSub access tokenSumSubKycUrlResponse
{
"Success": true,
"ErrorCode": "string",
"ErrorMessage": "string",
"AccessToken": "PLACEHOLDER_TOKEN",
"ApplicantId": "string",
"ExternalUserId": "external_reference_123",
"KycSubmissionId": 123,
"Status": "PENDING",
"ExistingStatus": "PENDING",
"ExpiresAt": "2026-08-05T09:30:00Z",
"CreatedAt": "2026-08-05T09:30:00Z",
"CompletedAt": "2026-08-05T09:30:00Z",
"IsNewApplicant": true,
"Message": "string",
"Configuration": {
"LevelName": "string",
"TokenValidityHours": 1,
"Provider": "string",
"IsTestMode": true,
"SdkVersion": "string",
"RequiredDocuments": [
"string"
]
}
}400Invalid request or KYC already completedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401User not authenticatedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}403User does not belong to the companyErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404User not foundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal server errorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/api/v2/users/{userId}/tierSet user tier and queue the first subscription fee for scheduled fee chargingRequest & responses +
curl --request POST 'https://staging.hoppa.global/api/v2/users/123/tier' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data '{
"TierId": 123,
"TierCycle": "string"
}'Parameters
userIdpathintegerrequiredExample: 123Request fields and validation
TierId · integer · optionalPattern: ^-?(?:0|[1-9]\d*)$
TierCycle · string · optionalExample request body · replace placeholders
{
"TierId": 123,
"TierCycle": "string"
}200OKTierBuyResponse
{
"Success": true,
"UserId": 123,
"TierId": 123,
"TierName": "string",
"TierLevel": "string",
"OrderId": "string",
"TotalCost": 100,
"Currency": "USD",
"Status": "PENDING",
"PurchasedAt": "2026-08-05T09:30:00Z",
"ActivatedAt": "2026-08-05T09:30:00Z",
"ExpiresAt": "2026-08-05T09:30:00Z",
"UpgradeDetails": {
"PreviousTierName": "string",
"PreviousTierLevel": "string",
"NewTierName": "string",
"NewTierLevel": "string",
"IsUpgrade": true,
"IsDowngrade": true,
"IsRenewal": true,
"ChangedFeatures": [
"string"
],
"AddedFeatures": [
"string"
],
"RemovedFeatures": [
"string"
]
},
"PaymentDetails": {
"PaymentMethod": "string",
"WalletAddress": "0x1111111111111111111111111111111111111111",
"TransactionId": "string",
"AmountPaid": 100,
"Amount": 100,
"Currency": "USD",
"PaymentDate": "2026-08-05T09:30:00Z",
"ProcessedAt": "2026-08-05T09:30:00Z",
"PaymentStatus": "PENDING",
"Status": "PENDING",
"FailureReason": "string"
},
"NewBenefits": {
"MaxCards": 1,
"DailySpendLimit": 100,
"MonthlySpendLimit": 100,
"DailyWithdrawLimit": 100,
"MonthlyWithdrawLimit": 100,
"VirtualCards": true,
"PhysicalCards": true,
"InternationalUsage": true,
"PremiumSupport": true,
"CashbackPercentage": 100,
"SupportedCurrencies": [
"string"
],
"AvailableCardTypes": [
{
"Id": 123,
"Name": "string",
"Type": "string",
"Price": 100,
"IsVirtual": true,
"IsPhysical": true,
"IsActive": true,
"MonthlyFee": 100,
"YearlyFee": 100,
"BankProviderType": 1,
"CustomerPaysForProduction": true,
"CustomerPaysForShippment": true
}
]
},
"ErrorCode": "string",
"ErrorMessage": "string",
"Message": "string",
"Audit": {
"RequestedBy": "string",
"RequestedAt": "2026-08-05T09:30:00Z",
"RequestSource": "string",
"IPAddress": "string",
"UserAgent": "string",
"IsSecureConnection": true,
"AuthenticationMethod": "string",
"AdditionalNotes": "string"
},
"PurchaseId": "00000000-0000-4000-8000-000000000123",
"PurchaseExpiresAt": "2026-08-05T09:30:00Z",
"StripePayment": {
"PublishableKey": "string",
"ClientSecret": "string",
"PaymentIntentId": "string"
}
}400Bad RequestErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}401UnauthorizedErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}404Not FoundErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}500Internal Server ErrorErrorResponse
{
"Message": "string",
"Code": "string",
"Status": 1,
"ValidationErrors": {
"FIELD_FROM_APPLICATION": [
"string"
]
},
"Details": "string"
}Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
Webhooks70 operations
POST/webhooks/outbound/mor.card.assignedmor.card.assignedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. A merchant card's assignment changed. Durable, at-least-once delivery; deduplicate by event id and read current state after out-of-order delivery. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "mor.card.assigned",
"domain": "mor",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"companyId": 42,
"cardId": 123,
"assignedUserId": 456,
"previousAssignedUserId": null
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: mor.card.assigned
domain · string · requiredBusiness domain for the event.
Allowed: mor
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `mor.card.assigned`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "mor.card.assigned",
"domain": "mor",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"companyId": 42,
"cardId": 123,
"assignedUserId": 456,
"previousAssignedUserId": null
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/mor.card.unassignedmor.card.unassignedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. A merchant card was unassigned. Ownership and funds stay with the merchant. Deduplicate by event id. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "mor.card.unassigned",
"domain": "mor",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"companyId": 42,
"cardId": 123,
"previousAssignedUserId": 456
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: mor.card.unassigned
domain · string · requiredBusiness domain for the event.
Allowed: mor
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `mor.card.unassigned`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "mor.card.unassigned",
"domain": "mor",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"companyId": 42,
"cardId": 123,
"previousAssignedUserId": 456
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/mor.card.load_request.updatedmor.card.load_request.updatedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. A load request was created, changed, completed or cancelled. This event does not itself move funds. Read current state by cardId. Deduplicate by event id. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "mor.card.load_request.updated",
"domain": "mor",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"companyId": 42,
"cardId": 123,
"requestedByUserId": 456,
"amount": 50,
"currency": "USD",
"status": "pending"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: mor.card.load_request.updated
domain · string · requiredBusiness domain for the event.
Allowed: mor
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `mor.card.load_request.updated`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "mor.card.load_request.updated",
"domain": "mor",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"companyId": 42,
"cardId": 123,
"requestedByUserId": 456,
"amount": 50,
"currency": "USD",
"status": "pending"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/mor.kyb.updatedmor.kyb.updatedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. A current merchant-company KYB status was persisted through submission, provider webhook or polling. Deduplicate by event id. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "mor.kyb.updated",
"domain": "mor",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"companyId": 42,
"profileId": "profile_123",
"status": "PASSED",
"previousStatus": "PROCESSING"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: mor.kyb.updated
domain · string · requiredBusiness domain for the event.
Allowed: mor
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `mor.kyb.updated`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "mor.kyb.updated",
"domain": "mor",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"companyId": 42,
"profileId": "profile_123",
"status": "PASSED",
"previousStatus": "PROCESSING"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/user.registereduser.registeredRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent after a user is created. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "user.registered",
"domain": "user",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"email": "user@example.com"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: user.registered
domain · string · requiredBusiness domain for the event.
Allowed: user
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `user.registered`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "user.registered",
"domain": "user",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"email": "user@example.com"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/user.kyc.updateduser.kyc.updatedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a user's KYC status changes during verification submission or provider processing. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "user.kyc.updated",
"domain": "user",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"status": "pending"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: user.kyc.updated
domain · string · requiredBusiness domain for the event.
Allowed: user
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `user.kyc.updated`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "user.kyc.updated",
"domain": "user",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"status": "pending"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/kyc.verifiedkyc.verifiedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Crypto cards or SumSub KYC review is processed. For the Crypto cards (card issuer) verdict provider is "bank", status is approved | rejected | action_required | pending and, for a rejection, reason / requiredAction / caseId are set. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "kyc.verified",
"domain": "kyc",
"provider": "sumsub",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"kycLevel": "hoppacard-stagging",
"status": "approved",
"type": "KYC",
"reason": null,
"requiredAction": null,
"caseId": "cdd_123"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: kyc.verified
domain · string · requiredBusiness domain for the event.
Allowed: kyc
provider · string · requiredProvider that originated the event.
Allowed: sumsub
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `kyc.verified`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "kyc.verified",
"domain": "kyc",
"provider": "sumsub",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"kycLevel": "hoppacard-stagging",
"status": "approved",
"type": "KYC",
"reason": null,
"requiredAction": null,
"caseId": "cdd_123"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/kyc.resubmission_requiredkyc.resubmission_requiredRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when Crypto cards rejects a Sumsub-approved verification and the user has to act: RESUBMIT_DOCUMENTS (the listed Sumsub doc sets were reset, re-open the verification flow), RESUBMIT_DATA (Hoppa resubmits corrected data) or CONTACT_SUPPORT. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "kyc.resubmission_required",
"domain": "kyc",
"provider": "interlace",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"applicantId": "applicant_123",
"reason": "Your identity document could not be accepted by the card issuer. Please upload a new, clear photo of your document.",
"providerReason": "Applicant uploaded a bad ID document.",
"requiredAction": "RESUBMIT_DOCUMENTS",
"docSets": [
"IDENTITY"
],
"attempts": 1,
"maxAttempts": 3,
"caseId": "cdd_123",
"type": "KYC"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: kyc.resubmission_required
domain · string · requiredBusiness domain for the event.
Allowed: kyc
provider · string · requiredProvider that originated the event.
Allowed: interlace
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `kyc.resubmission_required`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "kyc.resubmission_required",
"domain": "kyc",
"provider": "interlace",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"applicantId": "applicant_123",
"reason": "Your identity document could not be accepted by the card issuer. Please upload a new, clear photo of your document.",
"providerReason": "Applicant uploaded a bad ID document.",
"requiredAction": "RESUBMIT_DOCUMENTS",
"docSets": [
"IDENTITY"
],
"attempts": 1,
"maxAttempts": 3,
"caseId": "cdd_123",
"type": "KYC"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/kyc.interlace_submission_failedkyc.interlace_submission_failedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when SumSub approval could not be submitted to Crypto cards. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "kyc.interlace_submission_failed",
"domain": "kyc",
"provider": "interlace",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"error": "Interlace submission failed",
"accountId": "acc_123",
"applicantId": "applicant_123"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: kyc.interlace_submission_failed
domain · string · requiredBusiness domain for the event.
Allowed: kyc
provider · string · requiredProvider that originated the event.
Allowed: interlace
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `kyc.interlace_submission_failed`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "kyc.interlace_submission_failed",
"domain": "kyc",
"provider": "interlace",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"error": "Interlace submission failed",
"accountId": "acc_123",
"applicantId": "applicant_123"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/legal_entity.statuslegal_entity.statusRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a business legal entity status changes. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "legal_entity.status",
"domain": "kyc",
"provider": "bank",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"entityId": "le_123",
"status": "approved",
"type": "BUSINESS"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: legal_entity.status
domain · string · requiredBusiness domain for the event.
Allowed: kyc
provider · string · requiredProvider that originated the event.
Allowed: bank
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `legal_entity.status`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "legal_entity.status",
"domain": "kyc",
"provider": "bank",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"entityId": "le_123",
"status": "approved",
"type": "BUSINESS"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/bank_account.statusbank_account.statusRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a business bank account status changes. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "bank_account.status",
"domain": "account",
"provider": "bank",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"bankAccountId": "ba_123",
"iban": "GB00HOPP00000000000000",
"currency": "GBP",
"status": "active"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: bank_account.status
domain · string · requiredBusiness domain for the event.
Allowed: account
provider · string · requiredProvider that originated the event.
Allowed: bank
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `bank_account.status`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "bank_account.status",
"domain": "account",
"provider": "bank",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"bankAccountId": "ba_123",
"iban": "GB00HOPP00000000000000",
"currency": "GBP",
"status": "active"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/account.deposit.addressaccount.deposit.addressRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when deposit addresses are created for a user's account. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "account.deposit.address",
"domain": "account",
"provider": "bank",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"status": "created"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: account.deposit.address
domain · string · requiredBusiness domain for the event.
Allowed: account
provider · string · requiredProvider that originated the event.
Allowed: bank
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `account.deposit.address`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "account.deposit.address",
"domain": "account",
"provider": "bank",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"status": "created"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/account.createdaccount.createdRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking account is created. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "account.created",
"domain": "account",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "AccountCreated",
"correlationId": "corr_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "PENDING",
"type": "INDIVIDUAL"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: account.created
domain · string · requiredBusiness domain for the event.
Allowed: account
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `account.created`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "account.created",
"domain": "account",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "AccountCreated",
"correlationId": "corr_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "PENDING",
"type": "INDIVIDUAL"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/account.activatedaccount.activatedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking account is activated. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "account.activated",
"domain": "account",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "AccountActivated",
"id": "acc_eq_123",
"correlationId": "corr_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "ACTIVE",
"type": "INDIVIDUAL",
"primaryOwnerPersonaId": "persona_123",
"details": {
"accountId": "acc_eq_123",
"name": "Example Trading Account"
},
"settlementDetails": [
{
"currency": "GBP",
"sortCode": "040075",
"accountNumber": "12345678",
"ibans": [
{
"iban": "GB29NWBK60161331926819",
"bic": "NWBKGB2L"
}
],
"accountName": "Example Trading Account",
"bankName": "Equals Money",
"bankAddress": "London, United Kingdom",
"balanceReference": "BAL-123"
}
]
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: account.activated
domain · string · requiredBusiness domain for the event.
Allowed: account
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `account.activated`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "account.activated",
"domain": "account",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "AccountActivated",
"id": "acc_eq_123",
"correlationId": "corr_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "ACTIVE",
"type": "INDIVIDUAL",
"primaryOwnerPersonaId": "persona_123",
"details": {
"accountId": "acc_eq_123",
"name": "Example Trading Account"
},
"settlementDetails": [
{
"currency": "GBP",
"sortCode": "040075",
"accountNumber": "12345678",
"ibans": [
{
"iban": "GB29NWBK60161331926819",
"bic": "NWBKGB2L"
}
],
"accountName": "Example Trading Account",
"bankName": "Equals Money",
"bankAddress": "London, United Kingdom",
"balanceReference": "BAL-123"
}
]
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/account.status_updatedaccount.status_updatedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking account status changes. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "account.status_updated",
"domain": "account",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "AccountStatusUpdated",
"correlationId": "corr_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "SUSPENDED",
"type": "INDIVIDUAL"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: account.status_updated
domain · string · requiredBusiness domain for the event.
Allowed: account
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `account.status_updated`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "account.status_updated",
"domain": "account",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "AccountStatusUpdated",
"correlationId": "corr_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "SUSPENDED",
"type": "INDIVIDUAL"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/payment.completedpayment.completedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent after a payment completes successfully. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.completed",
"domain": "payment",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"paymentId": 987,
"amount": 25.5,
"currency": "EUR"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: payment.completed
domain · string · requiredBusiness domain for the event.
Allowed: payment
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `payment.completed`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.completed",
"domain": "payment",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"paymentId": 987,
"amount": 25.5,
"currency": "EUR"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/payment.mandate.createdpayment.mandate.createdRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent after a payment mandate is created. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.mandate.created",
"domain": "payment",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"paymentMandateId": 456,
"maxAmount": 250,
"currency": "EUR",
"frequency": "monthly"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: payment.mandate.created
domain · string · requiredBusiness domain for the event.
Allowed: payment
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `payment.mandate.created`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.mandate.created",
"domain": "payment",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"paymentMandateId": 456,
"maxAmount": 250,
"currency": "EUR",
"frequency": "monthly"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/payment.mandate.cancelledpayment.mandate.cancelledRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent after a payment mandate is cancelled. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.mandate.cancelled",
"domain": "payment",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"paymentMandateId": 456
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: payment.mandate.cancelled
domain · string · requiredBusiness domain for the event.
Allowed: payment
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `payment.mandate.cancelled`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.mandate.cancelled",
"domain": "payment",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"paymentMandateId": 456
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/payment.request.createdpayment.request.createdRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent after a payment request is created. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.request.created",
"domain": "payment",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"paymentRequestId": 789,
"amount": 19.99,
"currency": "EUR"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: payment.request.created
domain · string · requiredBusiness domain for the event.
Allowed: payment
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `payment.request.created`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.request.created",
"domain": "payment",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"paymentRequestId": 789,
"amount": 19.99,
"currency": "EUR"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/payment.request.cancelledpayment.request.cancelledRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent after a payment request is cancelled. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.request.cancelled",
"domain": "payment",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"paymentRequestId": 789,
"amount": 19.99,
"currency": "EUR"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: payment.request.cancelled
domain · string · requiredBusiness domain for the event.
Allowed: payment
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `payment.request.cancelled`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.request.cancelled",
"domain": "payment",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"paymentRequestId": 789,
"amount": 19.99,
"currency": "EUR"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/payment.request.confirmed.directpayment.request.confirmed.directRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent after a payment request is confirmed by direct payment. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.request.confirmed.direct",
"domain": "payment",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"paymentRequestId": 789,
"paymentMandateId": 456,
"amount": 19.99,
"currency": "EUR",
"transferId": "tr_123"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: payment.request.confirmed.direct
domain · string · requiredBusiness domain for the event.
Allowed: payment
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `payment.request.confirmed.direct`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.request.confirmed.direct",
"domain": "payment",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"paymentRequestId": 789,
"paymentMandateId": 456,
"amount": 19.99,
"currency": "EUR",
"transferId": "tr_123"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/payment.request.confirmed.with.exchangepayment.request.confirmed.with.exchangeRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent after a payment request is confirmed using crypto exchange. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.request.confirmed.with.exchange",
"domain": "payment",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"paymentRequestId": 789,
"paymentMandateId": 456,
"amount": 19.99,
"currency": "EUR",
"transferId": "tr_123"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: payment.request.confirmed.with.exchange
domain · string · requiredBusiness domain for the event.
Allowed: payment
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `payment.request.confirmed.with.exchange`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.request.confirmed.with.exchange",
"domain": "payment",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"paymentRequestId": 789,
"paymentMandateId": 456,
"amount": 19.99,
"currency": "EUR",
"transferId": "tr_123"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/order.completedorder.completedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking payment order completes. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "order.completed",
"domain": "payment",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"orderId": "order_123",
"accountId": "account_123"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: order.completed
domain · string · requiredBusiness domain for the event.
Allowed: payment
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `order.completed`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "order.completed",
"domain": "payment",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"orderId": "order_123",
"accountId": "account_123"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/order.createdorder.createdRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking FX order is created. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "order.created",
"domain": "order",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "OrderCreated",
"orderId": "order_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "CREATED",
"buyCurrency": "EUR",
"sellCurrency": "GBP",
"buyAmount": 1000,
"sellAmount": 850,
"rate": 0.85,
"payments": [
{
"settlementDate": "2026-04-29T00:00:00Z",
"rate": 0.85,
"inverseRate": 1.1765,
"internalReference": "INT-123",
"externalReference": "EXT-123",
"from": {
"amount": 850,
"currency": "GBP"
},
"to": {
"amount": 1000,
"currency": "EUR"
},
"recipient": {
"id": "recipient_123",
"name": "Example Supplier Ltd"
}
}
]
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: order.created
domain · string · requiredBusiness domain for the event.
Allowed: order
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `order.created`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "order.created",
"domain": "order",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "OrderCreated",
"orderId": "order_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "CREATED",
"buyCurrency": "EUR",
"sellCurrency": "GBP",
"buyAmount": 1000,
"sellAmount": 850,
"rate": 0.85,
"payments": [
{
"settlementDate": "2026-04-29T00:00:00Z",
"rate": 0.85,
"inverseRate": 1.1765,
"internalReference": "INT-123",
"externalReference": "EXT-123",
"from": {
"amount": 850,
"currency": "GBP"
},
"to": {
"amount": 1000,
"currency": "EUR"
},
"recipient": {
"id": "recipient_123",
"name": "Example Supplier Ltd"
}
}
]
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/order.cancelledorder.cancelledRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking FX order is cancelled. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "order.cancelled",
"domain": "order",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "OrderCancelled",
"orderId": "order_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "CANCELLED"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: order.cancelled
domain · string · requiredBusiness domain for the event.
Allowed: order
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `order.cancelled`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "order.cancelled",
"domain": "order",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "OrderCancelled",
"orderId": "order_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "CANCELLED"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/payout.paymentpayout.paymentRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a business payout payment update is processed. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payout.payment",
"domain": "payout",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": 1001,
"externalTransactionId": "ext_tx_123",
"userId": 12345,
"accountId": 321,
"amount": 100,
"currency": "EUR",
"status": "completed",
"transferId": "transfer_123",
"type": "PAYOUT.PAYMENT"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: payout.payment
domain · string · requiredBusiness domain for the event.
Allowed: payout
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `payout.payment`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payout.payment",
"domain": "payout",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": 1001,
"externalTransactionId": "ext_tx_123",
"userId": 12345,
"accountId": 321,
"amount": 100,
"currency": "EUR",
"status": "completed",
"transferId": "transfer_123",
"type": "PAYOUT.PAYMENT"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/business_account.transactionbusiness_account.transactionRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a business account transaction is processed. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "business_account.transaction",
"domain": "business_account",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": 1001,
"externalTransactionId": "ext_tx_123",
"userId": 12345,
"accountId": 321,
"transactionType": "payout_payment",
"amount": 100,
"currency": "EUR",
"status": "completed",
"fee": 1.25
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: business_account.transaction
domain · string · requiredBusiness domain for the event.
Allowed: business_account
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `business_account.transaction`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "business_account.transaction",
"domain": "business_account",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": 1001,
"externalTransactionId": "ext_tx_123",
"userId": 12345,
"accountId": 321,
"transactionType": "payout_payment",
"amount": 100,
"currency": "EUR",
"status": "completed",
"fee": 1.25
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/wallet.topped_upwallet.topped_upRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a wallet, budget, or card funding transaction credits value. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "wallet.topped_up",
"domain": "wallet",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": "1001",
"walletId": "wallet_123",
"userId": "12345",
"amount": "100.00",
"currency": "EUR",
"status": "completed",
"provider": "hoppacard"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: wallet.topped_up
domain · string · requiredBusiness domain for the event.
Allowed: wallet
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `wallet.topped_up`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "wallet.topped_up",
"domain": "wallet",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": "1001",
"walletId": "wallet_123",
"userId": "12345",
"amount": "100.00",
"currency": "EUR",
"status": "completed",
"provider": "hoppacard"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/wallet.withdrawalwallet.withdrawalRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a wallet withdrawal or debit transaction is processed. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "wallet.withdrawal",
"domain": "wallet",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": "1002",
"walletId": "wallet_123",
"userId": "12345",
"amount": "50.00",
"currency": "EUR",
"status": "completed",
"provider": "hoppacard"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: wallet.withdrawal
domain · string · requiredBusiness domain for the event.
Allowed: wallet
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `wallet.withdrawal`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "wallet.withdrawal",
"domain": "wallet",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": "1002",
"walletId": "wallet_123",
"userId": "12345",
"amount": "50.00",
"currency": "EUR",
"status": "completed",
"provider": "hoppacard"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/wallet.refundwallet.refundRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a crypto refund is processed. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "wallet.refund",
"domain": "wallet",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": "1001",
"userId": "12345",
"amount": "10.00",
"currency": "USDT",
"chain": "TRON",
"address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"status": "completed",
"transferId": "transfer_123",
"transactionHash": "0x1234567890abcdef",
"provider": "hoppacard"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: wallet.refund
domain · string · requiredBusiness domain for the event.
Allowed: wallet
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `wallet.refund`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "wallet.refund",
"domain": "wallet",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": "1001",
"userId": "12345",
"amount": "10.00",
"currency": "USDT",
"chain": "TRON",
"address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"status": "completed",
"transferId": "transfer_123",
"transactionHash": "0x1234567890abcdef",
"provider": "hoppacard"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/budget.createdbudget.createdRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a budget is created. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "budget.created",
"domain": "budget",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"budgetId": "budget_123",
"name": "Main EUR Budget",
"currency": "EUR",
"amount": "1000.00",
"spent": "125.00",
"remaining": "875.00",
"period": "monthly",
"status": "active"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: budget.created
domain · string · requiredBusiness domain for the event.
Allowed: budget
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `budget.created`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "budget.created",
"domain": "budget",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"budgetId": "budget_123",
"name": "Main EUR Budget",
"currency": "EUR",
"amount": "1000.00",
"spent": "125.00",
"remaining": "875.00",
"period": "monthly",
"status": "active"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/budget.updatedbudget.updatedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a budget is updated. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "budget.updated",
"domain": "budget",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"budgetId": "budget_123",
"name": "Main EUR Budget",
"currency": "EUR",
"amount": "1000.00",
"spent": "125.00",
"remaining": "875.00",
"period": "monthly",
"status": "active"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: budget.updated
domain · string · requiredBusiness domain for the event.
Allowed: budget
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `budget.updated`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "budget.updated",
"domain": "budget",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"budgetId": "budget_123",
"name": "Main EUR Budget",
"currency": "EUR",
"amount": "1000.00",
"spent": "125.00",
"remaining": "875.00",
"period": "monthly",
"status": "active"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/budget.deletedbudget.deletedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a budget is deleted. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "budget.deleted",
"domain": "budget",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"budgetId": "budget_123",
"name": "Main EUR Budget",
"currency": "EUR",
"amount": "1000.00",
"spent": "125.00",
"remaining": "875.00",
"period": "monthly",
"status": "deleted"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: budget.deleted
domain · string · requiredBusiness domain for the event.
Allowed: budget
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `budget.deleted`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "budget.deleted",
"domain": "budget",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"budgetId": "budget_123",
"name": "Main EUR Budget",
"currency": "EUR",
"amount": "1000.00",
"spent": "125.00",
"remaining": "875.00",
"period": "monthly",
"status": "deleted"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/budget.transaction.closedbudget.transaction.closedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a budget transaction is closed. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "budget.transaction.closed",
"domain": "budget",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": "1001",
"userId": "12345",
"budgetId": "budget_123",
"amount": "15.00",
"currency": "EUR",
"status": "closed",
"type": "DEBIT"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: budget.transaction.closed
domain · string · requiredBusiness domain for the event.
Allowed: budget
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `budget.transaction.closed`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "budget.transaction.closed",
"domain": "budget",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": "1001",
"userId": "12345",
"budgetId": "budget_123",
"amount": "15.00",
"currency": "EUR",
"status": "closed",
"type": "DEBIT"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/budget.creditedbudget.creditedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking budget receives funds. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "budget.credited",
"domain": "budget",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": 1001,
"externalTransactionId": "ext_tx_123",
"userId": 12345,
"budgetId": "budget_123",
"amount": 75,
"currency": "EUR",
"source": "BANK_TRANSFER",
"reference": "Invoice 123",
"remitterName": "Example Ltd"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: budget.credited
domain · string · requiredBusiness domain for the event.
Allowed: budget
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `budget.credited`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "budget.credited",
"domain": "budget",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": 1001,
"externalTransactionId": "ext_tx_123",
"userId": 12345,
"budgetId": "budget_123",
"amount": 75,
"currency": "EUR",
"source": "BANK_TRANSFER",
"reference": "Invoice 123",
"remitterName": "Example Ltd"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/budget.debitedbudget.debitedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking budget is debited. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "budget.debited",
"domain": "budget",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": 1002,
"externalTransactionId": "ext_tx_456",
"userId": 12345,
"budgetId": "budget_123",
"amount": 25,
"currency": "EUR",
"source": "CARD_PAYMENT"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: budget.debited
domain · string · requiredBusiness domain for the event.
Allowed: budget
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `budget.debited`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "budget.debited",
"domain": "budget",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": 1002,
"externalTransactionId": "ext_tx_456",
"userId": 12345,
"budgetId": "budget_123",
"amount": 25,
"currency": "EUR",
"source": "CARD_PAYMENT"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/budget.credit_pendingbudget.credit_pendingRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking budget credit is pending settlement. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "budget.credit_pending",
"domain": "budget",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "BoxCreditPending",
"budgetId": "budget_123",
"budgetName": "Operations Budget",
"settlementPriceAmount": 1200,
"settlementPriceCurrency": "GBP",
"valueDateTime": "2026-04-29T00:00:00Z"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: budget.credit_pending
domain · string · requiredBusiness domain for the event.
Allowed: budget
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `budget.credit_pending`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "budget.credit_pending",
"domain": "budget",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "BoxCreditPending",
"budgetId": "budget_123",
"budgetName": "Operations Budget",
"settlementPriceAmount": 1200,
"settlementPriceCurrency": "GBP",
"valueDateTime": "2026-04-29T00:00:00Z"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/card.createdcard.createdRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a card is created. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.created",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"cardId": 555,
"cardNumber": "****-****-****-4242",
"lastFour": "4242",
"status": "active",
"currency": "EUR"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: card.created
domain · string · requiredBusiness domain for the event.
Allowed: card
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `card.created`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.created",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"cardId": 555,
"cardNumber": "****-****-****-4242",
"lastFour": "4242",
"status": "active",
"currency": "EUR"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/card.activatedcard.activatedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a card is activated. Virtual cards may emit this immediately after creation. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.activated",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"cardId": 555
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: card.activated
domain · string · requiredBusiness domain for the event.
Allowed: card
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `card.activated`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.activated",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"cardId": 555
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/card.updatedcard.updatedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a card status changes. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.updated",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"cardId": 555,
"previousStatus": "PENDING",
"newStatus": "ACTIVE",
"lastFour": "4242"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: card.updated
domain · string · requiredBusiness domain for the event.
Allowed: card
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `card.updated`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.updated",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"cardId": 555,
"previousStatus": "PENDING",
"newStatus": "ACTIVE",
"lastFour": "4242"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/card.deletedcard.deletedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a card is deleted or cancelled. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.deleted",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"cardId": 555,
"previousStatus": "ACTIVE",
"newStatus": "CANCELLED"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: card.deleted
domain · string · requiredBusiness domain for the event.
Allowed: card
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `card.deleted`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.deleted",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"cardId": 555,
"previousStatus": "ACTIVE",
"newStatus": "CANCELLED"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/card.shippedcard.shippedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a physical card is shipped. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.shipped",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"cardId": 555,
"trackingNumber": "TRACK123",
"shippingCarrier": "DHL",
"shippedAt": "2026-04-28T10:15:30Z"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: card.shipped
domain · string · requiredBusiness domain for the event.
Allowed: card
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `card.shipped`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.shipped",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"cardId": 555,
"trackingNumber": "TRACK123",
"shippingCarrier": "DHL",
"shippedAt": "2026-04-28T10:15:30Z"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/fee.chargedfee.chargedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Crypto cards tier_fee_charged or card_issuance_fee customer transaction completes. Amount is the signed ledger amount; transactionId is the local reference and externalTransactionId is the provider transfer ID. Deduplicate retries by event id. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "fee.charged",
"domain": "transaction",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": "8178",
"externalTransactionId": "2100585559431249922",
"userId": "12345",
"transactionType": "fees",
"feeType": "tier_fee_charged",
"amount": -10,
"currency": "USD",
"status": "completed",
"description": "fees: tier_fee_charged",
"transactionTime": "2026-09-17T13:59:00Z"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: fee.charged
domain · string · requiredBusiness domain for the event.
Allowed: transaction
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `fee.charged`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "fee.charged",
"domain": "transaction",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": "8178",
"externalTransactionId": "2100585559431249922",
"userId": "12345",
"transactionType": "fees",
"feeType": "tier_fee_charged",
"amount": -10,
"currency": "USD",
"status": "completed",
"description": "fees: tier_fee_charged",
"transactionTime": "2026-09-17T13:59:00Z"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/card.transactioncard.transactionRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent for card purchases, refunds, reversals, fee transactions, freezes, and unfreezes. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.transaction",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": 1001,
"externalTransactionId": "card_tx_123",
"userId": 12345,
"accountId": 321,
"cardId": 555,
"externalCardId": "card_ext_123",
"transactionType": "card_payment",
"amount": 42.5,
"currency": "EUR",
"status": "completed",
"description": "CARD PAYMENT: Example Merchant",
"transactionDate": "2026-04-28T10:15:30Z",
"merchantName": "Example Merchant",
"merchantMid": "merchant_mid_123",
"merchantCity": "London",
"merchantCountry": "GB",
"merchantState": "ENG",
"merchantZipcode": "EC1A1BB",
"mcc": "5812",
"mccCategory": "Restaurants",
"fee": 0.35,
"transactionCurrency": "GBP",
"transactionAmount": "36.25",
"clientTransactionId": "client_tx_123",
"cardTransactionId": "card_trace_123",
"relatedCardTransactionId": "card_trace_parent_123",
"remark": "Approved",
"detail": "Card transaction processed",
"type": "CONSUMPTION"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: card.transaction
domain · string · requiredBusiness domain for the event.
Allowed: card
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `card.transaction`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.transaction",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": 1001,
"externalTransactionId": "card_tx_123",
"userId": 12345,
"accountId": 321,
"cardId": 555,
"externalCardId": "card_ext_123",
"transactionType": "card_payment",
"amount": 42.5,
"currency": "EUR",
"status": "completed",
"description": "CARD PAYMENT: Example Merchant",
"transactionDate": "2026-04-28T10:15:30Z",
"merchantName": "Example Merchant",
"merchantMid": "merchant_mid_123",
"merchantCity": "London",
"merchantCountry": "GB",
"merchantState": "ENG",
"merchantZipcode": "EC1A1BB",
"mcc": "5812",
"mccCategory": "Restaurants",
"fee": 0.35,
"transactionCurrency": "GBP",
"transactionAmount": "36.25",
"clientTransactionId": "client_tx_123",
"cardTransactionId": "card_trace_123",
"relatedCardTransactionId": "card_trace_parent_123",
"remark": "Approved",
"detail": "Card transaction processed",
"type": "CONSUMPTION"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/card.topupcard.topupRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when value is loaded onto a card. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.topup",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": 1001,
"externalTransactionId": "card_tx_123",
"userId": 12345,
"accountId": 321,
"cardId": 555,
"externalCardId": "card_ext_123",
"transactionType": "card_topup",
"amount": 42.5,
"currency": "EUR",
"status": "completed",
"description": "CARD PAYMENT: Example Merchant",
"transactionDate": "2026-04-28T10:15:30Z",
"merchantName": "Example Merchant",
"merchantMid": "merchant_mid_123",
"merchantCity": "London",
"merchantCountry": "GB",
"merchantState": "ENG",
"merchantZipcode": "EC1A1BB",
"mcc": "5812",
"mccCategory": "Restaurants",
"fee": 0.35,
"transactionCurrency": "GBP",
"transactionAmount": "36.25",
"clientTransactionId": "client_tx_123",
"cardTransactionId": "card_trace_123",
"relatedCardTransactionId": "card_trace_parent_123",
"remark": "Approved",
"detail": "Card transaction processed",
"type": "CONSUMPTION"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: card.topup
domain · string · requiredBusiness domain for the event.
Allowed: card
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `card.topup`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.topup",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": 1001,
"externalTransactionId": "card_tx_123",
"userId": 12345,
"accountId": 321,
"cardId": 555,
"externalCardId": "card_ext_123",
"transactionType": "card_topup",
"amount": 42.5,
"currency": "EUR",
"status": "completed",
"description": "CARD PAYMENT: Example Merchant",
"transactionDate": "2026-04-28T10:15:30Z",
"merchantName": "Example Merchant",
"merchantMid": "merchant_mid_123",
"merchantCity": "London",
"merchantCountry": "GB",
"merchantState": "ENG",
"merchantZipcode": "EC1A1BB",
"mcc": "5812",
"mccCategory": "Restaurants",
"fee": 0.35,
"transactionCurrency": "GBP",
"transactionAmount": "36.25",
"clientTransactionId": "client_tx_123",
"cardTransactionId": "card_trace_123",
"relatedCardTransactionId": "card_trace_parent_123",
"remark": "Approved",
"detail": "Card transaction processed",
"type": "CONSUMPTION"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/card.unloadcard.unloadRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when value is unloaded from a card. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.unload",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": 1001,
"externalTransactionId": "card_tx_123",
"userId": 12345,
"accountId": 321,
"cardId": 555,
"externalCardId": "card_ext_123",
"transactionType": "card_unload",
"amount": 42.5,
"currency": "EUR",
"status": "completed",
"description": "CARD PAYMENT: Example Merchant",
"transactionDate": "2026-04-28T10:15:30Z",
"merchantName": "Example Merchant",
"merchantMid": "merchant_mid_123",
"merchantCity": "London",
"merchantCountry": "GB",
"merchantState": "ENG",
"merchantZipcode": "EC1A1BB",
"mcc": "5812",
"mccCategory": "Restaurants",
"fee": 0.35,
"transactionCurrency": "GBP",
"transactionAmount": "36.25",
"clientTransactionId": "client_tx_123",
"cardTransactionId": "card_trace_123",
"relatedCardTransactionId": "card_trace_parent_123",
"remark": "Approved",
"detail": "Card transaction processed",
"type": "CONSUMPTION"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: card.unload
domain · string · requiredBusiness domain for the event.
Allowed: card
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `card.unload`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.unload",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"transactionId": 1001,
"externalTransactionId": "card_tx_123",
"userId": 12345,
"accountId": 321,
"cardId": 555,
"externalCardId": "card_ext_123",
"transactionType": "card_unload",
"amount": 42.5,
"currency": "EUR",
"status": "completed",
"description": "CARD PAYMENT: Example Merchant",
"transactionDate": "2026-04-28T10:15:30Z",
"merchantName": "Example Merchant",
"merchantMid": "merchant_mid_123",
"merchantCity": "London",
"merchantCountry": "GB",
"merchantState": "ENG",
"merchantZipcode": "EC1A1BB",
"mcc": "5812",
"mccCategory": "Restaurants",
"fee": 0.35,
"transactionCurrency": "GBP",
"transactionAmount": "36.25",
"clientTransactionId": "client_tx_123",
"cardTransactionId": "card_trace_123",
"relatedCardTransactionId": "card_trace_parent_123",
"remark": "Approved",
"detail": "Card transaction processed",
"type": "CONSUMPTION"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/card.state_updatedcard.state_updatedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking card state changes. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.state_updated",
"domain": "card",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"cardId": 555,
"externalCardId": "card_ext_123",
"userId": 12345,
"previousState": "ACTIVE",
"currentState": "SUSPENDED",
"status": "blocked"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: card.state_updated
domain · string · requiredBusiness domain for the event.
Allowed: card
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `card.state_updated`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.state_updated",
"domain": "card",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"cardId": 555,
"externalCardId": "card_ext_123",
"userId": 12345,
"previousState": "ACTIVE",
"currentState": "SUSPENDED",
"status": "blocked"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/card.3ds.otpcard.3ds.otpRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a card 3DS OTP is received from Crypto cards. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.3ds.otp",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"cardId": 555,
"externalCardId": "card_ext_123",
"otp": "123456",
"expiresAt": "2026-04-28T10:20:30Z"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: card.3ds.otp
domain · string · requiredBusiness domain for the event.
Allowed: card
provider · string · requiredProvider that originated the event.
Allowed: hoppacard
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `card.3ds.otp`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.3ds.otp",
"domain": "card",
"provider": "hoppacard",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"cardId": 555,
"externalCardId": "card_ext_123",
"otp": "123456",
"expiresAt": "2026-04-28T10:20:30Z"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/card.3ds_auth_requestcard.3ds_auth_requestRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking card 3DS authentication request requires OTP handling. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.3ds_auth_request",
"domain": "card",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"cardId": 555,
"externalCardId": "card_ext_123",
"merchantName": "Example Merchant",
"amount": 42.5,
"currency": "EUR",
"transactionId": "txn_123",
"otp": "123456"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: card.3ds_auth_request
domain · string · requiredBusiness domain for the event.
Allowed: card
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `card.3ds_auth_request`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "card.3ds_auth_request",
"domain": "card",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"cardId": 555,
"externalCardId": "card_ext_123",
"merchantName": "Example Merchant",
"amount": 42.5,
"currency": "EUR",
"transactionId": "txn_123",
"otp": "123456"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/digitalwallet.token_transitiondigitalwallet.token_transitionRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking digital wallet token changes state. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "digitalwallet.token_transition",
"domain": "digitalwallet",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "DigitalWalletTokenTransition",
"cardId": "card_ext_123",
"tokenId": "token_123",
"walletType": "APPLE_PAY",
"eventTime": "2026-04-28T10:15:30Z",
"previousState": "INACTIVE",
"currentState": "ACTIVE"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: digitalwallet.token_transition
domain · string · requiredBusiness domain for the event.
Allowed: digitalwallet
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `digitalwallet.token_transition`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "digitalwallet.token_transition",
"domain": "digitalwallet",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "DigitalWalletTokenTransition",
"cardId": "card_ext_123",
"tokenId": "token_123",
"walletType": "APPLE_PAY",
"eventTime": "2026-04-28T10:15:30Z",
"previousState": "INACTIVE",
"currentState": "ACTIVE"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/cardholder.statuscardholder.statusRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent whenever a cardholder status update is processed. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "cardholder.status",
"domain": "cardholder",
"provider": "bank",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"status": "Active"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: cardholder.status
domain · string · requiredBusiness domain for the event.
Allowed: cardholder
provider · string · requiredProvider that originated the event.
Allowed: bank
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `cardholder.status`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "cardholder.status",
"domain": "cardholder",
"provider": "bank",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"status": "Active"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/cardholder.createdcardholder.createdRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a cardholder is created by the banking provider. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "cardholder.created",
"domain": "cardholder",
"provider": "bank",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"status": "Active",
"cardholderId": "cardholder_123"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: cardholder.created
domain · string · requiredBusiness domain for the event.
Allowed: cardholder
provider · string · requiredProvider that originated the event.
Allowed: bank
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `cardholder.created`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "cardholder.created",
"domain": "cardholder",
"provider": "bank",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"status": "Active",
"cardholderId": "cardholder_123"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/cardholder.approvedcardholder.approvedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a cardholder is approved by the banking provider. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "cardholder.approved",
"domain": "cardholder",
"provider": "bank",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"status": "Active"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: cardholder.approved
domain · string · requiredBusiness domain for the event.
Allowed: cardholder
provider · string · requiredProvider that originated the event.
Allowed: bank
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `cardholder.approved`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "cardholder.approved",
"domain": "cardholder",
"provider": "bank",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"status": "Active"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/cardholder.deletedcardholder.deletedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a cardholder is deleted by the banking provider. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "cardholder.deleted",
"domain": "cardholder",
"provider": "bank",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"cardholderId": "cardholder_123"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: cardholder.deleted
domain · string · requiredBusiness domain for the event.
Allowed: cardholder
provider · string · requiredProvider that originated the event.
Allowed: bank
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `cardholder.deleted`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "cardholder.deleted",
"domain": "cardholder",
"provider": "bank",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"userId": 12345,
"cardholderId": "cardholder_123"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/person.createdperson.createdRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking associated person is created. `data.personId` is the canonical person identifier; `data.email` is the canonical person email when available. Provider aliases `data.id` and `data.primaryEmailAddress` may also be included. Nonblank canonical fields take precedence when both forms are supplied. The flat data object includes user/account context and the current `associatedPeople` list. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "person.created",
"domain": "person",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PersonCreated",
"userId": 12345,
"companyId": 42,
"userEmail": "user@example.com",
"accountType": "personal",
"equalsAccountId": "acc_eq_123",
"equalsApplicationId": "app_eq_123",
"personId": "person_123",
"id": "person_123",
"eventTime": "2026-04-28T10:15:30Z",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@example.com",
"primaryEmailAddress": "jane.doe@example.com",
"associatedPeople": [
{
"id": 456,
"externalId": "person_123",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@example.com",
"associationType": ""
}
]
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: person.created
domain · string · requiredBusiness domain for the event.
Allowed: person
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `person.created`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "person.created",
"domain": "person",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PersonCreated",
"userId": 12345,
"companyId": 42,
"userEmail": "user@example.com",
"accountType": "personal",
"equalsAccountId": "acc_eq_123",
"equalsApplicationId": "app_eq_123",
"personId": "person_123",
"id": "person_123",
"eventTime": "2026-04-28T10:15:30Z",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@example.com",
"primaryEmailAddress": "jane.doe@example.com",
"associatedPeople": [
{
"id": 456,
"externalId": "person_123",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@example.com",
"associationType": ""
}
]
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/kyc.updatekyc.updateRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when Banking updates a user's KYC review status. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "kyc.update",
"domain": "kyc",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "KycUpdate",
"correlationId": "corr_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "PENDING_DOCUMENTS",
"personId": "person_123",
"requiredAction": "upload_bank_statement",
"actionUrl": "https://app.equalsmoney.com/kyc/upload"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: kyc.update
domain · string · requiredBusiness domain for the event.
Allowed: kyc
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `kyc.update`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "kyc.update",
"domain": "kyc",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "KycUpdate",
"correlationId": "corr_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "PENDING_DOCUMENTS",
"personId": "person_123",
"requiredAction": "upload_bank_statement",
"actionUrl": "https://app.equalsmoney.com/kyc/upload"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/kyc.information_requestkyc.information_requestRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when Banking requests additional KYC documents. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "kyc.information_request",
"domain": "kyc",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "KycInformationRequest",
"correlationId": "corr_123",
"eventTime": "2026-04-28T10:15:30Z",
"requiredDocuments": [
"proof_of_address",
"source_of_funds"
]
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: kyc.information_request
domain · string · requiredBusiness domain for the event.
Allowed: kyc
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `kyc.information_request`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "kyc.information_request",
"domain": "kyc",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "KycInformationRequest",
"correlationId": "corr_123",
"eventTime": "2026-04-28T10:15:30Z",
"requiredDocuments": [
"proof_of_address",
"source_of_funds"
]
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/recipient.createdrecipient.createdRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking recipient is created. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "recipient.created",
"domain": "recipient",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "RecipientCreated",
"recipientId": "recipient_123",
"eventTime": "2026-04-28T10:15:30Z",
"name": "Example Supplier Ltd"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: recipient.created
domain · string · requiredBusiness domain for the event.
Allowed: recipient
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `recipient.created`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "recipient.created",
"domain": "recipient",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "RecipientCreated",
"recipientId": "recipient_123",
"eventTime": "2026-04-28T10:15:30Z",
"name": "Example Supplier Ltd"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/recipient.deletedrecipient.deletedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking recipient is deleted. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "recipient.deleted",
"domain": "recipient",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "RecipientDeleted",
"recipientId": "recipient_123",
"eventTime": "2026-04-28T10:15:30Z"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: recipient.deleted
domain · string · requiredBusiness domain for the event.
Allowed: recipient
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `recipient.deleted`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "recipient.deleted",
"domain": "recipient",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "RecipientDeleted",
"recipientId": "recipient_123",
"eventTime": "2026-04-28T10:15:30Z"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/payment.createdpayment.createdRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking payment is created. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.created",
"domain": "payment",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentCreated",
"paymentId": "payment_123",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "PROCESSING",
"amount": 250,
"currency": "GBP",
"recipientId": "recipient_123",
"reference": "Invoice 123"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: payment.created
domain · string · requiredBusiness domain for the event.
Allowed: payment
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `payment.created`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.created",
"domain": "payment",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentCreated",
"paymentId": "payment_123",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "PROCESSING",
"amount": 250,
"currency": "GBP",
"recipientId": "recipient_123",
"reference": "Invoice 123"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/payment.returnedpayment.returnedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking payment is returned. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.returned",
"domain": "payment",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentReturned",
"paymentId": "payment_123",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "RETURNED",
"returnReason": "Beneficiary account closed"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: payment.returned
domain · string · requiredBusiness domain for the event.
Allowed: payment
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `payment.returned`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "payment.returned",
"domain": "payment",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentReturned",
"paymentId": "payment_123",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "RETURNED",
"returnReason": "Beneficiary account closed"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/fee.createdfee.createdRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking fee is created. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "fee.created",
"domain": "fee",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "FeeCreated",
"feeId": "fee_123",
"eventTime": "2026-04-28T10:15:30Z",
"feeType": "payment_fee",
"amount": 2.5,
"currency": "GBP"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: fee.created
domain · string · requiredBusiness domain for the event.
Allowed: fee
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `fee.created`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "fee.created",
"domain": "fee",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "FeeCreated",
"feeId": "fee_123",
"eventTime": "2026-04-28T10:15:30Z",
"feeType": "payment_fee",
"amount": 2.5,
"currency": "GBP"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/paymentbatch.createdpaymentbatch.createdRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking payment batch is created. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "paymentbatch.created",
"domain": "paymentbatch",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentBatchCreated",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "CREATED",
"totalAmount": 1500,
"currency": "GBP",
"paymentCount": 3
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: paymentbatch.created
domain · string · requiredBusiness domain for the event.
Allowed: paymentbatch
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `paymentbatch.created`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "paymentbatch.created",
"domain": "paymentbatch",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentBatchCreated",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "CREATED",
"totalAmount": 1500,
"currency": "GBP",
"paymentCount": 3
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/paymentbatch.cancelledpaymentbatch.cancelledRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking payment batch is cancelled. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "paymentbatch.cancelled",
"domain": "paymentbatch",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentBatchCancelled",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "CANCELLED"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: paymentbatch.cancelled
domain · string · requiredBusiness domain for the event.
Allowed: paymentbatch
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `paymentbatch.cancelled`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "paymentbatch.cancelled",
"domain": "paymentbatch",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentBatchCancelled",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "CANCELLED"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/paymentbatch.validation_errorpaymentbatch.validation_errorRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking payment batch fails validation. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "paymentbatch.validation_error",
"domain": "paymentbatch",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentBatchValidationError",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"errors": [
"Recipient account number is invalid",
"Payment amount exceeds limit"
]
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: paymentbatch.validation_error
domain · string · requiredBusiness domain for the event.
Allowed: paymentbatch
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `paymentbatch.validation_error`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "paymentbatch.validation_error",
"domain": "paymentbatch",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentBatchValidationError",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"errors": [
"Recipient account number is invalid",
"Payment amount exceeds limit"
]
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/paymentbatch.processingpaymentbatch.processingRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking payment batch enters processing. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "paymentbatch.processing",
"domain": "paymentbatch",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentBatchProcessing",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "PROCESSING"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: paymentbatch.processing
domain · string · requiredBusiness domain for the event.
Allowed: paymentbatch
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `paymentbatch.processing`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "paymentbatch.processing",
"domain": "paymentbatch",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentBatchProcessing",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "PROCESSING"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/paymentbatch.completedpaymentbatch.completedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking payment batch completes. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "paymentbatch.completed",
"domain": "paymentbatch",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentBatchCompleted",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "COMPLETED",
"successCount": 2,
"failureCount": 1
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: paymentbatch.completed
domain · string · requiredBusiness domain for the event.
Allowed: paymentbatch
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `paymentbatch.completed`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "paymentbatch.completed",
"domain": "paymentbatch",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentBatchCompleted",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "COMPLETED",
"successCount": 2,
"failureCount": 1
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/paymentbatchorder.createdpaymentbatchorder.createdRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking payment batch FX order is created. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "paymentbatchorder.created",
"domain": "paymentbatchorder",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentBatchOrderCreated",
"orderId": "order_123",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "CREATED"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: paymentbatchorder.created
domain · string · requiredBusiness domain for the event.
Allowed: paymentbatchorder
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `paymentbatchorder.created`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "paymentbatchorder.created",
"domain": "paymentbatchorder",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentBatchOrderCreated",
"orderId": "order_123",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "CREATED"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/paymentbatchorder.completedpaymentbatchorder.completedRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking payment batch FX order completes. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "paymentbatchorder.completed",
"domain": "paymentbatchorder",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentBatchOrderCompleted",
"orderId": "order_123",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "COMPLETED"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: paymentbatchorder.completed
domain · string · requiredBusiness domain for the event.
Allowed: paymentbatchorder
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `paymentbatchorder.completed`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "paymentbatchorder.completed",
"domain": "paymentbatchorder",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentBatchOrderCompleted",
"orderId": "order_123",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "COMPLETED"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
POST/webhooks/outbound/paymentbatchorder.cancelledpaymentbatchorder.cancelledRequest & responses +
This operation documents an outbound webhook request that CryptoCard Platform sends to your configured webhook URL. Sent when a Banking payment batch FX order is cancelled. Configure the destination URL and webhook secret on the company configuration. We send an HTTP `POST` with `Content-Type: application/json` and `X-Hoppacard-Signature`. The signature is a lowercase hex HMAC-SHA256 digest of the exact request body, using your webhook secret as the key. Return any 2xx status code to acknowledge the webhook. Delivery is retried for network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses. The initial request may be followed by up to 15 retries over approximately 76 hours. Other HTTP 4xx responses are treated as permanent failures. Consumers must process webhook identifiers idempotently because duplicate delivery is possible.
curl --request POST 'https://api.your-company.example/webhooks/hoppa' \
-H 'X-Hoppacard-Signature: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6a' \
-H 'X-Hoppacard-Webhook-Id: 62ff4fa912be4b3ab4f163dc45a337f4' \
-H 'X-Hoppacard-Delivery-Attempt: 1' \
-H 'Content-Type: application/json' \
--data '{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "paymentbatchorder.cancelled",
"domain": "paymentbatchorder",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentBatchOrderCancelled",
"orderId": "order_123",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "CANCELLED"
}
}'Parameters
X-Hoppacard-SignatureheaderstringrequiredExample: c1f6d6d2e8b9f1f13b0f7a2b8cc8d4f44aa50ef0997b0c0e86f8f4f6112e3c6aX-Hoppacard-Webhook-IdheaderstringrequiredExample: 62ff4fa912be4b3ab4f163dc45a337f4X-Hoppacard-Delivery-AttemptheaderintegerrequiredExample: 1Request fields and validation
id · string · requiredUnique webhook event id.
type · string · requiredWebhook event type.
Allowed: paymentbatchorder.cancelled
domain · string · requiredBusiness domain for the event.
Allowed: paymentbatchorder
provider · string · requiredProvider that originated the event.
Allowed: equalsmoney
timestamp · string · requiredUTC time when the webhook was created.
data · object · requiredEvent-specific payload for `paymentbatchorder.cancelled`.
Example request body · replace placeholders
{
"id": "evt_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"type": "paymentbatchorder.cancelled",
"domain": "paymentbatchorder",
"provider": "equalsmoney",
"timestamp": "2026-04-28T10:15:30Z",
"data": {
"accountId": "acc_eq_123",
"messageId": "msg_01HX7B7MZ4Q4Y9R1H2J3K4L5M6",
"webhookEventTypeName": "PaymentBatchOrderCancelled",
"orderId": "order_123",
"batchId": "batch_123",
"eventTime": "2026-04-28T10:15:30Z",
"status": "CANCELLED"
}
}200Return any 2xx response to acknowledge receipt.No response body
No response body is required for this acknowledgement.Examples use safe placeholder values. Confirm required fields, enums and programme availability in the live Scalar schema before sending production traffic.
Make retries boring and safe.
Fix the request. Do not retry unchanged.
Fix credentials or company scope.
Confirm the resource belongs to this user and company.
Fetch current state; the operation may already exist.
Wait for Retry-After, then retry with jitter.
Retry only idempotent calls with exponential backoff.
Production readiness checklist
Open the live API reference.
Use this guide for the workflow and Scalar for the exact current schema and response model.