General Principles
- The API is REST-based
- All communication is performed over HTTPS
- Requests and responses use application/json in camelCase format
- The API is designed for machine-to-machine integration
- All requests must be authenticated and digitally signed
Environments
We have two environments:
- Sandbox https://api.sandbox.altery.com: Used for integration testing and validation
- Production https://api.altery.com: Used for live payment processing
Each environment has its own:
- Base URI
- API credentials
Authentication & Request Signing
Required Headers
All API requests must include:
- X-Key-Id
- X-Signature
Signing Algorithm
- RSA-based digital signature
- Generated using the private key issued via the web portal
- Signature is passed in the X-Signature header
Signature Calculation
The signature must be calculated over:
- Request URI (if no body is present)
- Request body (if present)
- Custom headers (if included)
Currently supported custom headers:
- X-OnBehalf-Of
Error Handling
- HTTP status codes indicate transport-level status
- Business errors are returned in the response body
- Invalid signatures result in authentication errors
- By default, response with not successful status code contains general error on top-level and detailed error in a corresponding level of failed entity for processing
Date format
Time and date parameters accept string value. The start time and end time parameters of a transfer are recorded as following:
yyyy-MM-ddTHH:mm:ss.fffZ.
yyyy– year.MM– month.dd– day of the month.T– Latin symbol “T” in upper-case.HH– hour (24-hour format, from 00 to 23).mm– minutes (from 00 to 59).ss– seconds (from 00 to 59).f– fractions of a second.Z– UTC, symbol “Z” in upper-case.
Example: 2022-02-17T15:05:52.403607Z – 5 minutes and 52 seconds past 3 pm on the 17th of March 2022.
Transfer currencies
For the transfer’s currency parameters, use the ISO-4217 three-letter Alphabetic Codes.
Outgoing payment currency must match one of the currencies supported by the Altery:
- USD – United States dollar
- EUR – Euro
- GBP – British pound
If currency exchange is required, it is carried out using Altery exchange rates.