{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"7e1f7326-12aa-4efa-9983-031ba436cd67","name":"Finecore Partners BAAS Documentation","description":"# Finecore BAAS API Documentation\n\nWelcome to the official API documentation for Finecore Partners' Backend-as-a-Service (BAAS) platform. This collection includes endpoints for managing wallets and accounts, including both static and dynamic account generation.\n\nAvailable Services\n\n- Wallet Management\n    \n    - Create and retrieve wallet details\n        \n    - Check balances\n        \n    - View transaction history\n        \n- Account Management\n    \n    - Generate static accounts for users or organizations\n        \n    - Create dynamic virtual accounts for one-time or scoped use\n        \n    - Link accounts to wallets\n        \n\nFor questions or technical support, contact our team at [tech@finecore.co](https://mailto:tech@finecore.co).\n\nGetting Started\n\n1. Set up your environment variables (e.g. [https://api.finecore.co/v1](https://api.finecore.co/v1), {{API_KEY}})\n    \n2. Use your API key in the X-API-Key header:\n    \n    X-API-Key: {{API_KEY}}\n    \n3. Explore the endpoints organized by service in this collection\n    \n4. Review the example requests and responses for correct formatting\n    \n\nNotes\n\n- This is the v1 version of the Finecore BAAS API.\n    \n- All responses are returned in JSON format.\n    \n- Ensure your API key is kept secure and not exposed in public environments.\n    \n- Error responses will contain helpful messages and status codes.\n    \n\n## Web Hook Events\n\nThis document outlines the webhook event types and their associated data structures.\n\n#### Webhook Event Types\n\n- `customer_bank_transfer`: Represents a customer bank transfer event.\n    \n- `bank_transfer`: Represents a merchant bank transfer event.\n    \n- `customer_wallet_debited`: Represents an event where a customer's wallet is debited.\n    \n- `customer_wallet_credited`: Represents an event where a customer's wallet is credited.\n    \n- `wallet_to_wallet_transfer`: Represents a wallet-to-wallet transfer event.\n    \n- `batch_bank_transfer`: Represents a batch bank transfer event.\n    \n- `account_funded`: Represents an event where an account is funded.\n    \n\n## 🔔 Webhook Response\n\nWhen an event occurs, a webhook will be sent with the following JSON structure:\n\n``` json\n{\n\"event\": \"customer_bank_transfer\",\n\"data\":{\n  \"id\": \"5a8d6c3e-bbf4-4f4b-80b9-8f2877363eae\",\n  \"user_id\": \"2c8e91cd-7ae4-4b34-bc9f-39e72b2dd9c4\",\n  \"merchant_id\": \"77b2d420-531c-44e7-a0fd-3d7e87b264dc\",\n  \"reference\": \"TXN-239487293847\",\n  \"amount\": 1500.75,\n  \"currency\": \"NGN\",\n  \"status\": \"COMPLETED\",\n  \"balance_before\": 3500.00,\n  \"balance_after\": 2000.25,\n  \"environment\": \"SANDBOX\",\n  \"type\": \"DEBIT\",\n  \"category\": \"BANK_TRANSFER\",\n  \"source\": \"wallet\",\n  \"destination\": \"merchant_account\",\n  \"description\": \"Payment for Order #12345\",\n  \"metadata\": {\n    \"order_id\": \"12345\",\n    \"channel\": \"web\"\n  },\n  \"created_at\": \"2025-05-01T13:25:43Z\"\n}\n}\n\n ```\n\n---\n\n## 📝 Field Descriptions\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `id` | UUID | Unique identifier for the webhook event |\n| `user_id` | UUID | The user associated with the transaction |\n| `merchant_id` | UUID | The merchant involved in the transaction |\n| `reference` | String | Unique transaction reference |\n| `amount` | Float | Transaction amount |\n| `currency` | String | ISO currency code (e.g., NGN, USD) |\n| `status` | String | Status of the transaction (COMPLETED, FAILED, etc.) |\n| `balance_before` | Float | Balance before the transaction |\n| `balance_after` | Float | Balance after the transaction |\n| `environment` | String | Environment (LIVE, SANDBOX) |\n| `type` | String | Type of transaction (CREDIT, DEBIT) |\n| `category` | String | Category of transaction (e.g., BANK_TRANSFER, CREDIT_CUSTOMER_WALLET, etc) |\n| `source` | String | Origin of funds (e.g., WALLET, CARD) |\n| `destination` | String | Destination of funds |\n| `description` | String | Description of the transaction |\n| `metadata` | Object | Custom metadata (key-value pairs) |\n| `created_at` | Timestamp | ISO 8601 timestamp when the webhook event was triggered |\n\n---\n\n## Webhook Documentation\n\nThis webhook system allows Finecore to send event notifications to your server in real-time. The webhook delivers a JSON payload via an HTTP POST request to your specified webhook URL.\n\n---\n\nHow It Works:\n\n- The server sends a `POST` request to your webhook`Url` with a JSON payload.\n    \n- The payload is signed using an HMAC-SHA256 signature generated with your `secretKey`.\n    \n- The request includes headers to help you verify authenticity and ensure security.\n    \n\n---\n\nHeaders:\n\n- Content-Type: application/json\n    \n- X-Webhook-Signature: {HMAC_SHA256_SIGNATURE}\n    \n- X-Webhook-Timestamp: {ISO_8601_UTC_TIMESTAMP}\n    \n\nExample:\n\nX-Webhook-Signature: b1946ac92492d2347c6235b4d2611184  \nX-Webhook-Timestamp: 2025-05-08T12:34:56.789Z\n\n---\n\nPayload:\n\nThe payload is a JSON object that contains the data relevant to the event. The structure will vary based on the event type.\n\nExample payload:\n\n``` json\n{\n\"event\": \"customer_bank_transfer\",\n\"data\":{\n  \"id\": \"5a8d6c3e-bbf4-4f4b-80b9-8f2877363eae\",\n  \"user_id\": \"2c8e91cd-7ae4-4b34-bc9f-39e72b2dd9c4\",\n  \"merchant_id\": \"77b2d420-531c-44e7-a0fd-3d7e87b264dc\",\n  \"reference\": \"TXN-239487293847\",\n  \"amount\": 1500.75,\n  \"currency\": \"NGN\",\n  \"status\": \"COMPLETED\",\n  \"balance_before\": 3500.00,\n  \"balance_after\": 2000.25,\n  \"environment\": \"SANDBOX\",\n  \"type\": \"DEBIT\",\n  \"category\": \"BANK_TRANSFER\",\n  \"source\": \"wallet\",\n  \"destination\": \"merchant_account\",\n  \"description\": \"Payment for Order #12345\",\n  \"metadata\": {\n    \"order_id\": \"12345\",\n    \"channel\": \"web\"\n  },\n  \"created_at\": \"2025-05-01T13:25:43Z\"\n}\n}\n\n ```\n\n---\n\nVerifying the Webhook:\n\n1. Compute an HMAC-SHA256 hash of the **raw request body** using your `secretKey`.\n    \n2. Compare your computed hash with the value in the `X-Webhook-Signature` header.\n    \n3. Check that the `X-Webhook-Timestamp` is recent (recommended within 5 minutes) to prevent replay attacks.\n    \n\nExample verification steps:\n\n- Extract `X-Webhook-Signature` and `X-Webhook-Timestamp` from the headers.\n    \n- Compute:\n    \n    signature = HMAC_SHA256(secretKey, rawBody)\n    \n- Compare:\n    \n    If signature === X-Webhook-Signature → ✅ valid.\n    \n\n---\n\nWebhook Retry Policy\n\nTo ensure reliable delivery, Finecore’s webhook system implements an automatic retry mechanism when delivering webhook events to your endpoint.\n\nBehavior:\n\n- **Number of retries:** 3 attempts in total (1 initial + 2 retries).\n    \n- **Retry interval:** Exponential backoff starting at 100 milliseconds:\n    \n    - 1st attempt: immediately.\n        \n    - 2nd attempt: after 5 seconds.\n        \n    - 3rd attempt: after 10 seconds.\n        \n- **Timeout:** Each webhook request will timeout after 30 seconds if your server does not respond.\n    \n- **Retry triggers:** Retries occur if:\n    \n    - Your server is unreachable (network error).\n        \n    - Your server responds with a **non-2xx HTTP status code**.\n        \n    - Your server takes too long to respond (exceeds 30 seconds).\n        \n\nStopping Condition:\n\n- If your server responds with a **2xx HTTP status code**, the webhook is considered delivered and no further retries are attempted.\n    \n\n---\n\nBest Practices for Your Endpoint:\n\n- Always respond with a **2xx HTTP status code** to acknowledge successful receipt.\n    \n- Validate the `X-Webhook-Signature` header to ensure the request’s authenticity.\n    \n- Process webhook payloads **idempotently** to avoid duplicate side effects in case of retries.\n    \n\nExample Retry Flow:\n\n| Attempt | Wait before retry | Notes |\n| --- | --- | --- |\n| 1st | Immediate | Initial delivery attempt |\n| 2nd | 5s | First retry if needed |\n| 3rd | 10s | Second retry if needed |\n\n---\n\nImportant Notes:\n\n- Always acknowledge receipt with a `200 OK` HTTP status code.\n    \n- Make sure your endpoint is secure and can handle requests at scale.\n    \n- Your server should verify the signature and timestamp before processing the webhook payload.\n    \n\n---\n\nFor technical support or questions, contact [tech@finecore.co](https://mailto:tech@finecore.co).","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"38720320","team":6550833,"collectionId":"7e1f7326-12aa-4efa-9983-031ba436cd67","publishedId":"2sB2j4eW8P","public":true,"publicUrl":"https://documenter-api.postman.tech/view/38720320/2sB2j4eW8P","privateUrl":"https://go.postman.co/documentation/38720320-7e1f7326-12aa-4efa-9983-031ba436cd67","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.1","publishDate":"2025-07-25T22:18:46.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/13243c6b22b328bb51d6ad0d019e92a1eab2330b0442dfb2b00e1b7beb8358c7","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/2sB2j4eW8P"}