# cURL examples

> Signed cURL requests for every endpoint, for quick local testing against the test environment.

These examples are suitable for local quick integration testing.

In the test environment, use the test card `4111111111111111`, with any future expiry date and CVC `123`, as in [Create Payment Order](https://www.hansapay.io/docs/testing#create-payment-order).

## Prepare Variables

```bash
BASE_URL="https://api.example.com/api/v1"
MERCHANT_ID="M123456"
SECRET_KEY="your_merchant_secret"
TIMESTAMP="$(date +%s)"
NONCE="8f31a2bc9d4e6f70"
```

## Create Payment Order

```bash
BODY='{"payment_method":"CARD","merchant_order_no":"M202406240001","trans_amount":{"currency":"USD","value":"99.99"},"notify_url":"https://merchant.example.com/callback/payment","return_url":"https://merchant.example.com/pay/success","trade_info":{"goods_name":"VIP Membership","description":"Monthly subscription"},"metadata":"biz=member&uid=10001","card":{"card_number":"4111111111111111","cardholder_name":"JOHN DOE","exp_month":12,"exp_year":2028,"cvc":"123"},"billing_address":{"country":"US","first_name":"John","last_name":"Doe","email":"john@example.com","phone":"15551234567","state":"CA","city":"San Francisco","address":"Market Street","street_number":"1355","postal_code":"94103"},"device_ip":"1.1.1.1","client_ip":"1.1.1.1"}'

SIGN_PAYLOAD="${MERCHANT_ID}"$'\n'"${TIMESTAMP}"$'\n'"${NONCE}"$'\n'"${BODY}"
SIGN=$(printf '%s' "$SIGN_PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET_KEY" -binary | xxd -p -c 256)

curl -X POST "${BASE_URL}/payments/create" \
  -H "Content-Type: application/json" \
  -H "X-MerchantID: ${MERCHANT_ID}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Sign: ${SIGN}" \
  -d "$BODY"
```

Typical failure response when the amount does not satisfy current channel limits:

```json
{
  "code": 2006,
  "msg": "Amount is out of the allowed range|amountOutOfRange"
}
```

## Query Payment Order

```bash
BODY='{"merchant_order_no":"M202406240001"}'

TIMESTAMP="$(date +%s)"
NONCE="9a42b3cc7d8e9f10"
SIGN_PAYLOAD="${MERCHANT_ID}"$'\n'"${TIMESTAMP}"$'\n'"${NONCE}"$'\n'"${BODY}"
SIGN=$(printf '%s' "$SIGN_PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET_KEY" -binary | xxd -p -c 256)

curl -X POST "${BASE_URL}/payments/query" \
  -H "Content-Type: application/json" \
  -H "X-MerchantID: ${MERCHANT_ID}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Sign: ${SIGN}" \
  -d "$BODY"
```

## Create Refund

```bash
BODY='{"original_merchant_order_no":"M202406240001","merchant_refund_no":"MR202406240001","refund_amount":"10.00","reason":"customer requested","notify_url":"https://merchant.example.com/callback/refund","metadata":"refund=manual"}'

TIMESTAMP="$(date +%s)"
NONCE="abcd1234ef567890"
SIGN_PAYLOAD="${MERCHANT_ID}"$'\n'"${TIMESTAMP}"$'\n'"${NONCE}"$'\n'"${BODY}"
SIGN=$(printf '%s' "$SIGN_PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET_KEY" -binary | xxd -p -c 256)

curl -X POST "${BASE_URL}/refunds/create" \
  -H "Content-Type: application/json" \
  -H "X-MerchantID: ${MERCHANT_ID}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Sign: ${SIGN}" \
  -d "$BODY"
```

## Create Payout

```bash
BODY='{"payment_method":"CASH_APP","merchant_payout_no":"MP202406240001","trans_amount":{"currency":"USD","value":"88.50"},"payee":{"account_id":"$cashdemo","account_type":"CASHTAG","full_name":"John Doe","country":"US"},"memo":"settlement","notify_url":"https://merchant.example.com/callback/payout","metadata":"batch=20260624","client_ip":"1.1.1.1"}'

TIMESTAMP="$(date +%s)"
NONCE="11223344aabbccdd"
SIGN_PAYLOAD="${MERCHANT_ID}"$'\n'"${TIMESTAMP}"$'\n'"${NONCE}"$'\n'"${BODY}"
SIGN=$(printf '%s' "$SIGN_PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET_KEY" -binary | xxd -p -c 256)

curl -X POST "${BASE_URL}/payouts/create" \
  -H "Content-Type: application/json" \
  -H "X-MerchantID: ${MERCHANT_ID}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Sign: ${SIGN}" \
  -d "$BODY"
```

Typical response while the payout is under way:

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "CASH_APP",
    "payout_no": "P202406240001",
    "merchant_payout_no": "MP202406240001",
    "status": "PROCESSING",
    "trans_amount": {
      "currency": "USD",
      "value": "88.50"
    },
    "fee": {
      "currency": "USD",
      "value": "1.50"
    },
    "total_debit": {
      "currency": "USD",
      "value": "90.00"
    },
    "next_action": "WAIT_NOTIFY",
    "created_at": "2026-06-24T12:00:00+08:00"
  }
}
```

## Query Payout

```bash
BODY='{"merchant_payout_no":"MP202406240001"}'

TIMESTAMP="$(date +%s)"
NONCE="22334455bbccddee"
SIGN_PAYLOAD="${MERCHANT_ID}"$'\n'"${TIMESTAMP}"$'\n'"${NONCE}"$'\n'"${BODY}"
SIGN=$(printf '%s' "$SIGN_PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET_KEY" -binary | xxd -p -c 256)

curl -X POST "${BASE_URL}/payouts/query" \
  -H "Content-Type: application/json" \
  -H "X-MerchantID: ${MERCHANT_ID}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Sign: ${SIGN}" \
  -d "$BODY"
```

## Cancel Payout

```bash
BODY='{"merchant_payout_no":"MP202406240001","reason":"manual cancel"}'

TIMESTAMP="$(date +%s)"
NONCE="33445566ccddee77"
SIGN_PAYLOAD="${MERCHANT_ID}"$'\n'"${TIMESTAMP}"$'\n'"${NONCE}"$'\n'"${BODY}"
SIGN=$(printf '%s' "$SIGN_PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET_KEY" -binary | xxd -p -c 256)

curl -X POST "${BASE_URL}/payouts/cancel" \
  -H "Content-Type: application/json" \
  -H "X-MerchantID: ${MERCHANT_ID}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Sign: ${SIGN}" \
  -d "$BODY"
```

## Payout Precheck

```bash
BODY='{"payment_method":"PAYPAL","trans_amount":{"currency":"USD","value":"88.50"}}'

TIMESTAMP="$(date +%s)"
NONCE="44556677ddeeff88"
SIGN_PAYLOAD="${MERCHANT_ID}"$'\n'"${TIMESTAMP}"$'\n'"${NONCE}"$'\n'"${BODY}"
SIGN=$(printf '%s' "$SIGN_PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET_KEY" -binary | xxd -p -c 256)

curl -X POST "${BASE_URL}/payouts/precheck" \
  -H "Content-Type: application/json" \
  -H "X-MerchantID: ${MERCHANT_ID}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Sign: ${SIGN}" \
  -d "$BODY"
```
