Create partner transaction with canonical recovery reference

Creates a partner transaction and reserves a deposit address. Use Idempotency-Key for safe retries and provide a canonical merchant_reference for recovery lookups. Request pricing must use either quote mode (quote_id) or direct mode (fiat_amount + crypto_currency + network).

POST /partner/transactions

Create partner transaction with canonical recovery reference

cURL

curl --request POST \
  --url https://dev.cashweb.cash/api/v1/partner/transactions \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "crypto_currency": "usdt",
  "merchant_reference": "order-4551",
  "network": "bep20",
  "fiat_amount": "49000.00",
  "merchant_id": "mrc_001",
  "quote_id": "9f8ad58e-f8d5-4e4f-b3f2-f44eaf8f95d1",
  "seller_phone": "08031234567",
  "terminal_id": "term_01"
}
'

200

{
  "data": {
    "amount": "161500.00",
    "crypto_amount": "100.00",
    "crypto_currency": "usdt",
    "deposit_address": "0x9d8D32b6D7DfDdAb66f6a79b9dA8fA2E30A91B7a",
    "expires_at": "2026-02-12T12:00:00Z",
    "id": "01917f00-7b4c-7f56-8a2b-15998d58c9f3",
    "merchant_id": "mrc_001",
    "merchant_reference": "order-4551",
    "network": "bep20",
    "rate": "1615.00",
    "status": "awaiting_deposit",
    "terminal_id": "term_01"
  },
  "success": true
}

Authorizations

X-API-KEY · string · header · required

Headers

Idempotency-Key · string · required

Idempotency key for safe retries

Body

application/json

Create a partner transaction. Use either quote mode (quote_id) or direct mode (fiat_amount + crypto_currency + network).

crypto_currency · string · required

Token symbol (only for direct mode).

Example:

"usdt"

merchant_reference · string · required

Canonical partner reference for recovery and reconciliation.

Required string length: 1 - 255

Example:

"order-4551"

network · string · required

Network expected for this transaction.

Example:

"bep20"

fiat_amount · string | null

Fiat amount in NGN (only for direct mode).

Example:

"49000.00"

merchant_id · string | null

Merchant identifier from partner systems.

Example:

"mrc_001"

quote_id · string | null

Quote identifier previously returned from /quotes.

Example:

"9f8ad58e-f8d5-4e4f-b3f2-f44eaf8f95d1"

seller_phone · string | null

Seller phone for assisted flow.

Example:

"08031234567"

terminal_id · string | null

Terminal identifier from partner systems.

Example:

"term_01"

Response

200

application/json

Transaction created successfully

Standard API response wrapper for all successful responses

data · object · required

Partner transaction snapshot returned by create and cancel endpoints.

Show child attributes

success · boolean · required

Indicates if the request was successful

Example:

"true"

message · string | null

Optional message for additional information