API Reference

Base URL

All API requests should be made to the following base URL:

https://api.sevenpayments.money/v1

Authentication

All API requests require an API key for authentication. Include your API key in the Authorization header of each request.

Authorization: Bearer YOUR_API_KEY

Status Codes

Status Code	Description
200	OK - Successful request
201	Created - Resource created successfully
400	Bad Request - Invalid request parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
422	Unprocessable Entity - Validation failed
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end

Resources

Accounts

Get Account Balance

GET /accounts/{account_id}/balance

Response

{
  "data": {
    "account_id": "acc_123456789",
    "currency": "USD",
    "available_balance": 12500.75,
    "current_balance": 13000.00,
    "hold_balance": 499.25,
    "last_updated": "2023-07-18T14:30:00Z"
  }
}

Transfers

Create Transfer

POST /transfers
Content-Type: application/json

{
  "source_account_id": "acc_123456789",
  "destination": {
    "type": "bank_account",
    "bank_account": {
      "account_number": "12345678",
      "routing_number": "021000021",
      "account_holder_name": "John Doe",
      "country": "US"
    }
  },
  "amount": 1000.50,
  "currency": "USD",
  "reference": "Invoice #12345",
  "description": "Client refund"
}

Response

{
  "data": {
    "id": "trx_789012345678",
    "status": "pending",
    "amount": 1000.50,
    "currency": "USD",
    "fee": 9.99,
    "source_account_id": "acc_123456789",
    "destination": {
      "type": "bank_account",
      "bank_account": {
        "last_four": "5678",
        "bank_name": "JPMORGAN CHASE BANK, N.A.",
        "country": "US"
      }
    },
    "reference": "Invoice #12345",
    "description": "Client refund",
    "created_at": "2023-07-18T14:35:22Z",
    "estimated_arrival_date": "2023-07-20"
  }
}

Get Transfer Status

GET /transfers/{transfer_id}

Response

{
  "data": {
    "id": "trx_789012345678",
    "status": "completed",
    "amount": 1000.50,
    "currency": "USD",
    "fee": 9.99,
    "source_account_id": "acc_123456789",
    "destination": {
      "type": "bank_account",
      "bank_account": {
        "last_four": "5678",
        "bank_name": "JPMORGAN CHASE BANK, N.A.",
        "country": "US"
      }
    },
    "reference": "Invoice #12345",
    "description": "Client refund",
    "created_at": "2023-07-18T14:35:22Z",
    "completed_at": "2023-07-18T15:10:05Z",
    "tracking_url": "https://sevenpayments.money/transfers/trx_789012345678"
  }
}

Exchange Rates

Get Exchange Rate

GET /exchange-rates?from=USD&to=EUR&amount=100

Query Parameters

Parameter	Type	Required	Description
from	string	Yes	Source currency code (e.g., USD)
to	string	Yes	Target currency code (e.g., EUR)
amount	number	No	Amount to convert (default: 1)

Response

{
  "data": {
    "from_currency": "USD",
    "to_currency": "EUR",
    "exchange_rate": 0.8923,
    "amount": 100.00,
    "converted_amount": 89.23,
    "last_updated": "2023-07-18T14:00:00Z",
    "expires_at": "2023-07-18T15:00:00Z"
  }
}

Beneficiaries

Add Beneficiary

POST /beneficiaries
Content-Type: application/json

{
  "type": "bank_account",
  "bank_account": {
    "account_number": "12345678",
    "routing_number": "021000021",
    "account_holder_name": "John Doe",
    "account_type": "checking",
    "country": "US",
    "currency": "USD"
  },
  "nickname": "John's Chase Account"
}

Response

{
  "data": {
    "id": "ben_987654321",
    "type": "bank_account",
    "bank_account": {
      "last_four": "5678",
      "bank_name": "JPMORGAN CHASE BANK, N.A.",
      "account_holder_name": "John Doe",
      "account_type": "checking",
      "country": "US",
      "currency": "USD"
    },
    "nickname": "John's Chase Account",
    "created_at": "2023-07-18T14:40:15Z"
  }
}

Webhooks

Seven sends webhooks to notify your application about important events. Configure your webhook endpoint in the dashboard.

Webhook Events

• transfer.created - A new transfer was created
• transfer.completed - A transfer was successfully completed
• transfer.failed - A transfer has failed
• account.updated - Account details or balance has been updated

Webhook Payload Example

{
  "event": "transfer.completed",
  "data": {
    "id": "trx_789012345678",
    "status": "completed",
    "amount": 1000.50,
    "currency": "USD",
    "reference": "Invoice #12345"
  },
  "created_at": "2023-07-18T15:10:05Z"
}

Rate Limiting

API requests are limited to 1000 requests per hour per API key. The following headers are included in each response:

• X-RateLimit-Limit: The maximum number of requests allowed in the current period
• X-RateLimit-Remaining: The number of requests remaining in the current period
• X-RateLimit-Reset: The time at which the current rate limit window resets (UTC epoch seconds)

Error Handling

Error responses follow this format:

{
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient funds in the source account",
    "details": {
      "available_balance": 500.00,
      "requested_amount": 1000.50,
      "currency": "USD"
    }
  }
}

Pagination

List endpoints support pagination using the following query parameters:

• page: Page number (default: 1)
• per_page: Items per page (default: 25, max: 100)

Pagination metadata is included in the response:

{
  "data": [],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 25,
    "total_pages": 4
  },
  "links": {
    "first": "/transfers?page=1",
    "last": "/transfers?page=4",
    "prev": null,
    "next": "/transfers?page=2"
  }
}