Version: 1.0.0

CrowdSplit API

CrowdSplit is a payment-orchestration API that routes payment, payout, transfer, buy/sell, KYC, and wallet operations across multiple upstream providers (Stripe, Bridge, and others) behind a single merchant-facing contract.

Authentication

Three auth schemes are in use:

• bearerAuth — a JWT issued via POST /api/v1/merchant/token/grant using your client_id + client_secret. Pass as Authorization: Bearer <token>. This is the default for every merchant-facing operation unless an operation documents otherwise.
• accessTokenAuth — user-scoped JWT (obtained via POST /api/auth/signin) passed in the x-access-token header. Used for admin/internal operations.
• refAppKeyAuth — subscription-service shared key passed in the Ref-App-Key header, combined with Payment-Type: recurring_payment. Used only for recurring-payment flows.

Webhooks

CrowdSplit delivers webhooks as POST requests to merchant-registered URLs. Every delivery carries the envelope { id, event, category, data } and two HTTP headers:

• CrowdSplit-Signature — HMAC-SHA256 over the raw body, formatted as t={unix-ts},v1={hex-hmac}. Verify with the secret returned at webhook registration.
• CrowdSplit-Timestamp — seconds since epoch at dispatch. Reject if the skew exceeds 5 minutes.

Use the envelope's id for idempotency — the same id is used for all retry attempts of a given notification.

Failed deliveries are retried on a linear schedule controlled by the WEBHOOK_MAXIMUM_RETRY_COUNT and WEBHOOK_RETRY_INTERVAL deployment settings. The n-th retry is scheduled n × WEBHOOK_RETRY_INTERVAL × 60 seconds after the previous failed attempt, and retries stop once n × WEBHOOK_RETRY_INTERVAL exceeds WEBHOOK_MAXIMUM_RETRY_COUNT. Total delivery attempts equal floor(WEBHOOK_MAXIMUM_RETRY_COUNT / WEBHOOK_RETRY_INTERVAL) + 1.

With the reference configuration (WEBHOOK_MAXIMUM_RETRY_COUNT=15, WEBHOOK_RETRY_INTERVAL=5) this yields 4 total delivery attempts, with retries scheduled 5, 10, and 15 minutes after each preceding failure. After the final attempt the notification is left un-acknowledged and no further attempts are made.

Pagination

List endpoints accept limit and offset query parameters. The response envelope is { count, <resource>_list }. Default and maximum limit values vary per resource; see each endpoint.

Errors

Every 4xx/5xx response uses the shared ApiErrorResponse schema: { msg, data: null, provider_message? }. provider_message is present only when the failure originated from an upstream provider, and forwards the provider's own error text verbatim.

Environments

The servers list below describes production, sandbox, and local environments. Override the server URL in your client or via the generated Postman / Bruno collections.

Authentication

HTTP: Bearer Auth

Merchant authentication token. Obtained via POST /api/v1/merchant/token/grant. Pass as: Authorization: Bearer <token>

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer
Bearer format:	JWT

API Key: accessTokenAuth

User JWT access token for user-level authentication. Used primarily for admin and internal operations.

Security Scheme Type:	apiKey
Header parameter name:	x-access-token

API Key: refAppKeyAuth

Subscription service authentication key. Used with Payment-Type: recurring_payment header for subscription payments.

Security Scheme Type:	apiKey
Header parameter name:	Ref-App-Key

Contact

CrowdSplit Engineering:

URL: https://github.com/oak-network/crowdsplit

License