Payments API

Process Payment

POST /payments

Request Body

Parameter	Type	Required	Description
mandate_id	string	Yes	The mandate authorizing this payment
amount	number	Yes	Amount in smallest currency unit
currency	string	No	Currency code (default: USD)
payment_method	string	No	Payment method type
idempotency_key	string	Yes	Unique key for deduplication
metadata	object	No	Custom key-value pairs

Example

curl -X POST https://api.soft.house/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mandate_id": "mnd_abc123",
    "amount": 119999,
    "currency": "usd",
    "idempotency_key": "pay_unique_456"
  }'

Response (201 Created)

{
  "data": {
    "id": "pay_xyz789",
    "mandate_id": "mnd_abc123",
    "amount": 119999,
    "currency": "usd",
    "status": "succeeded",
    "protocol_type": "ap2",
    "created_at": "2026-01-20T10:35:00Z"
  }
}

List Payments

GET /payments

Query Parameters

Parameter	Type	Description
status	string	Filter by payment status
mandate_id	string	Filter by mandate
limit	number	Items per page
offset	number	Pagination offset

Get Payment

GET /payments/:id

Payment Statuses

Status	Description
pending	Payment initiated
processing	Being processed by payment provider
succeeded	Successfully completed
failed	Payment failed
refunded	Payment was refunded

Idempotency

All payment operations require an idempotency_key. If a request with the same key is received within 24 hours, the original response is returned without reprocessing.

# First request - processes payment
curl -X POST https://api.soft.house/payments \
  -H "Idempotency-Key: pay_unique_456" \
  -d '{ ... }'

# Duplicate request - returns cached response
curl -X POST https://api.soft.house/payments \
  -H "Idempotency-Key: pay_unique_456" \
  -d '{ ... }'
# Returns same response, no duplicate charge