Skip to main content

Fetching Transactions

Fetch All Transactions​

You can fetch all transactions for a customer with optional query parameters:

  • limit - Maximum number of transactions to return
  • starting_after - Return transactions created after this transaction ID
  • ending_before - Return transactions created before this transaction ID
  • updated_before_ms - Return transactions updated before this timestamp (in milliseconds)
  • updated_after_ms - Return transactions updated after this timestamp (in milliseconds)

Note: starting_after, ending_before, updated_before_ms, and updated_after_ms are mutually exclusive.

GET v1/customers/cust_alice/transactions
curl -G https://api.sphere.net/v1/customers/cust_alice/transactions?limit=10&starting_after=txn_123 \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'accept: application/json'

Response​

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": [
    {
      "id": "txn_123",
    "state": "awaitingFunds",
    "customer": "cust_alice",
    "amount": "1000.00",
    "source": {
      "paymentRail": "wire",
      "currency": "usd",
      "bankAccountId": null
    },
    "destination": {
      "paymentRail": "spherenet",
      "currency": "usd",
      "account": "sphere1abc..."
    },
    "sourceDepositInstructions": {
      "amount": "1000.00",
      "currency": "usd",
      "sepositMessage": "SPH7depositmessage"
    },
    "createdAt": "2024-01-20T19:39:14.316Z",
      "updatedAt": "2024-01-20T19:39:14.316Z"
    }
  ],
  "ts": "2024-08-22T16:15:42.707Z",
  "request": "request_cdde26b2c0534183a1aaba6baebaec1f"
}

Fetch Specific Transaction​

GET v1/transactions/txn_123
curl -G https://api.sphere.net/v1/transactions/txn_123 \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'accept: application/json'

Response​

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "id": "txn_123",
    "state": "awaitingFunds",
    "customer": "cust_alice",
    "amount": "1000.00",
    "source": {
      "paymentRail": "wire",
      "currency": "usd",
      "bankAccountId": null
    },
    "destination": {
      "paymentRail": "spherenet",
      "currency": "usd",
      "account": "sphere1abc..."
    },
    "sourceDepositInstructions": {
      "amount": "1000.00",
      "currency": "usd",
      "sepositMessage": "SPH7depositmessage"
    },
    "createdAt": "2024-01-20T19:39:14.316Z",
    "updatedAt": "2024-01-20T19:39:14.316Z"
  },
  "ts": "2024-08-22T16:15:42.707Z",
  "request": "request_cdde26b2c0534183a1aaba6baebaec1f"
}

Additional Fields​

Source Information​

For wire transfers that have been received, the source object includes additional details:

{
  "source": {
    "paymentRail": "wire",
    "currency": "usd",
    "bankAccountId": null,
    "bank_beneficiary_name": "Sender Name",
    "bank_routing_number": "123456789",
    "bank_name": "Sending Bank",
    "imad": "20240120MMQFMPX1234567"
  }
}

For ACH push transfers:

{
  "source": {
    "paymentRail": "ach_push",
    "currency": "usd",
    "bankAccountId": null,
    "description": "ACH payment description"
  }
}

Destination Information​

For completed wire transfers, the destination object includes additional details:

{
  "destination": {
    "paymentRail": "wire",
    "currency": "usd",
    "bankAccountId": "ext_123",
    "imad": "20240120MMQFMPX1234567"
  }
}

For ACH transfers:

{
  "destination": {
    "paymentRail": "ach",
    "currency": "usd",
    "bankAccountId": "ext_123",
    "trace_number": "123456789012345"
  }
}