{
  "openapi": "3.1.0",
  "info": {
    "title": "Blaaiz Platform API - List Transactions",
    "version": "1.0.0",
    "description": "Retrieve a paginated list of completed API transactions for your business. Transaction responses now include `swap_details` for swap transactions."
  },
  "tags": [
    {
      "name": "Transaction"
    }
  ],
  "servers": [
    {
      "url": "https://api-prod.blaaiz.com"
    },
    {
      "url": "https://api-dev.blaaiz.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "oauth2ClientCredentials": {
        "type": "oauth2",
        "description": "Use your OAuth client credentials to obtain a short-lived Bearer token from POST /oauth/token.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "/oauth/token",
            "scopes": {
              "transaction:read": "Read transactions."
            }
          }
        }
      }
    },
    "schemas": {
      "TransactionListRequest": {
        "type": "object",
        "properties": {
          "start_date": {
            "type": "string",
            "format": "date",
            "description": "Filter transactions created on or after this date."
          },
          "end_date": {
            "type": "string",
            "format": "date",
            "description": "Filter transactions created on or before this date. Must be the same as or after `start_date`."
          },
          "wallet_id": {
            "type": "string",
            "description": "Filter by business wallet ID."
          },
          "type": {
            "type": "string",
            "description": "Filter by transaction type.",
            "enum": [
              "SEND_MONEY",
              "FUND_WALLET",
              "SWAP"
            ]
          },
          "status": {
            "type": "string",
            "description": "Filter by transaction status.",
            "enum": [
              "FAILED",
              "SUCCESSFUL"
            ]
          },
          "customer_id": {
            "type": "string",
            "description": "Filter by business customer ID."
          }
        }
      },
      "SourceInformation": {
        "type": "object",
        "properties": {
          "collection_email": {
            "type": [
              "string",
              "null"
            ],
            "description": "Collection email used for Interac collections, when applicable."
          },
          "collection_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Name of the sender for Interac collections, when available."
          }
        }
      },
      "Recipient": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "account_number": {
            "type": "string"
          },
          "account_name": {
            "type": "string"
          },
          "amount": {
            "type": "number"
          },
          "currency": {
            "type": "string"
          },
          "bank_name": {
            "type": "string"
          },
          "bank_code": {
            "type": "string"
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          },
          "routing_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "SwapDetails": {
        "type": "object",
        "properties": {
          "from_business_wallet_id": {
            "type": "string",
            "description": "Source business wallet ID."
          },
          "to_business_wallet_id": {
            "type": "string",
            "description": "Destination business wallet ID."
          },
          "from_currency": {
            "type": "string",
            "description": "Source wallet currency."
          },
          "from_amount": {
            "type": "number",
            "description": "Amount swapped from the source wallet."
          },
          "from_amount_without_fee": {
            "type": "number",
            "description": "Source amount after fees."
          },
          "to_currency": {
            "type": "string",
            "description": "Destination wallet currency."
          },
          "to_amount": {
            "type": "number",
            "description": "Amount credited to the destination wallet."
          },
          "amount_type": {
            "type": "string",
            "enum": [
              "from",
              "to"
            ],
            "description": "How the swap request amount was interpreted."
          },
          "exchange_rate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Applied exchange rate."
          }
        },
        "required": [
          "from_business_wallet_id",
          "to_business_wallet_id",
          "from_currency",
          "from_amount",
          "from_amount_without_fee",
          "to_currency",
          "to_amount",
          "amount_type",
          "exchange_rate"
        ]
      },
      "TransactionListItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Transaction ID."
          },
          "business_id": {
            "type": "string",
            "description": "Business ID."
          },
          "business_customer_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Business customer ID when the transaction is tied to a customer."
          },
          "business_wallet_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Primary business wallet ID recorded on the transaction."
          },
          "status": {
            "type": "string",
            "description": "Transaction status."
          },
          "type": {
            "type": "string",
            "description": "Normalized transaction type returned by the API. Possible values are `collection`, `payout`, and `swap`."
          },
          "reference": {
            "type": "string",
            "description": "Transaction reference."
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "Source currency for the transaction."
          },
          "amount": {
            "type": [
              "number",
              "null"
            ],
            "description": "Gross transaction amount."
          },
          "amount_without_fee": {
            "type": [
              "number",
              "null"
            ],
            "description": "Net transaction amount after fees."
          },
          "fee": {
            "type": [
              "number",
              "null"
            ],
            "description": "Transaction fee."
          },
          "rate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Recipient exchange rate for payout transactions."
          },
          "date": {
            "type": "string",
            "format": "date-time",
            "description": "Transaction creation timestamp."
          },
          "payee_collection_email": {
            "type": [
              "string",
              "null"
            ],
            "description": "Payee collection email for Interac transactions, when applicable."
          },
          "source_information": {
            "$ref": "#/components/schemas/SourceInformation"
          },
          "swap_details": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/SwapDetails"
              },
              {
                "type": "null"
              }
            ]
          },
          "recipient": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Recipient"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "business_id",
          "business_customer_id",
          "business_wallet_id",
          "status",
          "type",
          "reference",
          "currency",
          "amount",
          "amount_without_fee",
          "fee",
          "rate",
          "date",
          "payee_collection_email",
          "source_information",
          "swap_details",
          "recipient"
        ]
      },
      "PaginationLinks": {
        "type": "object",
        "properties": {
          "first": {
            "type": [
              "string",
              "null"
            ]
          },
          "last": {
            "type": [
              "string",
              "null"
            ]
          },
          "prev": {
            "type": [
              "string",
              "null"
            ]
          },
          "next": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "PaginationMeta": {
        "type": "object",
        "properties": {
          "current_page": {
            "type": "integer"
          },
          "from": {
            "type": [
              "integer",
              "null"
            ]
          },
          "last_page": {
            "type": "integer"
          },
          "path": {
            "type": "string"
          },
          "per_page": {
            "type": "integer"
          },
          "to": {
            "type": [
              "integer",
              "null"
            ]
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "TransactionListResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TransactionListItem"
            }
          },
          "links": {
            "$ref": "#/components/schemas/PaginationLinks"
          },
          "meta": {
            "$ref": "#/components/schemas/PaginationMeta"
          }
        },
        "required": [
          "message",
          "data",
          "links",
          "meta"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        },
        "required": [
          "message"
        ]
      },
      "ValidationError": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        },
        "required": [
          "message",
          "errors"
        ]
      }
    }
  },
  "paths": {
    "/api/external/transaction": {
      "post": {
        "summary": "List transactions",
        "description": "Retrieve a paginated list of completed API transactions for your business. You can filter by date range, status, customer, wallet, and transaction type. Use `type: SWAP` to return only swap transactions. Required scope: `transaction:read`.",
        "tags": [
          "Transaction"
        ],
        "security": [
          {
            "oauth2ClientCredentials": [
              "transaction:read"
            ]
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransactionListRequest"
              },
              "examples": {
                "swap_filter": {
                  "value": {
                    "start_date": "2026-03-01",
                    "end_date": "2026-03-13",
                    "status": "SUCCESSFUL",
                    "type": "SWAP"
                  }
                },
                "payout_filter": {
                  "value": {
                    "wallet_id": "wallet_123",
                    "type": "SEND_MONEY",
                    "customer_id": "customer_123"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transactions retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransactionListResponse"
                },
                "example": {
                  "message": "Transactions retrieved successfully",
                  "data": [
                    {
                      "id": "txn_collection_001",
                      "business_id": "business_123",
                      "business_customer_id": "customer_123",
                      "business_wallet_id": "wallet_ngn_001",
                      "status": "SUCCESSFUL",
                      "type": "collection",
                      "reference": "collection_ref_001",
                      "currency": "NGN",
                      "amount": 50000,
                      "amount_without_fee": 50000,
                      "fee": 0,
                      "rate": null,
                      "date": "2026-03-13T09:10:00.000000Z",
                      "payee_collection_email": "customer@company.com",
                      "source_information": {
                        "collection_email": "collections@blaaiz.com",
                        "collection_name": "John Doe"
                      },
                      "swap_details": null,
                      "recipient": null
                    },
                    {
                      "id": "txn_payout_001",
                      "business_id": "business_123",
                      "business_customer_id": "customer_123",
                      "business_wallet_id": "wallet_ngn_001",
                      "status": "SUCCESSFUL",
                      "type": "payout",
                      "reference": "payout_ref_001",
                      "currency": "NGN",
                      "amount": 50000,
                      "amount_without_fee": 49500,
                      "fee": 500,
                      "rate": null,
                      "date": "2026-03-13T10:30:00.000000Z",
                      "payee_collection_email": null,
                      "source_information": {
                        "collection_email": null,
                        "collection_name": null
                      },
                      "swap_details": null,
                      "recipient": {
                        "id": "recipient_123",
                        "account_number": "0123456789",
                        "account_name": "John Doe",
                        "amount": 50000,
                        "currency": "NGN",
                        "bank_name": "Access Bank",
                        "bank_code": "044",
                        "status": "SUCCESSFUL",
                        "routing_number": null,
                        "email": null
                      }
                    },
                    {
                      "id": "txn_swap_001",
                      "business_id": "business_123",
                      "business_customer_id": null,
                      "business_wallet_id": "wallet_usd_001",
                      "status": "SUCCESSFUL",
                      "type": "swap",
                      "reference": "swap_ref_001",
                      "currency": "USD",
                      "amount": 100,
                      "amount_without_fee": 99,
                      "fee": 1,
                      "rate": null,
                      "date": "2026-03-13T11:45:00.000000Z",
                      "payee_collection_email": null,
                      "source_information": {
                        "collection_email": null,
                        "collection_name": null
                      },
                      "swap_details": {
                        "from_business_wallet_id": "wallet_usd_001",
                        "to_business_wallet_id": "wallet_ngn_001",
                        "from_currency": "USD",
                        "from_amount": 100,
                        "from_amount_without_fee": 99,
                        "to_currency": "NGN",
                        "to_amount": 160000,
                        "amount_type": "from",
                        "exchange_rate": 1600
                      },
                      "recipient": null
                    }
                  ],
                  "links": {
                    "first": "https://api-prod.blaaiz.com/api/external/transaction?page=1",
                    "last": "https://api-prod.blaaiz.com/api/external/transaction?page=1",
                    "prev": null,
                    "next": null
                  },
                  "meta": {
                    "current_page": 1,
                    "from": 1,
                    "last_page": 1,
                    "path": "https://api-prod.blaaiz.com/api/external/transaction",
                    "per_page": 10,
                    "to": 3,
                    "total": 3
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "message": "Invalid or missing access token"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                },
                "example": {
                  "message": "The given data was invalid.",
                  "errors": {
                    "type": [
                      "The selected type is invalid."
                    ],
                    "end_date": [
                      "The end date must be a date after or equal to start date."
                    ]
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}