Payments

Payments are used to orchestrate end-to-end payment flows from external parties or from within the platform.

Endpoints

POST /payments Create payment POST /payments/{id}/accept Accept payment GET /payments/{id} Retrieve payment GET /payments/{id}/status Retrieve payment status

POST /payments

Create a payment to collect funds from an external counterparty.

Request Body

Field	Type	Description
`account_id` required	string	Destination account ID
`counterparty_id` required	string	Source counterparty ID
`amount` required	string	Payment amount
`reference`	string	Payment reference (e.g., invoice number)
`description`	string	Payment description

Example Request

Request

{
  "account_id": "acc_123456789",
  "counterparty_id": "cpty_111222333",
  "amount": "5000.00",
  "reference": "INV-2026-001",
  "description": "Payment for services"
}

Response

201 Created

{
  "id": "pay_999888777",
  "account_id": "acc_123456789",
  "counterparty_id": "cpty_111222333",
  "amount": "5000.00",
  "currency": "USD",
  "status": "REQUESTED",
  "reference": "INV-2026-001",
  "description": "Payment for services",
  "created_at": "2026-01-15T10:30:00Z"
}

POST /payments/{id}/accept

Accept a payment request and receive deposit instructions.

Response

200 OK

{
  "id": "pay_999888777",
  "status": "ACCEPTED",
  "deposit_instructions": {
    "account_number": "9876543210",
    "routing_number": "021000021",
    "bank_name": "Bultra Bank",
    "reference": "PAY999888777",
    "beneficiary_name": "Bultra Inc FBO Customer"
  },
  "accepted_at": "2026-01-15T10:35:00Z"
}

GET /payments/{id}

Retrieve details of a specific payment.

Response

200 OK

{
  "id": "pay_999888777",
  "account_id": "acc_123456789",
  "counterparty_id": "cpty_111222333",
  "amount": "5000.00",
  "currency": "USD",
  "status": "EXECUTED",
  "reference": "INV-2026-001",
  "description": "Payment for services",
  "deposit_instructions": {
    "account_number": "9876543210",
    "routing_number": "021000021",
    "reference": "PAY999888777"
  },
  "created_at": "2026-01-15T10:30:00Z",
  "accepted_at": "2026-01-15T10:35:00Z",
  "executed_at": "2026-01-17T14:20:00Z"
}

GET /payments/{id}/status

Retrieve the current status and any RFI requirements for a payment.

Response (Normal)

200 OK

{
  "id": "pay_999888777",
  "status": "IN_PROGRESS",
  "required_documents": []
}

Response (RFI Required)

200 OK

{
  "id": "pay_999888777",
  "status": "CHANGES_REQUESTED",
  "required_documents": [
    {
      "id": "doc_req_001",
      "type": "INVOICE",
      "description": "Please provide the invoice for this payment",
      "status": "PENDING"
    }
  ]
}

Payment Status Values

Status	Description
`REQUESTED`	Payment created, awaiting acceptance
`ACCEPTED`	Payment accepted, deposit instructions available
`IN_PROGRESS`	Funds received, processing
`CHANGES_REQUESTED`	RFI triggered, documentation required
`IN_REVIEW`	Under compliance review
`EXECUTED`	Payment completed successfully
`FAILED`	Payment failed
`REJECTED`	Payment rejected (e.g., compliance issue)