Skip to main content
We offer flexible solutions to match your integration preference:

​
I. Integration Options: Choose Your Flow

SolutionBest ForTechnical Flow
Spotflow RedirectFast, secure payments without extensive UI integration.Initiate via API from your server → Redirect customer to a secure Spotflow-hosted payment page.
Spotflow Embed (Client-Side)Seamless, intuitive in-app/on-site checkout experience.Embed our JavaScript library directly. We handle the entire UI/UX without redirecting users off your site.
Spotflow Classic (API)Businesses needing a highly custom payment experience and with PCI-DSS licenseYou build the entire UI; Spotflow processes the encrypted transaction from your server.

​
II. Core API Management

  • Create Payments: Use POST /payments/initialize or POST /payments for one-time and recurring payment collections.
  • List & Retrieve: Use GET /payments to list all, and GET /payments/(/api-reference/payments/fetch-collection) to retrieve details.
  • Payment Webhooks: React to events like payment.successful in your backend.
SECURITY NOTE: Your SECRET_KEY must never be exposed on the client-side. All API interactions must originate from and be managed by your secure backend server.

​
III. Spotflow Classic: Direct API Integration (Advanced)

The Spotflow Classic API grants total control but imposes strict security and compliance requirements such as having PCI-DSS License.

​
A. Prerequisites for Card Payments

To process card payments directly through the Payment API, you must meet these non-negotiable requirements:
  1. Account Status: Ensure your Spotflow account is fully activated and verified.
  2. Merchant Configuration: Request activation for your collection regions and service providers by contacting support@spotflow.one. (This is disabled by default for new accounts).
  3. PCI-DSS Compliance: You must be PCI-DSS certified. Spotflow may require a specific level (e.g., Level 1) due to handling raw card data. Consult with support for full details.
  4. API Keys: Obtain your SECRET_KEY and Encryption Key from the Dashboard.
  5. URLs: Configure your Webhook URL (for server-to-server status updates) and Callback URL (for customer redirects).

​
B. The Card Payment Flow

The Classic API flow is a two-step process designed for security and compliance:

​
Step 1: Encrypt and Create Payment

Before making the POST request to https://api.spotflow.co/api/v1/payments, you must:
  1. Collect Card Data: Gather the customer’s raw card details (PAN, CVV, expiry).
  2. Encrypt Data: Crucially, encrypt the raw card data using your unique Encryption Key and AES-256 encryption from your server. This ensures sensitive data is never transmitted in the clear.
  3. Send Request: Send the request with the required parameters, including the encrypted card data.
ParameterTypeDescription
referenceStringYour unique transaction ID.
amountIntegerCharge amount (in the smallest subunit).
currencyStringUSD or your local currency (NGN, GHS, etc.).
localCurrencyStringRequired when currency is USD. Sets the local FX reference.
encryptedCardStringThe AES-256 encrypted raw card string.

​
Step 2: Authorization (3D Secure, OTP, PIN, AVS)

Upon receiving the initial status: pending response, the card may require secondary authorization. The system indicates the required mode in the response’s authorization object:
ModeAction RequiredEndpoint Used
PINCollect the customer’s PIN.POST /authorize-payment with
OTPCollect the One-Time Password sent to the customer.POST /authorize-payment with
3DSRedirect the customer to the provided redirectUrl.No API call needed; customer handles auth.
AVSCollect the customer’s Address Verification details.POST /authorize-payment with
ENROLLCollect the phone number for card enrollment (e.g., for some Verve cards).POST /authorize-payment with

​
C. Bank Transfer Payments (Non-Card)

For Bank Transfers (“channel”: “bank_transfer”), the flow is simpler as no encryption is needed.
  • The initial POST /payments request returns a status: pending with the required bankDetails (Account Number, Bank Name) in the response.
  • The customer must then make the transfer to these details.
  • Final Status: Spotflow monitors the transfer. You must Verify the Payment to confirm the final successful status.

​
D. Final Step: Verify Payment

For every transaction—especially after an authorization step or a bank transfer—you must call the Verify Payment endpoint using your transaction reference to confirm the final and definitive status.
Important: This is the most critical step. You must always verify the status of the payment before you give value to the customer. Do not trust the redirect URL parameters or the response from the final authorization step alone!

​
How to Verify:

  1. Retrieve Reference: Get the unique transaction reference ID from your system or from the query parameters sent back to your Callback URL.
  2. Call Verify Endpoint: Send a request to our Verify Payment Collection Endpoint (GET /payments/).
  3. Confirm Status: The verification response provides the definitive, server-to-server confirmed status (successful, failed, etc.).

​
Receive Payment Confirmation Via Webhook

As a concurrent and reliable method, when a payment is successful, Spotflow sends a payment_successful webhook event to your specified Webhook URL.
Best Practice: Treat the webhook as an alert and the verification API call as the confirmation. Only fulfill the order after the verification API call confirms the status is successful.
Important Information: Payment Data Requirements: To avoid frustrating errors, ensure your request body adheres to these critical formatting and data rules:
  • Amount Format: The amount should always be in the subunit of the supported currency (e.g., kobo for NGN, cents for USD).
  • Unique Reference: You must use a unique reference ID generated by your company for the reference field to identify each customer and transaction.
  • Currency Selection:
  1. Select the currency for the payment collection (e.g., USD or NGN).
  2. If currency is set to USD, you must also include the localCurrency field set to the local currency of your collection region (e.g., NGN, GHS, KSH). This is required for accurate FX calculation and compliance.
To learn more about what you can do with payment collections on Spotflow, check out our API Reference. If you’ve got any questions, don’t hesitate to check our FAQs or reach out to our team at support@spotflow.one.