This guide entails comprehensive information on report distributions, why they are relevant to your workflow, and how to create and manage them using our step-by-step guides. If you have specific questions about our infrastructure, please contact your account manager or reach us at support@silverflow.com.

Description

The Silverflow API allows users to automatically send generated reports to specific destinations by creating a distribution object. This distribution object can be attached to a report schedule to trigger delivery as soon as the report is finalized. Currently, Silverflow supports report delivery via Email, SFTP, and Amazon S3.

Why it is relevant

Report distribution eliminates the need for users to manually log into the Acquirer Portal or call the API to download reports. By fully automating the delivery process, you ensure that reports reliably reach the correct internal systems (via SFTP and Amazon S3) or specific stakeholders (via Email) exactly when they are ready, saving time and streamlining your reconciliation and operations workflows.

How to integrate: a step-by-step guide

To set up automatic distribution for your reports, follow the step-by-step guide below. For SFTP and Amazon S3, there is an additional section below with more details.

Creating a distribution object

To create a distribution object, the user should use the POST /v1/distributions endpoint. Here, a distribution type should be included (see list above). Depending on the distribution delivery type, the user should then provide where the reports should be delivered to in the targets field. Optionally, the user can provide a reference for internal purposes. An example request is the following:
The response from that request will include the distributionKey, that should then be used when creating a report schedule on our POST /v1/reportSchedules endpoint.
The response from the request above will look like the following:
To retrieve the distribution object(s), the user may call the GET /v1/distributions endpoint to list all distribution objects or the GET /v1/distributions/{distributionKey} endpoint using the key of the distribution object.
To update an existing distribution configuration, one should use PATCH /v1/distributions/{distributionKey}. This is useful to update email addresses or to change the reference without having to create a new distribution object and report schedule.
To archive a distribution object, the user may call DELETE /v1/distributions/{distributionKey} which will change its status to archived.

Setting up the SFTP connection

Silverflow authenticates to your SFTP server using the SSH protocol. To facilitate this, users should add Silverflow's public SSH key to your SFTP server's authorized keys (see our keys below). Silverflow will sign all files sent through the SFTP connection with our private SSH key. This ensures secure and authenticated file transfers.
After adding the public key to your SFTP server, you can create a SFTP distribution configuration with a POST request to /distributions to set-up the SFTP distribution object with the following body:

Parameter details:
- type: Must be sftp
- targets.host: Your SFTP server hostname (without sftp:// prefix)
- targets.username: SSH username for authentication
- targets.dirPath: Directory path where files should be stored
- reference: Your unique reference for this distribution configuration
After receiving a successful 201 response, you'll get a distributionKey in the response. Use this key when creating report schedules. Every report generated by the report schedule configuration will be automatically distributed to the SFTP folder and directory path.
Clients get notified by succesful and failed SFTP file deliveries by subscribing to our com.silverflow.distributions event source. Please read more on event subscriptions here.

SSH Keys for SFTP per environment

Environment	Region	Public ssh-rsa key
Sandbox	All	ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDOZ+puvjDgABGQwAnyb67xhlZeY9aktSDpMaclTUpAP7SpjY4wONyspksnakYQ67zs6k13UNXhT3DMzZtjFDelSKabEdAtcvfsTjTu+I1fA4P1e0RYOhExNmHfthOB3zUEcB5MTbbSh2cmjxbuLaDBdTUSHzwNL5cQUb9OJwuY9TyiiKTBFvE/8S7wb/u5EUVFGfD+n4J4PHcBM/fNhENEhfB1NER8XvN05W2qMbiOru+rmzZuRwTq/VG4mbV/+wqSE0rmUWamX94+kAkh6Auo0aOhY0d/mw4BtE3g46pyR5SzdBsqlnPvuAHwBlP3Sh+6+FjgZ1DCJiizS0+urJG0P8oQewuDLbx56C9pvR3m7Ie5FGMgGLoCGkgugoFM6hfh3Q+9mVTSnlJTgO9T0WOomdqBTKL8EVW987SmRSjYNW52wgkMEAcI3G8UCVFdJLIO9nJE+6cMlq9T8+/jNGnrvgtEMsyrxfCX/fgO8yzgd3xjBsHhu85IUWBtBHgMrc3PeQ1gy2BjKwTP6xcOXJg8xniqkf0DtOxEkSJLzfhORL59MztAV1TrbXdnSJoZHlyQsc0V8/TWjWSoIjaSjjyIXXeeoxnXRP2SZkVnxsUsGmgNSK3UFssdzqviTc4JUdl+LLmeof8vheSsSPllj++v2xasc8ZxRJkl9R1+slRoTQ==
Production	Europe	ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDOCZOIuS7YVKjLZFLhic9kL8fMMe7/5yscWwqXSNH2pymBYypErzvu5g02XD02TXOhTtd8bRkWvu+5I8gD2VsH/uy+8oaufLsViR8STJJvyeE9w4Try5rbP0zwEoHrfX4qqARqTs/dF27Mn44f4yFm5hCLGYhyvh7P5emdHoU7lHABc/sFzr4Oq0aNSkk98luBgMbk3AKHAfMeCnPginqmRSgxzJUxpWxhxXfkDgbMvL84c0RYx4SatKZi9UQU4OwHamr/MWQc3kfToNQlMNdWkMgxFsJp9sdU4PoLnkADHmNnSpb6J2N7MTb6RVrhFD/J2KLQ0LKT3V/YE8VpH0Ct97WT2Tq76jKsLagTIUP/RGadmN09qqiFMVv07hXx804vnXNUiq4Jv6Hk5tjlhWc2UHpXXKls0uslb4aP4dip5ygvxeA9w3lJVzi4Ykm5COcfL6Rfc3lCkW/Ki8/SplvGh4MztdCCGAHdEGuoE52DwS6f3pKPfQcEi3ssAU/AJUvDaZbtgV/3o1l2C3CJGhqvSElxFLqtxYhDAkH0gnRA+n5XVA5GMQyGynznLz1xj/z8Zar+S132HMR0kBaNhT6f/Vgck2zvo0BwJKepLZqHQVQFsYbDIvTj3iJnRa4PbBiI5MlPt7mPdBrrwCHsuhzbFiA8Qn1vwSFVPrJVyYet4w==
Production	United States	ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQCdwjnh36hmd4SL1uMqsWlnpHd3njYuJdYTfCXKxFAIXzxlE+O9ReJPbJc0WK2rxD9NG9q5VKTK2gWEZV3cBPEN7/VJnwKAXJSikV783PWYflfGtCP/b29it0NbV7fFA+bi/oJrb5wUO80t4des+KXt7/sWGYW34zdH20Jao2OkWzsjn6+pXowsYO1ScaXdxmlTSqshvy2NkkvBoyt3jkhUCJEbbyXGdbdLTOG0n+rZV2fX2ls2+m3a6Ft+HCUqQSk6aNEd412yyI30N3A9UdaUIJq/eGhAZvA0+LaZBllkVkk+el+Hq4lxtTF6ugouHU9UGlCEYWZZKk6Euqc+iiFFdt3I8qpKG3sOlGL8HFl8I+aGOsiFv2heWAIdi7egP2kqItg26/mZoGWCRFvhNEB36jDuznDNYq0fsDJQHAQFs+aQRE5zOu+DVz8c6fQAYCnlZQigIsxBnc8KeRsjvx1WYgCBalqtDpMt4alrlHRtIF+OMGendQQ7n76+A6E1TIvTd4CsGFrixVu+MZ2bDBIfS9eTJ2uJw5T41g/h/0mUFi9OZ8NViOr0hPw2lHqcrxO7F/AwNtMgPw1NGBGsPHcS/zugZMOUhEhEhpyfJ59k2qPp2tRrcXvaLSkz/qz2UKF6NEV6t/caoQ3SiixtSjFbOiQ9aKJhXZPPwZ0mP/S16Q==

Setting up the Amazon S3 connection

Before creating an Amazon S3 distribution, complete the following steps in your AWS account.

Create (or designate) a Amazon S3 bucket to receive Silverflow report files. The bucket should be used exclusively for Silverflow deliveries. Silverflow cannot accept responsibility for modifying or overwriting files that were not placed by Silverflow, or for the contents of any file if other parties have write access to the same bucket.
Create an IAM role in your AWS account that grants s3:PutObject access to the target bucket. This role must not grant read access to Silverflow. Silverflow's internal threat controls rely on data access monitoring that does not extend to remote locations. The role's permission policy may look like the following:
The IAM role must include a trust policy that allows Silverflow to assume it. The trust policy uses an External ID to prevent the confused deputy problem. Choose a unique, secret External ID and share it only with Silverflow when creating the distribution object:
Once the IAM role and trust policy are in place, create an S3 distribution configuration with a POST request to:
- type: Must be s3.
- targets.bucketName: The name of your S3 bucket.
- targets.accountId: The 12-digit AWS account ID that owns the bucket. For security, Silverflow validates bucket ownership before every upload.
- targets.directory: The prefix (subdirectory) inside the bucket where files will be delivered (e.g. reports/daily).
- targets.roleArn: The ARN of the IAM role you created earlier.
- targets.externalId: The External ID configured in the trust policy.
- reference: An optional label for your own reference.
After receiving a successful 201 response, you will get a distributionKey in the response. Use this key when creating report schedules via the POST request to /v1/reportSchedules endpoint. Every report generated by the schedule will be automatically delivered to the configured S3 bucket and directory.

Important considerations

Bucket ownership validation: Silverflow validates that the bucket is still owned by the configured AWS account before every upload. If a bucket is deleted and recreated by a different account, deliveries will fail.
At-least-once delivery: A file may be delivered more than once with the same file key. Your integration should handle duplicate deliveries gracefully (e.g. by overwriting or deduplicating based on the file name).
Write-only access: The IAM role must grant only s3:PutObject. Do not grant read, list, or delete permissions to Silverflow.
Event notifications: Clients are notified of successful and failed S3 file deliveries by subscribing to the com.silverflow.distributions event source. Please read more on event subscriptions here.