Create an escrow transaction

Creates a draft escrow transaction. Once created, it can be paid using the /pay endpoint. Visit our purchase flow developer guide for more info. The request payload for an escrow transaction is identical to the request payload for a create invoice API call.

Securitytilia_auth
Request
Request Body schema: application/json
required

Escrow Transaction resource

account_id
required
string <= 36 characters

The buyer's Tilia Account ID.

reference_type
string

A type for your reference_id.

reference_id
string

Your own reference ID.

description
string

A user-facing description for this invoice. May be used in receipts and transaction history pages, and viewed by support agents.

tax_inclusive
boolean
Default: false

An optional boolean flag indicating whether taxes should be calculated. If exclusive (false), the tax amount will be added to each line item amount. If inclusive (true), the line item amount you pass in is inclusive of the tax amount. For example, consider the following invoice of 1000 USD and 10% tax:

  • Tax exclusive: 1100 USD total (1000 USD net + 100 tax)
  • Tax inclusive: 1000 USD total (909 USD net + 91 tax)
object

An optional object used for tax determination calculation. If none is provided, the address associated with a user's account details or payment method will be used.

metadata
object

An arbitrary data structure associated with this invoice. POSTed back to your webhook upon invoice completion.

Array of objects (PaymentMethod)

The buyer's payment method to use for purchase. NOTE: if the line items are priced in real currency, this field is required.

required
Array of objects (LineItemsRequest)

The line items to be purchased. NOTE: If line items are priced in virtual currency, the payment method section should be omitted, as Tilia will handle it for you.

Responses
201

Successfully created escrow transaction.

400

Invalid input

401

Unauthorized access.

500

Service unavailable or server error.

post/v2/escrow
Request samples
application/json
{
  • "account_id": "acct_2TiDFXHVFMlAuyy7ovvz3YPKv9b",
  • "reference_type": "Acme order number",
  • "reference_id": "8987749",
  • "description": "Digital product order",
  • "tax_inclusive": false,
  • "location": {
    },
  • "metadata": {
    },
  • "payment_methods": [
    ],
  • "line_items": [
    ]
}
Response samples
application/json
{
  • "id": "esc_2V2TxPgh8usE9neZJoEjQyFHhVh",
  • "account_id": "acct_2TiDFXHVFMlAuyy7ovvz3YPKv9b",
  • "escrow_invoice_id": "inv_2V2XDLW6zogChdShdFh8WKOhHii",
  • "commit_invoice_id": "inv_2V2XDLW6zogChdShdFh8WKOhHii",
  • "cancel_invoice_id": "inv_2V2XDLW6zogChdShdFh8WKOhHii",
  • "status": "OPEN",
  • "integrator": "Acme",
  • "created": "string",
  • "updated": "string",
  • "escrow_invoice": {
    }
}