> ## 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.
# Create Payment
> If you have PCI-DSS certification, use this endpoint to collect payments using different payment methods. Note that for card payments, you'll use the authorize endpoint to input either the OTP or PIN.
This endpoint requires PCI-DSS certification because you handle raw card
data directly. If you are not PCI-DSS certified, use the
[Initialize Payment endpoint](/api-reference/payments/initialize-collection)
instead.
## Which Payment Endpoint Should I Use?
**Recommended for most integrations.**
No PCI-DSS certification required. Spotflow hosts the checkout
page. Customer is redirected to complete payment.
**Requires PCI-DSS certification.**
You collect card details directly and pass them encrypted to
our API. Only use this if you are PCI-DSS certified.
## 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](https://d2i9iv7q8xti2t.cloudfront.net/). Note that this is for NGN and GHS only.
See the full guide on [Adding Fake Funds For Testing](/expert-desk/simulating-funds).
To learn on payment states, go to [this page](/developer-resources/payment-states)
## OpenAPI
````yaml post /payments
openapi: 3.1.0
info:
title: Spotflow
description: ''
license:
name: MIT
version: 1.0.0
servers:
- description: Production server
url: https://api.spotflow.co/api/v1
security:
- bearerAuth: []
paths:
/payments:
post:
description: >-
If you have PCI-DSS certification, use this endpoint to collect payments
using different payment methods. Note that for card payments, you'll use
the authorize endpoint to input either the OTP or PIN.
operationId: CreatePayment
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
reference:
type: string
example: string
description: >-
Specify a unique reference ID generated by your company to
identify each customer.
amount:
type: number
example: 100
description: >-
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.
currency:
type: string
example: USD
description: >-
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.
countryCode:
type: string
example: CI
description: >-
***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.
if:
properties:
currency:
enum:
- XOF
- XAF
then:
required:
- countryCode
planId:
type: string
example: 95eb086a-b11a-44b2-8422-a1955ca0fd9a
description: >-
***Note that including this turns the payment into a
subscription.** Omitting it makes it a one-time charge as it
is used when paying for a subscription plan.
localCurrency:
type: string
example: NGN
description: >-
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.
if:
properties:
currency:
const: USD
then:
required:
- localCurrency
encryptedCard:
type: string
example: 8NqWW9RdFa+iNM6+Y4k92V0n3xxxxxxxxxxxx
description: >-
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.
mobileMoney:
type: object
properties:
provider:
type: string
example: mtn
phoneNumber:
type: string
example: +2547100xxxx
description: >-
This is the phone number of the region you want to put in.
E.g mobile_money number for Ghana, Kenya, Tanzania etc.
callBackUrl:
type: string
format: url
example: https://yourapp.com/callback
description: >-
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.
metadata:
type: object
properties:
productName:
type: string
example: Algo.ai
description: >-
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.
customer:
type: object
properties:
email:
type: string
format: email
example: john@example.com
required:
- email
description: The customer’s email address
required:
- reference
- currency
- channel
- customer
responses:
'200':
description: A JSON array of create payment objects.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
'400':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized - Invalid or missing authentication token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
components:
schemas:
PaymentResponse:
type: object
properties:
id:
type: string
format: uuid
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
reference:
type: string
example: REF123456789
spotflowReference:
type: string
example: SPF-REF-001
amount:
type: number
example: 100
currency:
type: string
example: USD
localAmount:
type: number
example: 156000
totalFees:
type: number
example: 500
localCurrency:
type: string
example: NGN
channel:
type: string
example: card
status:
type: string
example: SUCCESS
mode:
type: string
example: TEST
rate:
type: number
example: 1560
region:
type: string
example: Nigeria
authorization:
type: object
properties:
mode:
type: string
example: Pin
ussd:
type: object
properties:
code:
type: string
example: '*737#'
paymentCode:
type: string
example: '123456'
bankDetails:
type: object
properties:
accountName:
type: string
example: John Doe
accountNumber:
type: string
example: '0123456789'
bankName:
type: string
example: Access Bank
card:
type: object
properties:
type:
type: string
example: VISA
firstSix:
type: string
example: '412345'
lastFour:
type: string
example: '6789'
createdAt:
type: string
format: date-time
example: '2025-10-17T15:21:11.287Z'
metadata:
type: object
additionalProperties:
type: string
example:
orderId: ORD-000123
note: First payment
totalTaxAmount:
type: number
example: 50
totalLocalAmount:
type: number
example: 156050
planId:
type: string
format: uuid
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
mobileMoney:
type: object
properties:
otp:
type: string
example: '1234'
code:
type: string
example: MTN
name:
type: string
example: MTN Mobile Money
phoneNumber:
type: string
example: '+233540000000'
required:
- id
- reference
- amount
- currency
- status
Error400:
type: object
properties:
error:
type: string
example: Missing Parameter
message:
type: string
example: missing_parameter
status:
type: integer
format: float
example: 400
Error401:
type: object
properties:
error:
type: string
example: Unauthorized
message:
type: string
example: invalid_credentials
status:
type: integer
format: float
example: 401
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````