Getting Started with PagarmeApiSDK (Crystal)

Introduction

Pagarme API — a Crystal shard that ports the official pagarme_api_sdk Ruby gem (Pagar.me Core API v5 client, gem version 6.8.17) to idiomatic, high-performance Crystal. Same public surface, same wire behavior: every controller method, model, exception and configuration option of the gem has a Crystal equivalent with the same name, arguments and return type.

Installation

Add the dependency to your shard.yml and run shards install:

dependencies:
  pagarme-crystal-sdk:
    github: MatheusBasso99/pagarme-crystal-sdk

Requires Crystal >= 1.20.2.

Initialize the API Client

require "pagarme-crystal-sdk"

client = PagarmeApiSdk::Client.new(
  basic_auth_credentials: PagarmeApiSdk::BasicAuthCredentials.new(
    "YOUR_SECRET_KEY", "password"
  ),
  service_referer_name: "MyApp",
  timeout: 60
)

The base URI is https://api.pagar.me/core/v5.

Making Calls

The twelve controllers are lazy, memoized accessors on the client — exactly like the Ruby gem:

charge = client.charges.get_charge("ch_ExAmPlE123")
puts charge.status

charges = client.charges.get_charges(page: 1, size: 10, status: "paid")
charges.data.try &.each { |item| puts item.id }

customer = client.customers.create_customer(
  PagarmeApiSdk::CreateCustomerRequest.new(
    name: "Jane Doe",
    email: "jane@example.com"
  ),
  idempotency_key: "my-idempotency-key"
)

subscriptions, orders, plans, invoices, customers, charges, recipients, tokens, transactions, transfers, payables and balance_operations — 130 endpoints in total. See doc/ for every endpoint and model.

Errors

Mapped statuses raise PagarmeApiSdk::ErrorException (400, 401, 404, 412, 422, 500); any other non-2xx raises the base PagarmeApiSdk::APIException:

begin
  client.charges.get_charge("ch_missing")
rescue ex : PagarmeApiSdk::ErrorException
  puts ex.reason        # "An informed resource was not found"
  puts ex.message       # message parsed from the error body
  puts ex.errors        # errors object parsed from the body
  puts ex.response_code # 404
rescue ex : PagarmeApiSdk::APIException
  puts ex.reason # "HTTP response not OK."
end

Notes for users of the Ruby gem

• Model fields are typed: DateTime fields are Time (RFC 3339 on the wire), Integer fields are Int64, hashes are Hash(String, String). Unset optionals are omitted from request bodies; assigning nil through a setter sends an explicit null for nullable fields.
• connection/adapter are accepted for source compatibility but the SDK always uses Crystal's native HTTP::Client (keep-alive, pooled).
• Every request runs with connect/read/write timeouts set; the retry policy honors Retry-After.
• The SDK's own logging (Log.for("pagarme")) never includes credentials, the Authorization header, URLs, or request/response bodies. Anything you do inside an HttpCallBack is your responsibility.

Development

shards install                 # install deps (ameba, webmock)
crystal spec                   # run the test suite
crystal tool format --check    # formatting
bin/ameba                      # lint
crystal build --no-codegen src/pagarme-crystal-sdk.cr   # fast type-check

List of APIs

• Subscriptions
• Orders
• Plans
• Invoices
• Customers
• Charges
• Recipients
• Tokens
• Transactions
• Transfers
• Payables
• Balance Operations

Classes Documentation

• Client
• HttpRequest
• HttpResponse
• ApiHelper
• DateTimeHelper
• Models: doc/models/