payments/ce/plugins/generic/client/generated/README.md

Go API client for genericclient

Generic connector API client for Formance Payments. This connector allows integration with any PSP that implements the Generic Connector API specification.

Overview

This API client was generated by the OpenAPI Generator project.

• API version: v0.1
• Package version: latest
• Build package: org.openapitools.codegen.languages.GoClientCodegen

Features

• Account Management: Fetch internal accounts and balances
• Beneficiary Management: Fetch external accounts (beneficiaries)
• Transaction Polling: Fetch and track payment transactions
• Payment Initiation: Create payouts and internal transfers

Installation

Install the following dependencies:

go get github.com/stretchr/testify/assert
go get golang.org/x/net/context

Put the package under your project folder and add the following in import:

import genericclient "github.com/hanzo-fi/payments/genericclient"

Configuration of Server URL

Default configuration comes with Servers field that contains server objects as defined in the OpenAPI specification.

Select Server Configuration

ctx := context.WithValue(context.Background(), genericclient.ContextServerIndex, 1)

Templated Server URL

ctx := context.WithValue(context.Background(), genericclient.ContextServerVariables, map[string]string{
    "basePath": "v2",
})

Documentation for API Endpoints

All URIs are relative to http://localhost

Data Fetching (Read Operations)

Class	Method	HTTP request	Description
DefaultApi	GetAccounts	Get /accounts	Get all internal accounts
DefaultApi	GetAccountBalances	Get /accounts/{accountId}/balances	Get account balances
DefaultApi	GetBeneficiaries	Get /beneficiaries	Get all external accounts
DefaultApi	GetTransactions	Get /transactions	Get all transactions

Payment Initiation (Write Operations)

Class	Method	HTTP request	Description
DefaultApi	CreatePayout	Post /payouts	Create payout to external account
DefaultApi	CreateTransfer	Post /transfers	Create internal transfer

Documentation For Models

Core Models

• Account - Internal account
• Balance - Account balance
• Balances - Account balances container
• Beneficiary - External account (beneficiary)
• Transaction - Payment transaction
• Error - Error response

Payment Initiation Models

• PayoutRequest - Create payout request
• Payout - Payout response
• TransferRequest - Create transfer request
• Transfer - Transfer response

Enums

• TransactionType - PAYIN, PAYOUT, TRANSFER, OTHER
• TransactionStatus - PENDING, SUCCEEDED, FAILED, CANCELLED, and more

Key Concepts

Amount Format

All amounts are in minor units (smallest currency unit):

• "10000" = $100.00 USD
• "1000" = €10.00 EUR
• "100000000" = 1.00000000 BTC

Currency/Asset Format (UMN)

Assets use Universal Monetary Notation:

• "USD/2" - US Dollar with 2 decimal places
• "EUR/2" - Euro with 2 decimal places
• "BTC/8" - Bitcoin with 8 decimal places
• "JPY" or "JPY/0" - Japanese Yen (no decimals)

Payment Adjustments

To link related transactions (refunds, chargebacks), use relatedTransactionID:

{
  "id": "refund_123",
  "relatedTransactionID": "original_payment_456",
  "type": "OTHER",
  "status": "REFUNDED",
  "amount": "5000"
}

Pagination

All list endpoints use page-based pagination:

• page: Page number (1-based)
• pageSize: Items per page (default: 100)
• sort: Sort order (e.g., createdAt:asc)

Formance determines hasMore by checking if len(results) >= pageSize.

Documentation For Authorization

Endpoints do not require authorization. Authentication is configured at the connector level.

Documentation for Utility Methods

This package contains utility functions for obtaining pointers to basic types:

• PtrBool
• PtrInt
• PtrInt32
• PtrInt64
• PtrFloat
• PtrFloat32
• PtrFloat64
• PtrString
• PtrTime

Author

Formance