The Payments API from Tesser — 7 operation(s) for payments.
openapi: 3.1.0
info:
title: Tesser Accounts Payments API
description: The Tesser Payments Platform API documentation.
version: v1
contact: {}
servers: []
security:
- bearer: []
tags:
- name: Payments
paths:
/v1/payments:
get:
description: Retrieve all payments for the authenticated user's organization.
operationId: payments_getPayments
parameters:
- name: start_date
required: false
in: query
description: Start date for filtering payments (ISO 8601 format)
schema:
type: string
- name: end_date
required: false
in: query
description: End date for filtering payments (ISO 8601 format)
schema:
type: string
- name: direction
required: false
in: query
description: 'Payment direction filter: ''outbound'' for outgoing payments, ''inbound'' for incoming payments'
schema:
type: string
enum:
- outbound
- inbound
- name: page
required: false
in: query
schema:
type: integer
minimum: 1
description: Page number for pagination (1-based)
- name: limit
required: false
in: query
schema:
type: integer
minimum: 1
maximum: 100
description: 'Number of items per page (default: 20)'
responses:
'200':
description: Successfully retrieved team payments
content:
application/json:
schema:
$ref: '#/components/schemas/ListPaymentsResponse'
example:
data:
- id: 5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e
workspace_id: b53f6690-3242-4942-9907-885779632832
organization_reference_id: ref_123
direction: outbound
funding_account_id: 2113b166-5873-42fd-85fe-5b1a02940d43
desired:
from:
account_id: 6de8a7e9-be79-4885-9b65-b25b11d38078
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 53b7aabd-97bc-4a4f-9f9c-1c1c69474889
amount: null
currency: USDC
network: ETHEREUM
estimated:
from:
account_id: 6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e
amount: '10.00'
currency: USDC
network: ETHEREUM
actual:
from:
account_id: 6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e
amount: '10.00'
currency: USDC
network: ETHEREUM
risk_status: automatically_approved
risk_status_reasons: []
risk_reviewed_by: null
risk_reviewed_at: null
balance_status: reserved
balance_reserved_at: '2024-03-01T09:59:00.000Z'
steps:
- id: 4f7c1a9e-2b3d-4e85-b0a6-8d5c2e1f3b9a
payment_id: 5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e
step_sequence: 1
step_type: transfer
estimated:
from:
account_id: 6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e
amount: '10.00'
currency: USDC
network: ETHEREUM
actual:
from:
account_id: 6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e
amount: '10.00'
currency: USDC
network: ETHEREUM
transaction_hash: '0xabc123'
unsigned_transaction: null
fees: []
provider_key: circle_mint
status: completed
status_reasons: []
created_at: '2024-03-01T10:00:00.000Z'
updated_at: '2024-03-01T10:02:30.000Z'
submitted_at: '2024-03-01T10:00:10.000Z'
confirmed_at: '2024-03-01T10:02:00.000Z'
completed_at: '2024-03-01T10:02:30.000Z'
failed_at: null
created_at: '2024-03-01T10:00:00.000Z'
updated_at: '2024-03-01T10:02:30.000Z'
expires_at: '2024-03-04T10:00:00.000Z'
pagination:
page: 1
limit: 20
total: 1
total_pages: 1
has_next: false
has_prev: false
'400':
description: Invalid request data
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
error_code:
type: string
error_message:
type: string
required:
- error_code
- error_message
required:
- errors
example:
errors:
- error_code: counterparties-3001
error_message: 'classification must be one of: individual, business'
- error_code: counterparties-3002
error_message: business_legal_name is required when classification is business
security:
- bearer: []
summary: Get payments
tags:
- Payments
x-zuplo-route:
corsPolicy: anything-goes
handler:
export: forwardToBackend
module: $import(./modules/forward-to-backend)
policies:
inbound:
- set-backend-secret-inbound
- auth0-jwt-auth-inbound
- forward-user-info-inbound
post:
description: Create a payment. Returns the created payment details.
operationId: payments_createPayment
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentRequest'
examples:
default:
summary: Create a standard payment
value:
organization_reference_id: ref_123
funding_account_id: 2113b166-5873-42fd-85fe-5b1a02940d43
desired:
from:
account_id: 6de8a7e9-be79-4885-9b65-b25b11d38078
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 53b7aabd-97bc-4a4f-9f9c-1c1c69474889
currency: USDC
network: ETHEREUM
responses:
'201':
description: Payment created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
example:
data:
id: 9f3b7e1c-4a2d-4f69-b5a8-0c6e2d9f1a3b
workspace_id: b53f6690-3242-4942-9907-885779632832
organization_reference_id: ref_123
direction: outbound
funding_account_id: 2113b166-5873-42fd-85fe-5b1a02940d43
desired:
from:
account_id: 6de8a7e9-be79-4885-9b65-b25b11d38078
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 53b7aabd-97bc-4a4f-9f9c-1c1c69474889
amount: null
currency: USDC
network: ETHEREUM
estimated:
from:
account_id: null
amount: null
currency: null
network: null
to:
account_id: null
amount: null
currency: null
network: null
actual:
from:
account_id: null
amount: null
currency: null
network: null
to:
account_id: null
amount: null
currency: null
network: null
risk_status: unchecked
risk_status_reasons: []
risk_reviewed_by: null
risk_reviewed_at: null
balance_status: unreserved
balance_reserved_at: null
steps: []
created_at: '2024-03-01T10:00:00.000Z'
updated_at: '2024-03-01T10:00:00.000Z'
expires_at: '2024-03-04T10:00:00.000Z'
'400':
description: Invalid request data
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
error_code:
type: string
error_message:
type: string
required:
- error_code
- error_message
required:
- errors
example:
errors:
- error_code: counterparties-3001
error_message: 'classification must be one of: individual, business'
- error_code: counterparties-3002
error_message: business_legal_name is required when classification is business
security:
- bearer: []
summary: Create payment
tags:
- Payments
x-zuplo-route:
corsPolicy: anything-goes
handler:
export: forwardToBackend
module: $import(./modules/forward-to-backend)
policies:
inbound:
- set-backend-secret-inbound
- auth0-jwt-auth-inbound
- forward-user-info-inbound
/v1/payments/internal:
get:
description: Retrieve payments optimized for table display. Returns only fields needed for the payments table UI.
operationId: payments_getPaymentsInternal
parameters:
- name: start_date
required: false
in: query
description: Start date for filtering payments (ISO 8601 format)
schema:
type: string
- name: end_date
required: false
in: query
description: End date for filtering payments (ISO 8601 format)
schema:
type: string
- name: direction
required: false
in: query
description: 'Payment direction filter: ''outbound'' for outgoing payments, ''inbound'' for incoming payments'
schema:
type: string
enum:
- outbound
- inbound
- name: status
required: false
in: query
description: Payment status for filtering payments
schema:
type: string
enum:
- queued
- processing
- ready-to-submit
- rejected
- sent
- need-review
- compliance-blocked
- insufficient-balance
- name: payment_type
required: false
in: query
description: 'Payment type filter: ''deposit'', ''withdrawal'', or ''transfer'''
schema:
type: string
enum:
- deposit
- withdrawal
- transfer
- name: page
required: false
in: query
schema:
type: integer
minimum: 1
description: Page number for pagination (1-based)
- name: limit
required: false
in: query
schema:
type: integer
minimum: 1
maximum: 100
description: 'Number of items per page (default: 20)'
responses:
'200':
description: Successfully retrieved team payments
content:
application/json:
schema:
$ref: '#/components/schemas/InternalPaymentListResponse'
'400':
description: Invalid request data
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
error_code:
type: string
error_message:
type: string
required:
- error_code
- error_message
required:
- errors
example:
errors:
- error_code: counterparties-3001
error_message: 'classification must be one of: individual, business'
- error_code: counterparties-3002
error_message: business_legal_name is required when classification is business
security:
- bearer: []
summary: '[INTERNAL] Get payments for UI table'
tags:
- Payments
x-internal: true
x-zuplo-route:
corsPolicy: anything-goes
handler:
export: forwardToBackend
module: $import(./modules/forward-to-backend)
policies:
inbound:
- set-backend-secret-inbound
- auth0-jwt-auth-inbound
- forward-user-info-inbound
/v1/payments/internal/{paymentId}:
get:
description: Retrieve a single payment with full details including steps and entity data for UI display.
operationId: payments_getPaymentInternal
parameters:
- name: paymentId
required: true
in: path
description: Unique identifier of the payment to retrieve
schema:
type: string
responses:
'400':
description: Invalid request data
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
error_code:
type: string
error_message:
type: string
required:
- error_code
- error_message
required:
- errors
example:
errors:
- error_code: counterparties-3001
error_message: 'classification must be one of: individual, business'
- error_code: counterparties-3002
error_message: business_legal_name is required when classification is business
security:
- bearer: []
summary: '[INTERNAL] Get single payment for UI'
tags:
- Payments
x-internal: true
x-zuplo-route:
corsPolicy: anything-goes
handler:
export: forwardToBackend
module: $import(./modules/forward-to-backend)
policies:
inbound:
- set-backend-secret-inbound
- auth0-jwt-auth-inbound
- forward-user-info-inbound
/v1/payments/simulate-inbound:
post:
description: Sends a real on-chain test-USDC transfer from the platform faucet into a managed wallet and forces the risk-screening verdict to mocked_risk_status. Only available in staging. Returns 201 with the screened payment, or 202 with the tx hash if it is still being detected/screened.
operationId: payments_simulateInbound
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SimulateInboundPaymentRequest'
responses:
'201':
description: The simulated inbound payment, already screened to mocked_risk_status.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
'202':
description: The on-chain transfer was broadcast but the inbound was not detected and screened within the wait budget. Once payment_id is present, poll GET /v1/payments/{paymentId} for the screened payment.
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: object
required:
- tx_hash
- network
- status
- payment_id
properties:
tx_hash:
type: string
network:
type: string
status:
type: string
enum:
- pending
example: pending
payment_id:
type: string
format: uuid
nullable: true
security:
- bearer: []
summary: Simulate an inbound payment with a chosen risk status (staging)
tags:
- Payments
x-zuplo-route:
corsPolicy: anything-goes
handler:
export: forwardToBackend
module: $import(./modules/forward-to-backend)
policies:
inbound:
- set-backend-secret-inbound
- auth0-jwt-auth-inbound
- forward-user-info-inbound
/v1/payments/{paymentId}:
get:
description: Retrieve a specific payment by ID.
operationId: payments_getPaymentById
parameters:
- name: paymentId
required: true
in: path
description: Unique identifier of the payment to retrieve
schema:
type: string
responses:
'200':
description: Successfully retrieved payment
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
example:
data:
id: 5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e
workspace_id: b53f6690-3242-4942-9907-885779632832
organization_reference_id: ref_123
direction: outbound
funding_account_id: 2113b166-5873-42fd-85fe-5b1a02940d43
desired:
from:
account_id: 6de8a7e9-be79-4885-9b65-b25b11d38078
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 53b7aabd-97bc-4a4f-9f9c-1c1c69474889
amount: null
currency: USDC
network: ETHEREUM
estimated:
from:
account_id: 6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e
amount: '10.00'
currency: USDC
network: ETHEREUM
actual:
from:
account_id: 6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e
amount: '10.00'
currency: USDC
network: ETHEREUM
risk_status: automatically_approved
risk_status_reasons: []
risk_reviewed_by: null
risk_reviewed_at: null
balance_status: reserved
balance_reserved_at: '2024-03-01T09:59:00.000Z'
steps:
- id: 4f7c1a9e-2b3d-4e85-b0a6-8d5c2e1f3b9a
payment_id: 5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e
step_sequence: 1
step_type: transfer
estimated:
from:
account_id: 6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e
amount: '10.00'
currency: USDC
network: ETHEREUM
actual:
from:
account_id: 6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e
amount: '10.00'
currency: USDC
network: ETHEREUM
transaction_hash: '0xabc123'
unsigned_transaction: null
fees: []
provider_key: circle_mint
status: completed
status_reasons: []
created_at: '2024-03-01T10:00:00.000Z'
updated_at: '2024-03-01T10:02:30.000Z'
submitted_at: '2024-03-01T10:00:10.000Z'
confirmed_at: '2024-03-01T10:02:00.000Z'
completed_at: '2024-03-01T10:02:30.000Z'
failed_at: null
created_at: '2024-03-01T10:00:00.000Z'
updated_at: '2024-03-01T10:02:30.000Z'
expires_at: '2024-03-04T10:00:00.000Z'
'400':
description: Invalid request data
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
error_code:
type: string
error_message:
type: string
required:
- error_code
- error_message
required:
- errors
example:
errors:
- error_code: counterparties-3001
error_message: 'classification must be one of: individual, business'
- error_code: counterparties-3002
error_message: business_legal_name is required when classification is business
security:
- bearer: []
summary: Get payment by ID
tags:
- Payments
x-zuplo-route:
corsPolicy: anything-goes
handler:
export: forwardToBackend
module: $import(./modules/forward-to-backend)
policies:
inbound:
- set-backend-secret-inbound
- auth0-jwt-auth-inbound
- forward-user-info-inbound
patch:
description: Update a payment with accounts.
operationId: payments_updatePayment
parameters:
- name: paymentId
required: true
in: path
description: Unique identifier of the payment to update
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePaymentRequest'
examples:
default:
summary: Update payment accounts
value:
organization_reference_id: ref_456
funding_account_id: 2113b166-5873-42fd-85fe-5b1a02940d43
desired:
from:
account_id: 6de8a7e9-be79-4885-9b65-b25b11d38078
to:
account_id: 53b7aabd-97bc-4a4f-9f9c-1c1c69474889
responses:
'200':
description: Payment updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
example:
data:
id: 5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e
workspace_id: b53f6690-3242-4942-9907-885779632832
organization_reference_id: ref_456
direction: outbound
funding_account_id: 2113b166-5873-42fd-85fe-5b1a02940d43
desired:
from:
account_id: 6de8a7e9-be79-4885-9b65-b25b11d38078
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 53b7aabd-97bc-4a4f-9f9c-1c1c69474889
amount: null
currency: USDC
network: ETHEREUM
estimated:
from:
account_id: 6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e
amount: '10.00'
currency: USDC
network: ETHEREUM
actual:
from:
account_id: 6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e
amount: '10.00'
currency: USDC
network: ETHEREUM
risk_status: automatically_approved
risk_status_reasons: []
risk_reviewed_by: null
risk_reviewed_at: null
balance_status: reserved
balance_reserved_at: '2024-03-01T09:59:00.000Z'
steps:
- id: 4f7c1a9e-2b3d-4e85-b0a6-8d5c2e1f3b9a
payment_id: 5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e
step_sequence: 1
step_type: transfer
estimated:
from:
account_id: 6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e
amount: '10.00'
currency: USDC
network: ETHEREUM
actual:
from:
account_id: 6c1e9a4f-3b8d-4f72-a0e5-7d2c1b9f3a8e
amount: '10.00'
currency: USDC
network: ETHEREUM
to:
account_id: 8e2c6a9f-1b4d-4f83-a5e7-3d0c9b1f2a6e
amount: '10.00'
currency: USDC
network: ETHEREUM
transaction_hash: '0xabc123'
unsigned_transaction: null
fees: []
provider_key: circle_mint
status: completed
status_reasons: []
created_at: '2024-03-01T10:00:00.000Z'
updated_at: '2024-03-01T10:02:30.000Z'
submitted_at: '2024-03-01T10:00:10.000Z'
confirmed_at: '2024-03-01T10:02:00.000Z'
completed_at: '2024-03-01T10:02:30.000Z'
failed_at: null
created_at: '2024-03-01T10:00:00.000Z'
updated_at: '2024-03-05T09:00:00.000Z'
expires_at: '2024-03-04T10:00:00.000Z'
'400':
description: Invalid request data
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
error_code:
type: string
error_message:
type: string
required:
- error_code
- error_message
required:
- errors
example:
errors:
- error_code: counterparties-3001
error_message: 'classification must be one of: individual, business'
- error_code: counterparties-3002
error_message: business_legal_name is required when classification is business
security:
- bearer: []
summary: Update payment
tags:
- Payments
x-zuplo-route:
corsPolicy: anything-goes
handler:
export: forwardToBackend
module: $import(./modules/forward-to-backend)
policies:
inbound:
- set-backend-secret-inbound
- auth0-jwt-auth-inbound
- forward-user-info-inbound
/v1/payments/{paymentId}/review:
post:
description: Manually review and approve or reject a payment requiring risk review.
operationId: payments_reviewPayment
parameters:
- name: paymentId
required: true
in: path
description: Unique identifier of the payment to review
schema:
format: uuid
example: 5a9c3e7f-2b1d-4f48-a6e0-8c4b2d1f9a3e
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ReviewPaymentRequest'
examples:
default:
summary: Approve payment
value:
is_approved: true
responses:
'200':
description: Payment review completed successfully
content:
application/json:
schema:
# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tesser/refs/heads/main/openapi/tesser-payments-api-openapi.yml