Payment APIs Documentation

Base URL & Environments

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

https://api.finvypay.com

The difference between production and sandbox environments is in the API path:

https://api.finvypay.com/api/v1/production/...

https://api.finvypay.com/api/v1/sandbox/...

Authentication

All payment API endpoints require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer your_api_key_or_sandbox_api_key

You can obtain your API keys from your merchant dashboard after completing the onboarding process.

API Versioning

The Payment API uses versioning in the URL path. The current version is v1.

/api/v1/production/card
/api/v1/sandbox/card

Request & Response Format

Content-Type

All requests must include the Content-Type: application/json header.

Request Body

Request bodies should be JSON-encoded objects.

Response Format

All responses are JSON objects. Successful responses return a 200 OK status code.

{
  "success": true,
  "data": {
    "transactionId": "TXN-20240101-ABC123",
    "status": "SUCCESS",
    "amount": 100.50,
    "currency": "USD"
  }
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request parameters are invalid",
    "details": {
      "field": "amount",
      "reason": "Amount must be greater than 0"
    }
  }
}

Rate Limits

To ensure fair usage and system stability, API requests are rate-limited:

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Idempotency

For payment endpoints, you can include an idempotencyKey in the request header to ensure that duplicate requests are not processed multiple times:

Idempotency-Key: unique-key-per-request

If you make the same request (with the same idempotency key) multiple times, only the first request will be processed. Subsequent requests will return the same response as the first request.

Webhooks

Webhooks allow you to receive real-time notifications about transaction status changes. Configure your webhook URL when creating a payment, and we will send POST requests to your endpoint when events occur.

Webhook requests include a signature header for verification:

fs-webhook-hash: HMAC-SHA256 signature

Payment Statuses

Transactions can have the following statuses:

Quick Start

Ready to get started? Here's a quick example of processing a card payment:

curl -X POST https://api.finvypay.com/api/v1/sandbox/card \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_or_sandbox_api_key" \
  -d '{
    "orderId": "ORD-12345",
    "amount": 100.50,
    "currency": "USD",
    "cardNumber": "4111111111111111",
    "cardExpiryMonth": 12,
    "cardExpiryYear": 2025,
    "cvv": "123",
    "cardholderName": "John Doe",
    "email": "john@example.com"
  }'

API Categories