Movements

The Movements API allows you to retrieve transaction history and movement details for user accounts. This includes filtering, pagination, and advanced querying capabilities using GraphQL.

The Movement Object

{
  "id": 789012,
  "amount": 10000,
  "currency": "USD",
  "state": "completed",
  "reference": "REF-123",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:31:00Z",
  "balanceBefore": 140000,
  "balanceAfter": 150000
}

Attributes

Attribute	Type	Description
id	integer	Unique identifier for the movement
amount	integer	Movement amount in cents
currency	string	Currency code (USD, EUR, etc.)
state	string	Movement state (pending, completed, failed, cancelled)
reference	string	External reference or transaction ID
createdAt	string	ISO 8601 timestamp when movement was created
completedAt	string	ISO 8601 timestamp when movement was completed
balanceBefore	integer	Account balance before the movement in cents
balanceAfter	integer	Account balance after the movement in cents

List Movements

Returns a list of movements for the authenticated user with optional filtering and pagination.

GET/movements/

curl -X GET "https://sandbox.tropipay.me/api/v3/movements/?limit=20&offset=0" \
  -H "Authorization: Bearer sk_test_..."

Parameters

Parameter	Type	Required	Description
limit	integer	No	Number of results to return (max: 50, default: 20)
offset	integer	No	Number of records to skip (default: 0)
query	string	No	JSON-encoded filter object

Query Filter Object

The query parameter accepts a JSON-encoded object with the following optional fields:

{
  "state": ["completed", "pending"],
  "currency": "USD",
  "amountGte": 1000,
  "amountLte": 100000,
  "createdAtFrom": "2024-01-01T00:00:00Z",
  "createdAtTo": "2024-12-31T23:59:59Z",
  "reference": "REF-123"
}

Filter	Type	Description
state	array	Filter by movement states
currency	string	Filter by currency
amountGte	integer	Minimum amount in cents
amountLte	integer	Maximum amount in cents
createdAtFrom	string	Start date (ISO 8601)
createdAtTo	string	End date (ISO 8601)
reference	string	Filter by reference

Response

{
  "items": [
    {
      "id": 789012,
      "amount": 10000,
      "currency": "USD",
      "state": "completed",
      "reference": "REF-123",
      "createdAt": "2024-01-15T10:30:00Z",
      "completedAt": "2024-01-15T10:31:00Z",
      "balanceBefore": 140000,
      "balanceAfter": 150000
    }
  ],
  "totalCount": 1,
  "hasMore": false
}

Response Parameters

Parameter	Type	Description
items	array	Array of movement objects
totalCount	integer	Total number of movements matching the query
hasMore	boolean	Whether there are more results available

List Account Movements

Returns movements for a specific account.

GET/accounts/{accountId}/movements

curl -X GET https://sandbox.tropipay.me/api/v3/accounts/acc_123/movements \
  -H "Authorization: Bearer sk_test_..."

Parameters

Same parameters as the general movements endpoint, but filtered to the specified account.

Advanced Movements Query (GraphQL)

For complex queries and advanced filtering, use the GraphQL endpoint.

POST/movements/business

curl -X POST https://sandbox.tropipay.me/api/v3/movements/business \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetMovements($filter: MovementFilter, $pagination: Pagination) { movements(filter: $filter, pagination: $pagination) { items { id amount state currency createdAt recipient { name email } sender { name email } } totalCount } }",
    "variables": {
      "filter": {
        "state": ["completed", "pending"],
        "amountGte": 100,
        "amountLte": 100000,
        "createdAtFrom": "2024-01-01T00:00:00Z",
        "createdAtTo": "2024-12-31T23:59:59Z"
      },
      "pagination": {
        "limit": 20,
        "offset": 0
      }
    }
  }'

GraphQL Schema

MovementFilter

input MovementFilter {
  state: [MovementState!]
  currency: String
  amountGte: Int
  amountLte: Int
  createdAtFrom: DateTime
  createdAtTo: DateTime
  reference: String
  accountId: String
}

Pagination

input Pagination {
  limit: Int
  offset: Int
}

Movement Type

type Movement {
  id: ID!
  amount: Int!
  currency: String!
  state: MovementState!
  reference: String
  createdAt: DateTime!
  completedAt: DateTime
  balanceBefore: Int!
  balanceAfter: Int!
  recipient: User
  sender: User
  account: Account!
}

MovementState Enum

enum MovementState {
  PENDING
  COMPLETED
  FAILED
  CANCELLED
}

GraphQL Response

{
  "data": {
    "movements": {
      "items": [
        {
          "id": "789012",
          "amount": 10000,
          "state": "COMPLETED",
          "currency": "USD",
          "createdAt": "2024-01-15T10:30:00Z",
          "recipient": {
            "name": "John",
            "email": "john@example.com"
          },
          "sender": {
            "name": "Jane",
            "email": "jane@example.com"
          }
        }
      ],
      "totalCount": 1
    }
  }
}

Refund a Transaction

Allows a user to refund a previously completed transaction.

POST/movements/in/refund

Authentication:

• Requires user authentication (JWT token)
• Requires Two-Factor Authentication (2FA) enabled
• Requires ALLOW_REFUND permission

curl -X POST https://sandbox.tropipay.me/api/v3/movements/in/refund \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "orderCode": "ORD-123456",
    "amount": 5000
  }'

Request Body Parameters

Parameter	Type	Required	Description
orderCode	string	Yes	Code of the order/transaction to refund
amount	number	Yes	Amount to refund in cents

Response

Status Code: 200 OK

Returns a booking object with the details of the generated refund.

{
  "id": 123456,
  "orderCode": "ORD-123456",
  "amount": 5000,
  "currency": "USD",
  "state": "completed",
  "type": "refund",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:31:00Z"
}

Error Responses

Status Code	Description
400	Bad Request - Missing required parameters or invalid values
401	Unauthorized - User not authenticated
403	Forbidden - User doesn't have ALLOW_REFUND permission or 2FA not enabled
404	Not Found - Order code doesn't exist
500	Internal Server Error - Error during refund processing

Example Error Response

{
  "error": {
    "type": "permission_error",
    "code": "missing_permission",
    "message": "User does not have ALLOW_REFUND permission"
  }
}

Notes

• The refund is processed as a client-initiated request
• Both the order code and amount must be valid
• The transaction must be in a refundable state
• 2FA must be enabled on the user account

---

Movement States

State	Description
pending	Movement is being processed
completed	Movement has been successfully completed
failed	Movement failed due to an error
cancelled	Movement was cancelled by user or system

Pagination

All movement endpoints support pagination using limit and offset parameters:

• limit: Maximum number of results to return (1-50, default: 20)
• offset: Number of records to skip (default: 0)

Example Pagination

# Get first 20 movements
curl -X GET "https://sandbox.tropipay.me/api/v3/movements/?limit=20&offset=0"

# Get next 20 movements
curl -X GET "https://sandbox.tropipay.me/api/v3/movements/?limit=20&offset=20"

Error Handling

The Movements API uses conventional HTTP response codes to indicate the success or failure of an API request.

Common Error Codes

Code	Description
400	Bad Request - Invalid query parameters
401	Unauthorized - Invalid authentication
403	Forbidden - Insufficient permissions
404	Not Found - Account or movement doesn't exist
422	Unprocessable Entity - Invalid filter parameters
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Example Error Response

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_filter",
    "message": "Invalid date format in createdAtFrom parameter",
    "param": "query.createdAtFrom"
  }
}

Best Practices

1. Use pagination for large result sets to improve performance
2. Filter by date range to limit the scope of your queries
3. Use specific states to get only the movements you need
4. Cache results when appropriate to reduce API calls
5. Use GraphQL for complex queries requiring related data