Payment & Withdrawal Management

Overview

This skill enables AI agents and applications to initiate and manage withdrawals using Eclipse APIs.

It supports:

Initiating payments and withdrawals - e.g. ATM withdrawals
Retrieving withdrawal history
Displaying withdrawal details, e.g. tokens (OTP), expiry, and amount

All responses shown below use anonymised sample data.

1. Initiate ATM Withdrawal

Create a withdrawal request and generate a token (OTP) for collection.

Notes

externalUniqueId must be unique per transaction
Duplicate requests with the same externalUniqueId will be rejected

Request

POST {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenant_id}/wallets/{wallet_id}/withdrawals

Example Request

{
  "amount": 100,
  "description": "ATM withdrawal",
  "type": "ZA_PAYCORP_ATM",
  "externalUniqueId": "uuid-redacted",
  "deliverToPhone": "27XXXXXXXXX"
}

Example Response

{
  "withdrawalId": 50001,
  "externalUniqueId": "uuid-redacted",
  "status": "PENDING",
  "token": "123456",
  "expires": "2026-03-30T10:00:00.000Z",
  "amount": 100.00,
  "currency": "ZAR",
  "gateway": "ZA_PAYCORP_ATM",
  "type": "ATM",
  "subType": "NORMAL",
  "walletId": 20001,
  "fee": 0.00,
  "created": "2026-03-24T10:00:00.000Z",
  "description": "ATM withdrawal",
  "deliverToPhone": "27XXXXXXXXX",
  "lastModified": "2026-03-24T10:00:00.000Z",
  "tracingContext": "trace-redacted"
}

2. Get Withdrawals

Retrieve withdrawals for a wallet within a date range.

Request

GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenant_id}/wallets/{wallet_id}/withdrawals?dateFromIncl={ISO_DATE}&dateToExcl={ISO_DATE}&limit={limit}&offset={offset}

Notes

Dates must be in ISO 8601 format: 2026-03-01T00:00:00.000Z

Example Response

[
  {
    "withdrawalId": 50001,
    "externalUniqueId": "uuid-redacted",
    "status": "PENDING",
    "token": "123456",
    "expires": "2026-03-30T10:00:00.000Z",
    "amount": 100.00,
    "currency": "ZAR",
    "gateway": "ZA_PAYCORP_ATM",
    "type": "ATM",
    "subType": "NORMAL",
    "walletId": 20001,
    "fee": 0.00,
    "created": "2026-03-24T10:00:00.000Z",
    "extraInfo": "{}",
    "description": "ATM withdrawal",
    "deliverToPhone": "27XXXXXXXXX",
    "lastModified": "2026-03-24T10:00:00.000Z",
    "tracingContext": "trace-redacted"
  },
  {
    "withdrawalId": 50002,
    "externalUniqueId": "uuid-redacted-2",
    "status": "TIMEOUT",
    "errorDescription": "Expired",
    "token": "654321",
    "expires": "2026-03-20T10:00:00.000Z",
    "amount": 100.00,
    "currency": "ZAR",
    "gateway": "ZA_PAYCORP_ATM",
    "type": "ATM",
    "subType": "NORMAL",
    "walletId": 20001,
    "fee": 0.00,
    "created": "2026-03-18T10:00:00.000Z",
    "extraInfo": "{}",
    "description": "ATM withdrawal",
    "deliverToPhone": "27XXXXXXXXX",
    "lastModified": "2026-03-20T10:00:00.000Z",
    "tracingContext": "trace-redacted"
  }
]

Common Patterns for AI Agents

1. Initiate Withdrawal Flow

Capture:
- Amount
- Phone number
Generate unique externalUniqueId
Initiate withdrawal
Display:
- Token (OTP)
- Amount
- Expiry time

2. Display Active Withdrawal Token

Fetch withdrawals
Filter:
- status = PENDING
Display:
- token
- amount
- expiry

3. Handle Expired Withdrawals

Status = TIMEOUT indicates expired token
Prompt user to initiate a new withdrawal

Error Handling

Typical responses include:

400 – Invalid request
401 – Authentication failure
403 – Permissions error

Example Error Response

[
  {
    "type": "BUSINESS",
    "severity": "LOW",
    "description": "JWT has expired",
    "code": "ARCH014",
    "traceId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "spanId": "xxxxxxxxxxxxxxxx",
    "environment": "sandbox-environment"
  }
]

Best Practices

Always generate a unique externalUniqueId per request
Never reuse tokens or identifiers
Clearly display token expiry to users
Avoid exposing sensitive data beyond masked formats
Retry only with a new externalUniqueId to prevent duplicates