Documentation Index Fetch the complete documentation index at: https://docs.trymaven.com/llms.txt
Use this file to discover all available pages before exploring further.
Webhooks Maven sends an HTTP POST to your webhook URL when a payment session completes or fails. This is the recommended way to get payment results back into your system.
Voice and chat widget both use the same webhook. One webhook URL per project, one handler in your code — it processes both channels. Use the caller field to distinguish: it’s the customer’s phone number for voice, and null for chat.
When Webhooks Fire Webhooks are sent when a session reaches a terminal payment status:
Status When payment-successCharge was authorized and captured immediately (default) payment-authorizedAuthorize.net auth-only charge succeeded — funds held but not captured. You settle the auth yourself in your gateway dashboard or via the gateway’s API. payment-failedCharge declined or gateway error
Webhooks are not sent for expired, cancelled, or abandoned sessions — poll the GET session endpoint for those.
Configuring Your Webhook URL Set a webhook URL per app in the Maven Dashboard :
Navigate to your app
Go to the Settings tab
Enter your webhook URL (must be HTTPS in production)
Save
All webhook payloads share the same top-level fields. The processor object varies by gateway and mode — see Processor Fields by Gateway for the full specs.
Voice vs Chat The payload is almost identical for voice and chat — only one field differs:
callernull for chat sessions (no phone involved)
Everything else — status, processor, card_brand, card_last4, error codes — is the same. A single webhook handler works for both.
Full examples by gateway { "session_id" : "a1b2c3d4-..." , "status" : "payment-success" , "project" : "my-store" , "environment" : "live" , "amount" : 49.99 , "currency" : "USD" , "mode" : "charge" , "gateway" : "stripe" , "caller" : "+14155551234" , "card_brand" : "visa" , "card_last4" : "4242" , "processor" : { "payment_intent_id" : "pi_xxx" , "charge_id" : "ch_xxx" , "receipt_url" : "https://pay.stripe.com/receipts/..." , "payment_method_id" : "pm_xxx" , "card_brand" : "visa" , "card_last4" : "4242" } }
{ "session_id" : "a1b2c3d4-..." , "status" : "payment-success" , "project" : "my-store" , "environment" : "live" , "amount" : 49.99 , "currency" : "USD" , "mode" : "tokenize" , "gateway" : "stripe" , "caller" : "+14155551234" , "card_brand" : "visa" , "card_last4" : "4242" , "processor" : { "payment_method_id" : "pm_xxx" , "cloned_payment_method_id" : "pm_yyy" , "cloned_customer_id" : "cus_xxx" , "card_brand" : "visa" , "card_last4" : "4242" } }
{ "session_id" : "a1b2c3d4-..." , "status" : "payment-success" , "project" : "my-store" , "environment" : "live" , "amount" : 49.99 , "currency" : "USD" , "mode" : "charge" , "gateway" : "authorizenet" , "caller" : "+14155551234" , "card_brand" : "visa" , "card_last4" : "4242" , "processor" : { "transaction_id" : "80053776892" , "auth_code" : "D2U7TY" , "response_code" : "1" , "avs_result_code" : "Y" , "cvv_result_code" : "M" , "cavv_result_code" : "2" , "network_trans_id" : "V1NZI0NLBXIKFMK2RAC1YCV" , "auth_only" : false , "card_brand" : "visa" , "card_last4" : "4242" } }
{ "session_id" : "a1b2c3d4-..." , "status" : "payment-authorized" , "project" : "my-store" , "environment" : "live" , "amount" : 49.99 , "currency" : "USD" , "mode" : "charge" , "gateway" : "authorizenet" , "caller" : "+14155551234" , "card_brand" : "visa" , "card_last4" : "4242" , "processor" : { "transaction_id" : "80053776894" , "auth_code" : "P60ZS3" , "response_code" : "1" , "avs_result_code" : "Y" , "cvv_result_code" : "M" , "cavv_result_code" : "2" , "network_trans_id" : "DTUM1U4E6VT99F6A5KZQ0SS" , "auth_only" : true , "card_brand" : "visa" , "card_last4" : "4242" } }
Funds are held but not captured. Use processor.transaction_id to settle the charge later in your Authorize.net dashboard or via your own priorAuthCaptureTransaction API call. See Authorize.net Setup → Capture Mode . { "session_id" : "a1b2c3d4-..." , "status" : "payment-success" , "project" : "my-store" , "environment" : "live" , "amount" : 49.99 , "currency" : "USD" , "mode" : "tokenize" , "gateway" : "authorizenet" , "caller" : "+14155551234" , "card_brand" : "visa" , "card_last4" : "4242" , "processor" : { "customer_profile_id" : "123456789" , "payment_profile_id" : "987654321" , "card_brand" : "visa" , "card_last4" : "4242" } }
{ "session_id" : "a1b2c3d4-..." , "status" : "payment-success" , "project" : "my-store" , "environment" : "live" , "amount" : 49.99 , "currency" : "USD" , "mode" : "charge" , "gateway" : "braintree" , "caller" : "+14155551234" , "card_brand" : "visa" , "card_last4" : "4242" , "processor" : { "transaction_id" : "abc123" , "braintree_status" : "submitted_for_settlement" , "customer_id" : "cust_xxx" , "payment_method_token" : "token_xxx" , "card_brand" : "visa" , "card_last4" : "4242" } }
{ "session_id" : "a1b2c3d4-..." , "status" : "payment-success" , "project" : "my-store" , "environment" : "live" , "amount" : 49.99 , "currency" : "USD" , "mode" : "tokenize" , "gateway" : "braintree" , "caller" : "+14155551234" , "card_brand" : "visa" , "card_last4" : "4242" , "processor" : { "customer_id" : "cust_xxx" , "payment_method_token" : "token_xxx" , "card_brand" : "visa" , "card_last4" : "4242" } }
{ "session_id" : "a1b2c3d4-..." , "status" : "payment-success" , "project" : "my-store" , "environment" : "live" , "amount" : 49.99 , "currency" : "USD" , "mode" : "charge" , "gateway" : "shift4" , "caller" : "+14155551234" , "card_brand" : "visa" , "card_last4" : "4242" , "processor" : { "charge_id" : "char_xxx" , "customer_id" : "cust_xxx" , "card_id" : "card_xxx" , "card_brand" : "visa" , "card_last4" : "4242" } }
{ "session_id" : "a1b2c3d4-..." , "status" : "payment-success" , "project" : "my-store" , "environment" : "live" , "amount" : 49.99 , "currency" : "USD" , "mode" : "tokenize" , "gateway" : "shift4" , "caller" : "+14155551234" , "card_brand" : "visa" , "card_last4" : "4242" , "processor" : { "customer_id" : "cust_xxx" , "card_id" : "card_xxx" , "card_brand" : "visa" , "card_last4" : "4242" } }
{ "session_id" : "a1b2c3d4-..." , "status" : "payment-success" , "project" : "my-store" , "environment" : "live" , "amount" : 49.99 , "currency" : "USD" , "mode" : "charge" , "gateway" : "fiserv" , "caller" : "+14155551234" , "card_brand" : "VISA" , "card_last4" : "4977" , "processor" : { "fiserv_transaction_id" : "84653901038" , "fiserv_order_id" : "R-ddf385f2-..." , "fiserv_payment_token" : "A60759FC-B2E7-40E2-BC78-3C230C5AB7CB" , "fiserv_state" : "CAPTURED" , "fiserv_status" : "APPROVED" , "approval_code" : "279391" , "response_code" : "00" , "response_message" : "Function performed error-free" , "card_brand" : "VISA" , "card_last4" : "4977" } }
{ "session_id" : "a1b2c3d4-..." , "status" : "payment-success" , "project" : "my-store" , "environment" : "live" , "amount" : 49.99 , "currency" : "USD" , "mode" : "tokenize" , "gateway" : "fiserv" , "caller" : "+14155551234" , "card_brand" : "VISA" , "card_last4" : "4977" , "processor" : { "fiserv_payment_token" : "A60759FC-B2E7-40E2-BC78-3C230C5AB7CB" , "ipg_transaction_id" : "84653901037" , "card_brand" : "VISA" , "card_last4" : "4977" } }
Field Reference Field Type Description session_idstring Session UUID statusstring "payment-success", "payment-authorized", or "payment-failed"projectstring App slug environmentstring "test" or "live"amountnumber Amount in dollars (e.g., 49.99) currencystring Currency code (e.g., "USD") modestring "charge" or "tokenize"gatewaystring "stripe", "authorizenet", "braintree", "shift4", or "fiserv"callerstring | null Caller phone number in E.164 format (voice only; null for chat) card_brandstring | null Card brand (visa, mastercard, amex, etc.) card_last4string | null Last 4 digits of the card processorobject | null Gateway-specific response fields (see below) errorobject | null Present only when status is "payment-failed"
Error Object (failures only) { "error" : { "code" : "card_declined" , "message" : "Your card was declined." } }
Processor Fields by Gateway The processor object contains different fields depending on the gateway and mode (charge vs tokenize).
Stripe
Authorize.net
Braintree
Shift4
Fiserv
Charge mode: { "payment_intent_id" : "pi_xxx" , "charge_id" : "ch_xxx" , "receipt_url" : "https://pay.stripe.com/receipts/..." , "payment_method_id" : "pm_xxx" , "card_brand" : "visa" , "card_last4" : "4242" , "postal_code" : "90210" , "exp_month" : 12 , "exp_year" : 2027 }
Field Description payment_intent_idStripe PaymentIntent ID charge_idStripe Charge ID receipt_urlStripe-hosted receipt URL payment_method_idStripe PaymentMethod ID card_brandCard brand (visa, mastercard, etc.) card_last4Last 4 digits of the card postal_codeBilling ZIP/postal code (if collected) exp_monthCard expiration month (if collected) exp_yearCard expiration year (if collected)
Tokenize mode: { "payment_method_id" : "pm_xxx" , "cloned_payment_method_id" : "pm_yyy" , "cloned_customer_id" : "cus_xxx" , "card_brand" : "visa" , "card_last4" : "4242" , "postal_code" : "90210" , "exp_month" : 12 , "exp_year" : 2027 }
Field Description payment_method_idOriginal Stripe PaymentMethod ID (on Maven’s platform account) cloned_payment_method_idPaymentMethod cloned to your Stripe account (absent if same as payment_method_id) cloned_customer_idCustomer created on your Stripe account card_brandCard brand card_last4Last 4 digits postal_codeBilling ZIP/postal code (if collected) exp_monthCard expiration month (if collected) exp_yearCard expiration year (if collected)
Charge mode: { "transaction_id" : "80053776892" , "auth_code" : "D2U7TY" , "response_code" : "1" , "avs_result_code" : "Y" , "cvv_result_code" : "M" , "cavv_result_code" : "2" , "network_trans_id" : "V1NZI0NLBXIKFMK2RAC1YCV" , "auth_only" : false , "card_brand" : "visa" , "card_last4" : "4242" , "postal_code" : "90210" , "exp_month" : 12 , "exp_year" : 2027 }
Field Description transaction_idAuthorize.net transaction ID. In Authorize Only mode, use this as the refTransId for priorAuthCaptureTransaction. auth_codeAuthorization code from the issuing bank response_codeAuthorize.net response code (1=Approved, 2=Declined, 3=Error, 4=Held for review) avs_result_codeAVS (Address Verification System) match result. Y = address+zip match. cvv_result_codeCVV match result. M = match. cavv_result_codeCAVV (3D Secure) result. 2 = passed. network_trans_idCard network transaction ID (Visa/Mastercard) — needed for card-on-file flows and certain refunds auth_onlytrue when the project is set to Authorize Only capture mode (auth without capture). See Capture Mode .card_brandCard brand card_last4Last 4 digits postal_codeBilling ZIP/postal code (if collected) exp_monthCard expiration month (if collected) exp_yearCard expiration year (if collected)
Tokenize mode: { "customer_profile_id" : "123456789" , "payment_profile_id" : "987654321" , "card_brand" : "visa" , "card_last4" : "4242" , "postal_code" : "90210" , "exp_month" : 12 , "exp_year" : 2027 }
Field Description customer_profile_idCIM Customer Profile ID payment_profile_idCIM Payment Profile ID card_brandCard brand card_last4Last 4 digits postal_codeBilling ZIP/postal code (if collected) exp_monthCard expiration month (if collected) exp_yearCard expiration year (if collected)
Charge mode: { "transaction_id" : "abc123" , "braintree_status" : "submitted_for_settlement" , "customer_id" : "cust_xxx" , "payment_method_token" : "token_xxx" , "card_brand" : "visa" , "card_last4" : "4242" , "postal_code" : "90210" , "exp_month" : 12 , "exp_year" : 2027 }
Field Description transaction_idBraintree transaction ID braintree_statusTransaction status (e.g., submitted_for_settlement) customer_idBraintree customer ID payment_method_tokenBraintree payment method token card_brandCard brand card_last4Last 4 digits postal_codeBilling ZIP/postal code (if collected) exp_monthCard expiration month (if collected) exp_yearCard expiration year (if collected)
Tokenize mode: { "customer_id" : "cust_xxx" , "payment_method_token" : "token_xxx" , "card_brand" : "visa" , "card_last4" : "4242" , "postal_code" : "90210" , "exp_month" : 12 , "exp_year" : 2027 }
Field Description customer_idBraintree customer ID payment_method_tokenBraintree payment method token card_brandCard brand card_last4Last 4 digits postal_codeBilling ZIP/postal code (if collected) exp_monthCard expiration month (if collected) exp_yearCard expiration year (if collected)
Charge mode: { "charge_id" : "char_xxx" , "customer_id" : "cust_xxx" , "card_id" : "card_xxx" , "card_brand" : "visa" , "card_last4" : "4242" , "postal_code" : "90210" , "exp_month" : 12 , "exp_year" : 2027 }
Field Description charge_idShift4 charge ID customer_idShift4 customer ID card_idShift4 card ID card_brandCard brand card_last4Last 4 digits postal_codeBilling ZIP/postal code (if collected) exp_monthCard expiration month (if collected) exp_yearCard expiration year (if collected)
Tokenize mode: { "customer_id" : "cust_xxx" , "card_id" : "card_xxx" , "card_brand" : "visa" , "card_last4" : "4242" , "postal_code" : "90210" , "exp_month" : 12 , "exp_year" : 2027 }
Field Description customer_idShift4 customer ID card_idShift4 card ID card_brandCard brand card_last4Last 4 digits postal_codeBilling ZIP/postal code (if collected) exp_monthCard expiration month (if collected) exp_yearCard expiration year (if collected)
Charge mode: { "fiserv_transaction_id" : "84653901038" , "fiserv_order_id" : "R-ddf385f2-..." , "fiserv_payment_token" : "A60759FC-B2E7-40E2-BC78-3C230C5AB7CB" , "fiserv_state" : "CAPTURED" , "fiserv_status" : "APPROVED" , "approval_code" : "279391" , "response_code" : "00" , "response_message" : "Function performed error-free" , "card_brand" : "VISA" , "card_last4" : "4977" , "postal_code" : "90210" }
Field Description fiserv_transaction_idFiserv ipgTransactionId fiserv_order_idFiserv orderId fiserv_payment_tokenReusable Fiserv payment token (also returned on each charge for re-use) fiserv_state"CAPTURED"fiserv_status"APPROVED" on successapproval_codeFiserv authorization code response_codeProcessor response code ("00" = success) response_messageProcessor response message card_brandCard brand (e.g. VISA) card_last4Last 4 digits postal_codeBilling ZIP/postal code (if collected)
Tokenize mode: { "fiserv_payment_token" : "A60759FC-B2E7-40E2-BC78-3C230C5AB7CB" , "ipg_transaction_id" : "84653901037" , "card_brand" : "VISA" , "card_last4" : "4977" , "postal_code" : "90210" }
Field Description fiserv_payment_tokenReusable Fiserv payment token (UUID) ipg_transaction_idFiserv ipgTransactionId from the tokenization request card_brandCard brand card_last4Last 4 digits postal_codeBilling ZIP/postal code (if collected)
Handling Webhooks Your webhook endpoint should:
Return a 200 status code quickly (within 5 seconds)
Process the payload asynchronously if needed
Be idempotent — use session_id to deduplicate
from fastapi import FastAPI, Request app = FastAPI() @app.post ( "/webhooks/maven" ) async def maven_webhook ( request : Request): payload = await request.json() session_id = payload[ "session_id" ] status = payload[ "status" ] if status == "payment-success" : card_last4 = payload.get( "card_last4" ) caller = payload.get( "caller" ) # phone for voice, None for chat processor = payload.get( "processor" , {}) # Update your order, send receipt, etc. await handle_payment_success(session_id, processor) elif status == "payment-failed" : error = payload.get( "error" , {}) await handle_payment_failure(session_id, error) return { "status" : "ok" }
Best Practices
Always return 200 quickly
Return a 200 response immediately and process the webhook asynchronously. If your endpoint times out, the webhook will not be retried.
Use the session_id to deduplicate — check if you’ve already processed this session before acting on it.
Verify that the session_id in the webhook belongs to your organization by checking it against the API: GET /v1/sessions/{session_id}
Handle failures gracefully
Webhook delivery is fire-and-forget. If your endpoint is down, the webhook is lost. For critical flows, also poll the session status as a fallback.
