Custodial Funding Protocol

The Immersve Custodial funding protocol allows client applications to authorize Immersve card payments in real-time using their own ledger.

Protocol Mechanics

On-Chain Pooled Float

The custodian deposits a "float" into an Immersve smart contract in order to cover the anticipated cardholder payments. The available balance of the float is adjusted in real-time according to cardholder payments. When the available balance drops to zero then all cardholder payments will be declined. Settlements are handled automatically by Immersve by drawing on the float.

Webhook Payment Messages

Card payment authorization requests and other payment lifecycle events are actioned by delegating to the custodian's webhook endpoints.

Partner Setup

A Funding Channel must be created using the Create A Funding Channel endpoint. The funding channel should have a funding type of custodial-usdc.

Cardholder Setup

A funding source must be created for each Cardholder using the Create A Funding Source For An Account endpoint. An externalId field must be supplied which can be correlated to a user's custodial ledger account. The externalId field will be supplied with every webhook notification for payments relating to the funding source.

Webhooks

Authentication

Webhooks are authenticated by an RSA signature. The signature is made against the contatenation of the request headers and body like {requestId}:{keyId}:{body}. The signature is provided in the X-Signature header.

Headers

Idempotency

Notification messages are guaranteed to be delivered. When message delivery fails, delivery will be retried at an exponentially increasing interval. Authorization messages are not retried; if an authorization message fails a cancel message will be sent instead.

Authorize Payment Webhook

The authorization webhook is called when a merchant requests payment from the card.

The authorization request is expected to respond within ~1.5 seconds. Unresponsive authoriation requests will be canceled.

Response Format

The authorize response must contain a JSON object with the following fields.

Cancel Payment Webhook

Immersve will send a cancel payment instruction incase an error has occured while handling an authorization request.

Adjust Balance Webhook

A balance adjustment instruction will be sent in several scenarios: when a payment is cleared for an amount greater or less than the authorized amount; when a payment is reversed or expired; or when a refund has been issued.

The integrated client must accept the balance adjustment and increment or decrement the funding source balance accordingly.

Request Body Format

All custodial webhook endpoints share the same message body format. The request content type is application/json.