Financier API v1

This reference documents the Financier API v1 integration.

Base URL

Sandbox:    https://sandbox.swapenergies/api/v1
Production: https://portal.swapenergies/api/v1

The API is JSON-only. Use the base URL for the environment you are working with.

Authentication

POST /login is public. Every other route requires an access token:

Authorization: Bearer <access-token>
Accept: application/json

Common query parameters

Collection endpoints that paginate accept these optional query parameters:

Parameter	Type	Default	Description
page	integer	1	Page number.
per_page	integer	15	Number of records per page.

Paginated responses include the named collection key, such as riders, engines, or transactions, together with pagination metadata.

Endpoint summary

Method	Path	Auth	Description
POST	/login	No	Authenticate a financier.
GET	/riders	Yes	List riders.
POST	/rider/create	Yes	Create a rider.
GET	/rider/{rider}	Yes	Retrieve a rider.
PUT	/rider/{rider}/update	Yes	Update a rider.
DELETE	/rider/{rider}/delete	Yes	Delete a rider.
PATCH	/rider/{rider}/suspend	Yes	Suspend a rider.
PATCH	/rider/{rider}/resume	Yes	Resume a rider.
GET	/engines	Yes	List engines.
GET	/engine/{engine}	Yes	Retrieve an engine.
GET	/codes	Yes	List codes.
GET	/claims	Yes	List claims.
GET	/claim/{claim}	Yes	Retrieve a claim.
GET	/claim/{claim}/code	Yes	Retrieve a claim's code.
GET	/claim/{claim}/transaction	Yes	Retrieve a claim's transaction.
GET	/credits	Yes	List credits.
POST	/credit/create	Yes	Create a credit.
POST	/credit/preview	Yes	Preview a credit.
GET	/credit/{credit}	Yes	Retrieve a credit.
PUT	/credit/{credit}/update	Yes	Update a credit.
DELETE	/credit/{credit}/delete	Yes	Delete a credit.
GET	/credit/{credit}/payments	Yes	List payments for a credit.
GET	/credit/{credit}/transactions	Yes	List transactions for a credit.
GET	/transactions	Yes	List transactions.
POST	/upload	Yes	Upload a file.

Authentication

Login

POST /login
Content-Type: application/json
Accept: application/json

Request body:

Field	Type	Required	Description
client_id	string	Yes	Integration client identifier issued to your organisation.
client_secret	string	Yes	Integration secret issued to your organisation.

Example:

{
  "client_id": "<your-client-id>",
  "client_secret": "<your-client-secret>"
}

Successful response:

{
  "token": "<access-token>",
  "expires_at": 1793270400
}

expires_at is a Unix timestamp for token expiry. Invalid credentials return a validation error.

Riders

Rider route parameters use the rider identifier returned by the API.

List riders

GET /riders?page=1&per_page=15

Response envelope: { "riders": [...] } with pagination metadata.

Create a rider

POST /rider/create
Content-Type: application/json

Required fields are firstname, lastname, phone, address, state, country, earnings, identification, ownership, passport, and signature. Optional fields are email and bvn.

Field	Type	Rules
firstname	string	Required; letters, dashes, and underscores.
lastname	string	Required; letters, dashes, and underscores.
email	string	Optional; valid email and unique among riders.
phone	string	Required; Nigerian phone format and unique.
address	string	Required.
state	string	Required.
country	string	Required.
bvn	string	Optional; unique 11-digit value.
earnings	number	Required; minimum 0.
identification	URL	Required.
ownership	URL	Required.
passport	URL	Required.
signature	URL	Required.

Response envelope: { "rider": { ... } }.

Retrieve a rider

GET /rider/{rider}

Response envelope: { "rider": { ... } }.

Update a rider

PUT /rider/{rider}/update
Content-Type: application/json

The request uses the same fields as creation except email is not accepted by the active update rules, and document URLs are optional and nullable. firstname, lastname, phone, address, state, country, and earnings remain required. bvn is optional and must be a unique 11-digit value.

Response envelope: { "rider": { ... } }.

Delete a rider

DELETE /rider/{rider}/delete

Successful response:

{ "message": "Rider deleted successfully" }

Suspend or resume a rider

PATCH /rider/{rider}/suspend
PATCH /rider/{rider}/resume

Successful responses contain a message and the updated rider resource. The messages are Rider suspended successfully and Rider resumed successfully.

Engines

List engines

GET /engines?page=1&per_page=15

Response envelope: { "engines": [...] } with pagination metadata.

Retrieve an engine

GET /engine/{engine}

Response envelope: { "engine": { ... } }.

An engine resource includes its identifier, model, URL, serial number, status, allocation status, activation date, related financier, related rider, related stock, and timestamps.

Codes

List codes

GET /codes?page=1&per_page=15

Response envelope: { "codes": [...] } with pagination metadata. Each code includes its id, value, claims_remaining, related order and claim when loaded, rider name, validation timestamp, and timestamps.

Claims

List claims

GET /claims?page=1&per_page=15

Response envelope: { "claims": [...] } with pagination metadata.

Claim detail and related lookups

GET /claim/{claim}
GET /claim/{claim}/code
GET /claim/{claim}/transaction

These endpoints provide claim details and related lookups.

Credits

List credits

GET /credits

Response envelope: { "credits": [...] }. This endpoint currently returns all credits and does not apply pagination parameters.

Create a credit

POST /credit/create
Content-Type: application/json

Request body:

Field	Type	Required	Description
rider	integer	Yes	Existing rider ID.
total_amount	number	Yes	Credit amount; minimum 0.
number_of_repayments	integer	Yes	Minimum 1.
repayment_per_swap	number	Yes	Repayment amount per swap; minimum 0.

Response envelope: { "credit": { ... } }.

Preview a credit

POST /credit/preview
Content-Type: application/json

The preview endpoint accepts the same credit inputs as the create endpoint and returns a preview response without creating a credit.

Retrieve, update, or delete a credit

GET /credit/{credit}
PUT /credit/{credit}/update
DELETE /credit/{credit}/delete

The update body uses the same four fields and validation rules as credit creation.

The detail and update responses use { "credit": { ... } }. A successful delete returns { "message": "Credit deleted successfully." }.

A credit resource includes rider details, amount and repayment fields, paid and skipped sequences, remaining balance, credit type, agreement media, repayment history, activation/completion times, and timestamps.

List credit payments

GET /credit/{credit}/payments

Response envelope: { "payments": [...] }.

List credit transactions

GET /credit/{credit}/transactions?page=1&per_page=15

Response envelope: { "transactions": [...] } with pagination metadata.

Transactions

List transactions

GET /transactions?page=1&per_page=15

Response envelope: { "transactions": [...] } with pagination metadata. A transaction resource includes id, reference, pid, platform, description, amount, transactable, agent, verification and success flags, status, type, and timestamps.

File uploads

Upload a file

POST /upload
Content-Type: multipart/form-data

Form field:

Field	Type	Required	Description
file	file	Yes	File to upload.

Successful response:

{
  "message": "File uploaded successfully.",
  "file": "<file-reference>"
}

Error responses

Validation failures normally return HTTP 422:

{
  "message": "The given data was invalid.",
  "errors": {
    "field": ["The field is required."]
  }
}

Unauthenticated requests to protected endpoints require a valid bearer token. Requests for unknown resource identifiers return a not-found response.