Skip to main content
POST
/
payments
/
initialize
cURL
curl --request POST \
  --url https://api.spotflow.co/api/v1/payments/initialize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "reference": "string",
  "amount": 0,
  "expiresIn": 10,
  "channel": "card",
  "planId": "95eb086a-b11a-44b2-8422-a1955ca0fd9a",
  "currency": "USD",
  "localCurrency": "NGN",
  "callBackUrl": "https://yourapp.com/callback",
  "mobileMoney": {
    "code": "atl",
    "phoneNumber": "+2547100xxxx"
  },
  "metadata": {
    "productName": "Algo.ai"
  },
  "customer": {
    "email": "john@example.com"
  }
}'
{
  "reference": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "checkoutUrl": "https://checkout.spotflow.co/paymentCode",
  "paymentCode": "PAY123456789",
  "status": "pending",
  "mode": "TEST",
  "expiryTime": "2025-11-03T10:16:26.948278058",
  "callBackUrl": "https://yourapp.com/callback",
  "metadata": {
    "productName": "Algo.ai"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
reference
string
required

Specify a unique reference ID generated by your company to identify each customer.

Example:

"string"

​
currency
enum<string>
required

Select the currency for the payment charge. Can either be in USD or in the local currency of your collection region. If you put in USD, you have to put in the local currency of the region in the local currency request field.

Available options:
USD,
NGN,
GHS,
KES,
ZAR,
TZS
Example:

"USD"

​
customer
object
required

The customer’s email address

​
amount
number

Amount should be in the subunit of our supported currency i.e your local currency or USD. This is not needed if you use a planId in your request.

Example:

0

​
expiresIn
number

The default maximum expiry time is 30 mins. However, you can set yours to the time you desire. The least time you can set is 5 mins.

Example:

10

​
channel
enum<string>

This is optional to add. Channel can be Card, Bank Transfer, Mobile Money or EFT depending on the region

Available options:
card,
bank_transfer,
mobile_money,
eft
Example:

"card"

​
planId
string

Used when paying for a subscription plan.

Example:

"95eb086a-b11a-44b2-8422-a1955ca0fd9a"

​
localCurrency
enum<string>

This is the local currency of your region. Used only when currency is set to USD. According to the local region, this can either be in NGN, GHS, ZAR, TZS, KSH etc.

Available options:
NGN,
GHS,
KES,
ZAR,
TZS
Example:

"NGN"

​
callBackUrl
string<url>

This is the URL you want your users to be redirected to after making payments. You can also set this permanently on your Spotflow dashboard.

Example:

"https://yourapp.com/callback"

​
mobileMoney
object

This is the phone number of the region you want to put in. E.g mobile_money number for Ghana, Kenya, Tanzania etc.

​
metadata
object

This is information pertaining to additional details about your product or service. Under metadata, you have productName” as a field — This is necessary for you to add as it indicates the name of your product and helps to specify to your user what your product is called. You can add any other additional field as you deem fit.

Response

A JSON array of intialize payment objects.

​
reference
string<uuid>
​
checkoutUrl
string<url>
Example:

"https://checkout.spotflow.co/paymentCode"

​
paymentCode
string
Example:

"PAY123456789"

​
status
string
Example:

"pending"

​
mode
string
Example:

"TEST"

​
expiryTime
string
Example:

"2025-11-03T10:16:26.948278058"

​
callBackUrl
string<url>
Example:

"https://yourapp.com/callback"

​
metadata
object

This is information pertaining to additional details about your product or service.