Transactions Overview

ELI5 Summary

Use POST /institution/transaction to create money movement. Use GET /institution/transaction to check where it ended.

For POST, your token is encrypted, but transaction id is plaintext. For GET, the transaction id must be encrypted.

Transaction Type Decision Guide

transaction_type	Use it for
p2p	Wallet-to-wallet transfer between users
inttransfer	Remittance / FX / cross-border style transfer
deposit	Money moving into wallet/account balance
cashout	Money leaving wallet/account to external destination
payments	Merchant payment / checkout settlement
internal	Internal operation only (not available to third parties)

Required Fields Matrix by Type

Field	p2p	inttransfer	deposit	cashout
session_token_enc	required	required	required	required
transaction_id (plaintext for POST)	required	required	required	required
transaction_date	required	required	required	required
amount	required	required	required	required
sender_currency	required	required	required	required
sender_amount	required	required	required	required
description	required	required	required	required
transaction_type	p2p	inttransfer	deposit	cashout
fees	required	required	required	required
debit_party	required	required	required	required
credit_party	required	required	required	required
sender_kyc	required	required	required	required
recipient_kyc	required	required	required	required
transfer_information	optional	required	optional	optional

POST vs GET Encryption Rules

POST /institution/transaction

• session_token_enc is required and must be encrypted.
• transaction_id is plaintext and acts as your idempotency/correlation id.

Session minting/account status check rule:

• p2p: mint from the source PW wallet (debit_party PW user).
• cashout: mint from the debit_party PW user.
• deposit: mint from the credit_party PW user.
• inttransfer: mint from the PW-side participant (debit_party or credit_party, based on your flow).

GET /institution/transaction

• transaction_id_enc is required and must be encrypted.
• Wrapper processing maps transaction_id_enc to transaction_id before request execution.

Skinny Test Payloads

Use these minimal payloads for quick smoke tests.

POST /institution/transaction (p2p skinny)

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-P2P-SMOKE-001",
  "transaction_date": "2026-02-13T18:00:00.000Z",
  "amount": "1.00",
  "sender_currency": "USD",
  "sender_amount": "1.00",
  "description": "p2p smoke test",
  "transaction_type": "p2p",
  "debit_party": [
    { "key": "msisdn", "value": "15550001011" }
  ],
  "credit_party": [
    { "key": "msisdn", "value": "15550001012" }
  ]
}

POST /institution/transaction (inttransfer skinny)

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-INT-SMOKE-001",
  "transaction_date": "2026-02-13T18:05:00.000Z",
  "amount": "1.00",
  "sender_currency": "USD",
  "sender_amount": "1.00",
  "description": "inttransfer smoke test",
  "transaction_type": "inttransfer",
  "debit_party": [
    { "key": "msisdn", "value": "15550001011" }
  ],
  "credit_party": [
    { "key": "bank_account", "value": "0000001234" },
    { "key": "bank_code", "value": "DEMOUS33" }
  ],
  "transfer_information": {
    "purpose": "family_support",
    "source_of_funds": "salary"
  }
}

POST /institution/transaction (deposit skinny)

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-DEP-SMOKE-001",
  "transaction_date": "2026-02-13T18:10:00.000Z",
  "amount": "1.00",
  "sender_currency": "USD",
  "sender_amount": "1.00",
  "description": "deposit smoke test",
  "transaction_type": "deposit",
  "debit_party": [
    { "key": "external_source", "value": "card_ending_4242" }
  ],
  "credit_party": [
    { "key": "msisdn", "value": "15550001011" }
  ]
}

POST /institution/transaction (cashout skinny)

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-CASHOUT-SMOKE-001",
  "transaction_date": "2026-02-13T18:15:00.000Z",
  "amount": "1.00",
  "sender_currency": "USD",
  "sender_amount": "1.00",
  "description": "cashout smoke test",
  "transaction_type": "cashout",
  "debit_party": [
    { "key": "msisdn", "value": "15550001011" }
  ],
  "credit_party": [
    { "key": "bank_account", "value": "0000001234" }
  ]
}

GET /institution/transaction (status skinny)

Use query parameters:

version=2024-10-01
institution_name=DemoBank
transaction_id_enc=<encrypted_base64>

Full Reference Payloads

Use these complete payloads when you want full field coverage (not just smoke tests).

POST /institution/transaction (p2p full)

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-P2P-20260213-0001",
  "transaction_date": "2026-02-13T18:25:00.000Z",
  "amount": "25.00",
  "sender_currency": "USD",
  "sender_amount": "25.00",
  "description": "P2P wallet transfer",
  "transaction_type": "p2p",
  "fees": [
    { "fee_type": "service_fee", "fee_amount": "0.00", "fee_currency": "USD" }
  ],
  "debit_party": [
    { "key": "msisdn", "value": "15550001011" }
  ],
  "credit_party": [
    { "key": "msisdn", "value": "15550001012" }
  ],
  "sender_kyc": {
    "full_name": "Casey Example",
    "country": "US"
  },
  "recipient_kyc": {
    "full_name": "Jordan Example",
    "country": "US"
  }
}

POST /institution/transaction (inttransfer full)

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-INT-20260213-0001",
  "transaction_date": "2026-02-13T18:30:00.000Z",
  "amount": "300.00",
  "sender_currency": "USD",
  "sender_amount": "300.00",
  "description": "Remittance transfer",
  "transaction_type": "inttransfer",
  "fees": [
    { "fee_type": "service_fee", "fee_amount": "3.50", "fee_currency": "USD" }
  ],
  "debit_party": [
    { "key": "msisdn", "value": "15550001011" }
  ],
  "credit_party": [
    { "key": "bank_account", "value": "0000001234" },
    { "key": "bank_code", "value": "DEMOUS33" }
  ],
  "sender_kyc": {
    "full_name": "Casey Example",
    "country": "US"
  },
  "recipient_kyc": {
    "full_name": "Riley Example",
    "country": "MX"
  },
  "transfer_information": {
    "purpose": "family_support",
    "source_of_funds": "salary"
  }
}

POST /institution/transaction (deposit full)

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-DEP-20260213-0001",
  "transaction_date": "2026-02-13T18:35:00.000Z",
  "amount": "100.00",
  "sender_currency": "USD",
  "sender_amount": "100.00",
  "description": "Wallet deposit",
  "transaction_type": "deposit",
  "fees": [
    { "fee_type": "service_fee", "fee_amount": "0.00", "fee_currency": "USD" }
  ],
  "debit_party": [
    { "key": "external_source", "value": "card_ending_4242" }
  ],
  "credit_party": [
    { "key": "msisdn", "value": "15550001011" }
  ],
  "sender_kyc": {
    "full_name": "Casey Example",
    "country": "US"
  },
  "recipient_kyc": {
    "full_name": "Casey Example",
    "country": "US"
  }
}

POST /institution/transaction (cashout full)

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-CASHOUT-20260213-0001",
  "transaction_date": "2026-02-13T18:40:00.000Z",
  "amount": "80.00",
  "sender_currency": "USD",
  "sender_amount": "80.00",
  "description": "Wallet cashout",
  "transaction_type": "cashout",
  "fees": [
    { "fee_type": "service_fee", "fee_amount": "1.00", "fee_currency": "USD" }
  ],
  "debit_party": [
    { "key": "msisdn", "value": "15550001011" }
  ],
  "credit_party": [
    { "key": "bank_account", "value": "0000001234" }
  ],
  "sender_kyc": {
    "full_name": "Casey Example",
    "country": "US"
  },
  "recipient_kyc": {
    "full_name": "Casey Example",
    "country": "US"
  }
}

Quote Endpoint Note

GET /quote is coming soon in pw-wrappers. Today, use the POST /institution/quote response and consume quote_id immediately.

Next Steps

• Read Token Encryption Guide
• Follow Recipe 0: Account preflight + encryption