Merchant API
Topup Intents

Create a top-up intent

Create a provider-backed top-up intent. Requires `Idempotency-Key`; the API key determines merchant and environment.

POST
/topup_intents

Create a provider-backed top-up intent. Requires Idempotency-Key; the API key determines merchant and environment.

Authorization

apiKey
AuthorizationBasic <token>

Merchant API key pair. Send as Authorization: Basic base64(publicKey:secretKey) — username is the public key (pk_live_… / pk_test_…), password is the secret key (sk_live_… / sk_test_…). The public key prefix determines the environment of every order created by the request — there is no body, query, or header override.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/topup_intents" \  -H "Content-Type: application/json" \  -d '{    "destination_amount": "10000",    "destination_currency": "MYR",    "source": {      "provider": "m1pay",      "type": "provider_gateway"    }  }'
{
  "created_at": "2026-06-07T10:20:00.000Z",
  "destination": {
    "amount": "100000",
    "credited_amount": "100000",
    "currency": "MYR",
    "merchant_id": "team_01HZYABCDXYZ"
  },
  "environment": "test",
  "expires_at": "2026-06-07T10:35:00.000Z",
  "failure_code": null,
  "failure_message": null,
  "fx": {
    "destination_currency": "MYR",
    "rate": "4.670000",
    "source_currency": "USDT",
    "spread_amount": "0"
  },
  "id": "tuin_01HZYABCDXYZ",
  "next_action": {
    "address": "TExampleAddress",
    "amount": "214123456",
    "currency": "USDT",
    "expires_at": "2026-06-07T10:35:00.000Z",
    "network": "TRC20",
    "type": "display_crypto_payment_instructions"
  },
  "object": "topup_intent",
  "source": {
    "amount": "214123456",
    "currency": "USDT",
    "expires_at": "2026-06-07T10:35:00.000Z",
    "fee_amount": "0",
    "fee_mode": "absorbed",
    "provider": "m1pay",
    "type": "provider_gateway"
  },
  "status": "requires_payment",
  "updated_at": "2026-06-07T10:20:01.000Z"
}
{
  "error": {
    "code": "validation_failed",
    "message": "Currency XYZ is not enabled for this merchant."
  }
}
{
  "error": {
    "code": "validation_failed",
    "message": "Currency XYZ is not enabled for this merchant."
  }
}
{
  "error": {
    "code": "validation_failed",
    "message": "Currency XYZ is not enabled for this merchant."
  }
}
{
  "error": {
    "code": "validation_failed",
    "message": "Currency XYZ is not enabled for this merchant."
  }
}
{
  "error": {
    "code": "validation_failed",
    "message": "Currency XYZ is not enabled for this merchant."
  }
}
{
  "error": {
    "code": "validation_failed",
    "message": "Currency XYZ is not enabled for this merchant."
  }
}
{
  "error": {
    "code": "validation_failed",
    "message": "Currency XYZ is not enabled for this merchant."
  }
}

Get a top-up intent GET

Fetch a top-up intent by id. Scoped to the authenticating merchant and the key's stamped environment.

List outbound webhook event types GET

Static catalogue of every outbound webhook event the platform can emit, with a realistic example payload per type. Authoritative source for the closed event-type union; SDKs and merchant handlers should switch exhaustively over this list. No authentication: this is a contract surface, not merchant data.