Go SDK

Use the github.com/raimshq/raims-go module in your integration backend. The SDK provides resource services, typed parameters and responses, cursor pagination, and webhook authentication.

Install the package

The SDK requires Go 1.26.5 or later. From the project containing go.mod:

go get github.com/raimshq/raims-go@latest

Go resolves the latest stable module version and records the dependency in your application. Keep go.mod and go.sum with the project.

Configure the client

Get a key from API keys and store it in a vault or protected application environment variable. Keep the credential in the backend, out of browsers, applications distributed to customers, and logs.

The validated API key determines company, environment, and permissions. Sandbox and Production use https://api.raims.com.

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    raims "github.com/raimshq/raims-go"
)

func main() {
    client, err := raims.NewClient(os.Getenv("RAIMS_API_KEY"),
        raims.WithMaxNetworkRetries(0),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer client.CloseIdleConnections()

    page, err := client.Customers.List(context.Background(), &raims.ListCustomersParams{
        PageSize: raims.Set[int64](20),
    })
    if err != nil {
        log.Fatal(err)
    }
    for _, customer := range page.List {
        fmt.Println(customer.ID)
    }
}

Reuse the client across requests and goroutines. context.Context lets you cancel calls and limit their duration. Close idle connections when finished. The following snippets assume a configured client and an application context named ctx.

Create a customer and a charge

customerTaxID is the valid CPF or CNPJ of the authorized customer. customerIdempotencyKey and chargeIdempotencyKey are separate keys created and persisted before the requests. chargeDueDate is an int64 containing the chosen, persisted due date in UTC Unix seconds. This snippet belongs in a function that returns error.

customer, err := client.Customers.Create(ctx, &raims.CreateCustomerParams{
    TaxID: raims.Set(customerTaxID),
}, raims.WithIdempotencyKey(customerIdempotencyKey))
if err != nil {
    return err
}

charge, err := client.Charges.Create(ctx, &raims.CreateChargeParams{
    CustomerID:  raims.Set(customer.ID),
    AmountCents: raims.Set[int64](15000),
    DueDate:     raims.Set(chargeDueDate),
    Title:       raims.Set("Order 1234"),
}, raims.WithIdempotencyKey(chargeIdempotencyKey))
if err != nil {
    return err
}
fmt.Println(charge.LastResponse.StatusCode, charge.LastResponse.RequestID)

If the CPF or CNPJ already exists in the same company and environment, the customer is updated and keeps its identifier. 15000 represents BRL 150.00. Keep the key and every parameter, including the due date, when recovering the same intent after losing a response. See Create a charge.

Optional[T] preserves the difference between omitting a field, sending a value with Set, and sending null with Null[T](). Check the field contract before clearing a value.

Pagination and pending results

List fetches one page, available in page.List. NextPage(ctx) and PreviousPage(ctx) preserve filters and return nil when there is no continuation. ListAll advances as you consume it; leaving the loop stops further fetches. processCustomer represents your application logic.

for customer, err := range client.Customers.ListAll(ctx, nil).All() {
    if err != nil {
        return err
    }
    processCustomer(customer.ID)
}

Copy the received cursors and keep the filters; do not send after and before together. See Listing and pagination.

An HTTP 202 response indicates a pending result. It does not confirm payment or financial completion and does not start automatic polling. Retrieve the resource or follow the appropriate event before confirming the effect in your application.

Idempotency and errors

Use errors.As to identify *raims.APIError and make decisions using StatusCode and Code. Response.RequestID identifies the attempt when a response exists. ConnectionError indicates a transport failure and can leave a write inconclusive. WithMaxNetworkRetries configures retries for GET only; the default is zero.

The SDK sends an idempotency key only when your application supplies it to an endpoint that accepts Idempotency-Key. It does not generate keys or retry writes automatically. A timeout does not prove that a write was rejected.

Make decisions using the HTTP status and structured code; error.message is a human diagnostic that can change. Do not log complete responses, credentials, personal documents, or temporary URLs. See Idempotency and the SDK error guide.

Use Sandbox

Use a Sandbox key for simulations in client.Simulations.Charges and client.Simulations.Refunds. A Production key does not become a Sandbox key when these services are used. Check the conditions in the Simulations reference.

Requests that ask for email or webhook deliveries can reach external destinations even in Sandbox. Use only destinations authorized for the integration.

Receive webhooks

rawBody contains the received bytes and headers contains the original HTTP headers. The helper returns the authenticated event or an error; do not process the body when authentication fails.

import (
    "encoding/json"
    "net/http"
    "time"

    raims "github.com/raimshq/raims-go"
)

func authenticateDelivery(rawBody []byte, headers http.Header, webhookSecret string) (map[string]json.RawMessage, error) {
    return raims.ConstructWebhookEvent(rawBody, headers, webhookSecret,
        raims.DefaultWebhookTolerance, time.Now())
}

Use the secret_key returned when creating or rotating the webhook, which differs from the API Bearer key. Read the body before the JSON parser and preserve its bytes: do not reserialize the content before authentication.

After authentication, check the type and environment, deduplicate by the event id, and store the work durably before responding with success. The webhook-id header identifies the delivery, not the event. See Receive events.

Update the SDK

Run go get github.com/raimshq/raims-go@latest again in the project. Review the releases and changes to go.mod and go.sum, and test your application flows before deploying the update.

The SDK version is independent of the API HTTP version /v1. Full guides and the method reference are in the SDK repository.