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

​
I. Integration Options: Choose Your Flow

​
II. Core API Management

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.

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

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