Skip to main content
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​

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

Contact

CrowdSplit Engineering:

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

License