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",
  "currency": "USD",
  "customer": {
    "email": "john@example.com"
  },
  "amount": 0,
  "expiresIn": 10,
  "planId": "95eb086a-b11a-44b2-8422-a1955ca0fd9a",
  "countryCode": "CI",
  "localCurrency": "NGN",
  "callBackUrl": "https://yourapp.com/callback",
  "mobileMoney": {
    "code": "atl",
    "phoneNumber": "+2547100xxxx"
  },
  "metadata": {
    "productName": "Algo.ai"
  }
}
'
{
  "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"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.spotflow.one/llms.txt

Use this file to discover all available pages before exploring further.

​
Adding Test Funds

On test mode with your test keys, you can easily add fake funds to the jollof bank account number created for you using our Funds Simulator App. Note that this is for NGN and GHS only.See the full guide on Adding Fake Funds For Testing.

​
Mobile Money

When channel is set to mobile_money and a planId is included, Spotflow will automatically send a mandate approval request to the customer’s phone. The subscription will only activate once the mandate is approved.See the full guide on Mobile Money Subscriptions.

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,
XOF,
XAF
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

​
planId
string

Used when paying for a subscription plan.

Example:

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

​
countryCode
string

Note that, this is only needed to be passed or used for XOF and XAF currency payments. Country code of XOF countries like Cote D'voire with code CI, or XAF countries like Cameroon with code CM.

Example:

"CI"

​
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.