Create payment request

Wrapper endpoint for payment-request upstream route.

New to PayWise payments? Use the Checkout Builder.

The Checkout Builder guides you through creating a valid /payments/request payload, including fees, payment methods, split payers, split payouts, optional notify/callback URLs, and sandbox testing.

Open Checkout Builder (Sandbox) Open Checkout Builder (Production)

Sandbox keys work only with https://sandbox-api.paywise.co. Production keys can process real transactions and may require approvals.

Going live? Follow the Production go-live checklist.

Using Checkout Builder

If you are new to PayWise Checkout, use the Checkout Builder to generate a valid POST /payments/request payload and test in sandbox.

fraud_check

When used, fraud_check belongs inside transaction_request (defaults to 0 when omitted).

For a full worked example payload, see Recipe 1: Checkout.

Endpoint

POST /payments/request

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

{
  "api_key": "<your_api_key>",
  "transaction_request": {
    "id": "checkout_smoke_0001",
    "amount": "25.00",
    "currency": "TTD",
    "description": "checkout example request",
    "fees": {
      "pays_fees": 1,
      "payer_covers": 100
    },
    "fraud_check": 0,
    "payees": [
      {
        "mobile_number": "+1XXXXXXXXXX",
        "amount": "25.00",
        "delay_days": 0
      }
    ],
    "payers": [
      {
        "mobile_number": "+1XXXXXXXXXX",
        "first_name": "First",
        "last_name": "Last",
        "email": "[email protected]",
        "payment_channel": "direct_pos",
        "payment_method": "wallet",
        "amount": "25.00"
      }
    ]
  }
}

Downloads

• Download Postman-ready request body

Implementation Notes

• PW-request-date must be sent in UTC using the format YYYY-MM-DD HH:mm:ss.

payment_channel and payment_method

payment_channel	When to use	Allowed payment_method values
agent	In-person payment at a PayWise agent location	cash, card
direct_pos	QR generated for in-store direct scan-and-pay	wallet, card, credit, debit, qr_code
payment_link	Hosted remote payment link sent by SMS, email, or similar channels	wallet, card, credit, debit

Validation rules

• payment_channel=agent must use payment_method=cash or payment_method=card.
• payment_channel=direct_pos must not use payment_method=cash.
• payment_channel=payment_link must not use payment_method=cash.
• If an unsupported combination is submitted, the wrapper returns 400 and rejects the request.

Responses

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

Example: success

{
  "status": "success",
  "code": 200,
  "message": "Payment request created successfully",
  "request_id": "590fdf72-928a-4114-bb98-8c3d3ddb5d55",
  "timestamp": "2026-02-11T03:59:45.550Z",
  "transaction_request": {
    "id": "checkout_demo_20260326_0001",
    "status": "pending"
  },
  "payment_details": {
    "id": "paydet_demo_20260326_0001",
    "currency": "TTD",
    "amount": "25.00"
  },
  "payers": [
    {
      "mobile_number": "+1XXXXXXXXXX",
      "payment_channel": "direct_pos",
      "payment_method": "wallet",
      "link": "https://payers.example.test/pay/checkout_demo_20260326_0001"
    }
  ],
  "observed_client_ip": {
    "request_ip": "172.64.80.1",
    "socket_remote_address": "172.64.80.1"
  }
}

400 - Wrapper-normalized response envelope (400)

Example: error

{
  "status": "error",
  "code": 400,
  "message": "api_key is required",
  "request_id": "4d55f2c0-487a-4a10-8c0a-5a136eb7f176",
  "timestamp": "2026-02-11T03:59:45.554Z",
  "observed_client_ip": {
    "request_ip": "172.64.80.1",
    "socket_remote_address": "172.64.80.1"
  }
}

Notes

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