airwallex

package module
v0.2.4 Latest Latest
Warning

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

 Go to latest Published: Jul 2, 2026 License: MIT Imports: 19 Imported by: 0

README

airwallex-go

Unofficial Go SDK for the Airwallex API — payouts, FX, balances, global accounts, beneficiaries, payment acceptance, issuing, and webhooks.

CI Go Reference Go Report Card

[!IMPORTANT] This is an unofficial, community-maintained library. It is not affiliated with, endorsed by, or supported by Airwallex Pty Ltd — "Airwallex" is their trademark, used here only to describe compatibility. The SDK is in beta: the public interface may change before v1.0, so pin your version. For vendor-supported tooling, use the official Node.js SDK.

Airwallex's only official server-side SDK is Node.js. This library brings the same developer experience to Go, mirroring the airwallex-python SDK:

  • One idiomatic client — services as fields, context.Context on every call, zero third-party dependencies (standard library only)
  • Automatic authentication — token fetched on first use and refreshed before expiry; no manual login calls
  • Idempotent by default — request_id is auto-generated for money-moving calls, so retries never double-pay
  • Automatic retries with full-jitter exponential backoff on 408/429/5xx/network failures (honours Retry-After in both seconds and HTTP-date form; 409 business conflicts are never retried)
  • Typed responses that are forward-compatible — every resource keeps the raw response JSON in .Raw, so fields from newer API versions are never lost
  • Auto-pagination — walk every page with one range loop (Go 1.23 iterators)
  • Webhook signature verification with constant-time comparison and replay protection
  • Typed errors — *airwallex.Error carries the HTTP status, Airwallex error code, source, and x-request-id; transport failures are a distinct *airwallex.ConnectionError
  • Response metadata everywhere — every resource and page exposes LastResponse (status, x-request-id, headers), like stripe-go
  • Opt-in structured logging via log/slog (WithLogger) — request outcomes, retries, and token refreshes at debug level, with credentials never logged

Installation

go get github.com/Cyvid7-Darus10/airwallex-go

Requires Go 1.23+. Releases follow semantic versioning; see the changelog.

Quickstart

Create API credentials in the Airwallex web app under Developer → API keys, then:

import "github.com/Cyvid7-Darus10/airwallex-go"

client, err := airwallex.New(
    airwallex.WithClientID("your_client_id"), // or set AIRWALLEX_CLIENT_ID
    airwallex.WithAPIKey("your_api_key"),     // or set AIRWALLEX_API_KEY
    airwallex.WithEnv(airwallex.Demo),        // airwallex.Production is the default
)
if err != nil {
    log.Fatal(err)
}

// Current wallet balances
balances, err := client.Balances.Current(ctx)
for _, balance := range balances {
    fmt.Println(balance.Currency, balance.AvailableAmount)
}
Send a payout

Payouts use /api/v1/transfers, which requires API version 2024-01-31 or later. If your account default is older, pass airwallex.WithAPIVersion("2024-01-31") (or newer).

transfer, err := client.Transfers.Create(ctx, &airwallex.TransferCreateParams{
    BeneficiaryID:    "ben_abc123",
    SourceCurrency:   "USD",
    TransferCurrency: "PHP",
    TransferAmount:   5000,
    TransferMethod:   "LOCAL",
    Reference:        "Invoice 42",
    Reason:           "professional_service_fees",
})
fmt.Println(transfer.ID, transfer.Status)

RequestID is generated for you (set it to control idempotency yourself). Airwallex will never execute the same request_id twice — including across the SDK's automatic retries.

FX: quote and convert
rate, err := client.Rates.Current(ctx, &airwallex.RateCurrentParams{
    BuyCurrency: "USD", SellCurrency: "SGD", BuyAmount: 1000,
})
fmt.Println(rate.Rate)

conversion, err := client.Conversions.Create(ctx, &airwallex.ConversionCreateParams{
    BuyCurrency:   "USD",
    SellCurrency:  "SGD",
    BuyAmount:     1000,
    TermAgreement: true,
    Reason:        "hedging",
})
Accept a payment
intent, err := client.PaymentIntents.Create(ctx, &airwallex.PaymentIntentCreateParams{
    Amount:          25.00,
    Currency:        "USD",
    MerchantOrderID: "order_42",
})
confirmed, err := client.PaymentIntents.Confirm(ctx, intent.ID, &airwallex.PaymentIntentActionParams{
    PaymentMethod: map[string]any{"type": "card", "card": map[string]any{ /* ... */ }},
})
refund, err := client.Refunds.Create(ctx, &airwallex.RefundCreateParams{
    PaymentIntentID: intent.ID, Amount: 5.00,
})
Issue a card
cardholder, err := client.IssuingCardholders.Create(ctx, &airwallex.CardholderCreateParams{
    Email: "employee@example.com",
    Individual: map[string]any{
        "name": map[string]any{"first_name": "Ada", "last_name": "Lovelace"},
    },
    Type: "INDIVIDUAL",
})
card, err := client.IssuingCards.Create(ctx, &airwallex.CardCreateParams{
    CardholderID: cardholder.CardholderID,
    FormFactor:   "VIRTUAL",
    CreatedBy:    "Ada Lovelace",
    Program:      map[string]any{"purpose": "COMMERCIAL"},
})
Test flows in the sandbox
// Demo environment only
client.Simulation.CreateDeposit(ctx, &airwallex.SimulationDepositParams{Amount: 1000, Currency: "USD"})
client.Simulation.TransitionTransfer(ctx, "tra_123", &airwallex.SimulationTransitionParams{NextStatus: "PAID"})
Auto-pagination
// Iterates page by page under the hood (Go 1.23 range-over-func)
for beneficiary, err := range client.Beneficiaries.All(ctx, nil) {
    if err != nil {
        return err
    }
    fmt.Println(beneficiary.EffectiveID(), beneficiary.Nickname)
}

// Or drive pages manually
page, err := client.Beneficiaries.List(ctx, &airwallex.BeneficiaryListParams{
    ListParams: airwallex.ListParams{PageSize: 100},
})
for page != nil {
    for _, b := range page.Items { /* ... */ }
    if !page.HasMore {
        break
    }
    page, err = page.Next(ctx)
}
Webhooks

Verify and parse incoming notifications (get the secret when you create the webhook endpoint):

import "github.com/Cyvid7-Darus10/airwallex-go/webhooks"

func handle(w http.ResponseWriter, r *http.Request) {
    payload, _ := io.ReadAll(r.Body) // raw bytes — do not re-serialise
    event, err := webhooks.ConstructEvent(
        payload,
        r.Header.Get("x-timestamp"),
        r.Header.Get("x-signature"),
        webhookSecret,
    )
    if err != nil {
        w.WriteHeader(http.StatusBadRequest)
        return
    }
    if event.Name == "transfer.settled" { /* ... */ }
}
Error handling
transfer, err := client.Transfers.Retrieve(ctx, "tra_missing")
if err != nil {
    var apiErr *airwallex.Error
    var connErr *airwallex.ConnectionError
    switch {
    case errors.As(err, &apiErr):
        // HTTP status, Airwallex code/source, and x-request-id for support
        fmt.Println(apiErr.StatusCode, apiErr.Code, apiErr.Message, apiErr.RequestID)
    case errors.As(err, &connErr):
        // network failure / timeout — already retried automatically
    }
}

Rate limits (429) and transient 5xx are retried automatically before an error ever reaches you.

Response metadata

Every resource and every page records the HTTP response it came from — quote RequestID when contacting Airwallex support:

transfer, _ := client.Transfers.Retrieve(ctx, "tra_1")
fmt.Println(transfer.LastResponse.StatusCode, transfer.LastResponse.RequestID)
Logging

Pass any *slog.Logger to see request outcomes, retries, and token refreshes at debug level. Only method, path, status, attempt, delay, and request id are logged — never credentials, tokens, headers, or bodies:

client, err := airwallex.New(airwallex.WithLogger(slog.Default()))
Calling endpoints the SDK doesn't wrap yet

Every list-params struct accepts extra query params via ListParams.ExtraQuery, every body-params struct accepts extra fields via Params.ExtraParams, and the client exposes a raw escape hatch with auth, retries, and error mapping intact:

var disputes json.RawMessage
err := client.Request(ctx, "GET", "/api/v1/pa/payment_disputes",
    url.Values{"status": {"OPEN"}}, nil, &disputes)

// Per-call headers (e.g. a one-off x-api-version); Authorization stays SDK-managed
err = client.RequestWithHeaders(ctx, "GET", "/api/v1/pa/payment_disputes",
    nil, http.Header{"x-api-version": {"2020-01-01"}}, nil, &disputes)

Note on zero values: params structs use omitempty, so a 0 amount or false flag is omitted from the request. In the rare case you must send an explicit zero, put it in ExtraParams/ExtraQuery.

Forward-compatible responses

Every response type embeds airwallex.APIResource, whose Raw field holds the exact JSON the API returned — so a field this SDK has no typed accessor for yet is still available:

transfer, _ := client.Transfers.Retrieve(ctx, "tra_1")
var full map[string]any
json.Unmarshal(transfer.Raw, &full) // nothing is ever dropped
Bring your own http.Client
client, err := airwallex.New(
    airwallex.WithHTTPClient(&http.Client{
        Transport: proxyTransport, // proxies, custom TLS, tracing, ...
        Timeout:   30 * time.Second,
    }),
)

The SDK applies the base URL and default headers per request; it never mutates or closes a client you own.

Connected accounts (platforms)
client, err := airwallex.New(airwallex.WithOnBehalfOf("acct_connected_account_id")) // sets x-on-behalf-of
Pinning an API version
client, err := airwallex.New(airwallex.WithAPIVersion("2024-08-07")) // sets x-api-version on every request

Examples

Runnable programs live in examples/ — payouts, FX, and a webhook-verification server:

AIRWALLEX_CLIENT_ID=... AIRWALLEX_API_KEY=... go run ./examples/payout

Resources covered

Resource Methods
client.Balances Current, History, AllHistory
client.Transfers Create, Retrieve, List, All, Cancel, Validate, ConfirmFunding
client.BatchTransfers Create, Retrieve, List, All, AddItems, DeleteItems, Items, AllItems, Quote, Submit, Delete
client.WalletTransfers Create, Retrieve, List, All
client.Payers Create, Retrieve, Update, Delete, List, All, Validate
client.Beneficiaries Create, Retrieve, Update, Delete, List, All, Validate
client.Conversions Create, Retrieve, List, All
client.Rates Current
client.FxQuotes Create, Retrieve
client.ConversionAmendments Create, Quote, Retrieve, List, All
client.PaymentIntents Create, Retrieve, List, All, Confirm, ConfirmContinue, Capture, Cancel
client.Customers Create, Retrieve, Update, List, All, GenerateClientSecret
client.Refunds Create, Retrieve, List, All
client.IssuingCardholders Create, Retrieve, Update, Delete, List, All
client.IssuingCards Create, Retrieve, Update, Activate, Limits, List, All
client.IssuingTransactions Retrieve, List, All
client.IssuingAuthorizations Retrieve, List, All
client.Accounts Retrieve
client.FinancialTransactions Retrieve, List, All
client.Settlements Retrieve, List, All
client.Simulation demo-only: deposit create/settle/reject/reverse, transfer/payment transitions
client.GlobalAccounts Create, Retrieve, Update, Close, List, All, Transactions, AllTransactions
client.Deposits List, All
client.Reference SupportedCurrencies, SettlementAccounts, InvalidConversionDates
client.WebhookEndpoints Create, Retrieve, Update, Delete, List, All
webhooks package VerifySignature, ConstructEvent (+ WithTolerance variants)

Coverage matches the airwallex-python SDK v0.2.0 — contributions welcome for the remaining areas (disputes, payment consents, linked accounts, scale/platform APIs).

Status

This SDK is beta software:

  • The wrapped endpoints are grounded in Airwallex's published API spec and covered by tests (>90% coverage, race-detector clean), but they have not yet been exercised against every account configuration.
  • Semantic versioning applies: breaking changes only in minor versions while 0.x, and patch releases never change behavior.
  • Response types tolerate unknown fields and preserve the raw JSON, so new Airwallex API versions won't break parsing.
  • Test in the Demo environment before pointing at production, and pin the version in your go.mod.

Development

make check    # gofmt + vet + golangci-lint + race tests (what CI runs)
make cover    # coverage report

Disclaimer

This project is an independent, unofficial SDK maintained by the community. It is not affiliated with, endorsed by, sponsored by, or supported by Airwallex Pty Ltd. "Airwallex" and related marks are trademarks of Airwallex Pty Ltd; they are used here solely to indicate API compatibility. This software is provided "as is" under the MIT license — review the SECURITY policy and test against the demo environment before moving real money. If you need vendor support or SLAs, use the official Node.js SDK.

License

MIT

Documentation

Overview

Package airwallex is an unofficial Go SDK for the Airwallex API — payouts, FX, balances, global accounts, payment acceptance, issuing, and webhooks.

Getting started

Create a Client with New; credentials default to the AIRWALLEX_CLIENT_ID / AIRWALLEX_API_KEY environment variables: 

client, err := airwallex.New(
    airwallex.WithClientID("..."),
    airwallex.WithAPIKey("..."),
    airwallex.WithEnv(airwallex.Demo), // Production is the default
)
balances, err := client.Balances.Current(ctx)

Authentication happens lazily on the first request; the bearer token is cached and refreshed automatically before it expires.

Reliability

Transient failures (408/429/5xx and network errors) are retried with full-jitter exponential backoff, honouring Retry-After in both delta-seconds and HTTP-date form. 409 business conflicts are never retried. Money-moving creates carry an auto-generated request_id that is re-sent byte-for-byte on every retry, so Airwallex never executes the same operation twice.

Responses

Every response type embeds APIResource: the exact JSON the API returned is preserved in Raw (fields from newer API versions are never lost), and LastResponse records the HTTP status, x-request-id, and headers.

Errors

API failures are returned as *Error (status, Airwallex code, source, request id, and the raw error body); transport failures as *ConnectionError. Both work with errors.As.

Pagination

List methods return a Page; All methods return a Go 1.23 iterator that fetches pages lazily: 

for b, err := range client.Beneficiaries.All(ctx, nil) {
    if err != nil { return err }
    fmt.Println(b.EffectiveID())
}

Webhooks

The webhooks subpackage verifies webhook signatures with constant-time comparison and replay protection; see github.com/Cyvid7-Darus10/airwallex-go/webhooks.

Disclaimer

This library is not affiliated with, endorsed by, or supported by Airwallex Pty Ltd. "Airwallex" is their trademark, used here only to describe compatibility.

Index

Examples

Constants

View Source 
const Version = "0.2.2"

Version is the SDK release, sent in the User-Agent header.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIResource 

type APIResource struct {
	// Raw is the exact JSON the API returned for this resource.
	Raw json.RawMessage `json:"-"`
	// LastResponse describes the HTTP response this resource was decoded
	// from. For items inside a list it reflects the page's response.
	LastResponse *ResponseMetadata `json:"-"`
}

APIResource is embedded in every response type. It preserves the raw JSON body of the response, so fields added by newer Airwallex API versions are never lost even before this SDK grows typed accessors for them, and records which HTTP response the resource came from.

type Account 

type Account struct {
	APIResource
	ID         string `json:"id"`
	Identifier string `json:"identifier"`
	Nickname   string `json:"nickname"`
	Status     string `json:"status"`
	ViewType   string `json:"view_type"`

	AccountDetails    map[string]any   `json:"account_details"`
	PrimaryContact    map[string]any   `json:"primary_contact"`
	ReactivateDetails map[string]any   `json:"reactivate_details"`
	SuspendDetails    []map[string]any `json:"suspend_details"`
	Metadata          map[string]any   `json:"metadata"`

	CreatedAt string `json:"created_at"`
}

Account is your own Airwallex account (GET /api/v1/account).

type AccountsService 

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

AccountsService retrieves details of your own Airwallex account.

func (*AccountsService) Retrieve 

func (s *AccountsService) Retrieve(ctx context.Context) (*Account, error)

Retrieve fetches the account the credentials belong to.

type AmendmentCharge 

type AmendmentCharge struct {
	Amount       float64 `json:"amount"`
	Currency     string  `json:"currency"`
	Type         string  `json:"type"`
	CurrencyPair string  `json:"currency_pair"`
	AwxRate      float64 `json:"awx_rate"`
	ClientRate   float64 `json:"client_rate"`
}

AmendmentCharge is one charge or credit resulting from an amendment.

type Balance 

type Balance struct {
	APIResource
	Currency        string  `json:"currency"`
	AvailableAmount float64 `json:"available_amount"`
	PendingAmount   float64 `json:"pending_amount"`
	ReservedAmount  float64 `json:"reserved_amount"`
	TotalAmount     float64 `json:"total_amount"`
}

Balance is a wallet balance in one currency (GET /api/v1/balances/current).

type BalanceHistoryItem 

type BalanceHistoryItem struct {
	APIResource
	Currency    string  `json:"currency"`
	Amount      float64 `json:"amount"`
	Balance     float64 `json:"balance"`
	Fee         float64 `json:"fee"`
	Description string  `json:"description"`
	Source      string  `json:"source"`
	SourceType  string  `json:"source_type"`
	PostedAt    string  `json:"posted_at"`
}

BalanceHistoryItem is one ledger movement (GET /api/v1/balances/history).

type BalanceHistoryParams 

type BalanceHistoryParams struct {
	ListParams
	Currency   string `json:"currency,omitempty"`
	FromPostAt string `json:"from_post_at,omitempty"`
	ToPostAt   string `json:"to_post_at,omitempty"`
}

BalanceHistoryParams filter BalancesService.History.

type BalancesService 

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

BalancesService reports current and historical wallet balances.

func (*BalancesService) AllHistory 

func (s *BalancesService) AllHistory(ctx context.Context, params *BalanceHistoryParams) iter.Seq2[BalanceHistoryItem, error]

AllHistory iterates every ledger movement across every page.

func (*BalancesService) Current 

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

Current returns the wallet balance in every currency.

func (*BalancesService) History 

func (s *BalancesService) History(ctx context.Context, params *BalanceHistoryParams) (*Page[BalanceHistoryItem], error)

History returns one page of ledger movements, filtered by params (may be nil).

type BankDetails 

type BankDetails struct {
	AccountCurrency     string `json:"account_currency,omitempty"`
	AccountName         string `json:"account_name,omitempty"`
	AccountNumber       string `json:"account_number,omitempty"`
	AccountRoutingType1 string `json:"account_routing_type1,omitempty"`
	AccountRoutingVal1  string `json:"account_routing_value1,omitempty"`
	AccountRoutingType2 string `json:"account_routing_type2,omitempty"`
	AccountRoutingVal2  string `json:"account_routing_value2,omitempty"`
	BankCountryCode     string `json:"bank_country_code,omitempty"`
	BankName            string `json:"bank_name,omitempty"`
	BankBranch          string `json:"bank_branch,omitempty"`
	IBAN                string `json:"iban,omitempty"`
	SwiftCode           string `json:"swift_code,omitempty"`
	LocalClearingSystem string `json:"local_clearing_system,omitempty"`
}

BankDetails describe the bank account of a beneficiary.

type BatchFunding 

type BatchFunding struct {
	DepositType     string         `json:"deposit_type"`
	FailureDetails  map[string]any `json:"failure_details"`
	FailureReason   string         `json:"failure_reason"`
	FundingSourceID string         `json:"funding_source_id"`
	Reference       string         `json:"reference"`
	Status          string         `json:"status"`
}

BatchFunding describes how a batch transfer is funded.

type BatchQuoteDetails 

type BatchQuoteDetails struct {
	AmountBeneficiaryReceives float64 `json:"amount_beneficiary_receives"`
	AmountPayerPays           float64 `json:"amount_payer_pays"`
	ClientRate                float64 `json:"client_rate"`
	CurrencyPair              string  `json:"currency_pair"`
	FeeAmount                 float64 `json:"fee_amount"`
	FeeCurrency               string  `json:"fee_currency"`
	PaymentCurrency           string  `json:"payment_currency"`
	SourceCurrency            string  `json:"source_currency"`
}

BatchQuoteDetails is one FX quote inside a batch quote summary.

type BatchQuoteSummary 

type BatchQuoteSummary struct {
	ExpiresAt    string              `json:"expires_at"`
	LastQuotedAt string              `json:"last_quoted_at"`
	Quotes       []BatchQuoteDetails `json:"quotes"`
	Validity     string              `json:"validity"`
}

BatchQuoteSummary aggregates the FX quotes locked for a batch.

type BatchTransfer 

type BatchTransfer struct {
	APIResource
	ID               string `json:"id"`
	RequestID        string `json:"request_id"`
	ShortReferenceID string `json:"short_reference_id"`
	Status           string `json:"status"`
	Name             string `json:"name"`
	Remarks          string `json:"remarks"`

	Funding      *BatchFunding      `json:"funding"`
	QuoteSummary *BatchQuoteSummary `json:"quote_summary"`

	TotalItemCount int            `json:"total_item_count"`
	ValidItemCount int            `json:"valid_item_count"`
	TransferDate   string         `json:"transfer_date"`
	Metadata       map[string]any `json:"metadata"`
	UpdatedAt      string         `json:"updated_at"`
}

BatchTransfer is a batch of payouts (/api/v1/batch_transfers).

type BatchTransferCreateParams 

type BatchTransferCreateParams struct {
	Params
	// RequestID makes the create idempotent; auto-generated when empty.
	RequestID    string           `json:"request_id,omitempty"`
	Name         string           `json:"name,omitempty"`
	Remarks      string           `json:"remarks,omitempty"`
	TransferDate string           `json:"transfer_date,omitempty"`
	Items        []map[string]any `json:"items,omitempty"`
	Funding      map[string]any   `json:"funding,omitempty"`
	Metadata     map[string]any   `json:"metadata,omitempty"`
}

BatchTransferCreateParams are the parameters for BatchTransfersService.Create.

type BatchTransferItem 

type BatchTransferItem struct {
	APIResource
	ID            string           `json:"id"`
	RequestID     string           `json:"request_id"`
	Status        string           `json:"status"`
	TransferDraft map[string]any   `json:"transfer_draft"`
	TransferID    string           `json:"transfer_id"`
	Errors        []map[string]any `json:"errors"`
	UpdatedAt     string           `json:"updated_at"`
}

BatchTransferItem is one payout inside a batch.

type BatchTransferListParams 

type BatchTransferListParams struct {
	ListParams
	Status           string `json:"status,omitempty"`
	RequestID        string `json:"request_id,omitempty"`
	ShortReferenceID string `json:"short_reference_id,omitempty"`
}

BatchTransferListParams filter BatchTransfersService.List.

type BatchTransferQuoteParams 

type BatchTransferQuoteParams struct {
	Params
}

BatchTransferQuoteParams are the parameters for BatchTransfersService.Quote.

type BatchTransfersService 

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

BatchTransfersService manages batches of payouts through their full lifecycle: create, add/delete items, quote, submit.

func (*BatchTransfersService) AddItems 

func (s *BatchTransfersService) AddItems(ctx context.Context, batchTransferID string, items []map[string]any) (*BatchTransfer, error)

AddItems adds transfer drafts to a batch that has not been submitted.

func (*BatchTransfersService) All 

func (s *BatchTransfersService) All(ctx context.Context, params *BatchTransferListParams) iter.Seq2[BatchTransfer, error]

All iterates every batch transfer across every page, fetching lazily.

func (*BatchTransfersService) AllItems 

func (s *BatchTransfersService) AllItems(ctx context.Context, batchTransferID string, params *ListParams) iter.Seq2[BatchTransferItem, error]

AllItems iterates every item in a batch across every page.

func (*BatchTransfersService) Create 

func (s *BatchTransfersService) Create(ctx context.Context, params *BatchTransferCreateParams) (*BatchTransfer, error)

Create creates a batch transfer. A request_id is generated automatically when params.RequestID is empty, making the call idempotent.

func (*BatchTransfersService) Delete 

func (s *BatchTransfersService) Delete(ctx context.Context, batchTransferID string) (*BatchTransfer, error)

Delete deletes a batch that has not been submitted.

func (*BatchTransfersService) DeleteItems 

func (s *BatchTransfersService) DeleteItems(ctx context.Context, batchTransferID string, itemIDs []string) (*BatchTransfer, error)

DeleteItems removes items from a batch that has not been submitted.

func (*BatchTransfersService) Items 

func (s *BatchTransfersService) Items(ctx context.Context, batchTransferID string, params *ListParams) (*Page[BatchTransferItem], error)

Items returns one page of the transfer items in a batch.

func (*BatchTransfersService) List 

func (s *BatchTransfersService) List(ctx context.Context, params *BatchTransferListParams) (*Page[BatchTransfer], error)

List returns one page of batch transfers, filtered by params (may be nil).

func (*BatchTransfersService) Quote 

func (s *BatchTransfersService) Quote(ctx context.Context, batchTransferID string, params *BatchTransferQuoteParams) (*BatchTransfer, error)

Quote locks FX rates for the batch ahead of submission.

func (*BatchTransfersService) Retrieve 

func (s *BatchTransfersService) Retrieve(ctx context.Context, batchTransferID string) (*BatchTransfer, error)

Retrieve fetches a single batch transfer by id.

func (*BatchTransfersService) Submit 

func (s *BatchTransfersService) Submit(ctx context.Context, batchTransferID string) (*BatchTransfer, error)

Submit submits the batch for processing.

type BeneficiariesService 

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

BeneficiariesService manages payout recipients.

func (*BeneficiariesService) All 

func (s *BeneficiariesService) All(ctx context.Context, params *BeneficiaryListParams) iter.Seq2[Beneficiary, error]

All iterates every beneficiary across every page, fetching lazily.

Example

Walk every beneficiary across every page with one loop. 

package main

import (
	"context"
	"fmt"
	"log"

	airwallex "github.com/Cyvid7-Darus10/airwallex-go"
)

func main() {
	client, _ := airwallex.New(airwallex.WithEnv(airwallex.Demo))
	for beneficiary, err := range client.Beneficiaries.All(context.Background(), nil) {
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(beneficiary.BeneficiaryID, beneficiary.Nickname)
	}
}

func (*BeneficiariesService) Create 

func (s *BeneficiariesService) Create(ctx context.Context, params *BeneficiaryCreateParams) (*Beneficiary, error)

Create saves a new beneficiary.

func (*BeneficiariesService) Delete 

func (s *BeneficiariesService) Delete(ctx context.Context, beneficiaryID string) error

Delete removes a saved beneficiary.

func (*BeneficiariesService) List 

func (s *BeneficiariesService) List(ctx context.Context, params *BeneficiaryListParams) (*Page[Beneficiary], error)

List returns one page of beneficiaries, filtered by params (may be nil).

func (*BeneficiariesService) Retrieve 

func (s *BeneficiariesService) Retrieve(ctx context.Context, beneficiaryID string) (*Beneficiary, error)

Retrieve fetches a single beneficiary by id.

func (*BeneficiariesService) Update 

func (s *BeneficiariesService) Update(ctx context.Context, beneficiaryID string, params *BeneficiaryCreateParams) (*Beneficiary, error)

Update replaces a beneficiary's details.

func (*BeneficiariesService) Validate 

func (s *BeneficiariesService) Validate(ctx context.Context, params *BeneficiaryCreateParams) (json.RawMessage, error)

Validate validates a beneficiary payload without saving it, returning the raw validation result from Airwallex.

type Beneficiary 

type Beneficiary struct {
	APIResource
	ID              string              `json:"id"`
	BeneficiaryID   string              `json:"beneficiary_id"`
	Nickname        string              `json:"nickname"`
	PayerEntityType string              `json:"payer_entity_type"`
	TransferMethods []string            `json:"transfer_methods"`
	PaymentMethods  []string            `json:"payment_methods"`
	Beneficiary     *BeneficiaryDetails `json:"beneficiary"`
}

Beneficiary is a saved payout recipient (/api/v1/beneficiaries).

Current API versions return the identifier as id and the methods as transfer_methods; older versions use beneficiary_id / payment_methods. All are typed. Use the EffectiveID helper to get whichever is set.

func (*Beneficiary) EffectiveID added in v0.2.2 

func (b *Beneficiary) EffectiveID() string

EffectiveID returns the beneficiary identifier regardless of which API version produced the response.

type BeneficiaryCreateParams 

type BeneficiaryCreateParams struct {
	Params
	Beneficiary     *BeneficiaryDetails `json:"beneficiary,omitempty"`
	Nickname        string              `json:"nickname,omitempty"`
	PayerEntityType string              `json:"payer_entity_type,omitempty"`
	PaymentMethods  []string            `json:"payment_methods,omitempty"`
	TransferMethods []string            `json:"transfer_methods,omitempty"`
}

BeneficiaryCreateParams are the parameters for BeneficiariesService.Create and Update. Note: this endpoint has no request_id — creating twice creates two beneficiaries.

type BeneficiaryDetails 

type BeneficiaryDetails struct {
	EntityType     string         `json:"entity_type,omitempty"`
	CompanyName    string         `json:"company_name,omitempty"`
	FirstName      string         `json:"first_name,omitempty"`
	LastName       string         `json:"last_name,omitempty"`
	DateOfBirth    string         `json:"date_of_birth,omitempty"`
	BankDetails    *BankDetails   `json:"bank_details,omitempty"`
	Address        map[string]any `json:"address,omitempty"`
	AdditionalInfo map[string]any `json:"additional_info,omitempty"`
}

BeneficiaryDetails describe who a payout goes to.

type BeneficiaryListParams 

type BeneficiaryListParams struct {
	ListParams
	EntityType        string `json:"entity_type,omitempty"`
	Name              string `json:"name,omitempty"`
	NickName          string `json:"nick_name,omitempty"`
	CompanyName       string `json:"company_name,omitempty"`
	BankAccountNumber string `json:"bank_account_number,omitempty"`
	FromDate          string `json:"from_date,omitempty"`
	ToDate            string `json:"to_date,omitempty"`
}

BeneficiaryListParams filter BeneficiariesService.List.

type Card 

type Card struct {
	APIResource
	CardID       string `json:"card_id"`
	RequestID    string `json:"request_id"`
	CardStatus   string `json:"card_status"`
	CardNumber   string `json:"card_number"`
	CardholderID string `json:"cardholder_id"`

	Brand      string `json:"brand"`
	FormFactor string `json:"form_factor"`
	Type       string `json:"type"`
	IssueTo    string `json:"issue_to"`
	Purpose    string `json:"purpose"`

	NameOnCard      string `json:"name_on_card"`
	NickName        string `json:"nick_name"`
	Note            string `json:"note"`
	ClientData      string `json:"client_data"`
	CreatedBy       string `json:"created_by"`
	ActivateOnIssue bool   `json:"activate_on_issue"`

	AuthorizationControls map[string]any `json:"authorization_controls"`
	PostalAddress         map[string]any `json:"postal_address"`
	PrimaryContactDetails map[string]any `json:"primary_contact_details"`
	DeliveryDetails       map[string]any `json:"delivery_details"`
	Metadata              map[string]any `json:"metadata"`

	CardVersion     int              `json:"card_version"`
	AllCardVersions []map[string]any `json:"all_card_versions"`

	CreatedAt string `json:"created_at"`
}

Card is an issued card (/api/v1/issuing/cards). PCI-scoped endpoints (/details, /provision_digital_token) are deliberately not wrapped.

type CardCreateParams 

type CardCreateParams struct {
	Params
	// RequestID makes the create idempotent; auto-generated when empty
	// (Create only — Update sends the params as-is).
	RequestID    string `json:"request_id,omitempty"`
	CardholderID string `json:"cardholder_id,omitempty"`
	FormFactor   string `json:"form_factor,omitempty"`
	IssueTo      string `json:"issue_to,omitempty"`
	CreatedBy    string `json:"created_by,omitempty"`
	NameOnCard   string `json:"name_on_card,omitempty"`
	NickName     string `json:"nick_name,omitempty"`
	Note         string `json:"note,omitempty"`
	ClientData   string `json:"client_data,omitempty"`

	ActivateOnIssue       bool           `json:"activate_on_issue,omitempty"`
	Program               map[string]any `json:"program,omitempty"`
	AuthorizationControls map[string]any `json:"authorization_controls,omitempty"`
	PostalAddress         map[string]any `json:"postal_address,omitempty"`
	PrimaryContactDetails map[string]any `json:"primary_contact_details,omitempty"`
	DeliveryDetails       map[string]any `json:"delivery_details,omitempty"`
	Metadata              map[string]any `json:"metadata,omitempty"`
}

CardCreateParams are the parameters for IssuingCardsService.Create and Update.

type CardLimits 

type CardLimits struct {
	APIResource
	Currency             string           `json:"currency"`
	Limits               []map[string]any `json:"limits"`
	CashWithdrawalLimits []map[string]any `json:"cash_withdrawal_limits"`
}

CardLimits are a card's spending limits (GET /api/v1/issuing/cards/{id}/limits).

type CardListParams 

type CardListParams struct {
	ListParams
	CardStatus    string `json:"card_status,omitempty"`
	CardholderID  string `json:"cardholder_id,omitempty"`
	NickName      string `json:"nick_name,omitempty"`
	FromCreatedAt string `json:"from_created_at,omitempty"`
	ToCreatedAt   string `json:"to_created_at,omitempty"`
	FromUpdatedAt string `json:"from_updated_at,omitempty"`
	ToUpdatedAt   string `json:"to_updated_at,omitempty"`
}

CardListParams filter IssuingCardsService.List.

type Cardholder 

type Cardholder struct {
	APIResource
	CardholderID string `json:"cardholder_id"`
	Email        string `json:"email"`
	MobileNumber string `json:"mobile_number"`
	Status       string `json:"status"`

	Individual    map[string]any `json:"individual"`
	Address       map[string]any `json:"address"`
	PostalAddress map[string]any `json:"postal_address"`
}

Cardholder is a person cards can be issued to (/api/v1/issuing/cardholders).

type CardholderCreateParams 

type CardholderCreateParams struct {
	Params
	Email         string         `json:"email,omitempty"`
	MobileNumber  string         `json:"mobile_number,omitempty"`
	Individual    map[string]any `json:"individual,omitempty"`
	Address       map[string]any `json:"address,omitempty"`
	PostalAddress map[string]any `json:"postal_address,omitempty"`
	// Type is the cardholder kind, e.g. "INDIVIDUAL" or "DELEGATE".
	Type string `json:"type,omitempty"`
}

CardholderCreateParams are the parameters for IssuingCardholdersService.Create and Update. Note: this endpoint has no request_id — creating twice creates two cardholders.

type CardholderListParams 

type CardholderListParams struct {
	ListParams
	CardholderStatus string `json:"cardholder_status,omitempty"`
	Email            string `json:"email,omitempty"`
}

CardholderListParams filter IssuingCardholdersService.List.

type Client 

type Client struct {

	// Accounts retrieves details of your own Airwallex account.
	Accounts *AccountsService
	// Balances reports current and historical wallet balances.
	Balances *BalancesService
	// BatchTransfers manages batches of payouts.
	BatchTransfers *BatchTransfersService
	// Beneficiaries manages payout recipients.
	Beneficiaries *BeneficiariesService
	// ConversionAmendments amends or cancels existing conversions.
	ConversionAmendments *ConversionAmendmentsService
	// Conversions books FX conversions between wallet currencies.
	Conversions *ConversionsService
	// Customers manages payment-acceptance shoppers.
	Customers *CustomersService
	// Deposits lists deposits received into the wallet.
	Deposits *DepositsService
	// FinancialTransactions lists payment-acceptance ledger activity.
	FinancialTransactions *FinancialTransactionsService
	// FxQuotes creates lockable FX quotes.
	FxQuotes *FxQuotesService
	// GlobalAccounts manages local currency accounts for collecting funds.
	GlobalAccounts *GlobalAccountsService
	// IssuingAuthorizations lists card authorizations.
	IssuingAuthorizations *IssuingAuthorizationsService
	// IssuingCardholders manages people cards can be issued to.
	IssuingCardholders *IssuingCardholdersService
	// IssuingCards manages issued cards.
	IssuingCards *IssuingCardsService
	// IssuingTransactions lists card transactions.
	IssuingTransactions *IssuingTransactionsService
	// Payers manages the payers money is sent on behalf of.
	Payers *PayersService
	// PaymentIntents collects payments from shoppers.
	PaymentIntents *PaymentIntentsService
	// Rates fetches indicative FX rates.
	Rates *RatesService
	// Reference exposes static reference data.
	Reference *ReferenceService
	// Refunds refunds collected payments.
	Refunds *RefundsService
	// Settlements lists payment-acceptance settlements.
	Settlements *SettlementsService
	// Simulation drives demo-environment state transitions (sandbox only).
	Simulation *SimulationService
	// Transfers creates and manages payouts to beneficiaries.
	Transfers *TransfersService
	// WalletTransfers moves money between Airwallex wallets.
	WalletTransfers *WalletTransfersService
	// WebhookEndpoints manages webhook subscriptions.
	WebhookEndpoints *WebhookEndpointsService
	// contains filtered or unexported fields
}

Client is the Airwallex API client. Create one with New and share it — it is safe for concurrent use.

func New 

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

New creates a Client. Credentials default to the AIRWALLEX_CLIENT_ID and AIRWALLEX_API_KEY environment variables, and the environment defaults to Production.

Example

Construct a client for the demo (sandbox) environment. Credentials can also come from the AIRWALLEX_CLIENT_ID / AIRWALLEX_API_KEY environment variables, in which case New() needs no credential options at all. 

package main

import (
	"context"
	"fmt"
	"log"

	airwallex "github.com/Cyvid7-Darus10/airwallex-go"
)

func main() {
	client, err := airwallex.New(
		airwallex.WithClientID("your_client_id"),
		airwallex.WithAPIKey("your_api_key"),
		airwallex.WithEnv(airwallex.Demo),
	)
	if err != nil {
		log.Fatal(err)
	}
	balances, err := client.Balances.Current(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	for _, balance := range balances {
		fmt.Println(balance.Currency, balance.AvailableAmount)
	}
}

func (*Client) GoString 

func (c *Client) GoString() string

GoString implements fmt.GoStringer (%#v) with credentials redacted.

func (*Client) Request 

func (c *Client) Request(ctx context.Context, method, path string, params url.Values, body, out any) error

Request calls any Airwallex endpoint, including ones this SDK has no typed wrapper for yet. Authentication, retries, and error mapping still apply. body is JSON-encoded when non-nil; the response is decoded into out when non-nil. 

var disputes json.RawMessage
err := client.Request(ctx, "GET", "/api/v1/pa/payment_disputes",
    url.Values{"status": {"OPEN"}}, nil, &disputes)
Example

Call an endpoint the SDK has no typed wrapper for, with auth, retries, and error mapping intact. 

package main

import (
	"context"
	"log"

	airwallex "github.com/Cyvid7-Darus10/airwallex-go"
)

func main() {
	client, _ := airwallex.New(airwallex.WithEnv(airwallex.Demo))
	var out map[string]any
	err := client.Request(context.Background(), "GET",
		"/api/v1/reference/supported_currencies", nil, nil, &out)
	if err != nil {
		log.Fatal(err)
	}
}

func (*Client) RequestWithHeaders added in v0.2.0 

func (c *Client) RequestWithHeaders(ctx context.Context, method, path string, params url.Values, headers http.Header, body, out any) error

RequestWithHeaders is Request with additional headers applied to the call (e.g. a one-off x-api-version). Caller headers override the SDK defaults on collision; the Authorization header is always managed by the SDK.

func (*Client) String 

func (c *Client) String() string

String implements fmt.Stringer with credentials redacted.

type ConnectionError 

type ConnectionError struct {
	// Message describes the failed operation.
	Message string
	// Err is the underlying transport error.
	Err error
}

ConnectionError means the request never received a valid HTTP response (network failure, timeout, cancelled context). It wraps the underlying transport error.

func (*ConnectionError) Error 

func (e *ConnectionError) Error() string

func (*ConnectionError) Unwrap 

func (e *ConnectionError) Unwrap() error

type Conversion 

type Conversion struct {
	APIResource
	ConversionID     string `json:"conversion_id"`
	RequestID        string `json:"request_id"`
	ShortReferenceID string `json:"short_reference_id"`
	Status           string `json:"status"`

	CurrencyPair  string  `json:"currency_pair"`
	BuyAmount     float64 `json:"buy_amount"`
	BuyCurrency   string  `json:"buy_currency"`
	SellAmount    float64 `json:"sell_amount"`
	SellCurrency  string  `json:"sell_currency"`
	DealtCurrency string  `json:"dealt_currency"`

	AwxRate     float64          `json:"awx_rate"`
	ClientRate  float64          `json:"client_rate"`
	MidRate     float64          `json:"mid_rate"`
	RateDetails []map[string]any `json:"rate_details"`

	QuoteID              string `json:"quote_id"`
	ConversionDate       string `json:"conversion_date"`
	SettlementCutoffTime string `json:"settlement_cutoff_time"`
	Reason               string `json:"reason"`

	CreatedAt     string `json:"created_at"`
	LastUpdatedAt string `json:"last_updated_at"`
}

Conversion is a booked FX conversion (/api/v1/conversions).

type ConversionAmendment 

type ConversionAmendment struct {
	APIResource
	AmendmentID      string `json:"amendment_id"`
	RequestID        string `json:"request_id"`
	ShortReferenceID string `json:"short_reference_id"`
	ConversionID     string `json:"conversion_id"`
	Type             string `json:"type"`

	Charges  []AmendmentCharge `json:"charges"`
	Metadata map[string]any    `json:"metadata"`

	CreatedAt string `json:"created_at"`
	UpdatedAt string `json:"updated_at"`
}

ConversionAmendment amends or cancels an existing conversion (/api/v1/conversion_amendments).

type ConversionAmendmentCreateParams 

type ConversionAmendmentCreateParams struct {
	Params
	// RequestID makes the call idempotent; auto-generated when empty.
	RequestID    string `json:"request_id,omitempty"`
	ConversionID string `json:"conversion_id,omitempty"`
	// Type is the amendment kind, e.g. "CANCELLATION".
	Type     string         `json:"type,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

ConversionAmendmentCreateParams are the parameters for ConversionAmendmentsService.Create and Quote.

type ConversionAmendmentListParams 

type ConversionAmendmentListParams struct {
	ListParams
	ConversionID string `json:"conversion_id,omitempty"`
}

ConversionAmendmentListParams filter ConversionAmendmentsService.List. ConversionID is required by the API.

type ConversionAmendmentQuote 

type ConversionAmendmentQuote struct {
	APIResource
	RequestID        string            `json:"request_id"`
	ShortReferenceID string            `json:"short_reference_id"`
	ConversionID     string            `json:"conversion_id"`
	Type             string            `json:"type"`
	Charges          []AmendmentCharge `json:"charges"`
	Metadata         map[string]any    `json:"metadata"`
}

ConversionAmendmentQuote previews the charges of an amendment before committing to it.

type ConversionAmendmentsService 

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

ConversionAmendmentsService amends or cancels existing conversions.

func (*ConversionAmendmentsService) All 

func (s *ConversionAmendmentsService) All(ctx context.Context, params *ConversionAmendmentListParams) iter.Seq2[ConversionAmendment, error]

All iterates every amendment across every page, fetching lazily.

func (*ConversionAmendmentsService) Create 

func (s *ConversionAmendmentsService) Create(ctx context.Context, params *ConversionAmendmentCreateParams) (*ConversionAmendment, error)

Create executes an amendment (e.g. cancel a conversion). A request_id is generated automatically when params.RequestID is empty.

func (*ConversionAmendmentsService) List 

func (s *ConversionAmendmentsService) List(ctx context.Context, params *ConversionAmendmentListParams) (*Page[ConversionAmendment], error)

List returns one page of amendments for a conversion.

func (*ConversionAmendmentsService) Quote 

func (s *ConversionAmendmentsService) Quote(ctx context.Context, params *ConversionAmendmentCreateParams) (*ConversionAmendmentQuote, error)

Quote previews the charges an amendment would incur, without executing it. A request_id is generated automatically when params.RequestID is empty.

func (*ConversionAmendmentsService) Retrieve 

func (s *ConversionAmendmentsService) Retrieve(ctx context.Context, conversionAmendmentID string) (*ConversionAmendment, error)

Retrieve fetches a single amendment by id.

type ConversionCreateParams 

type ConversionCreateParams struct {
	Params
	// RequestID makes the create idempotent; auto-generated when empty.
	RequestID    string  `json:"request_id,omitempty"`
	BuyCurrency  string  `json:"buy_currency,omitempty"`
	BuyAmount    float64 `json:"buy_amount,omitempty"`
	SellCurrency string  `json:"sell_currency,omitempty"`
	SellAmount   float64 `json:"sell_amount,omitempty"`
	QuoteID      string  `json:"quote_id,omitempty"`
	// TermAgreement must be true to accept the conversion terms.
	TermAgreement  bool   `json:"term_agreement,omitempty"`
	ConversionDate string `json:"conversion_date,omitempty"`
	Reason         string `json:"reason,omitempty"`
}

ConversionCreateParams are the parameters for ConversionsService.Create.

type ConversionListParams 

type ConversionListParams struct {
	ListParams
	Status        string `json:"status,omitempty"`
	BuyCurrency   string `json:"buy_currency,omitempty"`
	SellCurrency  string `json:"sell_currency,omitempty"`
	RequestID     string `json:"request_id,omitempty"`
	FromCreatedAt string `json:"from_created_at,omitempty"`
	ToCreatedAt   string `json:"to_created_at,omitempty"`
}

ConversionListParams filter ConversionsService.List.

type ConversionsService 

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

ConversionsService books FX conversions between wallet currencies.

func (*ConversionsService) All 

func (s *ConversionsService) All(ctx context.Context, params *ConversionListParams) iter.Seq2[Conversion, error]

All iterates every conversion across every page, fetching lazily.

func (*ConversionsService) Create 

func (s *ConversionsService) Create(ctx context.Context, params *ConversionCreateParams) (*Conversion, error)

Create books a conversion. A request_id is generated automatically when params.RequestID is empty, making the call idempotent.

func (*ConversionsService) List 

func (s *ConversionsService) List(ctx context.Context, params *ConversionListParams) (*Page[Conversion], error)

List returns one page of conversions, filtered by params (may be nil).

func (*ConversionsService) Retrieve 

func (s *ConversionsService) Retrieve(ctx context.Context, conversionID string) (*Conversion, error)

Retrieve fetches a single conversion by id.

type Customer 

type Customer struct {
	APIResource
	ID                 string `json:"id"`
	RequestID          string `json:"request_id"`
	MerchantCustomerID string `json:"merchant_customer_id"`

	FirstName    string         `json:"first_name"`
	LastName     string         `json:"last_name"`
	BusinessName string         `json:"business_name"`
	Email        string         `json:"email"`
	PhoneNumber  string         `json:"phone_number"`
	Address      map[string]any `json:"address"`

	ClientSecret string         `json:"client_secret"`
	Metadata     map[string]any `json:"metadata"`

	CreatedAt string `json:"created_at"`
	UpdatedAt string `json:"updated_at"`
}

Customer is a shopper whose payment details can be saved (/api/v1/pa/customers).

type CustomerClientSecret 

type CustomerClientSecret struct {
	APIResource
	ClientSecret string `json:"client_secret"`
	ExpiredTime  string `json:"expired_time"`
}

CustomerClientSecret is a short-lived client secret for browser and mobile SDK flows.

type CustomerCreateParams 

type CustomerCreateParams struct {
	Params
	// RequestID makes the create idempotent; auto-generated when empty
	// (Create only — Update sends the params as-is).
	RequestID          string         `json:"request_id,omitempty"`
	MerchantCustomerID string         `json:"merchant_customer_id,omitempty"`
	FirstName          string         `json:"first_name,omitempty"`
	LastName           string         `json:"last_name,omitempty"`
	BusinessName       string         `json:"business_name,omitempty"`
	Email              string         `json:"email,omitempty"`
	PhoneNumber        string         `json:"phone_number,omitempty"`
	Address            map[string]any `json:"address,omitempty"`
	Metadata           map[string]any `json:"metadata,omitempty"`
}

CustomerCreateParams are the parameters for CustomersService.Create and Update.

type CustomerListParams 

type CustomerListParams struct {
	ListParams
	MerchantCustomerID string `json:"merchant_customer_id,omitempty"`
	FromCreatedAt      string `json:"from_created_at,omitempty"`
	ToCreatedAt        string `json:"to_created_at,omitempty"`
}

CustomerListParams filter CustomersService.List.

type CustomersService 

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

CustomersService manages payment-acceptance shoppers.

func (*CustomersService) All 

func (s *CustomersService) All(ctx context.Context, params *CustomerListParams) iter.Seq2[Customer, error]

All iterates every customer across every page, fetching lazily.

func (*CustomersService) Create 

func (s *CustomersService) Create(ctx context.Context, params *CustomerCreateParams) (*Customer, error)

Create saves a new customer. A request_id is generated automatically when params.RequestID is empty, making the call idempotent.

func (*CustomersService) GenerateClientSecret 

func (s *CustomersService) GenerateClientSecret(ctx context.Context, customerID string) (*CustomerClientSecret, error)

GenerateClientSecret creates a short-lived client secret for use in browser and mobile SDK flows.

func (*CustomersService) List 

func (s *CustomersService) List(ctx context.Context, params *CustomerListParams) (*Page[Customer], error)

List returns one page of customers, filtered by params (may be nil).

func (*CustomersService) Retrieve 

func (s *CustomersService) Retrieve(ctx context.Context, customerID string) (*Customer, error)

Retrieve fetches a single customer by id.

func (*CustomersService) Update 

func (s *CustomersService) Update(ctx context.Context, customerID string, params *CustomerCreateParams) (*Customer, error)

Update changes a customer's details.

type Deposit 

type Deposit struct {
	APIResource
	ID                    string         `json:"id"`
	Amount                float64        `json:"amount"`
	Currency              string         `json:"currency"`
	Status                string         `json:"status"`
	Reference             string         `json:"reference"`
	Payer                 map[string]any `json:"payer"`
	Fee                   map[string]any `json:"fee"`
	FundingSourceID       string         `json:"funding_source_id"`
	GlobalAccountID       string         `json:"global_account_id"`
	ProviderTransactionID string         `json:"provider_transaction_id"`
	Type                  string         `json:"type"`
	EstimatedSettledAt    string         `json:"estimated_settled_at"`
	SettledAt             string         `json:"settled_at"`
	CreatedAt             string         `json:"created_at"`
}

Deposit is money received into the wallet (GET /api/v1/deposits).

type DepositListParams 

type DepositListParams struct {
	ListParams
	FromCreatedAt string `json:"from_created_at,omitempty"`
	ToCreatedAt   string `json:"to_created_at,omitempty"`
}

DepositListParams filter DepositsService.List.

type DepositsService 

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

DepositsService lists deposits received into the wallet.

func (*DepositsService) All 

func (s *DepositsService) All(ctx context.Context, params *DepositListParams) iter.Seq2[Deposit, error]

All iterates every deposit across every page, fetching lazily.

func (*DepositsService) List 

func (s *DepositsService) List(ctx context.Context, params *DepositListParams) (*Page[Deposit], error)

List returns one page of deposits, filtered by params (may be nil).

type Environment 

type Environment string

Environment selects which Airwallex API host the client talks to. 

const (
	// Production is the live Airwallex API (https://api.airwallex.com).
	Production Environment = "production"
	// Demo is the Airwallex sandbox (https://api-demo.airwallex.com).
	Demo Environment = "demo"
)

type Error 

type Error struct {
	// StatusCode is the HTTP status code of the response.
	StatusCode int
	// Code is the Airwallex machine-readable error code (e.g. "validation_error").
	Code string
	// Source is the field or parameter the error refers to, when provided.
	Source string
	// RequestID is the Airwallex request id from the x-request-id header —
	// include it when contacting Airwallex support.
	RequestID string
	// Message is the human-readable error description.
	Message string
	// Raw is the full error response body. Validation failures carry an
	// "errors" object here with per-field detail beyond Message.
	Raw json.RawMessage
}

Error is an error response from the Airwallex API.

Use errors.As to inspect it: 

var apiErr *airwallex.Error
if errors.As(err, &apiErr) && apiErr.StatusCode == http.StatusNotFound {
    ...
}
Example

Inspect a typed API error, including the request id to quote to Airwallex support. 

package main

import (
	"context"
	"errors"
	"fmt"

	airwallex "github.com/Cyvid7-Darus10/airwallex-go"
)

func main() {
	client, _ := airwallex.New(airwallex.WithEnv(airwallex.Demo))
	_, err := client.Transfers.Retrieve(context.Background(), "tra_missing")
	var apiErr *airwallex.Error
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.StatusCode, apiErr.Code, apiErr.RequestID)
	}
}

func (*Error) Error 

func (e *Error) Error() string

func (*Error) IsRetryable 

func (e *Error) IsRetryable() bool

IsRetryable reports whether the SDK considers this status transient (408, 429, or 5xx). 409 business conflicts are never retryable.

type FinancialTransaction 

type FinancialTransaction struct {
	APIResource
	ID              string  `json:"id"`
	BatchID         string  `json:"batch_id"`
	SourceID        string  `json:"source_id"`
	FundingSourceID string  `json:"funding_source_id"`
	SourceType      string  `json:"source_type"`
	TransactionType string  `json:"transaction_type"`
	Currency        string  `json:"currency"`
	Amount          float64 `json:"amount"`
	Net             float64 `json:"net"`
	Fee             float64 `json:"fee"`
	ClientRate      float64 `json:"client_rate"`
	CurrencyPair    string  `json:"currency_pair"`
	Description     string  `json:"description"`
	Status          string  `json:"status"`

	EstimatedSettledAt string `json:"estimated_settled_at"`
	SettledAt          string `json:"settled_at"`
	CreatedAt          string `json:"created_at"`
}

FinancialTransaction is one payment-acceptance ledger entry (/api/v1/pa/financial/transactions).

type FinancialTransactionListParams 

type FinancialTransactionListParams struct {
	ListParams
	BatchID       string `json:"batch_id,omitempty"`
	Currency      string `json:"currency,omitempty"`
	SourceID      string `json:"source_id,omitempty"`
	Status        string `json:"status,omitempty"`
	FromCreatedAt string `json:"from_created_at,omitempty"`
	ToCreatedAt   string `json:"to_created_at,omitempty"`
}

FinancialTransactionListParams filter FinancialTransactionsService.List.

type FinancialTransactionsService 

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

FinancialTransactionsService lists payment-acceptance ledger activity.

func (*FinancialTransactionsService) All 

func (s *FinancialTransactionsService) All(ctx context.Context, params *FinancialTransactionListParams) iter.Seq2[FinancialTransaction, error]

All iterates every financial transaction across every page.

func (*FinancialTransactionsService) List 

func (s *FinancialTransactionsService) List(ctx context.Context, params *FinancialTransactionListParams) (*Page[FinancialTransaction], error)

List returns one page of financial transactions, filtered by params (may be nil).

func (*FinancialTransactionsService) Retrieve 

func (s *FinancialTransactionsService) Retrieve(ctx context.Context, transactionID string) (*FinancialTransaction, error)

Retrieve fetches a single financial transaction by id.

type FxQuote 

type FxQuote struct {
	APIResource
	// ID is the quote id; current API versions return it as quote_id
	// (see QuoteID), older ones as id.
	ID        string `json:"id"`
	QuoteID   string `json:"quote_id"`
	RequestID string `json:"request_id"`
	Status    string `json:"status"`

	CurrencyPair  string  `json:"currency_pair"`
	BuyAmount     float64 `json:"buy_amount"`
	BuyCurrency   string  `json:"buy_currency"`
	SellAmount    float64 `json:"sell_amount"`
	SellCurrency  string  `json:"sell_currency"`
	DealtCurrency string  `json:"dealt_currency"`

	AwxRate     float64          `json:"awx_rate"`
	ClientRate  float64          `json:"client_rate"`
	MidRate     float64          `json:"mid_rate"`
	RateDetails []map[string]any `json:"rate_details"`

	Validity       string `json:"validity"`
	ConversionDate string `json:"conversion_date"`
	ExpiresAt      string `json:"expires_at"`
	CreatedAt      string `json:"created_at"`
}

FxQuote is a lockable FX quote (/api/v1/fx/quotes). Unlike RateQuote, the rate is held for the validity window and can be used to create a conversion at that rate.

type FxQuoteCreateParams 

type FxQuoteCreateParams struct {
	Params
	// RequestID makes the create idempotent; auto-generated when empty.
	RequestID    string  `json:"request_id,omitempty"`
	BuyCurrency  string  `json:"buy_currency,omitempty"`
	BuyAmount    float64 `json:"buy_amount,omitempty"`
	SellCurrency string  `json:"sell_currency,omitempty"`
	SellAmount   float64 `json:"sell_amount,omitempty"`
	// Validity is how long the quote is locked, e.g. "HR_1".
	Validity       string `json:"validity,omitempty"`
	ConversionDate string `json:"conversion_date,omitempty"`
}

FxQuoteCreateParams are the parameters for FxQuotesService.Create.

type FxQuotesService 

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

FxQuotesService creates lockable FX quotes.

func (*FxQuotesService) Create 

func (s *FxQuotesService) Create(ctx context.Context, params *FxQuoteCreateParams) (*FxQuote, error)

Create locks an FX quote. A request_id is generated automatically when params.RequestID is empty, making the call idempotent.

func (*FxQuotesService) Retrieve 

func (s *FxQuotesService) Retrieve(ctx context.Context, quoteID string) (*FxQuote, error)

Retrieve fetches a single FX quote by id.

type GlobalAccount 

type GlobalAccount struct {
	APIResource
	ID            string `json:"id"`
	RequestID     string `json:"request_id"`
	AccountName   string `json:"account_name"`
	AccountNumber string `json:"account_number"`
	AccountType   string `json:"account_type"`
	CountryCode   string `json:"country_code"`
	NickName      string `json:"nick_name"`
	Status        string `json:"status"`

	Institution       *GlobalAccountInstitution `json:"institution"`
	RequiredFeatures  []GlobalAccountFeature    `json:"required_features"`
	SupportedFeatures []GlobalAccountFeature    `json:"supported_features"`

	// Legacy fields returned by older API versions.
	AccountRoutingType string         `json:"account_routing_type"`
	AccountRoutingVal  string         `json:"account_routing_value"`
	BranchCode         string         `json:"branch_code"`
	ClearingSystems    []string       `json:"clearing_systems"`
	Currency           string         `json:"currency"`
	InstitutionName    string         `json:"institution_name"`
	PaymentMethods     []string       `json:"payment_methods"`
	SwiftCode          string         `json:"swift_code"`
	RegisteredEmail    string         `json:"registered_email"`
	AlternateAccountID map[string]any `json:"alternate_account_identifiers"`
}

GlobalAccount is a local currency account for collecting funds (/api/v1/global_accounts).

Current API versions describe the bank via Institution and the currencies/rails via RequiredFeatures / SupportedFeatures; older versions use the flat Currency / InstitutionName / ClearingSystems fields. All are typed.

func (*GlobalAccount) PrimaryCurrency added in v0.2.4 

func (g *GlobalAccount) PrimaryCurrency() string

PrimaryCurrency returns the account's currency regardless of which API version produced the response: the flat Currency field when present, otherwise the first required feature's currency.

type GlobalAccountCreateParams 

type GlobalAccountCreateParams struct {
	Params
	// RequestID makes the create idempotent; auto-generated when empty.
	RequestID      string   `json:"request_id,omitempty"`
	CountryCode    string   `json:"country_code,omitempty"`
	Currency       string   `json:"currency,omitempty"`
	NickName       string   `json:"nick_name,omitempty"`
	PaymentMethods []string `json:"payment_methods,omitempty"`
}

GlobalAccountCreateParams are the parameters for GlobalAccountsService.Create.

type GlobalAccountFeature added in v0.2.4 

type GlobalAccountFeature struct {
	Currency            string                     `json:"currency"`
	TransferMethod      string                     `json:"transfer_method"`
	Type                string                     `json:"type"`
	LocalClearingSystem string                     `json:"local_clearing_system"`
	RoutingCodes        []GlobalAccountRoutingCode `json:"routing_codes"`
	AliasTypes          []string                   `json:"alias_types"`
}

GlobalAccountFeature describes one capability of a global account (current API versions), e.g. SGD LOCAL deposits via FAST.

type GlobalAccountInstitution added in v0.2.4 

type GlobalAccountInstitution struct {
	Name    string `json:"name"`
	Address string `json:"address"`
	City    string `json:"city"`
	ZipCode string `json:"zip_code"`
}

GlobalAccountInstitution describes the bank holding a global account (current API versions).

type GlobalAccountListParams 

type GlobalAccountListParams struct {
	ListParams
	Currency      string `json:"currency,omitempty"`
	CountryCode   string `json:"country_code,omitempty"`
	Status        string `json:"status,omitempty"`
	NickName      string `json:"nick_name,omitempty"`
	FromCreatedAt string `json:"from_created_at,omitempty"`
	ToCreatedAt   string `json:"to_created_at,omitempty"`
}

GlobalAccountListParams filter GlobalAccountsService.List.

type GlobalAccountRoutingCode added in v0.2.4 

type GlobalAccountRoutingCode struct {
	Type  string `json:"type"`
	Value string `json:"value"`
}

GlobalAccountRoutingCode is one routing identifier of a global account feature (e.g. bank_code, branch_code).

type GlobalAccountTransaction 

type GlobalAccountTransaction struct {
	APIResource
	Amount          float64 `json:"amount"`
	Currency        string  `json:"currency"`
	Description     string  `json:"description"`
	Fee             float64 `json:"fee"`
	PayerName       string  `json:"payer_name"`
	Reference       string  `json:"reference"`
	Status          string  `json:"status"`
	TransactionDate string  `json:"transaction_date"`
}

GlobalAccountTransaction is one transaction received into a global account.

type GlobalAccountTransactionsParams 

type GlobalAccountTransactionsParams struct {
	ListParams
	FromCreatedAt string `json:"from_created_at,omitempty"`
	ToCreatedAt   string `json:"to_created_at,omitempty"`
}

GlobalAccountTransactionsParams filter GlobalAccountsService.Transactions.

type GlobalAccountUpdateParams 

type GlobalAccountUpdateParams struct {
	Params
	NickName string `json:"nick_name,omitempty"`
}

GlobalAccountUpdateParams are the parameters for GlobalAccountsService.Update.

type GlobalAccountsService 

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

GlobalAccountsService manages local currency accounts for collecting funds.

func (*GlobalAccountsService) All 

func (s *GlobalAccountsService) All(ctx context.Context, params *GlobalAccountListParams) iter.Seq2[GlobalAccount, error]

All iterates every global account across every page, fetching lazily.

func (*GlobalAccountsService) AllTransactions 

func (s *GlobalAccountsService) AllTransactions(ctx context.Context, globalAccountID string, params *GlobalAccountTransactionsParams) iter.Seq2[GlobalAccountTransaction, error]

AllTransactions iterates every transaction across every page.

func (*GlobalAccountsService) Close 

func (s *GlobalAccountsService) Close(ctx context.Context, globalAccountID string) (*GlobalAccount, error)

Close closes a global account.

func (*GlobalAccountsService) Create 

func (s *GlobalAccountsService) Create(ctx context.Context, params *GlobalAccountCreateParams) (*GlobalAccount, error)

Create opens a global account. A request_id is generated automatically when params.RequestID is empty, making the call idempotent.

func (*GlobalAccountsService) List 

func (s *GlobalAccountsService) List(ctx context.Context, params *GlobalAccountListParams) (*Page[GlobalAccount], error)

List returns one page of global accounts, filtered by params (may be nil).

func (*GlobalAccountsService) Retrieve 

func (s *GlobalAccountsService) Retrieve(ctx context.Context, globalAccountID string) (*GlobalAccount, error)

Retrieve fetches a single global account by id.

func (*GlobalAccountsService) Transactions 

func (s *GlobalAccountsService) Transactions(ctx context.Context, globalAccountID string, params *GlobalAccountTransactionsParams) (*Page[GlobalAccountTransaction], error)

Transactions returns one page of transactions received into a global account.

func (*GlobalAccountsService) Update 

func (s *GlobalAccountsService) Update(ctx context.Context, globalAccountID string, params *GlobalAccountUpdateParams) (*GlobalAccount, error)

Update changes a global account's mutable details.

type IssuingAuthorization 

type IssuingAuthorization struct {
	APIResource
	TransactionID string `json:"transaction_id"`
	Status        string `json:"status"`

	CardID               string `json:"card_id"`
	CardNickname         string `json:"card_nickname"`
	MaskedCardNumber     string `json:"masked_card_number"`
	DigitalWalletTokenID string `json:"digital_wallet_token_id"`

	TransactionAmount   float64          `json:"transaction_amount"`
	TransactionCurrency string           `json:"transaction_currency"`
	BillingAmount       float64          `json:"billing_amount"`
	BillingCurrency     string           `json:"billing_currency"`
	FeeDetails          []map[string]any `json:"fee_details"`

	Merchant                       map[string]any `json:"merchant"`
	AcquiringInstitutionIdentifier string         `json:"acquiring_institution_identifier"`
	AuthCode                       string         `json:"auth_code"`
	NetworkTransactionID           string         `json:"network_transaction_id"`
	RetrievalRef                   string         `json:"retrieval_ref"`
	LifecycleID                    string         `json:"lifecycle_id"`
	UpdatedByTransaction           string         `json:"updated_by_transaction"`

	RiskDetails   map[string]any `json:"risk_details"`
	FailureReason string         `json:"failure_reason"`
	ClientData    string         `json:"client_data"`

	CreateTime string `json:"create_time"`
	ExpiryDate string `json:"expiry_date"`
}

IssuingAuthorization is a card authorization (/api/v1/issuing/authorizations).

type IssuingAuthorizationListParams 

type IssuingAuthorizationListParams struct {
	ListParams
	CardID               string `json:"card_id,omitempty"`
	Status               string `json:"status,omitempty"`
	BillingCurrency      string `json:"billing_currency,omitempty"`
	DigitalWalletTokenID string `json:"digital_wallet_token_id,omitempty"`
	LifecycleID          string `json:"lifecycle_id,omitempty"`
	RetrievalRef         string `json:"retrieval_ref,omitempty"`
	FromCreatedAt        string `json:"from_created_at,omitempty"`
	ToCreatedAt          string `json:"to_created_at,omitempty"`
}

IssuingAuthorizationListParams filter IssuingAuthorizationsService.List.

type IssuingAuthorizationsService 

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

IssuingAuthorizationsService lists card authorizations.

func (*IssuingAuthorizationsService) All 

func (s *IssuingAuthorizationsService) All(ctx context.Context, params *IssuingAuthorizationListParams) iter.Seq2[IssuingAuthorization, error]

All iterates every authorization across every page, fetching lazily.

func (*IssuingAuthorizationsService) List 

func (s *IssuingAuthorizationsService) List(ctx context.Context, params *IssuingAuthorizationListParams) (*Page[IssuingAuthorization], error)

List returns one page of authorizations, filtered by params (may be nil).

func (*IssuingAuthorizationsService) Retrieve 

func (s *IssuingAuthorizationsService) Retrieve(ctx context.Context, authorizationID string) (*IssuingAuthorization, error)

Retrieve fetches a single authorization by id.

type IssuingCardholdersService 

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

IssuingCardholdersService manages people cards can be issued to.

func (*IssuingCardholdersService) All 

func (s *IssuingCardholdersService) All(ctx context.Context, params *CardholderListParams) iter.Seq2[Cardholder, error]

All iterates every cardholder across every page, fetching lazily.

func (*IssuingCardholdersService) Create 

func (s *IssuingCardholdersService) Create(ctx context.Context, params *CardholderCreateParams) (*Cardholder, error)

Create registers a new cardholder.

func (*IssuingCardholdersService) Delete 

func (s *IssuingCardholdersService) Delete(ctx context.Context, cardholderID string) (*Cardholder, error)

Delete removes a cardholder who has no active cards.

func (*IssuingCardholdersService) List 

func (s *IssuingCardholdersService) List(ctx context.Context, params *CardholderListParams) (*Page[Cardholder], error)

List returns one page of cardholders, filtered by params (may be nil).

func (*IssuingCardholdersService) Retrieve 

func (s *IssuingCardholdersService) Retrieve(ctx context.Context, cardholderID string) (*Cardholder, error)

Retrieve fetches a single cardholder by id.

func (*IssuingCardholdersService) Update 

func (s *IssuingCardholdersService) Update(ctx context.Context, cardholderID string, params *CardholderCreateParams) (*Cardholder, error)

Update changes a cardholder's details.

type IssuingCardsService 

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

IssuingCardsService manages issued cards.

func (*IssuingCardsService) Activate 

func (s *IssuingCardsService) Activate(ctx context.Context, cardID string) error

Activate activates a physical card.

func (*IssuingCardsService) All 

func (s *IssuingCardsService) All(ctx context.Context, params *CardListParams) iter.Seq2[Card, error]

All iterates every card across every page, fetching lazily.

func (*IssuingCardsService) Create 

func (s *IssuingCardsService) Create(ctx context.Context, params *CardCreateParams) (*Card, error)

Create issues a card. A request_id is generated automatically when params.RequestID is empty, making the call idempotent — a retry never issues two cards.

func (*IssuingCardsService) Limits 

func (s *IssuingCardsService) Limits(ctx context.Context, cardID string) (*CardLimits, error)

Limits fetches a card's spending limits.

func (*IssuingCardsService) List 

func (s *IssuingCardsService) List(ctx context.Context, params *CardListParams) (*Page[Card], error)

List returns one page of cards, filtered by params (may be nil).

func (*IssuingCardsService) Retrieve 

func (s *IssuingCardsService) Retrieve(ctx context.Context, cardID string) (*Card, error)

Retrieve fetches a single card by id.

func (*IssuingCardsService) Update 

func (s *IssuingCardsService) Update(ctx context.Context, cardID string, params *CardCreateParams) (*Card, error)

Update changes a card's mutable details.

type IssuingTransaction 

type IssuingTransaction struct {
	APIResource
	TransactionID   string `json:"transaction_id"`
	TransactionType string `json:"transaction_type"`
	Status          string `json:"status"`

	CardID               string `json:"card_id"`
	CardNickname         string `json:"card_nickname"`
	MaskedCardNumber     string `json:"masked_card_number"`
	DigitalWalletTokenID string `json:"digital_wallet_token_id"`

	TransactionAmount   float64          `json:"transaction_amount"`
	TransactionCurrency string           `json:"transaction_currency"`
	BillingAmount       float64          `json:"billing_amount"`
	BillingCurrency     string           `json:"billing_currency"`
	FeeDetails          []map[string]any `json:"fee_details"`

	Merchant                       map[string]any `json:"merchant"`
	AcquiringInstitutionIdentifier string         `json:"acquiring_institution_identifier"`
	AuthCode                       string         `json:"auth_code"`
	NetworkTransactionID           string         `json:"network_transaction_id"`
	RetrievalRef                   string         `json:"retrieval_ref"`
	LifecycleID                    string         `json:"lifecycle_id"`
	MatchedAuthorizations          []string       `json:"matched_authorizations"`

	RiskDetails   map[string]any `json:"risk_details"`
	FailureReason string         `json:"failure_reason"`
	ClientData    string         `json:"client_data"`

	TransactionDate string `json:"transaction_date"`
	PostedDate      string `json:"posted_date"`
}

IssuingTransaction is a cleared card transaction (/api/v1/issuing/transactions).

type IssuingTransactionListParams 

type IssuingTransactionListParams struct {
	ListParams
	CardID               string `json:"card_id,omitempty"`
	BillingCurrency      string `json:"billing_currency,omitempty"`
	TransactionType      string `json:"transaction_type,omitempty"`
	DigitalWalletTokenID string `json:"digital_wallet_token_id,omitempty"`
	LifecycleID          string `json:"lifecycle_id,omitempty"`
	RetrievalRef         string `json:"retrieval_ref,omitempty"`
	FromCreatedAt        string `json:"from_created_at,omitempty"`
	ToCreatedAt          string `json:"to_created_at,omitempty"`
}

IssuingTransactionListParams filter IssuingTransactionsService.List.

type IssuingTransactionsService 

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

IssuingTransactionsService lists cleared card transactions.

func (*IssuingTransactionsService) All 

func (s *IssuingTransactionsService) All(ctx context.Context, params *IssuingTransactionListParams) iter.Seq2[IssuingTransaction, error]

All iterates every card transaction across every page, fetching lazily.

func (*IssuingTransactionsService) List 

func (s *IssuingTransactionsService) List(ctx context.Context, params *IssuingTransactionListParams) (*Page[IssuingTransaction], error)

List returns one page of card transactions, filtered by params (may be nil).

func (*IssuingTransactionsService) Retrieve 

func (s *IssuingTransactionsService) Retrieve(ctx context.Context, transactionID string) (*IssuingTransaction, error)

Retrieve fetches a single card transaction by id.

type ListParams 

type ListParams struct {
	// PageNum is the 0-based page to start from.
	PageNum int `json:"page_num,omitempty"`
	// PageSize is the number of items per page (server default when 0).
	PageSize int `json:"page_size,omitempty"`
	// ExtraQuery is merged into the query string, for filters this SDK has
	// no typed field for yet.
	ExtraQuery url.Values `json:"-"`
}

ListParams carries pagination fields shared by all list-parameter structs.

type Option 

type Option func(*config)

Option configures a Client created by New.

func WithAPIKey 

func WithAPIKey(apiKey string) Option

WithAPIKey sets the Airwallex API key. Defaults to the AIRWALLEX_API_KEY environment variable.

func WithAPIVersion 

func WithAPIVersion(version string) Option

WithAPIVersion pins an x-api-version header (e.g. "2024-08-07") instead of your account's default API version.

func WithBaseURL 

func WithBaseURL(baseURL string) Option

WithBaseURL overrides the API host entirely (advanced; wins over WithEnv). The URL must use https; plain http is allowed only for loopback hosts.

func WithClientID 

func WithClientID(clientID string) Option

WithClientID sets the Airwallex client id. Defaults to the AIRWALLEX_CLIENT_ID environment variable.

func WithEnv 

func WithEnv(env Environment) Option

WithEnv selects the production or demo (sandbox) environment. The default is Production.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient supplies a custom *http.Client (proxies, custom TLS, ...). The SDK applies the base URL and default headers per request and never mutates or closes the supplied client.

func WithLogger added in v0.2.0 

func WithLogger(logger *slog.Logger) Option

WithLogger enables debug logging of request outcomes, retries, and token refreshes through the given structured logger. Only non-sensitive facts (method, path, status, attempt, request id, delay) are logged — never credentials, tokens, headers, or bodies. Logging is off by default.

func WithMaxRetries 

func WithMaxRetries(maxRetries int) Option

WithMaxRetries sets how many times transient failures (408/429/5xx/network) are retried. The default is 2. Retries reuse the same request_id, so money-moving calls are never executed twice.

func WithOnBehalfOf 

func WithOnBehalfOf(accountID string) Option

WithOnBehalfOf acts on a connected account (sets x-on-behalf-of on every request).

func WithTimeout 

func WithTimeout(timeout time.Duration) Option

WithTimeout sets the per-request timeout for the HTTP client the SDK constructs. It has no effect when WithHTTPClient supplies a custom client — configure the timeout on that client instead.

type Page 

type Page[T any] struct {
	// Items are the results on this page.
	Items []T
	// HasMore reports whether another page follows this one.
	HasMore bool
	// LastResponse describes the HTTP response this page was decoded from.
	LastResponse *ResponseMetadata
	// contains filtered or unexported fields
}

Page is one page of a list endpoint's results, with lazy access to the pages after it. 

page, err := client.Beneficiaries.List(ctx, nil)
for page != nil {
    for _, b := range page.Items { ... }
    if !page.HasMore { break }
    page, err = page.Next(ctx)
}

Or walk every item across every page with All.

func (*Page[T]) All 

func (p *Page[T]) All(ctx context.Context) iter.Seq2[T, error]

All returns an iterator over every item on this page and all following pages, fetching lazily: 

for item, err := range page.All(ctx) {
    if err != nil { ... }
}

func (*Page[T]) Next 

func (p *Page[T]) Next(ctx context.Context) (*Page[T], error)

Next fetches the page after this one. Check HasMore first.

type Params 

type Params struct {
	// ExtraParams is merged into the request body, overriding typed fields
	// on key collision.
	ExtraParams map[string]any `json:"-"`
}

Params carries fields shared by request-parameter structs. Embed values in ExtraParams to send body fields this SDK has no typed field for yet; they are merged into the JSON body on top of the typed fields.

type Payer 

type Payer struct {
	APIResource
	PayerID  string        `json:"payer_id"`
	Nickname string        `json:"nickname"`
	Payer    *PayerDetails `json:"payer"`
}

Payer is a saved payer (/api/v1/payers).

type PayerCreateParams 

type PayerCreateParams struct {
	Params
	Payer    *PayerDetails `json:"payer,omitempty"`
	Nickname string        `json:"nickname,omitempty"`
}

PayerCreateParams are the parameters for PayersService.Create and Update. Note: this endpoint has no request_id — creating twice creates two payers.

type PayerDetails 

type PayerDetails struct {
	EntityType     string         `json:"entity_type,omitempty"`
	CompanyName    string         `json:"company_name,omitempty"`
	FirstName      string         `json:"first_name,omitempty"`
	LastName       string         `json:"last_name,omitempty"`
	DateOfBirth    string         `json:"date_of_birth,omitempty"`
	Address        map[string]any `json:"address,omitempty"`
	AdditionalInfo map[string]any `json:"additional_info,omitempty"`
}

PayerDetails describe who money is sent on behalf of.

type PayerListParams 

type PayerListParams struct {
	ListParams
	EntityType string `json:"entity_type,omitempty"`
	Name       string `json:"name,omitempty"`
	NickName   string `json:"nick_name,omitempty"`
	FromDate   string `json:"from_date,omitempty"`
	ToDate     string `json:"to_date,omitempty"`
}

PayerListParams filter PayersService.List.

type PayersService 

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

PayersService manages the payers money is sent on behalf of.

func (*PayersService) All 

func (s *PayersService) All(ctx context.Context, params *PayerListParams) iter.Seq2[Payer, error]

All iterates every payer across every page, fetching lazily.

func (*PayersService) Create 

func (s *PayersService) Create(ctx context.Context, params *PayerCreateParams) (*Payer, error)

Create saves a new payer.

func (*PayersService) Delete 

func (s *PayersService) Delete(ctx context.Context, payerID string) error

Delete removes a saved payer.

func (*PayersService) List 

func (s *PayersService) List(ctx context.Context, params *PayerListParams) (*Page[Payer], error)

List returns one page of payers, filtered by params (may be nil).

func (*PayersService) Retrieve 

func (s *PayersService) Retrieve(ctx context.Context, payerID string) (*Payer, error)

Retrieve fetches a single payer by id.

func (*PayersService) Update 

func (s *PayersService) Update(ctx context.Context, payerID string, params *PayerCreateParams) (*Payer, error)

Update replaces a payer's details.

func (*PayersService) Validate 

func (s *PayersService) Validate(ctx context.Context, params *PayerCreateParams) (json.RawMessage, error)

Validate validates a payer payload without saving it, returning the raw validation result from Airwallex.

type PaymentIntent 

type PaymentIntent struct {
	APIResource
	ID        string `json:"id"`
	RequestID string `json:"request_id"`
	Status    string `json:"status"`

	Amount         float64 `json:"amount"`
	CapturedAmount float64 `json:"captured_amount"`
	Currency       string  `json:"currency"`

	MerchantOrderID    string `json:"merchant_order_id"`
	InvoiceID          string `json:"invoice_id"`
	PaymentLinkID      string `json:"payment_link_id"`
	ConnectedAccountID string `json:"connected_account_id"`
	ConversionQuoteID  string `json:"conversion_quote_id"`
	Descriptor         string `json:"descriptor"`
	ReturnURL          string `json:"return_url"`
	ClientSecret       string `json:"client_secret"`
	TriggeredBy        string `json:"triggered_by"`

	CustomerID           string         `json:"customer_id"`
	Customer             map[string]any `json:"customer"`
	PaymentConsentID     string         `json:"payment_consent_id"`
	PaymentConsent       map[string]any `json:"payment_consent"`
	PaymentMethodOptions map[string]any `json:"payment_method_options"`
	LatestPaymentAttempt map[string]any `json:"latest_payment_attempt"`
	NextAction           map[string]any `json:"next_action"`

	Order              map[string]any   `json:"order"`
	AdditionalInfo     map[string]any   `json:"additional_info"`
	FundsSplitData     []map[string]any `json:"funds_split_data"`
	RiskControlOptions map[string]any   `json:"risk_control_options"`
	Metadata           map[string]any   `json:"metadata"`

	CancellationReason string `json:"cancellation_reason"`
	CancelledAt        string `json:"cancelled_at"`
	CreatedAt          string `json:"created_at"`
	UpdatedAt          string `json:"updated_at"`
}

PaymentIntent is a payment collected from a shopper (/api/v1/pa/payment_intents).

type PaymentIntentActionParams 

type PaymentIntentActionParams struct {
	Params
	// RequestID makes the action idempotent; auto-generated when empty.
	RequestID          string         `json:"request_id,omitempty"`
	Amount             float64        `json:"amount,omitempty"`
	PaymentMethod      map[string]any `json:"payment_method,omitempty"`
	PaymentConsentRef  map[string]any `json:"payment_consent_reference,omitempty"`
	PaymentMethodOpts  map[string]any `json:"payment_method_options,omitempty"`
	CancellationReason string         `json:"cancellation_reason,omitempty"`
	Type               string         `json:"type,omitempty"`
	ThreeDS            map[string]any `json:"three_ds,omitempty"`
	DeviceData         map[string]any `json:"device_data,omitempty"`
}

PaymentIntentActionParams carry the payload for confirm / continue / capture / cancel actions on a payment intent (e.g. payment_method, payment_consent_reference, amount). Use ExtraParams for fields this SDK has no typed field for.

type PaymentIntentCreateParams 

type PaymentIntentCreateParams struct {
	Params
	// RequestID makes the create idempotent; auto-generated when empty.
	RequestID       string         `json:"request_id,omitempty"`
	Amount          float64        `json:"amount,omitempty"`
	Currency        string         `json:"currency,omitempty"`
	MerchantOrderID string         `json:"merchant_order_id,omitempty"`
	CustomerID      string         `json:"customer_id,omitempty"`
	Descriptor      string         `json:"descriptor,omitempty"`
	ReturnURL       string         `json:"return_url,omitempty"`
	Order           map[string]any `json:"order,omitempty"`
	Metadata        map[string]any `json:"metadata,omitempty"`
}

PaymentIntentCreateParams are the parameters for PaymentIntentsService.Create.

type PaymentIntentListParams 

type PaymentIntentListParams struct {
	ListParams
	Status             string `json:"status,omitempty"`
	Currency           string `json:"currency,omitempty"`
	MerchantOrderID    string `json:"merchant_order_id,omitempty"`
	PaymentConsentID   string `json:"payment_consent_id,omitempty"`
	ConnectedAccountID string `json:"connected_account_id,omitempty"`
	FromCreatedAt      string `json:"from_created_at,omitempty"`
	ToCreatedAt        string `json:"to_created_at,omitempty"`
}

PaymentIntentListParams filter PaymentIntentsService.List.

type PaymentIntentsService 

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

PaymentIntentsService collects payments from shoppers.

func (*PaymentIntentsService) All 

func (s *PaymentIntentsService) All(ctx context.Context, params *PaymentIntentListParams) iter.Seq2[PaymentIntent, error]

All iterates every payment intent across every page, fetching lazily.

func (*PaymentIntentsService) Cancel 

func (s *PaymentIntentsService) Cancel(ctx context.Context, paymentIntentID string, params *PaymentIntentActionParams) (*PaymentIntent, error)

Cancel cancels a payment intent.

func (*PaymentIntentsService) Capture 

func (s *PaymentIntentsService) Capture(ctx context.Context, paymentIntentID string, params *PaymentIntentActionParams) (*PaymentIntent, error)

Capture captures a previously authorized payment intent.

func (*PaymentIntentsService) Confirm 

func (s *PaymentIntentsService) Confirm(ctx context.Context, paymentIntentID string, params *PaymentIntentActionParams) (*PaymentIntent, error)

Confirm confirms a payment intent with a payment method.

func (*PaymentIntentsService) ConfirmContinue 

func (s *PaymentIntentsService) ConfirmContinue(ctx context.Context, paymentIntentID string, params *PaymentIntentActionParams) (*PaymentIntent, error)

ConfirmContinue continues a confirmation that requires further steps (e.g. 3-D Secure).

func (*PaymentIntentsService) Create 

func (s *PaymentIntentsService) Create(ctx context.Context, params *PaymentIntentCreateParams) (*PaymentIntent, error)

Create creates a payment intent. A request_id is generated automatically when params.RequestID is empty, making the call idempotent.

func (*PaymentIntentsService) List 

func (s *PaymentIntentsService) List(ctx context.Context, params *PaymentIntentListParams) (*Page[PaymentIntent], error)

List returns one page of payment intents, filtered by params (may be nil).

func (*PaymentIntentsService) Retrieve 

func (s *PaymentIntentsService) Retrieve(ctx context.Context, paymentIntentID string) (*PaymentIntent, error)

Retrieve fetches a single payment intent by id.

type RateCurrentParams 

type RateCurrentParams struct {
	BuyCurrency    string  `json:"buy_currency,omitempty"`
	SellCurrency   string  `json:"sell_currency,omitempty"`
	BuyAmount      float64 `json:"buy_amount,omitempty"`
	SellAmount     float64 `json:"sell_amount,omitempty"`
	ConversionDate string  `json:"conversion_date,omitempty"`
}

RateCurrentParams are the parameters for RatesService.Current. Specify at most one of BuyAmount / SellAmount; Airwallex defaults to a notional amount of 10,000 when neither is given.

type RateQuote 

type RateQuote struct {
	APIResource
	CurrencyPair         string           `json:"currency_pair"`
	Rate                 float64          `json:"rate"`
	BuyCurrency          string           `json:"buy_currency"`
	BuyAmount            float64          `json:"buy_amount"`
	SellCurrency         string           `json:"sell_currency"`
	SellAmount           float64          `json:"sell_amount"`
	ConversionDate       string           `json:"conversion_date"`
	CreatedAt            string           `json:"created_at"`
	ClientRate           float64          `json:"client_rate"`
	MidRate              float64          `json:"mid_rate"`
	DealtCurrency        string           `json:"dealt_currency"`
	ClientBuyAmount      float64          `json:"client_buy_amount"`
	ClientBuyCurrency    string           `json:"client_buy_currency"`
	ClientSellAmount     float64          `json:"client_sell_amount"`
	ClientSellCurrency   string           `json:"client_sell_currency"`
	SettlementCutoffTime string           `json:"settlement_cutoff_time"`
	SettlementDate       string           `json:"settlement_date"`
	RateDetails          []map[string]any `json:"rate_details"`
}

RateQuote is an indicative FX rate (GET /api/v1/fx/rates/current). No funds move; use FxQuotes to lock a rate.

Current API versions return Rate (with per-level detail in RateDetails); older versions return ClientRate/MidRate. Both are typed here.

type RatesService 

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

RatesService fetches indicative FX rates.

func (*RatesService) Current 

func (s *RatesService) Current(ctx context.Context, params *RateCurrentParams) (*RateQuote, error)

Current gets the current indicative FX rate for a currency pair. No funds move.

type ReferenceService 

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

ReferenceService exposes static reference data.

func (*ReferenceService) InvalidConversionDates 

func (s *ReferenceService) InvalidConversionDates(ctx context.Context, currencyPair string) (json.RawMessage, error)

InvalidConversionDates lists dates on which the given currency pair (e.g. "USDSGD") cannot settle, as the raw JSON reference payload.

func (*ReferenceService) SettlementAccounts 

func (s *ReferenceService) SettlementAccounts(ctx context.Context, params *ReferenceSettlementAccountsParams) (json.RawMessage, error)

SettlementAccounts lists settlement accounts available for the given corridor, as the raw JSON reference payload. params may be nil.

func (*ReferenceService) SupportedCurrencies 

func (s *ReferenceService) SupportedCurrencies(ctx context.Context) (json.RawMessage, error)

SupportedCurrencies lists the currencies Airwallex supports, as the raw JSON reference payload.

type ReferenceSettlementAccountsParams 

type ReferenceSettlementAccountsParams struct {
	CountryCode string `json:"country_code,omitempty"`
	Currency    string `json:"currency,omitempty"`
}

ReferenceSettlementAccountsParams filter ReferenceService.SettlementAccounts.

type Refund 

type Refund struct {
	APIResource
	ID        string `json:"id"`
	RequestID string `json:"request_id"`
	Status    string `json:"status"`

	Amount   float64 `json:"amount"`
	Currency string  `json:"currency"`
	Reason   string  `json:"reason"`

	PaymentIntentID         string `json:"payment_intent_id"`
	PaymentAttemptID        string `json:"payment_attempt_id"`
	AcquirerReferenceNumber string `json:"acquirer_reference_number"`

	FailureDetails map[string]any `json:"failure_details"`
	Metadata       map[string]any `json:"metadata"`

	CreatedAt string `json:"created_at"`
	UpdatedAt string `json:"updated_at"`
}

Refund is a full or partial refund of a payment (/api/v1/pa/refunds).

type RefundCreateParams 

type RefundCreateParams struct {
	Params
	// RequestID makes the create idempotent; auto-generated when empty.
	RequestID        string         `json:"request_id,omitempty"`
	PaymentIntentID  string         `json:"payment_intent_id,omitempty"`
	PaymentAttemptID string         `json:"payment_attempt_id,omitempty"`
	Amount           float64        `json:"amount,omitempty"`
	Reason           string         `json:"reason,omitempty"`
	Metadata         map[string]any `json:"metadata,omitempty"`
}

RefundCreateParams are the parameters for RefundsService.Create.

type RefundListParams 

type RefundListParams struct {
	ListParams
	Status           string `json:"status,omitempty"`
	Currency         string `json:"currency,omitempty"`
	PaymentIntentID  string `json:"payment_intent_id,omitempty"`
	PaymentAttemptID string `json:"payment_attempt_id,omitempty"`
	FromCreatedAt    string `json:"from_created_at,omitempty"`
	ToCreatedAt      string `json:"to_created_at,omitempty"`
}

RefundListParams filter RefundsService.List.

type RefundsService 

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

RefundsService refunds collected payments.

func (*RefundsService) All 

func (s *RefundsService) All(ctx context.Context, params *RefundListParams) iter.Seq2[Refund, error]

All iterates every refund across every page, fetching lazily.

func (*RefundsService) Create 

func (s *RefundsService) Create(ctx context.Context, params *RefundCreateParams) (*Refund, error)

Create creates a refund. A request_id is generated automatically when params.RequestID is empty, making the call idempotent — a retry never refunds twice.

func (*RefundsService) List 

func (s *RefundsService) List(ctx context.Context, params *RefundListParams) (*Page[Refund], error)

List returns one page of refunds, filtered by params (may be nil).

func (*RefundsService) Retrieve 

func (s *RefundsService) Retrieve(ctx context.Context, refundID string) (*Refund, error)

Retrieve fetches a single refund by id.

type ResponseMetadata added in v0.2.0 

type ResponseMetadata struct {
	// StatusCode is the HTTP status code of the response.
	StatusCode int
	// RequestID is the Airwallex x-request-id header.
	RequestID string
	// Header holds the response headers.
	Header http.Header
}

ResponseMetadata describes the HTTP response a resource was decoded from. Use RequestID when contacting Airwallex support about a specific call.

type Settlement 

type Settlement struct {
	APIResource
	ID       string  `json:"id"`
	Currency string  `json:"currency"`
	Amount   float64 `json:"amount"`
	Fee      float64 `json:"fee"`
	Status   string  `json:"status"`

	EstimatedSettledAt string `json:"estimated_settled_at"`
	SettledAt          string `json:"settled_at"`
	CreatedAt          string `json:"created_at"`
}

Settlement is one payment-acceptance settlement (/api/v1/pa/financial/settlements).

type SettlementListParams 

type SettlementListParams struct {
	ListParams
	Currency      string `json:"currency,omitempty"`
	Status        string `json:"status,omitempty"`
	FromSettledAt string `json:"from_settled_at,omitempty"`
	ToSettledAt   string `json:"to_settled_at,omitempty"`
}

SettlementListParams filter SettlementsService.List.

type SettlementsService 

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

SettlementsService lists payment-acceptance settlements.

func (*SettlementsService) All 

func (s *SettlementsService) All(ctx context.Context, params *SettlementListParams) iter.Seq2[Settlement, error]

All iterates every settlement across every page, fetching lazily.

func (*SettlementsService) List 

func (s *SettlementsService) List(ctx context.Context, params *SettlementListParams) (*Page[Settlement], error)

List returns one page of settlements, filtered by params (may be nil).

func (*SettlementsService) Retrieve 

func (s *SettlementsService) Retrieve(ctx context.Context, settlementID string) (*Settlement, error)

Retrieve fetches a single settlement by id.

type SimulationDepositParams 

type SimulationDepositParams struct {
	Params
	Amount          float64 `json:"amount,omitempty"`
	Currency        string  `json:"currency,omitempty"`
	GlobalAccountID string  `json:"global_account_id,omitempty"`
	Reference       string  `json:"reference,omitempty"`
}

SimulationDepositParams are the parameters for SimulationService.CreateDeposit.

type SimulationService 

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

SimulationService drives demo-environment state transitions. Every method only works against the Demo environment.

func (*SimulationService) CreateDeposit 

func (s *SimulationService) CreateDeposit(ctx context.Context, params *SimulationDepositParams) (json.RawMessage, error)

CreateDeposit simulates money arriving in the wallet.

func (*SimulationService) RejectDeposit 

func (s *SimulationService) RejectDeposit(ctx context.Context, depositID string) (json.RawMessage, error)

RejectDeposit moves a simulated deposit to REJECTED.

func (*SimulationService) ReverseDeposit 

func (s *SimulationService) ReverseDeposit(ctx context.Context, depositID string) (json.RawMessage, error)

ReverseDeposit reverses a simulated deposit.

func (*SimulationService) SettleDeposit 

func (s *SimulationService) SettleDeposit(ctx context.Context, depositID string) (json.RawMessage, error)

SettleDeposit moves a simulated deposit to SETTLED.

func (*SimulationService) TransitionPayment 

func (s *SimulationService) TransitionPayment(ctx context.Context, paymentID string, params *SimulationTransitionParams) (json.RawMessage, error)

TransitionPayment moves a simulated payment to its next status.

func (*SimulationService) TransitionTransfer 

func (s *SimulationService) TransitionTransfer(ctx context.Context, transferID string, params *SimulationTransitionParams) (json.RawMessage, error)

TransitionTransfer moves a simulated transfer to its next status.

type SimulationTransitionParams 

type SimulationTransitionParams struct {
	Params
	NextStatus string `json:"next_status,omitempty"`
}

SimulationTransitionParams drive a resource to its next status, e.g. NextStatus: "PAID".

type Transfer 

type Transfer struct {
	APIResource
	ID               string `json:"id"`
	RequestID        string `json:"request_id"`
	Status           string `json:"status"`
	ShortReferenceID string `json:"short_reference_id"`

	SourceAmount     float64 `json:"source_amount"`
	SourceCurrency   string  `json:"source_currency"`
	TransferAmount   float64 `json:"transfer_amount"`
	TransferCurrency string  `json:"transfer_currency"`
	TransferMethod   string  `json:"transfer_method"`
	TransferDate     string  `json:"transfer_date"`

	AmountBeneficiaryReceives float64 `json:"amount_beneficiary_receives"`
	AmountPayerPays           float64 `json:"amount_payer_pays"`
	FeeAmount                 float64 `json:"fee_amount"`
	FeeCurrency               string  `json:"fee_currency"`
	FeePaidBy                 string  `json:"fee_paid_by"`
	SwiftChargeOption         string  `json:"swift_charge_option"`

	Beneficiary   *BeneficiaryDetails `json:"beneficiary"`
	BeneficiaryID string              `json:"beneficiary_id"`
	Payer         map[string]any      `json:"payer"`

	Reference string         `json:"reference"`
	Reason    string         `json:"reason"`
	Remarks   string         `json:"remarks"`
	Metadata  map[string]any `json:"metadata"`

	FailureReason string `json:"failure_reason"`
	FailureType   string `json:"failure_type"`

	CreatedAt string `json:"created_at"`
	UpdatedAt string `json:"updated_at"`
}

Transfer is a payout to a beneficiary (/api/v1/transfers).

type TransferConfirmFundingParams 

type TransferConfirmFundingParams struct {
	Params
	FundingSourceID string `json:"funding_source_id,omitempty"`
}

TransferConfirmFundingParams are the parameters for TransfersService.ConfirmFunding.

type TransferCreateParams 

type TransferCreateParams struct {
	Params
	// RequestID makes the create idempotent; auto-generated when empty.
	RequestID     string              `json:"request_id,omitempty"`
	BeneficiaryID string              `json:"beneficiary_id,omitempty"`
	Beneficiary   *BeneficiaryDetails `json:"beneficiary,omitempty"`
	Payer         map[string]any      `json:"payer,omitempty"`

	SourceCurrency   string  `json:"source_currency,omitempty"`
	SourceAmount     float64 `json:"source_amount,omitempty"`
	TransferAmount   float64 `json:"transfer_amount,omitempty"`
	TransferCurrency string  `json:"transfer_currency,omitempty"`
	TransferMethod   string  `json:"transfer_method,omitempty"`
	TransferDate     string  `json:"transfer_date,omitempty"`

	FeePaidBy         string `json:"fee_paid_by,omitempty"`
	SwiftChargeOption string `json:"swift_charge_option,omitempty"`

	Reference string         `json:"reference,omitempty"`
	Reason    string         `json:"reason,omitempty"`
	Remarks   string         `json:"remarks,omitempty"`
	QuoteID   string         `json:"quote_id,omitempty"`
	Metadata  map[string]any `json:"metadata,omitempty"`
}

TransferCreateParams are the parameters for TransfersService.Create.

type TransferListParams 

type TransferListParams struct {
	ListParams
	Status        string `json:"status,omitempty"`
	Currency      string `json:"currency,omitempty"`
	RequestID     string `json:"request_id,omitempty"`
	FromCreatedAt string `json:"from_created_at,omitempty"`
	ToCreatedAt   string `json:"to_created_at,omitempty"`
}

TransferListParams filter TransfersService.List.

type TransfersService 

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

TransfersService creates and manages payouts to beneficiaries.

Requires an API version of 2024-01-31 or later (earlier versions call this resource "payments"). Use WithAPIVersion if your account default is older.

func (*TransfersService) All 

func (s *TransfersService) All(ctx context.Context, params *TransferListParams) iter.Seq2[Transfer, error]

All iterates every transfer across every page, fetching lazily.

func (*TransfersService) Cancel 

func (s *TransfersService) Cancel(ctx context.Context, transferID string) (*Transfer, error)

Cancel cancels a transfer that has not yet been dispatched.

func (*TransfersService) ConfirmFunding 

func (s *TransfersService) ConfirmFunding(ctx context.Context, transferID string, params *TransferConfirmFundingParams) (*Transfer, error)

ConfirmFunding confirms funding for a transfer that is awaiting funds: once the money has arrived (or you choose the funding source), confirming releases the transfer for processing.

func (*TransfersService) Create 

func (s *TransfersService) Create(ctx context.Context, params *TransferCreateParams) (*Transfer, error)

Create creates a payout. A request_id is generated automatically when params.RequestID is empty, making the call idempotent — Airwallex never executes the same request_id twice, even across the SDK's automatic retries.

Example

Send a payout. RequestID is auto-generated when empty, so the call is idempotent even across the SDK's automatic retries. 

package main

import (
	"context"
	"fmt"
	"log"

	airwallex "github.com/Cyvid7-Darus10/airwallex-go"
)

func main() {
	client, _ := airwallex.New(airwallex.WithEnv(airwallex.Demo))
	transfer, err := client.Transfers.Create(context.Background(), &airwallex.TransferCreateParams{
		BeneficiaryID:    "ben_abc123",
		SourceCurrency:   "USD",
		TransferCurrency: "PHP",
		TransferAmount:   5000,
		TransferMethod:   "LOCAL",
		Reference:        "Invoice 42",
		Reason:           "professional_service_fees",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(transfer.ID, transfer.Status)
}

func (*TransfersService) List 

func (s *TransfersService) List(ctx context.Context, params *TransferListParams) (*Page[Transfer], error)

List returns one page of transfers, filtered by params (which may be nil).

func (*TransfersService) Retrieve 

func (s *TransfersService) Retrieve(ctx context.Context, transferID string) (*Transfer, error)

Retrieve fetches a single transfer by id.

func (*TransfersService) Validate 

func (s *TransfersService) Validate(ctx context.Context, params *TransferCreateParams) (json.RawMessage, error)

Validate validates a transfer payload without creating it, returning the raw validation result from Airwallex. Current API versions require a request_id even to validate, so one is generated when params.RequestID is empty (nothing is executed either way).

type WalletTransfer 

type WalletTransfer struct {
	APIResource
	WalletTransferID string `json:"wallet_transfer_id"`
	RequestID        string `json:"request_id"`
	ShortReferenceID string `json:"short_reference_id"`
	Status           string `json:"status"`

	TransferAmount   float64                    `json:"transfer_amount"`
	TransferCurrency string                     `json:"transfer_currency"`
	Beneficiary      *WalletTransferBeneficiary `json:"beneficiary"`

	Reason    string `json:"reason"`
	Reference string `json:"reference"`

	CreatedAt string `json:"created_at"`
	SettledAt string `json:"settled_at"`
}

WalletTransfer is a transfer between Airwallex wallets (/api/v1/wallet_transfers).

type WalletTransferBeneficiary 

type WalletTransferBeneficiary struct {
	AccountName   string `json:"account_name,omitempty"`
	AccountNumber string `json:"account_number,omitempty"`
}

WalletTransferBeneficiary identifies the receiving wallet.

type WalletTransferCreateParams 

type WalletTransferCreateParams struct {
	Params
	// RequestID makes the create idempotent; auto-generated when empty.
	RequestID        string                     `json:"request_id,omitempty"`
	TransferAmount   float64                    `json:"transfer_amount,omitempty"`
	TransferCurrency string                     `json:"transfer_currency,omitempty"`
	Beneficiary      *WalletTransferBeneficiary `json:"beneficiary,omitempty"`
	Reason           string                     `json:"reason,omitempty"`
	Reference        string                     `json:"reference,omitempty"`
}

WalletTransferCreateParams are the parameters for WalletTransfersService.Create.

type WalletTransferListParams 

type WalletTransferListParams struct {
	ListParams
	Status           string `json:"status,omitempty"`
	TransferCurrency string `json:"transfer_currency,omitempty"`
	RequestID        string `json:"request_id,omitempty"`
	ShortReferenceID string `json:"short_reference_id,omitempty"`
	FromCreatedAt    string `json:"from_created_at,omitempty"`
	ToCreatedAt      string `json:"to_created_at,omitempty"`
}

WalletTransferListParams filter WalletTransfersService.List.

type WalletTransfersService 

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

WalletTransfersService moves money between Airwallex wallets.

func (*WalletTransfersService) All 

func (s *WalletTransfersService) All(ctx context.Context, params *WalletTransferListParams) iter.Seq2[WalletTransfer, error]

All iterates every wallet transfer across every page, fetching lazily.

func (*WalletTransfersService) Create 

func (s *WalletTransfersService) Create(ctx context.Context, params *WalletTransferCreateParams) (*WalletTransfer, error)

Create creates a wallet transfer. A request_id is generated automatically when params.RequestID is empty, making the call idempotent.

func (*WalletTransfersService) List 

func (s *WalletTransfersService) List(ctx context.Context, params *WalletTransferListParams) (*Page[WalletTransfer], error)

List returns one page of wallet transfers, filtered by params (may be nil).

func (*WalletTransfersService) Retrieve 

func (s *WalletTransfersService) Retrieve(ctx context.Context, walletTransferID string) (*WalletTransfer, error)

Retrieve fetches a single wallet transfer by id.

type WebhookEndpoint 

type WebhookEndpoint struct {
	APIResource
	ID        string   `json:"id"`
	RequestID string   `json:"request_id"`
	URL       string   `json:"url"`
	Secret    string   `json:"secret"`
	Version   string   `json:"version"`
	Events    []string `json:"events"`
	Status    string   `json:"status"`
	CreatedAt string   `json:"created_at"`
	UpdatedAt string   `json:"updated_at"`
}

WebhookEndpoint is a webhook subscription (/api/v1/webhooks). Secret is only returned on create — store it to verify signatures with the webhooks package.

type WebhookEndpointCreateParams 

type WebhookEndpointCreateParams struct {
	Params
	// RequestID makes the create idempotent; auto-generated when empty
	// (Create only — Update sends the params as-is).
	RequestID string `json:"request_id,omitempty"`
	// URL is where notifications are delivered.
	URL string `json:"url,omitempty"`
	// Events are the event names to subscribe to (e.g. "transfer.settled").
	Events []string `json:"events,omitempty"`
}

WebhookEndpointCreateParams are the parameters for WebhookEndpointsService.Create and Update.

type WebhookEndpointsService 

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

WebhookEndpointsService manages webhook subscriptions.

func (*WebhookEndpointsService) All 

func (s *WebhookEndpointsService) All(ctx context.Context, params *ListParams) iter.Seq2[WebhookEndpoint, error]

All iterates every webhook endpoint across every page, fetching lazily.

func (*WebhookEndpointsService) Create 

func (s *WebhookEndpointsService) Create(ctx context.Context, params *WebhookEndpointCreateParams) (*WebhookEndpoint, error)

Create registers a webhook endpoint. A request_id is generated automatically when params.RequestID is empty.

func (*WebhookEndpointsService) Delete 

func (s *WebhookEndpointsService) Delete(ctx context.Context, webhookID string) error

Delete removes a webhook endpoint.

func (*WebhookEndpointsService) List 

func (s *WebhookEndpointsService) List(ctx context.Context, params *ListParams) (*Page[WebhookEndpoint], error)

List returns one page of webhook endpoints. params may be nil.

func (*WebhookEndpointsService) Retrieve 

func (s *WebhookEndpointsService) Retrieve(ctx context.Context, webhookID string) (*WebhookEndpoint, error)

Retrieve fetches a single webhook endpoint by id.

func (*WebhookEndpointsService) Update 

func (s *WebhookEndpointsService) Update(ctx context.Context, webhookID string, params *WebhookEndpointCreateParams) (*WebhookEndpoint, error)

Update changes a webhook endpoint's URL or subscribed events.

Source Files

View all Source files

Directories

Path Synopsis
examples
collect-funds command
Command collect-funds demonstrates the receivables flow in the Airwallex demo environment: global accounts, simulated incoming deposits, and the resulting balance and ledger entries.
 Command collect-funds demonstrates the receivables flow in the Airwallex demo environment: global accounts, simulated incoming deposits, and the resulting balance and ledger entries.
fx command
Command fx demonstrates the FX flow against the Airwallex demo environment: indicative rate, lockable quote, and a conversion.
 Command fx demonstrates the FX flow against the Airwallex demo environment: indicative rate, lockable quote, and a conversion.
issuing command
Command issuing demonstrates issuing a virtual card in the Airwallex demo environment: create a cardholder, issue a card, inspect its limits, and list its transactions.
 Command issuing demonstrates issuing a virtual card in the Airwallex demo environment: create a cardholder, issue a card, inspect its limits, and list its transactions.
patterns command
Command patterns demonstrates the SDK's cross-cutting features: typed error handling, response metadata, auto-pagination, debug logging, and the escape hatch for endpoints without typed wrappers.
 Command patterns demonstrates the SDK's cross-cutting features: typed error handling, response metadata, auto-pagination, debug logging, and the escape hatch for endpoints without typed wrappers.
payment-acceptance command
Command payment-acceptance demonstrates collecting a payment in the Airwallex demo environment: create a customer, create a payment intent, and refund it.
 Command payment-acceptance demonstrates collecting a payment in the Airwallex demo environment: create a customer, create a payment intent, and refund it.
payout command
Command payout demonstrates the core payout flow against the Airwallex demo environment: check balances, list beneficiaries, validate, and create a transfer.
 Command payout demonstrates the core payout flow against the Airwallex demo environment: check balances, list beneficiaries, validate, and create a transfer.
webhook-server command
Command webhook-server demonstrates verifying Airwallex webhook signatures in an HTTP handler.
 Command webhook-server demonstrates verifying Airwallex webhook signatures in an HTTP handler.
Package webhooks verifies and parses incoming Airwallex webhook notifications.
 Package webhooks verifies and parses incoming Airwallex webhook notifications.

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.