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 (sometime 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 provide
  • 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>)

Emails 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 out 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 complete 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 PUT {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 break (\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"
        }
    ]
}