SDKs

What crosses the wire

• Where it sits

  Between your application and the REST interface. It builds the request, attaches the credential and the API version, applies the retry policy and turns the response into a typed object your compiler can check.

• What you configure

  An environment-scoped secret key, the API version to pin, and a timeout. Everything else has a documented default. The reference for your language lists the constructor options and the exact method names.

• What it hands back

  A typed model of the resource on success, and a typed error carrying the same code the raw API would have returned on failure. Your handling logic is the same either way; the SDK only saves you the parsing.

When to use it

• Server-side integration

  Typed models catch schema mistakes at compile time rather than in production, which matters most on the request bodies you write once and never look at again.

• Mobile acceptance

  Mobile SDKs handle card entry and tokenization without card data touching your app code, which is what keeps a mobile build out of PCI scope.

• Teams without a payments specialist

  The retry helper and the signature helper encode decisions that are easy to get subtly wrong and expensive to get wrong quietly.

How to implement SDKs

What fails, and how you find out

• Floating the SDK version

  An unpinned dependency can move the API version it targets, which changes response shapes without any change on your side. Pin the package and pin the API version separately.

• Wrapping the retry helper in another retry

  An outer retry layer that does not carry the idempotency key turns one safe retry into two independent charges. Pick one layer to own retries, and let the other pass failures through.

• Parsing the body before the signature helper sees it

  The helper needs the raw bytes. A framework that has already deserialized the request will make every verification fail, and the SDK cannot tell you that from inside.

• A typed error caught as a generic exception

  Catching broadly and logging the message discards the code the rest of your handling depends on. Catch the typed error, branch on the code, then log.

Sandbox versus production

• One client, two configurations

  The same SDK talks to both environments; only the credential differs. Building the client from configuration rather than hard-coding it is what makes the cutover a deployment change instead of a code change.

• Retry behaviour is observable

  Provoking a retryable failure in sandbox is the only practical way to see the helper actually retry, and to confirm your logs record one logical operation rather than several.

• Mobile SDKs need the sandbox publishable key

  A mobile build pointed at sandbox tokenizes documented test cards. Shipping a build still configured that way produces tokens production cannot charge, so the key belongs in build configuration.