YuciferPay API Documentation

Base URL: https://api.yuciferpay.xyz

Interactive documentation is available at:

Swagger Docs ReDoc

Authentication

Every request must include your API key.

api-key: my-secret-key
Content-Type: application/json

If your API key is invalid, YuciferPay will return: { "code":401, "message":"Invalid Api key" }

Schedule ID Format

All routes that require a schedule_id expect the following format:

SCHEDULE-{user_id}-{serial_id}

Example:

SCHEDULE-12-001

Get your user_id from GET /user/id.
serial_id is the value supplied when creating a schedule.
You may also obtain schedule IDs using GET /get_schedules.
serial IDs cannot be reused.
serial ID can be your staff id or random numbers or letters

Get User ID

GET /user/id

Returns your YuciferPay user ID.

Request

GET https://api.yuciferpay.xyz/user/id

Headers

api-key: my-secret-key

Response

{
  "code":200,
  "message":"SUCCESS",
  "user_id":12
}

Get All Schedules

GET /get_schedules

Returns all schedules belonging to your account.

Request

GET https://api.yuciferpay.xyz/get_schedules

Headers

api-key: my-secret-key

Response

{
  "code":200,
  "message":"SUCCESS",
  "data":[
    {
      "Schedule Id":"SCHEDULE-12-001",
      "Account Name":"John Doe",
      "Bank Name":"GTBank",
      "Account No":"0123456789",
      "Amount":"5000",
      "Is_active":true,
      "Paused":false,
      "Pay date":"2026-06-22"
    }
  ]
}

Get Single Schedule

GET /get_schedule/{schedule_id}

Returns information about one schedule.

Request

GET https://api.yuciferpay.xyz/get_schedule/SCHEDULE-12-001

Headers

api-key: my-secret-key

Response

{
  "code":200,
  "message":"SUCCESS",
  "data":[
    {
      "Schedule Id":"SCHEDULE-12-001",
      "Account Name":"John Doe",
      "Bank Name":"GTBank",
      "Account No":"0123456789",
      "Amount":"5000",
      "Is_active":true,
      "Paused":false,
      "Pay date":"2026-06-22"
    }
  ]
}

Add Schedule

POST /add_schedule

Creates a new payment schedule.

Request

POST https://api.yuciferpay.xyz/add_schedule

Headers

api-key: my-secret-key
Content-Type: application/json

Body

{
  "serial_id":"001",
  "acct_name":"John Doe",
  "bank_name":"GTBank",
  "acct_num":"0123456789",
  "amount":"5000",
  "date":"2026-06-22",
  "frequency":4
}

frequency is an optional integer that specifies the interval, in weeks, between recurring payments. If omitted, the default value is 4 (monthly).

Examples:

1 – Weekly payments
2 – Biweekly payments (every 2 weeks)
4 – Monthly payments (every 4 weeks)

The generated schedule ID becomes: SCHEDULE-12-001

Response

{
  "code":200,
  "message":"SUCCESS"
}

Edit Schedule

PUT /schedule/edit/{schedule_id}

Updates an existing schedule. All fields are optional. Only supplied values will be changed.

Request

PUT https://api.yuciferpay.xyz/schedule/edit/SCHEDULE-12-001

Headers

api-key: my-secret-key
Content-Type: application/json

Body

{
  "acct_name":"John Doe",
  "bank_name":"GTBank",
  "acct_num":"0123456789",
  "amount":"10000",
  "date":"2026-06-25",
  "frequency":4
}

frequency is an integer that specifies the interval, in weeks, between recurring payments. If omitted, the default value is 4 (monthly).

Examples:

1 – Weekly payments
2 – Biweekly payments (every 2 weeks)
4 – Monthly payments (every 4 weeks)

You may provide one field or multiple fields. Missing fields remain unchanged.

Response

{
  "code":200,
  "message":"SUCCESS"
}

Delete Schedule

DELETE /schedule/{schedule_id}

Deletes an existing schedule.

Request

DELETE https://api.yuciferpay.xyz/schedule/SCHEDULE-12-001

Headers

api-key: my-secret-key

Response

{
  "code":200,
  "message":"SUCCESS"
}

Pause Schedule

POST /schedule/{schedule_id}/pause

Temporarily pauses a schedule. Paused schedules will not be processed.

Request

POST https://api.yuciferpay.xyz/schedule/SCHEDULE-12-001/pause

Headers

api-key: my-secret-key

Response

{
  "code":200,
  "message":"SUCCESS"
}

Resume Schedule

POST /schedule/{schedule_id}/unpause

Reactivates a previously paused schedule.

Request

POST https://api.yuciferpay.xyz/schedule/SCHEDULE-12-001/unpause

Headers

api-key: my-secret-key

Response

{
  "code":200,
  "message":"SUCCESS"
}

Get Orders

GET /orders

Returns every order belonging to your account.

Request

GET https://api.yuciferpay.xyz/orders

Headers

api-key: my-secret-key

Response

{
  "code":200,
  "message":"SUCCESS",
  "data":[
    {
      "Order id":"ORD-1001",
      "Account Number":"0123456789",
      "Account Name":"John Doe",
      "Bank Name":"GTBank",
      "Amount":"5000",
      "Status":"success",
      "Processed with":"Paystack",
      "Reference Id":"REF12345",
      "Is Queued":false,
      "Created At":"2026-06-23",
      "Updated At":"2026-06-23"
    }
  ]
}

Get Active Orders

GET /orders/active

Returns orders that are currently processing.

Request

GET https://api.yuciferpay.xyz/orders/active

Headers

api-key: my-secret-key

Response

{
  "code":200,
  "message":"SUCCESS",
  "data":[]
}

Get Failed Orders

GET /orders/failed

Returns orders that failed during processing.

Request

GET https://api.yuciferpay.xyz/orders/failed

Headers

api-key: my-secret-key

Response

{
  "code":200,
  "message":"SUCCESS",
  "data":[]
}

Retry Failed Orders

POST /orders/retry

Retries all failed orders belonging to your account.

Request

POST https://api.yuciferpay.xyz/orders/retry

Headers

api-key: my-secret-key

Response

{
  "code":200,
  "message":"SUCCESS"
}

Enable Automation

POST /automation/enable

Enables automatic schedule execution.

Request

POST https://api.yuciferpay.xyz/automation/enable

Headers

api-key: my-secret-key

Response

{
  "code":200,
  "message":"SUCCESS"
}

Disable Automation

POST /automation/disable

Disables automatic schedule execution.

Request

POST https://api.yuciferpay.xyz/automation/disable

Headers

api-key: my-secret-key

Response

{
  "code":200,
  "message":"SUCCESS"
}

Resolve Account

POST /resolve-account

Resolves a bank account number and returns the account holder's name.

Request

POST https://api.yuciferpay.xyz/resolve-account

Headers
api-key: my-secret-key
Content-Type: application/json

Body
{
  "bank_name": "GTBank",
  "acct_num": "0123456789"
}

bank_name is the name of the bank associated with the account.

acct_num is the bank account number to resolve.

Response

{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "account_name": "John Doe"
  }
}

The bank must be supported by the payment provider configured for your YuciferPay account.

Get Bank List

GET /get-bank-list

Returns the list of banks supported by the payment provider configured for your YuciferPay account.

Request

GET https://api.yuciferpay.xyz/get-bank-list

Headers
api-key: my-secret-key

Response

{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "bank_list": [
      "Access Bank",
      "GTBank",
      "First Bank",
      "United Bank for Africa"
    ]
  }
}

The returned bank list depends on the payment provider configured for your account.

Webhooks

YuciferPay sends webhook notifications to your configured webhook URL when a payout is successfully processed or fails.

Webhooks are sent for both recurring and one time services.

Webhook Events

YuciferPay currently supports the following webhook events:

payout.success – Sent when a payout is successfully processed.
payout.failed – Sent when a payout fails to process.

Webhook Request

YuciferPay sends a POST request to your configured webhook URL. Each request contains an X-Signature header that can be used to verify that the webhook was sent by YuciferPay.

POST https://your-domain.com/webhook

Headers
Content-Type: application/json
X-Signature: generated-signature

Successful Payout

{
  "event_id": "evt_a1b2c3d4e5f6",
  "event_type": "payout.success",
  "timestamp": "2026-06-22T14:30:00+00:00",
  "data": {
    "Schedule_id": "SCHEDULE-12-001",
    "Processed_with": "paystack",
    "Reference": "TRF_123456789",
    "Status": "success",
    "Amount": 5000,
    "Currency": "NGN"
  }
}

Failed Payout

{
  "event_id": "evt_a1b2c3d4e5f6",
  "event_type": "payout.failed",
  "timestamp": "2026-06-22T14:30:00+00:00",
  "data": {
    "Schedule_id": "SCHEDULE-12-001",
    "Processed_with": "paystack",
    "Reference": "TRF_123456789",
    "Status": "failed",
    "Amount": 5000,
    "Currency": "NGN"
  }
}

Verifying the Webhook

Each webhook request is signed using your webhook secret and the HMAC-SHA256 algorithm. The resulting signature is included in the X-Signature header.

To verify a webhook, generate an HMAC-SHA256 signature using your webhook secret and the exact JSON request body, then compare the generated signature with the value in the X-Signature header.

signature = HMAC-SHA256(
    webhook_secret,
    request_body
)

The signature is represented as a hexadecimal string.

Example Verification (Python)

import hmac
import hashlib
import json

signature = hmac.new(
    webhook_secret.encode(),
    json.dumps(data).encode(),
    hashlib.sha256
).hexdigest()

if hmac.compare_digest(
    signature,
    request.headers.get("X-Signature", "")
):
    # Webhook is valid
    pass

Always verify the X-Signature before processing the webhook data.

Recommended Workflow

Generate an API key from your dashboard.
Call GET /user/id to obtain your user ID.
Create schedules using POST /add_schedule.
Retrieve schedules using GET /get_schedules.
Pause or resume schedules whenever necessary.
Monitor payouts using the orders endpoints.
Enable automation to process schedules automatically.

Need More?

YuciferPay automatically generates interactive documentation via FastAPI. For a complete list of endpoints, schemas and response models, visit:

Swagger Docs ReDoc