/admin/payments

Path: /admin/payments
Namespace: admin
Resource: payments

Overview

The Payment resource represents financial transactions recording payments against invoices and transactions. Payments support multiple payment methods, currency conversion, authorization workflows, and links to accounting transactions.

Relationships

Model Associations

Payment connects to the following resources:

Invoice

Type: belongs_to via invoice_id
Field: invoice_id
Description: Invoice being paid. Each payment is associated with an invoice.
Reverse: Invoice has many payments (invoice.payments)
API Access:
- Direct: Included in payment response as invoice_id
- Filter: GET /admin/payments.json?q[invoice_id_eq]=123
- Nested: GET /admin/invoices/:id/payments.json (payments for an invoice)
Related Documentation: Invoices

Example: Get all payments for an invoice:

javascript

const payments = await fetch('/admin/invoices/123/payments.json', {
  credentials: 'include',
  headers: { 'Accept': 'application/json' }
}).then(r => r.json());

Address (Multiple Roles)

Type: belongs_to via sender_id and receiver_id
Fields: sender_id, receiver_id
Description: Addresses involved in the payment transaction (sender and receiver).
Roles:
- sender_id - Address sending payment (payer)
- receiver_id - Address receiving payment (payee)
Reverse: Address has many payments:
- payments_sent - Payments sent by this address
- payments_received - Payments received by this address
API Access:
- Direct: payment.sender_id, payment.receiver_id
- Filter:
  - GET /admin/payments.json?q[sender_id_eq]=123
  - GET /admin/payments.json?q[receiver_id_eq]=123
- Nested:
  - GET /admin/addresses/:id/payments_sent.json - Payments sent by address
  - GET /admin/addresses/:id/payments_received.json - Payments received by address
Related Documentation: Addresses

Example: Get all payments sent by an address:

javascript

const paymentsSent = await fetch('/admin/addresses/123/payments_sent.json', {
  credentials: 'include',
  headers: { 'Accept': 'application/json' }
}).then(r => r.json());

User

Type: belongs_to via authorized_by_id (optional)
Field: authorized_by_id
Description: User who authorized the payment. Tracks authorization workflow.
Reverse: User has many payments (user.payments_authorized)
API Access:
- Direct: payment.authorized_by_id (may be null)
- Filter: GET /admin/payments.json?q[authorized_by_id_eq]=1
Related Documentation: Users

Domain

Type: belongs_to via host_id
Field: host_id
Description: Tenant domain for multi-tenant scoping. All payments belong to a domain.
Reverse: Domain has many payments (domain.payments)
API Access:
- Direct: Included in payment response as host_id
- Filter: GET /admin/payments.json?q[host_id_eq]=1
Related Documentation: Domains

PaymentMethod

Type: belongs_to via payment_method_id (optional)
Field: payment_method_id
Description: Payment method used for this payment (credit card, bank transfer, etc.).
Reverse: PaymentMethod has many payments (payment_method.payments)
API Access:
- Direct: payment.payment_method_id (may be null)
- Filter: GET /admin/payments.json?q[payment_method_id_eq]=1
Related Documentation: Addresses - Payment Methods

Reverse Associations

The following resources connect to Payment:

AccountingTransaction[]

Type: has_many on AccountingTransaction via payment_id or polymorphic association
Description: Accounting transactions created from payments. Links payments to accounting entries.
API Access:
- Filter: GET /admin/accounting_transactions.json?q[payment_id_eq]=123
Related Documentation: Accounting

Relationship Patterns

Creating Payment for Invoice

Use Case: Record a payment against an invoice

Example:

javascript

const payment = await fetch('/admin/payments.json', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    payment: {
      invoice_id: 123,
      sender_id: 2, // Buyer address
      receiver_id: 1, // Seller address
      amount_cents: 100000,
      currency_code: 'USD',
      payment_method_id: 1,
      date: '2024-01-15',
      authorized: true
    }
  })
}).then(r => r.json());

Creating Payment via Invoice (Nested)

Use Case: Create a payment directly through the invoice endpoint

Example:

javascript

const payment = await fetch('/admin/invoices/123/create_payment', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    payment: {
      amount_cents: 100000,
      payment_method_id: 1,
      date: '2024-01-15'
    }
  })
}).then(r => r.json());

Filtering Payments by Address

Use Case: Get all payments where a specific address is sender or receiver

Example: Get all payments sent by an address:

javascript

const paymentsSent = await fetch('/admin/payments.json?q[sender_id_eq]=123', {
  credentials: 'include',
  headers: { 'Accept': 'application/json' }
}).then(r => r.json());

Accessing Invoice Payments

Use Case: Get all payments for a specific invoice

Example: Via nested endpoint:

javascript

const invoicePayments = await fetch('/admin/invoices/123/invoice_payments.json', {
  credentials: 'include',
  headers: { 'Accept': 'application/json' }
}).then(r => r.json());

Key Features

Invoice Association: Payments are associated with invoices
Payment Method Tracking: Support for multiple payment methods
Authorization Tracking: Track payment authorization status
Amount and Currency Management: Multi-currency support with amounts
Accounting Integration: Links to AccountingTransactions
Nested Resources: Invoice payments are nested under invoices

Available Operations

List Payments (GET)

Endpoint: GET /admin/payments.json

Query Parameters:

q[field_predicate]=value - Ransack query filters for advanced filtering
page=N - Page number for pagination
per_page=N - Items per page (default: 25)

Request Examples:

bash

curl -X GET "https://your-company.erpax.com/admin/payments.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

bash

curl -X GET "https://your-company.erpax.com/admin/payments.json?q[invoice_id_eq]=123" \
  -H "Accept: application/json"

bash

curl -X GET "https://your-company.erpax.com/admin/payments.json?q[date_gteq]=2024-01-01&q[date_lteq]=2024-12-31" \
  -H "Accept: application/json"

bash

curl -X GET "https://your-company.erpax.com/admin/payments.json?q[currency_code_eq]=USD&page=1&per_page=25" \
  -H "Accept: application/json"

JavaScript Example:

javascript

const response = await fetch('/admin/payments.json', {
  credentials: 'include',
  headers: { 'Accept': 'application/json' }
});
const data = await response.json();

Response (200 OK):

json

{
  "payments": [
    {
      "id": 1,
      "invoice_id": 123,
      "amount_cents": 100000,
      "amount": "1000.00",
      "currency_code": "USD",
      "payment_method": "Credit Card",
      "date": "2024-01-15",
      "authorized": true,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 2,
    "total_count": 45
  }
}

Show Payment (GET /:id)

Endpoint: GET /admin/payments/:id.json

Request Example:

bash

curl -X GET "https://your-company.erpax.com/admin/payments/1.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

JavaScript Example:

javascript

const response = await fetch('/admin/payments/1.json', {
  credentials: 'include',
  headers: { 'Accept': 'application/json' }
});
const payment = await response.json();

Response (200 OK):

json

{
  "payment": {
    "id": 1,
    "invoice_id": 123,
    "sender_id": 1,
    "receiver_id": 2,
    "amount_cents": 100000,
    "invoice_amount_cents": 100000,
    "currency_code": "USD",
    "payment_method": "Credit Card",
    "date": "2024-01-15",
    "sent_at": "2024-01-15T10:00:00Z",
    "received_at": "2024-01-15T10:05:00Z",
    "authorized": true,
    "authorized_by_id": 1,
    "created_at": "2024-01-15T10:00:00Z"
  }
}

Create Payment (POST)

Endpoint: POST /admin/payments.json

Request Example:

bash

curl -X POST "https://your-company.erpax.com/admin/payments.json" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie" \
  -d '{
    "payment": {
      "invoice_id": 123,
      "amount_cents": 100000,
      "currency_code": "USD",
      "payment_method": "Credit Card",
      "date": "2024-01-15",
      "authorized": true
    }
  }'

JavaScript Example:

javascript

const response = await fetch('/admin/payments.json', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    payment: {
      invoice_id: 123,
      amount_cents: 100000,
      currency_code: 'USD',
      payment_method: 'Credit Card',
      date: '2024-01-15',
      authorized: true
    }
  })
});
const payment = await response.json();

Response (201 Created):

json

{
  "payment": {
    "id": 1,
    "invoice_id": 123,
    "amount_cents": 100000,
    "currency_code": "USD",
    "payment_method": "Credit Card",
    "date": "2024-01-15",
    "authorized": true,
    "created_at": "2024-01-15T14:30:00Z"
  }
}

Response (422 Unprocessable Entity):

json

{
  "errors": {
    "invoice_id": ["can't be blank"],
    "amount_cents": ["must be greater than 0"]
  }
}

Update Payment (PATCH /:id)

Endpoint: PATCH /admin/payments/:id.json

Request Example:

bash

curl -X PATCH "https://your-company.erpax.com/admin/payments/1.json" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie" \
  -d '{
    "payment": {
      "authorized": true,
      "received_at": "2024-01-15T11:00:00Z"
    }
  }'

JavaScript Example:

javascript

const response = await fetch('/admin/payments/1.json', {
  method: 'PATCH',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    payment: {
      authorized: true,
      received_at: '2024-01-15T11:00:00Z'
    }
  })
});
const payment = await response.json();

Response (200 OK):

json

{
  "payment": {
    "id": 1,
    "authorized": true,
    "received_at": "2024-01-15T11:00:00Z",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}

Delete Payment (DELETE /:id)

Endpoint: DELETE /admin/payments/:id.json

Request Example:

bash

curl -X DELETE "https://your-company.erpax.com/admin/payments/1.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

JavaScript Example:

javascript

const response = await fetch('/admin/payments/1.json', {
  method: 'DELETE',
  credentials: 'include',
  headers: { 'Accept': 'application/json' }
});

Response (204 No Content):

(empty response)

Scopes

No custom scopes are configured (uses default 'all' scope).

Filters

Available filters for searching and filtering payments:

invoice - Select filter - Filter by associated invoice
address - Select filter - Filter by address
payment_method - Select filter (multiple) - Filter by payment method
authorized - Boolean filter - Filter by authorization status
amount_cents - Numeric range filter - Filter by amount range
currency_code - Select filter (multiple) - Filter by currency code
date - Date filter - Filter by payment date
created_at - Date filter - Filter by creation date
updated_at - Date filter - Filter by update date

Filtering Examples:

bash

# Filter by invoice
GET /admin/payments.json?q[invoice_id_eq]=123

# Filter by date range
GET /admin/payments.json?q[date_gteq]=2024-01-01&q[date_lteq]=2024-12-31

# Filter by payment method
GET /admin/payments.json?q[payment_method_eq]=Credit Card

Business Rules

Invoice Association: Payments must be associated with an invoice
Amount Validation: Payment amount must be greater than 0
Currency Matching: Payment currency should match invoice currency (or conversion is applied)
Authorization: Payments can require authorization before being processed
Accounting Integration: Payments automatically create accounting transactions

Nested Resources

Payments can be nested under invoices:

Invoice Payments - /admin/invoices/:id/invoice_payments - Payments associated with a specific invoice

Invoices - Payments are associated with invoices
Addresses - Payments can be associated with addresses
Accounting - Accounting entries for payments

/admin/payments ​

Overview ​

Relationships ​

Model Associations ​

Invoice ​

Address (Multiple Roles) ​

User ​

Domain ​

PaymentMethod ​

Reverse Associations ​

AccountingTransaction[] ​

Relationship Patterns ​

Creating Payment for Invoice ​

Creating Payment via Invoice (Nested) ​

Filtering Payments by Address ​

Accessing Invoice Payments ​

Key Features ​

Available Operations ​

List Payments (GET) ​

Show Payment (GET /:id) ​

Create Payment (POST) ​

Update Payment (PATCH /:id) ​

Delete Payment (DELETE /:id) ​

Scopes ​

Filters ​

Business Rules ​

Nested Resources ​

Related Resources ​

/admin/payments

Overview

Relationships

Model Associations

Invoice

Address (Multiple Roles)

User

Domain

PaymentMethod

Reverse Associations

AccountingTransaction[]

Relationship Patterns

Creating Payment for Invoice

Creating Payment via Invoice (Nested)

Filtering Payments by Address

Accessing Invoice Payments

Key Features

Available Operations

List Payments (GET)

Show Payment (GET /:id)

Create Payment (POST)

Update Payment (PATCH /:id)

Delete Payment (DELETE /:id)

Scopes

Filters

Business Rules

Nested Resources

Related Resources