Skip to main content
Sandbox tokens, card numbers, and API keys in this documentation are examples only. Values may differ per environment or tenant. Never use production credentials in shared sandboxes or commit secrets to source control.

Environments and base URLs

Authentication in tests

  • Send header api_key on every request (value issued for your tenant in that environment).
  • Scopes in the Partner API are grouped in the OpenAPI tags Partner, Partner Send, and Partner Full. Use an API key that includes the scope required by the endpoint you are calling.
Keep api_key on your server only. Do not embed it in mobile apps or public web clients.

Test card number (sandbox)

Use these sandbox-only PANs where your flow accepts a test card number (for example via VGS or a widget that tokenizes before RaaS). Confirm with Leapfinancial which rows apply to your tenant and processor; lists can change.

Card field tokenization (VGS)

Some integrations send sensitive card fields (PAN, CVV) to Very Good Security (VGS) outbound proxy endpoints instead of posting raw values to RaaS. The vault identifier in the hostname is tenant- or environment-specific; replace it with your own value (for example a REST Client variable {{vgsVaultId}} declared in your .http file). Sandbox URL pattern
Example request (Content-Type: application/json):
Example response (shape may vary slightly by VGS route configuration; tokens below are illustrative):
Use the values under json (e.g. tok_sandbox_…) as number / securityCode (or equivalent fields) when calling Partner funding or card endpoints—never send live PAN/CVV to RaaS from untrusted clients.
Do not commit real card data, production vault IDs, or proxy credentials. The PAN/CVV in the request example are test-only patterns for sandbox documentation.

UBN and bank-style test data

For POST /user/funding/source/ubn-account/add/{userToken} (and related flows), sandbox account numbers are often numeric strings in a fixed length for your country (for example a value shaped like 002320275621938815). Validate the exact test account list for your tenant and country with Leap—do not assume one global test account across all partners.

Phones, users, and contacts

  • Use E.164 phone numbers with the correct dial country code for getUserTokenV2 and registration flows.
  • For duplicate contact tests, reuse the same phone under the same userToken and expect a 400-class error with a clear reason / code (see OpenAPI for createContact).

getUserTokenV2 — scenario matrix

Use POST /auth/get-user-token-v2 with a valid api_key so the request reaches this handler. Body: GetUserTokenParams (phoneNumber and/or email, optional countryCode). The table lists handler outcomes (successResponse, badRequestResponse, notFoundResponse, errorResponse) and the 401 case now declared in OpenAPI via @Response<ErrorResponse>(401, "Missing or invalid API key") (enforcement may still occur at the gateway before TSOA). Ready-to-run examples for these rows live in clients/clientv5/partner-ask-v1.http — search for getUserToken-v2 —.
For ERROR_COUNTRY_NOT_SUPPORTED, use a real sandbox mobile your TPE accepts, then deliberately pass the wrong countryCode. If validation is stubbed in a local dev stack, this row may not fire until you hit a CV-like environment.
Responses often include both reason (human-readable) and code (machine-readable). Treat 400 as “fix the request or tenant context”; 404 as “user does not exist — register or fix the alias”; 500 as “retry later / escalate with timestamps.” For getUserTokenV2, 500 uses the same generic internal payload (ERROR_INTERNAL_SERVER_ERROR).

registerUserV2 — scenario matrix

POST /auth/register-user-v2. Handler returns 200 with userId when registration is queued; 400 for tenant, country, schema, DOB, already enrolled, or phone validation (NumiBadRequestError); 500 for unexpected or platform errors (generic body, no raw error.message). 401 is documented in OpenAPI (@Response<ErrorResponse>(401, "Missing or invalid API key")).

getProfile — scenario matrix

GET /user/profile/{phoneOrEmail}. Resolves a registered user by E.164 phone (with +) or email, loads the subscriber record for createdAt, and enriches the response with CIP process status from cipService.getProcessInfo. Returns a UserProfile with identity, contact, address, optional geo coordinates (latitude, longitude), and CIP status. 404 when the user or subscriber is missing; 500 on unexpected storage/CIP/platform errors (sanitized ErrorResponse, no raw error.message). 401 is declared in OpenAPI (@Response<ErrorResponse>(401, "Missing or invalid API key")). OpenAPI per-status tables come from openapi-examples.json (_mintlifyResponseDescriptions.getProfile); keep this section and that JSON in sync. Ready-to-run examples live in clients/clientv5/partner-ask-v1.http — search for getProfile —.

listContacts — scenario matrix

GET /user/contacts/{userToken}. Resolves the path userToken via user storage: 404 if there is no user; 200 with an array (possibly empty) when the user exists; 500 if contact storage throws. Use api_key with partner or partner_send scope (401/403 come from the gateway when the key is missing, invalid, or out of scope).

createContact — scenario matrix

POST /user/contacts/{userToken}. 404 when userToken does not resolve to a user; 400 for missing names, bad phone, missing country, duplicates; 500 sanitized on unknown errors (NumiBadRequestError / NumiError mapped in catch). 401 is documented in OpenAPI (same @Response<ErrorResponse>(401, …) pattern as listContacts). 422 TSOA ValidateError is no longer declared on this route; structural validation errors surface as 400 / 500 per handler.

updateContact — scenario matrix

PUT /user/contacts/{userToken}. 404 when userToken does not resolve to a user; 400 / 500 for payload or storage errors (sanitized). 401 documented in OpenAPI like other contact routes.

getAvailablePaymentMethods — scenario matrix

GET /user/corridors/available-receiver-methodtypes/{userToken} (getAvailableReceiverMethodTypes in code). Returns method type strings for corridors.

getReceivingMethods — scenario matrix

GET /user/funding/source/get-receiving-methods/{userToken}. 400 invalid tenant; 200 SOF list; 500 downstream / NumiError.

createFundingCard (add card) — scenario matrix

POST /user/funding/source/card/add/{userToken} (OperationId: createFundingCard). 400 card/issuer validation; 200 existing or new PM; 500 unexpected.

addUBNAccount — scenario matrix

POST /user/funding/source/ubn-account/add/{userToken}. 403 user/tenant; 400 UBN validation / duplicate; 500 platform failure.

getPaymentMethodV2 — scenario matrix

GET /user/funding/source/get-payment-method-v2/{userToken}?id=.... 200 when the payment method exists for the subscriber; 404 when there is no subscriber or the id is not in the user’s methods; 400 for other NumiBadRequestError paths from downstream; 500 for NumiError or unexpected failures.

requestMoneyV2 — scenario matrix

POST /user/operations/request-money-v2/{userToken}. 404 when path userToken does not resolve; 400 for corridor / contact / PM validation; 500 uses mapped NumiError or generic internal (no raw exception text). 401 in OpenAPI for missing/invalid API key.

operationQuoteV2 — scenario matrix

POST /user/operations/operation-quote-v2/{userToken}. 400 invalid quotation fields; 500 tenant/user/rate failures; 401 documented in OpenAPI.

getOperationStatus — scenario matrix

GET /user/operations/status/{userToken}/{operationId}. 404 unknown user; 400 NumiBadRequestError; 500 otherwise; 401 in OpenAPI.

getOperationQuote — scenario matrix

POST /user/operations/quotation/{userToken}. Same auth pattern as other operations routes; 401 in OpenAPI.

preQuote — scenario matrix

POST /user/operations/pre-quote/{userToken}. 500 on market/integration errors; 401 in OpenAPI.

getOperation (operation detail) — scenario matrix

GET /user/operations/detail/{id}. 500 when operation missing or tenant mismatch (OPERATION_NOT_FOUND); 401 in OpenAPI.

getOperations — scenario matrix

GET /user/operations/{userToken}. 400 when user tenant ≠ request tenant; 401 in OpenAPI.

getFrequentContacts — scenario matrix

GET /user/operations/frequent/{userToken}/{limit}. Returns the top limit contacts derived from recent operations for userToken. OpenAPI merges per-status scenario tables from openapi-examples.json (_mintlifyResponseDescriptionsgetFrequentContacts); keep this section and that JSON in sync.

Webhooks and async events

  • Register a reachable HTTPS URL (or tunnel such as ngrok) for webhook callbacks in non-production.
  • Verify signature / shared secret handling if your integration consumes outbound events.
  • Use a unique correlationId on money operations so support can correlate logs across systems.

Correlation IDs for money operations

  • requestMoney requests must include a correlationId. That same value is carried into the related funding operation, so request money and its funding step share one correlation boundary for tracing and support.
  • A standalone or spontaneous send money (not tied to that request-money → funding chain) must use its own correlationId.
  • Treat correlationId as unique per distinct money operation. The only exception is the linked case above: funding reuses the correlationId you sent with requestMoney.