Initiate Payment

Creates a new transaction record and returns details required to proceed with payment via the chosen processor (e.g., an authorization URL for Paystack).

This endpoint likely requires API Key Authentication (using your Test or Live Secret Key) in a real implementation, although the current backend example doesn't enforce it yet.

POST /api/transactions/initiate

Request Body

{
  "merchantId": "uuid-merchant-456", // Required (How this is identified needs clarification - API key?)
  "amount": 500000, // Required, Integer (kobo/cents)
  "email": "customer@example.com", // Required
  "firstName": "John", // Optional
  "lastName": "Doe", // Optional
  "channel": "card", // Optional (card, bank_transfer, ussd)
  "reference": "your-order-ref-123", // Optional merchant reference prefix
  "callbackUrl": "https://yourdomain.com/payment/callback", // Optional URL for frontend redirect
  "paymentLinkId": "uuid-link-123", // Optional if initiated from a link
  "invoiceId": "uuid-invoice-789", // Optional if initiated from an invoice
  "metadata": { // Optional
    "custom_field": "custom_value",
    "cart_id": "xyz789"
  }
}

Field	Type	Required	Description
merchantId	String	Yes	The ID of the merchant initiating the payment. (Authentication TBD)
amount	Integer	Yes	Amount in the lowest currency unit (kobo/cents). Min 5000 (50 NGN).
email	String	Yes	Customer's email address.
firstName	String	No	Customer's first name.
lastName	String	No	Customer's last name.
channel	String	No	Payment channel (card, bank_transfer, ussd). Defaults may apply.
reference	String	No	Optional base reference from the merchant. SkyPay generates a unique full ref.
callbackUrl	String (URL)	No	URL to redirect the user to on your frontend after payment attempt.
paymentLinkId	String (UUID)	No	ID of the source PaymentLink if applicable.
invoiceId	String (UUID)	No	ID of the source Invoice if applicable.
metadata	Object	No	An object containing any additional data you want to associate.

Responses

Success 201 Created

Returns details needed for the next step in the payment flow.

{
  "message": "Payment initiated successfully",
  "reference": "SKP-1678886400000-a1b2c3d4", // SkyPay's unique transaction reference
  // Details below depend on the payment processor used:
  "authorizationUrl": "https://checkout.skypay.com/simulated_url", // Example for Paystack
  "accessCode": "simulated_code" // Example for Paystack
}

Error 400 Bad Request

Returned for invalid input data.

{
  "message": "Validation failed",
  "errors": [ /* ... details ... */ ]
}

Error 404 Not Found

Returned if the specified merchantId is invalid.

{
  "message": "Merchant not found"
}

Error 502 Bad Gateway

Returned if the downstream payment processor fails during initiation.

{
  "message": "Payment processor interaction failed: [Processor Error Message]"
}