Appearance

Templates ​

Treezor uses the Twig 3.x templating engine. Like other files, templates should be base64-encoded.

Twig Basics ​

A template is a file that contains both structure (sometimes also styling) and instructions to inject content within. Such as: "display this variable or something else if the variable is unavailable", "iterate on this array", etc.

Info icon

Information – Limitations of Treezor Twig implementation

  • Layouts and Blocks are unavailable
  • Variables are limited to those Treezor provides
  • CSS styling must be inlined (<a style="color:orange;">my link</a> or within a <style type="text/css"></style> in the page's <head>)

Email templates ​

Your Email templates must produce HTML; an additional template producing TXT is also required. This TXT alternative is dedicated to clients that don't support HTML such as screen readers for the visually impaired.

Example ​

html
<html>
	<h1>
		Confirm your account
	</h1>
	<p>
		Welcome, you are one step away from activating your account!
	</p>
	<a href="{{ confirmation_link }}">
		Validate my account
	</a>
</html>
books icon

Reading – More information on how to format templates

Checking supported endpoints ​

Not all Treezor endpoints support templates. To check which endpoints can be templated, you can use the following request.

bash
curl -X GET {baseUrl}/customization/templates \
	-H 'Authorization: Bearer {accessToken}' \
	-H 'Content-Type: application/json'

Returns the list of customizable templates.

json
{
	"templates":[
		"email.user.onboarding_confirmation_html",        
		"email.user.onboarding_confirmation_text",        
		"wallet.address_details",        
		"wallet.statement",         
		"email.user.password_forgot_html",        
		"email.user.password_forgot_text",         
		"payout.proof_of_payout"
	]
}

Listing available variables ​

To retrieve the list of variables available within a template, you can use the following request.

bash
curl -X GET {baseUrl}/customization/templates/{templateName} \
	-H 'Authorization: Bearer {accessToken}' \
	-H 'Content-Type: application/json'

Returns the details about the template, including a list of accessible variables (variables).

json
{
    "name": "payout.proof_of_payout",
    "description": "Proof of Payout",
    "mimeType": "text/html",
    "variables": {
        "wallet": {
            "name": "wallet",
            "type": "model",
            "description": "Wallet model",
            "children": [],
            "parentName": null
        },
        "user": {
            "name": "user",
            "type": "model",
            "description": "User model",
            "children": [],
            "parentName": null
        },
        "payout": {
            "name": "payout",
            "type": "model",
            "description": "Payout model",
            "children": [],
            "parentName": null
        },
        "beneficiarie": {
            "name": "beneficiarie",
            "type": "model",
            "description": "Beneficiary model",
            "children": [],
            "parentName": null
        }
    }
}

If you attempt to use a non-existent variable, an error is returned.

Uploading a template ​

All templates must be uploaded to the following endpoint {baseUrl}/customization/templates/{templateName}/template, where the endpointName URL parameter corresponds to the endpoint to which you want to apply this template.

Your base64-encoded template should not contain line breaks (\n)

Example ​

bash
curl -X PUT {baseUrl}/customization/templates/{templateName}/template \
	-H 'Authorization: Bearer {accessToken}' \
	-H 'Content-Type: application/json' \
	-d '{
		"template":"ewogInRvdG8iOiAiQSBtYWduaWZpY2VudCB0ZW1wbGF0ZSAhIiAsCiAiZm9vIjoiYmFyIgp9"
	}'
Warning icon

Caution – Replacing a Template:

  • Takes effect immediately.
  • Cannot be undone.

Testing a template ​

To test a template with dummy values, you can use the following request.

bash
curl -X GET {baseUrl}/customization/templates/{templateName}/example \
	-H 'Authorization: Bearer {accessToken}' \
	-H 'Content-Type: application/json'

Returns an object containing a populated version of your template in the template attribute.

json
{
	"template":"PGh0bWw+Cjxib2R5Pgo8aDE+V2VsY29tZTwvaDE+CjxwPlBsZWFzZSA8Yj5jdXJyZW50IHVzZXIgPC9iPmNsaWNrIG9uIHRoZSBsaW5rIHRvIHZhbGlkYXRlIHlvdXIgYWNjb3VudDI6IDxhIGhyZWY9Imh0dHA6Ly9nb29nbGUuZnIiPmhlcmU8L2E+PC9wPgo8L2JvZHk+CjwvaHRtbD4="
}

Accessing a template ​

To retrieve a template that you have already uploaded, you can use the following request.

bash
curl -X GET {baseUrl}/customization/templates/{templateName}/template \
	-H 'Authorization: Bearer {accessToken}' \
	-H 'Content-Type: application/json'

Returns an object containing your template in the template attribute.

json
{
	"template":"ewogInRvdG8iOiAiUmVuZGVyIG5ldyB0ZW1wbGF0aW5nICEiIAp9"
}

Deleting a template ​

If you want to remove a template altogether, you can use the following request. The endpoint will immediately revert the indicated template to Treezor's default template.

bash
curl -X DELETE {baseUrl}/customization/templates/{templateName} \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json'

Using a template ​

To enable your template in a response, add the following header X-TrzConnect-Custom-Template with a value of 1.

bash
curl -X GET {baseUrl}/v1/users \
	-H 'Authorization: Bearer {accessToken}' \
	-H 'Content-Type: application/json' \
	-H 'X-TrzConnect-Custom-Template: 1' \		# <--- this header enables your template for this response only
	# [...] parameters hidden for clarity

Errors ​

If something goes wrong while uploading a template, you can expect an Error object. Its message attribute will contain useful debugging details.

Examples of errors ​

The twig template cannot be compiled ​

json
{
    "errors": [
        {
            "type": "invalid_request",
            "code": "input_validation_error",
            "message": "Your template syntax is an invalid twig syntax : \"Unexpected character \"'\" in \"5eeb7991d1cd4\" at line 18.\"",
            "docUrl": "https://developers.treezor.co"
        }
    ]
}

A variable used is not available ​

json
{
    "errors": [
        {
            "type": "invalid_request",
            "code": "input_validation_error",
            "message": "Your template is invalid : \"Variable \"my_variable\" does not exist in \"5eeb7a689e62c\" at line 12.\"",
            "docUrl": "https://developers.treezor.co"
        }
    ]
}