Transactions

New transaction

Initiate a new transaction, such as a payment or transfer.

The New Transaction endpoint creates a financial transaction, such as a one-time payment, credit, or refund. Transactions are associated with an account and may include metadata for reconciliation and reporting.

Endpoint

POST /v1/transactions

Headers

Key	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer <access_token>	Yes

Request Body

{
  "account_id": "acct_001",
  "amount": 5000,
  "currency": "USD",
  "type": "payment",
  "reference": "order_12345",
  "metadata": {
    "customer_id": "cus_789",
    "order_id": "ord_456"
  }
}

Field	Type	Required	Description
account_id	string	Yes	The ID of the account the transaction belongs to.
amount	int	Yes	Transaction amount in minor units (e.g., 5000 = $50.00).
currency	string	Yes	ISO 4217 currency code (e.g., USD, EUR).
type	string	Yes	Transaction type: payment, credit, or refund.
reference	string	No	External reference ID (e.g., order number).
metadata	object	No	Key-value metadata for custom tracking.

Response

Successful Response (201 Created)

{
  "id": "txn_001",
  "account_id": "acct_001",
  "amount": 5000,
  "currency": "USD",
  "type": "payment",
  "status": "succeeded",
  "reference": "order_12345",
  "metadata": {
    "customer_id": "cus_789",
    "order_id": "ord_456"
  },
  "created_at": "2025-09-18T20:28:00Z"
}

Field	Type	Description
id	string	Unique transaction ID.
account_id	string	ID of the account the transaction belongs to.
amount	int	Transaction amount in minor units.
currency	string	Currency code.
type	string	Transaction type (payment, credit, refund).
status	string	Status of the transaction (pending, succeeded, failed).
reference	string	External reference ID, if provided.
metadata	object	Custom metadata attached to the transaction.
created_at	string	ISO 8601 timestamp when the transaction was created.

Error Response (400 / 402 / 404)

{
  "error": "insufficient_funds",
  "message": "The account does not have enough balance to process this transaction."
}

Error Code	Meaning
invalid_request	Missing or invalid fields in the request.
insufficient_funds	Account does not have enough balance.
currency_mismatch	Currency does not match the account’s base currency.
not_found	Account ID does not exist.

Example Usage

cURL

curl -X POST "https://api.example.com/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "account_id": "acct_001",
    "amount": 5000,
    "currency": "USD",
    "type": "payment",
    "reference": "order_12345",
    "metadata": {
      "customer_id": "cus_789",
      "order_id": "ord_456"
    }
  }'

JavaScript (Fetch)

const response = await fetch("https://api.example.com/v1/transactions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer your_access_token"
  },
  body: JSON.stringify({
    account_id: "acct_001",
    amount: 5000,
    currency: "USD",
    type: "payment",
    reference: "order_12345",
    metadata: {
      customer_id: "cus_789",
      order_id: "ord_456"
    }
  })
});

const data = await response.json();
console.log(data.status); // succeeded

All amounts must be provided in minor units (cents, pence, etc.). Ensure your client app converts amounts correctly before sending.

List accounts

Update transaction

Need help? Contact Support

Join our Discord Community

Questions? Contact Sales

On this page

Title