Skip to main content
POST
/
payments
cURL
curl --request POST \
  --url https://api.spotflow.co/api/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "reference": "string",
  "amount": 100,
  "currency": "USD",
  "planId": "95eb086a-b11a-44b2-8422-a1955ca0fd9a",
  "localCurrency": "NGN",
  "channel": "card",
  "encryptedCard": "8NqWW9RdFa+iNM6+Y4k92V0n3xxxxxxxxxxxx",
  "mobileMoney": {
    "code": "atl",
    "phoneNumber": "+2547100xxxx"
  },
  "callBackUrl": "https://yourapp.com/callback",
  "metadata": {
    "productName": "Algo.ai"
  },
  "customer": {
    "email": "john@example.com"
  }
}'
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reference": "REF123456789",
  "spotflowReference": "SPF-REF-001",
  "amount": 100,
  "currency": "USD",
  "localAmount": 156000,
  "totalFees": 500,
  "localCurrency": "NGN",
  "channel": "card",
  "status": "SUCCESS",
  "mode": "TEST",
  "customer": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "email": "john@example.com"
  },
  "providerMessage": "Transaction successful",
  "rate": 1560,
  "region": "Nigeria",
  "authorization": {
    "mode": "Pin"
  },
  "ussd": {
    "code": "*737#",
    "paymentCode": "123456"
  },
  "bankDetails": {
    "accountName": "John Doe",
    "accountNumber": "0123456789",
    "bankName": "Access Bank"
  },
  "card": {
    "type": "VISA",
    "firstSix": "412345",
    "lastFour": "6789"
  },
  "createdAt": "2025-10-17T15:21:11.287Z",
  "metadata": {
    "orderId": "ORD-000123",
    "note": "First payment"
  },
  "totalTaxAmount": 50,
  "totalLocalAmount": 156050,
  "planId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "mobileMoney": {
    "otp": "1234",
    "code": "MTN",
    "name": "MTN Mobile Money",
    "phoneNumber": "+233540000000"
  }
}

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

Example:

"USD"

​
channel
enum<string>
required

Channel can be Card, Bank Transfer, Mobile Money or EFT depending on the region

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

"card"

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

100

​
planId
string

Used when paying for a subscription plan.

Example:

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

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

Example:

"NGN"

​
encryptedCard
string

This contains the encrypted card data (token) and encryption key information gotten from your dashboard. This is based on the AES-256-GCM encryption algorithm. According to compliance rules, you can do this if you have PCI-DSS certification.

Example:

"8NqWW9RdFa+iNM6+Y4k92V0n3xxxxxxxxxxxx"

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

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

​
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 create payment objects.

​
id
string<uuid>
required
Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

​
reference
string
required
Example:

"REF123456789"

​
amount
number
required
Example:

100

​
currency
string
required
Example:

"USD"

​
status
string
required
Example:

"SUCCESS"

​
spotflowReference
string
Example:

"SPF-REF-001"

​
localAmount
number
Example:

156000

​
totalFees
number
Example:

500

​
localCurrency
string
Example:

"NGN"

​
channel
string
Example:

"card"

​
mode
string
Example:

"TEST"

​
customer
object
​
providerMessage
string
Example:

"Transaction successful"

​
rate
number
Example:

1560

​
region
string
Example:

"Nigeria"

​
authorization
object
​
ussd
object
​
bankDetails
object
​
card
object
​
createdAt
string<date-time>
Example:

"2025-10-17T15:21:11.287Z"

​
metadata
object
Example:
{
  "orderId": "ORD-000123",
  "note": "First payment"
}
​
totalTaxAmount
number
Example:

50

​
totalLocalAmount
number
Example:

156050

​
planId
string<uuid>
Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

​
mobileMoney
object