Intents (Fixed Settlements)

Define the fixed economics of a transaction before hand.

When initiating a request for payment, for example, it is undesirable to permit modifying certain transaction parameters, such as payout destination, currency and quantity.

An intent can be created with a fixed set of economics and any other parameters, without reference a quote. This intent can then be shared with the user for them to fulfil. In the payment example this means passing the intent_id to the initialization object of the widget.

A default (but still user changeable) currency can be set for either side of the transaction by setting the default_transaction in the widget initialization.

Create Intent

GET /api/v1/partner/{public_api_key}/intent

Must contain `funding_settlement` and/or `payout_settlement`. Can only contain a quantity value for one.

Path Parameters

Name	Type	Description
public_api_key	string

Headers

Name	Type	Description
X-Quoine-Auth	string

Request Body

Name	Type	Description
funding_settlement	object	Object defining the funding information.
payout_settlement	object	Object defining the payout information.
strategy	string	Consumable strategy for this intent. Either `ONE_TO_ONE_ATTEMPTED` or `ONE_TO_MANY`
expires_at	number	Unix millisecond timestamp for expiring the intent.
partner_order_id	string	Optional searchable id. Max 40 characters.
partner_ref	string	Optional long string to be associated with the transaction.
partner_tags	array	Optional array of tags for items such as campaign id or product sku.

200

{
    "success": true,
    "environment": "SANDBOX",
    "message": "Intent created. This intent can now be fulfilled by the widget.",
    "payload": {
        "id": "d627cead-8298-441c-a85a-bdf9c664877a",
        "created_at": "1623231760578",
        "expires_at": null,
        "strategy": "ONE_TO_MANY",
        "funding_settlement": null,
        "payout_settlement": {
            "method": "LIQUID_PARTNER_WALLET",
            "currency": "JPY",
            "quantity": "6540"
        },
        "partner_order_id": "searchable order id, max 40 characters",
        "partner_ref": "Signed JWT",
        "partner_tags": [
            "campaign_id"
        ]
    }
}

X-Quoine-Auth

Signed JWT. Please refer to auth token instructions.

Encoded payload must contain:

{
    "token_id": "{created in Liquid web app, link above}",
    "path": "/realtime",
    "delegate_path": "/api/v1/partner/{public_api_key}/intent",
    "nonce": {current unix timestamp}
}

Strategy

The strategy field is optional, and defaults to ONE_TO_ONE_ATTEMPTED .

Strategy	Description
ONE_TO_ONE_ATTEMPTED	This causes the intent to be "consumed" the first time a user attempts to fulfil it. (Note: this refers to clicking "Buy now", not simply rendering the widget with the intent_id)
ONE_TO_MANY	This allows the intent to be reused multiple times. (Note: the partner_* fields will appear in each transaction created with the intent unless overridden in the widget configuration.)

Example

Notation

POST https://partners.liquid.com/api/v1/partner/{public_api_key}/intent
{
    "partner_ref": "optional external reference",
    "payout_settlement": {
        "method": "LIQUID_PARTNER_WALLET",
        "currency": "JPY",
        "quantity": "6500"
    }
}

200
{
    "success": true,
    "environment": "SANDBOX",
    "message": "Intent created. This intent can now be fulfilled by the widget.",
    "payload": {
        "id": "d627cead-8298-441c-a85a-bdf9c664877a",
        "created_at": "1623231760578",
        "expires_at": null,
        "strategy": "ONE_TO_MANY",
        "funding_settlement": null,
        "payout_settlement": {
            "method": "LIQUID_PARTNER_WALLET",
            "currency": "JPY",
            "quantity": "6540"
        },
        "partner_order_id": "searchable order id, max 40 characters",
        "partner_ref": "Signed JWT",
        "partner_tags": [
            "campaign_id"
        ]
    }
}

Javascript

const jwt = require("jwt-simple");
const axios = require("axios");

const tokenId = "";
const tokenSecret = "";
const publicApiKey = "pk_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

const path = `/api/v1/partner/${publicApiKey}/intent`;
const apiBase = "https://partners.liquid.com";

const xQuoineAuth = jwt.encode(
  {
    token_id: tokenId,
    path: "/realtime",
    delegate_path: path,
    nonce: Date.now(),
  },
  tokenSecret
);

axios({
  method: "post",
  url: apiBase + path,
  headers: {
    "X-Quoine-Auth": xQuoineAuth,
  },
  data: {
    public_api_key: "pk_sandbox_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    payout_settlement: {
      method: "LIQUID_PARTNER_WALLET",
      currency: "JPY",
      quantity: "6540",
    },
    strategy: "ONE_TO_MANY",

    partner_order_id: "searchable order id, max 40 characters",
    partner_ref: "Signed JWT",
    partner_tags: ["campaign_id"],
  },
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((err) => console.log(err));

Note: In this example funding_settlement is not set to allow the user to choose how to fund the transaction.

Pass the Intent ID to the Widget

See widget configuration.

{
    "public_api_key": "pk_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "config_version": "1.2",
    "intent_id": "634fa9ca-75b6-4ecc-bc61-e2555fe06323"
}

This will cause the widget to start on the quote screen, but the payout currency and quantity will be locked.