---
description: >-
  Execute wallet transactions with optional holds, confirm held transactions,
  transfer funds between wallets, and void transfers using the Wallets API.
---

# Transactions and Transfers

This page covers wallet transaction operations: creating transactions (with optional holds), confirming held transactions, transferring between wallets, and voiding transfers.

---

## Create a Transaction

Create a debit or credit transaction against a wallet. Optionally place a hold to reserve funds without finalizing.

### Endpoint

```
POST https://{FQDN}/wallets/transaction
```

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |
| `Content-Type` | `application/json` |

### Request

| Field | Type | Required | Description |
|---|---|---|---|
| `walletId` | string | ❌ | Target wallet identifier |
| `externalId` | string | ❌ | Your unique transaction identifier |
| `amount` | number | ❌ | Transaction amount |
| `paymentType` | string | ❌ | Transaction type (e.g., `"DEBIT"`, `"CREDIT"`) |
| `description` | string | ❌ | Human-readable description |
| `hold` | boolean | ❌ | Set to `true` to reserve funds without finalizing. The transaction must be confirmed separately via `POST /wallets/transaction/{transactionId}/confirm` |

### Example — Immediate Transaction

```bash
curl -X POST https://{FQDN}/wallets/transaction \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "walletId": "w-a1b2c3d4-e5f6-7890",
    "externalId": "txn-order-5001",
    "amount": 75.00,
    "paymentType": "DEBIT",
    "description": "Payment for order #5001",
    "hold": false
  }'
```

### Example — Hold Transaction

```bash
curl -X POST https://{FQDN}/wallets/transaction \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "walletId": "w-a1b2c3d4-e5f6-7890",
    "externalId": "txn-hold-001",
    "amount": 200.00,
    "paymentType": "DEBIT",
    "description": "Hold for reservation #8842",
    "hold": true
  }'
```

### Response (200)

```json
{
  "transactionId": "txn-7f8e9d0c-1a2b-3c4d",
  "walletId": "w-a1b2c3d4-e5f6-7890",
  "externalId": "txn-hold-001",
  "amount": 200.00,
  "paymentType": "DEBIT",
  "status": "HELD",
  "description": "Hold for reservation #8842",
  "createdAt": "2025-03-31T12:00:00Z"
}
```

| Status | Description |
|---|---|
| `COMPLETED` | Transaction finalized immediately (`hold: false`) |
| `HELD` | Funds reserved, awaiting confirmation (`hold: true`) |

---

## Confirm a Held Transaction

Finalize a previously held transaction. Once confirmed, the held funds are debited or credited.

### Endpoint

```
POST https://{FQDN}/wallets/transaction/{transactionId}/confirm
```

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |

### Path Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `transactionId` | string | ✅ | The transaction ID returned from the hold request |

### Example Request

```bash
curl -X POST https://{FQDN}/wallets/transaction/txn-7f8e9d0c-1a2b-3c4d/confirm \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'
```

### Response (200)

```json
{
  "transactionId": "txn-7f8e9d0c-1a2b-3c4d",
  "walletId": "w-a1b2c3d4-e5f6-7890",
  "status": "COMPLETED",
  "amount": 200.00,
  "confirmedAt": "2025-03-31T12:05:00Z"
}
```

---

## Transfer Between Wallets

Transfer funds atomically from one wallet to another. Both wallets must use the same currency.

### Endpoint

```
POST https://{FQDN}/wallets/transfer
```

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |
| `Content-Type` | `application/json` |

### Request

| Field | Type | Required | Description |
|---|---|---|---|
| `fromWallet` | string | ❌ | Source wallet identifier |
| `toWallet` | string | ❌ | Destination wallet identifier |
| `amount` | number | ❌ | Amount to transfer |
| `description` | string | ❌ | Human-readable description |
| `externalId` | string | ❌ | Your unique transfer identifier |

### Example Request

```bash
curl -X POST https://{FQDN}/wallets/transfer \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "fromWallet": "w-a1b2c3d4-e5f6-7890",
    "toWallet": "w-x9y8z7w6-v5u4-3210",
    "amount": 150.00,
    "description": "Settlement transfer",
    "externalId": "xfer-001"
  }'
```

### Response (200)

```json
{
  "transferId": "xfer-5e6f7g8h-9i0j-1k2l",
  "externalTransferId": "xfer-001",
  "fromWallet": "w-a1b2c3d4-e5f6-7890",
  "toWallet": "w-x9y8z7w6-v5u4-3210",
  "amount": 150.00,
  "status": "COMPLETED",
  "createdAt": "2025-03-31T14:00:00Z"
}
```

---

## Void a Transfer

Reverse a completed wallet-to-wallet transfer. The full amount is returned to the source wallet.

### Endpoint

```
POST https://{FQDN}/wallets/transfer/{externalTransferId}/void
```

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |

### Path Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `externalTransferId` | string | ✅ | Your external transfer identifier used when creating the transfer |

### Example Request

```bash
curl -X POST https://{FQDN}/wallets/transfer/xfer-001/void \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'
```

### Response (200)

```json
{
  "transferId": "xfer-5e6f7g8h-9i0j-1k2l",
  "externalTransferId": "xfer-001",
  "status": "VOIDED",
  "voidedAt": "2025-03-31T14:10:00Z"
}
```

## What's Next

- [Wallet management](wallet-management.md) — Create wallets, check balances, and retrieve statements
- [Balance](../balance.md) — Check payer balance across all providers
- [Push Transaction](../payment/push-transaction.md) — Send payouts to external recipients