Skip to main content

Create Payment Collection​

Our API helps you collect payments using different payment methods. Payment methods are available for each regions. This endpoint requires that your encrypt the JSON data before making the request. Check out our documentation here for more details on card encryption.

POST https://api.spotflow.co/api/v1/payments

Headers

authorization
String

Bearer SECRET_KEY
Include your secret key in the request header as a Bearer token for authorization. Unauthorized requests will result in a 401 HTTP status code.

content-type
String		application/json

Body Parameters for Card Payments

reference
String

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

amount
Integer		Amount should be in the subunit of our supported currency i.e your local currency or USD.
currency
String		Select the currency for the payment charge. Can either be in USD or in the local currency of your collection region.
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 or KSH.
customer email
String		The customer’s email address
channel
String		The channel is Card
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.
metadata
String		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.

Sample Request Body for Card Payments in Foreign Currency (USD)

{
    "reference": "ref-{{$randomUUID}}",
    "amount": 10,
    "currency": "USD",
    "localCurrency": "NGN",
    "customer": {
        "email": "customer@email.com"
    },
    "channel": "card",
    "encryptedCard": "8/5XbSZFQfvaZmY55UizZGM0HYQdkEMyHoyGw1GZ+XlXdBC+hEcluYKC5WONz1Vxkvihxxxxxxxxxxxxxxxxxxxxx",
    "callBackUrl": "https://www.algoai.one", // optional if a callback url has been set on your dashboard
    "metadata": {
        "productName": "Algo.ai",
        "SubscriptionPlan": "MonthlyPass"
    }
}

Sample Response for Card Payments in Foreign Currency (USD)

200 OK 

{
    "id": "e0a0bc86-a2e6-46d8-91dc-1e50261b40d7",
    "reference": "ref-24676c48-31df-4968-8a04-54602c784ef5",
    "spotflowReference": "SPF-FLW-9d27bb78a7be40a8ae0fa86b54dab3c8",
    "amount": 10.00,
    "currency": "USD",
    "localAmount": 15334.90,
    "totalFees": 20.00,
    "localCurrency": "NGN",
    "channel": "card",
    "status": "pending",
    "customer": {
        "id": "95e4a0fa-9fb2-4dd4-9c81-cf6f4dad04a3",
        "email": "customer@email.com"
    },
    "providerMessage": "Please enter your PIN",
    "rate": 1533.49,
    "region": "Nigeria",
    "authorization": {
        "mode": "pin"
    },
    "card": {
        "type": "Mastercard",
        "firstSix": "555556",
        "lastFour": "1842"
    },
    "createdAt": "2025-02-18T16:48:53.922814Z",
     "callBackUrl": "https://www.algoai.one",
    "metadata": {
        "SubscriptionPlan": "MonthlyPass",
        "productName": "Algo.ai"
    }
}

Sample Request Body For Payments in Local Currency (e.g NGN)

{
    "reference": "ref-{{$randomUUID}}",
    "amount": 300,
    "currency": "NGN", //according to the local region, this can either be in NGN, GHS or KSH
    "customer": {
        "email": "customer@email.com"
    },
    "channel": "card",
    "encryptedCard": "8/5XbSZFQfvaZmY55UizZGM0HYQdkEMyHoyGw1GZ+XlXdBC+hEcluYKC5WONz1Vxkvihj/xxxxxxxxxxxx",
    "metadata": {
        "productName": "Algo.ai",
        "SubscriptionPlan": "MonthlyPass"
    }
     "callBackUrl": "https://www.algoai.one", // optional if a callback url has been set on your dashboard
}

Sample Response For Payments in Local Currency (e.g NGN)

200 OK 

{
    "id": "48b0e095-735d-4763-9b78-62e16adc446b",
    "reference": "ref-74a9b9c4-4d2d-46b8-aa4b-0bc1ca10317b",
    "spotflowReference": "SPF-FLW-63544769cad4438db4e5456b354a9ba8",
    "amount": 300.00,
    "currency": "NGN",
    "totalFees": 20.00,
    "channel": "card",
    "status": "successful",
    "customer": {
        "id": "95e4a0fa-9fb2-4dd4-9c81-cf6f4dad04a3",
        "email": "customer@email.com"
    },
    "providerMessage": "Approved successful",
    "rate": 1539.24,
    "region": "Nigeria",
    "card": {
        "type": "Visa",
        "firstSix": "411111",
        "lastFour": "2555"
    },
    "createdAt": "2025-02-18T22:02:46.779912Z",
    "callBackUrl": "https://www.algoai.one", 
    "metadata": {
        "SubscriptionPlan": "MonthlyPass",
        "productName": "Algo.ai"
    }
}

Body Parameters for Bank Transfer Payments​

reference
String

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

amount
Integer		Amount should be in the subunit of our supported currency i.e your local currency or USD.
currency
String		Select the currency for the payments charge. Can either be in USD or in the local currency of your collection region.
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 or KSH.
customer email
String		The customer’s email address
channel
String		The channel is bank transfer of the payment providers available on the system
metadata
String		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.

Sample Request Body for Bank Transfer Payments in Foreign Currency (USD)​

{
     "reference": "ref-{{$randomUUID}}",
     "amount":10,
     "currency": "USD",
     "localCurrency": "NGN", // according to the local region, this can either be in NGN, GHS or KSH
     "customer": {
         "name": "{{$randomFirstName}} {{$randomLastName}}",
        "email": "customer@email.com"
     },
    "channel": "bank_transfer",
    "metadata": {
        "productName": "Algo.ai",
        "SubscriptionPlan": "MonthlyPass"
    }
 }

Sample Response for Bank Transfer Payments in Foreign Currency (USD)​

200 OK 

{
    "id": "65022454-9d1e-4422-964d-63b4ca6e3b13",
    "reference": "ref-0d805f61-fc67-41ec-8852-a1de0552de5b",
    "spotflowReference": "SPF-FLW-2b17b0af4a594b1f9731b66aa6409765",
    "amount": 10.00,
    "currency": "USD",
    "localAmount": 15352.30,
    "totalFees": 20.00,
    "localCurrency": "NGN",
    "channel": "bank_transfer",
    "status": "pending",
    "customer": {
        "id": "814a4c79-dd54-4fc1-935d-c2d4f34376b4",
        "name": "Kenya Ziemann",
        "email": "customer@email.com"
    },
    "rate": 1535.23,
    "region": "Nigeria",
    "bankDetails": {
        "accountNumber": "0067100155",
        "bankName": "Mock Bank"
    },
    "createdAt": "2025-02-18T21:35:32.110809Z",
    "metadata": {
        "SubscriptionPlan": "MonthlyPass",
        "productName": "Algo.ai"
    }
}

USSD Payments​

GET https://api.spotflow.co/api/v1/banks?ussd=true

Sample Response to Get All Banks (NG available currently)

200 OK 

[
    {
        "code": "044",
        "name": "Access Bank"
    },
    {
        "code": "050",
        "name": "Ecobank"
    },
    {
        "code": "070",
        "name": "Fidelity Bank"
    },
    {
        "code": "011",
        "name": "First Bank of Nigeria"
    },
    {
        "code": "214",
        "name": "First City Monument Bank (FCMB)"
    },
    {
        "code": "058",
        "name": "Guaranty Trust Bank"
    },
    {
        "code": "030",
        "name": "Heritage Bank"
    },
    {
        "code": "082",
        "name": "Keystone Bank"
    },
    {
        "code": "303",
        "name": "Lotus Bank"
    },
    {
        "code": "105",
        "name": "Premium Trust Bank"
    },
    {
        "code": "221",
        "name": "Stanbic IBTC Bank"
    },
    {
        "code": "232",
        "name": "Sterling Bank"
    },
    {
        "code": "032",
        "name": "Union Bank"
    },
    {
        "code": "033",
        "name": "United Bank for Africa (UBA)"
    },
    {
        "code": "215",
        "name": "Unity Bank"
    },
    {
        "code": "090110",
        "name": "VFD Microfinance Bank"
    },
    {
        "code": "035",
        "name": "Wema Bank"
    },
    {
        "code": "057",
        "name": "Zenith Bank"
    }
]

Recurring Payment​

Set up recurring payments for a subscription plan using Spotflow. Check out our documentation for more details.

POST https://api.spotflow.co/api/v1/payments

Headers

authorization
String

Bearer SECRET_KEY
Include your secret key in the request header as a Bearer token for authorization. Unauthorized requests will result in a 401 HTTP status code.

content-type
String		application/json

Body Parameters for Recurring Payments via Card​

reference
String

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

planId
String		Add the plan ID gotten when the subscription plan was created. Go to the Subscription Plan Endpoint to know more.
amount
Integer		Amount should be in the subunit of our supported currency i.e your local currency or USD.
currency
String		Select the currency for the payments charge. Can either be in USD or in the local currency of your collection region.
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 or KSH.
customer email
String		The customer’s email address
channel
String		In this case, the channel is card using the available payment providers.
encryptedCard
String		This contains the encrypted card data (token) and encryption key information. This is based on the AES-256-GCM encryption algorithm.
metadata
String		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.

Sample Request Body for Recurring Payments in Foreign Currency (USD)​

{
    "reference": "ref-{{$randomUUID}}",
    "planId": "961ca3d6-0505-4bc5-8dd3-fc160ac4afc9",
    "currency": "USD",
    "localCurrency": "NGN", //not needed when currency is not set to USD, according to the local region, this can either be in NGN, GHS or KSH
    "customer": {
        "email": "customer@email.com"
    },
    "channel": "card",
    "encryptedCard": "8/5XbSZFQfvaZmY55UizZGM0HYQdkEMyHoyGw1GZ+XlXdBC+hEcluYKC5WONz1Vxkvihjxxxxxxxxxx",
    "metadata": {
        "productName": "Algo.ai",
        "SubscriptionPlan": "MonthlyPass"
    }
}

Sample Response for Recurring Payments in Foreign Currency (USD):​

200 OK 
{
    "id": "575bea7c-148e-4835-8575-d40a0a19fd4b",
    "reference": "ref-9e9f2817-82fc-47d0-993c-a9ead96c0149",
    "spotflowReference": "SPF-FLW-d039ef320381405d976a5b097cf5e71e",
    "amount": 10.00,
    "currency": "USD",
    "localAmount": 15367.90,
    "totalFees": 20.00,
    "localCurrency": "NGN",
    "channel": "card",
    "status": "successful",
    "customer": {
        "id": "95e4a0fa-9fb2-4dd4-9c81-cf6f4dad04a3",
        "email": "customer@email.com"
    },
    "providerMessage": "Approved successful",
    "rate": 1536.79,
    "region": "Nigeria",
    "card": {
        "type": "Visa",
        "firstSix": "411111",
        "lastFour": "2555"
    },
    "createdAt": "2025-02-19T09:04:40.227575Z",
    "metadata": {
        "SubscriptionPlan": "MonthlyPass",
        "productName": "Algo.ai"
    }
}

Ensure you authorize the payments with our Authorize Payment Endpoint if it’s an authorization card.