mirror of
https://github.com/hanzo-fi/payments.git
synced 2026-10-30 20:31:20 +00:00
CrimsonandGitHub
61cae8af0a
* Move all public connectors to ce/plugins * Update tooling to account for new go modules under ce * Ensure we test all CE plugins in CI * Move Dummypay to ce/plugins for simplicity's sake in the generation scripts * Use versioned pkg/domain in plugins * Ensure that renovate updates all CE plugins in a single PR when pkg/domain tags are pushed to github * Ensure Justfile commands work over all CE plugins * Copy ce plugin go.mods in dev.Dockerfile * Only add a go.mod for new plugins if they are ce * Ensure generated generic client structs are named correctly for submodule * Add coverprofile for each ce plugin * Add set -e for Justfile for loops over plugins * Infer go version from flake.nix in connector template tool
538 lines
14 KiB
YAML
538 lines
14 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: GENERIC connector API
|
|
version: "v0.1"
|
|
|
|
# ---------------------- PATHS ----------------------
|
|
paths:
|
|
/accounts:
|
|
get:
|
|
summary: Get all accounts
|
|
operationId: getAccounts
|
|
parameters:
|
|
- $ref: '#/components/parameters/PageSize'
|
|
- $ref: '#/components/parameters/Page'
|
|
- $ref: '#/components/parameters/Sort'
|
|
- $ref: '#/components/parameters/CreatedAtFrom'
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/Accounts'
|
|
default:
|
|
$ref: '#/components/responses/ErrorResponse'
|
|
|
|
/accounts/{accountId}/balances:
|
|
get:
|
|
summary: Get account balance
|
|
operationId: getAccountBalances
|
|
parameters:
|
|
- $ref: '#/components/parameters/AccountId'
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/Balances'
|
|
default:
|
|
$ref: '#/components/responses/ErrorResponse'
|
|
|
|
/beneficiaries:
|
|
get:
|
|
summary: Get all beneficiaries
|
|
operationId: getBeneficiaries
|
|
parameters:
|
|
- $ref: '#/components/parameters/PageSize'
|
|
- $ref: '#/components/parameters/Page'
|
|
- $ref: '#/components/parameters/Sort'
|
|
- $ref: '#/components/parameters/CreatedAtFrom'
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/Beneficiaries'
|
|
default:
|
|
$ref: '#/components/responses/ErrorResponse'
|
|
|
|
/transactions:
|
|
get:
|
|
summary: Get all transactions
|
|
operationId: getTransactions
|
|
parameters:
|
|
- $ref: '#/components/parameters/PageSize'
|
|
- $ref: '#/components/parameters/Page'
|
|
- $ref: '#/components/parameters/Sort'
|
|
- $ref: '#/components/parameters/UpdatedAtFrom'
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/Transactions'
|
|
default:
|
|
$ref: '#/components/responses/ErrorResponse'
|
|
|
|
/payouts:
|
|
post:
|
|
summary: Create payout
|
|
operationId: createPayout
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PayoutRequest'
|
|
responses:
|
|
201:
|
|
$ref: '#/components/responses/PayoutResponse'
|
|
default:
|
|
$ref: '#/components/responses/ErrorResponse'
|
|
|
|
/transfers:
|
|
post:
|
|
summary: Create transfer
|
|
description: |
|
|
Create an internal transfer between two accounts.
|
|
The idempotencyKey should be used to prevent duplicate transfers on retries.
|
|
operationId: createTransfer
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TransferRequest'
|
|
responses:
|
|
201:
|
|
$ref: '#/components/responses/TransferResponse'
|
|
default:
|
|
$ref: '#/components/responses/ErrorResponse'
|
|
|
|
# ---------------------- COMPONENTS ----------------------
|
|
components:
|
|
# ---------------------- PARAMETERS ----------------------
|
|
parameters:
|
|
AccountId:
|
|
name: accountId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
PageSize:
|
|
name: pageSize
|
|
in: query
|
|
description: Number of items per page
|
|
example: 100
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
minimum: 1
|
|
default: 100
|
|
Page:
|
|
name: page
|
|
in: query
|
|
description: Page number
|
|
example: 1
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
minimum: 1
|
|
default: 1
|
|
Sort:
|
|
name: sort
|
|
in: query
|
|
description: Sort order
|
|
example: createdAt:asc
|
|
schema:
|
|
type: string
|
|
CreatedAtFrom:
|
|
name: createdAtFrom
|
|
in: query
|
|
description: Filter by created at date
|
|
schema:
|
|
type: string
|
|
format: date-time
|
|
UpdatedAtFrom:
|
|
name: updatedAtFrom
|
|
in: query
|
|
description: Filter by updated at date
|
|
schema:
|
|
type: string
|
|
format: date-time
|
|
|
|
# ---------------------- RESPONSES ----------------------
|
|
responses:
|
|
NoContent:
|
|
description: No content
|
|
|
|
ErrorResponse:
|
|
description: General error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
Accounts:
|
|
description: List of accounts
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Account'
|
|
|
|
Balances:
|
|
description: Account balances
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Balances'
|
|
|
|
Beneficiaries:
|
|
description: List of beneficiaries
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Beneficiary'
|
|
|
|
Transactions:
|
|
description: List of transactions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Transaction'
|
|
|
|
PayoutResponse:
|
|
description: Payout response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Payout'
|
|
|
|
TransferResponse:
|
|
description: Transfer response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Transfer'
|
|
|
|
# ---------------------- SCHEMAS ----------------------
|
|
schemas:
|
|
Error:
|
|
type: object
|
|
required:
|
|
- Title
|
|
- Detail
|
|
properties:
|
|
Title:
|
|
type: string
|
|
Detail:
|
|
type: string
|
|
|
|
Account:
|
|
type: object
|
|
required:
|
|
- id
|
|
- accountName
|
|
- createdAt
|
|
properties:
|
|
id:
|
|
type: string
|
|
accountName:
|
|
type: string
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
metadata:
|
|
$ref: '#/components/schemas/Metadata'
|
|
|
|
Balances:
|
|
type: object
|
|
required:
|
|
- id
|
|
- accountID
|
|
- at
|
|
- balances
|
|
properties:
|
|
id:
|
|
type: string
|
|
accountID:
|
|
type: string
|
|
at:
|
|
type: string
|
|
format: date-time
|
|
balances:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Balance'
|
|
|
|
Balance:
|
|
type: object
|
|
required:
|
|
- amount
|
|
- currency
|
|
properties:
|
|
amount:
|
|
type: string
|
|
description: Amount in minor units (integer string)
|
|
currency:
|
|
type: string
|
|
description: Asset in UMN format with optional precision (e.g., "USD/2", "BTC/8", "COIN", "JPY")
|
|
|
|
Beneficiary:
|
|
type: object
|
|
required:
|
|
- id
|
|
- createdAt
|
|
- ownerName
|
|
properties:
|
|
id:
|
|
type: string
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
ownerName:
|
|
type: string
|
|
metadata:
|
|
$ref: '#/components/schemas/Metadata'
|
|
|
|
|
|
Transaction:
|
|
type: object
|
|
required:
|
|
- id
|
|
- createdAt
|
|
- updatedAt
|
|
- currency
|
|
- type
|
|
- status
|
|
- amount
|
|
properties:
|
|
id:
|
|
type: string
|
|
relatedTransactionID:
|
|
type: string
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
updatedAt:
|
|
type: string
|
|
format: date-time
|
|
currency:
|
|
type: string
|
|
description: Asset in UMN format with optional precision (e.g., "USD/2", "BTC/8", "COIN", "JPY")
|
|
scheme:
|
|
type: string
|
|
type:
|
|
$ref: '#/components/schemas/TransactionType'
|
|
status:
|
|
$ref: '#/components/schemas/TransactionStatus'
|
|
amount:
|
|
type: string
|
|
description: Amount in minor units (integer string)
|
|
sourceAccountID:
|
|
type: string
|
|
destinationAccountID:
|
|
type: string
|
|
metadata:
|
|
$ref: '#/components/schemas/Metadata'
|
|
|
|
Metadata:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
nullable: true
|
|
|
|
TransactionType:
|
|
type: string
|
|
description: |
|
|
Payment/transaction type. Core types are mapped to Formance payment types:
|
|
- PAYIN: Incoming payment (maps to PAY-IN)
|
|
- PAYOUT: Outgoing payment to external account (maps to PAYOUT)
|
|
- TRANSFER: Internal transfer between accounts (maps to TRANSFER)
|
|
- OTHER: Any other transaction type (maps to OTHER)
|
|
enum:
|
|
- PAYIN
|
|
- PAYOUT
|
|
- TRANSFER
|
|
- OTHER
|
|
|
|
TransactionStatus:
|
|
type: string
|
|
description: |
|
|
Payment/transaction status. Mapped to Formance payment statuses:
|
|
- PENDING: Payment is awaiting processing
|
|
- SUCCEEDED: Payment completed successfully
|
|
- FAILED: Payment failed
|
|
- CANCELLED: Payment was cancelled
|
|
- EXPIRED: Payment expired
|
|
- REFUNDED: Payment was refunded
|
|
- REFUNDED_FAILURE: Refund attempt failed
|
|
- REFUND_REVERSED: Refund was reversed
|
|
- DISPUTE: Payment is under dispute
|
|
- DISPUTE_WON: Dispute resolved in merchant's favor
|
|
- DISPUTE_LOST: Dispute resolved against merchant
|
|
- AUTHORISATION: Payment authorized but not captured
|
|
- CAPTURE: Payment captured
|
|
- CAPTURE_FAILED: Capture attempt failed
|
|
- OTHER: Other/unknown status
|
|
enum:
|
|
- PENDING
|
|
- SUCCEEDED
|
|
- FAILED
|
|
- CANCELLED
|
|
- EXPIRED
|
|
- REFUNDED
|
|
- REFUNDED_FAILURE
|
|
- REFUND_REVERSED
|
|
- DISPUTE
|
|
- DISPUTE_WON
|
|
- DISPUTE_LOST
|
|
- AUTHORISATION
|
|
- CAPTURE
|
|
- CAPTURE_FAILED
|
|
- OTHER
|
|
|
|
PayoutRequest:
|
|
type: object
|
|
required:
|
|
- idempotencyKey
|
|
- amount
|
|
- currency
|
|
- sourceAccountId
|
|
- destinationAccountId
|
|
properties:
|
|
idempotencyKey:
|
|
type: string
|
|
description: Unique identifier for the payout request
|
|
amount:
|
|
type: string
|
|
description: Payout amount in minor units (integer string)
|
|
currency:
|
|
type: string
|
|
description: Asset in UMN format (e.g., "USD/2", "BTC/8")
|
|
sourceAccountId:
|
|
type: string
|
|
description: Source account identifier
|
|
destinationAccountId:
|
|
type: string
|
|
description: Destination account identifier
|
|
description:
|
|
type: string
|
|
description: Payout description
|
|
metadata:
|
|
$ref: '#/components/schemas/Metadata'
|
|
|
|
Payout:
|
|
type: object
|
|
required:
|
|
- id
|
|
- idempotencyKey
|
|
- amount
|
|
- currency
|
|
- sourceAccountId
|
|
- destinationAccountId
|
|
- status
|
|
- createdAt
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Payout identifier
|
|
idempotencyKey:
|
|
type: string
|
|
description: Unique identifier for the payout request
|
|
amount:
|
|
type: string
|
|
description: Payout amount in minor units (integer string)
|
|
currency:
|
|
type: string
|
|
description: Asset in UMN format (e.g., "USD/2", "BTC/8")
|
|
sourceAccountId:
|
|
type: string
|
|
description: Source account identifier
|
|
destinationAccountId:
|
|
type: string
|
|
description: Destination account identifier
|
|
description:
|
|
type: string
|
|
description: Payout description
|
|
status:
|
|
$ref: '#/components/schemas/TransactionStatus'
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
updatedAt:
|
|
type: string
|
|
format: date-time
|
|
metadata:
|
|
$ref: '#/components/schemas/Metadata'
|
|
|
|
TransferRequest:
|
|
type: object
|
|
required:
|
|
- idempotencyKey
|
|
- amount
|
|
- currency
|
|
- sourceAccountId
|
|
- destinationAccountId
|
|
properties:
|
|
idempotencyKey:
|
|
type: string
|
|
description: |
|
|
Client-provided unique identifier for this transfer request.
|
|
Used for idempotency - if a transfer with this key already exists, return the existing transfer.
|
|
amount:
|
|
type: string
|
|
description: Transfer amount in minor units (integer string)
|
|
currency:
|
|
type: string
|
|
description: Asset in UMN format (e.g., "USD/2", "BTC/8")
|
|
sourceAccountId:
|
|
type: string
|
|
description: Source account identifier (internal account)
|
|
destinationAccountId:
|
|
type: string
|
|
description: Destination account identifier (internal account)
|
|
description:
|
|
type: string
|
|
description: Transfer description/memo
|
|
metadata:
|
|
$ref: '#/components/schemas/Metadata'
|
|
|
|
Transfer:
|
|
type: object
|
|
required:
|
|
- id
|
|
- idempotencyKey
|
|
- amount
|
|
- currency
|
|
- sourceAccountId
|
|
- destinationAccountId
|
|
- status
|
|
- createdAt
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: PSP-generated unique transfer identifier
|
|
idempotencyKey:
|
|
type: string
|
|
description: Client-provided unique identifier for this transfer request
|
|
amount:
|
|
type: string
|
|
description: Transfer amount in minor units (integer string)
|
|
currency:
|
|
type: string
|
|
description: Asset in UMN format (e.g., "USD/2", "BTC/8")
|
|
sourceAccountId:
|
|
type: string
|
|
description: Source account identifier
|
|
destinationAccountId:
|
|
type: string
|
|
description: Destination account identifier
|
|
description:
|
|
type: string
|
|
description: Transfer description
|
|
status:
|
|
$ref: '#/components/schemas/TransactionStatus'
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
updatedAt:
|
|
type: string
|
|
format: date-time
|
|
metadata:
|
|
$ref: '#/components/schemas/Metadata'
|