Skip to main content

Create payment request

Wrapper endpoint for payment-request upstream route.

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)
  • PW-ip-address (string, required)
  • User-Agent (string, required)

Request Body​

{
  "api_key": "MIL0DMG0JN8RIX6BZ9HQS17BW0BHIL",
  "transaction_request": {
    "id": "checkout-direct-devhouse-1773463144",
    "amount": "25.00",
    "fees": {
      "pays_fees": 1,
      "payer_covers": 0
    },
    "tax": "0",
    "tip": "0",
    "convenience": "0",
    "currency": "TTD",
    "description": "Checkout direct devhouse verification retry 2",
    "metadata": [
      {
        "key": 1,
        "value": "codex-retry-2"
      }
    ],
    "payees": [
      {
        "mobile_number": "+18681112220",
        "amount": "25.00",
        "delay_days": 0,
        "fees_covered": 0,
        "metadata": [
          {
            "key": 1,
            "value": "payee1-retry-2"
          }
        ]
      }
    ],
    "urls": {
      "success": "https://example.com/success",
      "notify": "https://example.com/notify",
      "error": "https://example.com/error",
      "callback": "https://example.com/callback"
    },
    "payers": [
      {
        "mobile_number": "+18681111113",
        "first_name": "Checkout",
        "last_name": "Smoke",
        "email": "[email protected]",
        "payment_channel": "direct_pos",
        "payment_method": "wallet",
        "amount": "25.00"
      }
    ]
  },
  "fraud_check": 0
}

Responses​

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

Example: direct_devhouse_success_wrapped​

{
  "status": "success",
  "code": 200,
  "message": "Payment request successful.",
  "request_id": "7c8d238a-4ab8-4d85-a45b-3f77fbd7f9a3",
  "timestamp": "2026-03-14T04:39:05.000Z",
  "payment_details": {
    "id": 178,
    "transaction_id": "checkout-direct-devhouse-1773463144",
    "amount": "25.00",
    "fees": {
      "total": "0.50",
      "card_processing": "0.00",
      "crypto_processing": 0,
      "platform_processing": "0.50",
      "agent_processing": "0.00",
      "payer_pays": "0.00",
      "payee_pays": "0.00",
      "merchant_pays": "0.50",
      "convenience": 0
    },
    "payers": [
      {
        "mobile_number": "+18681111113",
        "amount": "25.00",
        "tip": "0.00",
        "tax": "0.00",
        "payment_channel": "direct_pos",
        "payment_method": "wallet",
        "convenience_fee": "0.00",
        "fee": 0,
        "status": "Pending",
        "metadata": "",
        "qr_code": [],
        "url": "https://paywise.app.link/VH0d8nuAu1b",
        "expire_date_time": "2026-03-15 00:39:04"
      }
    ],
    "payees": [
      {
        "mobile_number": "+18681112220",
        "amount": "25.00",
        "delay_days": 0,
        "fees_covered": 0,
        "metadata": [
          {
            "key": 1,
            "value": "payee1-retry-2"
          }
        ],
        "fee": "0.50"
      }
    ],
    "fraud_check_status": "skipped"
  }
}

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

403 - Wrapper-normalized response envelope (403)​

Example: captured_primary​

{
  "status": "error",
  "code": 403,
  "message": "Invalid or unauthorized `PW-subscription-key`",
  "request_id": "590fdf72-928a-4114-bb98-8c3d3ddb5d55",
  "timestamp": "2026-02-11T03:59:45.550Z",
  "observed_client_ip": {
    "request_ip": "172.64.80.1",
    "socket_remote_address": "172.64.80.1"
  }
}

409 - Wrapper-normalized response envelope (409)​

Example: payee_wallet_unavailable​

{
  "status": "error",
  "code": "409",
  "message": "`payees[1]` wallet is currently unable to receive this disbursement. Please try again later or contact the payee directly",
  "request_id": "3f565f62-2904-4ebb-af89-413343f52a20",
  "timestamp": "2026-03-14T04:34:59.000Z",
  "errorCode": "PW_PAYEES_1_WALLET_IS_CURRENTLY_UNABLE_TO_RECEIVE_THIS_DISBURSEMENT_PLEASE_TRY_AGAIN_LATER_OR_CONTACT_THE_PAYEE_DIRECTLY"
}

422 - Wrapper-normalized response envelope (422)​

Example: fees_validation​

{
  "status": "error",
  "code": "422",
  "message": "When fees are paid by the merchant, payer_covers must be 0.",
  "request_id": "2687fd84-c147-48ee-a850-6f1d8eaebf1a",
  "timestamp": "2026-03-14T04:38:02.000Z",
  "errorCode": "PW_WHEN_FEES_ARE_PAID_BY_THE_MERCHANT_PAYER_COVERS_MUST_BE_0"
}

Notes​

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