Skip to main content
POST
/
payments
/
initiate
Create Payment
curl --request POST \
  --url https://api.usepooler.com/payments/initiate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 123,
  "currency": "<string>",
  "recipient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "description": "<string>",
  "reference": "<string>",
  "transaction_type": "<string>",
  "transaction_category": "<string>",
  "transaction_tags": "<string>",
  "transaction_notes": "<string>",
  "channel": "<string>",
  "sub_type": "<string>"
}
'
{
  "success": true,
  "message": "<string>",
  "stan": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "reference": "<string>",
    "status": "pending",
    "amount": "<string>",
    "currency": "<string>",
    "description": "<string>",
    "type": "<string>",
    "sub_type": "<string>",
    "category": "<string>",
    "transaction_date": "2023-11-07T05:31:56Z",
    "tags": "<string>",
    "is_reversed": true,
    "is_completed": true,
    "channel": "<string>",
    "notes": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}
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