Postbox API

The Postbox is designed to serve as a communication channel between Solaris and its customers for banking documents.

As a bank, Solaris must regularly provide certain documentation to its customers. With Postbox, Solaris can upload all of this documentation to a central repository, and then you can provide it to your customers through your frontend using the Solaris Postbox API.

This document describes how to implement this feature in your solution using the Postbox API.

Types of documents

Currently, Solaris provides the following types of documents via Postbox:

  • Balance confirmations
  • Fee summary statements (Currently only for Spain)

How to implement Postbox

note

Please ensure that your Postbox implementation supports all types of Postbox documents.

Here is the process for retrieving Solaris documents and providing them to the customers:

  1. Solaris produces a new document and uploads it to the Postbox as an item.
  2. Solaris notifies partners of the new item (and provides the item_id) using the POSTBOX_ITEM_CREATED webhook.

  3. Call the GET Index Postbox items endpoint to retrieve all Postbox items. You can filter the response based on which items to show to the customers, e.g., by document type.

  4. Call the GET Retrieve a Postbox item endpoint to retrieve the metadata around a specific item to be displayed to a single customer.
  5. Call the GET Download document endpoint to download the actual document contained in the item.
  6. Display the downloaded PDF document to the customer.
  7. If the document requires a confirmation (specified in the customer_confirmation property), your solution must collect the customer's confirmation and then send it to Solaris using the POST Create confirmation endpoint.

Diagram: Postbox overview

Postbox overview

Postbox entities

Postbox items

An item represents a document that Solaris has created for the customers and its associated metadata. An item can belong to either a Person or a Business.

Each item has an associated document. The document is stored as a binary and must be retrieved using the GET Download document endpoint.

Items may include two properties that would require additional action from your solution:

  • customer_notification: If true, then this item has a higher priority and customers should receive a notification to read it from your solution.
  • customer_confirmation: If true, then you must collect the customer's confirmation for this item and send it to Solaris using the POST Create confirmation method.

Confirmations

A confirmation represents an instance when the customer acknowledges that they have read (and accepted) the contents of an item.

Solaris will only require confirmations for specific types of documents, not for all documents.

Webhooks

POSTBOX_ITEM_CREATED

Subscribe to the POSTBOX_ITEM_CREATED webhook to receive notifications whenever Solaris publishes a new Postbox item.

Example payload:

Copy
Copied
{
  "id": "d347d967ae8c4d58b93e6698b386cae9pbxi",
  "belongs_to": "3e0b990bb0f49eb1a43904e78461c0cbcper",
  "owner_type": "Person",
  "created_at": "2022-01-04T13:45:05Z",
  "document_date": "2021-06-30",
  "document_type": "BALANCE_CONFIRMATION",
  "name": "Item's name",
  "description": "Description",
  "customer_notification": true,
  "customer_confirmation": false,
  "document_size": 1667317,
  "document_content_type": "application/pdf"
}

Postbox API endpoints

You must implement the following API endpoints in order to use the Postbox feature:

Postbox testing

Solaris offers the following endpoints for testing the Postbox feature:

POST Create a Postbox item for a person

Creates a Postbox item for the person specified in the request URL. Note that you can only use this endpoint for testing purposes on the testing, staging, and sandbox environments.

Click here to view the full API reference.

POST Create a Postbox item for a business

Creates a Postbox item for the business specified in the request URL. Note that you can only use this endpoint for testing purposes on the testing, staging, and sandbox environments.

Click here to view the full API reference.

POST Generate Postbox PDF document

Generates an empty PDF document on Solaris' servers for use as a Postbox item. Please note the following:

  • The Content-Type header for this request must be application/json.
  • This endpoint can only be used on the testing, staging, and sandbox environments.

Click here to view the full API reference.