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

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

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)

{
  "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

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

Response (200)

{
  "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

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)

{
  "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

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

Response (200)

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

What's Next

Wallet management — Create wallets, check balances, and retrieve statements
Balance — Check payer balance across all providers
Push Transaction — Send payouts to external recipients