> For the complete documentation index, see [llms.txt](https://docs.optty.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.optty.com/direct-api-orders/order-flow/merchant-initiated-orders.md).

# Merchant Initiated Orders

Not all payment methods support this flow. Please confirm support before enabling, as a 'Not Supported' error will be thrown when attempting to use tokenisation with an unsupported provider.

This flow utilises the same endpoint as Create Order and is controlled by the `tokenisation` object in the request body:

1. Create a traditional order with `tokenisation.getToken` set to `true` (and `tokenisation.customerPresent` set to `true`), prompting the customer to complete the checkout flow.
2. Store the token returned via webhook notification from the initial order. Pass it as `tokenisation.token` in any future Create Order calls where you wish to use those tokenized payment details for processing (as illustrated in the flow below).

Status updates on merchant initiated payment should be handled the same as customer-initiated transactions outlined here [Exception Handling](/universal-integration-features/exception-handling.md).

{% hint style="warning" %}
The merchant or integrator must confirm that the customer consented when initiating a token transaction. Optty does not take any liability for the customer's consent to token transactions.
{% endhint %}

<figure><img src="https://3947039319-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfCUCEi1845pQGMcbjae6%2Fuploads%2FkY40tVIM9lowamumsEIx%2FCreate%20Merchant%20Initiated%20Order%20Flow.png?alt=media&amp;token=61c58247-a5db-4238-83df-1efa8631f192" alt=""><figcaption></figcaption></figure>

## The `tokenisation` Object

Add a `tokenisation` object to the [POST /orders](/direct-api-orders/order-flow/post-orders.md) request body. All fields are optional.

<table><thead><tr><th width="190">Name</th><th width="104">Type</th><th>Description</th></tr></thead><tbody><tr><td>tokenisation.getToken</td><td>boolean</td><td><p>Set to <code>true</code> to create a token of the payer's payment details for use in future merchant initiated transactions. The token is returned in the <code>ORDER_ASYNC_CALLBACK</code> webhook notification when the order reaches a successful status.</p><p>Requires <code>customerPresent</code> to be <code>true</code>. Defaults to false.</p></td></tr><tr><td>tokenisation.token</td><td>string</td><td>The token returned via webhook when a previous payment was completed with <code>getToken</code> set to <code>true</code>. The payment proceeds without customer interaction. When a token is supplied, <code>customerPresent</code> must also be supplied.</td></tr><tr><td>tokenisation.customerPresent</td><td>boolean</td><td>True if the customer is present on your site when initiating the transaction.<br><br>False if the customer is not present, such as a subscription payment.</td></tr><tr><td>tokenisation.customerIdentifier</td><td>string</td><td>A stable identifier you assign to the customer (for example, their account ID in your system), used to associate saved payment methods with that customer across orders where the provider supports card-on-file. If omitted, <code>customer.email</code> is used, so supply this if you want saved cards to remain linked when a customer changes their email address.</td></tr></tbody></table>

### Example: first order, requesting a token

```json
{
  "bnplProvider": "<PROVIDER>",
  "orderReference": "ORDER-1001",
  "orderAmount": 49.95,
  "purchaseCurrency": "AUD",
  "tokenisation": {
    "getToken": true,
    "customerPresent": true,
    "customerIdentifier": "cust_8f14e45f"
  }
}
```

### Example: later merchant initiated order using the token

```json
{
  "bnplProvider": "<PROVIDER>",
  "orderReference": "ORDER-1002",
  "orderAmount": 49.95,
  "purchaseCurrency": "AUD",
  "tokenisation": {
    "token": "<TOKEN_FROM_WEBHOOK>",
    "customerPresent": false
  }
}
```

Other order fields (items, customer, addresses, redirect URLs) are sent as for any Create Order request.

{% hint style="info" %}
**Token format.** Treat the token as an opaque string: store the entire value exactly as received in the webhook and send it back unchanged. For some providers the value contains more than one part (for example, separated by a `|` character).
{% endhint %}

{% hint style="warning" %}
**Deprecated top-level fields.** `getToken`, `token` and `customerPresent` can still be sent at the top level of the request body and continue to work, but are deprecated. New integrations should use the `tokenisation` object. If both forms are sent, the values inside `tokenisation` take precedence; avoid mixing them.
{% endhint %}

The flow to get the status of the order after it has been initiated via the Create Order endpoint with a token passed in is the same as a non-token payment. A valid web hook with the same structure will be returned when the status is updated, and the structure of the Get Order endpoint will remain the same.

The only variation is the redirect URL. For a token order, the `redirectUrl` returned by Create Order does not open a checkout page. It takes the customer straight to the redirect URL you passed on the order (`dynamicRedirectUrl`), with the payment status in the same URL parameters as a non-token payment. If the customer is present, you can redirect them exactly as you would for a normal order and reuse the same status page for tokenised and non-tokenised payments.

For a customer not present transaction, there is no need to do anything with the Redirect URL, there is no payment processing done when redirected.