API Overview

The X-Link P2P API is a RESTful API that enables secure peer-to-peer payment processing. This overview provides essential information about working with our API.

Base URLs

Environment	Base URL
Production	https://api.x-link.asia/api/v1/p2p
Staging	https://api.stage.x-link.asia/api/v1/p2p

API Endpoints

Core Endpoints

Method	Endpoint	Description
POST	/p2p/sessions	Initialize a payment session
GET	/p2p/sessions/{session_id}	Get session details
POST	/p2p/operations	Create an operation from session
GET	/p2p/operations/{shop_id}/{operation_number}	Get operation details
GET	/p2p/payment-method-types	List available payment methods

Request Format

Headers

All requests must include these headers:

x-api-key: your-api-key-here
Content-Type: application/json

Request Body

Request bodies should be JSON formatted:

{
  "shop_id": 1,
  "payment_method_type_id": "550e8400-e29b-41d4-a716-446655440000",
  "operation_type": "PAYIN",
  "operation_number": "ORDER-12345",
  "payer_id": "customer-123",
  "amount": "100.00",
  "currency": "USD"
}

Response Format

Successful Response

{
  "session_id": "550e8400-e29b-41d4-a716-446655440001",
  "expired_at": "2024-12-25T10:30:00Z",
  "payer_requisites": {
    "card_number": "****1234"
  },
  "payment_method_requisites": {
    "card_number": "4242424242424242",
    "card_holder": "JOHN DOE",
    "expiry_date": "12/25"
  }
}

Note: Swagger UI may show additionalProp1/2/3 for objects that allow arbitrary keys (additionalProperties). These are placeholders, not real API fields.

Error Response

{
  "detail": "Session not found"
}

Data Types

Operation Types

Value	Description
PAYIN	Incoming payment (receiving money)
PAYOUT	Outgoing payment (sending money)

Operation Status

Status	Description
PENDING	Operation created, awaiting processing
PROCESSING	Operation is being processed
SUCCESS	Operation completed successfully
FAILED	Operation failed
CANCELLED	Operation was cancelled
REFUNDED	Operation was refunded
DECLINED	Operation was declined

Session Status

Status	Description
active	Session created and awaiting action/callback
used	Session successfully completed
expired	Session expired or finished unsuccessfully

Currencies

The API supports standard ISO 4217 currency codes:

• USD - US Dollar
• EUR - Euro
• GBP - British Pound
• RUB - Russian Ruble
• And more...

Pagination

List endpoints support pagination:

GET /p2p/payment-method-types?shop_id=1&operation_type=PAYIN&page=1&size=20

Response includes pagination metadata:

{
  "data": [...],
  "page": 1,
  "size": 20,
  "total": 100,
  "pages": 5
}

Filtering and Sorting

Filtering

Apply filters using query parameters:

GET /p2p/operations?operation_type=PAYIN&status=SUCCESS

Sorting

Sort results using sort_by and sort_type:

GET /operations?sort_by=created_at&sort_type=desc

Rate Limits

Limit Type	Value
Requests per minute	1000
Burst limit	100/second

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1628856000

HTTP Status Codes

Code	Description
200	Success
201	Created
204	No Content
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid authentication
403	Forbidden - Missing or invalid API key
404	Not Found - Resource doesn't exist
422	Unprocessable Entity - Validation error
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Idempotency

For safe retries, use unique operation_number values:

{
  "operation_number": "ORDER-12345-UNIQUE"
}

The API will return the same response for duplicate requests with the same operation_number.

Versioning

The API version is included in the URL path:

/api/v1/p2p/...

We maintain backward compatibility within major versions. Breaking changes will be introduced in new major versions.