Environments and base URLs
Authentication in tests
- Send header
api_keyon every request (value issued for your tenant in that environment). - Scopes in the Partner API are grouped in the OpenAPI tags
Partner,Partner Send, andPartner Full. Use an API key that includes the scope required by the endpoint you are calling.
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
Content-Type: application/json):
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.
UBN and bank-style test data
ForPOST /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 codeforgetUserTokenV2and registration flows. - For duplicate contact tests, reuse the same
phoneunder the sameuserTokenand expect a 400-class error with a clearreason/code(see OpenAPI forcreateContact).
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 —.
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 (_mintlifyResponseDescriptions → getFrequentContacts); 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
correlationIdon money operations so support can correlate logs across systems.
Correlation IDs for money operations
requestMoneyrequests must include acorrelationId. 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
correlationIdas unique per distinct money operation. The only exception is the linked case above: funding reuses thecorrelationIdyou sent withrequestMoney.
Related pages
- Introduction — mTLS, happy path, common HTTP errors.