# Create Transaction

Malum charges a comission of 4% transaction through this API Endpoint this includes a 1,5% comission for infrastructure and 2,5% profit margin. We are open for negotiations. 

Create a new reseller checkout order and receive a `transaction_code` you can use to track the payment flow.

**Method:** `GET`\
**Endpoint:** `https://malum.co/api/v3/reseller/checkout`\
**Response format:** JSON

***

### Required query parameters

| Parameter                 | Type   | Example     | Notes                                        |
| ------------------------- | ------ | ----------- | -------------------------------------------- |
| `fiat_amount`             | number | `49.99`     | Must be numeric, `> 0` and `<= 10000`        |
| `fiat_currency`           | string | `EUR`       | (`A-Z`)                                      |
| `crypto_currency`         | string | `USDT`      | (`A-Z`)                                      |
| `crypto_currency_network` | string | `TRC20`     | (`A-Z0-9`)                                   |
| `wallet_address`          | string | `TA1b...`   | Destination wallet address (customer wallet) |
| `external_reference`      | string | `INV-10001` | Your reference (order id, invoice id, etc.)  |

***

### Optional query parameters

| Parameter     | Type | Example                               | Default                               |
| ------------- | ---- | ------------------------------------- | ------------------------------------- |
| `webhook_url` | url  | `https://merchant.tld/webhooks/malum` | `https://merchant.tld/webhooks/malum` |

***

### Partner split parameters (optional group)

If you set **any** `partner_*` parameter, then **all** partner parameters must be provided (except `partner_wallet_address` is effectively the toggle, but the API checks that the whole group is present).

| Parameter                         | Type   | Example                              | Notes                                                                                                                                  |
| --------------------------------- | ------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `partner_wallet_address`          | string | `0xabc...`                           | Partner wallet address                                                                                                                 |
| `partner_external_reference`      | string | `PARTNER-REF-1`                      | Your partner reference                                                                                                                 |
| `partner_crypto_currency`         | string | `USDT`                               | Same validation as `crypto_currency`                                                                                                   |
| `partner_crypto_currency_network` | string | `ERC20`                              | Same validation as `crypto_currency_network`                                                                                           |
| `partner_comission_percentage`    | number | `10`                                 | Commission percentage, must be provided if using partner split                                                                         |
| `partner_webhook_url`             | url    | `https://partner.tld/webhooks/malum` | Default if omitted is `https://merchant.tld/webhooks/malum`, but note the API also requires it to be present when partner mode is used |

***

### Validation rules

The endpoint applies these checks before creating the order:

* **Only GET parameters are processed.**
* Missing or empty required parameters return an error.
* `fiat_amount` must be numeric, greater than 0, and not greater than 10000.
* `fiat_currency` must be 2 to 4 uppercase letters.
* `crypto_currency` must be 2 to 6 uppercase letters.
* `crypto_currency_network` must be 2 to 10 uppercase letters or numbers.
* `webhook_url` (and `partner_webhook_url`) must be valid URLs.
* Crypto currency and network must be supported by the reseller system.
* Wallet addresses are stored if unknown, reused if already known.
* If `fiat_currency` is not `USD`, an exchange rate is fetched and the amount is converted to USD for internal processing.

***

### Example request (basic)

```http
GET https://malum.co/api/v3/reseller/checkout?fiat_amount=49.99&fiat_currency=EUR&crypto_currency=USDT&crypto_currency_network=TRC20&wallet_address=TA1bExampleWallet&external_reference=INV-10001&webhook_url=https%3A%2F%2Fmerchant.tld%2Fwebhooks%2Fmalum
```

***

### Example request (with partner split)

```http
GET https://malum.co/api/v3/reseller/checkout?fiat_amount=49.99&fiat_currency=EUR&crypto_currency=USDT&crypto_currency_network=TRC20&wallet_address=TA1bExampleWallet&external_reference=INV-10001&webhook_url=https%3A%2F%2Fmerchant.tld%2Fwebhooks%2Fmalum&partner_wallet_address=0xPartnerWallet&partner_external_reference=PARTNER-REF-1&partner_crypto_currency=USDT&partner_crypto_currency_network=ERC20&partner_comission_percentage=10&partner_webhook_url=https%3A%2F%2Fpartner.tld%2Fwebhooks%2Fmalum
```

***

### Success response

On success, the API returns a JSON object like:

```json
{
  "status": "success",
  "message": "Order created successfully.",
  "data": {
    "transaction_code": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "fiat_amount": "49.99",
    "fiat_currency": "EUR",
    "crypto_currency": "USDT",
    "crypto_currency_network": "TRC20",
    "wallet_address": "TA1bExampleWallet",
    "status": "pending"
  }
}
```

**Field notes**

* `transaction_code` is generated server-side (UUID4).
* `status` in `data` is returned as `pending` right after creation.

***

### Error responses

Errors return JSON with:

* `status`: `failed`
* `message`: a human-readable error message
* `data`: usually an empty object/array

Common messages include:

* `Invalid Request. Missing parameters.`
* `Invalid Request. Missing partner parameters.`
* `Invalid fiat amount.`
* `Invalid fiat currency.`
* `Invalid crypto currency.`
* `Invalid crypto currency network.`
* `Invalid webhook URL.`
* `Invalid partner webhook URL.`
* `The requested cryptocurrency or network is not supported.`
* `Could not retrieve exchange rate for the requested fiat currency.`
* `Could not create order. Please try again later.`

***

### Notes for implementers

* URL-encode your webhook URLs.
* Keep your `external_reference` unique per order to simplify reconciliation on your side.
* If you enable partner split, treat the partner parameters as an all-or-nothing block.