Skip to main content

Quickstart

End-to-end TEST walkthrough of the payment path. About 5 minutes; no real funds move.

Setup​

export BASE_URL="https://api.thiqwave.com/api"     # same host for TEST and LIVE
export THIQWAVE_API_KEY="tw_test_replace_me"       # the key selects the environment
export CUSTOMER_ID="" BENEFICIARY_ID="" QUOTE_ID="" TRANSACTION_ID=""

:::info TEST vs LIVE A tw_test_ key always hits sandbox providers — KYB is mocked, no real money moves. Swap in tw_live_ only after full validation. See Environments. :::

1. Create the sending customer​

CUSTOMER_ID=$(curl -s -X POST "$BASE_URL/v1/customers" \
  -H "X-API-Key: $THIQWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "business",
    "legal_name": "Al Rashid Trading LLC",
    "email": "finance@alrashid.ae",
    "country": "AE",
    "verification_level": "standard",
    "tax_id": "TRN-100234567890003"
  }' | jq -r .id)

2. Create a beneficiary​

BENEFICIARY_ID=$(curl -s -X POST "$BASE_URL/v1/beneficiaries" \
  -H "X-API-Key: $THIQWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "'"$CUSTOMER_ID"'",
    "type": "business",
    "full_name": "Singapore Exports Pte Ltd",
    "country": "SG",
    "account": {
      "kind": "BANK_ACCOUNT",
      "destination_asset": "SGD",
      "iban": "SG00BANK0000000001",
      "bank_name": "Example Bank Singapore",
      "bank_country": "SG",
      "routing": "EXBKSGSGXXX",
      "is_default": true
    }
  }' | jq -r .id)

3. Request a quote​

source_amount_minor is integer minor units as a string ("150000" = AED 1,500.00).

QUOTE_ID=$(curl -s -X POST "$BASE_URL/v1/transactions/quote" \
  -H "X-API-Key: $THIQWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "corridor_id": "AE-SG",
    "source_asset": "AED",
    "source_amount_minor": "150000",
    "destination_asset": "SGD",
    "destination_kind": "BANK",
    "customer_id": "'"$CUSTOMER_ID"'"
  }' | jq -r .id)

4. Accept the quote (locks the rate)​

curl -X POST "$BASE_URL/v1/transactions/quote/$QUOTE_ID/accept" \
  -H "X-API-Key: $THIQWAVE_API_KEY" | jq .

Accept before expires_at (~2 min TTL).

5. Create the transaction (money-moving — Idempotency-Key required)​

TRANSACTION_ID=$(curl -s -X POST "$BASE_URL/v1/transactions" \
  -H "X-API-Key: $THIQWAVE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "'"$QUOTE_ID"'",
    "beneficiary_id": "'"$BENEFICIARY_ID"'"
  }' | jq -r .id)

:::caution LIVE — real funds With a tw_live_ key this call starts real settlement. Validate end-to-end on TEST first. :::

6. Poll status (or subscribe to webhooks)​

curl "$BASE_URL/v1/transactions/$TRANSACTION_ID" \
  -H "X-API-Key: $THIQWAVE_API_KEY" | jq .

Typical state arc: CREATED → COMPLIANCE_PENDING → COMPLIANCE_APPROVED → COLLECTION_PENDING → COLLECTION_CONFIRMED → SETTLEMENT_PENDING → SETTLEMENT_PROCESSING → SETTLEMENT_COMPLETED. On TEST this completes in seconds. Prefer Webhooks over polling.

Next steps​