Skip to main content

Quickstart

End-to-end TEST walkthrough of the Flow B (canonical MVP) payment path. About 5 minutes; no real funds move.

Setup​

export BASE_URL="https://api.thiqwave.com/api"     # prod gateway
export THIQWAVE_API_KEY="tw_test_replace_me"       # see Authentication
export PARTICIPANT_ID="" BENEFICIARY_ID="" QUOTE_ID="" TRANSACTION_ID=""
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 participant​

PARTICIPANT_ID=$(curl -s -X POST "$BASE_URL/v1/participants" \
  -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 '{
    "participant_id": "'"$PARTICIPANT_ID"'",
    "type": "business",
    "full_name": "Mumbai Exports Pvt Ltd",
    "country": "IN",
    "account": {
      "kind": "BANK_ACCOUNT",
      "destination_asset": "INR",
      "iban": "IN00BANK0000000001",
      "bank_name": "HDFC Bank",
      "bank_country": "IN",
      "routing": "HDFC0001234",
      "is_default": true
    }
  }' | jq -r .id)

3. Request a quote (Flow B)​

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-IN",
    "source_asset": "AED",
    "source_amount_minor": "150000",
    "destination_asset": "INR",
    "destination_kind": "BANK",
    "participant_id": "'"$PARTICIPANT_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)
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​