Transactions Overview

Product Mapping

Checkout is the merchant payment-request surface and uses /payments/request, /payments/status, and /payments/cancel.
PayWise Pay uses /institution/transaction for wallet movement flows such as p2p and cashout.
Remittance / FX also uses /institution/transaction, but with transaction_type=inttransfer.

Public Contract Rules

Public success responses preserve the upstream institution/DevHouse message when one is available.
Public success responses surface institution_receipt_id when DevHouse returns one.
Public responses never include internal PayWise orchestration fields such as intent, metadata_json, normalized_status, reference_id, paywise_reference, execution_context, provider_request_id, or raw upstream payloads.
Transaction history for institution-created transactions is checked through /institution/transaction_history.
Canonical institution identity in the transaction body is transfer_information.institution_name.
Top-level institution_name is compatibility-only and is intentionally omitted from public POST /institution/transaction examples.
Wrappers accepts public session_token_enc and translates it to internal session_token before transactions, DAP, and DevHouse execution.
DevHouse execution version remains 2024-10-01.

ELI5 Summary

Use POST /institution/transaction to create money movement. Use GET /institution/transaction to check where it ended. Use GET /institution/transaction_history to confirm the DevHouse history record after the transaction completes.

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`	PayWise Pay wallet-to-wallet transfer between users
`inttransfer`	Remittance / FX / cross-border style transfer
`deposit`	Money moving into wallet/account balance
`cashout`	PayWise Pay money leaving wallet/account to external destination

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-13 18:00:00",
  "amount": "1.00",
  "sender_currency": "TTD",
  "sender_amount": "1.00",
  "description": "p2p smoke test",
  "transaction_type": "p2p",
  "fees": {
    "total": "",
    "convenience": "",
    "sender_pays": "",
    "recipient_pays": ""
  },
  "debit_party": {
    "mobile_number": "15550001011",
    "organization_id": "",
    "account_number": "",
    "account_type": "",
    "currency": "TTD",
    "metadata": ""
  },
  "credit_party": {
    "mobile_number": "15550001012",
    "organization_id": "",
    "account_number": "",
    "account_type": "",
    "currency": "TTD",
    "metadata": ""
  },
  "sender_kyc": {
    "nationality": "TT"
  },
  "recipient_kyc": {
    "nationality": "TT"
  },
  "transfer_information": {
    "institution_name": "DemoBank",
    "receiving_country": "TT",
    "remittance_purpose": "family_support",
    "source_of_funds": "salary_income",
    "relationship_sender": "self"
  }
}

POST /institution/transaction (inttransfer skinny)

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-INT-SMOKE-001",
  "transaction_date": "2026-02-13 18:05:00",
  "amount": "1.00",
  "sender_currency": "USD",
  "sender_amount": "1.00",
  "description": "inttransfer smoke test",
  "transaction_type": "inttransfer",
  "fees": {
    "total": "",
    "convenience": "",
    "sender_pays": "",
    "recipient_pays": ""
  },
  "debit_party": {
    "mobile_number": "15550001011",
    "organization_id": "",
    "account_number": "",
    "account_type": "",
    "currency": "USD",
    "metadata": ""
  },
  "credit_party": {
    "mobile_number": "15550001012",
    "organization_id": "",
    "account_number": "0000001234",
    "account_type": "",
    "currency": "TTD",
    "metadata": {
      "bank_code": "DEMOUS33"
    }
  },
  "sender_kyc": {
    "nationality": "US"
  },
  "recipient_kyc": {
    "nationality": "TT"
  },
  "transfer_information": {
    "institution_name": "DemoBank",
    "quote_id": "<quote_id_from_post_institution_quote>",
    "remittance_purpose": "family_support",
    "source_of_funds": "salary_income",
    "receiving_country": "TT",
    "relationship_sender": "self"
  }
}

POST /institution/transaction (deposit skinny)

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-DEP-SMOKE-001",
  "transaction_date": "2026-02-13 18:10:00",
  "amount": "1.00",
  "sender_currency": "TTD",
  "sender_amount": "1.00",
  "description": "deposit smoke test",
  "transaction_type": "deposit",
  "fees": {
    "total": "",
    "convenience": "",
    "sender_pays": "",
    "recipient_pays": ""
  },
  "debit_party": {
    "mobile_number": "15550009999",
    "organization_id": "",
    "account_number": "",
    "account_type": "",
    "currency": "TTD",
    "metadata": {
      "external_source": "card_ending_4242"
    }
  },
  "credit_party": {
    "mobile_number": "15550001011",
    "organization_id": "",
    "account_number": "",
    "account_type": "",
    "currency": "TTD",
    "metadata": ""
  },
  "sender_kyc": {
    "nationality": "TT"
  },
  "recipient_kyc": {
    "nationality": "TT"
  },
  "transfer_information": {
    "institution_name": "DemoBank"
  }
}

POST /institution/transaction (cashout skinny)

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-CASHOUT-SMOKE-001",
  "transaction_date": "2026-02-13 18:15:00",
  "amount": "1.00",
  "sender_currency": "TTD",
  "sender_amount": "1.00",
  "description": "cashout smoke test",
  "transaction_type": "cashout",
  "fees": {
    "total": "",
    "convenience": "",
    "sender_pays": "",
    "recipient_pays": ""
  },
  "debit_party": {
    "mobile_number": "15550001011",
    "organization_id": "",
    "account_number": "",
    "account_type": "",
    "currency": "TTD",
    "metadata": ""
  },
  "credit_party": {
    "mobile_number": "15550001012",
    "organization_id": "",
    "account_number": "0000001234",
    "account_type": "",
    "currency": "TTD",
    "metadata": ""
  },
  "sender_kyc": {
    "nationality": "TT"
  },
  "recipient_kyc": {
    "nationality": "TT"
  },
  "transfer_information": {
    "institution_name": "DemoBank"
  }
}

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-13 18:25:00",
  "amount": "25.00",
  "sender_currency": "TTD",
  "sender_amount": "25.00",
  "description": "P2P wallet transfer",
  "transaction_type": "p2p",
  "fees": {
    "total": "",
    "convenience": "",
    "sender_pays": "",
    "recipient_pays": ""
  },
  "debit_party": {
    "mobile_number": "15550001011",
    "organization_id": "",
    "account_number": "",
    "account_type": "",
    "currency": "TTD",
    "metadata": ""
  },
  "credit_party": {
    "mobile_number": "15550001012",
    "organization_id": "",
    "account_number": "",
    "account_type": "",
    "currency": "TTD",
    "metadata": ""
  },
  "sender_kyc": {
    "nationality": "TT"
  },
  "recipient_kyc": {
    "nationality": "TT"
  },
  "transfer_information": {
    "institution_name": "DemoBank",
    "receiving_country": "TT",
    "remittance_purpose": "family_support",
    "source_of_funds": "salary_income",
    "relationship_sender": "self"
  }
}

POST /institution/transaction (inttransfer full)

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-INT-20260213-0001",
  "transaction_date": "2026-02-13 18:30:00",
  "amount": "300.00",
  "sender_currency": "USD",
  "sender_amount": "300.00",
  "description": "Remittance transfer",
  "transaction_type": "inttransfer",
  "fees": {
    "total": "",
    "convenience": "",
    "sender_pays": "",
    "recipient_pays": ""
  },
  "debit_party": {
    "mobile_number": "15550001011",
    "organization_id": "",
    "account_number": "",
    "account_type": "",
    "currency": "USD",
    "metadata": ""
  },
  "credit_party": {
    "mobile_number": "15550001012",
    "organization_id": "",
    "account_number": "0000001234",
    "account_type": "",
    "currency": "TTD",
    "metadata": {
      "bank_code": "DEMOUS33"
    }
  },
  "sender_kyc": {
    "nationality": "US"
  },
  "recipient_kyc": {
    "nationality": "TT"
  },
  "transfer_information": {
    "institution_name": "DemoBank",
    "quote_id": "<quote_id_from_post_institution_quote>",
    "remittance_purpose": "family_support",
    "source_of_funds": "salary_income",
    "receiving_country": "TT",
    "relationship_sender": "self"
  }
}

POST /institution/transaction (deposit full)

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-DEP-20260213-0001",
  "transaction_date": "2026-02-13 18:35:00",
  "amount": "100.00",
  "sender_currency": "TTD",
  "sender_amount": "100.00",
  "description": "Wallet deposit",
  "transaction_type": "deposit",
  "fees": {
    "total": "",
    "convenience": "",
    "sender_pays": "",
    "recipient_pays": ""
  },
  "debit_party": {
    "mobile_number": "15550009999",
    "organization_id": "",
    "account_number": "",
    "account_type": "",
    "currency": "TTD",
    "metadata": {
      "external_source": "card_ending_4242"
    }
  },
  "credit_party": {
    "mobile_number": "15550001011",
    "organization_id": "",
    "account_number": "",
    "account_type": "",
    "currency": "TTD",
    "metadata": ""
  },
  "sender_kyc": {
    "nationality": "TT"
  },
  "recipient_kyc": {
    "nationality": "TT"
  },
  "transfer_information": {
    "institution_name": "DemoBank"
  }
}

POST /institution/transaction (cashout full)

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-CASHOUT-20260213-0001",
  "transaction_date": "2026-02-13 18:40:00",
  "amount": "80.00",
  "sender_currency": "TTD",
  "sender_amount": "80.00",
  "description": "Wallet cashout",
  "transaction_type": "cashout",
  "fees": {
    "total": "",
    "convenience": "",
    "sender_pays": "",
    "recipient_pays": ""
  },
  "debit_party": {
    "mobile_number": "15550001011",
    "organization_id": "",
    "account_number": "",
    "account_type": "",
    "currency": "TTD",
    "metadata": ""
  },
  "credit_party": {
    "mobile_number": "15550001012",
    "organization_id": "",
    "account_number": "0000001234",
    "account_type": "",
    "currency": "TTD",
    "metadata": ""
  },
  "sender_kyc": {
    "nationality": "TT"
  },
  "recipient_kyc": {
    "nationality": "TT"
  },
  "transfer_information": {
    "institution_name": "DemoBank"
  }
}

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

Product Mapping​

Public Contract Rules​

ELI5 Summary​

Transaction Type Decision Guide​

Required Fields Matrix by Type​

POST vs GET Encryption Rules​

POST /institution/transaction​

GET /institution/transaction​

Skinny Test Payloads​

POST /institution/transaction (p2p skinny)​

POST /institution/transaction (inttransfer skinny)​

POST /institution/transaction (deposit skinny)​

POST /institution/transaction (cashout skinny)​

GET /institution/transaction (status skinny)​

Full Reference Payloads​

POST /institution/transaction (p2p full)​

POST /institution/transaction (inttransfer full)​

POST /institution/transaction (deposit full)​

POST /institution/transaction (cashout full)​

Quote Endpoint Note​

Next Steps​