curl --request POST \
  --url https://api-beta.pepay.io/api/commerce/devnet/orders/{orderId}/simulate \
  --header 'Content-Type: application/json' \
  --header 'x-commerce-api-key: <api-key>' \
  --data '
{
  "transitionTo": "payment_confirmed",
  "walletNetwork": "bsc",
  "walletAddress": "0x0000000000000000000000000000000000000001"
}
'

{
  "success": true,
  "data": {
    "order": {
      "orderId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "invoiceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "merchantId": 123,
      "networkEnvironment": "devnet",
      "retailer": "amazon",
      "createdAt": 123,
      "updatedAt": 123,
      "customerId": "cust_123456",
      "walletAddress": "0x0000000000000000000000000000000000000001",
      "walletNetwork": "bsc",
      "status": "placed",
      "substatus": "AWAITING_TRACKING",
      "actions": {
        "canCancel": false
      },
      "timeline": [
        {
          "status": "placed",
          "timestamp": 1765843200,
          "message": "Order placed with retailer"
        }
      ],
      "payment": {
        "status": "paid",
        "txHash": "0xpay",
        "settlement": {
          "status": "settled",
          "txHash": "0xsettle",
          "network": "bsc"
        }
      },
      "fulfillment": {
        "shipments": [
          {
            "shipmentId": "ship_123",
            "carrier": "UPS",
            "trackingNumber": "1Z999AA10123456784",
            "carrierTrackingUrl": "https://t.17track.net/en#nums=1Z999AA10123456784",
            "deliveryStatus": "In Transit",
            "retailerTrackingNumber": "TBA111189418000",
            "retailerTrackingUrl": "https://www.amazon.com/progress-tracker/...",
            "obtainedAt": 1765843200
          }
        ]
      },
      "lineItems": [
        {
          "productId": "B08N5WRWNW",
          "title": "Item",
          "imageUrl": "https://example.com/product.jpg",
          "quantity": 1,
          "price": "9.00",
          "status": "processing"
        }
      ],
      "shippingAddress": {
        "addressId": "addr_123",
        "firstName": "Jane",
        "lastName": "Doe",
        "addressLine1": "123 Main St",
        "addressLine2": "Apt 4B",
        "city": "Miami",
        "state": "FL",
        "zipCode": "33101",
        "country": "US",
        "email": "jane@example.com",
        "phoneNumber": "+13055550123",
        "validated": true,
        "validatedAt": 1765843200
      },
      "cancellationStatus": "none",
      "refundStatus": "NONE",
      "totalAmountUsd": "10.00",
      "commerceFeeUsd": "1.00",
      "refund": {
        "status": "NONE",
        "amountUsd": "9.00",
        "feeUsd": "1.00",
        "destinationWalletAddressBsc": "0x0000000000000000000000000000000000000001",
        "txHash": "0xrefund"
      },
      "refundQuote": {
        "originalAmountUsd": "10.00",
        "feeAmountUsd": "1.00",
        "refundAmountUsd": "9.00",
        "refundToken": {
          "network": "bsc",
          "symbol": "USD1"
        },
        "refundDestination": {
          "network": "bsc",
          "address": "0x0000000000000000000000000000000000000001"
        }
      }
    }
  }
}

Commerce

Simulate a Commerce order transition (devnet only)

Advances a devnet commerce order to a specific state for integration testing.

Typical devnet flow:

Create a checkout order + invoice via POST /api/commerce/merchant/checkout/invoice (returns orderId)
Simulate payment confirmation: transitionTo=payment_confirmed
Simulate settlement (unlocks placement): transitionTo=payment_settled
Simulate provider placement: transitionTo=placed
Simulate tracking: transitionTo=shipped (optionally include tracking)
Optionally simulate delivery: transitionTo=delivery_confirmed

Notes:

payment_settled also simulates provider submission (substatus=PROVIDER_PLACEMENT_SUBMITTED).
failed can only be simulated from status=processing.
cancelled can only be simulated from status=placed.
refunded requires a valid BSC refund destination (capture it at checkout or simulate payment using walletNetwork=bsc).

POST

api

commerce

devnet

orders

{orderId}

simulate

curl --request POST \
  --url https://api-beta.pepay.io/api/commerce/devnet/orders/{orderId}/simulate \
  --header 'Content-Type: application/json' \
  --header 'x-commerce-api-key: <api-key>' \
  --data '
{
  "transitionTo": "payment_confirmed",
  "walletNetwork": "bsc",
  "walletAddress": "0x0000000000000000000000000000000000000001"
}
'

{
  "success": true,
  "data": {
    "order": {
      "orderId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "invoiceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "merchantId": 123,
      "networkEnvironment": "devnet",
      "retailer": "amazon",
      "createdAt": 123,
      "updatedAt": 123,
      "customerId": "cust_123456",
      "walletAddress": "0x0000000000000000000000000000000000000001",
      "walletNetwork": "bsc",
      "status": "placed",
      "substatus": "AWAITING_TRACKING",
      "actions": {
        "canCancel": false
      },
      "timeline": [
        {
          "status": "placed",
          "timestamp": 1765843200,
          "message": "Order placed with retailer"
        }
      ],
      "payment": {
        "status": "paid",
        "txHash": "0xpay",
        "settlement": {
          "status": "settled",
          "txHash": "0xsettle",
          "network": "bsc"
        }
      },
      "fulfillment": {
        "shipments": [
          {
            "shipmentId": "ship_123",
            "carrier": "UPS",
            "trackingNumber": "1Z999AA10123456784",
            "carrierTrackingUrl": "https://t.17track.net/en#nums=1Z999AA10123456784",
            "deliveryStatus": "In Transit",
            "retailerTrackingNumber": "TBA111189418000",
            "retailerTrackingUrl": "https://www.amazon.com/progress-tracker/...",
            "obtainedAt": 1765843200
          }
        ]
      },
      "lineItems": [
        {
          "productId": "B08N5WRWNW",
          "title": "Item",
          "imageUrl": "https://example.com/product.jpg",
          "quantity": 1,
          "price": "9.00",
          "status": "processing"
        }
      ],
      "shippingAddress": {
        "addressId": "addr_123",
        "firstName": "Jane",
        "lastName": "Doe",
        "addressLine1": "123 Main St",
        "addressLine2": "Apt 4B",
        "city": "Miami",
        "state": "FL",
        "zipCode": "33101",
        "country": "US",
        "email": "jane@example.com",
        "phoneNumber": "+13055550123",
        "validated": true,
        "validatedAt": 1765843200
      },
      "cancellationStatus": "none",
      "refundStatus": "NONE",
      "totalAmountUsd": "10.00",
      "commerceFeeUsd": "1.00",
      "refund": {
        "status": "NONE",
        "amountUsd": "9.00",
        "feeUsd": "1.00",
        "destinationWalletAddressBsc": "0x0000000000000000000000000000000000000001",
        "txHash": "0xrefund"
      },
      "refundQuote": {
        "originalAmountUsd": "10.00",
        "feeAmountUsd": "1.00",
        "refundAmountUsd": "9.00",
        "refundToken": {
          "network": "bsc",
          "symbol": "USD1"
        },
        "refundDestination": {
          "network": "bsc",
          "address": "0x0000000000000000000000000000000000000001"
        }
      }
    }
  }
}

Authorizations

x-commerce-api-key

string

header

required

Legacy alias for commerce-scoped API keys. Prefer x-api-key with scope=commerce.

Path Parameters

orderId

string<uuid>

required

Body

application/json

Devnet-only request for simulating a commerce order transition.

transitionTo

enum<string>

required

Available options:

payment_confirmed,

payment_settled,

placed,

shipped,

delivery_confirmed,

failed,

cancelled,

refunded

Example:

"placed"

tracking

object | null

Optional tracking payload used for shipped/delivery transitions.

Show child attributes

walletNetwork

string | null

Optional payer wallet network used for payment simulation transitions.

Example:

"bsc"

walletAddress

string | null

Optional payer wallet address used for payment simulation transitions (must be EVM address for bsc).

Example:

"0x0000000000000000000000000000000000000001"

Response

Updated order snapshot

success

boolean

Example:

true

data

object

Show child attributes

Overview

API

Merchant

Tokens

Commerce

Payor

WebSockets

Webhooks

Simulate a Commerce order transition (devnet only)

Authorizations

Path Parameters

Body

Response