# Authentication Source: https://docs.spotflow.one/api-reference/authentication Secure authentication is crucial for protecting your account and ensuring authorized access. All API requests require authentication with your secret key, kindly include it in the `Authorization` header for secure access. ### API Key Management Spotflow provides two types of API keys for different use cases: public keys and secret keys. You can manage these keys from your Spotflow dashboard. * **Public Keys (pk\_test\_ for test mode, pk\_live\_ for live mode)**: Primarily used for client-facing integrations such as frontend applications, Spotflow Inline, and Mobile SDKs. These keys are designed to initiate payment collections but cannot modify account settings or access sensitive data. Public keys are safe to expose in client-side code. * **Secret Keys (sk\_test\_ for test mode, sk\_live\_ for live mode)**: Used exclusively for server-to-server communications and backend integrations. These keys grant full access to your account and must be kept confidential. Never share your secret keys in public locations like code repositories (GitHub), client-side code, or other unsecured environments. ### Authentication Process All server-side API requests to Spotflow must be authenticated using your secret key. Here's how to authenticate: * **Include your secret key** in the Authorization header of every request using the Bearer token format. * **HTTPS is mandatory**: All API requests must be made over HTTPS for secure communication. Requests made over plain HTTP will fail. * **Authentication Failure**: Calls made without proper authentication will result in a 401 Unauthorized status code response from the API. Secure your API requests by including an Authorization header in the following format:

`Authorization: Bearer SECRET_KEY`

```yaml theme={null} { "Authorization": "Bearer sk_test_6988f8d1539a48ab945764ec361fa3eb" } ``` To test functionalities specific to your account, you'll need to replace this sample key with your own. By following these guidelines, you can ensure secure and authorized access while integrating with Spotflow's APIs. # Create Virtual Account Source: https://docs.spotflow.one/api-reference/dynamic-accounts/create-dynamic-account openapi.json POST /virtual-accounts/temporary Virtual accounts don't act as independent money storage - they simply channel incoming payments straight to your account. These accounts cannot process outgoing payments or be linked to payment terminals. Since virtual accounts do not serve as containers for funds, there's no need for BVN verification during setup. ## 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). # Get Virtual Account by ID Source: https://docs.spotflow.one/api-reference/dynamic-accounts/dynamic-account-id openapi.json GET /virtual-accounts/{id} Get details of your created virtual account by its ID. # Get All Virtual Accounts Source: https://docs.spotflow.one/api-reference/dynamic-accounts/list-dynamic-account openapi.json GET /virtual-accounts This retrieves and lists all the active virtual accounts you created. # Error Codes Source: https://docs.spotflow.one/api-reference/error-codes Ran into an error? Don't worry—we've got you covered. This page lists all known error codes along with simple explanations and fixes to get you back on track. ### Spotflow API Response Codes Spotflow leverages standardized HTTP response codes to consistently communicate the outcome of your API requests. Understanding these codes is essential for interpreting the success or failure of your interactions with the Spotflow platform.

Success (2xx)

* **200 OK**: The request was processed successfully. **Don't assume everything went as planned!** Always examine the response data object to determine the specific outcome (e.g., successful or failed charge). Even a 200 response might indicate an error within the data object. * **201 Created**: A new resource was created successfully through your request. This typically occurs when creating new entities like users or payment collections within your Spotflow account.

Client Errors(4xx)

* **400 Bad Request**: The request failed due to invalid or missing required parameters. Double-check your request to ensure all required parameters are present and formatted correctly. * **401 Unauthorized**: Authentication failed. This could be caused by an invalid or missing secret key in the authorization header. Make sure you're using the correct secret key associated with your Spotflow account and that it's included in the authorization header of your request. * **403 Forbidden**: The API key you used doesn't have the required permissions to perform the specific action. Spotflow utilizes a permission-based system for API keys, where each key type grants access to a defined set of functionalities. Ensure you're using a key with the appropriate permissions for the action you're trying to execute. * **404 Not Found**: The requested resource does not exist on the Spotflow platform. This might occur if you're trying to access a user ID that doesn't exist or referencing an incorrect endpoint URL. * **429 Too Many Requests**: The API received an excessive number of requests from your application in a short period. This might indicate an issue with your integration logic or excessive retries. We recommend implementing exponential backoff for your requests to avoid overwhelming the API and encountering this error.

Server Error (5xx)

* **500, 502, 503, 504**: These codes indicate errors on Spotflow's servers. While uncommon, please report any instances of these errors you encounter to [support@spotflow.one](mailto:support@spotflow.one). We will work to resolve the issue on our end as soon as possible. ## Error Handling Beyond the HTTP status codes, Spotflow's API responses may also include specific error types and messages to provide more details about the encountered issue. This section provides guidance on handling various error conditions that you might encounter while interacting with Spotflow's API. Understanding these errors and their potential solutions is crucial for building robust integrations, as it can help you pinpoint the exact cause of the problem and implement appropriate solutions. ### General Error Handling: * **Uncertain Outcomes**: For certain error types (e.g., connection errors), the outcome of the API call might be unclear. In such cases, don't assume success or failure. * **Webhooks**: Spotflow utilizes webhooks to notify you about events and actions. Relying on webhooks can provide valuable information about the eventual outcome of an API call, even if the initial request encounters an error due to network issues or other transient problems. ### Specific Error Types Here's a breakdown of common Spotflow API error types and recommended solutions: | Error Type | Description | Solutions | | :--------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Invalid Request Errors, `(Spotflow:: InvalidRequestError)` | This error indicates a problem with the structure or content of your request. It could be due to invalid parameters, incorrect formatting, or attempting an action in an invalid state. The error response will typically include a specific error code and message to help you diagnose the issue. | Consult the Spotflow API documentation for detailed information on specific error codes and how to resolve them. | | Connection Errors `(Spotflow::APIConnectionError)` | Network issues between your server and Spotflow can sometimes cause connection errors. In such cases, the outcome of the API call is indeterminate. You cannot rely on the response to indicate success or failure. | | | API Errors `(Spotflow::APIError)` | These errors, while uncommon, indicate issues on Spotflow server. | | | Authentication Errors `(Spotflow::AuthenticationError)` | These errors occur when Spotflow cannot authenticate your request using the provided credentials. | | | Permission Errors `(Spotflow::PermissionError)` | These errors indicate that the API key used lacks the necessary permissions for the attempted action. | | | Rate Limit Errors `(Spotflow::RateLimitError)` | These errors occur when your application makes excessive API calls withtin a short period | |
By understanding these error types and implementing the recommended solutions, you can build more resilient and informative integrations with Spotflow API. # Introduction Source: https://docs.spotflow.one/api-reference/introduction Spotflow is your global Merchant of Record (MoR) that simplifies payment processing for businesses worldwide. We handle everything from global payment acceptance to compliance and settlement — empowering merchants to go global effortlessly. Learn how to easily integrate our APIs to streamline your in-app payments. Spotflow API helps global merchant collect payments in local currency. Learn how to easily integrate our APIs to streamline your in-app payments. Spotflow API is designed to be `RESTful`, utilizing familiar resource structures for most interactions. However, there might be a few exceptions from the strict REST principles for specific functionalities. These exceptions will be clearly documented within the API reference. This means you can expect: * **Predictable Resource-Oriented URLs**: URLs are designed to be clear and intuitive, reflecting the resources you're interacting with (e.g., /payments, /plans). * **Form-Encoded Request Bodies**: Data sent to the API uses a simple, well-understood format called form-encoded data. * **JSON-Encoded Responses**: Our API returns data in JSON response format, providing structured and easy-to-parse data. * **Standard HTTP Methods and Response Codes**: Our API utilizes standard HTTP verbs for different actions like GET for retrieving data, POST for creating new resources, PUT for updating existing ones and DEL for trashing existing ones. It also returns standard HTTP response codes to indicate success or failure (e.g., 200 for success, 400 for bad request). * **Content-Type**: When sending request to the API, you should ensure your request includes a Content-Type header set to application/JSON. This informs the API about the format of the data you are sending. ### API Keys and Authentication: To ensure secure communication with Spotflow APIs, you'll need to authenticate your requests using an API key. All endpoints access requires authentication with your API Keys. Your API key acts as a unique identifier for your application and allows us to differentiate between test and live mode usage. Specific instructions for including your API key within your requests will be provided in the documentation for each API endpoint. Your API Keys can be found on the API Keys and webhooks section of your dashboard. # Authorize Payment Source: https://docs.spotflow.one/api-reference/payments/authorize-collection post /payments/authorize This authorizes a payment by pre-approving the transaction before final validation. Authorization required could be PIN, OTP, 3DS, AVS, etc. # Create Payment Source: https://docs.spotflow.one/api-reference/payments/create-collection post /payments 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. ## 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). # Get Payment Source: https://docs.spotflow.one/api-reference/payments/fetch-collection get /payments/{payment-id} Get details of a specific payment by its ID # Initialize Payment Source: https://docs.spotflow.one/api-reference/payments/initialize-collection post /payments/initialize This is Spotflow's Redirect Checkout. Initiate a payment request to generate a unique payment reference, payment code and checkout URL for your customers ## 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). ## Mobile Money When `channel` is set to `mobile_money` and a `planId` is included, Spotflow will automatically send a mandate approval request to the customer's phone. The subscription will only activate once the mandate is approved. See the full guide on [Mobile Money Subscriptions](/features/mobile-money-subscriptions). # List Payments Source: https://docs.spotflow.one/api-reference/payments/list-collection get /payments Get details of all payments collection done via your keys. # Verify Payment Source: https://docs.spotflow.one/api-reference/payments/verify-collection get /payments/verify Confirm the status of a payment # Activate Plan Source: https://docs.spotflow.one/api-reference/subscription-plans/activate-plan openapi.json POST /plans/{plan-id}/activate Activate a subscription with the plan Id. # Cancel Plan Source: https://docs.spotflow.one/api-reference/subscription-plans/cancel-plan openapi.json POST /plans/{plan-id}/cancel Cancel a subscription with the plan Id. # Create Bulk Plans Source: https://docs.spotflow.one/api-reference/subscription-plans/create-bulk-plan openapi.json POST /bulk-plans Create multiple subscription plans under your integration. ### Required Fields in CSV File | Field | Type | Description | | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | `title` | string | Name/Title of plan | | `frequency` | string | This simply means how often. Valid frequencies are: daily, weekly, monthly, quarterly, biannually (every 6 months), annually. | | `amount` | interger | Amount should be in the subunit of our supported currency i.e your local currency or USD. | | `currency` | string | Currency code (e.g., NGN, USD). | | `internalReference` | string | A unique reference number generated by your company to identify each customer. | | `pricingOptions` | string | Specify one or more amount or currency for your payment plan. | # Create Single Plan Source: https://docs.spotflow.one/api-reference/subscription-plans/create-single-plan openapi.json POST /plans Create a subscription plan under your integration. ## Mobile Money When `channel` is set to `mobile_money` and a `planId` is included, Spotflow will automatically send a mandate approval request to the customer's phone. The subscription will only activate once the mandate is approved. See the full guide on [Mobile Money Subscriptions](/features/mobile-money-subscriptions). # Get All Plans Source: https://docs.spotflow.one/api-reference/subscription-plans/fetch-plan openapi.json GET /plans This retrieves and lists all subscription plans available on your integration. # Get Single Plan Source: https://docs.spotflow.one/api-reference/subscription-plans/list-single-plan openapi.json GET /plans/{plan-id} Retrieve details of a single subscription plan available on your integration. # Update Plan Source: https://docs.spotflow.one/api-reference/subscription-plans/update-plan openapi.json POST /plans/{plan-id} Update the details of an existing subscription plan # Get All Subscriptions Source: https://docs.spotflow.one/api-reference/subscriptions/list-subscriptions openapi.json GET /subscriptions Retrieve details of all subscriptions. # Activate Subscription Source: https://docs.spotflow.one/api-reference/subscriptions/subscription-activate openapi.json POST /subscriptions/{subscription-id}/activate Activate a subscription with the plan Id. # Subscriptions by plan Source: https://docs.spotflow.one/api-reference/subscriptions/subscription-by-plan openapi.json GET /plans/{plan-id}/subscriptions Retrieve details of all subscriptions associated with a customer's plan ID. # Cancel Subscription Source: https://docs.spotflow.one/api-reference/subscriptions/subscription-cancel openapi.json POST /subscriptions/{subscription-id}/cancel Cancel a subscription with the plan Id. # Get Subscriptions Details Source: https://docs.spotflow.one/api-reference/subscriptions/subscription-details openapi.json GET /subscriptions/{subscription-id} This is the unique ID of the subscription or customer you want to fetch. # Create a New Tax Setting Source: https://docs.spotflow.one/api-reference/tax-collections-configuration/create-tax openapi.json POST /tax-configurations Create a new tax rule to an approved country. You can set this up as a fixed flat fee or a percentage-based charge. # Get Tax Settings by Country/Region Source: https://docs.spotflow.one/api-reference/tax-collections-configuration/get-tax-region openapi.json GET /tax-configurations Returns a list of all custom tax rules and rates configured for a specific country. # Check Tax Activation Status Source: https://docs.spotflow.one/api-reference/tax-collections-configuration/get-tax-status openapi.json GET /merchant/tax-status According to your request made, checks if your merchant account has been authorized by Spotflow to collect regional checkout taxes. # Start or Stop Charging a Tax Source: https://docs.spotflow.one/api-reference/tax-collections-configuration/toggle-tax-status openapi.json PUT /tax-configurations/{id}/status Changes the status of a tax rule. Set to `active` to start charging your customers during checkout, or `inactive` to pause it. # Edit Tax Details Source: https://docs.spotflow.one/api-reference/tax-collections-configuration/update-tax openapi.json PUT /tax-configurations/{id} Updates the display name, amount, or maximum cap limit for an existing tax rule. # Get Bulk Disbursement By Its Categories Source: https://docs.spotflow.one/api-reference/transfer-api/bulk-transfer-categories openapi.json GET /transfers/bulk/categories Get details of an uploaded bulk disbursement by the categories you created with. # Get Bulk Disbursement By ID Source: https://docs.spotflow.one/api-reference/transfer-api/bulk-transfer-id openapi.json GET /transfers/bulk/{id} Get details of an uploaded bulk disbursement by its id. # Get All Bulk Disbursements Source: https://docs.spotflow.one/api-reference/transfer-api/bulk-transfers openapi.json GET /transfers/bulk Get details of all bulk disbursements files you have uploaded. # Get Bulk Disbursements By ID Source: https://docs.spotflow.one/api-reference/transfer-api/bulk-transfers-by-id openapi.json GET /transfers/bulk/{id}/transfers Fetch all transfer details present in a bulk disbursements file by its specific id to know the status of each transaction. # Create Bulk Disbursement Source: https://docs.spotflow.one/api-reference/transfer-api/create-bulk-transfer openapi.json POST /transfers/bulk You can use this endpoint to perform bulk bank account transfer to multiple bank accounts. # Create Single Bank Disbursement Source: https://docs.spotflow.one/api-reference/transfer-api/create-single-transfer openapi.json POST /transfers Use this endpoint to perform payouts for currencies - NGN, GHS mobile money and bank accounts transfer using the bank code from our Get All Banks endpoint # Get All Banks Source: https://docs.spotflow.one/api-reference/transfer-api/list-banks openapi.json GET /transfers/banks/{currency} Get details of all banks, their names and bank codes. Currently, this is for NGN and GHS only. For NGN currency, It also returns a metadata field where the NIBSS & NIP/CBNCode is seen for banks that have it. # Get Transfer By Reference Source: https://docs.spotflow.one/api-reference/transfer-api/transfer-by-reference openapi.json GET /transfers/reference/{reference} Get details of a particular transfer by its reference id. # Resolve Bank Account Source: https://docs.spotflow.one/api-reference/transfer-api/transfer-resolve-account openapi.json GET /transfers/resolve-account Get/Validate A Specific Account Number and Bank Code with its details i.e the account name # Validate Bulk Disbursements File Source: https://docs.spotflow.one/api-reference/transfer-api/validate-bulk-transfer openapi.json POST /transfers/bulk/validate Use this endpoint to confirm your bulk disbursements CSV file has all the necessary details needed and won't fail when uploaded for the bulk transfer transaction. ## Request Body Parameters Add a form-data with a key of “file” in the request body. In the value tab, upload a CSV file of your bulk transfer. Ensure all the required fields such as the amount, currency, bank\_code, branch\_code, account\_number, account\_name, and narration are present in your CSV file before uploading it. # Get Spotflow Accounts Balance Source: https://docs.spotflow.one/api-reference/wallets/account-balance openapi.json GET /balances/accounts/{accountNumber}/balance Get account balance details for a specific wallet before and after top-up in both NGN and GHS currency. # Get Spotflow Accounts Balance By Account Number Source: https://docs.spotflow.one/api-reference/wallets/account-balance-spotflow-wallet openapi.json GET /balances/accounts/{accountNumber}/sub-balances Retrieves account balance details for all direct wallets of the specified main account in both NGN and GHS. # Create Spotflow Accounts Source: https://docs.spotflow.one/api-reference/wallets/create-account openapi.json POST /accounts Wallets are created only through the API and serve a unique purpose to act as a pocket of money where funds can sit in. Importantly, wallets do not require BVNs upon creation. ## 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). # Get All Spotflow Accounts Source: https://docs.spotflow.one/api-reference/wallets/list-spotflow-wallets openapi.json GET /accounts This retrieves and lists all the wallets you've created. This is both for your main account wallet and sub account wallets. # Get Main Spotflow Account Balance Source: https://docs.spotflow.one/api-reference/wallets/main-account-balance openapi.json GET /balances Retrieves paginated balances for main accounts with optional currency, mode, and date filters. ## 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). # Get Spotflow Account By ID Source: https://docs.spotflow.one/api-reference/wallets/spotflow-wallet-id openapi.json GET /accounts/{id} Get details of your created wallet by its ID. You can get this in either NGN or GHS. # Introduction Source: https://docs.spotflow.one/changelog/introduction Welcome to the Spotflow Changelog. Or, as we call it, "The Big List of Things We Just Made Better." We're constantly shipping updates to make your payment processing less of a headache. We're obsessed with building a platform that just works for global merchants. Consider this page our public commitment to that goal—a running list of every improvement we send your way. This is where you'll find the proof—no marketing fluff, just the features and fixes that'll make your life as a global merchant easier. # Version Logs | Version | Date | Description | Link | | --------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | | `v1.52.5` | `29-10-25` | Security & Control. A major security upgrade (Public/Secret Keys), and new Checkout Expiry settings to give you more control over your sessions. | [Read More](/changelog/v1.52.5) | | `v1.52.4` | `15-10-2025` | Growth & Onboarding. A massively streamlined onboarding flow, Subscription Free Trials, Bank Transfers in Ghana to help you get paid faster and grow. | [Read More](/changelog/v1.52.4) | # v1.52.4 (15 Oct 2025) Source: https://docs.spotflow.one/changelog/v1.52.4 This release was focused on getting you started faster and giving you the tools to grow. ## New Features * The "Get Paid Faster" Onboarding: We've completely overhauled our onboarding and KYB (Know Your Business) dashboard. The new flow is streamlined, faster, and gets you from signup to "accepting payments" with way less friction. * Subscription Free Trials & Discounts: You can now offer Free Trial and Discount Periods for your subscription plans. This is a powerful new tool to drive customer adoption and grow your recurring revenue. * Bank Transfer now LIVE in Ghana on Checkout: We've officially added Bank Transfer as a new payment method for GHS transactions on checkout. This is a huge win for converting more customers in Ghana by offering the local payment methods they trust. ## Improvements & Updates * Filter Balance Ledger by Currency: Managing multiple currencies? Your life just got easier. The dashboard balance ledger can now be filtered by currency, making reconciliation a breeze. * General Enhancements: A host of minor API enhancements, stability improvements, and bug fixes across the platform. # v1.52.5 (29 Oct 2025) Source: https://docs.spotflow.one/changelog/v1.52.5 This release is all about security, control, and giving you more data to work with. ## New Features * Public Key Security Model: This is a big one. We've rolled out a major security enhancement by separating key functions. Public Keys are now used for all server-to-server communications, while your Secret Key remains for client-side communications. This separation of duties is a massive leap forward for platform security. ## Improvements & Updates * Checkout Expiry Control: You can now set an expiry time for checkout URLs. If a customer doesn't complete the purchase in time, a session\_expired ID is logged, giving you much better control over abandoned carts and time-sensitive offers. * Webhook Fix on Accounts/Wallets: You can now be 100% certain that you get a webhook from Spotflow when a credit and debit is done on your wallets and accounts created for your customers. * Payment Link UI tidy-up: We tidied up the Payment Link creation and management interface for both desktop and mobile. It's just cleaner, faster, and nicer to use. * The Usual Housekeeping: A healthy round of performance optimizations, security tweaks, and minor bug fixes to keep the entire platform running smoothly. # Community Contributions Source: https://docs.spotflow.one/contributions/overview Discover community-built SDKs and libraries for Spotflow. This is a curated list of open-source projects created by the community. These projects are not affiliated with or endorsed by Spotflow unless explicitly stated. * **What you'll find**: SDKs and libraries across languages * **How to use**: Evaluate licensing, maintenance status, and security for your use case * **How to contribute**: Submit your project via our template on the "Share Your Contributions" page Use at your own risk. Review code, licenses, and security posture before production use. Browse by type and language with links to code and docs. Add your project with a short PR using our template. # Projects Catalog Source: https://docs.spotflow.one/contributions/projects Community-maintained libraries and SDKs for Spotflow. Browse community projects by category. Each card links directly to the repository. Python SDK for interacting with Spotflow Payments API.
Handles the logic for initializing a transaction with minimal configuration (accepting amount, currency, email, etc.)

By @jackfros-glitch (Jackfros-glitch)

`Python` `Checkout` `PIP` Want your project listed? See Share Your Contributions. # Share Your Contributions Source: https://docs.spotflow.one/contributions/submit How to add your open-source project to Spotflow's contributions directory * The project is open-source with a permissive license. * It’s relevant to Spotflow (SDK, libraries, integration guides). * Has a README with install, usage, and maintenance status. Edit `contributions/projects.mdx` and add a new `` under the most relevant tab. ```mdx theme={null} One-sentence description of your project.
By @github_username

`LANGUAGE` `FRAMEWORK` `CATEGORY` ``` If you prefer, open an issue using the "Contributions Submission" template with: * Repo URL, description, category (SDK/Libraries/Plugin/Boilerplate) * Primary language/framework * Install/usage snippet link * Maintenance status and last update We review for correctness, relevance, clarity, and safety. Approved entries are merged and published after review. We may remove entries that are incorrect, unmaintained, insecure, misleading, or violate our policies. # Introduction Source: https://docs.spotflow.one/developer-resources/android-sdk The Spotflow Android SDK empowers developers to seamlessly integrate payment functionalities into their Android applications. It provides UI components and methods that allows you accept payment in your Android app. ## Project Requirements To integrate the Spotflow Android SDK into your project, ensure the following prerequisites are met: * Android Studio 4.1 or later * Android SDK API level 21 or higher while the minimum supported SDK version is 15 * Android Gradle Plugin 7.2 and above * Gradle 7.1.3 and above * AndroidX The Android SDK is currently a beta release. If you encounter any issues, kindly reach out to our support team at [support@spotflow.one](mailto:support@spotflow.one). ## Installation 1. Add the Spotflow SDK dependency to your app-level `build.gradle` file: ```yaml theme={null} dependencies { implementation 'com.spotflow:spotflow-android:latest_version' } ``` 2. Add the Internet permission to your AndroidManifest.xml file: ```kotlin theme={null} ``` 3. Sync your project with Gradle files to download the SDK into your project. Upon installation, you gain access to the UI components and methods to accept seamless payment experiences in your Android app. ### Parameters Required by the Library |

planId
`String`

|

The plan ID (optional).

| | :----------------------------------------------------- | :------------------------------------------------------------------- | |

currency
`String`

|

Currency for the payment (e.g., "NGN").

| |

amount
`String`

|

Amount to be paid (nullable).

| |

key
`String`

|

The API key for authenticating the transaction.

| |

encryptionKey
`String`

|

This key is used to encrypt the card for secure transactions.

| |

customerEmail
`String`

|

The email address of the customer.

| |

customerName
`String`

|

The name of the customer (optional).

| |

customerPhoneNumber
`String`

|

The phone number of the customer (optional).

| |

customerId
`String`

|

The unique identifier for the customer (optional).

| |

paymentDescription
`String`

|

Description of the payment (optional).

| |

appLogo
`String`

|

App logo widget (optional).

| |

appName
`String`

|

The name of the app (optional).

| |

debugMode
`bool`

|

Enable or disable debug mode.

| Avoid exposing your API keys in your application. Requests that require your API key should originate from a secure server environment. ## Usage with Jetpack Compose If you're using Jetpack Compose, call the `PaymentUI` composable function with the required parameters. ### Integration Example ```kotlin lines theme={null} PaymentUI( planID = "your_plan_id", currency = "NGN", amount = 100.0, key = "your_key", encryptionKey = "your_encryption_key", customerEmail = "customer@example.com", customerName = "John Doe", customerPhoneNumber = "1234567890", customerId = "customer_id", paymentDescription = "Payment for services", appLogo = R.drawable.your_logo, appName = "Your App", debugMode = true, onSuccess = { transactionId, paymentData -> // Handle successful payment }, onFailure = { errorCode, errorMessage -> // Handle payment failure } ) ``` ## Usage by Launching an Activity For apps not using Jetpack Compose, launch the payment activity directly. ### Integration Example ```kotlin lines theme={null} SpotFlowPaymentActivity.start( context = this, merchantId = "your_merchant_id", planID = "your_plan_id", currency = "NGN", amount = 100.0, key = "your_key", encryptionKey = "your_encryption_key", customerEmail = "customer@example.com", customerName = "John Doe", customerPhoneNumber = "1234567890", customerId = "customer_id", paymentDescription = "Payment for services", appLogo = R.drawable.your_logo, appName = "Your App", debugMode = true, requestCode = PAYMENT_REQUEST_CODE ) ``` # Angular Library Source: https://docs.spotflow.one/developer-resources/angular-library The `Spotflow Angular SDK` enables users to make payments seamlessly. It integrates smoothly into your Angular application, providing a streamlined checkout experience. ### Features * Collections: Card, Bank Transfers. * Recurring payments: Recurring Payments: Tokenization and Subscriptions. ## Requirements * Spoflow Encryption keys * Spotflow API keys * Node versions >= 16.x.x npm >=7.x.x ## Installation ```JavaScript theme={null} npm install @spot-flow/ng-spotflow-checkout ``` ```JavaScript theme={null} yarn add @spot-flow/ng-spotflow-checkout ``` ```JavaScript theme={null} pnpm add @spot-flow/ng-spotflow-checkout ``` ## Usage ### As a component **app.component.ts** ```JavaScript theme={null} import { Component } from '@angular/core'; import { RouterOutlet } from '@angular/router'; import { SpotflowAngularCheckoutModule } from '@spot-flow/ng-spotflow-checkout'; @Component({ selector: 'app-root', standalone: true, imports: [RouterOutlet, SpotflowAngularCheckoutModule], templateUrl: './app.component.html', styleUrl: './app.component.css', }) export class AppComponent { title = ''; options = { amount: 4000, // Not required for subscription payment currency: "NGN", email: "temi@mailinator.com", // Email of customer name: "John", // Name of customer: Not required phoneNumber: "09090909090", // Phone number of customer: Not required reference: "MC-123456", // Not required, a unique payment reference will be generated if not provided merchantKey: "pk_test_fXXXXedhXXXXXXXXXXXXXXXX", planId: "9e0808304-344d-XXXXXXXXX-XXXXX834034", // Not required for a one time payment encryptionKey:"SKKXXXXXXXXXXXXXXXXX" }; } ``` **app.component.html** ```JavaScript theme={null} Make Payment ``` ### Parameters Your API Secret Your transaction reference. This MUST be unique for every transaction Amount to charge the customer. NB: For subscription payments, amount comes from the plan details. This is not required for subscription payments. Currency to charge in. This is only required when a payment is being made in USD This is the encryption key for the merchant. This is required for card payments. This is the plan ID being paid for however, this is not required for one time payments. This is the Customer's Name This is the Customer's Phone Number This is the Customer's Email Address This contains other information about the product such as the product name and other additional properties. Product Name should not be passed if planId is being passed This is the URL the browser redirects to on success of a payment Need more information check out our [documentation](https://www.npmjs.com/package/@spot-flow/ng-spotflow-checkout) # Introduction Source: https://docs.spotflow.one/developer-resources/flutter-sdk Our Flutter SDK provides a rich set of pre-built UI components and APIs to seamlessly integrate payment functionalities within your Flutter application.

The `Spotflow Flutter SDK` pallows you to integrate smooth and secure payment flows into your Flutter apps. It supports both Android and iOS platforms, making it versatile for mobile app development. Android: Ensure INTERNET permission is declared in `AndroidManifest.xml` iOS: No special permissions required beyond basic networking ## Requirements Ensure your Flutter environment meets the following: * **context**: Flutter 3.7.0 or later * **context**: Dart 2.19 or later * **context**: Compatible with Android (minSdkVersion 21) and iOS (iOS 11+) * **context**: Internet permission for Android `AndroidManifest.xml` The Flutter SDK is currently a beta release. If you encounter any issues, kindly reach out to our support team at [support@spotflow.one](mailto:support@spotflow.one). ## Installation To use the `Spotflow Flutter SDK` package, add the following dependencies to your `pubspec.yaml` file: ```yaml theme={null} dependencies: spotflow_flutter: ^1.0.0 # or the latest version ``` Then run `flutter pub get` to fetch the package. ### Parameters Required by the SDK |

planId
`String`

|

The plan ID (optional).

| | :----------------------------------------------------- | :------------------------------------------------------------------- | |

currency
`String`

|

Currency for the payment (e.g., "NGN").

| |

amount
`String`

|

Amount to be paid (nullable).

| |

key
`String`

|

The API key for authenticating the transaction.

| |

encryptionKey
`String`

|

This key is used to encrypt the card for secure transactions.

| |

customerEmail
`String`

|

The email address of the customer.

| |

customerName
`String`

|

The name of the customer (optional).

| |

customerPhoneNumber
`String`

|

The phone number of the customer (optional).

| |

customerId
`String`

|

The unique identifier for the customer (optional).

| |

paymentDescription
`String`

|

Description of the payment (optional).

| |

appLogo
`String`

|

App logo widget (optional).

| |

appName
`String`

|

The name of the app (optional).

| |

debugMode
`bool`

|

Enable or disable debug mode.

| Always ensure that your key and encryptionKey are stored securely. Avoid hardcoding them in production apps. ## Usage Example Here is an example of how to make a payment using the `Spotflow` package: ```kotlin lines theme={null} import 'package:spotflow_flutter/spotflow_flutter.dart'; SpotflowFlutter.startPayment( context: context, customerId: "cust_001", customerEmail: "jane@example.com", customerName: "Jane Doe", customerPhoneNumber: "+123456789", currency: "USD", amount: 100.0, key: "your_public_key", encryptionKey: "your_encryption_key", paymentDescription: "Payment for services", planId: "plan_001", appName: "MyApp", appLogo: Image.asset('assets/logo.png'), // Or any Widget debugMode: true, ); ``` ### Testing Your implementation Test cards can be found [here](/expert-desk/testing-payments) ## Running the Example Project An example project has been provided on our [Github Repository](https://github.com/Spotflow-One/spotflow_flutter). Clone the repository and navigate to the example folder. Open it with a supported IDE or run `flutter run` from the terminal in that folder. # Introduction Source: https://docs.spotflow.one/developer-resources/iOS-sdk The Spotflow iOS SDK is a SwiftUI library that allows developers to integrate payment collection functionality into their iOS applications. It provides a simple interface to navigate to a payment screen, handle payment logic, and manage success or failure callbacks using the `SpotFlowPaymentUI` class. The iOS SDK is currently a beta release. If you encounter any issues, kindly reach out to our support team at [support@spotflow.one](mailto:support@spotflow.one). ## Project Requirements To integrate the Spotflow iOS SDK into your project, ensure the following prerequisites are met: * Xcode 13.0 or later * iOS 11.0 or higher * Swift 5.3 or later * Swift Package Manager (SPM) for dependency management ## Installation ### Using Swift Package Manager (SPM) To add `SpotFlow - iOS` SDK to your project using Xcode or by updating your `Package.swift` file: ```yaml theme={null} dependencies: [ .package(url: "https://github.com/Spotflow-One/SpotflowIOS.git", from: "1.0.0") ], targets: [ .target( name: "YourApp", dependencies: ["Spotflow"]), ] ``` After adding the dependency, import the Spotflow module where needed: ```kotlin wrap theme={null} import Spotflow ``` ### Parameters Required by the SDK |

planId
`String`

|

The plan ID (optional).

| | :----------------------------------------------------- | :------------------------------------------------------------------- | |

currency
`String`

|

Currency for the payment (e.g., "NGN").

| |

amount
`String`

|

Amount to be paid (nullable).

| |

key
`String`

|

The API key for authenticating the transaction.

| |

encryptionKey
`String`

|

This key is used to encrypt the card for secure transactions.

| |

customerEmail
`String`

|

The email address of the customer.

| |

customerName
`String`

|

The name of the customer (optional).

| |

customerPhoneNumber
`String`

|

The phone number of the customer (optional).

| |

customerId
`String`

|

The unique identifier for the customer (optional).

| |

paymentDescription
`String`

|

Description of the payment (optional).

| |

appLogo
`String`

|

App logo widget (optional).

| |

appName
`String`

|

The name of the app (optional).

| |

debugMode
`bool`

|

Enable or disable debug mode.

| Never expose your key or encryptionKey directly in the app for production. Use a secure server to perform sensitive operations. ### Navigating to the Payment Screen To navigate to the payment screen and initiate a payment process, create an instance of `SpotFlowPaymentManager` with the required parameters and pass it to `SpotFlowPaymentUI`. ### Example Usage ```kotlin lines theme={null} import SwiftUI; import Spotflow let config = SpotflowPaymentConfig( planId: "plan_001", currency: "USD", amount: 50.0, key: "your_public_key", encryptionKey: "your_encryption_key", customerEmail: "user@example.com", customerName: "Jane Smith", customerPhoneNumber: "+123456789", customerId: "user_123", paymentDescription: "Monthly Subscription", appLogo: UIImage(named: "AppLogo"), appName: "MyApp", debugMode: true ); Spotflow.shared.startPayment( from: self, config: config, onSuccess: { transactionId, paymentData in // Handle success }, onFailure: { errorCode, errorMessage in // Handle failure } ) ``` ## SpotFlowPaymentUI Parameters manager: An instance of `SpotFlowPaymentManager` containing payment and customer information. onPaymentSuccess: A closure that gets called when the payment is successful. onPaymentFailure: A closure that gets called when the payment fails, with an error as a parameter ## SpotFlowPaymentManager `SpotFlowPaymentManager` is a struct that holds all necessary information for a payment transaction. ### Properties/Parameters The merchant ID The plan ID The API key The Encryption key The customer's email The customer's name The customer's phone number The customer ID paymentDescription The logo of the app The name of the app ## Handling Error Messages This SDK provides comprehensive error handling mechanisms to assist in troubleshooting and providing informative feedback to users. Upon encountering an error, detailed error codes and descriptions are returned. By extracting error messages from the response, you can effectively communicate the issue to the user and take appropriate actions. Ensure you implement appropriate error handling mechanisms to provide informative feedback to the user. ## Testing Thoroughly test the integration with different payment scenarios including successful payments, failures, and edge cases to ensure a smooth user experience. Spotflow provides testing helpers that allows you to simulate different payment scenarios For your convenience, here are the testing helpers available: * **Card Testing:** Test cards can be found [here](https://app.spotflow.co/) * **Bank Transfer Testing:** Test bank transfer scenarios with the testing account details provided during your integration. These testing helpers help you ensure that your integration handles various payment scenarios effectively before deploying your application to a production environment. It's recommended to thoroughly test your integration with these testing details to provide a reliable payment experience to your users. # Introduction Source: https://docs.spotflow.one/developer-resources/inline-js InlineJS is Spotflow's JavaScript library designed to simplify the integration of payment functionalities into your web application. By embedding InlineJS into your checkout page, you can create a seamless payment experience without the need for redirects. It integrates smoothly into your application, providing a streamlined checkout experience. ## Browser Support Spotflow InlineJS is compatible with all recent versions of modern web browsers that support ECMAScript 5 or later. This includes: #### Supported Browsers * **Google Chrome**: Version 23 and above (all platforms) * **Safari**: Version 7 and above (macOS and iOS) * **Mozilla Firefox**: Version 21 and above (desktop) * **Microsoft Edge**: Version 79 and above (Chromium-based, desktop) * **Opera**: Version 15 and above (desktop) #### Mobile Browsers * **Chrome Mobile**: Android 5.0+ * **Safari Mobile**: iOS 10+ * **Samsung Internet**: Version 4.0+ ### Unsupported Browsers The following browsers and configurations are not supported: * **Internet Explorer (all versions, including IE 11)** * **Opera Mini in Super Saver/Extreme mode** * **Browsers with JavaScript disabled** * **Legacy browsers that do not support ECMAScript 5** ### Recommendations For the best experience, we recommend using the latest stable version of any supported browser with JavaScript enabled. ## Installation ```JavaScript theme={null} npm install @spot-flow/checkout-inline-js ``` ```JavaScript theme={null} yarn add @spot-flow/checkout-inline-js ``` ```JavaScript theme={null} ``` If you used `NPM` or `Yarn`, ensure you import the library as shown below: ```JavaScript theme={null} // Add for NPM, Yarn import { CheckoutForm } from "@spot-flow/checkout-inline-js"; ``` ## Usage ### One Time Payment ```JavaScript lines theme={null} import { CheckoutForm } from "@spot-flow/checkout-inline-js"; const checkout = new CheckoutForm({}); checkout.setup({ email: "temi@mailinator.com", encryptionKey: "gF1SPEMA3ido2Dg4ByXxxxxxxxxxxxxxxxxx", // The encryption key for the merchant merchantKey: "pk_test_8a586f9801254xxxxxxxxxxxx", // Your Merchant Public Key generated on Spotflow currency: "NGN", //can be in USD or in the local currency of your collection region e.g NGN, GHS localCurrency: "NGN", //optional and only needed if currency is in USD amount: 500 }); ``` ### Subscription Payment ```JavaScript lines theme={null} const checkout = new CheckoutForm({}); checkout.setup({ email: "temi@mailinator.com", encryptionKey: "gF1SPEMA3ido2Dg4ByXxxxxxxxxxxxxxxxxx", // The encryption key for the merchant merchantKey: "pk_test_8a586f9801254xxxxxxxxxxxx", // Your Merchant Public Key generated on Spotflow planId: "7447a235-9f53-4d44-xxxxxxxxxxxxxx", // Replace with your plan ID currency: "NGN", //can be in USD or in the local currency of your collection region e.g NGN, GHS localCurrency: "NGN", //optional and only needed if currency is in USD }); ``` ### One-Time Payment via CDN Alternatively, to integrate InlineJS into your web application, you can include it directly in your HTML via a CDN. Include the following script tag in the `` section of your HTML file: **HTML** ```HTML theme={null} ``` ```JavaScript lines theme={null} ``` ```JavaScript lines theme={null} ``` # Create Spotflow Payment Links In Under 5 Minutes (No Code Required) Source: https://docs.spotflow.one/developer-resources/integration-guide This guide will help you create a Spotflow Payment Link in under 5 minutes with no code required.