absolutepay

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 4, 2026 License: MIT Imports: 16 Imported by: 0

README

absolutepay-go

Official AbsolutePay API client for Go. Server-side only — your API key and signing secret must never reach a browser.

Every request from an app key is HMAC-signed automatically. Inbound webhooks are verified with one call. Zero third-party dependencies — standard library only.

Install

go get github.com/AbsolutePay/absolutepay-go@latest

Requires Go 1.18+.

import absolutepay "github.com/AbsolutePay/absolutepay-go"

Environments

Option Base URL
default https://api.absolutepay.io (production)
WithSandbox(true) https://sandbox-api.absolutepay.io
WithBaseURL("https://…") your override (wins over sandbox)

Quickstart

package main

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

	absolutepay "github.com/AbsolutePay/absolutepay-go"
)

func main() {
	ap, err := absolutepay.New(
		os.Getenv("ABSOLUTEPAY_API_KEY"), // ap_live_… / ap_test_…
		absolutepay.WithSigningSecret(os.Getenv("ABSOLUTEPAY_SIGNING_SECRET")), // apisign_…
		// absolutepay.WithSandbox(true),
	)
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()
	balances, err := ap.Balances.List(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(balances)

	inv, err := ap.Invoices.Create(ctx, absolutepay.InvoiceParams{
		Reference:   "order-123",
		Amount:      absolutepay.Money{Amount: "25.00", Currency: "USDT"},
		Chain:       "MATIC", // mint the deposit address up front; omit to let the payer pick
		RedirectURL: "https://shop.example.com/thanks", // payer returns here after checkout (?token=…&status=…)
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(inv["token"])
}

For a hosted page where the payer picks the asset and network at pay time, create a checkout link and redirect the customer to its checkoutUrl. Confirm payment via the payment.succeeded webhook or by polling ap.Invoices.Public.Status(ctx, token).

link, err := ap.Invoices.CreateCheckout(ctx, absolutepay.InvoiceParams{
	Reference: "order-123",
	Amount:    absolutepay.Money{Amount: "25.00", Currency: "USDT"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(link["checkoutUrl"]) // send the payer here; they choose how to pay

Errors

Non-2xx responses return an *absolutepay.Error:

_, err := ap.Payouts.Create(ctx, items)
var apErr *absolutepay.Error
if errors.As(err, &apErr) {
	fmt.Println(apErr.Status, apErr.Code, apErr.Detail, apErr.RequestID)
	if apErr.IsRateLimited() { /* 429 — back off and retry */ }
	if apErr.IsAuth()        { /* 401/403 — check key, scope, or signature */ }
}

Pagination

Live lists use keyset pagination. Pass a prior page's NextCursor as PageQuery.Before; it's nil on the last page.

var before string
for {
	page, err := ap.Invoices.List(ctx, absolutepay.PageQuery{Limit: 50, Before: before})
	if err != nil {
		log.Fatal(err)
	}
	for _, raw := range page.Items {
		// json.Unmarshal(raw, &yourType)
	}
	if page.NextCursor == nil {
		break
	}
	before = *page.NextCursor
}

Webhooks

Verify the signature and parse the event in one call. Pass the raw request body:

func handler(w http.ResponseWriter, r *http.Request) {
	raw, _ := io.ReadAll(r.Body) // RAW bytes — do not re-serialize
	event, err := absolutepay.ConstructEvent(raw, r.Header, os.Getenv("ABSOLUTEPAY_WEBHOOK_SECRET"))
	if err != nil {
		http.Error(w, "bad signature", http.StatusBadRequest)
		return
	}
	if event.Type == "payment.succeeded" {
		// json.Unmarshal(event.Data, &yourType)
	}
	w.WriteHeader(http.StatusOK)
}

The freshness (replay) window defaults to 5 minutes; pass absolutepay.WithTolerance(0) to disable it.

Security

  • Server-side only. The API key + signing secret authenticate as your workspace.
  • Requests go over HTTPS only (except localhost for local development).
  • The Idempotency-Key header (on payouts) is intentionally not part of the signed canonical string.

License

MIT

Documentation

Overview

Package absolutepay is the official Go client for the AbsolutePay API.

It signs every request from an app key automatically (HMAC-SHA512) and verifies inbound webhooks. Server-side only — your API key and signing secret must never reach a browser. Zero third-party dependencies (standard library only).

Typical use: 

ap, err := absolutepay.New("ap_live_...", absolutepay.WithSigningSecret("apisign_..."))
if err != nil {
	log.Fatal(err)
}
balances, err := ap.Balances.List(ctx)

Every list of scopes required by a call is documented on the service type that exposes it (for example BalancesService needs balances:read).

Index

Constants

View Source 
const (
	// ProductionBaseURL is the live API origin (real funds).
	ProductionBaseURL = "https://api.absolutepay.io"
	// SandboxBaseURL is the public sandbox API origin (mock funds); select it with WithSandbox.
	SandboxBaseURL = "https://sandbox-api.absolutepay.io"
)

Base URLs for the public API. Pass any other origin through WithBaseURL.

View Source 
const DefaultWebhookTolerance = 5 * time.Minute

DefaultWebhookTolerance is the default freshness window enforced on webhook timestamps (replay defense): a callback older than this is rejected.

Variables

View Source 
var ErrInvalidSignature = errors.New("absolutepay: invalid webhook signature")

ErrInvalidSignature is returned by ConstructEvent (and reported by VerifySignature) when a webhook fails signature or freshness verification.

Functions

func VerifySignature 

func VerifySignature(secret string, rawBody []byte, timestamp, signature string) bool

VerifySignature reports whether the HMAC-SHA512 of "{timestamp}.{rawBody}" keyed by secret equals signature, compared in constant time. secret is your app's callback secret (whsec_...); rawBody is the exact request body bytes; timestamp and signature come from the X-AbsolutePay-Timestamp and X-AbsolutePay-Signature headers. It returns false if any input is empty or the signatures differ. This is the low-level check; most callers use ConstructEvent, which also enforces freshness.

Types

type Balance 

type Balance struct {
	// Currency is the asset code, e.g. "USDT".
	Currency string `json:"currency"`
	// Available is the spendable amount as a decimal string.
	Available string `json:"available"`
	// Locked is the amount reserved/held (unavailable) as a decimal string.
	Locked string `json:"locked"`
}

Balance is a single asset balance for the workspace.

type BalancesService 

type BalancesService struct {
	// contains filtered or unexported fields
}

BalancesService reads workspace asset balances. Requires the balances:read scope.

func (*BalancesService) List 

func (s *BalancesService) List(ctx context.Context) ([]Balance, error)

List returns every asset balance for the workspace. ctx controls cancellation/deadline. It returns one Balance per asset, or an error.

func (*BalancesService) Summary 

func (s *BalancesService) Summary(ctx context.Context, quote string) (JSON, error)

Summary values the whole balance in a single quote currency. quote is the currency code to value in (e.g. "USDT"); pass "" to use the server default (USDT). It returns a loosely-typed JSON summary, or an error.

type BankMaterialsParams added in v0.2.0 

type BankMaterialsParams struct {
	// Certificate holds proof-of-account / certificate documents.
	Certificate []DocFile `json:"certificate"`
	// Passport holds identity (passport) documents.
	Passport []DocFile `json:"passport"`
}

BankMaterialsParams submits additional compliance documents for a registered bank account (e.g. when off-ramp review requests more materials).

type BankParams added in v0.2.0 

type BankParams struct {
	// BankAccountName is the account holder's name as it appears at the bank.
	BankAccountName string `json:"bankAccountName"`
	// BankName is the destination bank's name.
	BankName string `json:"bankName"`
	// CountryID is the numeric id of the bank's country (from OffRampService.Countries).
	CountryID int `json:"countryId"`
	// IBAN is the destination account's IBAN.
	IBAN string `json:"iban"`
	// Swift is the bank's SWIFT/BIC code. Optional.
	Swift string `json:"swift,omitempty"`
	// Address is the account holder's address. Optional.
	Address string `json:"address,omitempty"`
	// RemittanceLineNumber is an optional remittance reference line required by some corridors.
	RemittanceLineNumber string `json:"remittanceLineNumber,omitempty"`
	// File is the proof-of-account document uploaded inline (see DocFile).
	File DocFile `json:"file"`
}

BankParams registers a fiat destination bank account for off-ramp withdrawals.

type Client 

type Client struct {

	// Balances exposes workspace asset balances (scope: balances:read).
	Balances *BalancesService
	// Fees exposes fee previews (scope: balances:read).
	Fees *FeesService
	// Payouts exposes batch on-chain payouts (scopes: payouts:write / payouts:read).
	Payouts *PayoutsService
	// Refunds exposes refunds against checkout orders (scope: payments:write).
	Refunds *RefundsService
	// Conversions exposes currency conversions (scope: convert:write).
	Conversions *ConversionsService
	// Invoices exposes invoices and hosted payment links (scopes: invoices:write / invoices:read).
	Invoices *InvoicesService
	// Subscriptions exposes recurring plans and subscriptions (scopes: subscriptions:write / subscriptions:read).
	Subscriptions *SubscriptionsService
	// GiftCards exposes gift-card issuance and lookup (scopes: balances:read / payments:write).
	GiftCards *GiftCardsService
	// OffRamp exposes crypto-to-fiat off-ramp (scopes: payouts:write / payouts:read).
	OffRamp *OffRampService
	// Transactions exposes the unified ledger (scope: ledger:read).
	Transactions *TransactionsService
	// Reconciliation exposes settled payment/withdrawal reconciliation reports (scope: ledger:read).
	Reconciliation *ReconciliationService
	// Deposits exposes on-chain deposit chains and address minting (scope: balances:read).
	Deposits *DepositsService
	// contains filtered or unexported fields
}

Client is the AbsolutePay API client. Construct it once with New and reuse it across goroutines; each resource service hangs off it as a field.

func New 

func New(apiKey string, opts ...Option) (*Client, error)

New builds a Client. apiKey is required and identifies your workspace (ap_live_... for production, ap_test_... for sandbox/test). Pass Options to set the signing secret, choose sandbox/base URL, or supply a custom HTTP client. It returns an error if apiKey is empty or the resolved base URL is invalid or a non-https, non-localhost origin. Example: 

ap, err := absolutepay.New(
	"ap_live_...",
	absolutepay.WithSigningSecret("apisign_..."),
)
if err != nil {
	return err
}
balances, err := ap.Balances.List(ctx)

type ConversionsService 

type ConversionsService struct {
	// contains filtered or unexported fields
}

ConversionsService quotes and executes currency conversions. Requires the convert:write scope.

func (*ConversionsService) Convert 

func (s *ConversionsService) Convert(ctx context.Context, p QuoteParams) (JSON, error)

Convert quotes then immediately executes a conversion in one call — a convenience wrapper over Quote + Execute. p describes the legs (see QuoteParams). It returns the executed conversion as JSON, or an error from either step. Example: 

res, err := ap.Conversions.Convert(ctx, absolutepay.QuoteParams{
	SellCurrency: "USDT",
	BuyCurrency:  "BTC",
	SellAmount:   "100.00",
})

func (*ConversionsService) Execute 

func (s *ConversionsService) Execute(ctx context.Context, p ConvertExecuteParams) (JSON, error)

Execute runs a previously quoted conversion (this moves funds) and returns the result as JSON, or an error.

func (*ConversionsService) Quote 

func (s *ConversionsService) Quote(ctx context.Context, p QuoteParams) (*ConvertQuote, error)

Quote previews a conversion without moving any funds and returns a *ConvertQuote (rate and both legs), or an error. Follow with Execute to commit it.

type ConvertExecuteParams 

type ConvertExecuteParams struct {
	// QuoteID is the id from the ConvertQuote returned by Quote.
	QuoteID string `json:"quoteId"`
	// Sell is the amount and currency to sell (must match the quote).
	Sell Money `json:"sell"`
	// Buy is the amount and currency to buy (must match the quote).
	Buy Money `json:"buy"`
}

ConvertExecuteParams executes a previously obtained conversion quote.

type ConvertQuote 

type ConvertQuote struct {
	// QuoteID identifies this quote; pass it to Execute.
	QuoteID string `json:"quoteId"`
	// Rate is the quoted exchange rate as a decimal string.
	Rate string `json:"rate"`
	// SellCurrency is the currency being sold.
	SellCurrency string `json:"sellCurrency"`
	// SellAmount is the amount to be sold, as a decimal string.
	SellAmount string `json:"sellAmount"`
	// BuyCurrency is the currency being bought.
	BuyCurrency string `json:"buyCurrency"`
	// BuyAmount is the amount to be bought, as a decimal string.
	BuyAmount string `json:"buyAmount"`
}

ConvertQuote is a conversion quote returned by Quote. It is short-lived; pass its QuoteID to Execute to lock in the trade.

type DepositParams 

type DepositParams struct {
	// Currency is the asset code the payer chose, e.g. "USDT".
	Currency string `json:"currency"`
	// Chain is the blockchain network for the deposit, e.g. "TRX".
	Chain string `json:"chain"`
	// FullCurrType is the provider's fully-qualified currency/network identifier
	// (as returned by Assets).
	FullCurrType string `json:"fullCurrType"`
}

DepositParams selects the asset for a hosted-invoice deposit.

type DepositsService added in v0.2.0 

type DepositsService struct {
	// contains filtered or unexported fields
}

DepositsService mints on-chain deposit addresses that credit the workspace balance. Requires the balances:read scope.

func (*DepositsService) Chains added in v0.2.0 

func (s *DepositsService) Chains(ctx context.Context) (JSON, error)

Chains returns the blockchain networks available for deposits as JSON, or an error. Use a returned chain code with CreateAddress.

func (*DepositsService) CreateAddress added in v0.2.0 

func (s *DepositsService) CreateAddress(ctx context.Context, chain string) (JSON, error)

CreateAddress mints a deposit address on chain (e.g. "TRX", "ETH") that credits the workspace balance. It returns the address details as JSON, or an error.

type DocFile added in v0.2.0 

type DocFile struct {
	// Filename is the original file name, e.g. "passport.pdf".
	Filename string `json:"filename"`
	// ContentType is the file's MIME type, e.g. "application/pdf" or "image/png".
	ContentType string `json:"contentType"`
	// DataBase64 is the file's bytes, base64-encoded (standard encoding, no data: URI prefix).
	DataBase64 string `json:"dataBase64"`
}

DocFile is a base64-encoded document uploaded inline with an off-ramp bank registration or compliance submission (e.g. a proof-of-address certificate or a passport scan).

type Error 

type Error struct {
	// Status is the HTTP status code, or 0 for a transport/network failure.
	Status int
	// Code is the stable, machine-readable error code; branch on this in your code.
	Code string
	// Title is a short human-readable summary of the problem.
	Title string
	// Detail is optional extra context about the specific failure (may be empty).
	Detail string
	// RequestID is the server's x-request-id; include it when reporting a problem.
	RequestID string
}

Error is returned when the API responds with a non-2xx status (or a transport failure occurs). It carries the platform's problem+json fields. Every resource method returns this concrete type via the error interface; type-assert to *Error to inspect the fields or call IsAuth / IsRateLimited.

func (*Error) Error 

func (e *Error) Error() string

Error implements the error interface, formatting the status, title, and code.

func (*Error) IsAuth 

func (e *Error) IsAuth() bool

IsAuth reports whether the error is a 401 or 403 — bad or insufficient credentials, a missing scope, or an invalid request signature.

func (*Error) IsRateLimited 

func (e *Error) IsRateLimited() bool

IsRateLimited reports whether the error is a 429 — you are being throttled; back off and retry after a moment.

type Event 

type Event struct {
	// ID is the unique event identifier (use it to de-duplicate deliveries).
	ID string `json:"id"`
	// Type is the event name, e.g. "payment.succeeded".
	Type string `json:"type"`
	// Data is the event-specific payload as raw JSON; unmarshal it into your target type.
	Data json.RawMessage `json:"data"`
}

Event is a delivered webhook callback: the JSON the platform POSTs to your configured callback URL. Type identifies the event; Data is the event-specific payload as raw JSON that you unmarshal into the shape you expect.

Known Type values include: "payment.succeeded", "charge.refunded", "payout.settled", "payout.partial", and "payout.failed".

func ConstructEvent 

func ConstructEvent(rawBody []byte, headers http.Header, secret string, opts ...EventOption) (*Event, error)

ConstructEvent verifies a webhook callback's signature and freshness, then parses and returns the Event. Pass the RAW request body bytes (not a re-encoded copy), the request headers, and your app's callback secret (whsec_...). By default it rejects callbacks whose timestamp is more than DefaultWebhookTolerance old; tune or disable that with WithTolerance. It returns ErrInvalidSignature if the signature or freshness check fails, or a JSON error if the body cannot be parsed. Example (net/http handler): 

body, _ := io.ReadAll(r.Body)
evt, err := absolutepay.ConstructEvent(body, r.Header, "whsec_...")
if err != nil {
	http.Error(w, "bad signature", http.StatusBadRequest)
	return
}
switch evt.Type {
case "payment.succeeded":
	// json.Unmarshal(evt.Data, &payload)
}

type EventOption 

type EventOption func(*eventOptions)

EventOption customizes ConstructEvent (currently the freshness tolerance).

func WithTolerance 

func WithTolerance(d time.Duration) EventOption

WithTolerance sets the freshness window used for replay defense. d is the maximum allowed age of a webhook timestamp; pass WithTolerance(0) to disable the freshness check entirely (signature is still verified). Defaults to DefaultWebhookTolerance.

type FeePreview 

type FeePreview struct {
	// Amount is the input amount the fee was computed on, as a decimal string.
	Amount string `json:"amount"`
	// Currency is the currency code of Amount.
	Currency string `json:"currency"`
	// PaymentType is the operation kind the fee applies to (see the Payment* constants).
	PaymentType PaymentType `json:"paymentType"`
	// Fee is the total fee charged, as a decimal string (NetworkFee + Markup).
	Fee string `json:"fee"`
	// Net is the amount remaining after the fee, as a decimal string.
	Net string `json:"net"`
	// Markup is the account-tier margin portion of the fee, as a decimal string.
	Markup string `json:"markup"`
	// NetworkFee is the underlying network base fee, as a decimal string.
	NetworkFee string `json:"networkFee"`
}

FeePreview is the fee breakdown for a given amount: the platform fee is the network base fee plus the account-tier markup.

type FeesService 

type FeesService struct {
	// contains filtered or unexported fields
}

FeesService previews fees before you commit to an operation. Requires the balances:read scope.

func (*FeesService) Preview 

func (s *FeesService) Preview(ctx context.Context, amount, currency string, paymentType PaymentType) (*FeePreview, error)

Preview returns the fee breakdown for an amount and payment type. amount is the decimal-string value; currency is its code (e.g. "USDT"); paymentType is one of the Payment* constants (pass "" for the default CHECKOUT). It returns a *FeePreview, or an error.

type GiftCardParams 

type GiftCardParams struct {
	// Title is the gift card's display title.
	Title string `json:"title"`
	// TemplateID is the design template id (from Templates) to render the card with.
	TemplateID string `json:"templateId"`
	// Amount is the face value and currency loaded onto the card.
	Amount Money `json:"amount"`
}

GiftCardParams issues a gift card.

type GiftCardsService 

type GiftCardsService struct {
	// contains filtered or unexported fields
}

GiftCardsService issues and looks up gift cards. Reads require balances:read; issuing a card requires payments:write.

func (*GiftCardsService) Create 

func (s *GiftCardsService) Create(ctx context.Context, p GiftCardParams) (JSON, error)

Create issues a gift card from p and returns it as JSON (including its card number), or an error.

func (*GiftCardsService) Get 

func (s *GiftCardsService) Get(ctx context.Context, cardNum string) (JSON, error)

Get looks up an issued gift card by its card number (cardNum) and returns it as JSON, or an error.

func (*GiftCardsService) List 

func (s *GiftCardsService) List(ctx context.Context, q PageQuery) (*Page, error)

List returns a keyset-paginated page of issued gift cards. q sets page size, cursor, and optional status filter; pass a prior Page.NextCursor as q.Before for the next page (nil NextCursor means last page). See PageQuery and Page.

func (*GiftCardsService) Templates 

func (s *GiftCardsService) Templates(ctx context.Context) (JSON, error)

Templates returns the available gift-card design templates as JSON, or an error. Use a returned template's id as GiftCardParams.TemplateID.

type InvoiceParams 

type InvoiceParams struct {
	// Reference is your unique invoice reference.
	Reference string `json:"reference"`
	// Amount is the amount and currency to bill.
	Amount Money `json:"amount"`
	// Description is an optional human-readable line item / memo.
	Description string `json:"description,omitempty"`
	// CustomerEmail is the payer's email, used for receipts/notifications. Optional.
	CustomerEmail string `json:"customerEmail,omitempty"`
	// RedirectURL is an http(s) URL the payer's browser is sent to once the hosted
	// checkout reaches a terminal state. AbsolutePay appends
	// ?token=<invoiceToken>&status=<SUCCESS|EXPIRED|CANCELED> (preserving any existing
	// query). Echoed back on the invoice when set. Optional.
	RedirectURL string `json:"redirectUrl,omitempty"`
	// ExpiresAt is the expiry time in epoch milliseconds. Optional (0 = no explicit expiry).
	ExpiresAt int64 `json:"expiresAt,omitempty"`
	// Chain is the blockchain network. On Create it mints the deposit address up
	// front; ignored by CreateCheckout. Optional.
	Chain string `json:"chain,omitempty"`
}

InvoiceParams is the request body for Create and CreateCheckout. On Create, set Chain to mint the deposit address up front; CreateCheckout ignores Chain and lets the payer choose the network.

type InvoicesService 

type InvoicesService struct {

	// Public holds the unauthenticated, payer-facing invoice endpoints.
	Public *PublicInvoicesService
	// contains filtered or unexported fields
}

InvoicesService creates and manages invoices and hosted payment links. Writes require invoices:write; reads require invoices:read. Payer-facing endpoints that need no API key live under Public.

func (*InvoicesService) Create 

func (s *InvoicesService) Create(ctx context.Context, p InvoiceParams) (JSON, error)

Create creates a fixed-asset invoice and returns it as JSON (including its token and, if Chain was set, a deposit address), or an error.

func (*InvoicesService) CreateCheckout 

func (s *InvoicesService) CreateCheckout(ctx context.Context, p InvoiceParams) (JSON, error)

CreateCheckout creates a hosted checkout link where the payer picks the asset and network at pay time. Any Chain in p is cleared. It returns the link as JSON (including its token/URL), or an error.

func (*InvoicesService) List 

func (s *InvoicesService) List(ctx context.Context, q PageQuery) (*Page, error)

List returns a keyset-paginated page of invoices. q sets the page size, cursor, and optional status filter (see PageQuery). Pass a prior page's Page.NextCursor as q.Before for the next page; NextCursor is nil on the last page. Example: 

q := absolutepay.PageQuery{Limit: 50}
for {
	page, err := ap.Invoices.List(ctx, q)
	if err != nil {
		return err
	}
	// ... process page.Items ...
	if page.NextCursor == nil {
		break
	}
	q.Before = *page.NextCursor
}

func (*InvoicesService) Pause 

func (s *InvoicesService) Pause(ctx context.Context, token string, paused bool) (JSON, error)

Pause pauses or unpauses an open invoice or payment link. token identifies the invoice; paused=true pauses it and paused=false resumes it. It returns the updated state as JSON, or an error.

func (*InvoicesService) Stats 

func (s *InvoicesService) Stats(ctx context.Context) (JSON, error)

Stats returns aggregate invoice statistics for the workspace as JSON, or an error.

func (*InvoicesService) Void 

func (s *InvoicesService) Void(ctx context.Context, token string) (JSON, error)

Void makes an invoice or payment link permanently unpayable. token identifies the invoice. It returns the updated state as JSON, or an error.

type JSON 

type JSON = map[string]any

JSON is a loosely-typed object returned by endpoints that have no dedicated response struct. It is an alias for map[string]any; read fields by key, e.g. resp["orderId"]. Values follow encoding/json defaults (numbers decode to float64).

type Money 

type Money struct {
	// Amount is the decimal value as a string, e.g. "10.00". Never a float.
	Amount string `json:"amount"`
	// Currency is the asset/currency code, e.g. "USDT", "BTC", "USD".
	Currency string `json:"currency"`
}

Money is a monetary value: a decimal-string amount together with its currency code, e.g. Money{Amount: "10.00", Currency: "USDT"}. Amounts are ALWAYS strings (never floats) so no precision is lost on the money path.

type OffRampQuoteParams 

type OffRampQuoteParams struct {
	// CryptoCurrency is the asset code being sold, e.g. "USDT".
	CryptoCurrency string `json:"cryptoCurrency"`
	// FiatCurrency is the target fiat currency code, e.g. "USD", "EUR".
	FiatCurrency string `json:"fiatCurrency"`
	// CryptoAmount is the amount of crypto to sell, as a decimal string.
	CryptoAmount string `json:"cryptoAmount"`
}

OffRampQuoteParams requests a crypto-to-fiat quote.

type OffRampService 

type OffRampService struct {
	// contains filtered or unexported fields
}

OffRampService converts crypto to fiat and pays out to a registered bank account. Reads require payouts:read; quoting/withdrawing require payouts:write.

func (*OffRampService) Banks 

func (s *OffRampService) Banks(ctx context.Context) (JSON, error)

Banks returns the workspace's registered destination bank accounts as JSON, or an error. Use a returned account's id as OffRampWithdrawParams.BankAccountID.

func (*OffRampService) Countries 

func (s *OffRampService) Countries(ctx context.Context) (JSON, error)

Countries returns the fiat destination countries supported for off-ramp as JSON, or an error.

func (*OffRampService) DeleteBank added in v0.2.0 

func (s *OffRampService) DeleteBank(ctx context.Context, bankAccountID string) error

DeleteBank removes a registered destination bank account. bankAccountID is the account's id (from RegisterBank or Banks). It returns an error if the request is rejected.

func (*OffRampService) Orders 

func (s *OffRampService) Orders(ctx context.Context, q PageQuery) (*Page, error)

Orders returns a keyset-paginated page of off-ramp orders. q sets page size, cursor, and optional status filter; pass a prior Page.NextCursor as q.Before for the next page (nil NextCursor means last page). See PageQuery and Page.

func (*OffRampService) Quote 

func (s *OffRampService) Quote(ctx context.Context, p OffRampQuoteParams) (JSON, error)

Quote returns a crypto-to-fiat quote (including a quote token and fiat amount) for p as JSON, or an error. Follow with Withdraw to execute it.

func (*OffRampService) RegisterBank added in v0.2.0 

func (s *OffRampService) RegisterBank(ctx context.Context, p BankParams) (JSON, error)

RegisterBank registers a fiat destination bank account (see BankParams, including the inline proof document) and returns the created account as JSON (with its id, usable as OffRampWithdrawParams.BankAccountID), or an error.

func (*OffRampService) SubmitBankMaterials added in v0.2.0 

func (s *OffRampService) SubmitBankMaterials(ctx context.Context, bankAccountID string, p BankMaterialsParams) (JSON, error)

SubmitBankMaterials uploads additional compliance documents for a registered bank account. bankAccountID identifies the account; p carries the certificate/passport documents (see BankMaterialsParams). It returns the updated review state as JSON, or an error.

func (*OffRampService) Withdraw 

func (s *OffRampService) Withdraw(ctx context.Context, p OffRampWithdrawParams) (JSON, error)

Withdraw executes an off-ramp against a quote and registered bank account (see OffRampWithdrawParams) and returns the order as JSON, or an error.

type OffRampWithdrawParams 

type OffRampWithdrawParams struct {
	// QuoteToken is the token from the OffRampService.Quote response.
	QuoteToken string `json:"quoteToken"`
	// BankAccountID identifies the registered destination bank account.
	BankAccountID string `json:"bankAccountId"`
	// CryptoCurrency is the asset code being sold (must match the quote).
	CryptoCurrency string `json:"cryptoCurrency"`
	// FiatCurrency is the target fiat currency code (must match the quote).
	FiatCurrency string `json:"fiatCurrency"`
	// CryptoAmount is the crypto amount to sell, as a decimal string (must match the quote).
	CryptoAmount string `json:"cryptoAmount"`
	// FiatAmount is the fiat amount to receive, as a decimal string (from the quote).
	FiatAmount string `json:"fiatAmount"`
}

OffRampWithdrawParams executes an off-ramp against a prior quote and a registered bank account.

type Option 

type Option func(*Client)

Option customizes a Client during New. Options are applied in order.

func WithBaseURL 

func WithBaseURL(baseURL string) Option

WithBaseURL overrides the API origin entirely, e.g. a local dev server. It takes precedence over WithSandbox. baseURL must use https unless the host is localhost or 127.0.0.1; a non-https, non-local URL makes New return an error.

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient sets a custom *http.Client, letting you control timeouts, transport, proxy, and TLS. It replaces the default 30s-timeout client.

func WithSandbox 

func WithSandbox(sandbox bool) Option

WithSandbox targets the public sandbox host instead of production when sandbox is true. It is ignored if WithBaseURL is also set (WithBaseURL wins).

func WithSigningSecret 

func WithSigningSecret(secret string) Option

WithSigningSecret sets the request signing secret (apisign_...). It is required for app keys: when set, the client HMAC-SHA512-signs every request automatically. secret is the raw signing secret string. Keep it server-side only.

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout replaces the HTTP client with a fresh *http.Client whose per-request timeout is d. Use WithHTTPClient instead if you need to configure more than the timeout.

type Page 

type Page struct {
	// Items holds the page's rows as raw JSON; unmarshal each into your target type.
	Items []json.RawMessage `json:"items"`
	// NextCursor is a response-only opaque cursor. Pass it back as PageQuery.Before
	// to fetch the next page. It is nil on the last page (no more results).
	NextCursor *string `json:"nextCursor"`
}

Page is one page of a keyset-paginated list. Items are raw JSON objects that you unmarshal into the concrete type you expect from that endpoint.

type PageQuery 

type PageQuery struct {
	// Limit is the maximum number of items per page. 0 means the server default.
	Limit int
	// Before is the opaque cursor from a previous page's Page.NextCursor. Leave it
	// empty ("") to fetch the first page.
	Before string
	// Status is an optional, endpoint-specific status filter. "" means no filter.
	Status string
}

PageQuery holds keyset (cursor) pagination options for list endpoints such as Invoices.List, Subscriptions.List, GiftCards.List, and OffRamp.Orders.

type PaymentType 

type PaymentType = string

PaymentType enumerates the fee-bearing operation kinds. It is an alias for string; use the Payment* constants for the accepted values. 

const (
	// PaymentCheckout is a pay-in (customer pays the merchant).
	PaymentCheckout PaymentType = "CHECKOUT"
	// PaymentWithdrawal is an on-chain payout/withdrawal.
	PaymentWithdrawal PaymentType = "WITHDRAWAL"
	// PaymentSubscription is a recurring subscription charge.
	PaymentSubscription PaymentType = "SUBSCRIPTION"
	// PaymentConversion is a currency-to-currency conversion.
	PaymentConversion PaymentType = "CONVERSION"
	// PaymentOffRamp is a crypto-to-fiat off-ramp withdrawal.
	PaymentOffRamp PaymentType = "OFFRAMP"
	// PaymentGiftCard is a gift-card issuance.
	PaymentGiftCard PaymentType = "GIFTCARD"
)

The set of PaymentType values accepted by fee/preview and related endpoints.

type PayoutItem 

type PayoutItem struct {
	// RecipientAddress is the destination on-chain wallet address.
	RecipientAddress string `json:"recipientAddress"`
	// Chain is the blockchain network to send over, e.g. "TRX", "ETH".
	Chain string `json:"chain"`
	// Amount is the amount and currency to send to this recipient.
	Amount Money `json:"amount"`
	// Memo is an optional destination memo/tag (required by some chains/exchanges).
	Memo string `json:"memo,omitempty"`
}

PayoutItem is one recipient in a batch payout.

type PayoutsService 

type PayoutsService struct {
	// contains filtered or unexported fields
}

PayoutsService sends batch on-chain payouts and reads their status. Creating a payout requires payouts:write; reads require payouts:read.

func (*PayoutsService) Create 

func (s *PayoutsService) Create(ctx context.Context, items []PayoutItem, opts ...RequestOption) (JSON, error)

Create submits a batch payout of items and returns the batch details as JSON. Pass WithIdempotencyKey to make retries safe: replaying with the same key returns the original batch instead of paying twice. It returns an error if rejected. Example: 

batch, err := ap.Payouts.Create(ctx,
	[]absolutepay.PayoutItem{{
		RecipientAddress: "T...",
		Chain:            "TRX",
		Amount:           absolutepay.Money{Amount: "5.00", Currency: "USDT"},
	}},
	absolutepay.WithIdempotencyKey("payout-2026-06-01-001"),
)

func (*PayoutsService) Get 

func (s *PayoutsService) Get(ctx context.Context, id string) (JSON, error)

Get looks up a payout batch by its id and returns its status as JSON, or an error.

func (*PayoutsService) Options 

func (s *PayoutsService) Options(ctx context.Context, currency string) (JSON, error)

Options lists the supported chains plus the per-chain withdraw fee and limits for a currency. currency is the asset code (e.g. "USDT"). It returns the options as JSON, or an error.

type PlanParams 

type PlanParams struct {
	// MerchantPlanNo is your unique plan reference.
	MerchantPlanNo string `json:"merchantPlanNo"`
	// Name is the human-readable plan name.
	Name string `json:"name"`
	// Amount is the amount and currency charged each cycle.
	Amount Money `json:"amount"`
	// Interval is the billing interval unit, e.g. "DAY", "WEEK", "MONTH", "YEAR".
	Interval string `json:"interval"`
	// IntervalCount is the number of Interval units between charges (e.g. 3 with "MONTH" = quarterly).
	IntervalCount int `json:"intervalCount"`
	// TotalCycles is the number of charges before the subscription ends (0 = unlimited).
	TotalCycles int `json:"totalCycles"`
}

PlanParams defines a recurring billing plan.

type PublicInvoicesService 

type PublicInvoicesService struct {
	// contains filtered or unexported fields
}

PublicInvoicesService holds the unauthenticated, payer-facing invoice endpoints (no API key required). Reach it via InvoicesService.Public. token is the public invoice token shown to the payer.

func (*PublicInvoicesService) Assets 

func (s *PublicInvoicesService) Assets(ctx context.Context, token string) ([]JSON, error)

Assets lists the assets/networks the payer can use to pay the invoice identified by token. It returns one JSON object per payable asset, or an error.

func (*PublicInvoicesService) Deposit 

func (s *PublicInvoicesService) Deposit(ctx context.Context, token string, p DepositParams) (JSON, error)

Deposit selects an asset for the invoice identified by token and returns the deposit instructions (address/amount) as JSON, or an error.

func (*PublicInvoicesService) Get 

func (s *PublicInvoicesService) Get(ctx context.Context, token string) (JSON, error)

Get returns the public view of an invoice by token as JSON, or an error.

func (*PublicInvoicesService) Quote 

func (s *PublicInvoicesService) Quote(ctx context.Context, token, currency string) (JSON, error)

Quote returns the amount of currency required to pay the invoice identified by token. currency is the asset code the payer wants to pay in. It returns the quote as JSON, or an error.

func (*PublicInvoicesService) Status 

func (s *PublicInvoicesService) Status(ctx context.Context, token string) (JSON, error)

Status returns the current payment status of the invoice identified by token as JSON, or an error. Poll this from the payer-facing page.

func (*PublicInvoicesService) TrackOpen added in v0.2.0 

func (s *PublicInvoicesService) TrackOpen(ctx context.Context, token string) error

TrackOpen records that the payer opened the hosted invoice identified by token (an analytics/engagement signal). It sends no body and ignores the response, returning only an error if the request is rejected.

type QuoteParams 

type QuoteParams struct {
	// SellCurrency is the currency code you are converting from.
	SellCurrency string `json:"sellCurrency"`
	// BuyCurrency is the currency code you are converting to.
	BuyCurrency string `json:"buyCurrency"`
	// SellAmount fixes the amount to sell, as a decimal string. Optional (set this OR BuyAmount).
	SellAmount string `json:"sellAmount,omitempty"`
	// BuyAmount fixes the amount to buy, as a decimal string. Optional (set this OR SellAmount).
	BuyAmount string `json:"buyAmount,omitempty"`
}

QuoteParams requests a conversion quote. Set exactly one of SellAmount or BuyAmount to fix that side; the other is computed from the rate.

type ReconciliationQuery added in v0.2.0 

type ReconciliationQuery struct {
	// From is the inclusive start of the time range, in epoch milliseconds (0 = unbounded).
	From int64
	// To is the inclusive end of the time range, in epoch milliseconds (0 = unbounded).
	To int64
	// Limit is the maximum number of rows to return (0 = server default).
	Limit int
	// Offset is the number of rows to skip for offset-based pagination.
	Offset int
}

ReconciliationQuery filters a reconciliation report by time range and page. All fields are optional; zero values are omitted from the request.

type ReconciliationService added in v0.2.0 

type ReconciliationService struct {
	// contains filtered or unexported fields
}

ReconciliationService reads settlement reconciliation reports that pair each settled payment/withdrawal with its network fee and net amount. Requires the ledger:read scope.

func (*ReconciliationService) Payments added in v0.2.0 

func (s *ReconciliationService) Payments(ctx context.Context, q ReconciliationQuery) (JSON, error)

Payments returns the settled pay-in reconciliation report matching q as JSON, or an error. See ReconciliationQuery for the time-range and pagination filters.

func (*ReconciliationService) Withdrawals added in v0.2.0 

func (s *ReconciliationService) Withdrawals(ctx context.Context, q ReconciliationQuery) (JSON, error)

Withdrawals returns the settled withdrawal/payout reconciliation report matching q as JSON, or an error. See ReconciliationQuery for the time-range and pagination filters.

type RefundParams 

type RefundParams struct {
	// MerchantTradeNo is the order reference of the checkout being refunded.
	MerchantTradeNo string `json:"merchantTradeNo"`
	// Amount is the amount and currency to refund (may be a partial amount).
	Amount Money `json:"amount"`
	// Reason is an optional human-readable refund reason.
	Reason string `json:"reason,omitempty"`
}

RefundParams is the request body for Create.

type RefundsService 

type RefundsService struct {
	// contains filtered or unexported fields
}

RefundsService issues and looks up refunds against checkout orders. Requires the payments:write scope.

func (*RefundsService) Create 

func (s *RefundsService) Create(ctx context.Context, p RefundParams) (JSON, error)

Create issues a refund against a settled checkout order and returns the refund details as JSON (including a refundRequestId), or an error. Example: 

refund, err := ap.Refunds.Create(ctx, absolutepay.RefundParams{
	MerchantTradeNo: "order-123",
	Amount:          absolutepay.Money{Amount: "10.00", Currency: "USDT"},
	Reason:          "customer request",
})

func (*RefundsService) Get 

func (s *RefundsService) Get(ctx context.Context, id string) (JSON, error)

Get looks up a refund by its refundRequestId and returns its status as JSON, or an error.

type RequestOption 

type RequestOption func(map[string]string)

RequestOption sets per-request extras such as an idempotency key. The resulting headers are merged AFTER request signing and are therefore NOT part of the signed canonical string.

func WithIdempotencyKey 

func WithIdempotencyKey(key string) RequestOption

WithIdempotencyKey makes a write retry-safe: replaying a request with the same key returns the original result instead of performing the action twice. key is a caller-chosen unique string (e.g. a UUID) that you reuse across retries of the same logical operation.

type SubscribeParams 

type SubscribeParams struct {
	// MerchantSubNo is your unique subscription reference.
	MerchantSubNo string `json:"merchantSubNo"`
	// PlanNo is the plan's reference (MerchantPlanNo) to subscribe to.
	PlanNo string `json:"planNo"`
	// CallbackURL is an optional per-subscription webhook override URL.
	CallbackURL string `json:"callbackUrl,omitempty"`
}

SubscribeParams subscribes a customer to an existing plan.

type SubscriptionsService 

type SubscriptionsService struct {
	// contains filtered or unexported fields
}

SubscriptionsService manages recurring billing plans and subscriptions. Writes require subscriptions:write; reads require subscriptions:read.

func (*SubscriptionsService) Cancel 

func (s *SubscriptionsService) Cancel(ctx context.Context, merchantSubNo string) (JSON, error)

Cancel cancels a subscription identified by merchantSubNo and returns the updated state as JSON, or an error.

func (*SubscriptionsService) Create 

func (s *SubscriptionsService) Create(ctx context.Context, p SubscribeParams) (JSON, error)

Create subscribes a customer to a plan (see SubscribeParams) and returns the new subscription as JSON, or an error.

func (*SubscriptionsService) CreatePlan 

func (s *SubscriptionsService) CreatePlan(ctx context.Context, p PlanParams) (JSON, error)

CreatePlan creates a recurring billing plan from p and returns it as JSON, or an error.

func (*SubscriptionsService) Deductions 

func (s *SubscriptionsService) Deductions(ctx context.Context, merchantSubNo string) (JSON, error)

Deductions returns the per-cycle charge history for a subscription. merchantSubNo is the subscription reference. It returns the history as JSON, or an error.

func (*SubscriptionsService) List 

func (s *SubscriptionsService) List(ctx context.Context, q PageQuery) (*Page, error)

List returns a keyset-paginated page of subscriptions. q sets page size, cursor, and optional status filter; pass a prior Page.NextCursor as q.Before for the next page (nil NextCursor means last page). See PageQuery and Page.

func (*SubscriptionsService) ListPlans 

func (s *SubscriptionsService) ListPlans(ctx context.Context) (JSON, error)

ListPlans returns the workspace's recurring billing plans as JSON, or an error.

type TransactionsQuery 

type TransactionsQuery struct {
	// Currency filters to a single asset code, e.g. "USDT". "" = all currencies.
	Currency string
	// From is the inclusive start of the time range, in epoch milliseconds (0 = unbounded).
	From int64
	// To is the inclusive end of the time range, in epoch milliseconds (0 = unbounded).
	To int64
	// Limit is the maximum number of rows to return (0 = server default).
	Limit int
	// Offset is the number of rows to skip for offset-based pagination.
	Offset int
	// Format selects the response format; "csv" returns an export instead of JSON.
	Format string
}

TransactionsQuery filters the ledger. All fields are optional; zero/empty fields are omitted from the request.

type TransactionsService 

type TransactionsService struct {
	// contains filtered or unexported fields
}

TransactionsService reads the unified ledger across all operation types. Requires the ledger:read scope.

func (*TransactionsService) List 

func (s *TransactionsService) List(ctx context.Context, q TransactionsQuery) (JSON, error)

List returns ledger entries matching q as JSON, or an error. When q.Format is "csv" the response is a CSV export. See TransactionsQuery for the filters.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.