Skip to main content
Live 04/27/2026
Settlement request correlation: external_id and metadata are now first-class on the create payload, the list filter, and every read / webhook echo. Existing transaction_id clients keep working unchanged.

​
Added

  • external_id — string identifier you supply on POST /v0/settlement-requests. Echoed on every read and webhook; filterable via GET /v0/settlement-requests?external_id=.... Recommended pattern: don’t persist Superbank’s id, look up by your external_id whenever you need the settlement.
  • metadata — free-form key/value object (up to 50 string keys, 40-char keys, 500-char values). Echoed on every read and webhook; not filterable. Useful for carrying correlation (user_id, card_charge_id, etc.) without needing an extra lookup on your side when handling webhooks.
  • destination.is_third_party is now included in every settlement response (previously accepted on create but not echoed back).

​
Changed

  • amount formatting is now consistent across POST, GET, and PUT responses. All three return the canonical 8-decimal form (e.g. "1.00000000"). Previously the POST response echoed the raw input ("1") while reads returned the padded form.

​
Fixed

  • settlement_request.updated webhooks triggered by upstream payment status changes (e.g. SETTLEMENT_COMPLETED, payout failures) now carry external_id and metadata, matching the settlement_request.created payload. Previously these two fields were stripped from the production webhook path even though the API documentation stated they were echoed on every webhook. No action needed if you already handle missing fields gracefully; if you wired logic around their presence, they will now be present consistently.

​
Deprecated

  • transaction_id — superseded by external_id. Both are accepted on POST / PUT and both are echoed in responses today; they map to the same underlying value. New integrations should use external_id. Removal: 2026-05-25 (4 weeks from this release). After that date, requests sending transaction_id will be rejected and responses will no longer echo it. Migrate by replacing every occurrence of transaction_id with external_id — the values are interchangeable today.

​
Notes

  • external_id is not enforced as unique on Superbank’s side. If you send the same value twice, the list endpoint returns every match. Use metadata (e.g. metadata.card_charge_id) for client-side disambiguation if needed.