Skip to main content

API Reference

Welcome to the Finternet Payment Gateway API reference. This section provides detailed documentation for all API endpoints, request parameters, and response formats.

Base URL​

All API requests are made to:

https://sandbox.pg.api.finternetlab.io/v1
Sandbox Environment

🧪 Current Environment: This is the sandbox environment for testing and development.

🚀 Production API will be available once deployed.

For testing and development, use:

http://localhost:3000/api/v1

Authentication​

All API requests require authentication using an API key. Include your API key in the request header:

X-API-Key: sk_test_your_key_here

See Authentication for detailed information.

Request Format​

Content-Type​

All POST and PUT requests must include:

Content-Type: application/json

Request Body​

Request bodies should be JSON objects:

{
  "amount": "100.00",
  "currency": "USDC",
  "type": "DELIVERY_VS_PAYMENT"
}

Response Format​

All API responses follow a consistent structure:

{
  "id": "intent_2xYz9AbC123",
  "object": "payment_intent",
  "status": "SUCCEEDED",
  "data": {
    // Resource-specific data
  },
  "created": 1704067200,
  "updated": 1704067200
}

Response Fields​

FieldTypeDescription
idstringUnique identifier for the resource
objectstringType of object (e.g., payment_intent)
statusstringCurrent status of the resource
dataobjectResource-specific data
createdintegerUnix timestamp of creation
updatedintegerUnix timestamp of last update

HTTP Status Codes​

The API uses standard HTTP status codes:

CodeMeaning
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Missing or invalid API key
403Forbidden - Access denied
404Not Found - Resource doesn't exist
500Internal Server Error
503Service Unavailable

Error Responses​

When an error occurs, the API returns an error object:

{
  "error": {
    "code": "invalid_request",
    "message": "The amount must be greater than 0",
    "type": "invalid_request_error",
    "param": "amount"
  }
}

Error Object Fields​

FieldTypeDescription
codestringMachine-readable error code
messagestringHuman-readable error message
typestringError type (e.g., invalid_request_error)
paramstring(Optional) Parameter that caused the error

See Error Codes for a complete list of error codes.

Rate Limits​

API requests are subject to rate limits:

  • Test keys: 100 requests per minute
  • Live keys: 1000 requests per minute

Rate limit information is included in response headers:

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

See Rate Limits for more information.

Pagination​

List endpoints support pagination using limit and starting_after parameters:

GET /v1/payment-intents?limit=10&starting_after=intent_123

Versioning​

The API is versioned. The current version is v1. Include the version in the URL:

https://sandbox.pg.api.finternetlab.io/v1/payment-intents

Idempotency​

POST requests support idempotency keys to prevent duplicate operations:

Idempotency-Key: unique-key-here

If you retry a request with the same idempotency key within 24 hours, you'll receive the same response.

Webhooks​

Finternet can send webhooks to notify you of payment events. See Webhooks for setup and event types.

Next Steps​