rapydgo

README

rapyd-go

A production-grade, zero-dependency Go SDK for the Rapyd fintech-as-a-service platform, built with Domain-Driven Design (DDD) architecture.

Covers all 210+ API operations across Rapyd Collect, Disburse, Wallet, Issuing, Partner/PayFac, and Webhooks.

---

Architecture — DDD Layers

rapyd-go/
│
├── domain/                    ← Pure domain entities (no external deps)
│   ├── payment/               Payment, PaymentMethodType, EscrowDetails
│   ├── checkout/              CheckoutPage
│   ├── paymentlink/           PaymentLink
│   ├── grouppayment/          GroupPayment
│   ├── escrow/                EscrowReleaseEntry
│   ├── refund/                Refund
│   ├── dispute/               Dispute
│   ├── customer/              Customer, Plan, Subscription, Invoice, Coupon, Order, SKU
│   ├── payout/                Payout, Beneficiary, Sender, PayoutMethodType
│   ├── wallet/                Wallet, Contact, Account, Transfer, WalletTransaction
│   ├── virtualaccount/        VirtualAccount, BankAccountDetails
│   ├── identity/              IdentityVerification (KYC)
│   ├── card/                  IssuedCard, CardDetails, Transaction, RemoteAuth, CNLS
│   ├── cardtoken/             CardToken (Google/Apple Pay)
│   ├── partner/               Organization, Application, SettlementBankAccount
│   └── webhook/               Event, typed data extractors (PaymentData, RefundData…)
│
├── application/               ← Application services (use-cases, orchestration)
│   ├── collect/               CollectService — all 50+ collect operations
│   ├── disburse/              DisburseService — payouts, beneficiaries, senders
│   ├── wallet/                WalletService — wallets, contacts, transfers, virtual accounts
│   ├── issuing/               IssuingService — cards, tokens, auth, CNLS, simulations
│   ├── partner/               PartnerService — KYB onboarding, organisations, settlement accounts
│   ├── webhook/               WebhookService — verify, parse, Router
│   └── resource/              ResourceService — FX, countries, currencies, POS locations
│
├── infrastructure/            ← Technical infrastructure
│   ├── httpclient/            HTTP transport: signing, retry, response decoding
│   └── signing/               HMAC-SHA256 request + webhook signature
│
├── pkg/                       ← Shared cross-cutting concerns
│   ├── errors/                APIError, WebhookError, ValidationError, sentinels
│   ├── models/                Shared enums, value objects, 60+ WebhookEventType constants
│   └── retry/                 Full-jitter exponential backoff
│
├── config/                    ← SDK configuration
├── rapyd/                     ← Top-level client entry point (rapyd.New)
├── examples/                  ← 12 runnable example functions
└── tests/
    ├── unit/                  ← Signing + errors unit tests
    └── integration/           ← HTTP client + collect + webhook integration tests

---

Features

Feature	Details
Complete API coverage	All 210+ Rapyd operations
DDD architecture	Domain entities separated from application services and infrastructure
HMAC-SHA256 auth	Request + webhook signing per Rapyd spec
Webhook verification	ParseAndVerify + strongly-typed event Router
Full-jitter exponential backoff	Auto-retry on 429/500/502/503/504; never retries 400/401/403/404
Structured errors	*APIError with errors.Is sentinels, card network code extraction
Zero external dependencies	Pure stdlib
Context-first	Every method accepts context.Context
Race-clean	All tests pass with -race

---

Installation

go get github.com/iamkanishka/rapyd-go

Requires Go 1.25.

---

Quick Start

package main

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

    collectapp "github.com/iamkanishka/rapyd-go/application/collect"
    "github.com/iamkanishka/rapyd-go/domain/payment"
    "github.com/iamkanishka/rapyd-go/rapyd"
)

func main() {
    client, err := rapyd.New(rapyd.Config{
        AccessKey: os.Getenv("RAPYD_ACCESS_KEY"),
        SecretKey: os.Getenv("RAPYD_SECRET_KEY"),
        Sandbox:   true,
    })
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // Create a card payment
    p, err := client.Collect.CreatePayment(ctx, &collectapp.CreatePaymentRequest{
        Amount:   100.00,
        Currency: "USD",
        PaymentMethod: &payment.PaymentMethodInput{
            Type: "us_visa_card",
            Fields: map[string]any{
                "number":           "4111111111111111",
                "expiration_month": "12",
                "expiration_year":  "2026",
                "cvv":              "123",
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Payment: %s (%s)\n", p.ID, p.Status)
}

---

API Reference by Domain

Collect — Accept Payments

// Discovery
client.Collect.ListPaymentMethodTypes(ctx, "US", "USD")
client.Collect.GetPaymentMethodRequiredFields(ctx, "us_visa_card")

// Payments
client.Collect.CreatePayment(ctx, req)
client.Collect.UpdatePayment(ctx, id, req)
client.Collect.CapturePayment(ctx, id, req)
client.Collect.GetPayment(ctx, id)
client.Collect.ListPayments(ctx, req)
client.Collect.CancelPayment(ctx, id)

// Checkout
client.Collect.CreateCheckoutPage(ctx, req)  // → RedirectURL

// Payment Links
client.Collect.CreatePaymentLink(ctx, req)
client.Collect.UpdatePaymentLink(ctx, id, req)
client.Collect.DeletePaymentLink(ctx, id)
client.Collect.ListPaymentLinks(ctx)

// Group Payments
client.Collect.CreateGroupPayment(ctx, req)
client.Collect.CancelGroupPayment(ctx, id)
client.Collect.CreateGroupRefund(ctx, gpID, amount)

// Escrow
client.Collect.ReleaseEscrow(ctx, paymentID, escrowID, req)
client.Collect.CancelEscrow(ctx, paymentID, escrowID)

// Refunds
client.Collect.CreateRefund(ctx, req)
client.Collect.GetRefund(ctx, id)
client.Collect.ListRefunds(ctx, req)
client.Collect.CancelRefund(ctx, id)   // Mar 2026

// Disputes
client.Collect.GetDispute(ctx, id)
client.Collect.UpdateDispute(ctx, id, req)
client.Collect.ListDisputes(ctx, limit)

// Customers
client.Collect.CreateCustomer(ctx, req)
client.Collect.UpdateCustomer(ctx, id, req)
client.Collect.GetCustomer(ctx, id)
client.Collect.ListCustomers(ctx, limit)
client.Collect.DeleteCustomer(ctx, id)

// Customer Payment Methods
client.Collect.AddPaymentMethod(ctx, cusID, req)
client.Collect.GetPaymentMethod(ctx, cusID, pmID)
client.Collect.ListPaymentMethods(ctx, cusID)
client.Collect.DeletePaymentMethod(ctx, cusID, pmID)

// Plans, Subscriptions, Invoices, Coupons
client.Collect.CreatePlan(ctx, req) / GetPlan / ListPlans / DeletePlan
client.Collect.CreateSubscription(ctx, req) / GetSubscription / CancelSubscription
client.Collect.CreateInvoice(ctx, req) / FinalizeInvoice / PayInvoice / ListInvoices
client.Collect.CreateCoupon(ctx, req) / GetCoupon / DeleteCoupon
client.Collect.DeleteCustomerDiscount(ctx, cusID)

// Orders, SKUs, Card Tokens, Devices
client.Collect.CreateOrder / PayOrder / ReturnOrder / GetOrder
client.Collect.CreateSKU / GetSKU / DeleteSKU
client.Collect.CreateCardToken / GetCardToken
client.Collect.RegisterPaymentDevice / PairPaymentDevice / GetPaymentDevice / ListPaymentDevices
client.Collect.CreateAddress / GetAddress / DeleteAddress

// Sandbox
client.Collect.CompletePayment(ctx, token, param3)

Disburse — Send Payouts

client.Disburse.ListPayoutMethodTypes(ctx, benefCountry, payoutCurrency, senderCountry)
client.Disburse.GetPayoutRequiredFields(ctx, pmType, senderEntityType, benefEntityType, country, currency)

// Payouts
client.Disburse.CreatePayout(ctx, req)
client.Disburse.ConfirmPayout(ctx, id)          // FX confirmation
client.Disburse.SetPayoutResponse(ctx, req)      // accept/decline wallet payout
client.Disburse.UpdatePayout(ctx, id, req)
client.Disburse.GetPayout(ctx, id)
client.Disburse.ListPayouts(ctx, req)
client.Disburse.CancelPayout(ctx, id)
client.Disburse.CompletePayout(ctx, req)         // sandbox only

// Beneficiaries
client.Disburse.CreateBeneficiary(ctx, req)
client.Disburse.CreateExtendedBeneficiary(ctx, req)
client.Disburse.ValidateBeneficiary(ctx, req)
client.Disburse.UpdateBeneficiary(ctx, id, req)
client.Disburse.GetBeneficiary(ctx, id)
client.Disburse.DeleteBeneficiary(ctx, id)
client.Disburse.CreateBeneficiaryTokenizationPage(ctx, req)

// Senders
client.Disburse.CreateSender(ctx, req)
client.Disburse.UpdateSender(ctx, id, req)
client.Disburse.GetSender(ctx, id)
client.Disburse.DeleteSender(ctx, id)
client.Disburse.UploadPayoutDocument(ctx, payoutID, req)

Wallet — Fund Management

// Wallets
client.Wallet.CreateWallet(ctx, req)
client.Wallet.UpdateWallet(ctx, id, req)
client.Wallet.GetWallet(ctx, id)
client.Wallet.ListWallets(ctx, req)
client.Wallet.ChangeWalletStatus(ctx, req)  // enable/disable/close/delete_never_used
client.Wallet.DeleteWallet(ctx, id)

// Contacts (KYC subjects)
client.Wallet.AddContact(ctx, ewalletID, req)
client.Wallet.UpdateContact(ctx, ewalletID, contactID, req)
client.Wallet.GetContact(ctx, ewalletID, contactID)
client.Wallet.GetComplianceProfile(ctx, ewalletID, contactID)
client.Wallet.ListContacts(ctx, ewalletID)
client.Wallet.DeleteContact(ctx, ewalletID, contactID)

// Transactions & Balances
client.Wallet.TransferFunds(ctx, req)
client.Wallet.SetTransferResponse(ctx, req)
client.Wallet.PutFundsOnHold(ctx, req)
client.Wallet.ReleaseFunds(ctx, req)
client.Wallet.SetAccountLimit(ctx, ewalletID, req)
client.Wallet.DeleteAccountLimit(ctx, ewalletID)
client.Wallet.GetWalletAccounts(ctx, ewalletID)
client.Wallet.ListWalletTransactions(ctx, ewalletID, req)
client.Wallet.GetWalletTransaction(ctx, ewalletID, txnID)

// Virtual Accounts
client.Wallet.IssueVirtualAccount(ctx, req)
client.Wallet.UpdateVirtualAccount(ctx, id, req)
client.Wallet.GetVirtualAccount(ctx, id)
client.Wallet.ListVirtualAccountsByWallet(ctx, ewalletID)
client.Wallet.CloseVirtualAccount(ctx, id)
client.Wallet.SimulateBankTransfer(ctx, req)   // sandbox only

// KYC
client.Wallet.VerifyIdentity(ctx, req)
client.Wallet.GetIdentityVerification(ctx, kycID)

// Sandbox
client.Wallet.AddSandboxFunds(ctx, ewalletID, amount, currency)
client.Wallet.RemoveSandboxFunds(ctx, ewalletID, amount, currency)

Issuing — Card Issuance

// Card lifecycle
client.Issuing.IssueCard(ctx, req)
client.Issuing.ActivateCard(ctx, req)
client.Issuing.UpdateCardStatus(ctx, req)    // block/unblock/lost/stolen
client.Issuing.SetPIN(ctx, req)
client.Issuing.PersonalizeCard(ctx, req)
client.Issuing.GetCard(ctx, id)
client.Issuing.ListCards(ctx, req)
client.Issuing.GetCardStatusHistory(ctx, id)  // Jan 2026

// Display & eligibility
client.Issuing.GetCardDetails(ctx, id)
client.Issuing.GetCardEligibility(ctx, id)
client.Issuing.CreateHostedActivationPage(ctx, req)

// Transactions
client.Issuing.ListCardTransactions(ctx, cardID, req)
client.Issuing.GetCardTransaction(ctx, txnID)

// Digital wallet provisioning
client.Issuing.ProvisionGooglePay(ctx, cardID, req)
client.Issuing.ProvisionApplePay(ctx, cardID, req)
client.Issuing.ListCardTokens(ctx, cardID)
client.Issuing.UpdateCardTokenStatus(ctx, cardID, tokenID, req)

// Remote authorization
client.Issuing.GetRemoteAuthorization(ctx, cardAuthID)
client.Issuing.RespondToRemoteAuth(ctx, req)

// CNLS (PayFac only)
client.Issuing.InitiateCNLSQuery(ctx, req)
client.Issuing.GetCNLSQueryResults(ctx, referenceID)

// Sandbox simulations
client.Issuing.SimulateCardAuth(ctx, req)
client.Issuing.SimulateCardClearing(ctx, req)
client.Issuing.SimulateCardAuthNonEEA(ctx, req)
client.Issuing.SimulateCardClearingNonEEA(ctx, req)
client.Issuing.SimulateBlockCard(ctx, cardID)

Partner / PayFac

client.Partner.ListOfferings(ctx)
client.Partner.CreateOrganization(ctx, req)
client.Partner.GetOrganization(ctx, id)
client.Partner.ListOrganizations(ctx)
client.Partner.GetApplicationTemplate(ctx, country, type)
client.Partner.ListIndustries(ctx)
client.Partner.CreateApplication(ctx, req)
client.Partner.UpdateApplication(ctx, id, req)
client.Partner.UploadDocumentToApplication(ctx, id, req)
client.Partner.SubmitApplication(ctx, id)
client.Partner.GetApplication(ctx, id)
client.Partner.GetApplicationByWallet(ctx, ewalletID)
client.Partner.ApproveApplication(ctx, id)
client.Partner.RejectApplication(ctx, id)
client.Partner.UploadBankVerificationFile(ctx, req)
client.Partner.AddSettlementBankAccount(ctx, req)
client.Partner.UpdateSettlementBankAccount(ctx, id, req)
client.Partner.ListSettlementBankAccounts(ctx, ewalletID)
client.Partner.DeleteSettlementBankAccount(ctx, id)

// Merchant-scoped client
mc := client.Partner.WithMerchantAccountID(org.ID)

Webhooks

// HTTP handler (signature verification + parsing)
event, err := client.Webhook.ParseAndVerify(r, "/webhooks/rapyd")
err = client.Webhook.VerifySignature(path, salt, ts, sig, body)

// Typed event data
data, _ := event.PaymentData()
data, _ := event.RefundData()
data, _ := event.PayoutData()
data, _ := event.WalletData()
data, _ := event.TransferData()
data, _ := event.ContactData()
data, _ := event.VirtualAccountData()
data, _ := event.CardIssuingData()
data, _ := event.DisputeData()
data, _ := event.InvoiceData()

// Event router
router := webhook.NewRouter()
router.
    On(models.WebhookPaymentCompleted, func(e *webhook.Event) error { ... }).
    On(models.WebhookRefundCompleted, handler).
    Default(fallbackHandler)
router.Dispatch(event)

Resource / Utilities

client.Resource.GetFXRate(ctx, rapyd.GetFXRateRequest{BuyCurrency:"USD", SellCurrency:"EUR"})
client.Resource.ListCountries(ctx)
client.Resource.ListCurrencies(ctx)
client.Resource.ListSupportedLanguages(ctx)
client.Resource.ListPOSLocations(ctx, "MX")

---

Error Handling

_, err := client.Collect.CreatePayment(ctx, req)
if err != nil {
    apiErr, ok := rapyderr.AsAPIError(err)
    if ok {
        switch {
        case errors.Is(err, rapyderr.ErrInsufficientFunds):
            // Prompt customer for new payment method
        case errors.Is(err, rapyderr.ErrCardDeclined):
            fmt.Printf("Declined (network code %s)\n", apiErr.CardNetworkCode())
        case errors.Is(err, rapyderr.ErrRateLimit):
            // Back off and retry
        case errors.Is(err, rapyderr.ErrNotFound):
            // Resource missing
        case apiErr.IsRetryable():
            // Transient — safe to retry (500/502/503/504/429)
        default:
            log.Printf("[%s] %s — op_id=%s", apiErr.ErrorCode, apiErr.Message, apiErr.OperationID)
        }
    }
    if errors.Is(err, rapyderr.ErrWebhookSignature) {
        // Reject webhook — possible replay attack
    }
}

All sentinel errors: ErrNotFound · ErrUnauthorized · ErrForbidden · ErrRateLimit · ErrInvalidSignature · ErrIdempotency · ErrInvalidAmount · ErrInsufficientFunds · ErrCardDeclined · ErrInvalidWallet · ErrWebhookSignature

---

Running Tests

go test ./tests/unit/...        # Unit tests (signing, errors)
go test ./tests/integration/... # Integration tests (httpclient, collect, webhook)
go test ./... -race             # All tests with race detector

---

Environment Variables

Variable	Description
RAPYD_ACCESS_KEY	Your Rapyd access key
RAPYD_SECRET_KEY	Your Rapyd secret key

---

License

MIT — see LICENSE.

Author

Kanishka

Documentation

Overview

Package rapydgo is the root package for the rapyd-go module.

rapyd-go is a production-grade, zero-dependency Go SDK for the Rapyd fintech-as-a-service platform, built with Domain-Driven Design (DDD).

Quick Start

client, err := rapyd.New(rapyd.Config{
    AccessKey: os.Getenv("RAPYD_ACCESS_KEY"),
    SecretKey: os.Getenv("RAPYD_SECRET_KEY"),
    Sandbox:   true,
})

Architecture

The package is organized into four DDD layers:

• domain/ — Pure domain entities and value objects (no external deps)
• application/ — Application services orchestrating use-cases
• infrastructure/ — HTTP transport, HMAC signing, retry logic
• pkg/ — Cross-cutting concerns (errors, models, retry)

Entry Point

All interaction starts through [rapyd.New], which returns a [rapyd.Client] containing domain-aligned service groups:

• Client.Collect — Accept payments, refunds, subscriptions, customers
• Client.Disburse — Send payouts to beneficiaries worldwide
• Client.Wallet — Manage wallets, transfers, virtual accounts, KYC
• Client.Issuing — Issue and manage physical and virtual cards
• Client.Partner — PayFac / KYB onboarding for sub-merchants
• Client.Webhook — Verify and route incoming Rapyd webhook events
• Client.Resource — Reference data: FX rates, countries, currencies

Error Handling

All API errors are wrapped in pkg/errors.APIError and support errors.Is matching against sentinel values such as pkg/errors.ErrInsufficientFunds, pkg/errors.ErrCardDeclined, and pkg/errors.ErrRateLimit.

For full documentation, see https://github.com/iamkanishka/rapyd-go

Index

• Constants

Constants

const Version = "1.0.0"

Version is the current SDK version.