Create institution transaction

Posts transaction details to institution endpoint.

Endpoint

POST /institution/transaction

Query Parameters

• version (string, required) - API contract version. Use exactly 2024-10-01.
• diagnostics (boolean, optional) - Non-production docs only. Set true to include extra diagnostic metadata (for example observed_client_ip).

Header Parameters

• PW-subscription-key (string, required)
• PW-origin-country (string, required)
• PW-request-date (string, required) - UTC request timestamp formatted as YYYY-MM-DD HH:mm:ss.
• PW-ip-address (string, required)
• User-Agent (string, required)

Header Constraints

Key	Description	Example	Data type	Requirement	Field Length
PW-subscription-key	Developer key available after portal registration. Production key is shared on request.	eed0d85c530c4b26a91d09b783d8fab3	string	mandatory	32
PW-origin-country	ISO Alpha-2 country code where the transaction is created.	TT	string	mandatory	2
PW-request-date	Current request timestamp. Format: YYYY-MM-DD HH:mm:ss (UTC).	2014-10-08 16:01:31	string	mandatory	19
PW-ip-address	Fixed institution IP used for PayWise network-level validation.	255.255.255.255	string	conditional	8-16
User-Agent	In programmable environments, this avoids running into Cloudflare issues.	Mozilla/5.0 (Windows NT 10.0; Win64; x64)	string	mandatory	255

Request Body

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-P2P-SMOKE-001",
  "transaction_date": "2026-02-13 18:00:00",
  "amount": "50.00",
  "sender_currency": "TTD",
  "sender_amount": "50.00",
  "description": "p2p smoke test",
  "transaction_type": "inttransfer",
  "fees": {
    "total": "",
    "convenience": "",
    "sender_pays": "",
    "recipient_pays": ""
  },
  "debit_party": {
    "mobile_number": "18680001234",
    "organization_id": "",
    "account_number": "ACCT-XXXXXX",
    "account_type": "",
    "currency": "TTD",
    "metadata": ""
  },
  "credit_party": {
    "mobile_number": "18680001234",
    "organization_id": "",
    "account_number": "ACCT-XXXXXX",
    "account_type": "",
    "currency": "TTD",
    "metadata": ""
  },
  "sender_kyc": {
    "nationality": "TT"
  },
  "recipient_kyc": {
    "nationality": "TT"
  },
  "transfer_information": {
    "institution_name": "ExampleInstitution",
    "receiving_country": "TT",
    "remittance_purpose": "family_support",
    "source_of_funds": "salary_income",
    "relationship_sender": "self"
  }
}

Downloads

• Download Postman-ready request body
• Download Postman-ready response (200)
• Download Postman-ready response (403 error)

Before You Implement

• Read Transactions Overview
• Read Token Encryption Guide

Full request body examples (by transaction_type)

Show full request payloads by transaction type

p2p

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-P2P-20260213-0001",
  "transaction_date": "2026-02-13T18:25:00.000Z",
  "amount": "25.00",
  "sender_currency": "TTD",
  "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"
  }
}

inttransfer

{
  "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": {
    "quote_id": "<quote_id_from_post_institution_quote>",
    "remittance_purpose": "family_support",
    "source_of_funds": "salary"
  }
}

deposit

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-DEP-20260213-0001",
  "transaction_date": "2026-02-13T18:35:00.000Z",
  "amount": "100.00",
  "sender_currency": "TTD",
  "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"
  }
}

cashout

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-CASHOUT-20260213-0001",
  "transaction_date": "2026-02-13T18:40:00.000Z",
  "amount": "80.00",
  "sender_currency": "TTD",
  "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"
  }
}

Responses

200 - Wrapper-normalized response envelope (success cases).

Example: success

{
  "status": "success",
  "code": 200,
  "message": "Amount Credited.",
  "request_id": "90919ed3-102c-46a4-b62e-5b9dcdff14e4",
  "timestamp": "2026-02-13T18:17:24.774Z",
  "institution_receipt_id": "PWDP-TTI8LM"
}

403 - Wrapper-normalized response envelope (403)

Example: error

{
  "status": "error",
  "code": 403,
  "message": "This endpoint is not permitted for your institution.",
  "request_id": "16a33e14-6a68-44a2-a8ab-693656de0916",
  "timestamp": "2026-06-30T03:07:47.198Z",
  "errorCode": "PW_INSTITUTION_ENDPOINT_NOT_ALLOWED"
}

Notes

This endpoint page is generated from openapi/pw-wrappers.2024-10-01.yaml.