Skip to main content
This page covers the partner-observable surface for the Meld integration — which endpoints return which status codes, how provider routing is decided, and what every Meld-related error code means. For full request and response schemas, see the auto-generated API reference.

​
Authentication

All endpoints use standard Sumvin partner authentication. The user is resolved from the auth context — no user_id parameter is accepted. Bank-linking endpoints require the user to have the Meld bank-linking entitlement. Without it, calls return 403 Forbidden with error code GATE-403-001.

​
Provider routing

Bank linking goes through Meld. GET /v0/accounts/link/config surfaces the link-flow configuration:
  • provider — always "meld".
  • requires_institution_selection — true (you list institutions via GET /v0/bank-linking/institutions and pass the user’s selection on link initiation).
Call the config endpoint before every link flow. The /v0/bank-linking/* namespace is Meld-specific and gated by GATE-403-001.

​
Status codes per endpoint

​
Ramp

EndpointSuccessNotable errors
GET /v0/ramp/quotes200 OK (quotes may be empty)400 RAMP_INVALID_PAIR / RAMP_UNKNOWN_ASSET / RAMP_UNSUPPORTED_ASSET, 403 RAMP_KYC_REQUIRED, 502 RAMP_PROVIDER_ERROR
POST /v0/ramp/sessions201 Created400 RAMP_INVALID_PAIR / RAMP_UNKNOWN_ASSET / RAMP_UNSUPPORTED_ASSET, 403 RAMP_KYC_REQUIRED, 502 RAMP_PROVIDER_ERROR
GET /v0/ramp/transactions200 OK403 RAMP_KYC_REQUIRED
GET /v0/ramp/transactions/{transaction_id}200 OK403 RAMP_KYC_REQUIRED, 404 RAMP_TRANSACTION_NOT_FOUND

​
Bank linking

EndpointSuccessNotable errors
GET /v0/accounts/link/config200 OK—
GET /v0/bank-linking/institutions200 OK (may be empty)403 GATE-403-001
POST /v0/accounts/link202 Accepted400 BANK_INSTITUTION_REQUIRED
POST /v0/bank-linking/accounts/{account_id}/processor-token201 Created403 BANK_ACCOUNT_UNAUTHORIZED, 404 BANK_ACCOUNT_NOT_FOUND

​
Linked account management

These endpoints operate on Meld-linked accounts.
EndpointSuccess
GET /v0/accounts200 OK
GET /v0/accounts/{account_id}200 OK
POST /v0/accounts/{account_id}/sync202 Accepted
DELETE /v0/accounts/{account_id}204 No Content

​
Ramp status lifecycle

Ramp transactions use an internal status field for partner UI:
statusMeaning
pendingSession created; user has not submitted payment.
processingPayment submitted; settlement in progress (fiat capture, on-chain delivery, or fiat payout).
completedTerminal success. For buys, destination wallet holds the balance; for sells, fiat has been routed to the user’s destination.
failedTerminal failure. Surface the reason to the user and offer a retry.
cancelledUser abandoned, or the transaction was refunded or voided.
meld_status mirrors provider-side state and is useful for debugging a stuck transaction. See the full mapping in the on-ramp quickstart.

​
Error code reference

Errors follow RFC 7807 Problem Details with a Sumvin error_code field.

​
Ramp

Error codeTitleWhen it fires
RAMP_INVALID_PAIRInvalid Asset PairBoth sides of from_asset / to_asset are fiat, or both are crypto. One side must be fiat, the other crypto.
RAMP_UNKNOWN_ASSETUnknown AssetThe crypto symbol does not exist in the Sumvin catalog for the supplied chain_id. Discover valid pairs at GET /v0/assets.
RAMP_UNSUPPORTED_ASSETAsset Not Supported for RampThe crypto pair exists in the catalog but no service provider offers a fiat ramp for it today. See Supported values for the rampable subset.
RAMP_KYC_REQUIREDKYC Required for RampThe user has no verified KYC on the Sumvin side. Route them through KYC and retry. Applies to every /v0/ramp/* endpoint.
RAMP_TRANSACTION_NOT_FOUNDRamp Transaction Not FoundGET /v0/ramp/transactions/{transaction_id} referenced an id that does not exist, or the transaction belongs to a different user.
RAMP_PROVIDER_ERRORRamp Provider ErrorUpstream provider rejected the quote or session. Re-quote, try a different service_provider, or retry after a short backoff.

​
Bank linking

Error codeWhen it fires
BANK_INSTITUTION_REQUIREDPOST /v0/accounts/link was called on the Meld path without institution_id.
BANK_LINK_TOKEN_FAILEDPOST /v0/accounts/link could not obtain a link token from Meld.
BANK_PROVIDER_ERRORThe upstream provider returned an error during token exchange or sync.
BANK_ACCOUNT_NOT_FOUNDThe referenced account does not exist.
BANK_ACCOUNT_UNAUTHORIZEDThe account exists but does not belong to the authenticated user.
GATE-403-001The user does not have the Meld bank-linking entitlement.

​
Webhooks

Meld webhooks terminate on Sumvin. You do not subscribe to them or post to them — their effects land on the partner-facing endpoints:
  • Completed bank link → account appears on GET /v0/accounts.
  • Connection status change → account status updates (active, refresh_required, disconnected, error).
  • Account disconnect → account soft-deleted from /v0/accounts.
  • Transaction aggregation → transactions appear on /v0/transactions for the affected accounts.
  • Ramp settlement → transaction on /v0/ramp/transactions moves to completed or failed.
Poll the relevant resource for the terminal state. Partner-facing webhooks are on the roadmap.