openapi: 3.2.0 info: title: Fipto - OpenAPI 3.0 Automations API version: 4.3.0 description: This is a REST API specifications based on OpenAPI 3.0 for Fipto solution. contact: url: https://www.fipto.com/ servers: - url: https://api.fipto.app description: The API server on production tags: - name: Automations paths: /companies/{company_id}/automations: get: summary: List automation rules description: Retrieve the list of automation rules for your company. operationId: listAutomations tags: - Automations parameters: - $ref: '#/components/parameters/company_id' - $ref: '#/components/parameters/page_number' - $ref: '#/components/parameters/page_size_optional' - name: status in: query description: Filter by status required: false schema: type: string enum: - active - name: rule_type in: query description: Filter by rule type required: false schema: type: string enum: - conversion - payout responses: '200': description: List of automation rules. content: application/json: schema: allOf: - $ref: '#/components/schemas/meta' - $ref: '#/components/schemas/pagination' - type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/automation_rule_data' '400': description: Bad Request content: application/json: schema: type: object required: - data properties: data: type: object required: - message properties: message: type: string oneOf: - pattern: ^Automation is not enabled for this company\.$ post: summary: Create automation rule description: Create a new automation rule for automatic conversions or payouts. Requires 2FA verification. operationId: createAutomation tags: - Automations parameters: - $ref: '#/components/parameters/company_id' requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/automation_rule_create_raw_data' responses: '201': description: Automation rule successfully created. content: application/json: schema: allOf: - $ref: '#/components/schemas/meta' - type: object required: - data properties: data: $ref: '#/components/schemas/automation_rule_data' '400': description: Bad Request content: application/json: schema: type: object required: - data properties: data: type: object required: - message properties: message: type: string oneOf: - pattern: ^Automation is not enabled for this company\.$ - pattern: ^Invalid rule_type\. Must be 'conversion' or 'payout'\.$ - pattern: ^Invalid trigger_event\. Must be 'payin_completed' or 'conversion_completed'\.$ - pattern: ^Conversion rules can only be triggered by 'payin_completed'\.$ - pattern: ^Invalid amount_mode\. Must be 'full' or 'inherited'\.$ - pattern: ^Source wallet asset is not eligible for automation\. Only EUR, USD, and stablecoins are supported\.$ - pattern: ^This wallet already has an active automation rule for this trigger event\. Only one rule per trigger event per wallet is allowed\.$ - pattern: ^destination_wallet_id is required for conversion rules\.$ - pattern: ^Destination wallet must be different from source wallet\.$ - pattern: ^Destination wallet must have a different currency for conversions\.$ - pattern: ^destination_beneficiary_id is required for payout rules\.$ - pattern: ^Beneficiary currency must match source wallet currency for payouts\.$ - pattern: ^This beneficiary targets a Fipto wallet and cannot be used for automation\.$ '404': description: Not Found content: application/json: schema: type: object required: - data properties: data: type: object required: - message properties: message: type: string oneOf: - pattern: ^Unknown source wallet\.$ - pattern: ^Unknown destination wallet\.$ - pattern: ^Unknown beneficiary\.$ /companies/{company_id}/automations/{automation_id}: get: summary: Get automation rule description: Retrieve a specific automation rule by its unique identifier. operationId: getAutomation tags: - Automations parameters: - $ref: '#/components/parameters/company_id' - $ref: '#/components/parameters/automation_id' responses: '200': description: Automation rule details. content: application/json: schema: allOf: - $ref: '#/components/schemas/meta' - type: object required: - data properties: data: $ref: '#/components/schemas/automation_rule_data' '400': description: Bad Request content: application/json: schema: type: object required: - data properties: data: type: object required: - message properties: message: type: string oneOf: - pattern: ^Automation is not enabled for this company\.$ '404': description: Not Found content: application/json: schema: type: object required: - data properties: data: type: object required: - message properties: message: type: string oneOf: - pattern: ^Unknown automation rule\.$ put: summary: Update automation rule description: Update an existing automation rule's configuration. operationId: updateAutomation tags: - Automations parameters: - $ref: '#/components/parameters/company_id' - $ref: '#/components/parameters/automation_id' requestBody: content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/automation_rule_update_raw_data' responses: '200': description: Automation rule successfully updated. content: application/json: schema: allOf: - $ref: '#/components/schemas/meta' - type: object properties: data: $ref: '#/components/schemas/automation_rule_data' '400': description: Bad Request content: application/json: schema: type: object required: - data properties: data: type: object required: - message properties: message: type: string oneOf: - pattern: ^Automation is not enabled for this company\.$ - pattern: ^Cannot update a deleted automation rule\.$ - pattern: ^Invalid rule_type\. Must be 'conversion' or 'payout'\.$ - pattern: ^Invalid trigger_event\. Must be 'payin_completed' or 'conversion_completed'\.$ - pattern: ^Conversion rules can only be triggered by 'payin_completed'\.$ - pattern: ^Invalid amount_mode\. Must be 'full' or 'inherited'\.$ - pattern: ^Source wallet asset is not eligible for automation\. Only EUR, USD, and stablecoins are supported\.$ - pattern: ^This wallet already has an active automation rule for this trigger event\. Only one rule per trigger event per wallet is allowed\.$ - pattern: ^destination_wallet_id is required for conversion rules\.$ - pattern: ^Destination wallet must be different from source wallet\.$ - pattern: ^Destination wallet must have a different currency for conversions\.$ - pattern: ^destination_beneficiary_id is required for payout rules\.$ - pattern: ^Beneficiary currency must match source wallet currency for payouts\.$ - pattern: ^This beneficiary targets a Fipto wallet and cannot be used for automation\.$ '404': description: Not Found content: application/json: schema: type: object required: - data properties: data: type: object required: - message properties: message: type: string oneOf: - pattern: ^Unknown automation rule\.$ - pattern: ^Unknown source wallet\.$ - pattern: ^Unknown destination wallet\.$ - pattern: ^Unknown beneficiary\.$ delete: summary: Delete automation rule description: Delete an automation rule. operationId: deleteAutomation tags: - Automations parameters: - $ref: '#/components/parameters/company_id' - $ref: '#/components/parameters/automation_id' responses: '204': description: Automation rule successfully deleted. '400': description: Bad Request content: application/json: schema: type: object required: - data properties: data: type: object required: - message properties: message: type: string oneOf: - pattern: ^Automation is not enabled for this company\.$ - pattern: ^This automation rule has already been deleted\.$ '404': description: Not Found content: application/json: schema: type: object required: - data properties: data: type: object required: - message properties: message: type: string oneOf: - pattern: ^Unknown automation rule\.$ components: schemas: meta: description: Metadata of the request type: object required: - meta properties: meta: type: object required: - request_id properties: request_id: oneOf: - $ref: '#/components/schemas/uuid' - $ref: '#/components/schemas/request_id' query_parameters: $ref: '#/components/schemas/query_parameters' request_id: type: string pattern: '[0-9]-[0-9a-fA-F]{8}-[0-9a-fA-F]{24}' description: Request identifier. automation_rule_create_raw_data: description: Data for creating an automation rule type: object required: - type - attributes properties: type: type: string enum: - automation_rule attributes: type: object required: - source_wallet_id - rule_type - trigger_event - amount_mode properties: source_wallet_id: description: ID of the wallet that triggers the automation allOf: - $ref: '#/components/schemas/uuid' rule_type: type: string enum: - conversion - payout description: Type of automation (conversion or payout) trigger_event: type: string enum: - payin_completed - conversion_completed description: Event that triggers the automation amount_mode: type: string enum: - full - inherited description: How much to convert/payout destination_wallet_id: description: ID of the destination wallet (required for conversion rules) allOf: - $ref: '#/components/schemas/uuid' destination_beneficiary_id: description: ID of the destination beneficiary (required for payout rules) allOf: - $ref: '#/components/schemas/uuid' automation_rule_update_raw_data: description: Data for updating an automation rule type: object required: - type - attributes properties: type: type: string enum: - automation_rule attributes: type: object required: - source_wallet_id - rule_type - trigger_event - amount_mode properties: source_wallet_id: description: ID of the wallet that triggers the automation allOf: - $ref: '#/components/schemas/uuid' rule_type: type: string enum: - conversion - payout description: Type of automation (conversion or payout) trigger_event: type: string enum: - payin_completed - conversion_completed description: Event that triggers the automation amount_mode: type: string enum: - full - inherited description: How much to convert/payout destination_wallet_id: description: ID of the destination wallet (required for conversion rules) allOf: - $ref: '#/components/schemas/uuid' destination_beneficiary_id: description: ID of the destination beneficiary (required for payout rules) allOf: - $ref: '#/components/schemas/uuid' uuid: type: string pattern: '[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}' description: 128-bit value used to uniquely identify an object. example: 123e4567-e89b-12d3-a456-426614174000 pagination: description: Information about the pagination of the request type: object required: - meta properties: meta: type: object required: - total_results - query_parameters properties: total_results: description: The total number of results type: number example: 100 query_parameters: allOf: - $ref: '#/components/schemas/query_parameters' required: - page_number - page_size - sort properties: page_number: type: number example: 1 page_size: type: number example: 100 sort: type: string example: created_at automation_rule_data: description: Automation rule information type: object required: - id - type - attributes properties: id: $ref: '#/components/schemas/uuid' type: type: string enum: - automation_rule attributes: type: object required: - rule_type - trigger_event - amount_mode - status - source - destination - created_by - created_at - updated_at properties: rule_type: type: string enum: - conversion - payout description: Type of automation (conversion or payout) trigger_event: type: string enum: - payin_completed - conversion_completed description: Event that triggers the automation amount_mode: type: string enum: - full - inherited description: How much to convert/payout status: type: string enum: - active - deleted description: Current status of the automation rule source: type: object required: - wallet_id - wallet_name - asset properties: wallet_id: $ref: '#/components/schemas/uuid' wallet_name: type: string asset: type: string destination: type: object properties: wallet_id: $ref: '#/components/schemas/uuid' wallet_name: type: string asset: type: string beneficiary_id: $ref: '#/components/schemas/uuid' beneficiary_description: type: string created_by: $ref: '#/components/schemas/uuid' created_at: type: string format: date-time updated_at: type: string format: date-time query_parameters: description: Information about the parameters in the request. All query string parameters provided (or implicit/with default value) will be returned type: object parameters: company_id: name: company_id in: path required: true description: The Company ID given by Fipto. example: 9de0691c-bc8d-409b-8f40-75d4f45db2f3 schema: $ref: '#/components/schemas/uuid' automation_id: name: automation_id in: path required: true description: The Automation Rule ID. example: 9de0691c-bc8d-409b-8f40-75d4f45db2f3 schema: $ref: '#/components/schemas/uuid' page_number: name: page_number in: query required: false description: The page number retrieved in the paginated results. The default value is 1. schema: type: number example: 1 page_size_optional: name: page_size in: query required: false description: The number of items to include in each page of the paginated results. The default value is 100. The pagination is removed when the value is 0 (unlimited number of elements are returned). schema: type: number example: 100 x-topics: - title: Authentication content: "# Getting Started\n\nBefore using the API you need to generate a private/public key pair using:\n\n openssl genrsa -out private-key.rsa 2048\n openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private-key.rsa -out private-key.pem\n openssl rsa -in private-key.rsa -pubout -out public-key.pem\n\nAfter sending us the public key by email, you will receive an api key, referred below as `keyId`.\n\n## HTTP request signing\n\nAll authenticated requests must include the following headers:\n\n- `Host`: target host of the request, e.g. \"api.fipto.app\"\n- `Date`: time of creation of the request, in RFC1123 format\n- `Signature`: signature of the request (see below)\n\nIn addition, requests with a body (POST, PUT, PATCH) must include:\n\n- `Content-Type`: MIME type of the body, e.g. \"application/json\"\n- `Digest`: base64-encoded SHA-256 hash of the body, in the format SHA-256=\n\n`Date` values are expected to be earlier than the present time, but not\nearlier than 1 minute.\n\n`Digest` values must obviously match to the actual hashes of their request\nbodies. The way of getting the digest is language-dependent but a basic\nUNIX approach would be\n\n echo -n $BODY | openssl dgst -sha256 -binary | openssl enc -base64 -A\n\nwhere $BODY contains the string representation of the request body.\n\n### Signature header\n\nRequests are signed and verified using the [HTTP signatures protocol](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12).\nLibraries exist in different languages for building signed requests using that\nprotocol. We focus here on our specific requirements.\n\nWe expect the authentication data to be present in a `Signature` header.\n\nThe \"signing string\" itself should contain all the headers mentioned in the previous section,\nas well as the `(request-target)` pseudo-header (see [section 2.3](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12#section-2.3)).\n\nFor example, the signing string of a POST request would look like:\n\n (request-target): post /companies/c240e5bf-863e-4f44-91aa-cc74a8b3303f/wallets\n host: api.demo.fipto.tech\n date: Fri, 24 Jan 2025 08:56:30 GMT\n content-type: application/json\n digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n\nThat string must then be signed using the RSA-256 algorithm, encoded in base64 and\nincluded in the `signature` field of the header.\n\nThe following constraints apply to other fields:\n\n- the `keyId` field must contain the UUID of your API user\n- the `headers` field must contain `(request-target)` as well as all the headers mentioned above\n- the `algorithm` field must be \"hs2019\" (or its synonym \"rsa-sha256\")\n\nThe final header of a POST request should look like:\n\n Signature: keyId=\"\",algorithm=\"hs2019\",headers=\"(request-target) host date content-type digest\",signature=\"\"\n"