Skip to main content

Recipe 1: Checkout

Fastest path: 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.

This recipe is the fastest way to understand the end-to-end Checkout integration: build a valid POST /payments/request payload, send a sandbox request, and confirm the result using GET /payments/status.

Important​

For this Checkout flow:

  • No session minting is required
  • No token encryption is required
  • No transaction id encryption is required

Use these Checkout endpoints:

  1. POST /payments/request
  2. GET /payments/status
  3. POST /payments/cancel (only when needed)

Flow​

  1. Create payment request
  2. Capture payment_details_id from response
  3. Poll payment status with payment_details_id
  4. Optionally cancel with payment_details_id
  1. Open Sandbox Dashboard: https://sandbox-dashboard.paywise.co
  2. Create sandbox personal + business test accounts
  3. Install the Sandbox PayWise App and sign in as the business user
  4. Copy your sandbox business api_key from the portal credentials area
  5. Generate or use a sandbox pw-subscription-key
  6. Open Checkout Builder and generate a payload
  7. Send a sandbox request and capture payment_details_id
  8. Check GET /payments/status
  9. View the request in Transactions and Logs

Production go-live​

After sandbox success, follow the production readiness checklist before sending live payments:

https://docs.paywise.co/getting-started/go-live-checklist

Create Request​

Endpoint: POST /payments/request

{
  "api_key": "<your_api_key>",
  "transaction_request": {
    "id": "checkout_demo_20260326_0001",
    "amount": "50.00",
    "fees": {
      "pays_fees": 1,
      "payer_covers": 0
    },
    "tax": "0",
    "tip": "0",
    "convenience": "0",
    "currency": "TTD",
    "description": "Checkout recipe example",
    "customer_reference": "cust_demo_0001",
    "metadata": [
      {
        "key": 1,
        "value": "recipe-1"
      }
    ],
    "payees": [
      {
        "mobile_number": "+1XXXXXXXX01",
        "amount": "50.00",
        "delay_days": 0,
        "fees_covered": 0,
        "metadata": [
          {
            "key": 1,
            "value": "merchant-payee"
          }
        ]
      }
    ],
    "urls": {
      "success": "https://example.com/success",
      "notify": "https://example.com/notify",
      "error": "https://example.com/error",
      "callback": "https://example.com/callback"
    },
    "payers": [
      {
        "mobile_number": "+1XXXXXXXX02",
        "first_name": "<payer_first_name>",
        "last_name": "<payer_last_name>",
        "email": "[email protected]",
        "payment_channel": "direct_pos",
        "payment_method": "wallet",
        "amount": "50.00"
      }
    ],
    "fraud_check": 0
  }
}

Download Postman-ready request body

Expected success response includes a payment_details_id to use for status/cancel.

Status Check​

Endpoint: GET /payments/status

Example query:

GET /payments/status?version=2024-10-01&api_key=<your_api_key>&payment_details_id=<payment_details_id>

Cancel Request (Optional)​

Endpoint: POST /payments/cancel

{
  "api_key": "sandbox_api_key",
  "payment_details_id": "pay_123"
}