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 Delegation

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

Webhook Message Types

There are four message types: auth-request, auth-confirm, payment-advice, and auth-cancel. Messages are generated from Payment Lifecycle events. Messages relating to a payment are guaranteed to be delivered in the same sequence as the lifecycle events. The semantics and integrator obligations are described below for each of these message types.

There are two delivery modes: "transactional" and "notification". Transactional delivery means the message is delivered in real-time while the payment network waits for the transaction result. Notification delivery means the message is sent asynchronously and will be retried until a successfull response has been observed. The auth-request message type uses the transactional delivery mode and all other message types use the notification delivery mode. The two delivery modes correspond to the two webhook endpoint paths: /authorize and /notify.

Handling the different custodial payment message types will generally follow the same sequence:

1. Find the payment resource based on the paymentId field.
2. If the payment exists and the messageId has already been handled (due to duplicate message delivery) then do nothing and return the same response as the first time the message was handled.
3. Create or update the payment resource. Set the status based on the paymentFinalized field. Set the amount based on the paymentAmount field. Record the messageId field. In the same database transaction, apply an atomic balance adjustment if needed.

Auth Request Message

Auth Confirm Message

Payment Advice Message

Cancellation Message

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 Funding Source 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.

Webhook Specs

Authentication

Webhooks are authenticated by an RSA signature. The signature is made against the concatenation of the request headers and body like {deliveryId}:{keyId}:{body}. The signature is provided in the X-Signature header. The public key for validating the signature can be obtained from the JWKS endpoint at https://api.immersve.com/.well-known/jwks.json.

Headers

Idempotency

Notification messages are guaranteed to be delivered. When message delivery fails, delivery will be retried at an exponentially increasing interval. When the same message has been delivered twice then the handler must ignore it and return a successful response. The messageId field can be used to detect duplicate messages. 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 1000 milliseconds. Unresponsive authorization requests will be canceled.

Response Format

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

Merchants rely on the result value to determine the next steps in the payment process. A value of authorized indicates payment success. All other values will result in the decline of the payment. Use declined when a more specific value does not apply.

Payment Notification 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.

Immersve will send a cancel payment instruction in case an error has occurred while handling an authorization request.

Request Body Format

All custodial webhook endpoints share the same message body format. The request content type is application/json. Client consumers of the message format must tolerate the addition of unknown message attributes.