Skip to main content
POST
Create Payment
Initiate a new payment transaction. This endpoint creates a payment quote that must be confirmed using the Confirm Payment endpoint.

Overview

This endpoint starts a payment transaction by creating a payment quote. The quote includes fees, exchange rates, and total amount to collect. After reviewing the quote, you must call the confirm endpoint to execute the payment.
Payments require a two-step process: first initiate to get a quote, then complete to execute the payment. Quotes expire after 5 minutes.

Payment Flow

  1. Initiate Payment - Call this endpoint with payment details to get a quote
  2. Review Quote - Check the fees, exchange rates, and total amount
  3. Confirm Payment - Use the quote_id and reference from the response to complete the payment
Use the Idempotency-Key header to prevent duplicate payments if you need to retry the request.

Authorizations

Authorization
string
header
required

Bearer token authentication. Include your API key in the Authorization header as: Bearer {your_api_key}

Body

application/json
amount
number
required

Payment amount

currency
string
required

Currency code (e.g., NGN, USD)

recipient_id
string<uuid>
required

ID of the payment recipient

description
string

Payment description

reference
string

Unique reference for the payment

transaction_type
string

Type of transaction (e.g., inter)

transaction_category
string

Transaction category (e.g., transfer)

transaction_tags
string

Comma-separated tags for the transaction

transaction_notes
string

Additional notes for the transaction

channel
string

Payment channel (e.g., bank)

sub_type
string

Transaction sub-type (e.g., transfer)

Response

200 - application/json

Payment initiated successfully

success
boolean
message
string
stan
string<uuid>
data
object