java 36 lines · 7 steps

Resilient payment calls in Spring

A Spring service wraps an HTTP call to a payment gateway with retries, a circuit breaker, and typed fallbacks.

Explained by highlit

Spring Intermediate circuit breaker retry fault tolerance http client fallback

1@Service
2public class PaymentGatewayClient {
3 
  private static final Logger log = LoggerFactory.getLogger(PaymentGatewayClient.class);
5 
  private final RestClient restClient;
7 
  public PaymentGatewayClient(RestClient.Builder builder,
                              @Value("${payment.gateway.base-url}") String baseUrl) {
      this.restClient = builder.baseUrl(baseUrl).build();
  }
12 
  @CircuitBreaker(name = "paymentGateway", fallbackMethod = "chargeFallback")
  @Retry(name = "paymentGateway")
  public ChargeResult charge(ChargeRequest request) {
      return restClient.post()
              .uri("/v1/charges")
              .contentType(MediaType.APPLICATION_JSON)
              .body(request)
              .retrieve()
              .onStatus(HttpStatusCode::is5xxServerError, (req, res) -> {
                  throw new PaymentGatewayException("Gateway returned " + res.getStatusCode());
              })
              .body(ChargeResult.class);
  }
26 
  private ChargeResult chargeFallback(ChargeRequest request, CallNotPermittedException ex) {
      log.warn("Circuit open for paymentGateway, rejecting charge for order {}", request.orderId());
      return ChargeResult.deferred(request.orderId());
  }
31 
  private ChargeResult chargeFallback(ChargeRequest request, Throwable ex) {
      log.error("Payment charge failed for order {}: {}", request.orderId(), ex.getMessage());
      return ChargeResult.failed(request.orderId(), ex.getMessage());
  }
36}

01 / 01

STEP 01

Walkthrough

Space play ←→ step click any line

Three takeaways

1Resilience4j annotations let you add retries and a circuit breaker declaratively without cluttering the happy-path logic.
2Distinct fallback overloads matched by exception type let you react differently to an open circuit versus a genuine failure.
3Mapping 5xx responses to a custom exception turns transport errors into signals the resilience layer can act on.

Related explainers

java

@Component
@Converter
public class EncryptedStringConverter implements AttributeConverter<String, String> {

Transparent column encryption in Spring & JPA

encryption aes-gcm jpa-converter

Advanced 10 steps

java

package com.acme.billing.config;
 
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.ConfigurationProperties;

Feature-flagged beans with Spring @ConditionalOnProperty

feature-flags conditional-beans strategy-pattern

Intermediate 5 steps

java

public static Map<String, String> parseCookieHeader(String header) {
    Map<String, String> cookies = new LinkedHashMap<>();
    if (header == null || header.isBlank()) {
        return cookies;

Parsing an HTTP Cookie header in Java

string-parsing http url-decoding

Intermediate 6 steps

java

public class TimedSocketReader {
 
    private static final int READ_TIMEOUT_MS = 5_000;
    private static final int CONNECT_TIMEOUT_MS = 3_000;

Reading a socket with connect and read timeouts

sockets timeouts io

Intermediate 8 steps

java

public final class EncodingDetector {
 
    public enum Encoding {
        UTF_8, UTF_16LE, UTF_16BE, UTF_32LE, UTF_32BE, ASCII, UNKNOWN

Detecting text encoding from raw bytes in Java

byte-manipulation encoding-detection bitwise-operations

Intermediate 8 steps

java

public final class ImportOrganizer {
 
    private static final Pattern IMPORT_LINE =
            Pattern.compile("^import\\s+(static\\s+)?([\\w.]+(?:\\.\\*)?)\\s*;\\s*$");