Stripe Adapter
Stripe-compatible webhook payloads for Yolfi events
Overview
The Stripe adapter sends Stripe-style event envelopes with object: "event" and the provider object under data.object.
Yolfi webhooks are still authenticated with X-Yolfi-Signature. The adapter does not send or emulate Stripe-Signature.
Use this adapter as a compatibility bridge into existing Stripe-style handlers. Keep your business logic unchanged and only add Yolfi signature routing.
If a Stripe branch calls the Stripe API with object IDs from the webhook, keep that branch unchanged. Adapter IDs are compatibility IDs, so use a separate Yolfi endpoint or an existing body-driven handler instead of refactoring the Stripe branch.
Event Mapping
| Yolfi event | Stripe-compatible events |
|---|---|
invoice.created | checkout.session.created |
payment.confirmed one-time | payment_intent.succeeded, charge.succeeded, checkout.session.completed |
payment.confirmed recurring | payment_intent.succeeded, charge.succeeded, invoice.paid, invoice.payment_succeeded |
invoice.overdue | checkout.session.expired |
subscription.overdue | invoice.payment_failed, customer.subscription.updated |
subscription.cancelled | customer.subscription.deleted |
For recurring success, Stripe can surface both invoice.paid and invoice.payment_succeeded. If your business logic listens to both, deduplicate by invoice/event key to avoid double provisioning.
Field Mapping
| Yolfi field | Stripe field |
|---|---|
amountUsd | primary source for amount, amount_received, amount_total, amount_paid in cents |
amount | fallback source when amountUsd is missing |
symbol | currency; stablecoins map to usd |
customer.email | customer_email, receipt_email, billing_details.email |
customer.name | customer_details.name, billing_details.name |
customer.clientReferenceId | primary source for client_reference_id |
customerId | fallback source for client_reference_id and customer |
paylinkId | payment_link and metadata.yolfi_paylink_id |
invoiceId | generated Stripe-style object IDs and metadata.yolfi_invoice_id |
subscriptionId | generated subscription ID and metadata.yolfi_subscription_id |
metadata | Stripe metadata for primitive values |
Yolfi-specific blockchain fields are stored in Stripe metadata: chain_id, network, token, and symbol. Adapter metadata also includes Yolfi lifecycle IDs such as yolfi_event_id, yolfi_invoice_id, yolfi_paylink_id, and yolfi_org_id.
Stripe-style IDs in adapter payloads are generated compatibility IDs and may not be resolvable via Stripe API lookups.
Example: payment_intent.succeeded
{
"id": "evt_evt_yolfi_001_payment_intent_succeeded",
"object": "event",
"api_version": "2025-04-30.basil",
"created": 1710000000,
"livemode": false,
"pending_webhooks": 1,
"request": {
"id": null,
"idempotency_key": null
},
"type": "payment_intent.succeeded",
"data": {
"object": {
"id": "pi_yolfi_invoice_001",
"object": "payment_intent",
"amount": 1234,
"amount_received": 1234,
"currency": "usd",
"customer": "cus_yolfi_customer_001",
"latest_charge": "ch_yolfi_invoice_001",
"receipt_email": "customer@example.com",
"status": "succeeded",
"metadata": {
"yolfi_invoice_id": "invoice-001",
"yolfi_paylink_id": "paylink-001",
"yolfi_org_id": "org-001",
"chain_id": "42161",
"network": "ARB",
"token": "0xaf88",
"symbol": "USDC"
}
}
}
}Example: checkout.session.completed
{
"id": "evt_evt_yolfi_001_checkout_session_completed",
"object": "event",
"api_version": "2025-04-30.basil",
"created": 1710000000,
"livemode": false,
"pending_webhooks": 1,
"request": {
"id": null,
"idempotency_key": null
},
"type": "checkout.session.completed",
"data": {
"object": {
"id": "cs_yolfi_invoice_001",
"object": "checkout.session",
"amount_subtotal": 1234,
"amount_total": 1234,
"currency": "usd",
"customer": "cus_yolfi_customer_001",
"customer_email": "customer@example.com",
"client_reference_id": "merchant-customer-001",
"created": 1710000000,
"expires_at": 1710028800,
"livemode": false,
"metadata": {
"yolfi_event_id": "evt_yolfi_001",
"yolfi_invoice_id": "invoice-001",
"yolfi_paylink_id": "paylink-001",
"yolfi_org_id": "org-001",
"chain_id": "42161",
"network": "ARB",
"token": "0xaf88",
"symbol": "USDC"
},
"mode": "payment",
"payment_link": "paylink-001",
"payment_intent": "pi_yolfi_invoice_001",
"payment_status": "paid",
"status": "complete",
"subscription": null,
"url": null,
"customer_details": {
"email": "customer@example.com",
"name": "Customer One",
"phone": null
}
}
}
}