Replace lab 9's fake payment provider with a real one in a sandbox: Stripe's test mode, where no money moves.
Keep the contract order sees: payment still answers AUTHORIZED or DECLINED, behind a Psp interface with two implementations β the fake (still the default) and Stripe.
Receive Stripe's webhooks, check their signature, process each event once, and let a webhook record the charge whose answer was lost.
Reconcile your payments against the provider, the source of truth.
See how the same design takes Pix with Mercado Pago.
Lab 9 taught payment to survive a provider that is slow or down β against a WireMock that answers whatever we script. A real payment service provider (PSP) adds what a fake cannot: an account and keys, amounts in centavos, declined cards that are answers and not failures, and a second channel β the provider calls you back, later, maybe twice, to say what really happened. This lab plugs BoxOffice into Stripe's sandbox and handles all of it, without spending a cent.
The story so far
Chapter 10 of the story of the course, its second lab, which ties three threads together. Class 3 warned that between machines a message can be lost or duplicated: a retried "buy" can charge twice. Lab 9 answered with one idempotency key per order (order-<orderId>) against a fake provider, and showed the other face of a timeout: when lab 9's client gives up after 1 s and 3 attempts, the charge may still have happened β on a slow provider day the simulator below leaves 133 of 1,000 checkouts UNKNOWN. Class 12 adds that any endpoint the internet can reach must prove who is calling. This lab connects payment to a real provider's sandbox, turns the UNKNOWN into a known answer with signed webhooks and a reconciliation, and measures it: each checkout charged exactly once, and zero mismatches against the provider.
Before you start
Time
3β4 hours
You need
the tools of lab 0; a free Stripe account (an e-mail is enough for the sandbox); jq and openssl (both come with macOS and most Linux distributions)
Directory
every command runs from the root of your boxoffice/ repository
Costs
zero: the sandbox (test mode) moves no money, and the service refuses to start with a live key
dockercomposeversion# v2.xjq--version# jq-1.6+opensslversion# any
Start state β the end of lab 13 (lab 9 is the one this lab builds on: payment, order, Toxiproxy and the fake provider psp):
Skipped or broke a lab? Download boxoffice-after-lab-13.zip, unzip it and cd boxoffice. This lab addsPsp.java, StripePsp.java, StripeSignature.java, StripeWebhookController.java, Reconciliation.java, V2__stripe_events.sql, a unit test and scripts/send-webhook.sh, and replacescompose.yaml and, in services/payment/, pom.xml, application.yaml, ChargeRequest.java, PaymentService.java and PspClient.java. All are in full on this page and in boxoffice-after-lab-14.zip.
Slides
Click the slides and use β β to move through them; F goes full screen and P opens the presenter view, with the notes. Open the slides in a new tab
AUTHORIZED with a pi_β¦ reference; the same key, the same payment; a declined card is DECLINED
4. Webhooks
signature, one event once, stripe-cli
webhook evt_β¦ β AUTHORIZED; a replay is a duplicate; a forged one is 400
5. The lost answer
a charge payment never stored
the webhook stores it; paying again confirms the order with no second charge
6. Reconcile
ours vs Stripe's
{"checked": N, "mismatches": []} β then one mismatch, found
1. A Stripe sandbox
Create an account at dashboard.stripe.com/register. You do not need to activate payments: a sandbox (Stripe's test environment) is available at once.
In the Dashboard, open Developers β API keys of your sandbox and copy the secret key: it starts with sk_test_.
Put it in .env, at the root of the repository β Compose reads it, and lab 0's .gitignore keeps it out of Git:
.env
PSP_PROVIDER=stripe
STRIPE_SECRET_KEY=sk_test_...
gitcheck-ignore.env# prints ".env": it will never be committedcurl-shttps://api.stripe.com/v1/balance-u"$(grep'^STRIPE_SECRET_KEY='.env|cut-d=-f2-):"|jq'{object, livemode}'
You should see {"object": "balance", "livemode": false}. livemode: false is the sandbox: nothing you do here charges a real card.
A secret key is a password to your money
Never paste it in code, a commit, a screenshot or a chat. If it leaks, roll it in the Dashboard (Developers β API keys β Roll key). StripePsp refuses any key that does not start with sk_test_: in this course, a live key is a bug.
2. The adapter: one interface, two providers
order must not know which provider is behind payment β that is the point of the adapter of lab 9. The new Psp interface has two implementations, chosen by boxoffice.psp.provider: lab 9's PspClient (still the default, so the chaos experiments and CI keep working without keys) and StripePsp.
packageboxoffice.payment;importjava.math.BigDecimal;importjava.util.UUID;/** A payment service provider: the fake of lab 9 or the Stripe sandbox. */publicinterfacePsp{/** id: the provider's reference; approved: false when the card was declined. */recordCharge(Stringid,booleanapproved){}/** Charges once per idempotency key, however many times it is called. */Chargecharge(StringidempotencyKey,BigDecimalamount,UUIDorderId,StringpaymentMethod);}
packageboxoffice.payment;importjava.math.BigDecimal;importjava.net.http.HttpClient;importjava.time.Duration;importjava.util.UUID;importorg.springframework.beans.factory.annotation.Value;importorg.springframework.boot.autoconfigure.condition.ConditionalOnProperty;importorg.springframework.http.MediaType;importorg.springframework.http.client.JdkClientHttpRequestFactory;importorg.springframework.stereotype.Component;importorg.springframework.util.LinkedMultiValueMap;importorg.springframework.util.MultiValueMap;importorg.springframework.web.client.RestClient;/** The Stripe sandbox: one PaymentIntent per order, created and confirmed on the server. */@Component@ConditionalOnProperty(name="boxoffice.psp.provider",havingValue="stripe")publicclassStripePspimplementsPsp{/** The fields of a PaymentIntent this service reads. */recordIntent(Stringid,Stringstatus){}/** Stripe's error body: a declined card comes back as HTTP 402 with type card_error. */recordErrorBody(Errorerror){recordError(Stringtype,Stringcode,Stringdecline_code,Stringmessage,Intentpayment_intent){}}privatefinalRestClienthttp;privatefinalStringcurrency;privatefinalStringdefaultMethod;publicStripePsp(RestClient.Builderbuilder,@Value("${boxoffice.stripe.url}")Stringurl,@Value("${boxoffice.stripe.secret-key}")StringsecretKey,@Value("${boxoffice.stripe.currency}")Stringcurrency,@Value("${boxoffice.stripe.payment-method}")StringdefaultMethod,@Value("${boxoffice.psp.connect-timeout}")DurationconnectTimeout,@Value("${boxoffice.psp.read-timeout}")DurationreadTimeout){if(!secretKey.startsWith("sk_test_")){// a live key (sk_live_β¦) moves real money: this lab refuses to start with onethrownewIllegalStateException("STRIPE_SECRET_KEY must be a test key (sk_test_β¦)");}// the JDK HttpClient keeps the body of an error answer (HttpURLConnection may drop it)JdkClientHttpRequestFactoryfactory=newJdkClientHttpRequestFactory(HttpClient.newBuilder().connectTimeout(connectTimeout).build());factory.setReadTimeout(readTimeout);this.http=builder.baseUrl(url).defaultHeader("Authorization","Bearer "+secretKey).requestFactory(factory).build();this.currency=currency;this.defaultMethod=defaultMethod;}@OverridepublicChargecharge(StringidempotencyKey,BigDecimalamount,UUIDorderId,StringpaymentMethod){MultiValueMap<String,String>form=newLinkedMultiValueMap<>();form.add("amount",String.valueOf(amount.movePointRight(2).longValueExact()));// centavosform.add("currency",currency);form.add("payment_method",paymentMethod!=null?paymentMethod:defaultMethod);form.add("confirm","true");// charge now, on the serverform.add("automatic_payment_methods[enabled]","true");form.add("automatic_payment_methods[allow_redirects]","never");// no browser to redirectform.add("metadata[order_id]",orderId.toString());form.add("metadata[idempotency_key]",idempotencyKey);// lets a webhook find the paymentreturnhttp.post().uri("/v1/payment_intents").header("Idempotency-Key",idempotencyKey)// Stripe charges once per key.contentType(MediaType.APPLICATION_FORM_URLENCODED).body(form).exchange((request,response)->{if(response.getStatusCode().is2xxSuccessful()){Intentintent=response.bodyTo(Intent.class);returnnewCharge(intent.id(),"succeeded".equals(intent.status()));}ErrorBodybody=response.bodyTo(ErrorBody.class);if(response.getStatusCode().value()==402&&body!=null&&body.error().payment_intent()!=null){returnnewCharge(body.error().payment_intent().id(),false);// declined: an answer, not a failure}Stringmessage=body!=null?body.error().message():response.getStatusText();thrownewIllegalStateException("Stripe answered "+response.getStatusCode().value()+": "+message);});}/** The provider's view of one PaymentIntent: the source of truth for reconciliation. */publicIntentretrieve(StringintentId){returnhttp.get().uri("/v1/payment_intents/{id}",intentId).retrieve().body(Intent.class);}}
packageboxoffice.payment;importjava.math.BigDecimal;importjava.time.Duration;importjava.util.UUID;importorg.springframework.beans.factory.annotation.Value;importorg.springframework.boot.autoconfigure.condition.ConditionalOnProperty;importorg.springframework.http.client.SimpleClientHttpRequestFactory;importorg.springframework.stereotype.Component;importorg.springframework.web.client.RestClient;/** Lab 9's fake provider (WireMock behind Toxiproxy): still the default, so the chaos experiments keep working. */@Component@ConditionalOnProperty(name="boxoffice.psp.provider",havingValue="fake",matchIfMissing=true)publicclassPspClientimplementsPsp{recordChargeBody(BigDecimalamount,Stringcurrency,Stringreference){}recordChargeOut(Stringid,Stringstatus){}privatefinalRestClienthttp;publicPspClient(RestClient.Builderbuilder,@Value("${boxoffice.psp.url}")Stringurl,@Value("${boxoffice.psp.connect-timeout}")DurationconnectTimeout,@Value("${boxoffice.psp.read-timeout}")DurationreadTimeout){SimpleClientHttpRequestFactoryfactory=newSimpleClientHttpRequestFactory();factory.setConnectTimeout(connectTimeout);// time to open the TCP connectionfactory.setReadTimeout(readTimeout);// max silence while waiting for the responsethis.http=builder.baseUrl(url).requestFactory(factory).build();}/** The provider deduplicates by Idempotency-Key, like real PSPs do. */@OverridepublicChargecharge(StringidempotencyKey,BigDecimalamount,UUIDorderId,StringpaymentMethod){ChargeOutout=http.post().uri("/v1/charges").header("Idempotency-Key",idempotencyKey).body(newChargeBody(amount,"BRL","order-"+orderId)).retrieve().body(ChargeOut.class);returnnewCharge(out.id(),"approved".equals(out.status()));}}
server:port:8085spring:application:name:paymentmvc:problemdetails:enabled:truedatasource:url:jdbc:postgresql://${DB_HOST:db}:${DB_PORT:5432}/${DB_NAME:boxoffice}?currentSchema=paymentusername:${DB_USER:boxoffice}password:${DB_PASSWORD:boxoffice}flyway:schemas:paymentboxoffice:psp:provider:${PSP_PROVIDER:fake}# fake (lab 9's WireMock) | stripe (the sandbox, lab 14)url:${PSP_URL:http://psp:8080}connect-timeout:500msread-timeout:${PSP_READ_TIMEOUT:2s}stripe:url:https://api.stripe.comsecret-key:${STRIPE_SECRET_KEY:}# sk_test_β¦: from the environment, never from Gitwebhook-secret:${STRIPE_WEBHOOK_SECRET:}# whsec_β¦: printed by stripe listencurrency:${STRIPE_CURRENCY:brl}payment-method:${STRIPE_PAYMENT_METHOD:pm_card_visa}# a test card when the request names nonetolerance:300s# max age of a webhook signaturemanagement:endpoints:web:exposure:include:health,info,metricsendpoint:health:probes:enabled:true
One PaymentIntent per order, confirmed on the server.confirm=true charges at once with the test payment method (pm_card_visa by default β in a real checkout, Stripe.js in the browser turns the card into such an id, so card numbers never touch BoxOffice). allow_redirects=never: there is no browser to send to a bank page.
Amounts in centavos. R$ 350.00 is amount=35000; movePointRight(2).longValueExact() fails loudly on a fraction of a centavo instead of rounding money.
The same Idempotency-Key as payment's own table (order-<orderId> from order). Stripe stores the result of the first request with a key and replays it for every retry with the same key, so a retry after a crash between "Stripe charged" and "we saved it" cannot charge twice.
A declined card is an answer. Stripe returns HTTP 402 with type: card_error and the PaymentIntent; payment records DECLINED. Anything else (401, 5xx, a timeout) is an exception: lab 9's retry, breaker and fallback in order handle it.
Metadataorder_id and idempotency_key travel with the PaymentIntent: the webhook of step 4 uses them to find β or create β the payment.
PaymentService now asks the Psp interface instead of PspClient; its full code is in step 4. Rebuild payment and run its tests:
dockercomposebuildpayment# the Dockerfile runs mvn package -DskipTestsdockerrun--rm-v"$PWD/services/payment":/src-w/srcmaven:3.9-eclipse-temurin-21mvn-B-qtest
You should see Tests run: 5, Failures: 0 for StripeSignatureTest (step 4).
3. Charge in the sandbox
compose.yaml passes the new variables to payment (and adds stripe-cli, used in step 4):
name:boxoffice# lab 8: OpenTelemetry settings shared by every Java service (merged into each "environment")x-otel:&otelJAVA_TOOL_OPTIONS:-javaagent:/otel/opentelemetry-javaagent.jarOTEL_JAVAAGENT_ENABLED:${OTEL_ON:-true}# false = same image, agent offOTEL_EXPORTER_OTLP_ENDPOINT:http://otel-lgtm:4318OTEL_METRIC_EXPORT_INTERVAL:"10000"# 10 s instead of 60 sOTEL_RESOURCE_ATTRIBUTES:service.namespace=boxoffice,deployment.environment.name=localOTEL_TRACES_SAMPLER:${OTEL_TRACES_SAMPLER:-parentbased_always_on}OTEL_TRACES_SAMPLER_ARG:${OTEL_TRACES_SAMPLER_ARG:-1.0}LOGGING_PATTERN_CORRELATION:"[%X{trace_id:-},%X{span_id:-}]"# trace id in console logs# settings shared by the three catalog replicas (a YAML anchor)x-catalog:&catalogbuild:./services/catalogimage:boxoffice-catalogvolumes:-./infra/otel:/otel:ro# lab 8: the Java agentenvironment:<<:*otelOTEL_SERVICE_NAME:catalog# three replicas, ONE serviceDB_HOST:dbDB_PORT:5432DB_NAME:${DB_NAME:-boxoffice}DB_USER:${DB_USER:-boxoffice}DB_PASSWORD:${DB_PASSWORD:-boxoffice}DB_POOL_SIZE:${DB_POOL_SIZE:-10}REDIS_HOST:redisREDIS_PORT:6379CACHE_ENABLED:${CACHE_ENABLED:-true}CACHE_TTL_EVENT:${CACHE_TTL_EVENT:-60s}CACHE_TTL_LIST:${CACHE_TTL_LIST:-10s}CACHE_STAMPEDE_PROTECTION:${CACHE_STAMPEDE_PROTECTION:-false}depends_on:db:condition:service_healthyredis:condition:service_healthydeploy:resources:limits:cpus:"1.0"memory:768Mhealthcheck:test:["CMD-SHELL","wget-qO-http://localhost:8082/actuator/health/readiness||exit1"]interval:10stimeout:3sstart_period:120s# lab 8: with the agent, JVMs starting together need up to ~90 sretries:3services:db:image:pgvector/pgvector:0.8.7-pg17-trixie# lab 12: PostgreSQL 17 + the pgvector extensioncommand:["postgres","-c","max_connections=${DB_MAX_CONNECTIONS:-100}"]environment:POSTGRES_DB:${DB_NAME:-boxoffice}POSTGRES_USER:${DB_USER:-boxoffice}POSTGRES_PASSWORD:${DB_PASSWORD:-boxoffice}REPLICATION_PASSWORD:${REPLICATION_PASSWORD:-replicator}ports:-"5432:5432"volumes:-db-data:/var/lib/postgresql/data# runs only when the volume is new: creates the "replicator" user-./infra/postgres/10-replication.sh:/docker-entrypoint-initdb.d/10-replication.sh:rohealthcheck:test:["CMD-SHELL","pg_isready-U$${POSTGRES_USER}-d$${POSTGRES_DB}"]interval:5stimeout:3sretries:10# read-only streaming replica of db (hot standby)db-replica:image:pgvector/pgvector:0.8.7-pg17-trixie# lab 12: PostgreSQL 17 + the pgvector extensionuser:postgresentrypoint:["/usr/local/bin/replica-entrypoint.sh"]environment:PGPASSWORD:${REPLICATION_PASSWORD:-replicator}# used by pg_basebackupREPLICA_DELAY:${REPLICA_DELAY:-0}# e.g. 2s: artificial lagports:-"5433:5432"volumes:-replica-data:/var/lib/postgresql/data-./infra/postgres/replica-entrypoint.sh:/usr/local/bin/replica-entrypoint.sh:rodepends_on:db:condition:service_healthyhealthcheck:test:["CMD-SHELL","pg_isready-Uboxoffice-dboxoffice"]interval:5stimeout:3sretries:20pgbouncer:image:edoburu/pgbouncer:v1.26.0-p0ports:-"6432:6432"volumes:-./infra/pgbouncer/pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini:ro-./infra/pgbouncer/userlist.txt:/etc/pgbouncer/userlist.txt:rodepends_on:db:condition:service_healthyredis:image:redis:8-alpine# a pure cache: bounded memory, evict least-recently-used keys, no persistencecommand:["redis-server","--maxmemory","256mb","--maxmemory-policy","allkeys-lru","--save","","--appendonly","no"]ports:-"6379:6379"healthcheck:test:["CMD","redis-cli","ping"]interval:5stimeout:3sretries:10# three identical replicas; no "ports:" β only the edge is reachable from outsidecatalog-1:<<:*cataloghostname:catalog-1catalog-2:<<:*cataloghostname:catalog-2catalog-3:<<:*cataloghostname:catalog-3inventory:build:./services/inventoryvolumes:-./infra/otel:/otel:roenvironment:<<:*otelOTEL_SERVICE_NAME:inventoryDB_HOST:${INVENTORY_DB_HOST:-pgbouncer}# writes go through PgBouncer...DB_PORT:${INVENTORY_DB_PORT:-6432}DB_MIGRATION_HOST:db# ...migrations straight to the primaryDB_REPLICA_HOST:${DB_REPLICA_HOST:-db-replica}DB_REPLICA_PORT:5432DB_NAME:${DB_NAME:-boxoffice}DB_USER:${DB_USER:-boxoffice}DB_PASSWORD:${DB_PASSWORD:-boxoffice}DB_POOL_SIZE:${INVENTORY_POOL_SIZE:-20}INVENTORY_LOCKING:${INVENTORY_LOCKING:-pessimistic}INVENTORY_HOLD_TTL:${INVENTORY_HOLD_TTL:-PT10M}ports:-"8083:8083"# published for experiments; clients go through the edgedepends_on:db:condition:service_healthydb-replica:condition:service_healthypgbouncer:condition:service_starteddeploy:resources:limits:cpus:"1.0"memory:768Mhealthcheck:test:["CMD-SHELL","wget-qO-http://localhost:8083/actuator/health/readiness||exit1"]interval:10stimeout:3sstart_period:120sretries:3auth:build:./services/authvolumes:-./infra/otel:/otel:roenvironment:<<:*otelOTEL_SERVICE_NAME:authDB_HOST:dbDB_PORT:5432DB_NAME:${DB_NAME:-boxoffice}DB_USER:${DB_USER:-boxoffice}DB_PASSWORD:${DB_PASSWORD:-boxoffice}JWT_ISSUER:${JWT_ISSUER:-boxoffice-auth}JWT_TTL:${JWT_TTL:-PT1H}ADMIN_EMAIL:${ADMIN_EMAIL:-admin@boxoffice.dev}ADMIN_PASSWORD:${ADMIN_PASSWORD:-boxoffice-admin}depends_on:db:condition:service_healthydeploy:resources:limits:cpus:"1.0"memory:768Mhealthcheck:test:["CMD-SHELL","wget-qO-http://localhost:8081/actuator/health/readiness||exit1"]interval:10stimeout:3sstart_period:120sretries:3gateway:build:./services/gatewayvolumes:-./infra/otel:/otel:roenvironment:<<:*otelOTEL_SERVICE_NAME:gatewayAUTH_URL:http://auth:8081INVENTORY_URL:http://inventory:8083AUTH_JWKS_URI:http://auth:8081/auth/.well-known/jwks.jsonJWT_ISSUER:${JWT_ISSUER:-boxoffice-auth}ports:-"8080:8080"# published for experiments; clients use the edge (port 80)depends_on:-auth-inventory-catalog-1-catalog-2-catalog-3deploy:resources:limits:cpus:"1.0"memory:768Mhealthcheck:test:["CMD-SHELL","wget-qO-http://localhost:8080/actuator/health/readiness||exit1"]interval:10stimeout:3sstart_period:120sretries:3edge:image:nginx:1.30-alpineports:-"80:80"volumes:-./infra/nginx/nginx.conf:/etc/nginx/nginx.conf:rodepends_on:-gateway# ---- lab 7: Kafka (KRaft), Kafka UI, Mailpit, order and notification ----kafka:image:apache/kafka:4.3.1hostname:kafkaports:-"9094:9094"environment:KAFKA_NODE_ID:1KAFKA_PROCESS_ROLES:broker,controllerKAFKA_CONTROLLER_QUORUM_VOTERS:1@kafka:9093KAFKA_LISTENERS:PLAINTEXT://:9092,CONTROLLER://:9093,EXTERNAL://:9094KAFKA_ADVERTISED_LISTENERS:PLAINTEXT://kafka:9092,EXTERNAL://localhost:9094KAFKA_LISTENER_SECURITY_PROTOCOL_MAP:PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT,EXTERNAL:PLAINTEXTKAFKA_CONTROLLER_LISTENER_NAMES:CONTROLLERKAFKA_INTER_BROKER_LISTENER_NAME:PLAINTEXTKAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR:1KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR:1KAFKA_TRANSACTION_STATE_LOG_MIN_ISR:1KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS:0KAFKA_AUTO_CREATE_TOPICS_ENABLE:"false"healthcheck:test:["CMD-SHELL","/opt/kafka/bin/kafka-broker-api-versions.sh--bootstrap-serverlocalhost:9092>/dev/null2>&1"]interval:10stimeout:10sstart_period:60s# a busy laptop can take a minute to start the brokerretries:20kafka-init:image:apache/kafka:4.3.1depends_on:kafka:condition:service_healthyentrypoint:["/bin/sh","-c"]command:-|/opt/kafka/bin/kafka-topics.sh --bootstrap-server kafka:9092 --create --if-not-exists \--topic order-events --partitions 6 --replication-factor 1 &&/opt/kafka/bin/kafka-topics.sh --bootstrap-server kafka:9092 --create --if-not-exists \--topic order-events-dlt --partitions 6 --replication-factor 1restart:"no"kafka-ui:image:kafbat/kafka-ui:v1.5.0depends_on:kafka:condition:service_healthyports:-"8089:8080"environment:KAFKA_CLUSTERS_0_NAME:boxofficeKAFKA_CLUSTERS_0_BOOTSTRAPSERVERS:kafka:9092mailpit:image:axllent/mailpit:v1.31ports:-"8025:8025"-"1025:1025"order:build:./services/ordervolumes:-./infra/otel:/otel:roenvironment:<<:*otelOTEL_SERVICE_NAME:orderDB_HOST:dbDB_PORT:5432DB_NAME:${DB_NAME:-boxoffice}DB_USER:${DB_USER:-boxoffice}DB_PASSWORD:${DB_PASSWORD:-boxoffice}REDIS_HOST:redisKAFKA_BOOTSTRAP_SERVERS:kafka:9092NOTIFICATION_URL:http://notification:8086PAYMENT_URL:http://toxiproxy:18085# lab 9: through Toxiproxy, not payment:8085PAYMENT_RESILIENCE:${PAYMENT_RESILIENCE:-true}PAYMENT_READ_TIMEOUT:${PAYMENT_READ_TIMEOUT:-1s}PAYMENT_RETRY_ATTEMPTS:${PAYMENT_RETRY_ATTEMPTS:-3}PAYMENT_BULKHEAD:${PAYMENT_BULKHEAD:-10}NOTIFY_MODE:${NOTIFY_MODE:-outbox}# outbox (after) | sync (before)ADMIT_PER_SECOND:${ADMIT_PER_SECOND:-20}# waiting-room admission rateports:-"8084:8084"depends_on:db:condition:service_healthyredis:condition:service_healthykafka-init:condition:service_completed_successfullydeploy:resources:limits:cpus:"1.0"memory:768Mhealthcheck:test:["CMD-SHELL","wget-qO-http://localhost:8084/actuator/health/readiness||exit1"]interval:10stimeout:3sstart_period:120sretries:3notification:build:./services/notificationvolumes:-./infra/otel:/otel:roenvironment:<<:*otelOTEL_SERVICE_NAME:notificationDB_HOST:dbDB_PORT:5432DB_NAME:${DB_NAME:-boxoffice}DB_USER:${DB_USER:-boxoffice}DB_PASSWORD:${DB_PASSWORD:-boxoffice}KAFKA_BOOTSTRAP_SERVERS:kafka:9092MAIL_HOST:mailpitNOTIFY_CONCURRENCY:${NOTIFY_CONCURRENCY:-3}# consumer threads (max useful: 6 partitions)EMAIL_LATENCY:${EMAIL_LATENCY:-50ms}# simulated e-mail provider latencyNOTIFY_IDEMPOTENT:${NOTIFY_IDEMPOTENT:-true}# false = no dedupe (to see duplicates)ports:-"8086:8086"depends_on:db:condition:service_healthymailpit:condition:service_startedkafka-init:condition:service_completed_successfullydeploy:resources:limits:cpus:"1.0"memory:768Mhealthcheck:test:["CMD-SHELL","wget-qO-http://localhost:8086/actuator/health/readiness||exit1"]interval:10stimeout:3sstart_period:120sretries:3# ---- lab 8: observability backend (Grafana, Prometheus, Tempo, Loki, OTel Collector) ----otel-lgtm:image:grafana/otel-lgtm:0.37.0ports:-"3000:3000"# Grafana (no login)-"4317:4317"# OTLP gRPC-"4318:4318"# OTLP HTTPvolumes:-./infra/grafana/dashboards.yaml:/otel-lgtm/grafana/conf/provisioning/dashboards/boxoffice.yaml:ro-./infra/grafana/dashboards:/otel-lgtm/boxoffice-dashboards:ro-./infra/grafana/alerting:/otel-lgtm/grafana/conf/provisioning/alerting:ro# ---- lab 9: payment adapter, fake provider and fault injection ----psp:image:wiremock/wiremock:3.13.2volumes:-./infra/psp:/home/wiremock:rotoxiproxy:image:ghcr.io/shopify/toxiproxy:2.13.0command:["-host=0.0.0.0","-config=/config/toxiproxy.json"]volumes:-./infra/toxiproxy/toxiproxy.json:/config/toxiproxy.json:roports:-"8474:8474"payment:build:./services/paymentvolumes:-./infra/otel:/otel:roenvironment:<<:*otelOTEL_SERVICE_NAME:paymentDB_HOST:dbDB_PORT:5432DB_NAME:${DB_NAME:-boxoffice}DB_USER:${DB_USER:-boxoffice}DB_PASSWORD:${DB_PASSWORD:-boxoffice}PSP_URL:http://toxiproxy:18095# the provider, through ToxiproxyPSP_PROVIDER:${PSP_PROVIDER:-fake}# lab 14: fake (lab 9) | stripe (the sandbox)STRIPE_SECRET_KEY:${STRIPE_SECRET_KEY:-}# sk_test_β¦: from your shell or .env, never committedSTRIPE_WEBHOOK_SECRET:${STRIPE_WEBHOOK_SECRET:-}STRIPE_CURRENCY:${STRIPE_CURRENCY:-brl}ports:-"8085:8085"depends_on:db:condition:service_healthytoxiproxy:condition:service_startedpsp:condition:service_starteddeploy:resources:limits:cpus:"1.0"memory:768Mhealthcheck:test:["CMD-SHELL","wget-qO-http://localhost:8085/actuator/health/readiness||exit1"]interval:10stimeout:3sstart_period:120sretries:3# ---- lab 12: AI assistant (FastAPI + LiteLLM + pgvector) and a local LLM ----stripe-cli:# lab 14: forwards the sandbox's webhooks to paymentimage:stripe/stripe-cli:v1.55.11profiles:["stripe"]# only with --profile stripeenvironment:STRIPE_API_KEY:${STRIPE_SECRET_KEY:-}# the CLI reads its key from STRIPE_API_KEYcommand:["listen","--events","payment_intent.succeeded,payment_intent.payment_failed","--forward-to","http://payment:8085/webhooks/stripe"]depends_on:payment:condition:service_healthyollama:image:ollama/ollama:0.40.6ports:-"11434:11434"volumes:-ollama-models:/root/.ollama# models survive restarts (about 1.3 GB)healthcheck:# ollama-init must wait for the server, not just the containertest:["CMD","ollama","list"]interval:5stimeout:5sretries:12# one-shot: download the chat model and the embedding model, then exitollama-init:image:ollama/ollama:0.40.6environment:OLLAMA_HOST:ollama:11434entrypoint:["/bin/sh","-c"]command:-|ollama pull ${LOCAL_MODEL_TAG:-qwen2.5:1.5b} && ollama pull nomic-embed-textdepends_on:ollama:condition:service_healthyrestart:"no"assistant:build:./services/assistantenvironment:DB_HOST:dbDB_PORT:5432DB_NAME:${DB_NAME:-boxoffice}DB_USER:${DB_USER:-boxoffice}DB_PASSWORD:${DB_PASSWORD:-boxoffice}OLLAMA_URL:${OLLAMA_URL:-http://ollama:11434}# macOS: http://host.docker.internal:11434 (native Ollama)LOCAL_MODEL:ollama_chat/${LOCAL_MODEL_TAG:-qwen2.5:1.5b}CATALOG_URL:http://gateway:8080# GET /catalog/** is public at the gatewayORDER_URL:http://order:8084ANTHROPIC_API_KEY:${ANTHROPIC_API_KEY:-}# optional: empty = local model onlyOTEL_SERVICE_NAME:assistantOTEL_EXPORTER_OTLP_ENDPOINT:http://otel-lgtm:4318OTEL_METRIC_EXPORT_INTERVAL:"10000"OTEL_RESOURCE_ATTRIBUTES:service.namespace=boxoffice,deployment.environment.name=localports:-"8088:8088"extra_hosts:-"host.docker.internal:host-gateway"# reach a native Ollama on the hostdepends_on:db:condition:service_healthydeploy:resources:limits:cpus:"1.0"memory:1Ghealthcheck:test:["CMD","python","-c","importurllib.request;urllib.request.urlopen('http://localhost:8088/assistant/health')"]interval:10stimeout:5sstart_period:30sretries:3volumes:db-data:replica-data:ollama-models:
Start payment with the Stripe provider (.env sets PSP_PROVIDER=stripe) and charge it directly, as in lab 9:
You should see 201 and "status":"AUTHORIZED","providerRef":"pi_β¦". In the Dashboard (Payments), a R$ 350.00 payment shows the metadata order_id and idempotency_key. Then:
The same request again: 200, the same id and providerRef β and still one payment in the Dashboard.
A declined card, with a new key: add "paymentMethod":"pm_card_visa_chargeDeclined" to the body and use Idempotency-Key: sandbox-2. You should see 201 with "status":"DECLINED"; pm_card_visa_chargeDeclinedInsufficientFunds declines too, for another reason (both are Stripe test payment methods).
End to end, through order and Toxiproxy, as in lab 9:
You should see "status":"CONFIRMED". If the first pay answers 503, Stripe took longer than order's 1 s read timeout: payment still finished and saved the charge, so calling pay again confirms the order with the same PaymentIntent β the lost answer of step 5, by accident.
4. Webhooks: the provider tells you later
A synchronous answer can be lost; Stripe also calls you back with an event for every change of a PaymentIntent. In the sandbox, events are retried three times within a few hours if your endpoint does not answer 2xx; the same event can arrive more than once, and events can arrive out of order. So the endpoint must: prove the call comes from Stripe, process each event once, answer quickly.
packageboxoffice.payment;importjava.time.Clock;importjava.time.Duration;importjava.util.Map;importorg.slf4j.Logger;importorg.slf4j.LoggerFactory;importorg.springframework.beans.factory.annotation.Value;importorg.springframework.boot.autoconfigure.condition.ConditionalOnProperty;importorg.springframework.http.ResponseEntity;importorg.springframework.web.bind.annotation.PostMapping;importorg.springframework.web.bind.annotation.RequestBody;importorg.springframework.web.bind.annotation.RequestHeader;importorg.springframework.web.bind.annotation.RestController;importtools.jackson.databind.ObjectMapper;/** Stripe tells us what happened, later and maybe twice: the webhook is the source of truth. */@RestController@ConditionalOnProperty(name="boxoffice.psp.provider",havingValue="stripe")publicclassStripeWebhookController{privatestaticfinalLoggerlog=LoggerFactory.getLogger(StripeWebhookController.class);recordEvent(Stringid,Stringtype,Datadata){recordData(Intentobject){}recordIntent(Stringid,Stringstatus,longamount,Map<String,String>metadata){}}privatefinalPaymentServicepayments;privatefinalObjectMapperjson;privatefinalStringsecret;privatefinalDurationtolerance;privatefinalClockclock=Clock.systemUTC();publicStripeWebhookController(PaymentServicepayments,ObjectMapperjson,@Value("${boxoffice.stripe.webhook-secret}")Stringsecret,@Value("${boxoffice.stripe.tolerance}")Durationtolerance){this.payments=payments;this.json=json;this.secret=secret;this.tolerance=tolerance;}/** The raw body, as a String: the signature is computed over the exact bytes Stripe sent. */@PostMapping("/webhooks/stripe")publicResponseEntity<String>receive(@RequestBodyStringbody,@RequestHeader(value="Stripe-Signature",required=false)Stringsignature){if(!StripeSignature.valid(body,signature,secret,tolerance,clock)){log.warn("webhook rejected: bad or missing Stripe-Signature");returnResponseEntity.badRequest().body("bad signature");}Eventevent=json.readValue(body,Event.class);Stringstatus=switch(event.type()){case"payment_intent.succeeded"->"AUTHORIZED";case"payment_intent.payment_failed"->"DECLINED";default->null;// other events: acknowledged, ignored};if(status==null){returnResponseEntity.ok("ignored");}Event.Intentintent=event.data().object();booleanapplied=payments.applyWebhook(event.id(),event.type(),intent.id(),status,intent.amount(),intent.metadata());log.info("webhook {} {} {} β {}",event.id(),event.type(),intent.id(),applied?status:"duplicate, skipped");returnResponseEntity.ok(applied?"applied":"duplicate");// 2xx quickly, or Stripe retries}}
packageboxoffice.payment;importjava.nio.charset.StandardCharsets;importjava.security.MessageDigest;importjava.time.Clock;importjava.time.Duration;importjava.util.HexFormat;importjavax.crypto.Mac;importjavax.crypto.spec.SecretKeySpec;/** * Checks the Stripe-Signature header of a webhook: t=<unix time>,v1=<hex HMAC-SHA256 of "t.body">. * Without it, anyone who finds the URL can post "payment succeeded". */publicfinalclassStripeSignature{privateStripeSignature(){}publicstaticbooleanvalid(Stringbody,Stringheader,Stringsecret,Durationtolerance,Clockclock){if(header==null||secret==null||secret.isBlank()){returnfalse;}Stringtimestamp=null;Stringexpected=null;for(Stringpart:header.split(",")){String[]kv=part.split("=",2);if(kv.length==2&&kv[0].equals("t")){timestamp=kv[1];}elseif(kv.length==2&&kv[0].equals("v1")&&expected==null){expected=kv[1];}}if(timestamp==null||expected==null){returnfalse;}longage=clock.instant().getEpochSecond()-Long.parseLong(timestamp);if(Math.abs(age)>tolerance.toSeconds()){returnfalse;// an old, replayed request: even with a correct signature}Stringcomputed=hmacSha256Hex(secret,timestamp+"."+body);// constant-time comparison: do not leak, byte by byte, how much of the signature matchedreturnMessageDigest.isEqual(computed.getBytes(StandardCharsets.UTF_8),expected.getBytes(StandardCharsets.UTF_8));}staticStringhmacSha256Hex(Stringsecret,Stringpayload){try{Macmac=Mac.getInstance("HmacSHA256");mac.init(newSecretKeySpec(secret.getBytes(StandardCharsets.UTF_8),"HmacSHA256"));returnHexFormat.of().formatHex(mac.doFinal(payload.getBytes(StandardCharsets.UTF_8)));}catch(Exceptione){thrownewIllegalStateException(e);}}}
packageboxoffice.payment;importjava.math.BigDecimal;importjava.util.List;importjava.util.Map;importjava.util.Optional;importjava.util.UUID;importorg.springframework.jdbc.core.simple.JdbcClient;importorg.springframework.stereotype.Service;importorg.springframework.transaction.annotation.Transactional;@ServicepublicclassPaymentService{publicrecordResult(PaymentOutpayment,booleancreated){}privatefinalJdbcClientjdbc;privatefinalPsppsp;publicPaymentService(JdbcClientjdbc,Psppsp){this.jdbc=jdbc;this.psp=psp;}publicResultcharge(StringidempotencyKey,ChargeRequestreq){Optional<PaymentOut>done=find(idempotencyKey);if(done.isPresent()){returnnewResult(done.get(),false);// a retry: answer, do not charge again}// remote call OUTSIDE any database transaction: never hold a connection while waitingPsp.Chargecharge=psp.charge(idempotencyKey,req.amount(),req.orderId(),req.paymentMethod());Stringstatus=charge.approved()?"AUTHORIZED":"DECLINED";jdbc.sql(""" INSERT INTO payments (id, idempotency_key, order_id, amount, status, provider_ref) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT DO NOTHING """).params(UUID.randomUUID(),idempotencyKey,req.orderId(),req.amount(),status,charge.id()).update();returnnewResult(find(idempotencyKey).orElseThrow(),true);}/** * Applies a webhook once per event id. Updates the payment of that PaymentIntent, or creates it when * the charge went through but its answer never arrived (the caller timed out): the gap the webhook heals. * Returns false for a duplicate delivery. */@TransactionalpublicbooleanapplyWebhook(StringeventId,Stringtype,StringintentId,Stringstatus,longamountInCents,Map<String,String>metadata){intfresh=jdbc.sql("INSERT INTO stripe_events (id, type) VALUES (?, ?) ON CONFLICT DO NOTHING").params(eventId,type).update();if(fresh==0){returnfalse;// already processed: Stripe delivers at least once}intupdated=jdbc.sql("UPDATE payments SET status = ? WHERE provider_ref = ?").params(status,intentId).update();if(updated==0&&metadata!=null&&metadata.containsKey("idempotency_key")){jdbc.sql(""" INSERT INTO payments (id, idempotency_key, order_id, amount, status, provider_ref) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT DO NOTHING """).params(UUID.randomUUID(),metadata.get("idempotency_key"),UUID.fromString(metadata.get("order_id")),BigDecimal.valueOf(amountInCents).movePointLeft(2),status,intentId).update();}returntrue;}/** The payments of the last hours, with their provider reference: what reconciliation checks. */publicList<PaymentOut>since(java.time.Durationwindow){returnjdbc.sql(""" SELECT id, order_id, amount, status, provider_ref, created_at FROM payments WHERE created_at > now() - make_interval(secs => ?) ORDER BY created_at """).param(window.toSeconds()).query(PaymentOut.class).list();}privateOptional<PaymentOut>find(StringidempotencyKey){returnjdbc.sql(""" SELECT id, order_id, amount, status, provider_ref, created_at FROM payments WHERE idempotency_key = ? """).param(idempotencyKey).query(PaymentOut.class).optional();}}
-- every webhook event processed once: Stripe may deliver the same event more than onceCREATETABLEstripe_events(idVARCHAR(100)PRIMARYKEY,-- evt_β¦typeVARCHAR(100)NOTNULL,received_atTIMESTAMPTZNOTNULLDEFAULTnow());-- the provider's PaymentIntent id is how a webhook finds its paymentCREATEUNIQUEINDEXpayments_provider_refONpayments(provider_ref);
packageboxoffice.payment;import staticorg.junit.jupiter.api.Assertions.assertFalse;import staticorg.junit.jupiter.api.Assertions.assertTrue;importjava.time.Clock;importjava.time.Duration;importjava.time.Instant;importjava.time.ZoneOffset;importorg.junit.jupiter.api.Test;classStripeSignatureTest{staticfinalStringSECRET="whsec_test_secret";staticfinalStringBODY="{\"id\":\"evt_1\",\"type\":\"payment_intent.succeeded\"}";staticfinallongT=1_800_000_000L;staticfinalClockNOW=Clock.fixed(Instant.ofEpochSecond(T+10),ZoneOffset.UTC);staticfinalDurationTOLERANCE=Duration.ofSeconds(300);staticStringheader(longt,Stringbody,Stringsecret){return"t="+t+",v1="+StripeSignature.hmacSha256Hex(secret,t+"."+body);}@TestvoidacceptsTheSignatureStripeComputes(){assertTrue(StripeSignature.valid(BODY,header(T,BODY,SECRET),SECRET,TOLERANCE,NOW));}@TestvoidrejectsAnEditedBody(){assertFalse(StripeSignature.valid(BODY.replace("succeeded","failed"),header(T,BODY,SECRET),SECRET,TOLERANCE,NOW));}@TestvoidrejectsAnotherSecret(){assertFalse(StripeSignature.valid(BODY,header(T,BODY,"whsec_other"),SECRET,TOLERANCE,NOW));}@TestvoidrejectsAnOldSignature(){longold=T-600;// ten minutes before NOW: a replayed requestassertFalse(StripeSignature.valid(BODY,header(old,BODY,SECRET),SECRET,TOLERANCE,NOW));}@TestvoidrejectsAMissingHeader(){assertFalse(StripeSignature.valid(BODY,null,SECRET,TOLERANCE,NOW));}}
The signature.Stripe-Signature: t=<unix time>,v1=<hex> where v1 is the HMAC-SHA256 (a hash-based message authentication code: a SHA-256 hash keyed with the endpoint's secret) of <t>.<raw body>. The controller reads the body as a String β parsing first and serializing again would change the bytes β compares in constant time and rejects a timestamp older than 5 minutes, so a captured request cannot be replayed later.
Once per event.stripe_events has the event id as primary key; INSERT β¦ ON CONFLICT DO NOTHING returns 0 for a repeat, and the repeat is acknowledged and skipped.
The webhook heals. If no payment has that PaymentIntent β the charge went through but its answer never reached the database β the metadata recreates it, with the same idempotency key. The next pay of that order finds it.
Forward the sandbox's events to payment. The Stripe command-line interface (CLI) opens a connection to Stripe and forwards events to a local URL β no public address needed. Get its signing secret (it does not change between runs), put it in .env, restart payment and start the forwarder:
dockercomposerun--rm--no-depsstripe-clilisten--print-secret# prints whsec_β¦echo"STRIPE_WEBHOOK_SECRET=whsec_...">>.env# paste the value it printeddockercomposeup-d--waitpayment
dockercompose--profilestripeup-dstripe-cli
dockercomposelogsstripe-cli|grep-iready
You should see Ready! β¦ Your webhook signing secret is whsec_β¦ (the same value). Pay another order (step 3) and follow the logs:
dockercomposelogs-fpayment|grepwebhook
You should see webhook evt_β¦ payment_intent.succeeded pi_β¦ β AUTHORIZED, a moment after the pay answered: the event confirms what the synchronous answer said.
A replay and a forgery.scripts/send-webhook.sh signs an event the way Stripe does, with the secret from .env:
#!/usr/bin/env bash# Sends a webhook event to payment, signed the way Stripe signs it (lab 14, section 4):# Stripe-Signature: t=<unix time>,v1=<hex HMAC-SHA256 of "<t>.<body>" with the webhook secret>.# scripts/send-webhook.sh event.json # secret: STRIPE_WEBHOOK_SECRET from .env# scripts/send-webhook.sh event.json whsec_x # another secret: payment must answer 400set-euopipefail
body=$(cat"$1")secret=${2:-$(grep'^STRIPE_WEBHOOK_SECRET='.env|cut-d=-f2-)}t=$(date+%s)sig=$(printf'%s.%s'"$t""$body"|openssldgst-sha256-hmac"$secret"-hex|sed's/^.* //')curl-s-w' %{http_code}\n'-XPOSTlocalhost:8085/webhooks/stripe\-H'Content-Type: application/json'-H"Stripe-Signature: t=$t,v1=$sig"--data-binary"$body"
cat>/tmp/evt.json<<EOF{"id":"evt_sandbox_1","type":"payment_intent.succeeded","data":{"object":{"id":"pi_sandbox_1","status":"succeeded","amount":35000,"metadata":{"order_id":"5b0c2f9e-7d0a-4f43-9a55-1c1c2c8f8e11","idempotency_key":"sandbox-replay"}}}}EOFbashscripts/send-webhook.sh/tmp/evt.json# applied 200bashscripts/send-webhook.sh/tmp/evt.json# duplicate 200bashscripts/send-webhook.sh/tmp/evt.jsonwhsec_wrong# bad signature 400
The first call stores a payment that payment never charged β exactly what step 5 needs from a real event. The second is skipped, the third rejected (and logged as webhook rejected).
5. The lost answer: charged, but nobody knows
The worst case of lab 9: Stripe charged, and payment crashed before saving β or order timed out on all its attempts. For the fan, the checkout is UNKNOWN; for the provider, the money moved. Reproduce it: create an order, then send Stripe exactly the request payment sends, by hand, as if payment had died right after:
You should see "status": "succeeded": the fan was charged and BoxOffice has no record. Then:
docker compose logs payment | grep webhook | tail -1 β the event arrived and paymentcreated the payment from its metadata.
curl -s -X POST localhost:8084/orders/$ID/pay | jq '{id, status}' β the fan (or a retry) pays again: CONFIRMED. payment found the payment by the key order-<id> and did not call Stripe; had it called, Stripe would have replayed the same PaymentIntent for that key.
In the Dashboard, search the order id in the metadata: one payment.
The simulator shows the scale of the problem with lab 9's client and a slow provider:
Try it
With lab 9's client (1 s read timeout, 3 attempts) against a slow provider, 40.2% of the calls time out. One key per order (lab 9's order-<orderId>) keeps 1,000 charges for 1,000 fans β 0 duplicates β but 133 checkouts end UNKNOWN, each charged once: those are what this lab's webhook and reconciliation resolve. Switch the key to "none": 392 fans pay twice or more.
6. Reconcile: the provider is the source of truth
Webhooks can be missed (an endpoint down for more than a few hours, a bug that answered 200 and did nothing). A periodic reconciliation compares every recent payment with the provider's PaymentIntent:
packageboxoffice.payment;importjava.time.Duration;importjava.util.ArrayList;importjava.util.List;importorg.springframework.boot.autoconfigure.condition.ConditionalOnProperty;importorg.springframework.web.client.HttpClientErrorException;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestParam;importorg.springframework.web.bind.annotation.RestController;/** Compares our payments with Stripe's PaymentIntents: what the provider says wins. */@RestController@ConditionalOnProperty(name="boxoffice.psp.provider",havingValue="stripe")publicclassReconciliation{recordMismatch(StringproviderRef,Stringours,Stringstripe){}recordReport(intchecked,List<Mismatch>mismatches){}privatefinalPaymentServicepayments;privatefinalStripePspstripe;publicReconciliation(PaymentServicepayments,StripePspstripe){this.payments=payments;this.stripe=stripe;}@GetMapping("/payments/reconcile")publicReportreconcile(@RequestParam(defaultValue="PT1H")Durationwindow){List<PaymentOut>ours=payments.since(window);List<Mismatch>mismatches=newArrayList<>();for(PaymentOutp:ours){if(p.providerRef()==null||!p.providerRef().startsWith("pi_")){continue;// not a Stripe payment (lab 9's fake provider)}Stringtheirs;try{theirs=stripe.retrieve(p.providerRef()).status();}catch(HttpClientErrorException.NotFounde){theirs="missing";// a payment Stripe never made: the worst mismatch}Stringexpected=switch(theirs){case"succeeded"->"AUTHORIZED";case"requires_payment_method","canceled"->"DECLINED";default->null;// processing, requires_action, missingβ¦: always worth a look};if(!p.status().equals(expected)){mismatches.add(newMismatch(p.providerRef(),p.status(),theirs));}}returnnewReport(ours.size(),mismatches);}}
You should see checked counting your Stripe payments of the last two hours (lab 9's fake ch_β¦ references are skipped) and one mismatch: {"providerRef": "pi_sandbox_1", "ours": "AUTHORIZED", "stripe": "missing"} β the event you signed yourself in step 4 recorded a payment Stripe never made. That is the worst kind of mismatch (a ticket sold for nothing), and the reason reconciliation exists. Remove it, then break a real one on purpose and find it:
dockercomposeexecdbpsql-Uboxoffice-dboxoffice-c"DELETE FROM payment.payments WHERE provider_ref = 'pi_sandbox_1'"curl-s'localhost:8085/payments/reconcile?window=PT2H'|jq'.mismatches'# []dockercomposeexecdbpsql-Uboxoffice-dboxoffice-c\"UPDATE payment.payments SET status = 'DECLINED' WHERE id = (SELECT id FROM payment.payments WHERE status = 'AUTHORIZED' AND provider_ref LIKE 'pi_%' LIMIT 1)"curl-s'localhost:8085/payments/reconcile?window=PT2H'|jq'.mismatches'
You should see one mismatch: "ours": "DECLINED", "stripe": "succeeded" β a fan who paid and whose order BoxOffice would have cancelled. In production this report runs on a schedule and every mismatch becomes an alert or an automatic fix (confirm the order, or refund).
Costs and limits of the sandbox
The sandbox has rate limits lower than live mode and keeps test data until you delete it (Developers β β¦ β Delete all test data). GET /payments/reconcile makes one Stripe call per payment: fine for a lab, a job with pagination (GET /v1/payment_intents?created[gte]=β¦) for real volumes.
7. Pix with Mercado Pago
The Psp interface is the seam for any provider. Mercado Pago is the common choice in Brazil for Pix, and Pix changes one thing in the flow: the answer to "charge" is not "paid" β it is a QR code. The fan pays later, in the bank's app, and only the webhook says the money arrived. What is a safety net with Stripe's cards becomes the main path.
Stripe (this lab)
Mercado Pago, Pix
Sandbox
test mode keys sk_test_β¦
test credentials (test access token) from the developer panel
Create
POST /v1/payment_intents, confirm=true
POST /v1/orders (Orders API), the Pix payment method in transactions.payments
Idempotency
Idempotency-Key header
X-Idempotency-Key header (required)
First answer
succeeded, or a 402 decline
pending, with a QR code (qr_code, qr_code_base64) to show the fan
notification with an x-signature header (ts=β¦,v1=β¦), verified with the secret of ConfiguraΓ§Γ£o de Webhooks (the official software development kit, SDK, implements the HMAC check)
Test outcomes
test payment methods (pm_card_visaβ¦)
test cards whose holder name picks the result (APRO approved, OTHE error, CONT pending, FUND insufficient funds), taxpayer number (CPF) 12345678909
A MercadoPagoPsp would return Charge(id, false) with a new state β "pending" β that order must show as "waiting for payment", and the webhook would move the payment to AUTHORIZED. Check the current Mercado Pago developer documentation before writing it: the field names of the Orders API differ from the older Payments API.
Best practices in this lab
Keep the provider behind an interface β Psp with PspClient and StripePsp; order never learns which one charged (Compute β external integrations).
One idempotency key per order, end to end β order-<orderId> from order, the unique column of payments and Stripe's Idempotency-Key are the same value, so no retry anywhere charges twice (Distributed Systems).
Treat a decline as an answer, not a failure β StripePsp maps the 402 to DECLINED; only real failures reach lab 9's retry and breaker (Reliability patterns).
Verify every webhook, process each event once β StripeSignature (HMAC, constant time, 5-minute tolerance) and the stripe_events table (Network & Security).
Reconcile against the source of truth β Reconciliation finds what webhooks missed; money needs a second check, not trust (Observability).
Secrets from the environment, test keys only β .env ignored by Git, sk_test_ enforced at startup.
Troubleshooting
Symptom
Cause
Fix
payment exits: STRIPE_SECRET_KEY must be a test key (sk_test_β¦)
PSP_PROVIDER=stripe with an empty or live key
put the sk_test_β¦ key in .env, or remove PSP_PROVIDER to go back to the fake
500 and Stripe answered 401: Invalid API Key provided in the logs
the key was copied wrong, or rolled
copy it again from Developers β API keys
Stripe answered 400 mentioning the currency
your account's country does not accept BRL charges
add STRIPE_CURRENCY=usd to .env and restart payment
Stripe answered 400 about idempotency
the same Idempotency-Key sent with different parameters (another amount or card)
use a new key for a new request; a key means "this exact request"
webhooks answer 400 bad signature
STRIPE_WEBHOOK_SECRET differs from what listen --print-secret prints, or payment was not restarted after editing .env
fix .env, then docker compose up -d --wait payment
Every checkout is now charged once and every charge is known β but knowing is not fixing. The reconciliation's mismatch is a fan who paid for an order BoxOffice cancelled: that needs a refund (POST /v1/refunds) or a late confirmation, decided by a job, not by hand. Cards that ask for 3-D Secure need the fan's browser (Stripe.js), which means a front end and a requires_action state the server alone cannot finish. Pix makes "pending" the normal case, so order must learn a third state. And real money means live keys, a verified business and the card-data rules of the Payment Card Industry Data Security Standard (PCI DSS) β kept small precisely because card numbers never touch BoxOffice. Whether all of this still holds at 10:00, with 2 million fans, is the question of class 15 β Performance Engineering and of your project.