INTEGRATION
TRANSACTION ASSURANCE
CHARGES
DISPUTES & FRAUD
Connecting to the API
The Silverflow API is an internet-facing service based on HTTP REST principles. It runs on public cloud infrastructure. The latter has some implications for consuming the Silverflow API as a client because, without proper client configuration, the API might behave unexpectedly or break.
Connectivity
Global acceleration
The public access API endpoints utilize the global acceleration capability of AWS CloudFront, which offers lower latency access by using a worldwide network of 600+ Points of Presence in 100+ cities across 50 countries. This ensures that Silverflow customers will have the lowest possible latency accessing the public API endpoints from wherever they are physically located.
Domain Name System
The Silverflow servers are hosted by AWS and are available on the public internet. Therefore, Silverflow does not have complete control over the public IP addresses at which they are reachable. Instead, Silverflow relies on the Domain Name System (DNS) to ensure our servers can always be found. This means the following for any client of Silverflow:
Always use DNS to resolve the IP address.
Do not address the API using a hard-coded IP address.
Assume the IP address can change at any time.
Observe the time-to-live (TTL) specified in the DNS record when caching DNS responses.
Enforce and validate DNSSEC where presented. Most domains are configured with DNSSEC, meaning each record is accompanied by a signature record (RRSIG), which should be validated against the public key.
Certificates
Furthermore, the API and client will establish a secure connection using TLS. Clients are expected to:
Validate the certificate by checking the certificate chain up to one of the 5 AWS Trust Services root certificates installed in their TLS trust store.
Ensure that the certificate is issued by a Certificate Authority (CA) that is listed in the CAA DNS record for the domain.
Support one of the following protocols and ciphers:
Support the TLS SNI extension and always send the fully qualified hostname of the public access API endpoint in the SNI field.
Accept any certificate that passes the aforementioned checks. Pinning a certificate is not supported, as the certificates may rotate at any time.
Protocol
When integrating with the Silverflow REST API over HTTPS, clients are expected to follow industry best practices. The following guidelines outline the key areas for API client implementation:
Follow the HTTP/1.1 Standard
The Silverflow REST API adheres to the HTTP/1.1 protocol (RFC 2616). Clients must ensure compliance with this standard, including:
Correct use of HTTP methods such as GET, POST, PUT, PATCH, and DELETE.
Handling response status codes appropriately (200 OK, 201 Created, 400 Bad Request, 401 Unauthorized).
Proper formatting of request and response messages, including headers and message bodies.
Headers, Whitespace and Redirection
Include the required headers as specified in the API documentation (Content-Type, Accept, Authorization).
Headers are case-insensitive but must be formatted appropriately. Avoid leading or trailing whitespace in headers and their values.
Avoid sending unnecessary headers to reduce payload size and improve performance.
Clients must ensure requests do not contain unexpected whitespace, such as extra spaces or line breaks in headers or the message body.
Our API may use HTTP redirection (3xx status codes). Clients should handle redirects gracefully, including maintaining HTTP methods during 301 and 307 redirects.
Encodings, Compression and Streaming
Clients should handle different content encodings specified in the Content-Encoding headers.
Support for standard encodings like gzip and deflate is strongly recommended to reduce payload size and improve response times.
Set the Accept-Encoding header (Accept-Encoding: gzip, deflate) to enable HTTP compression for requests and responses where appropriate.
Clients must decompress responses automatically when compression is used.
Clients must support chunked transfer encoding for APIs that send large payloads in a streaming fashion.
Client Timeouts
Timeouts are crucial for preventing unresponsive or long-running requests from affecting client performance and user experience.
Set a reasonable limit (5-10 seconds) for establishing a connection to the API server. This prevents indefinite waiting if the server is unreachable.
Define a timeout for reading the server's response after a connection is established — for example, 30 seconds for standard responses. The maximum supported value is 59 seconds, after which the server will respond with an HTTP 504 Gateway Timeout Error.
Implement appropriate error handling and retries for timeout scenarios. Use exponential backoff with jitter to retry logic to prevent overwhelming the server.
Payloads
When working with the Silverflow API, it's crucial to follow these best practices for parsing JSON responses. The best way to ensure these practices are followed is to use a well-established, third-party JSON parser that complies with the JSON specification (RFC 8259). These parsers are designed to handle various edge cases and security concerns, ensuring more reliable and secure parsing of JSON data.
The client JSON parser should be configured as follows:
Use "open" schema definitions when using JSON Schema for validation. Expect and accept additional properties in the JSON payload that are not explicitly defined in the schema.
Do not assume or rely on any specific order of properties in JSON objects. The order of properties may change at any time without notice.
Insignificant whitespaces should be ignored.
Special characters (quotation marks, backslashes) should be properly escaped.
The parser should support UTF-8 encoding, which is the default for JSON.
Interprets and handles IEEE 754 binary64 (double precision) floating-point numbers.
Furthermore, avoid relying on JSON properties marked as "Experimental" or “BETA” in the Silverflow API documentation. These properties may change or be removed without notice in future API versions.